@golemui/gui-mcp 0.16.0 → 0.16.2

package/{index.js → get-concept-CHgtnDXr.js}

@@ -1,371 +1,5 @@
-#!/usr/bin/env node
-import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import Ajv2020 from "ajv/dist/2020.js";
 import addFormats from "ajv-formats";
-const SUPPORTED_STRING_FORMATS = /* @__PURE__ */ new Set([
-  "email",
-  "hostname",
-  "ipv4",
-  "ipv6",
-  "url",
-  "uuid",
-  "date",
-  "time",
-  "date-time",
-  "duration"
-]);
-function buildStringValidator(s, required2) {
-  const v = { type: "string" };
-  let used = false;
-  if (required2) {
-    v.required = true;
-    used = true;
-  }
-  if (typeof s.minLength === "number") {
-    v.minLength = s.minLength;
-    used = true;
-  }
-  if (typeof s.maxLength === "number") {
-    v.maxLength = s.maxLength;
-    used = true;
-  }
-  if (typeof s.pattern === "string") {
-    v.pattern = s.pattern;
-    used = true;
-  }
-  if (typeof s.format === "string" && SUPPORTED_STRING_FORMATS.has(s.format)) {
-    if (s.format !== "date" && s.format !== "date-time") {
-      v.format = s.format;
-      used = true;
-    }
-  }
-  if (s.const !== void 0) {
-    v.const = s.const;
-    used = true;
-  }
-  if (Array.isArray(s.enum)) {
-    v.enum = s.enum;
-    used = true;
-  }
-  return used ? v : void 0;
-}
-function buildNumberValidator(s, required2, t) {
-  const v = { type: t };
-  let used = false;
-  if (required2) {
-    v.required = true;
-    used = true;
-  }
-  if (typeof s.minimum === "number") {
-    v.minimum = s.minimum;
-    used = true;
-  }
-  if (typeof s.maximum === "number") {
-    v.maximum = s.maximum;
-    used = true;
-  }
-  if (typeof s.exclusiveMinimum === "number") {
-    v.exclusiveMinimum = s.exclusiveMinimum;
-    used = true;
-  }
-  if (typeof s.exclusiveMaximum === "number") {
-    v.exclusiveMaximum = s.exclusiveMaximum;
-    used = true;
-  }
-  if (typeof s.multipleOf === "number") {
-    v.multipleOf = s.multipleOf;
-    used = true;
-  }
-  return used ? v : void 0;
-}
-function buildBooleanValidator(s, required2) {
-  const v = { type: "boolean" };
-  let used = false;
-  if (required2) {
-    v.required = true;
-    used = true;
-  }
-  if (s.const !== void 0) {
-    v.const = s.const;
-    used = true;
-  }
-  return used ? v : void 0;
-}
-const SECRET_HINTS = /(password|secret|api[_-]?key|token)/i;
-const LONG_TEXT_MIN_LENGTH = 200;
-const SELECT_THRESHOLD = 6;
-function jsonSchemaToGui(schema, opts = {}) {
-  const unmapped = [];
-  const root = unwrap(schema);
-  const fields = [];
-  if (root.type === "object" || root.properties) {
-    const required2 = new Set(root.required ?? []);
-    for (const [name, propSchema] of Object.entries(root.properties ?? {})) {
-      const widget = mapProperty(name, unwrap(propSchema), required2.has(name), "", unmapped);
-      if (widget) fields.push(widget);
-    }
-  } else {
-    unmapped.push({
-      path: "",
-      reason: "Top-level JSON Schema is not an object — only object schemas map to forms."
-    });
-  }
-  if (opts.submitAction !== false) {
-    fields.push({
-      kind: "action",
-      type: "button",
-      actionType: "submit",
-      label: opts.submitLabel ?? "Submit",
-      props: { variant: "filled" }
-    });
-  }
-  const wrapped = opts.layout && opts.layout !== "vertical" ? [
-    {
-      kind: "layout",
-      type: opts.layout === "grid" ? "grid" : "flex",
-      props: opts.layout === "grid" ? { columnGap: 12, rowGap: 12 } : { direction: "row", gap: 12 },
-      children: fields
-    }
-  ] : fields;
-  return {
-    formDefinition: { $schema: "https://golemui.com/schemas/form.schema.json", form: wrapped },
-    unmapped
-  };
-}
-function unwrap(schema) {
-  if (schema.oneOf?.length === 2) {
-    const nonNull = schema.oneOf.find((s) => s.type !== "null");
-    if (nonNull) return { ...nonNull, ...stripBranches(schema) };
-  }
-  if (schema.anyOf?.length === 2) {
-    const nonNull = schema.anyOf.find((s) => s.type !== "null");
-    if (nonNull) return { ...nonNull, ...stripBranches(schema) };
-  }
-  return schema;
-}
-function stripBranches(s) {
-  const { oneOf: oneOf2, anyOf, ...rest } = s;
-  return rest;
-}
-function mapProperty(name, schema, required2, parentPath, unmapped) {
-  const path = parentPath ? `${parentPath}.${name}` : name;
-  const label = humanLabel(schema.title ?? name);
-  const t = Array.isArray(schema.type) ? schema.type.find((x) => x !== "null") : schema.type;
-  if (Array.isArray(schema.enum) && schema.enum.every((v) => typeof v === "string")) {
-    return buildEnumField(path, name, label, schema, required2);
-  }
-  switch (t) {
-    case "string":
-      return buildStringField(path, name, label, schema, required2);
-    case "number":
-    case "integer":
-      return buildNumberField(path, label, schema, required2, t);
-    case "boolean":
-      return buildBooleanField(path, label, schema, required2);
-    case "object":
-      return buildObjectGroup(path, name, label, schema, unmapped);
-    case "array":
-      return buildArrayField(path, name, label, schema, required2, unmapped);
-    default:
-      unmapped.push({
-        path,
-        reason: `Unsupported JSON Schema type \`${schema.type ?? "undefined"}\`.`
-      });
-      return null;
-  }
-}
-function buildStringField(path, name, label, schema, required2) {
-  const validator = buildStringValidator(schema, required2);
-  const isSecret = SECRET_HINTS.test(name);
-  const isLong = (schema.maxLength ?? 0) >= LONG_TEXT_MIN_LENGTH;
-  if (schema.format === "date") {
-    return cleanFields({ kind: "input", type: "dateInput", path, label, validator });
-  }
-  if (schema.format === "date-time") {
-    return cleanFields({ kind: "input", type: "datePicker", path, label, validator });
-  }
-  if (isSecret) {
-    return cleanFields({ kind: "input", type: "password", path, label, validator });
-  }
-  if (isLong) {
-    return cleanFields({
-      kind: "input",
-      type: "textarea",
-      path,
-      label,
-      validator,
-      props: schema.description ? { hint: schema.description } : void 0
-    });
-  }
-  return cleanFields({
-    kind: "input",
-    type: "textinput",
-    path,
-    label,
-    validator,
-    props: schema.description ? { hint: schema.description } : void 0
-  });
-}
-function buildEnumField(path, name, label, schema, required2) {
-  const values = schema.enum ?? [];
-  const validator = required2 ? { type: "string", required: true, enum: values } : { type: "string", enum: values };
-  if (values.length <= SELECT_THRESHOLD) {
-    return cleanFields({
-      kind: "input",
-      type: "select",
-      path,
-      label,
-      validator,
-      props: {
-        options: values.map((v) => ({ label: humanLabel(v), value: v }))
-      }
-    });
-  }
-  return cleanFields({
-    kind: "input",
-    type: "dropdown",
-    path,
-    label,
-    validator,
-    props: {
-      labelField: "label",
-      valueField: "value",
-      items: values.map((v) => ({ label: humanLabel(v), value: v }))
-    }
-  });
-}
-function buildNumberField(path, label, schema, required2, t) {
-  const validator = buildNumberValidator(schema, required2, t);
-  return cleanFields({
-    kind: "input",
-    type: "number",
-    path,
-    label,
-    validator,
-    props: schema.description ? { hint: schema.description } : void 0
-  });
-}
-function buildBooleanField(path, label, schema, required2) {
-  const validator = buildBooleanValidator(schema, required2);
-  return cleanFields({ kind: "input", type: "checkbox", path, label, validator });
-}
-function buildObjectGroup(path, _name, _label, schema, unmapped) {
-  const required2 = new Set(schema.required ?? []);
-  const children = [];
-  for (const [childName, childSchema] of Object.entries(schema.properties ?? {})) {
-    const w = mapProperty(childName, unwrap(childSchema), required2.has(childName), path, unmapped);
-    if (w) children.push(w);
-  }
-  if (!children.length) {
-    unmapped.push({ path, reason: "Object has no mappable properties." });
-    return null;
-  }
-  return {
-    kind: "layout",
-    type: "flex",
-    props: { direction: "column", gap: 8 },
-    children
-  };
-}
-function buildArrayField(path, _name, label, schema, required2, unmapped) {
-  const items = schema.items ? unwrap(schema.items) : void 0;
-  if (!items) {
-    unmapped.push({ path, reason: "Array without `items` schema cannot be mapped." });
-    return null;
-  }
-  if (items.type === "object") {
-    const templateChildren = [];
-    const required22 = new Set(items.required ?? []);
-    const childParent = `${path}.items`;
-    for (const [childName, childSchema] of Object.entries(items.properties ?? {})) {
-      const w = mapProperty(
-        childName,
-        unwrap(childSchema),
-        required22.has(childName),
-        childParent,
-        unmapped
-      );
-      if (w) templateChildren.push(w);
-    }
-    if (!templateChildren.length) {
-      unmapped.push({ path, reason: "Array of objects has no mappable item properties." });
-      return null;
-    }
-    return {
-      kind: "input",
-      type: "repeater",
-      path,
-      label,
-      props: {
-        addLabel: `Add ${singular(label).toLowerCase()}`,
-        removeLabel: "Remove",
-        template: {
-          kind: "layout",
-          type: "flex",
-          props: { direction: "column", gap: 8 },
-          children: templateChildren
-        }
-      }
-    };
-  }
-  if (items.type === "string" || items.type === "number" || items.type === "integer") {
-    const validator = buildArrayValidator(schema, required2);
-    return cleanFields({
-      kind: "input",
-      type: "tags",
-      path,
-      label,
-      validator,
-      props: schema.description ? { placeholder: "Add and press Enter", hint: schema.description } : { placeholder: "Add and press Enter" }
-    });
-  }
-  unmapped.push({
-    path,
-    reason: "Array shape is not mappable (only arrays of objects → repeater, or arrays of strings/numbers → tags)."
-  });
-  return null;
-}
-function buildArrayValidator(s, required2) {
-  const v = { type: "array" };
-  let used = false;
-  if (required2) {
-    v.required = true;
-    used = true;
-  }
-  if (typeof s.minItems === "number") {
-    v.minItems = s.minItems;
-    used = true;
-  }
-  if (typeof s.maxItems === "number") {
-    v.maxItems = s.maxItems;
-    used = true;
-  }
-  if (s.uniqueItems === true) {
-    v.uniqueItems = true;
-    used = true;
-  }
-  return used ? v : void 0;
-}
-function humanLabel(name) {
-  if (!name) return "";
-  return name.replace(/[_-]+/g, " ").replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/\s+/g, " ").trim().replace(/^./, (c) => c.toUpperCase());
-}
-function singular(label) {
-  if (label.endsWith("ies") && label.length > 3) return label.slice(0, -3) + "y";
-  if (label.endsWith("s") && !label.endsWith("ss")) return label.slice(0, -1);
-  return label;
-}
-function cleanFields(o) {
-  for (const k of Object.keys(o)) {
-    if (o[k] === void 0) delete o[k];
-  }
-  return o;
-}
 const $schema$u = "https://json-schema.org/draft/2020-12/schema";
 const $id$u = "https://golemui.com/schemas/common.schema.json";
 const title$u = "Golem Common Definitions";
@@ -1050,690 +684,1049 @@ function buildAjv() {
       ajv.addSchema(schema);
     }
   }
-  return ajv;
+  return ajv;
+}
+function getAjv() {
+  if (!cachedAjv) {
+    cachedAjv = buildAjv();
+  }
+  return cachedAjv;
+}
+function getFormValidator() {
+  if (!cachedFormValidator) {
+    cachedFormValidator = getAjv().compile(FORM_SCHEMA);
+  }
+  return cachedFormValidator;
+}
+const cache = /* @__PURE__ */ new Map();
+const validatorBranchCache = /* @__PURE__ */ new Map();
+const VALIDATOR_TYPE_TO_DEF = {
+  string: "stringValidator",
+  number: "numberValidator",
+  integer: "numberValidator",
+  boolean: "booleanValidator",
+  array: "arrayValidator",
+  custom: "customValidator"
+};
+function getValidatorBranches() {
+  return Object.keys(VALIDATOR_TYPE_TO_DEF);
+}
+function getValidatorBranchValidator(validatorType) {
+  const defKey = VALIDATOR_TYPE_TO_DEF[validatorType];
+  if (!defKey) return null;
+  if (validatorBranchCache.has(defKey)) return validatorBranchCache.get(defKey);
+  const defs = VALIDATORS_SCHEMA.$defs ?? {};
+  const branch = defs[defKey];
+  if (!branch) return null;
+  const cloned = {
+    ...JSON.parse(JSON.stringify(branch)),
+    $defs: JSON.parse(JSON.stringify(defs))
+  };
+  rewriteRefs(cloned, VALIDATORS_SCHEMA.$id);
+  const ajv = getAjv();
+  const v = ajv.compile(cloned);
+  validatorBranchCache.set(defKey, v);
+  return v;
+}
+function getShallowWidgetValidator(widgetType) {
+  if (cache.has(widgetType)) return cache.get(widgetType);
+  const schema = COMPONENT_SCHEMAS[widgetType];
+  if (!schema) return null;
+  const shallow = makeShallow(schema, schema.$id);
+  const ajv = getAjv();
+  const validator = ajv.compile(shallow);
+  cache.set(widgetType, validator);
+  return validator;
+}
+function makeShallow(schema, baseId) {
+  const cloned = JSON.parse(JSON.stringify(schema));
+  rewriteRefs(cloned, baseId);
+  delete cloned["$id"];
+  const props = cloned["properties"] ?? {};
+  if (props["children"]) {
+    props["children"] = { type: "array" };
+  }
+  if (props["validator"]) {
+    props["validator"] = { type: "object" };
+  }
+  const patternProps = cloned["patternProperties"];
+  if (patternProps) {
+    for (const key of Object.keys(patternProps)) {
+      if (key.startsWith("^validator\\.")) {
+        patternProps[key] = { type: "object" };
+      }
+    }
+  }
+  const propsField = props["props"];
+  if (propsField?.properties?.["template"]) {
+    propsField.properties["template"] = { type: "object" };
+  }
+  return cloned;
+}
+function rewriteRefs(node, baseId) {
+  if (node === null || typeof node !== "object") return;
+  if (Array.isArray(node)) {
+    for (const item of node) rewriteRefs(item, baseId);
+    return;
+  }
+  const obj = node;
+  if (typeof obj["$ref"] === "string") {
+    const ref = obj["$ref"];
+    if (!ref.startsWith("http") && !ref.startsWith("#")) {
+      try {
+        obj["$ref"] = new URL(ref, baseId).href;
+      } catch {
+      }
+    }
+  }
+  for (const v of Object.values(obj)) rewriteRefs(v, baseId);
+}
+const STRING_FORMATS = ["email", "hostname", "ipv4", "ipv6", "url", "uuid", "date", "time", "date-time", "duration"];
+const WIDGET_TYPES = Object.keys(COMPONENT_SCHEMAS);
+function levenshtein(a, b) {
+  if (a === b) return 0;
+  if (!a.length) return b.length;
+  if (!b.length) return a.length;
+  let prev = new Array(b.length + 1);
+  let curr = new Array(b.length + 1);
+  for (let j = 0; j <= b.length; j++) prev[j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      const del = (prev[j] ?? 0) + 1;
+      const ins = (curr[j - 1] ?? 0) + 1;
+      const sub = (prev[j - 1] ?? 0) + cost;
+      curr[j] = Math.min(del, ins, sub);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[b.length] ?? 0;
+}
+function nearest(target, candidates) {
+  let best;
+  let bestDist = Infinity;
+  for (const c of candidates) {
+    const d = levenshtein(target.toLowerCase(), c.toLowerCase());
+    if (d < bestDist) {
+      bestDist = d;
+      best = c;
+    }
+  }
+  return bestDist <= Math.max(2, Math.floor(target.length / 2)) ? best : void 0;
+}
+function suggestForAdditional(propertyName, instancePath) {
+  if (/\/validator(\/|$)/.test(instancePath)) {
+    const validatorKeys = ["type", "required", "minLength", "maxLength", "minimum", "maximum", "pattern", "format", "const", "enum", "messages", "minItems", "maxItems", "uniqueItems", "multipleOf", "exclusiveMinimum", "exclusiveMaximum"];
+    const guess = nearest(propertyName, validatorKeys);
+    if (guess && guess !== propertyName) return `Did you mean \`${guess}\`?`;
+    return void 0;
+  }
+  return void 0;
+}
+function suggestForEnum(value, allowed) {
+  if (typeof value !== "string") return void 0;
+  const stringAllowed = allowed.filter((v) => typeof v === "string");
+  if (!stringAllowed.length) return void 0;
+  const guess = nearest(value, stringAllowed);
+  if (guess) return `Did you mean \`${guess}\`? Allowed values: ${stringAllowed.map((v) => `\`${v}\``).join(", ")}.`;
+  return `Allowed values: ${stringAllowed.map((v) => `\`${v}\``).join(", ")}.`;
+}
+const VALIDATOR_TYPES = ["string", "number", "integer", "boolean", "array", "custom"];
+function suggestForConst(value, allowed, instancePath) {
+  if (typeof value !== "string" || typeof allowed !== "string") return void 0;
+  if (/^\/form\/\d+(?:\/children\/\d+)*(?:\/props\/template)?\/type$/.test(instancePath)) {
+    const guess = nearest(value, WIDGET_TYPES);
+    return guess ? `Did you mean \`type: '${guess}'\`?` : `Valid widget types: ${WIDGET_TYPES.map((v) => `\`${v}\``).join(", ")}.`;
+  }
+  if (instancePath.endsWith("/validator/type")) {
+    const guess = nearest(value, VALIDATOR_TYPES);
+    return guess ? `Did you mean \`type: '${guess}'\`?` : `Allowed validator types: ${VALIDATOR_TYPES.map((v) => `\`${v}\``).join(", ")}.`;
+  }
+  return void 0;
+}
+function describe(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  if (typeof value === "object") return "object";
+  return JSON.stringify(value);
+}
+function formatAjvErrors(errors, dataRoot) {
+  if (!errors?.length) return { errors: [], warnings: [] };
+  const collapsed = dataRoot !== void 0 ? collapseOneOfErrors(errors, dataRoot) : { errors, warnings: [] };
+  const filtered = collapsed.errors;
+  const out = [];
+  for (const err of filtered) {
+    const path = err.instancePath || "/";
+    let message = err.message ?? "invalid value";
+    let suggestion;
+    switch (err.keyword) {
+      case "additionalProperties":
+      case "unevaluatedProperties": {
+        const prop = err.params.additionalProperty;
+        if (prop) {
+          message = `Unknown property \`${prop}\` at \`${path}\``;
+          suggestion = suggestForAdditional(prop, path);
+        }
+        break;
+      }
+      case "required": {
+        const prop = err.params.missingProperty;
+        if (prop) {
+          message = `Missing required property \`${prop}\` at \`${path}\``;
+        }
+        break;
+      }
+      case "enum": {
+        const allowed = err.params.allowedValues ?? [];
+        const v = describe(err.data);
+        message = `Value ${v} at \`${path}\` is not one of the allowed values`;
+        suggestion = suggestForEnum(err.data, allowed);
+        break;
+      }
+      case "const": {
+        const allowed = err.params.allowedValue;
+        message = `Expected \`${describe(allowed)}\` at \`${path}\`, got \`${describe(err.data)}\``;
+        suggestion = suggestForConst(err.data, allowed, path);
+        break;
+      }
+      case "type": {
+        const expected = err.params.type;
+        message = `Expected type ${Array.isArray(expected) ? expected.join("|") : expected} at \`${path}\`, got ${describe(err.data)}`;
+        break;
+      }
+      case "oneOf":
+      case "anyOf": {
+        message = `Value at \`${path}\` does not match any allowed variant`;
+        break;
+      }
+      default:
+        message = `${err.message ?? "invalid value"} at \`${path}\``;
+    }
+    if (path.endsWith("/validator/format") && err.keyword === "enum") {
+      suggestion = `Allowed string formats: ${STRING_FORMATS.map((f) => `\`${f}\``).join(", ")}.`;
+    }
+    out.push({
+      path,
+      message,
+      suggestion,
+      keyword: err.keyword,
+      params: err.params
+    });
+  }
+  return { errors: dedupe(out), warnings: collapsed.warnings };
+}
+function extractWidgetPath(instancePath) {
+  const m = instancePath.match(/^(\/form\/\d+(?:\/children\/\d+)*)/);
+  return m ? m[1] : null;
+}
+function pickIntendedBranch(widget) {
+  if (!widget || typeof widget !== "object") return null;
+  const w = widget;
+  const widgetType = typeof w.type === "string" ? w.type : void 0;
+  const widgetKind = typeof w.kind === "string" ? w.kind : void 0;
+  if (widgetType && COMPONENT_SCHEMAS[widgetType]) {
+    return { $id: COMPONENT_SCHEMAS[widgetType].$id, type: widgetType };
+  }
+  if (!widgetType) return null;
+  const kindMatched = Object.entries(COMPONENT_SCHEMAS).filter(([, schema]) => {
+    const k = schema["properties"]?.["kind"]?.const;
+    return k === widgetKind;
+  });
+  const pool = kindMatched.length ? kindMatched : Object.entries(COMPONENT_SCHEMAS);
+  const candidateTypes = pool.map(([t]) => t);
+  const match = nearest(widgetType, candidateTypes);
+  if (!match) return null;
+  return { $id: COMPONENT_SCHEMAS[match].$id, type: match };
+}
+function collapseOneOfErrors(errors, dataRoot) {
+  const topLevel = [];
+  for (const err of errors) {
+    if (extractWidgetPath(err.instancePath) === null) topLevel.push(err);
+  }
+  const widgetErrors = [];
+  const warnings = [];
+  const form = dataRoot?.form;
+  if (Array.isArray(form)) {
+    form.forEach((widget, i) => {
+      collectWidgetErrors(widget, `/form/${i}`, widgetErrors, warnings);
+    });
+  }
+  return { errors: [...topLevel, ...widgetErrors], warnings };
+}
+function collectWidgetErrors(widget, widgetPath, out, warnings) {
+  const intended = pickIntendedBranch(widget);
+  if (!intended) {
+    const widgetType = widget?.type;
+    if (typeof widgetType !== "string" || !widgetType) {
+      out.push(
+        {
+          keyword: "required",
+          instancePath: widgetPath,
+          schemaPath: "",
+          params: { missingProperty: "type" },
+          message: `Widget at ${widgetPath} is missing or has an invalid \`type\``
+        }
+      );
+    } else {
+      warnings.push({
+        path: `${widgetPath}/type`,
+        keyword: "customWidget",
+        message: `Widget type \`${widgetType}\` at \`${widgetPath}\` is not a built-in GolemUI widget — assumed custom. Its props were not validated.`,
+        suggestion: "Built-in widget types: " + Object.keys(COMPONENT_SCHEMAS).join(", ") + ". If this is intentional (a custom widget registered via the framework loader), you can ignore this warning.",
+        params: { type: widgetType }
+      });
+    }
+    recurseIntoChildren(widget, widgetPath, out, warnings);
+    return;
+  }
+  const validator = getShallowWidgetValidator(intended.type);
+  if (validator) {
+    validator(widget);
+    for (const e of validator.errors ?? []) {
+      out.push({
+        ...e,
+        instancePath: widgetPath + e.instancePath
+      });
+    }
+  }
+  const w = widget;
+  if (w?.validator && typeof w.validator === "object") {
+    collectValidatorErrors(w.validator, `${widgetPath}/validator`, out);
+  }
+  if (widget && typeof widget === "object" && !Array.isArray(widget)) {
+    for (const [key, value] of Object.entries(widget)) {
+      if (key.startsWith("validator.") && value && typeof value === "object") {
+        collectValidatorErrors(value, `${widgetPath}/${key}`, out);
+      }
+    }
+  }
+  recurseIntoChildren(widget, widgetPath, out, warnings);
 }
-function getAjv() {
-  if (!cachedAjv) {
-    cachedAjv = buildAjv();
+function recurseIntoChildren(widget, widgetPath, out, warnings) {
+  const w = widget;
+  if (Array.isArray(w?.children)) {
+    w.children.forEach((child, i) => {
+      collectWidgetErrors(child, `${widgetPath}/children/${i}`, out, warnings);
+    });
+  }
+  if (w?.type === "repeater" && w.props?.template) {
+    collectWidgetErrors(w.props.template, `${widgetPath}/props/template`, out, warnings);
   }
-  return cachedAjv;
 }
-function getFormValidator() {
-  if (!cachedFormValidator) {
-    cachedFormValidator = getAjv().compile(FORM_SCHEMA);
+function collectValidatorErrors(validator, path, out) {
+  const v = validator;
+  const t = typeof v.type === "string" ? v.type : null;
+  const branches = getValidatorBranches();
+  const matchedType = t && branches.includes(t) ? t : t ? nearest(t, branches) : void 0;
+  if (!matchedType) {
+    out.push({
+      keyword: "enum",
+      instancePath: `${path}/type`,
+      schemaPath: "",
+      params: { allowedValues: branches },
+      message: `Validator type is not one of ${branches.join(", ")}`,
+      data: t
+    });
+    return;
+  }
+  const compiled = getValidatorBranchValidator(matchedType);
+  if (!compiled) return;
+  compiled(validator);
+  for (const e of compiled.errors ?? []) {
+    out.push({ ...e, instancePath: path + e.instancePath });
   }
-  return cachedFormValidator;
 }
-const cache = /* @__PURE__ */ new Map();
-const validatorBranchCache = /* @__PURE__ */ new Map();
-const VALIDATOR_TYPE_TO_DEF = {
-  string: "stringValidator",
-  number: "numberValidator",
-  integer: "numberValidator",
-  boolean: "booleanValidator",
-  array: "arrayValidator",
-  custom: "customValidator"
-};
-function getValidatorBranches() {
-  return Object.keys(VALIDATOR_TYPE_TO_DEF);
+function dedupe(errors) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const e of errors) {
+    const key = `${e.path}|${e.keyword}|${e.message}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push(e);
+  }
+  return result;
 }
-function getValidatorBranchValidator(validatorType) {
-  const defKey = VALIDATOR_TYPE_TO_DEF[validatorType];
-  if (!defKey) return null;
-  if (validatorBranchCache.has(defKey)) return validatorBranchCache.get(defKey);
-  const defs = VALIDATORS_SCHEMA.$defs ?? {};
-  const branch = defs[defKey];
-  if (!branch) return null;
-  const cloned = {
-    ...JSON.parse(JSON.stringify(branch)),
-    $defs: JSON.parse(JSON.stringify(defs))
-  };
-  rewriteRefs(cloned, VALIDATORS_SCHEMA.$id);
-  const ajv = getAjv();
-  const v = ajv.compile(cloned);
-  validatorBranchCache.set(defKey, v);
-  return v;
+function lintReactiveExpressions(formDefinition) {
+  const findings = [];
+  walk$1(formDefinition, "", findings);
+  return findings;
 }
-function getShallowWidgetValidator(widgetType) {
-  if (cache.has(widgetType)) return cache.get(widgetType);
-  const schema = COMPONENT_SCHEMAS[widgetType];
-  if (!schema) return null;
-  const shallow = makeShallow(schema, schema.$id);
-  const ajv = getAjv();
-  const validator = ajv.compile(shallow);
-  cache.set(widgetType, validator);
-  return validator;
+function walk$1(node, path, out) {
+  if (node === null || typeof node !== "object") return;
+  if (Array.isArray(node)) {
+    node.forEach((item, i) => walk$1(item, `${path}/${i}`, out));
+    return;
+  }
+  const obj = node;
+  for (const key of ["include", "exclude"]) {
+    const child = obj[key];
+    if (child && typeof child === "object" && "when" in child) {
+      const expr = child.when;
+      if (typeof expr === "string") {
+        checkExpression(expr, `${path}/${key}/when`, out);
+      }
+    }
+  }
+  if (path === "" && obj["states"] && typeof obj["states"] === "object") {
+    for (const [name, expr] of Object.entries(obj["states"])) {
+      if (typeof expr === "string") {
+        checkExpression(expr, `/states/${name}`, out);
+      }
+    }
+  }
+  for (const [k, v] of Object.entries(obj)) {
+    if (v && typeof v === "object" && !Array.isArray(v) && "when" in v) {
+      const expr = v.when;
+      if (typeof expr === "string" && k !== "include" && k !== "exclude") {
+        checkExpression(expr, `${path}/${k}/when`, out);
+      }
+    }
+    if (typeof v === "object" && v !== null) {
+      walk$1(v, `${path}/${k}`, out);
+    }
+  }
 }
-function makeShallow(schema, baseId) {
-  const cloned = JSON.parse(JSON.stringify(schema));
-  rewriteRefs(cloned, baseId);
-  delete cloned["$id"];
-  const props = cloned["properties"] ?? {};
-  if (props["children"]) {
-    props["children"] = { type: "array" };
+function checkExpression(expr, path, out) {
+  const trimmed = expr.trim();
+  if (!trimmed) {
+    out.push({ path, expression: expr, message: "Expression is empty." });
+    return;
   }
-  if (props["validator"]) {
-    props["validator"] = { type: "object" };
+  const stack = [];
+  const pairs = { ")": "(", "]": "[", "}": "{" };
+  for (const ch of trimmed) {
+    if ("([{".includes(ch)) stack.push(ch);
+    else if (")]}".includes(ch)) {
+      if (stack.pop() !== pairs[ch]) {
+        out.push({
+          path,
+          expression: expr,
+          message: `Unbalanced \`${ch}\` in reactive expression.`
+        });
+        return;
+      }
+    }
   }
-  const patternProps = cloned["patternProperties"];
-  if (patternProps) {
-    for (const key of Object.keys(patternProps)) {
-      if (key.startsWith("^validator\\.")) {
-        patternProps[key] = { type: "object" };
+  if (stack.length) {
+    out.push({
+      path,
+      expression: expr,
+      message: `Unclosed \`${stack[stack.length - 1]}\` in reactive expression.`
+    });
+    return;
+  }
+  if (!/\$form\b|\$meta\b|\$formIsInvalid\b/.test(trimmed)) {
+    out.push({
+      path,
+      expression: expr,
+      message: "Expression does not reference `$form`, `$meta`, or `$formIsInvalid`.",
+      suggestion: "GolemUI expressions read form data via `$form.fieldName`, form metadata via `$meta.key`, or the built-in `$formIsInvalid` boolean. Did you forget the prefix?"
+    });
+  }
+  if (/(?<![=!<>])=(?![=>])/.test(trimmed)) {
+    out.push({
+      path,
+      expression: expr,
+      message: "Expression contains a single `=` (assignment). Reactive expressions are read-only.",
+      suggestion: "Use `===` for equality comparison."
+    });
+  }
+  if (/(?<![&])&(?![&])/.test(trimmed) || /(?<![|])\|(?![|])/.test(trimmed)) {
+    out.push({
+      path,
+      expression: expr,
+      message: "Expression contains a single `&` or `|` (bitwise).",
+      suggestion: "Use `&&` for logical AND, `||` for logical OR."
+    });
+  }
+  if (/(?<![=!])==(?!=)/.test(trimmed) || /(?<![!])!=(?!=)/.test(trimmed)) {
+    out.push({
+      path,
+      expression: expr,
+      message: "Expression uses loose equality (`==` or `!=`).",
+      suggestion: "Use strict equality `===` / `!==` to avoid type coercion (e.g. `$form.x !== undefined` rather than `$form.x != null`)."
+    });
+  }
+  if (/(?<![=!])!\s*\$(?:form|meta)\b/.test(trimmed)) {
+    out.push({
+      path,
+      expression: expr,
+      message: "Expression negates a `$form`/`$meta` reference (relies on truthy/falsy coercion).",
+      suggestion: 'Form data values can be `undefined`. Pick the case you actually mean and write it explicitly — `$form.x === undefined`, `$form.x === null`, `$form.x === 0`, `$form.x === ""` — instead of `!$form.x`.'
+    });
+  }
+  const refChainRe = /\$(?:form|meta)\b((?:\.[\w?]+)*)/g;
+  let chainFlagged = false;
+  let chainMatch;
+  while ((chainMatch = refChainRe.exec(trimmed)) !== null) {
+    const chain = chainMatch[1];
+    if (!chain) continue;
+    const segments = chain.split(".").filter(Boolean);
+    let unsafe = false;
+    for (let i = 0; i < segments.length - 1; i++) {
+      const segment = segments[i];
+      if (!segment || !segment.endsWith("?")) {
+        unsafe = true;
+        break;
       }
     }
+    if (unsafe && !chainFlagged) {
+      out.push({
+        path,
+        expression: expr,
+        message: "Expression chains nested property access without optional chaining (e.g. `$form.user.name`).",
+        suggestion: "Treat every nested property as possibly `undefined`. Use `?.` between segments: `$form.user?.name` instead of `$form.user.name`. The runtime throws if `$form.user` is undefined."
+      });
+      chainFlagged = true;
+    }
   }
-  const propsField = props["props"];
-  if (propsField?.properties?.["template"]) {
-    propsField.properties["template"] = { type: "object" };
+  const refOnly = /^\$(?:form|meta)(?:\.[\w?]+)*$/;
+  const refBeforeBool = /\$(?:form|meta)(?:\.[\w?]+)*\s*(?:&&|\|\||\?(?![.?]))/;
+  const refAfterBool = /(?:&&|\|\|)\s*\$(?:form|meta)(?:\.[\w?]+)*\s*$/;
+  if (refOnly.test(trimmed) || refBeforeBool.test(trimmed) || refAfterBool.test(trimmed)) {
+    out.push({
+      path,
+      expression: expr,
+      message: "Expression uses `$form`/`$meta` directly as a boolean (relies on truthy/falsy coercion).",
+      suggestion: 'Form data values can be `undefined`. Compare explicitly: `$form.x !== undefined`, `$form.x === "value"`, `$form.items?.length > 0`. For default values use nullish coalescing: `$form.x ?? defaultValue`.'
+    });
+  }
+  const refForCmpRe = /\$(?:form|meta)(?:\.[\w?]+)+/g;
+  let r5Flagged = false;
+  let cmpMatch;
+  while ((cmpMatch = refForCmpRe.exec(trimmed)) !== null) {
+    const start = cmpMatch.index;
+    const end = start + cmpMatch[0].length;
+    const before = trimmed.slice(0, start).trimEnd();
+    const after = trimmed.slice(end).trimStart();
+    const opAfter = /^(?:<=?|>=?|[+\-*/%])(?!=)/.test(after);
+    const opBefore = /(?<![=!])[<>+\-*/%]$/.test(before);
+    if (!(opAfter || opBefore)) continue;
+    if (/&&|\|\|/.test(before)) continue;
+    if (!r5Flagged) {
+      out.push({
+        path,
+        expression: expr,
+        message: "Expression applies a comparison or arithmetic operator to a `$form`/`$meta` reference whose leaf may be `undefined`.",
+        suggestion: "Guard the value first: `$form.x !== undefined && $form.x > 180`. Or default it: `($form.x ?? 0) > 180`. Strict equality (`$form.x === 180`) is also safe since it evaluates to `false` when undefined."
+      });
+      r5Flagged = true;
+    }
   }
-  return cloned;
 }
-function rewriteRefs(node, baseId) {
-  if (node === null || typeof node !== "object") return;
+function lintStringInterpolations(formDefinition) {
+  const findings = [];
+  walk(formDefinition, "", findings);
+  return findings;
+}
+const SLOT_REGEX = /\{\{([^}]*(?:\}[^}]+)*)\}\}/g;
+function walk(node, path, out) {
+  if (node === null || typeof node !== "object") {
+    return;
+  }
   if (Array.isArray(node)) {
-    for (const item of node) rewriteRefs(item, baseId);
+    node.forEach((item, i) => walk(item, `${path}/${i}`, out));
     return;
   }
   const obj = node;
-  if (typeof obj["$ref"] === "string") {
-    const ref = obj["$ref"];
-    if (!ref.startsWith("http") && !ref.startsWith("#")) {
-      try {
-        obj["$ref"] = new URL(ref, baseId).href;
-      } catch {
+  const isTranslationConfig = typeof obj["key"] === "string" && obj["params"] !== null && typeof obj["params"] === "object" && !Array.isArray(obj["params"]);
+  if (isTranslationConfig) {
+    const params = obj["params"];
+    for (const [paramKey, paramValue] of Object.entries(params)) {
+      if (typeof paramValue === "string") {
+        checkParamExpression(paramValue, `${path}/params/${paramKey}`, out);
       }
     }
   }
-  for (const v of Object.values(obj)) rewriteRefs(v, baseId);
-}
-const STRING_FORMATS = ["email", "hostname", "ipv4", "ipv6", "url", "uuid", "date", "time", "date-time", "duration"];
-const WIDGET_TYPES = Object.keys(COMPONENT_SCHEMAS);
-function levenshtein(a, b) {
-  if (a === b) return 0;
-  if (!a.length) return b.length;
-  if (!b.length) return a.length;
-  let prev = new Array(b.length + 1);
-  let curr = new Array(b.length + 1);
-  for (let j = 0; j <= b.length; j++) prev[j] = j;
-  for (let i = 1; i <= a.length; i++) {
-    curr[0] = i;
-    for (let j = 1; j <= b.length; j++) {
-      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-      const del = (prev[j] ?? 0) + 1;
-      const ins = (curr[j - 1] ?? 0) + 1;
-      const sub = (prev[j - 1] ?? 0) + cost;
-      curr[j] = Math.min(del, ins, sub);
+  for (const [key, value] of Object.entries(obj)) {
+    if (key === "params" && isTranslationConfig) {
+      continue;
     }
-    [prev, curr] = [curr, prev];
-  }
-  return prev[b.length] ?? 0;
-}
-function nearest(target, candidates) {
-  let best;
-  let bestDist = Infinity;
-  for (const c of candidates) {
-    const d = levenshtein(target.toLowerCase(), c.toLowerCase());
-    if (d < bestDist) {
-      bestDist = d;
-      best = c;
+    if (key === "defaultValue" || key.startsWith("defaultValue.")) {
+      continue;
+    }
+    const childPath = `${path}/${key}`;
+    if (typeof value === "string") {
+      checkTemplate(value, childPath, out);
+    } else {
+      walk(value, childPath, out);
     }
   }
-  return bestDist <= Math.max(2, Math.floor(target.length / 2)) ? best : void 0;
 }
-function suggestForAdditional(propertyName, instancePath) {
-  if (/\/validator(\/|$)/.test(instancePath)) {
-    const validatorKeys = ["type", "required", "minLength", "maxLength", "minimum", "maximum", "pattern", "format", "const", "enum", "messages", "minItems", "maxItems", "uniqueItems", "multipleOf", "exclusiveMinimum", "exclusiveMaximum"];
-    const guess = nearest(propertyName, validatorKeys);
-    if (guess && guess !== propertyName) return `Did you mean \`${guess}\`?`;
-    return void 0;
+function checkParamExpression(value, path, out) {
+  if (value.includes("{{") || value.includes("}}")) {
+    out.push({
+      path,
+      slot: value,
+      message: "i18n param expression should not use `{{` / `}}` delimiters.",
+      suggestion: 'Use a bare expression: `"$form.fieldName"` not `"{{$form.fieldName}}"`.'
+    });
+    return;
+  }
+  if (value.startsWith("$") && /(?<![=!<>])=(?![=>])/.test(value)) {
+    out.push({
+      path,
+      slot: value,
+      message: "i18n param expression contains a single `=` (assignment).",
+      suggestion: "Param expressions are read-only. Did you mean `===` for equality?"
+    });
   }
-  return void 0;
-}
-function suggestForEnum(value, allowed) {
-  if (typeof value !== "string") return void 0;
-  const stringAllowed = allowed.filter((v) => typeof v === "string");
-  if (!stringAllowed.length) return void 0;
-  const guess = nearest(value, stringAllowed);
-  if (guess) return `Did you mean \`${guess}\`? Allowed values: ${stringAllowed.map((v) => `\`${v}\``).join(", ")}.`;
-  return `Allowed values: ${stringAllowed.map((v) => `\`${v}\``).join(", ")}.`;
 }
-const VALIDATOR_TYPES = ["string", "number", "integer", "boolean", "array", "custom"];
-function suggestForConst(value, allowed, instancePath) {
-  if (typeof value !== "string" || typeof allowed !== "string") return void 0;
-  if (/^\/form\/\d+(?:\/children\/\d+)*(?:\/props\/template)?\/type$/.test(instancePath)) {
-    const guess = nearest(value, WIDGET_TYPES);
-    return guess ? `Did you mean \`type: '${guess}'\`?` : `Valid widget types: ${WIDGET_TYPES.map((v) => `\`${v}\``).join(", ")}.`;
+function checkTemplate(value, path, out) {
+  const openCount = (value.match(/\{\{/g) ?? []).length;
+  const closeCount = (value.match(/\}\}/g) ?? []).length;
+  if (openCount !== closeCount) {
+    out.push({
+      path,
+      slot: value,
+      message: "String template has unbalanced `{{` / `}}` delimiters.",
+      suggestion: "Every `{{` must have a matching `}}`."
+    });
+    return;
   }
-  if (instancePath.endsWith("/validator/type")) {
-    const guess = nearest(value, VALIDATOR_TYPES);
-    return guess ? `Did you mean \`type: '${guess}'\`?` : `Allowed validator types: ${VALIDATOR_TYPES.map((v) => `\`${v}\``).join(", ")}.`;
+  if (openCount === 0) return;
+  let match;
+  SLOT_REGEX.lastIndex = 0;
+  while ((match = SLOT_REGEX.exec(value)) !== null) {
+    const slot = match[0];
+    const expr = match[1];
+    checkSlot(expr, slot, path, out);
   }
-  return void 0;
-}
-function describe(value) {
-  if (value === null) return "null";
-  if (Array.isArray(value)) return "array";
-  if (typeof value === "object") return "object";
-  return JSON.stringify(value);
 }
-function formatAjvErrors(errors, dataRoot) {
-  if (!errors?.length) return { errors: [], warnings: [] };
-  const collapsed = dataRoot !== void 0 ? collapseOneOfErrors(errors, dataRoot) : { errors, warnings: [] };
-  const filtered = collapsed.errors;
-  const out = [];
-  for (const err2 of filtered) {
-    const path = err2.instancePath || "/";
-    let message = err2.message ?? "invalid value";
-    let suggestion;
-    switch (err2.keyword) {
-      case "additionalProperties":
-      case "unevaluatedProperties": {
-        const prop = err2.params.additionalProperty;
-        if (prop) {
-          message = `Unknown property \`${prop}\` at \`${path}\``;
-          suggestion = suggestForAdditional(prop, path);
-        }
-        break;
-      }
-      case "required": {
-        const prop = err2.params.missingProperty;
-        if (prop) {
-          message = `Missing required property \`${prop}\` at \`${path}\``;
-        }
-        break;
-      }
-      case "enum": {
-        const allowed = err2.params.allowedValues ?? [];
-        const v = describe(err2.data);
-        message = `Value ${v} at \`${path}\` is not one of the allowed values`;
-        suggestion = suggestForEnum(err2.data, allowed);
-        break;
-      }
-      case "const": {
-        const allowed = err2.params.allowedValue;
-        message = `Expected \`${describe(allowed)}\` at \`${path}\`, got \`${describe(err2.data)}\``;
-        suggestion = suggestForConst(err2.data, allowed, path);
-        break;
-      }
-      case "type": {
-        const expected = err2.params.type;
-        message = `Expected type ${Array.isArray(expected) ? expected.join("|") : expected} at \`${path}\`, got ${describe(err2.data)}`;
-        break;
-      }
-      case "oneOf":
-      case "anyOf": {
-        message = `Value at \`${path}\` does not match any allowed variant`;
-        break;
-      }
-      default:
-        message = `${err2.message ?? "invalid value"} at \`${path}\``;
-    }
-    if (path.endsWith("/validator/format") && err2.keyword === "enum") {
-      suggestion = `Allowed string formats: ${STRING_FORMATS.map((f) => `\`${f}\``).join(", ")}.`;
-    }
+function checkSlot(expr, slot, path, out) {
+  const trimmed = expr.trim();
+  if (!trimmed) {
+    out.push({
+      path,
+      slot,
+      message: "String interpolation slot is empty.",
+      suggestion: "Add an expression, e.g. `{{$form.fieldName}}`."
+    });
+    return;
+  }
+  if (trimmed.includes("{{")) {
+    out.push({
+      path,
+      slot,
+      message: "Interpolation slot contains nested `{{`.",
+      suggestion: "Slots cannot be nested. Check for a copy-paste error."
+    });
+    return;
+  }
+  if (!/\$form\b|\$meta\b|\$errors\b|\$formIsInvalid\b/.test(trimmed)) {
+    out.push({
+      path,
+      slot,
+      message: "Interpolation slot does not reference `$form`, `$meta`, `$errors`, or `$formIsInvalid`.",
+      suggestion: "GolemUI template slots read data via `$form.fieldName`, metadata via `$meta.key`, validation errors via `$errors.fieldName`, or the built-in `$formIsInvalid` boolean."
+    });
+  }
+  if (/(?<![=!<>])=(?![=>])/.test(trimmed)) {
     out.push({
       path,
-      message,
-      suggestion,
-      keyword: err2.keyword,
-      params: err2.params
+      slot,
+      message: "Interpolation slot contains a single `=` (assignment).",
+      suggestion: "Template slots are read-only. Did you mean `===` for equality?"
     });
   }
-  return { errors: dedupe(out), warnings: collapsed.warnings };
-}
-function extractWidgetPath(instancePath) {
-  const m = instancePath.match(/^(\/form\/\d+(?:\/children\/\d+)*)/);
-  return m ? m[1] : null;
 }
-function pickIntendedBranch(widget) {
-  if (!widget || typeof widget !== "object") return null;
-  const w = widget;
-  const widgetType = typeof w.type === "string" ? w.type : void 0;
-  const widgetKind = typeof w.kind === "string" ? w.kind : void 0;
-  if (widgetType && COMPONENT_SCHEMAS[widgetType]) {
-    return { $id: COMPONENT_SCHEMAS[widgetType].$id, type: widgetType };
+function validateFormDefinition(input) {
+  const validate = getFormValidator();
+  const ajvOk = validate(input.formDefinition);
+  const { errors, warnings } = formatAjvErrors(validate.errors, input.formDefinition);
+  const expressionWarnings = lintReactiveExpressions(input.formDefinition);
+  const interpolationWarnings = lintStringInterpolations(input.formDefinition);
+  if (!ajvOk && errors.length === 0 && warnings.length === 0) {
+    errors.push({
+      path: "/",
+      keyword: "oneOf",
+      message: "Form failed schema validation but no specific error could be localized. The form may contain a widget at a position the form schema does not allow, or a structural shape that our targeted validator missed. Verify each widget against its `get_widget_spec` entry."
+    });
   }
-  if (!widgetType) return null;
-  const kindMatched = Object.entries(COMPONENT_SCHEMAS).filter(([, schema]) => {
-    const k = schema["properties"]?.["kind"]?.const;
-    return k === widgetKind;
-  });
-  const pool = kindMatched.length ? kindMatched : Object.entries(COMPONENT_SCHEMAS);
-  const candidateTypes = pool.map(([t]) => t);
-  const match = nearest(widgetType, candidateTypes);
-  if (!match) return null;
-  return { $id: COMPONENT_SCHEMAS[match].$id, type: match };
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    expressionWarnings,
+    interpolationWarnings
+  };
 }
-function collapseOneOfErrors(errors, dataRoot) {
-  const topLevel = [];
-  for (const err2 of errors) {
-    if (extractWidgetPath(err2.instancePath) === null) topLevel.push(err2);
+const VALIDATE_FORM_DEFINITION_TOOL = {
+  name: "validate_form_definition",
+  description: "Validate a GolemUI form definition against the bundled JSON Schemas. Use this AFTER generating or modifying a form definition to guarantee it is correct before the user pastes it into their codebase. Returns `{ valid, errors, warnings, expressionWarnings, interpolationWarnings }`. Hard mistakes (typos in widget `type`, missing required props, invalid validator shapes) show up in `errors` and flip `valid` to false. Likely-custom widgets (a `type` value that isn't a built-in and isn't close to one) show up in `warnings` instead — they don't affect `valid`. Reactive expressions (`include.when`, `disabled.when`, etc.) are linted separately into `expressionWarnings`. String interpolation templates (`{{$form.x}}`, `{{$meta.y}}`, expressions like `{{$form.count + 1}}`, etc.) in widget props, and bare expressions inside i18n `params` objects, are linted into `interpolationWarnings`.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      formDefinition: {
+        type: "object",
+        additionalProperties: true,
+        description: "The full GolemUI form definition object, shaped as `{ form: [...widgets], states?: {...} }`. Pass the JSON object, not a stringified version."
+      }
+    },
+    required: ["formDefinition"]
   }
-  const widgetErrors = [];
-  const warnings = [];
-  const form = dataRoot?.form;
-  if (Array.isArray(form)) {
-    form.forEach((widget, i) => {
-      collectWidgetErrors(widget, `/form/${i}`, widgetErrors, warnings);
-    });
+};
+const SUPPORTED_STRING_FORMATS = /* @__PURE__ */ new Set([
+  "email",
+  "hostname",
+  "ipv4",
+  "ipv6",
+  "url",
+  "uuid",
+  "date",
+  "time",
+  "date-time",
+  "duration"
+]);
+function buildStringValidator(s, required2) {
+  const v = { type: "string" };
+  let used = false;
+  if (required2) {
+    v.required = true;
+    used = true;
   }
-  return { errors: [...topLevel, ...widgetErrors], warnings };
-}
-function collectWidgetErrors(widget, widgetPath, out, warnings) {
-  const intended = pickIntendedBranch(widget);
-  if (!intended) {
-    const widgetType = widget?.type;
-    if (typeof widgetType !== "string" || !widgetType) {
-      out.push(
-        {
-          keyword: "required",
-          instancePath: widgetPath,
-          schemaPath: "",
-          params: { missingProperty: "type" },
-          message: `Widget at ${widgetPath} is missing or has an invalid \`type\``
-        }
-      );
-    } else {
-      warnings.push({
-        path: `${widgetPath}/type`,
-        keyword: "customWidget",
-        message: `Widget type \`${widgetType}\` at \`${widgetPath}\` is not a built-in GolemUI widget — assumed custom. Its props were not validated.`,
-        suggestion: "Built-in widget types: " + Object.keys(COMPONENT_SCHEMAS).join(", ") + ". If this is intentional (a custom widget registered via the framework loader), you can ignore this warning.",
-        params: { type: widgetType }
-      });
-    }
-    recurseIntoChildren(widget, widgetPath, out, warnings);
-    return;
+  if (typeof s.minLength === "number") {
+    v.minLength = s.minLength;
+    used = true;
   }
-  const validator = getShallowWidgetValidator(intended.type);
-  if (validator) {
-    validator(widget);
-    for (const e of validator.errors ?? []) {
-      out.push({
-        ...e,
-        instancePath: widgetPath + e.instancePath
-      });
-    }
+  if (typeof s.maxLength === "number") {
+    v.maxLength = s.maxLength;
+    used = true;
   }
-  const w = widget;
-  if (w?.validator && typeof w.validator === "object") {
-    collectValidatorErrors(w.validator, `${widgetPath}/validator`, out);
+  if (typeof s.pattern === "string") {
+    v.pattern = s.pattern;
+    used = true;
   }
-  if (widget && typeof widget === "object" && !Array.isArray(widget)) {
-    for (const [key, value] of Object.entries(widget)) {
-      if (key.startsWith("validator.") && value && typeof value === "object") {
-        collectValidatorErrors(value, `${widgetPath}/${key}`, out);
-      }
+  if (typeof s.format === "string" && SUPPORTED_STRING_FORMATS.has(s.format)) {
+    if (s.format !== "date" && s.format !== "date-time") {
+      v.format = s.format;
+      used = true;
     }
   }
-  recurseIntoChildren(widget, widgetPath, out, warnings);
-}
-function recurseIntoChildren(widget, widgetPath, out, warnings) {
-  const w = widget;
-  if (Array.isArray(w?.children)) {
-    w.children.forEach((child, i) => {
-      collectWidgetErrors(child, `${widgetPath}/children/${i}`, out, warnings);
-    });
+  if (s.const !== void 0) {
+    v.const = s.const;
+    used = true;
   }
-  if (w?.type === "repeater" && w.props?.template) {
-    collectWidgetErrors(w.props.template, `${widgetPath}/props/template`, out, warnings);
+  if (Array.isArray(s.enum)) {
+    v.enum = s.enum;
+    used = true;
   }
+  return used ? v : void 0;
 }
-function collectValidatorErrors(validator, path, out) {
-  const v = validator;
-  const t = typeof v.type === "string" ? v.type : null;
-  const branches = getValidatorBranches();
-  const matchedType = t && branches.includes(t) ? t : t ? nearest(t, branches) : void 0;
-  if (!matchedType) {
-    out.push({
-      keyword: "enum",
-      instancePath: `${path}/type`,
-      schemaPath: "",
-      params: { allowedValues: branches },
-      message: `Validator type is not one of ${branches.join(", ")}`,
-      data: t
-    });
-    return;
+function buildNumberValidator(s, required2, t) {
+  const v = { type: t };
+  let used = false;
+  if (required2) {
+    v.required = true;
+    used = true;
   }
-  const compiled = getValidatorBranchValidator(matchedType);
-  if (!compiled) return;
-  compiled(validator);
-  for (const e of compiled.errors ?? []) {
-    out.push({ ...e, instancePath: path + e.instancePath });
+  if (typeof s.minimum === "number") {
+    v.minimum = s.minimum;
+    used = true;
   }
-}
-function dedupe(errors) {
-  const seen = /* @__PURE__ */ new Set();
-  const result = [];
-  for (const e of errors) {
-    const key = `${e.path}|${e.keyword}|${e.message}`;
-    if (seen.has(key)) continue;
-    seen.add(key);
-    result.push(e);
+  if (typeof s.maximum === "number") {
+    v.maximum = s.maximum;
+    used = true;
   }
-  return result;
-}
-function lintReactiveExpressions(formDefinition) {
-  const findings = [];
-  walk$1(formDefinition, "", findings);
-  return findings;
+  if (typeof s.exclusiveMinimum === "number") {
+    v.exclusiveMinimum = s.exclusiveMinimum;
+    used = true;
+  }
+  if (typeof s.exclusiveMaximum === "number") {
+    v.exclusiveMaximum = s.exclusiveMaximum;
+    used = true;
+  }
+  if (typeof s.multipleOf === "number") {
+    v.multipleOf = s.multipleOf;
+    used = true;
+  }
+  return used ? v : void 0;
 }
-function walk$1(node, path, out) {
-  if (node === null || typeof node !== "object") return;
-  if (Array.isArray(node)) {
-    node.forEach((item, i) => walk$1(item, `${path}/${i}`, out));
-    return;
+function buildBooleanValidator(s, required2) {
+  const v = { type: "boolean" };
+  let used = false;
+  if (required2) {
+    v.required = true;
+    used = true;
   }
-  const obj = node;
-  for (const key of ["include", "exclude"]) {
-    const child = obj[key];
-    if (child && typeof child === "object" && "when" in child) {
-      const expr = child.when;
-      if (typeof expr === "string") {
-        checkExpression(expr, `${path}/${key}/when`, out);
-      }
+  if (s.const !== void 0) {
+    v.const = s.const;
+    used = true;
+  }
+  return used ? v : void 0;
+}
+const SECRET_HINTS = /(password|secret|api[_-]?key|token)/i;
+const LONG_TEXT_MIN_LENGTH = 200;
+const SELECT_THRESHOLD = 6;
+function jsonSchemaToGui(schema, opts = {}) {
+  const unmapped = [];
+  const root = unwrap(schema);
+  const fields = [];
+  if (root.type === "object" || root.properties) {
+    const required2 = new Set(root.required ?? []);
+    for (const [name, propSchema] of Object.entries(root.properties ?? {})) {
+      const widget = mapProperty(name, unwrap(propSchema), required2.has(name), "", unmapped);
+      if (widget) fields.push(widget);
     }
+  } else {
+    unmapped.push({
+      path: "",
+      reason: "Top-level JSON Schema is not an object — only object schemas map to forms."
+    });
   }
-  if (path === "" && obj["states"] && typeof obj["states"] === "object") {
-    for (const [name, expr] of Object.entries(obj["states"])) {
-      if (typeof expr === "string") {
-        checkExpression(expr, `/states/${name}`, out);
-      }
-    }
+  if (opts.submitAction !== false) {
+    fields.push({
+      kind: "action",
+      type: "button",
+      actionType: "submit",
+      label: opts.submitLabel ?? "Submit",
+      props: { variant: "filled" }
+    });
   }
-  for (const [k, v] of Object.entries(obj)) {
-    if (v && typeof v === "object" && !Array.isArray(v) && "when" in v) {
-      const expr = v.when;
-      if (typeof expr === "string" && k !== "include" && k !== "exclude") {
-        checkExpression(expr, `${path}/${k}/when`, out);
-      }
-    }
-    if (typeof v === "object" && v !== null) {
-      walk$1(v, `${path}/${k}`, out);
+  const wrapped = opts.layout && opts.layout !== "vertical" ? [
+    {
+      kind: "layout",
+      type: opts.layout === "grid" ? "grid" : "flex",
+      props: opts.layout === "grid" ? { columnGap: 12, rowGap: 12 } : { direction: "row", gap: 12 },
+      children: fields
     }
-  }
+  ] : fields;
+  return {
+    formDefinition: { $schema: "https://golemui.com/schemas/form.schema.json", form: wrapped },
+    unmapped
+  };
 }
-function checkExpression(expr, path, out) {
-  const trimmed = expr.trim();
-  if (!trimmed) {
-    out.push({ path, expression: expr, message: "Expression is empty." });
-    return;
+function unwrap(schema) {
+  if (schema.oneOf?.length === 2) {
+    const nonNull = schema.oneOf.find((s) => s.type !== "null");
+    if (nonNull) return { ...nonNull, ...stripBranches(schema) };
   }
-  const stack = [];
-  const pairs = { ")": "(", "]": "[", "}": "{" };
-  for (const ch of trimmed) {
-    if ("([{".includes(ch)) stack.push(ch);
-    else if (")]}".includes(ch)) {
-      if (stack.pop() !== pairs[ch]) {
-        out.push({
-          path,
-          expression: expr,
-          message: `Unbalanced \`${ch}\` in reactive expression.`
-        });
-        return;
-      }
-    }
+  if (schema.anyOf?.length === 2) {
+    const nonNull = schema.anyOf.find((s) => s.type !== "null");
+    if (nonNull) return { ...nonNull, ...stripBranches(schema) };
   }
-  if (stack.length) {
-    out.push({
-      path,
-      expression: expr,
-      message: `Unclosed \`${stack[stack.length - 1]}\` in reactive expression.`
-    });
-    return;
+  return schema;
+}
+function stripBranches(s) {
+  const { oneOf: oneOf2, anyOf, ...rest } = s;
+  return rest;
+}
+function mapProperty(name, schema, required2, parentPath, unmapped) {
+  const path = parentPath ? `${parentPath}.${name}` : name;
+  const label = humanLabel(schema.title ?? name);
+  const t = Array.isArray(schema.type) ? schema.type.find((x) => x !== "null") : schema.type;
+  if (Array.isArray(schema.enum) && schema.enum.every((v) => typeof v === "string")) {
+    return buildEnumField(path, name, label, schema, required2);
   }
-  if (!/\$form\b|\$meta\b|\$formIsInvalid\b/.test(trimmed)) {
-    out.push({
-      path,
-      expression: expr,
-      message: "Expression does not reference `$form`, `$meta`, or `$formIsInvalid`.",
-      suggestion: "GolemUI expressions read form data via `$form.fieldName`, form metadata via `$meta.key`, or the built-in `$formIsInvalid` boolean. Did you forget the prefix?"
-    });
+  switch (t) {
+    case "string":
+      return buildStringField(path, name, label, schema, required2);
+    case "number":
+    case "integer":
+      return buildNumberField(path, label, schema, required2, t);
+    case "boolean":
+      return buildBooleanField(path, label, schema, required2);
+    case "object":
+      return buildObjectGroup(path, name, label, schema, unmapped);
+    case "array":
+      return buildArrayField(path, name, label, schema, required2, unmapped);
+    default:
+      unmapped.push({
+        path,
+        reason: `Unsupported JSON Schema type \`${schema.type ?? "undefined"}\`.`
+      });
+      return null;
   }
-  if (/(?<![=!<>])=(?![=>])/.test(trimmed)) {
-    out.push({
-      path,
-      expression: expr,
-      message: "Expression contains a single `=` (assignment). Reactive expressions are read-only.",
-      suggestion: "Use `===` for equality comparison."
-    });
+}
+function buildStringField(path, name, label, schema, required2) {
+  const validator = buildStringValidator(schema, required2);
+  const isSecret = SECRET_HINTS.test(name);
+  const isLong = (schema.maxLength ?? 0) >= LONG_TEXT_MIN_LENGTH;
+  if (schema.format === "date") {
+    return cleanFields({ kind: "input", type: "dateInput", path, label, validator });
   }
-  if (/(?<![&])&(?![&])/.test(trimmed) || /(?<![|])\|(?![|])/.test(trimmed)) {
-    out.push({
-      path,
-      expression: expr,
-      message: "Expression contains a single `&` or `|` (bitwise).",
-      suggestion: "Use `&&` for logical AND, `||` for logical OR."
-    });
+  if (schema.format === "date-time") {
+    return cleanFields({ kind: "input", type: "datePicker", path, label, validator });
   }
-  if (/(?<![=!])==(?!=)/.test(trimmed) || /(?<![!])!=(?!=)/.test(trimmed)) {
-    out.push({
-      path,
-      expression: expr,
-      message: "Expression uses loose equality (`==` or `!=`).",
-      suggestion: "Use strict equality `===` / `!==` to avoid type coercion (e.g. `$form.x !== undefined` rather than `$form.x != null`)."
-    });
+  if (isSecret) {
+    return cleanFields({ kind: "input", type: "password", path, label, validator });
   }
-  if (/(?<![=!])!\s*\$(?:form|meta)\b/.test(trimmed)) {
-    out.push({
+  if (isLong) {
+    return cleanFields({
+      kind: "input",
+      type: "textarea",
       path,
-      expression: expr,
-      message: "Expression negates a `$form`/`$meta` reference (relies on truthy/falsy coercion).",
-      suggestion: 'Form data values can be `undefined`. Pick the case you actually mean and write it explicitly — `$form.x === undefined`, `$form.x === null`, `$form.x === 0`, `$form.x === ""` — instead of `!$form.x`.'
+      label,
+      validator,
+      props: schema.description ? { hint: schema.description } : void 0
     });
   }
-  const refChainRe = /\$(?:form|meta)\b((?:\.[\w?]+)*)/g;
-  let chainFlagged = false;
-  let chainMatch;
-  while ((chainMatch = refChainRe.exec(trimmed)) !== null) {
-    const chain = chainMatch[1];
-    if (!chain) continue;
-    const segments = chain.split(".").filter(Boolean);
-    let unsafe = false;
-    for (let i = 0; i < segments.length - 1; i++) {
-      const segment = segments[i];
-      if (!segment || !segment.endsWith("?")) {
-        unsafe = true;
-        break;
-      }
-    }
-    if (unsafe && !chainFlagged) {
-      out.push({
-        path,
-        expression: expr,
-        message: "Expression chains nested property access without optional chaining (e.g. `$form.user.name`).",
-        suggestion: "Treat every nested property as possibly `undefined`. Use `?.` between segments: `$form.user?.name` instead of `$form.user.name`. The runtime throws if `$form.user` is undefined."
-      });
-      chainFlagged = true;
-    }
-  }
-  const refOnly = /^\$(?:form|meta)(?:\.[\w?]+)*$/;
-  const refBeforeBool = /\$(?:form|meta)(?:\.[\w?]+)*\s*(?:&&|\|\||\?(?![.?]))/;
-  const refAfterBool = /(?:&&|\|\|)\s*\$(?:form|meta)(?:\.[\w?]+)*\s*$/;
-  if (refOnly.test(trimmed) || refBeforeBool.test(trimmed) || refAfterBool.test(trimmed)) {
-    out.push({
+  return cleanFields({
+    kind: "input",
+    type: "textinput",
+    path,
+    label,
+    validator,
+    props: schema.description ? { hint: schema.description } : void 0
+  });
+}
+function buildEnumField(path, name, label, schema, required2) {
+  const values = schema.enum ?? [];
+  const validator = required2 ? { type: "string", required: true, enum: values } : { type: "string", enum: values };
+  if (values.length <= SELECT_THRESHOLD) {
+    return cleanFields({
+      kind: "input",
+      type: "select",
       path,
-      expression: expr,
-      message: "Expression uses `$form`/`$meta` directly as a boolean (relies on truthy/falsy coercion).",
-      suggestion: 'Form data values can be `undefined`. Compare explicitly: `$form.x !== undefined`, `$form.x === "value"`, `$form.items?.length > 0`. For default values use nullish coalescing: `$form.x ?? defaultValue`.'
+      label,
+      validator,
+      props: {
+        options: values.map((v) => ({ label: humanLabel(v), value: v }))
+      }
     });
   }
-  const refForCmpRe = /\$(?:form|meta)(?:\.[\w?]+)+/g;
-  let r5Flagged = false;
-  let cmpMatch;
-  while ((cmpMatch = refForCmpRe.exec(trimmed)) !== null) {
-    const start = cmpMatch.index;
-    const end = start + cmpMatch[0].length;
-    const before = trimmed.slice(0, start).trimEnd();
-    const after = trimmed.slice(end).trimStart();
-    const opAfter = /^(?:<=?|>=?|[+\-*/%])(?!=)/.test(after);
-    const opBefore = /(?<![=!])[<>+\-*/%]$/.test(before);
-    if (!(opAfter || opBefore)) continue;
-    if (/&&|\|\|/.test(before)) continue;
-    if (!r5Flagged) {
-      out.push({
-        path,
-        expression: expr,
-        message: "Expression applies a comparison or arithmetic operator to a `$form`/`$meta` reference whose leaf may be `undefined`.",
-        suggestion: "Guard the value first: `$form.x !== undefined && $form.x > 180`. Or default it: `($form.x ?? 0) > 180`. Strict equality (`$form.x === 180`) is also safe since it evaluates to `false` when undefined."
-      });
-      r5Flagged = true;
+  return cleanFields({
+    kind: "input",
+    type: "dropdown",
+    path,
+    label,
+    validator,
+    props: {
+      labelField: "label",
+      valueField: "value",
+      items: values.map((v) => ({ label: humanLabel(v), value: v }))
     }
-  }
+  });
+}
+function buildNumberField(path, label, schema, required2, t) {
+  const validator = buildNumberValidator(schema, required2, t);
+  return cleanFields({
+    kind: "input",
+    type: "number",
+    path,
+    label,
+    validator,
+    props: schema.description ? { hint: schema.description } : void 0
+  });
 }
-function lintStringInterpolations(formDefinition) {
-  const findings = [];
-  walk(formDefinition, "", findings);
-  return findings;
+function buildBooleanField(path, label, schema, required2) {
+  const validator = buildBooleanValidator(schema, required2);
+  return cleanFields({ kind: "input", type: "checkbox", path, label, validator });
 }
-const SLOT_REGEX = /\{\{([^}]*(?:\}[^}]+)*)\}\}/g;
-function walk(node, path, out) {
-  if (node === null || typeof node !== "object") {
-    return;
+function buildObjectGroup(path, _name, _label, schema, unmapped) {
+  const required2 = new Set(schema.required ?? []);
+  const children = [];
+  for (const [childName, childSchema] of Object.entries(schema.properties ?? {})) {
+    const w = mapProperty(childName, unwrap(childSchema), required2.has(childName), path, unmapped);
+    if (w) children.push(w);
   }
-  if (Array.isArray(node)) {
-    node.forEach((item, i) => walk(item, `${path}/${i}`, out));
-    return;
+  if (!children.length) {
+    unmapped.push({ path, reason: "Object has no mappable properties." });
+    return null;
   }
-  const obj = node;
-  const isTranslationConfig = typeof obj["key"] === "string" && obj["params"] !== null && typeof obj["params"] === "object" && !Array.isArray(obj["params"]);
-  if (isTranslationConfig) {
-    const params = obj["params"];
-    for (const [paramKey, paramValue] of Object.entries(params)) {
-      if (typeof paramValue === "string") {
-        checkParamExpression(paramValue, `${path}/params/${paramKey}`, out);
-      }
-    }
+  return {
+    kind: "layout",
+    type: "flex",
+    props: { direction: "column", gap: 8 },
+    children
+  };
+}
+function buildArrayField(path, _name, label, schema, required2, unmapped) {
+  const items = schema.items ? unwrap(schema.items) : void 0;
+  if (!items) {
+    unmapped.push({ path, reason: "Array without `items` schema cannot be mapped." });
+    return null;
   }
-  for (const [key, value] of Object.entries(obj)) {
-    if (key === "params" && isTranslationConfig) {
-      continue;
-    }
-    if (key === "defaultValue" || key.startsWith("defaultValue.")) {
-      continue;
+  if (items.type === "object") {
+    const templateChildren = [];
+    const required22 = new Set(items.required ?? []);
+    const childParent = `${path}.items`;
+    for (const [childName, childSchema] of Object.entries(items.properties ?? {})) {
+      const w = mapProperty(
+        childName,
+        unwrap(childSchema),
+        required22.has(childName),
+        childParent,
+        unmapped
+      );
+      if (w) templateChildren.push(w);
     }
-    const childPath = `${path}/${key}`;
-    if (typeof value === "string") {
-      checkTemplate(value, childPath, out);
-    } else {
-      walk(value, childPath, out);
+    if (!templateChildren.length) {
+      unmapped.push({ path, reason: "Array of objects has no mappable item properties." });
+      return null;
     }
-  }
-}
-function checkParamExpression(value, path, out) {
-  if (value.includes("{{") || value.includes("}}")) {
-    out.push({
-      path,
-      slot: value,
-      message: "i18n param expression should not use `{{` / `}}` delimiters.",
-      suggestion: 'Use a bare expression: `"$form.fieldName"` not `"{{$form.fieldName}}"`.'
-    });
-    return;
-  }
-  if (value.startsWith("$") && /(?<![=!<>])=(?![=>])/.test(value)) {
-    out.push({
+    return {
+      kind: "input",
+      type: "repeater",
       path,
-      slot: value,
-      message: "i18n param expression contains a single `=` (assignment).",
-      suggestion: "Param expressions are read-only. Did you mean `===` for equality?"
-    });
+      label,
+      props: {
+        addLabel: `Add ${singular(label).toLowerCase()}`,
+        removeLabel: "Remove",
+        template: {
+          kind: "layout",
+          type: "flex",
+          props: { direction: "column", gap: 8 },
+          children: templateChildren
+        }
+      }
+    };
   }
-}
-function checkTemplate(value, path, out) {
-  const openCount = (value.match(/\{\{/g) ?? []).length;
-  const closeCount = (value.match(/\}\}/g) ?? []).length;
-  if (openCount !== closeCount) {
-    out.push({
+  if (items.type === "string" || items.type === "number" || items.type === "integer") {
+    const validator = buildArrayValidator(schema, required2);
+    return cleanFields({
+      kind: "input",
+      type: "tags",
       path,
-      slot: value,
-      message: "String template has unbalanced `{{` / `}}` delimiters.",
-      suggestion: "Every `{{` must have a matching `}}`."
+      label,
+      validator,
+      props: schema.description ? { placeholder: "Add and press Enter", hint: schema.description } : { placeholder: "Add and press Enter" }
     });
-    return;
-  }
-  if (openCount === 0) return;
-  let match;
-  SLOT_REGEX.lastIndex = 0;
-  while ((match = SLOT_REGEX.exec(value)) !== null) {
-    const slot = match[0];
-    const expr = match[1];
-    checkSlot(expr, slot, path, out);
   }
+  unmapped.push({
+    path,
+    reason: "Array shape is not mappable (only arrays of objects → repeater, or arrays of strings/numbers → tags)."
+  });
+  return null;
 }
-function checkSlot(expr, slot, path, out) {
-  const trimmed = expr.trim();
-  if (!trimmed) {
-    out.push({
-      path,
-      slot,
-      message: "String interpolation slot is empty.",
-      suggestion: "Add an expression, e.g. `{{$form.fieldName}}`."
-    });
-    return;
+function buildArrayValidator(s, required2) {
+  const v = { type: "array" };
+  let used = false;
+  if (required2) {
+    v.required = true;
+    used = true;
   }
-  if (trimmed.includes("{{")) {
-    out.push({
-      path,
-      slot,
-      message: "Interpolation slot contains nested `{{`.",
-      suggestion: "Slots cannot be nested. Check for a copy-paste error."
-    });
-    return;
+  if (typeof s.minItems === "number") {
+    v.minItems = s.minItems;
+    used = true;
   }
-  if (!/\$form\b|\$meta\b|\$errors\b|\$formIsInvalid\b/.test(trimmed)) {
-    out.push({
-      path,
-      slot,
-      message: "Interpolation slot does not reference `$form`, `$meta`, `$errors`, or `$formIsInvalid`.",
-      suggestion: "GolemUI template slots read data via `$form.fieldName`, metadata via `$meta.key`, validation errors via `$errors.fieldName`, or the built-in `$formIsInvalid` boolean."
-    });
+  if (typeof s.maxItems === "number") {
+    v.maxItems = s.maxItems;
+    used = true;
   }
-  if (/(?<![=!<>])=(?![=>])/.test(trimmed)) {
-    out.push({
-      path,
-      slot,
-      message: "Interpolation slot contains a single `=` (assignment).",
-      suggestion: "Template slots are read-only. Did you mean `===` for equality?"
-    });
+  if (s.uniqueItems === true) {
+    v.uniqueItems = true;
+    used = true;
   }
+  return used ? v : void 0;
 }
-function validateFormDefinition(input) {
-  const validate = getFormValidator();
-  const ajvOk = validate(input.formDefinition);
-  const { errors, warnings } = formatAjvErrors(validate.errors, input.formDefinition);
-  const expressionWarnings = lintReactiveExpressions(input.formDefinition);
-  const interpolationWarnings = lintStringInterpolations(input.formDefinition);
-  if (!ajvOk && errors.length === 0 && warnings.length === 0) {
-    errors.push({
-      path: "/",
-      keyword: "oneOf",
-      message: "Form failed schema validation but no specific error could be localized. The form may contain a widget at a position the form schema does not allow, or a structural shape that our targeted validator missed. Verify each widget against its `get_widget_spec` entry."
-    });
-  }
-  return {
-    valid: errors.length === 0,
-    errors,
-    warnings,
-    expressionWarnings,
-    interpolationWarnings
-  };
+function humanLabel(name) {
+  if (!name) return "";
+  return name.replace(/[_-]+/g, " ").replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/\s+/g, " ").trim().replace(/^./, (c) => c.toUpperCase());
 }
-const VALIDATE_FORM_DEFINITION_TOOL = {
-  name: "validate_form_definition",
-  description: "Validate a GolemUI form definition against the bundled JSON Schemas. Use this AFTER generating or modifying a form definition to guarantee it is correct before the user pastes it into their codebase. Returns `{ valid, errors, warnings, expressionWarnings, interpolationWarnings }`. Hard mistakes (typos in widget `type`, missing required props, invalid validator shapes) show up in `errors` and flip `valid` to false. Likely-custom widgets (a `type` value that isn't a built-in and isn't close to one) show up in `warnings` instead — they don't affect `valid`. Reactive expressions (`include.when`, `disabled.when`, etc.) are linted separately into `expressionWarnings`. String interpolation templates (`{{$form.x}}`, `{{$meta.y}}`, expressions like `{{$form.count + 1}}`, etc.) in widget props, and bare expressions inside i18n `params` objects, are linted into `interpolationWarnings`.",
-  inputSchema: {
-    type: "object",
-    properties: {
-      formDefinition: {
-        type: "object",
-        additionalProperties: true,
-        description: "The full GolemUI form definition object, shaped as `{ form: [...widgets], states?: {...} }`. Pass the JSON object, not a stringified version."
-      }
-    },
-    required: ["formDefinition"]
+function singular(label) {
+  if (label.endsWith("ies") && label.length > 3) return label.slice(0, -3) + "y";
+  if (label.endsWith("s") && !label.endsWith("ss")) return label.slice(0, -1);
+  return label;
+}
+function cleanFields(o) {
+  for (const k of Object.keys(o)) {
+    if (o[k] === void 0) delete o[k];
   }
-};
+  return o;
+}
 function generateFromJsonSchema(input) {
   const opts = {
     submitAction: input.submitAction,
@@ -1866,66 +1859,368 @@ function defaultSubmitLabel(method, op) {
   };
   return verbs[method.toLowerCase()] ?? "Submit";
 }
-function derefSchema(schema, doc, depth = 0) {
-  if (depth > 16) return schema;
-  if (typeof schema.$ref === "string") {
-    const target = resolveLocalRef(schema.$ref, doc);
-    if (target) return derefSchema(target, doc, depth + 1);
-    return schema;
+function derefSchema(schema, doc, depth = 0) {
+  if (depth > 16) return schema;
+  if (typeof schema.$ref === "string") {
+    const target = resolveLocalRef(schema.$ref, doc);
+    if (target) return derefSchema(target, doc, depth + 1);
+    return schema;
+  }
+  const result = { ...schema };
+  if (result.properties) {
+    result.properties = Object.fromEntries(
+      Object.entries(result.properties).map(([k, v]) => [k, derefSchema(v, doc, depth + 1)])
+    );
+  }
+  if (result.items) result.items = derefSchema(result.items, doc, depth + 1);
+  if (result.oneOf) result.oneOf = result.oneOf.map((s) => derefSchema(s, doc, depth + 1));
+  if (result.anyOf) result.anyOf = result.anyOf.map((s) => derefSchema(s, doc, depth + 1));
+  return result;
+}
+function resolveLocalRef(ref, doc) {
+  if (!ref.startsWith("#/")) return null;
+  const parts = ref.slice(2).split("/");
+  let cur = doc;
+  for (const p of parts) {
+    if (cur && typeof cur === "object") {
+      cur = cur[p];
+    } else {
+      return null;
+    }
+  }
+  return cur ?? null;
+}
+const GENERATE_FROM_OPENAPI_TOOL = {
+  name: "generate_from_openapi",
+  description: 'Generate a GolemUI form for a specific OpenAPI 3.x operation (e.g. "POST /users"). Resolves the operation\'s JSON request body, dereferences `$ref`s, then maps it to a form definition that is validated against the GolemUI JSON Schemas before being returned, so it is guaranteed syntactically correct. Falls back to operation parameters when no request body is present. Anything the mapper cannot handle is reported in `unmapped` rather than silently dropped — use that list to surface remaining work to the user. Pass either a parsed `document` or a `documentUrl` to fetch.',
+  inputSchema: {
+    type: "object",
+    properties: {
+      documentUrl: {
+        type: "string",
+        description: "URL of a JSON OpenAPI document. Either this or `document` is required."
+      },
+      document: {
+        type: "object",
+        additionalProperties: true,
+        description: "Parsed OpenAPI document (JSON object). Either this or `documentUrl` is required."
+      },
+      operation: {
+        type: "string",
+        description: 'The operation to generate a form for. Either "METHOD /path" (e.g. "POST /users") or an exact operationId.'
+      },
+      submitAction: {
+        type: "boolean",
+        description: "Append a submit button. Defaults to true."
+      },
+      submitLabel: {
+        type: "string",
+        description: "Label for the submit button. Defaults to the operation summary or a verb derived from the HTTP method."
+      }
+    },
+    required: ["operation"]
   }
-  const result = { ...schema };
-  if (result.properties) {
-    result.properties = Object.fromEntries(
-      Object.entries(result.properties).map(([k, v]) => [k, derefSchema(v, doc, depth + 1)])
-    );
+};
+const EXAMPLES = {
+  accordion: {
+    kind: "layout",
+    type: "accordion",
+    props: {
+      sections: [
+        { uid: "personal", label: "Personal" },
+        { uid: "preferences", label: "Preferences" }
+      ]
+    },
+    children: [
+      { kind: "input", type: "textinput", path: "firstName", label: "First name" },
+      { kind: "input", type: "checkbox", path: "newsletter", label: "Newsletter" }
+    ]
+  },
+  textinput: {
+    kind: "input",
+    type: "textinput",
+    path: "firstName",
+    label: "First name",
+    validator: { type: "string", required: true, minLength: 1 },
+    props: { placeholder: "Jane" }
+  },
+  textarea: {
+    kind: "input",
+    type: "textarea",
+    path: "bio",
+    label: "Bio",
+    props: { minimumHeight: 120, autoGrow: true }
+  },
+  tags: {
+    kind: "input",
+    type: "tags",
+    path: "keywords",
+    label: "Keywords",
+    defaultValue: [],
+    props: {
+      placeholder: "Add a keyword and press Enter",
+      separators: ["Enter", ","],
+      trim: true,
+      allowDuplicates: false,
+      limit: 10
+    },
+    validator: {
+      type: "array",
+      minItems: 1,
+      maxItems: 10
+    }
+  },
+  password: {
+    kind: "input",
+    type: "password",
+    path: "password",
+    label: "Password",
+    validator: { type: "string", required: true, minLength: 8 }
+  },
+  number: {
+    kind: "input",
+    type: "number",
+    path: "age",
+    label: "Age",
+    validator: { type: "integer", required: true, minimum: 0 }
+  },
+  currency: {
+    kind: "input",
+    type: "currency",
+    path: "salary",
+    label: "Salary",
+    props: { currency: "USD" }
+  },
+  checkbox: {
+    kind: "input",
+    type: "checkbox",
+    path: "termsAccepted",
+    label: "I accept the terms",
+    validator: { type: "boolean", required: true, const: true }
+  },
+  toggle: {
+    kind: "input",
+    type: "toggle",
+    path: "notifications",
+    label: "Email notifications"
+  },
+  dropdown: {
+    kind: "input",
+    type: "dropdown",
+    path: "country",
+    label: "Country",
+    props: {
+      labelField: "label",
+      valueField: "value",
+      items: [
+        { label: "United States", value: "us", flag: "🇺🇸" },
+        { label: "Canada", value: "ca", flag: "🇨🇦" }
+      ]
+    }
+  },
+  select: {
+    kind: "input",
+    type: "select",
+    path: "plan",
+    label: "Plan",
+    props: {
+      options: [
+        { label: "Free", value: "free" },
+        { label: "Pro", value: "pro" }
+      ]
+    }
+  },
+  radiogroup: {
+    kind: "input",
+    type: "radiogroup",
+    path: "shippingSpeed",
+    label: "Shipping",
+    props: {
+      options: [
+        { label: "Standard", value: "standard" },
+        { label: "Express", value: "express" }
+      ]
+    }
+  },
+  dateInput: {
+    kind: "input",
+    type: "dateInput",
+    path: "birthDate",
+    label: "Birth date"
+  },
+  datePicker: {
+    kind: "input",
+    type: "datePicker",
+    path: "startDate",
+    label: "Start date"
+  },
+  calendar: {
+    kind: "input",
+    type: "calendar",
+    path: "eventDate",
+    label: "Event date"
+  },
+  button: {
+    kind: "action",
+    type: "button",
+    actionType: "submit",
+    label: "Submit",
+    props: { variant: "filled" }
+  },
+  alert: {
+    kind: "display",
+    type: "alert",
+    props: { level: "info", text: "Heads up!" }
+  },
+  markdownText: {
+    kind: "display",
+    type: "markdownText",
+    props: { md: "Welcome to the form." }
+  },
+  flex: {
+    kind: "layout",
+    type: "flex",
+    props: { direction: "column", gap: 12 },
+    children: [
+      {
+        kind: "input",
+        type: "textinput",
+        path: "firstName",
+        label: "First name"
+      }
+    ]
+  },
+  grid: {
+    kind: "layout",
+    type: "grid",
+    props: { columnGap: 12, rowGap: 12 },
+    children: [
+      { kind: "input", type: "textinput", path: "firstName", label: "First name" },
+      { kind: "input", type: "textinput", path: "lastName", label: "Last name" }
+    ]
+  },
+  tabs: {
+    kind: "layout",
+    type: "tabs",
+    props: {
+      tabs: [
+        { uid: "personal", label: "Personal" },
+        { uid: "address", label: "Address" }
+      ]
+    },
+    children: [
+      { kind: "input", type: "textinput", path: "firstName", label: "First name" },
+      { kind: "input", type: "textinput", path: "street", label: "Street" }
+    ]
+  },
+  repeater: {
+    kind: "input",
+    type: "repeater",
+    path: "addresses",
+    label: "Addresses",
+    props: {
+      addLabel: "Add address",
+      removeLabel: "Remove",
+      template: {
+        kind: "layout",
+        type: "flex",
+        props: { direction: "column" },
+        children: [
+          // Child paths inside a repeater template MUST be `<repeater.path>.items.<field>` —
+          // `items` is the reserved segment that the runtime expands per array entry.
+          { kind: "input", type: "textinput", path: "addresses.items.street", label: "Street" },
+          { kind: "input", type: "textinput", path: "addresses.items.city", label: "City" }
+        ]
+      }
+    }
   }
-  if (result.items) result.items = derefSchema(result.items, doc, depth + 1);
-  if (result.oneOf) result.oneOf = result.oneOf.map((s) => derefSchema(s, doc, depth + 1));
-  if (result.anyOf) result.anyOf = result.anyOf.map((s) => derefSchema(s, doc, depth + 1));
-  return result;
+};
+const NOTES = {
+  textinput: [
+    "`path` is the dot-path into form data this field writes to.",
+    "`validator.format` supports: `email`, `hostname`, `ipv4`, `ipv6`, `url`, `uuid`, `date`, `time`, `date-time`, `duration`.",
+    'Root props `label`, `disabled`, `readonly`, `validator`, and `size` accept state suffixes — e.g. `"label.<stateName>": "New label"` overrides the label only when that named state is active. Props inside `props` (e.g. `hint`, `placeholder`) also accept suffixes as `"hint.<stateName>"`. Call `get_concept({ concept: "states" })` for the full pattern.'
+  ],
+  markdownText: [
+    "Display-only widget for rendering markdown. Can be used as a top-level form widget (inside any layout) or inside templates like `dropdown.props.items[].template`.",
+    "The required prop is `md` (the markdown string), not `text`."
+  ],
+  tags: [
+    "Use `tags` for free-form arrays of primitive values (typically `string[]`) — e.g. keywords, email lists, hashtags. Backing data is `string[]`. For arrays of structured objects, use `repeater` instead.",
+    '`props.separators` controls which keys/characters commit a new tag. Defaults emit on `Enter` and `,`; you can also include `"Tab"` or `"blur"`. `props.trim` strips whitespace from each tag; `props.allowDuplicates: false` rejects repeats; `props.limit` caps the array length.',
+    'Validate with an `arrayValidator`: `{ type: "array", minItems, maxItems, uniqueItems }`. The `tags` widget complements that with UI-level enforcement (`allowDuplicates`, `limit`) but the validator is still authoritative for form-level required/min/max constraints.'
+  ],
+  dropdown: [
+    "PREFER `select` for plain label/value lists (countries, plans, sizes). `dropdown` is for richer item shapes: when each item has extra fields (icons, flags, metadata) that an `itemRenderer` or `labelField`/`valueField` can use.",
+    '`props.items` is EITHER primitives `["one", 2, ...]` OR arbitrary objects `[{ label, value, ...extras }]`. Pair the object form with `labelField`/`valueField` to tell the dropdown which fields to render as label and which to use as the value. **Widget templates inside items (the `{template, value}` shape) are NOT supported — only `repeater` accepts widget templates.**'
+  ],
+  select: [
+    '`props.options[]` is the simple form: `[{ label: "United States", value: "us" }, ...]`. Use this for ANY plain text list — countries, plans, sizes, status enums. Only switch to `dropdown` if you need custom per-item rendering (icons, flags, rich layouts).',
+    "For very large lists (>50 items) consider `dropdown` for its virtualization (`height`, `itemHeight`, `searchFields`)."
+  ],
+  flex: ["`children` is an array of any widgets (inputs, displays, nested layouts)."],
+  grid: ["`children` is an array of any widgets. `props.columns` controls layout."],
+  tabs: [
+    "Children are associated with tabs by **`uid` matching**, not by array order: each direct child must have a `uid` field at the widget level (alongside `kind`/`type`) whose string value equals one of the `props.tabs[].uid` entries. There is no `tag` property — that is not a real GolemUI field.",
+    "Children are typically written in display order for readability, but rearranging them does not change which tab they belong to — only the `uid` string match does."
+  ],
+  accordion: [
+    "Children are associated with sections by **`uid` matching** (same pattern as `tabs`): each direct child must have a `uid` field at the widget level whose value equals one of the `props.sections[].uid` entries. There is no `tag` property.",
+    "`props.defaultOpen` is a map of `{ <sectionUid>: boolean }` controlling which sections start expanded."
+  ],
+  repeater: [
+    "`props.template` must be a layout widget (flex/grid/tabs/accordion) whose children are the per-item fields.",
+    'Child paths inside the template MUST follow the form `<repeater.path>.items.<fieldName>`. The `items` segment is reserved — the runtime substitutes it with the current array index per row. For example, a repeater at `path: "users"` with a child `firstName` uses `path: "users.items.firstName"`. Plain `firstName` will NOT bind to the array.',
+    'Nested repeaters chain the convention: a repeater at `path: "teams"` whose template contains a repeater at `path: "teams.items.members"` whose children use `path: "teams.items.members.items.<field>"`.',
+    '`addLabel` supports state suffixes: `"addLabel.<stateName>": "Limit reached"` swaps the add-button label when a named state is active — useful for capping array length. Call `get_concept({ concept: "states" })` for the full pattern.'
+  ],
+  button: [
+    "`actionType` controls the button's role. `actionType: \"submit\"` makes the button fire the form's `formSubmit` event natively — the host listens for it via `(formSubmit)` (Angular), `@formSubmit` (Vue), `onFormSubmit` (React), or the `form-submit` event (Lit). No custom handler needed. Use this for the primary submit button on a form.",
+    '`actionType: "button"` (the default, can be omitted) is a regular action button. Wire it via `on.click: "<handlerName>"` where `<handlerName>` is registered in the form config\'s event handlers.',
+    'Supports state-suffixed props: `"label.<stateName>"` and `"disabled.<stateName>"` swap the label or disabled state when a named state is active — e.g. disable the submit button until terms are accepted, then re-enable it. Call `get_concept({ concept: "states" })` for the full pattern.'
+  ],
+  checkbox: ["Set `validator.const: true` to require the user to tick it (e.g. terms acceptance)."],
+  alert: [
+    'Use `include: { in: ["stateName"] }` to show this alert only when a named state is active, or `exclude: { from: ["stateName"] }` to hide it when a state is active. This is cleaner than `include: { when: "..." }` when the same condition is reused across multiple widgets. Call `get_concept({ concept: "states" })` for the full states pattern.',
+    'Props inside `props` (e.g. `text`, `level`) accept state suffixes: `"text.<stateName>": "New message"` swaps the message when that state is active.'
+  ]
+};
+function synthesizeExample(widgetType, schema) {
+  const props = schema["properties"];
+  const kindProp = props?.["kind"]?.const ?? "input";
+  const ex = { kind: kindProp, type: widgetType };
+  if (props?.["path"]) ex["path"] = "field";
+  if (props?.["label"]) ex["label"] = "Field";
+  return ex;
 }
-function resolveLocalRef(ref, doc) {
-  if (!ref.startsWith("#/")) return null;
-  const parts = ref.slice(2).split("/");
-  let cur = doc;
-  for (const p of parts) {
-    if (cur && typeof cur === "object") {
-      cur = cur[p];
-    } else {
-      return null;
-    }
+function getWidgetSpec(input) {
+  const schema = COMPONENT_SCHEMAS[input.widgetType];
+  if (!schema) {
+    const known = Object.keys(COMPONENT_SCHEMAS).sort().join(", ");
+    throw new Error(`Unknown widget type \`${input.widgetType}\`. Known: ${known}.`);
   }
-  return cur ?? null;
+  const props = schema["properties"];
+  const kindProp = props?.["kind"]?.const ?? "unknown";
+  return {
+    widgetType: input.widgetType,
+    schema,
+    kind: kindProp,
+    example: EXAMPLES[input.widgetType] ?? synthesizeExample(input.widgetType, schema),
+    notes: NOTES[input.widgetType] ?? []
+  };
 }
-const GENERATE_FROM_OPENAPI_TOOL = {
-  name: "generate_from_openapi",
-  description: 'Generate a GolemUI form for a specific OpenAPI 3.x operation (e.g. "POST /users"). Resolves the operation\'s JSON request body, dereferences `$ref`s, then maps it to a form definition that is validated against the GolemUI JSON Schemas before being returned, so it is guaranteed syntactically correct. Falls back to operation parameters when no request body is present. Anything the mapper cannot handle is reported in `unmapped` rather than silently dropped — use that list to surface remaining work to the user. Pass either a parsed `document` or a `documentUrl` to fetch.',
+const GET_WIDGET_SPEC_TOOL = {
+  name: "get_widget_spec",
+  description: "Look up the JSON Schema and a minimal working example for a single GolemUI widget. Use this when you need to know which `props` a widget accepts, what `kind` value it uses, or what shape its `validator` takes. Cheaper than dumping the whole API into context.",
   inputSchema: {
     type: "object",
     properties: {
-      documentUrl: {
-        type: "string",
-        description: "URL of a JSON OpenAPI document. Either this or `document` is required."
-      },
-      document: {
-        type: "object",
-        additionalProperties: true,
-        description: "Parsed OpenAPI document (JSON object). Either this or `documentUrl` is required."
-      },
-      operation: {
-        type: "string",
-        description: 'The operation to generate a form for. Either "METHOD /path" (e.g. "POST /users") or an exact operationId.'
-      },
-      submitAction: {
-        type: "boolean",
-        description: "Append a submit button. Defaults to true."
-      },
-      submitLabel: {
+      widgetType: {
         type: "string",
-        description: "Label for the submit button. Defaults to the operation summary or a verb derived from the HTTP method."
+        description: "The widget `type` constant. One of: " + Object.keys(COMPONENT_SCHEMAS).sort().map((t) => `\`${t}\``).join(", ") + "."
       }
     },
-    required: ["operation"]
+    required: ["widgetType"]
   }
 };
 const STATES_CONCEPT = {
@@ -2026,152 +2321,28 @@ const STATES_CONCEPT = {
             kind: "display",
             type: "alert",
             props: {
-              level: "warning",
-              text: "Please accept the terms to continue.",
-              "text.termsAccepted": "Ready to submit!"
-            },
-            exclude: { from: ["busy"] }
-          },
-          {
-            kind: "input",
-            type: "repeater",
-            path: "users",
-            label: "Users",
-            addLabel: "Add user",
-            "addLabel.limitReached": "Limit reached — can't add more",
-            props: {
-              removeLabel: "Remove",
-              template: {
-                kind: "layout",
-                type: "flex",
-                props: { direction: "column" },
-                children: [
-                  { kind: "input", type: "textinput", path: "users.items.name", label: "Name" }
-                ]
-              }
-            }
-          }
-        ]
-      }
-    }
-  ],
-  rules: [
-    'Every state name used in `include.in`, `exclude.from`, or as a property suffix MUST be declared in the root `"states"` map.',
-    "Child state expressions must contain only the *additional* (incremental) condition — ancestor conditions are ANDed in automatically by the runtime. Duplicating a parent condition in a child expression is wrong and redundant.",
-    'A sub-state is only ever active when all of its ancestor states are also active. When using `include.in: ["register:adult"]` you do NOT need to also add `"register"` to the array.',
-    "State-suffixed root props — only these support suffixes at the widget root level: `label`, `disabled`, `readonly`, `validator`, `size`. All other overridable properties live inside `props`.",
-    'State-suffixed props inside `props` — any key inside the `props` object can be suffixed: `"hint.<state>"`, `"placeholder.<state>"`, `"items.<state>"`, `"addLabel.<state>"`, etc.',
-    'Suffix names must not contain dots (the dot is the separator between property and state name): `"label.myState"` ✅, `"label.register:adult"` ✅ — `"label.my.state"` ❌.',
-    'Reactive expressions must reference `$form`, `$meta`, or `$formIsInvalid`. A bare identifier like `termsAccepted` without a root reference is invalid. `$formIsInvalid` is a built-in boolean (no property chain — use it as-is: `disabled: { when: "$formIsInvalid" }` or inside a state expression: `states: { formInvalid: "$formIsInvalid" }`).',
-    "Use `===` / `!==` for equality, `&&` / `||` for logic. Avoid `=` (assignment), `==`/`!=` (loose equality), or bitwise `&`/`|`.",
-    'When multiple states are active at the same time and a property has more than one matching suffix, the longest state name wins (most specific takes priority). Example: if both `register` and `register:adult` are active, `"label.register:adult"` overrides `"label.register"`.',
-    "The `include.when` / `exclude.when` inline form is an alternative to named states for one-off conditions, but it cannot replace state-suffixed props — those require a named state.",
-    '`include.in` and `exclude.from` each accept an Array of state names. A widget included `in: ["a", "b"]` renders when state `a` OR state `b` is active.',
-    "Use optional chaining (`?.`) when accessing nested fields that may not yet exist in the form data: `$form.user?.age >= 18` not `$form.user.age >= 18`."
-  ]
-};
-const STRING_INTERPOLATION_CONCEPT = {
-  concept: "string-interpolation",
-  summary: "GolemUI supports live data binding in text props via `{{expression}}` template slots. Any string-valued property (e.g. `props.text`, `props.hint`, `label`) can embed one or more `{{...}}` slots. Each slot is a JavaScript-like expression evaluated against the live form state using a safe subset of JavaScript (no side effects, no function calls). i18n translation `params` objects accept a matching bare-expression format — the same expressions but without the `{{}}` delimiters.",
-  patterns: [
-    {
-      name: "Template slots in display text",
-      description: "Embed `{{expression}}` in any string prop to inject live values. Available scopes: `$form` (all current field values), `$meta` (host-supplied metadata), `$errors` (current validation error messages keyed by field uid), `$formIsInvalid` (boolean — `true` when any field currently fails validation). Use optional chaining (`?.`) when accessing nested fields that may not yet exist. Multiple slots can appear in a single string.",
-      example: {
-        $schema: "https://golemui.com/schemas/form.schema.json",
-        form: [
-          {
-            uid: "userName",
-            kind: "input",
-            type: "textinput",
-            path: "userName",
-            validator: { type: "string", required: true }
-          },
-          {
-            uid: "submitBtn",
-            kind: "action",
-            type: "button",
-            label: "Submit",
-            actionType: "submit"
-          },
-          {
-            uid: "greeting",
-            kind: "display",
-            type: "alert",
-            props: { text: "Hello {{$form.userName}}" }
-          },
-          {
-            uid: "status",
-            kind: "display",
-            type: "alert",
-            props: {
-              text: "Error: {{$errors.userName}} | Form invalid: {{$formIsInvalid}}"
-            }
-          },
-          {
-            uid: "meta-info",
-            kind: "display",
-            type: "alert",
-            props: { text: "Connected as {{$meta.role}} on {{$meta.server}}" }
-          }
-        ]
-      }
-    },
-    {
-      name: "Expressions in slots",
-      description: "Slots support full JavaScript-like expressions: arithmetic, string concatenation, ternary conditionals, and optional chaining. The expression is evaluated against the same scope object (`$form`, `$meta`, `$errors`, `$formIsInvalid`). If the expression evaluates to `null` or `undefined`, the slot renders as an empty string.",
-      example: {
-        $schema: "https://golemui.com/schemas/form.schema.json",
-        data: { firstName: "Jane", lastName: "Doe", count: 4, role: "admin" },
-        form: [
-          {
-            uid: "full-name",
-            kind: "display",
-            type: "alert",
-            props: { text: "Full name: {{$form.firstName + ' ' + $form.lastName}}" }
-          },
-          {
-            uid: "next-count",
-            kind: "display",
-            type: "alert",
-            props: { text: "Next item: {{$form.count + 1}}" }
-          },
-          {
-            uid: "role-label",
-            kind: "display",
-            type: "alert",
-            props: { text: "Role: {{$form.role === 'admin' ? 'Administrator' : 'User'}}" }
-          },
-          {
-            uid: "nested",
-            kind: "display",
-            type: "alert",
-            props: { text: "City: {{$form.address?.city}}" }
-          }
-        ]
-      }
-    },
-    {
-      name: "i18n param expressions",
-      description: "When using i18n translations, `params` values support the same expression language as `{{}}` slots, but as **bare expressions** without the `{{}}` delimiters. Params that start with a `$` scope prefix are evaluated; others are passed as static strings. The expression has access to `$form`, `$meta`, `$errors`, and `$formIsInvalid`.",
-      example: {
-        $schema: "https://golemui.com/schemas/form.schema.json",
-        data: { firstName: "Jane", lastName: "Doe", count: 4 },
-        meta: { connectionStatus: "online" },
-        form: [
-          {
-            uid: "greeting",
-            kind: "display",
-            type: "alert",
-            props: {
-              text: {
-                key: "user.greeting",
-                params: {
-                  hello: "Hola",
-                  fullName: "$form.firstName + ' ' + $form.lastName",
-                  n: "$form.count + 1",
-                  status: "$meta.connectionStatus"
-                }
+              level: "warning",
+              text: "Please accept the terms to continue.",
+              "text.termsAccepted": "Ready to submit!"
+            },
+            exclude: { from: ["busy"] }
+          },
+          {
+            kind: "input",
+            type: "repeater",
+            path: "users",
+            label: "Users",
+            addLabel: "Add user",
+            "addLabel.limitReached": "Limit reached — can't add more",
+            props: {
+              removeLabel: "Remove",
+              template: {
+                kind: "layout",
+                type: "flex",
+                props: { direction: "column" },
+                children: [
+                  { kind: "input", type: "textinput", path: "users.items.name", label: "Name" }
+                ]
               }
             }
           }
@@ -2180,413 +2351,179 @@ const STRING_INTERPOLATION_CONCEPT = {
     }
   ],
   rules: [
-    "Slots must reference at least one of `$form`, `$meta`, `$errors`, or `$formIsInvalid`. A bare identifier without a scope prefix is invalid inside `{{}}`: use `{{$form.name}}` not `{{name}}`.",
-    "`$formIsInvalid` is a built-in boolean — use it as-is: `{{$formIsInvalid}}`. Do not chain properties onto it.",
-    "If an expression evaluates to `null` or `undefined`, the slot renders as an empty string in display text.",
-    "Use optional chaining (`?.`) when accessing nested fields that may not yet exist: `{{$form.address?.city}}` not `{{$form.address.city}}`.",
-    "Do not use assignment `=` inside a slot — slots are read-only. Use `===` for equality checks.",
-    "Slots cannot be nested: `{{$form.a {{$form.b}}}}` is invalid.",
-    "Every `{{` must have a matching `}}`. Unbalanced delimiters cause a lint warning.",
-    'i18n `params` values are bare expressions — do NOT wrap them in `{{}}`. Write `"$form.name"` not `"{{$form.name}}"`.',
-    'Static string params (not starting with `$`) are passed through as-is — use them for constant values like `"Hola"` or `"px"`.',
-    "Supported operators in expressions: arithmetic (`+`, `-`, `*`, `/`, `%`), comparison (`===`, `!==`, `<`, `>`, `<=`, `>=`), logical (`&&`, `||`, `!`), ternary (`? :`), optional chaining (`?.`), nullish coalescing (`??`).",
-    "Expressions are evaluated using a safe subset of JavaScript — no `eval`, no function calls, no side effects."
+    'Every state name used in `include.in`, `exclude.from`, or as a property suffix MUST be declared in the root `"states"` map.',
+    "Child state expressions must contain only the *additional* (incremental) condition — ancestor conditions are ANDed in automatically by the runtime. Duplicating a parent condition in a child expression is wrong and redundant.",
+    'A sub-state is only ever active when all of its ancestor states are also active. When using `include.in: ["register:adult"]` you do NOT need to also add `"register"` to the array.',
+    "State-suffixed root props — only these support suffixes at the widget root level: `label`, `disabled`, `readonly`, `validator`, `size`. All other overridable properties live inside `props`.",
+    'State-suffixed props inside `props` — any key inside the `props` object can be suffixed: `"hint.<state>"`, `"placeholder.<state>"`, `"items.<state>"`, `"addLabel.<state>"`, etc.',
+    'Suffix names must not contain dots (the dot is the separator between property and state name): `"label.myState"` ✅, `"label.register:adult"` ✅ — `"label.my.state"` ❌.',
+    'Reactive expressions must reference `$form`, `$meta`, or `$formIsInvalid`. A bare identifier like `termsAccepted` without a root reference is invalid. `$formIsInvalid` is a built-in boolean (no property chain — use it as-is: `disabled: { when: "$formIsInvalid" }` or inside a state expression: `states: { formInvalid: "$formIsInvalid" }`).',
+    "Use `===` / `!==` for equality, `&&` / `||` for logic. Avoid `=` (assignment), `==`/`!=` (loose equality), or bitwise `&`/`|`.",
+    'When multiple states are active at the same time and a property has more than one matching suffix, the longest state name wins (most specific takes priority). Example: if both `register` and `register:adult` are active, `"label.register:adult"` overrides `"label.register"`.',
+    "The `include.when` / `exclude.when` inline form is an alternative to named states for one-off conditions, but it cannot replace state-suffixed props — those require a named state.",
+    '`include.in` and `exclude.from` each accept an Array of state names. A widget included `in: ["a", "b"]` renders when state `a` OR state `b` is active.',
+    "Use optional chaining (`?.`) when accessing nested fields that may not yet exist in the form data: `$form.user?.age >= 18` not `$form.user.age >= 18`."
   ]
 };
-const CONCEPTS = {
-  states: STATES_CONCEPT,
-  "string-interpolation": STRING_INTERPOLATION_CONCEPT
-};
-function getConcept(input) {
-  const result = CONCEPTS[input.concept];
-  if (!result) {
-    const known = Object.keys(CONCEPTS).sort().map((c) => `\`${c}\``).join(", ");
-    throw new Error(`Unknown concept \`${input.concept}\`. Known concepts: ${known}.`);
-  }
-  return result;
-}
-const GET_CONCEPT_TOOL = {
-  name: "get_concept",
-  description: 'Return a detailed guide for a cross-cutting GolemUI form concept — things that span multiple widgets and affect the whole form, rather than the API of a single widget. Call this when you need to: (1) change a widget\'s props based on form state (state-suffixed props like `"label.stateName": "…"`), or (2) reuse the same condition across multiple widgets (`include: { in: […] }` / `exclude: { from: […] }`). For a one-off show/hide on a single widget, use `include: { when: "…" }` or `exclude: { when: "…" }` directly — no states needed, no need to call this tool. Currently supported concepts: `states`, `string-interpolation`.',
-  inputSchema: {
-    type: "object",
-    properties: {
-      concept: {
-        type: "string",
-        description: 'The concept to explain. Currently supported: `"states"`, `"string-interpolation"`.',
-        enum: Object.keys(CONCEPTS)
-      }
-    },
-    required: ["concept"]
-  }
-};
-const EXAMPLES = {
-  accordion: {
-    kind: "layout",
-    type: "accordion",
-    props: {
-      sections: [
-        { uid: "personal", label: "Personal" },
-        { uid: "preferences", label: "Preferences" }
-      ]
-    },
-    children: [
-      { kind: "input", type: "textinput", path: "firstName", label: "First name" },
-      { kind: "input", type: "checkbox", path: "newsletter", label: "Newsletter" }
-    ]
-  },
-  textinput: {
-    kind: "input",
-    type: "textinput",
-    path: "firstName",
-    label: "First name",
-    validator: { type: "string", required: true, minLength: 1 },
-    props: { placeholder: "Jane" }
-  },
-  textarea: {
-    kind: "input",
-    type: "textarea",
-    path: "bio",
-    label: "Bio",
-    props: { minimumHeight: 120, autoGrow: true }
-  },
-  tags: {
-    kind: "input",
-    type: "tags",
-    path: "keywords",
-    label: "Keywords",
-    defaultValue: [],
-    props: {
-      placeholder: "Add a keyword and press Enter",
-      separators: ["Enter", ","],
-      trim: true,
-      allowDuplicates: false,
-      limit: 10
-    },
-    validator: {
-      type: "array",
-      minItems: 1,
-      maxItems: 10
-    }
-  },
-  password: {
-    kind: "input",
-    type: "password",
-    path: "password",
-    label: "Password",
-    validator: { type: "string", required: true, minLength: 8 }
-  },
-  number: {
-    kind: "input",
-    type: "number",
-    path: "age",
-    label: "Age",
-    validator: { type: "integer", required: true, minimum: 0 }
-  },
-  currency: {
-    kind: "input",
-    type: "currency",
-    path: "salary",
-    label: "Salary",
-    props: { currency: "USD" }
-  },
-  checkbox: {
-    kind: "input",
-    type: "checkbox",
-    path: "termsAccepted",
-    label: "I accept the terms",
-    validator: { type: "boolean", required: true, const: true }
-  },
-  toggle: {
-    kind: "input",
-    type: "toggle",
-    path: "notifications",
-    label: "Email notifications"
-  },
-  dropdown: {
-    kind: "input",
-    type: "dropdown",
-    path: "country",
-    label: "Country",
-    props: {
-      labelField: "label",
-      valueField: "value",
-      items: [
-        { label: "United States", value: "us", flag: "🇺🇸" },
-        { label: "Canada", value: "ca", flag: "🇨🇦" }
-      ]
-    }
-  },
-  select: {
-    kind: "input",
-    type: "select",
-    path: "plan",
-    label: "Plan",
-    props: {
-      options: [
-        { label: "Free", value: "free" },
-        { label: "Pro", value: "pro" }
-      ]
-    }
-  },
-  radiogroup: {
-    kind: "input",
-    type: "radiogroup",
-    path: "shippingSpeed",
-    label: "Shipping",
-    props: {
-      options: [
-        { label: "Standard", value: "standard" },
-        { label: "Express", value: "express" }
-      ]
-    }
-  },
-  dateInput: {
-    kind: "input",
-    type: "dateInput",
-    path: "birthDate",
-    label: "Birth date"
-  },
-  datePicker: {
-    kind: "input",
-    type: "datePicker",
-    path: "startDate",
-    label: "Start date"
-  },
-  calendar: {
-    kind: "input",
-    type: "calendar",
-    path: "eventDate",
-    label: "Event date"
-  },
-  button: {
-    kind: "action",
-    type: "button",
-    actionType: "submit",
-    label: "Submit",
-    props: { variant: "filled" }
-  },
-  alert: {
-    kind: "display",
-    type: "alert",
-    props: { level: "info", text: "Heads up!" }
-  },
-  markdownText: {
-    kind: "display",
-    type: "markdownText",
-    props: { md: "Welcome to the form." }
-  },
-  flex: {
-    kind: "layout",
-    type: "flex",
-    props: { direction: "column", gap: 12 },
-    children: [
-      {
-        kind: "input",
-        type: "textinput",
-        path: "firstName",
-        label: "First name"
+const STRING_INTERPOLATION_CONCEPT = {
+  concept: "string-interpolation",
+  summary: "GolemUI supports live data binding in text props via `{{expression}}` template slots. Any string-valued property (e.g. `props.text`, `props.hint`, `label`) can embed one or more `{{...}}` slots. Each slot is a JavaScript-like expression evaluated against the live form state using a safe subset of JavaScript (no side effects, no function calls). i18n translation `params` objects accept a matching bare-expression format — the same expressions but without the `{{}}` delimiters.",
+  patterns: [
+    {
+      name: "Template slots in display text",
+      description: "Embed `{{expression}}` in any string prop to inject live values. Available scopes: `$form` (all current field values), `$meta` (host-supplied metadata), `$errors` (current validation error messages keyed by field uid), `$formIsInvalid` (boolean — `true` when any field currently fails validation). Use optional chaining (`?.`) when accessing nested fields that may not yet exist. Multiple slots can appear in a single string.",
+      example: {
+        $schema: "https://golemui.com/schemas/form.schema.json",
+        form: [
+          {
+            uid: "userName",
+            kind: "input",
+            type: "textinput",
+            path: "userName",
+            validator: { type: "string", required: true }
+          },
+          {
+            uid: "submitBtn",
+            kind: "action",
+            type: "button",
+            label: "Submit",
+            actionType: "submit"
+          },
+          {
+            uid: "greeting",
+            kind: "display",
+            type: "alert",
+            props: { text: "Hello {{$form.userName}}" }
+          },
+          {
+            uid: "status",
+            kind: "display",
+            type: "alert",
+            props: {
+              text: "Error: {{$errors.userName}} | Form invalid: {{$formIsInvalid}}"
+            }
+          },
+          {
+            uid: "meta-info",
+            kind: "display",
+            type: "alert",
+            props: { text: "Connected as {{$meta.role}} on {{$meta.server}}" }
+          }
+        ]
       }
-    ]
-  },
-  grid: {
-    kind: "layout",
-    type: "grid",
-    props: { columnGap: 12, rowGap: 12 },
-    children: [
-      { kind: "input", type: "textinput", path: "firstName", label: "First name" },
-      { kind: "input", type: "textinput", path: "lastName", label: "Last name" }
-    ]
-  },
-  tabs: {
-    kind: "layout",
-    type: "tabs",
-    props: {
-      tabs: [
-        { uid: "personal", label: "Personal" },
-        { uid: "address", label: "Address" }
-      ]
     },
-    children: [
-      { kind: "input", type: "textinput", path: "firstName", label: "First name" },
-      { kind: "input", type: "textinput", path: "street", label: "Street" }
-    ]
-  },
-  repeater: {
-    kind: "input",
-    type: "repeater",
-    path: "addresses",
-    label: "Addresses",
-    props: {
-      addLabel: "Add address",
-      removeLabel: "Remove",
-      template: {
-        kind: "layout",
-        type: "flex",
-        props: { direction: "column" },
-        children: [
-          // Child paths inside a repeater template MUST be `<repeater.path>.items.<field>` —
-          // `items` is the reserved segment that the runtime expands per array entry.
-          { kind: "input", type: "textinput", path: "addresses.items.street", label: "Street" },
-          { kind: "input", type: "textinput", path: "addresses.items.city", label: "City" }
+    {
+      name: "Expressions in slots",
+      description: "Slots support full JavaScript-like expressions: arithmetic, string concatenation, ternary conditionals, and optional chaining. The expression is evaluated against the same scope object (`$form`, `$meta`, `$errors`, `$formIsInvalid`). If the expression evaluates to `null` or `undefined`, the slot renders as an empty string.",
+      example: {
+        $schema: "https://golemui.com/schemas/form.schema.json",
+        data: { firstName: "Jane", lastName: "Doe", count: 4, role: "admin" },
+        form: [
+          {
+            uid: "full-name",
+            kind: "display",
+            type: "alert",
+            props: { text: "Full name: {{$form.firstName + ' ' + $form.lastName}}" }
+          },
+          {
+            uid: "next-count",
+            kind: "display",
+            type: "alert",
+            props: { text: "Next item: {{$form.count + 1}}" }
+          },
+          {
+            uid: "role-label",
+            kind: "display",
+            type: "alert",
+            props: { text: "Role: {{$form.role === 'admin' ? 'Administrator' : 'User'}}" }
+          },
+          {
+            uid: "nested",
+            kind: "display",
+            type: "alert",
+            props: { text: "City: {{$form.address?.city}}" }
+          }
+        ]
+      }
+    },
+    {
+      name: "i18n param expressions",
+      description: "When using i18n translations, `params` values support the same expression language as `{{}}` slots, but as **bare expressions** without the `{{}}` delimiters. Params that start with a `$` scope prefix are evaluated; others are passed as static strings. The expression has access to `$form`, `$meta`, `$errors`, and `$formIsInvalid`.",
+      example: {
+        $schema: "https://golemui.com/schemas/form.schema.json",
+        data: { firstName: "Jane", lastName: "Doe", count: 4 },
+        meta: { connectionStatus: "online" },
+        form: [
+          {
+            uid: "greeting",
+            kind: "display",
+            type: "alert",
+            props: {
+              text: {
+                key: "user.greeting",
+                params: {
+                  hello: "Hola",
+                  fullName: "$form.firstName + ' ' + $form.lastName",
+                  n: "$form.count + 1",
+                  status: "$meta.connectionStatus"
+                }
+              }
+            }
+          }
         ]
       }
     }
-  }
-};
-const NOTES = {
-  textinput: [
-    "`path` is the dot-path into form data this field writes to.",
-    "`validator.format` supports: `email`, `hostname`, `ipv4`, `ipv6`, `url`, `uuid`, `date`, `time`, `date-time`, `duration`.",
-    'Root props `label`, `disabled`, `readonly`, `validator`, and `size` accept state suffixes — e.g. `"label.<stateName>": "New label"` overrides the label only when that named state is active. Props inside `props` (e.g. `hint`, `placeholder`) also accept suffixes as `"hint.<stateName>"`. Call `get_concept({ concept: "states" })` for the full pattern.'
-  ],
-  markdownText: [
-    "Display-only widget for rendering markdown. Can be used as a top-level form widget (inside any layout) or inside templates like `dropdown.props.items[].template`.",
-    "The required prop is `md` (the markdown string), not `text`."
-  ],
-  tags: [
-    "Use `tags` for free-form arrays of primitive values (typically `string[]`) — e.g. keywords, email lists, hashtags. Backing data is `string[]`. For arrays of structured objects, use `repeater` instead.",
-    '`props.separators` controls which keys/characters commit a new tag. Defaults emit on `Enter` and `,`; you can also include `"Tab"` or `"blur"`. `props.trim` strips whitespace from each tag; `props.allowDuplicates: false` rejects repeats; `props.limit` caps the array length.',
-    'Validate with an `arrayValidator`: `{ type: "array", minItems, maxItems, uniqueItems }`. The `tags` widget complements that with UI-level enforcement (`allowDuplicates`, `limit`) but the validator is still authoritative for form-level required/min/max constraints.'
-  ],
-  dropdown: [
-    "PREFER `select` for plain label/value lists (countries, plans, sizes). `dropdown` is for richer item shapes: when each item has extra fields (icons, flags, metadata) that an `itemRenderer` or `labelField`/`valueField` can use.",
-    '`props.items` is EITHER primitives `["one", 2, ...]` OR arbitrary objects `[{ label, value, ...extras }]`. Pair the object form with `labelField`/`valueField` to tell the dropdown which fields to render as label and which to use as the value. **Widget templates inside items (the `{template, value}` shape) are NOT supported — only `repeater` accepts widget templates.**'
-  ],
-  select: [
-    '`props.options[]` is the simple form: `[{ label: "United States", value: "us" }, ...]`. Use this for ANY plain text list — countries, plans, sizes, status enums. Only switch to `dropdown` if you need custom per-item rendering (icons, flags, rich layouts).',
-    "For very large lists (>50 items) consider `dropdown` for its virtualization (`height`, `itemHeight`, `searchFields`)."
-  ],
-  flex: ["`children` is an array of any widgets (inputs, displays, nested layouts)."],
-  grid: ["`children` is an array of any widgets. `props.columns` controls layout."],
-  tabs: [
-    "Children are associated with tabs by **`uid` matching**, not by array order: each direct child must have a `uid` field at the widget level (alongside `kind`/`type`) whose string value equals one of the `props.tabs[].uid` entries. There is no `tag` property — that is not a real GolemUI field.",
-    "Children are typically written in display order for readability, but rearranging them does not change which tab they belong to — only the `uid` string match does."
-  ],
-  accordion: [
-    "Children are associated with sections by **`uid` matching** (same pattern as `tabs`): each direct child must have a `uid` field at the widget level whose value equals one of the `props.sections[].uid` entries. There is no `tag` property.",
-    "`props.defaultOpen` is a map of `{ <sectionUid>: boolean }` controlling which sections start expanded."
-  ],
-  repeater: [
-    "`props.template` must be a layout widget (flex/grid/tabs/accordion) whose children are the per-item fields.",
-    'Child paths inside the template MUST follow the form `<repeater.path>.items.<fieldName>`. The `items` segment is reserved — the runtime substitutes it with the current array index per row. For example, a repeater at `path: "users"` with a child `firstName` uses `path: "users.items.firstName"`. Plain `firstName` will NOT bind to the array.',
-    'Nested repeaters chain the convention: a repeater at `path: "teams"` whose template contains a repeater at `path: "teams.items.members"` whose children use `path: "teams.items.members.items.<field>"`.',
-    '`addLabel` supports state suffixes: `"addLabel.<stateName>": "Limit reached"` swaps the add-button label when a named state is active — useful for capping array length. Call `get_concept({ concept: "states" })` for the full pattern.'
-  ],
-  button: [
-    "`actionType` controls the button's role. `actionType: \"submit\"` makes the button fire the form's `formSubmit` event natively — the host listens for it via `(formSubmit)` (Angular), `@formSubmit` (Vue), `onFormSubmit` (React), or the `form-submit` event (Lit). No custom handler needed. Use this for the primary submit button on a form.",
-    '`actionType: "button"` (the default, can be omitted) is a regular action button. Wire it via `on.click: "<handlerName>"` where `<handlerName>` is registered in the form config\'s event handlers.',
-    'Supports state-suffixed props: `"label.<stateName>"` and `"disabled.<stateName>"` swap the label or disabled state when a named state is active — e.g. disable the submit button until terms are accepted, then re-enable it. Call `get_concept({ concept: "states" })` for the full pattern.'
   ],
-  checkbox: ["Set `validator.const: true` to require the user to tick it (e.g. terms acceptance)."],
-  alert: [
-    'Use `include: { in: ["stateName"] }` to show this alert only when a named state is active, or `exclude: { from: ["stateName"] }` to hide it when a state is active. This is cleaner than `include: { when: "..." }` when the same condition is reused across multiple widgets. Call `get_concept({ concept: "states" })` for the full states pattern.',
-    'Props inside `props` (e.g. `text`, `level`) accept state suffixes: `"text.<stateName>": "New message"` swaps the message when that state is active.'
+  rules: [
+    "Slots must reference at least one of `$form`, `$meta`, `$errors`, or `$formIsInvalid`. A bare identifier without a scope prefix is invalid inside `{{}}`: use `{{$form.name}}` not `{{name}}`.",
+    "`$formIsInvalid` is a built-in boolean — use it as-is: `{{$formIsInvalid}}`. Do not chain properties onto it.",
+    "If an expression evaluates to `null` or `undefined`, the slot renders as an empty string in display text.",
+    "Use optional chaining (`?.`) when accessing nested fields that may not yet exist: `{{$form.address?.city}}` not `{{$form.address.city}}`.",
+    "Do not use assignment `=` inside a slot — slots are read-only. Use `===` for equality checks.",
+    "Slots cannot be nested: `{{$form.a {{$form.b}}}}` is invalid.",
+    "Every `{{` must have a matching `}}`. Unbalanced delimiters cause a lint warning.",
+    'i18n `params` values are bare expressions — do NOT wrap them in `{{}}`. Write `"$form.name"` not `"{{$form.name}}"`.',
+    'Static string params (not starting with `$`) are passed through as-is — use them for constant values like `"Hola"` or `"px"`.',
+    "Supported operators in expressions: arithmetic (`+`, `-`, `*`, `/`, `%`), comparison (`===`, `!==`, `<`, `>`, `<=`, `>=`), logical (`&&`, `||`, `!`), ternary (`? :`), optional chaining (`?.`), nullish coalescing (`??`).",
+    "Expressions are evaluated using a safe subset of JavaScript — no `eval`, no function calls, no side effects."
   ]
 };
-function synthesizeExample(widgetType, schema) {
-  const props = schema["properties"];
-  const kindProp = props?.["kind"]?.const ?? "input";
-  const ex = { kind: kindProp, type: widgetType };
-  if (props?.["path"]) ex["path"] = "field";
-  if (props?.["label"]) ex["label"] = "Field";
-  return ex;
-}
-function getWidgetSpec(input) {
-  const schema = COMPONENT_SCHEMAS[input.widgetType];
-  if (!schema) {
-    const known = Object.keys(COMPONENT_SCHEMAS).sort().join(", ");
-    throw new Error(`Unknown widget type \`${input.widgetType}\`. Known: ${known}.`);
+const CONCEPTS = {
+  states: STATES_CONCEPT,
+  "string-interpolation": STRING_INTERPOLATION_CONCEPT
+};
+function getConcept(input) {
+  const result = CONCEPTS[input.concept];
+  if (!result) {
+    const known = Object.keys(CONCEPTS).sort().map((c) => `\`${c}\``).join(", ");
+    throw new Error(`Unknown concept \`${input.concept}\`. Known concepts: ${known}.`);
   }
-  const props = schema["properties"];
-  const kindProp = props?.["kind"]?.const ?? "unknown";
-  return {
-    widgetType: input.widgetType,
-    schema,
-    kind: kindProp,
-    example: EXAMPLES[input.widgetType] ?? synthesizeExample(input.widgetType, schema),
-    notes: NOTES[input.widgetType] ?? []
-  };
+  return result;
 }
-const GET_WIDGET_SPEC_TOOL = {
-  name: "get_widget_spec",
-  description: "Look up the JSON Schema and a minimal working example for a single GolemUI widget. Use this when you need to know which `props` a widget accepts, what `kind` value it uses, or what shape its `validator` takes. Cheaper than dumping the whole API into context.",
+const GET_CONCEPT_TOOL = {
+  name: "get_concept",
+  description: 'Return a detailed guide for a cross-cutting GolemUI form concept — things that span multiple widgets and affect the whole form, rather than the API of a single widget. Call this when you need to: (1) change a widget\'s props based on form state (state-suffixed props like `"label.stateName": "…"`), or (2) reuse the same condition across multiple widgets (`include: { in: […] }` / `exclude: { from: […] }`). For a one-off show/hide on a single widget, use `include: { when: "…" }` or `exclude: { when: "…" }` directly — no states needed, no need to call this tool. Currently supported concepts: `states`, `string-interpolation`.',
   inputSchema: {
     type: "object",
     properties: {
-      widgetType: {
+      concept: {
         type: "string",
-        description: "The widget `type` constant. One of: " + Object.keys(COMPONENT_SCHEMAS).sort().map((t) => `\`${t}\``).join(", ") + "."
+        description: 'The concept to explain. Currently supported: `"states"`, `"string-interpolation"`.',
+        enum: Object.keys(CONCEPTS)
       }
     },
-    required: ["widgetType"]
+    required: ["concept"]
   }
 };
-function readPackageMeta() {
-  const here = dirname(fileURLToPath(import.meta.url));
-  for (const candidate of [join(here, "package.json"), join(here, "..", "package.json")]) {
-    try {
-      const pkg = JSON.parse(readFileSync(candidate, "utf-8"));
-      if (pkg.name && pkg.version) return { name: pkg.name, version: pkg.version };
-    } catch {
-    }
-  }
-  return { name: "@golemui/gui-mcp", version: "0.0.0" };
-}
-const { name: PKG_NAME, version: PKG_VERSION } = readPackageMeta();
-const TOOLS = [
-  VALIDATE_FORM_DEFINITION_TOOL,
-  GENERATE_FROM_JSON_SCHEMA_TOOL,
-  GENERATE_FROM_OPENAPI_TOOL,
-  GET_WIDGET_SPEC_TOOL,
-  GET_CONCEPT_TOOL
-];
-const SERVER_INSTRUCTIONS = 'This server builds and validates GolemUI form definitions — declarative, JSON-serializable forms shaped as `{ form: [...widgets], states?: {...} }`. Its job is to help you produce a form definition that is guaranteed correct before the user pastes it into their codebase.\n\nRecommended workflow:\n1. Starting from an existing schema? Use a generator — both return a pre-validated definition, so check the returned `unmapped` list and surface anything left over to the user. For a raw JSON Schema (e.g. an API request body), call `generate_from_json_schema`. For an OpenAPI 3.x spec, call `generate_from_openapi`: pass `operation` as "METHOD /path" (e.g. "POST /users") or an exact operationId, plus the spec as a parsed `document` or a `documentUrl` to fetch — it resolves the operation\'s request body, dereferences `$ref`s, and falls back to the operation\'s parameters when there is no request body.\n2. Building or editing by hand? Look up a single widget with `get_widget_spec` (its `kind`, `props`, and `validator` shape), and cross-cutting behavior that spans widgets — conditional rendering, per-state prop overrides — with `get_concept`.\n3. ALWAYS finish by calling `validate_form_definition`. It checks the definition against the bundled JSON Schemas and returns `{ valid, errors, warnings, expressionWarnings }`. Treat `errors` as blocking: fix them and re-validate until `valid` is true. `warnings` (likely-custom widgets) and `expressionWarnings` (linted reactive expressions) are advisory — surface them, but they do not flip `valid`.\n\nDo not hand a form definition to the user until `validate_form_definition` reports `valid: true`.';
-const server = new Server(
-  { name: PKG_NAME, version: PKG_VERSION },
-  { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS }
-);
-server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-  const { name, arguments: args } = request.params;
-  try {
-    switch (name) {
-      case "validate_form_definition":
-        return ok(validateFormDefinition(args));
-      case "generate_from_json_schema":
-        return ok(generateFromJsonSchema(args));
-      case "generate_from_openapi":
-        return ok(await generateFromOpenapi(args));
-      case "get_widget_spec":
-        return ok(getWidgetSpec(args));
-      case "get_concept":
-        return ok(getConcept(args));
-      default:
-        return err(`Unknown tool: ${name}`);
-    }
-  } catch (e) {
-    return err(e.message);
-  }
-});
-function ok(payload) {
-  return {
-    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }]
-  };
-}
-function err(message) {
-  return {
-    isError: true,
-    content: [{ type: "text", text: message }]
-  };
-}
-async function main() {
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
-  process.stderr.write(`${PKG_NAME} v${PKG_VERSION} ready on stdio
-`);
-}
-main().catch((e) => {
-  process.stderr.write(`${PKG_NAME} failed to start: ${e.stack ?? e}
-`);
-  process.exit(1);
-});
+export {
+  GENERATE_FROM_JSON_SCHEMA_TOOL as G,
+  VALIDATE_FORM_DEFINITION_TOOL as V,
+  generateFromOpenapi as a,
+  GENERATE_FROM_OPENAPI_TOOL as b,
+  getWidgetSpec as c,
+  GET_WIDGET_SPEC_TOOL as d,
+  getConcept as e,
+  GET_CONCEPT_TOOL as f,
+  generateFromJsonSchema as g,
+  validateFormDefinition as v
+};