@golemui/gui-mcp 0.15.1 → 0.16.0

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.15.1 (2026-05-27)
+
+This was a version bump only for gui-mcp to align it with other projects, there were no code changes.
+
 ## 0.15.0 (2026-05-26)
 
 ### 🩹 Fixes

package/README.md

@@ -91,14 +91,53 @@ version-locked to a specific GolemUI release. A CI check in this monorepo
 against the exact same schema definitions as `@golemui/gui-*@X.Y.Z`.
 
 No LLM calls happen inside this server — every tool is deterministic. The MCP is the
-*grounding layer* the host IDE's model calls into.
+_grounding layer_ the host IDE's model calls into.
 
 ## Development
 
+### Interactive testing with MCP Inspector
+
+Start the MCP server and open a local web UI at http://localhost:5173
+
+```bash
+npm run start:mcp
+```
+
+To use the server from within Claude Code conversations, register with local Claude Code:
+
+#### With the Calude code CLI
+
+```bash
+claude mcp add golemui-local -- node /Users/{USER}/{...}/golem/golemui/dist/libs/gui/mcp/index.js
+```
+
+Then restart or reload the session. The tools appear in Claude's tool list.
+
+Remove with claude mcp remove golemui-local when done.
+
+#### With the Calude code extension
+
+Create or edit the project-level MCP config at .mcp.json in the workspace root:
+
+```json
+{
+  "mcpServers": {
+    "golemui-local": {
+      "command": "node",
+      "args": ["/Users/{USER}/{...}/golem/golemui/dist/libs/gui/mcp/index.js"]
+    }
+  }
+}
+```
+
+Then reload the VS Code window (Cmd+Shift+P -> "Developer: Reload Window"). The 4 tools will appear in Claude's tool list for this workspace.
+
+Remove the entry from .mcp.json when done.
+
+### Other development commands
+
 ```bash
-# from the repo root
-npx nx run gui-mcp:build            # build to dist/libs/gui/mcp
-npx nx run gui-mcp:vite:test        # run the test suite
+npx nx run gui-mcp:vite:test     # run the test suite
 npm run sync:mcp-schemas            # refresh bundled schemas from libs/gui/shared
 npm run check:mcp-schemas           # CI mode — exits non-zero if out of sync
 ```

package/index.js

@@ -133,7 +133,7 @@ function jsonSchemaToGui(schema, opts = {}) {
     }
   ] : fields;
   return {
-    formDefinition: { form: wrapped },
+    formDefinition: { $schema: "https://golemui.com/schemas/form.schema.json", form: wrapped },
     unmapped
   };
 }
@@ -283,7 +283,13 @@ function buildArrayField(path, _name, label, schema, required2, unmapped) {
     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);
+      const w = mapProperty(
+        childName,
+        unwrap(childSchema),
+        required22.has(childName),
+        childParent,
+        unmapped
+      );
       if (w) templateChildren.push(w);
     }
     if (!templateChildren.length) {
@@ -363,7 +369,7 @@ function cleanFields(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";
-const $defs$t = { "reactiveExpression": { "type": "string", "description": "A reactive expression string. Use `$form` to access form data e.g. `$form.termsAccepted === true`" }, "dotPath": { "type": "string", "description": "A dot-separated path to a property in the form data" }, "dateRange": { "type": "object", "description": "A single date range used by calendar/date-picker widgets to mark days as disabled.", "properties": { "start": { "type": "string" }, "end": { "type": "string" } }, "required": ["start"], "additionalProperties": false }, "uid": { "type": "string", "description": "Unique identifier for the widget" }, "localizable": { "oneOf": [{ "type": "string" }, { "type": "object", "properties": { "key": { "type": "string" }, "default": { "type": "string" }, "params": { "type": "object" } }, "required": ["key"], "additionalProperties": false }] }, "include": { "oneOf": [{ "type": "object", "properties": { "in": { "type": "array", "items": { "type": "string" } } }, "required": ["in"], "additionalProperties": false }, { "type": "object", "properties": { "when": { "$ref": "#/$defs/reactiveExpression" } }, "required": ["when"], "additionalProperties": false }] }, "exclude": { "oneOf": [{ "type": "object", "properties": { "from": { "type": "array", "items": { "type": "string" } } }, "required": ["from"], "additionalProperties": false }, { "type": "object", "properties": { "when": { "$ref": "#/$defs/reactiveExpression" } }, "required": ["when"], "additionalProperties": false }] }, "boolOrWhen": { "oneOf": [{ "type": "boolean" }, { "type": "object", "properties": { "when": { "$ref": "#/$defs/reactiveExpression" } }, "required": ["when"], "additionalProperties": false }] }, "on": { "type": "object", "properties": { "load": { "type": "string" }, "click": { "type": "string" }, "change": { "type": "string" }, "filter": { "type": "string" }, "blur": { "type": "string" } }, "patternProperties": { "^load\\.[^.]+$": { "type": "string" }, "^click\\.[^.]+$": { "type": "string" }, "^change\\.[^.]+$": { "type": "string" }, "^filter\\.[^.]+$": { "type": "string" }, "^blur\\.[^.]+$": { "type": "string" } }, "additionalProperties": false }, "baseWidget": { "type": "object", "properties": { "$schema": { "type": "string" }, "uid": { "$ref": "#/$defs/uid" }, "type": { "type": "string" }, "size": { "type": "number" }, "include": { "$ref": "#/$defs/include" }, "exclude": { "$ref": "#/$defs/exclude" } }, "required": ["type"] } };
+const $defs$t = { "reactiveExpression": { "type": "string", "description": "A reactive expression string. Use `$form` to access form data e.g. `$form.termsAccepted === true`" }, "dotPath": { "type": "string", "description": "A dot-separated path to a property in the form data" }, "dateRange": { "type": "object", "description": "A single date range used by calendar/date-picker widgets to mark days as disabled.", "properties": { "start": { "type": "string", "description": "ISO-8601 date string for the start of the disabled range (inclusive)" }, "end": { "type": "string", "description": "ISO-8601 date string for the end of the disabled range (inclusive). Omit to disable a single day." } }, "required": ["start"], "additionalProperties": false }, "uid": { "type": "string", "description": "Unique identifier for the widget" }, "localizable": { "description": "A value that can be a plain string or an i18n key object. Use a plain string for static text, or `{key, default, params}` to reference a translation key.", "oneOf": [{ "type": "string" }, { "type": "object", "properties": { "key": { "type": "string", "description": "The i18n translation key" }, "default": { "type": "string", "description": "Fallback text shown when the translation key is not found" }, "params": { "type": "object", "description": "Interpolation parameters passed to the translation function" } }, "required": ["key"], "additionalProperties": false }] }, "include": { "description": "Show this widget only in certain form states (`{in: [stateNames]}`) or when a reactive expression is true (`{when: expr}`). If omitted the widget is always shown.", "oneOf": [{ "type": "object", "properties": { "in": { "type": "array", "items": { "type": "string" }, "description": "List of state names (defined in the form `states` map) in which this widget should be visible" } }, "required": ["in"], "additionalProperties": false }, { "type": "object", "properties": { "when": { "$ref": "#/$defs/reactiveExpression" } }, "required": ["when"], "additionalProperties": false }] }, "exclude": { "description": "Hide this widget in certain form states (`{from: [stateNames]}`) or when a reactive expression is true (`{when: expr}`). If omitted the widget is never hidden.", "oneOf": [{ "type": "object", "properties": { "from": { "type": "array", "items": { "type": "string" }, "description": "List of state names (defined in the form `states` map) in which this widget should be hidden" } }, "required": ["from"], "additionalProperties": false }, { "type": "object", "properties": { "when": { "$ref": "#/$defs/reactiveExpression" } }, "required": ["when"], "additionalProperties": false }] }, "boolOrWhen": { "description": "A static boolean or a conditional `{when: reactiveExpression}` object evaluated at runtime. Use `{when: '$form.someField === true'}` for dynamic behavior.", "oneOf": [{ "type": "boolean" }, { "type": "object", "properties": { "when": { "$ref": "#/$defs/reactiveExpression" } }, "required": ["when"], "additionalProperties": false }] }, "on": { "type": "object", "description": 'Event handlers for this widget. Values are action names dispatched to the form\'s event bus. Each key also accepts a state-suffixed variant (`"click.<stateName>"`) that overrides the base handler when the named state is active.', "properties": { "load": { "type": "string", "description": "Action dispatched when the widget is first mounted" }, "click": { "type": "string", "description": "Action dispatched when the user clicks the widget" }, "change": { "type": "string", "description": "Action dispatched when the widget value changes" }, "filter": { "type": "string", "description": "Action dispatched on search/filter input, typically used with async data sources" }, "blur": { "type": "string", "description": "Action dispatched when the widget loses focus" } }, "patternProperties": { "^load\\.[^.]+$": { "type": "string", "description": 'State-suffixed load handler: used instead of `load` when the named state is active (e.g. `"load.myState"`)' }, "^click\\.[^.]+$": { "type": "string", "description": 'State-suffixed click handler: used instead of `click` when the named state is active (e.g. `"click.myState"`)' }, "^change\\.[^.]+$": { "type": "string", "description": 'State-suffixed change handler: used instead of `change` when the named state is active (e.g. `"change.myState"`)' }, "^filter\\.[^.]+$": { "type": "string", "description": 'State-suffixed filter handler: used instead of `filter` when the named state is active (e.g. `"filter.myState"`)' }, "^blur\\.[^.]+$": { "type": "string", "description": 'State-suffixed blur handler: used instead of `blur` when the named state is active (e.g. `"blur.myState"`)' } }, "additionalProperties": false }, "baseWidget": { "type": "object", "description": 'Base properties shared by all widgets. Root-level props that support state-suffixing (e.g. `"label.myState"`) are: `label`, `disabled`, `readonly`, `validator`, `size`. Any key inside `props` can also be suffixed. State names must be declared in the form `states` map.', "properties": { "$schema": { "type": "string" }, "uid": { "$ref": "#/$defs/uid" }, "type": { "type": "string" }, "size": { "type": "number", "description": "Column span in the form grid (1–12). Defaults to full width when omitted.", "minimum": 1, "maximum": 12 }, "include": { "$ref": "#/$defs/include" }, "exclude": { "$ref": "#/$defs/exclude" } }, "required": ["type"] } };
 const commonSchema = {
   $schema: $schema$u,
   $id: $id$u,
@@ -374,10 +380,10 @@ const $schema$t = "https://json-schema.org/draft/2020-12/schema";
 const $id$t = "https://golemui.com/schemas/form.schema.json";
 const title$t = "Golem Form DSL";
 const type$r = "object";
-const properties$r = { "$schema": { "type": "string" }, "states": { "type": "object", "additionalProperties": { "$ref": "common.schema.json#/$defs/reactiveExpression" } }, "form": { "type": "array", "items": { "$ref": "#/$defs/formWidget" } }, "autocomplete": { "type": "string" } };
+const properties$r = { "$schema": { "type": "string" }, "states": { "type": "object", "description": 'Named boolean conditions keyed by state name, each mapping to a reactive expression. States serve two purposes: (1) gating widget visibility via `include.in` / `exclude.from`; (2) overriding individual widget properties when a state is active by appending `".<stateName>"` to any property key — e.g. `"label.myState": "Active label"` or `"props.hint.myState": "Active hint"`. Root-level suffixable props: `label`, `disabled`, `readonly`, `validator`, `size`. Any key inside `props` can also be suffixed.', "additionalProperties": { "$ref": "common.schema.json#/$defs/reactiveExpression" } }, "form": { "type": "array", "description": "The ordered list of widgets that make up the form body", "items": { "$ref": "#/$defs/formWidget" } }, "autocomplete": { "type": "string", "description": "HTML `autocomplete` attribute applied to the `<form>` element (e.g. `on`, `off`)" } };
 const required$r = ["form"];
 const additionalProperties = false;
-const $defs$s = { "chunkRef": { "type": "object", "properties": { "$ref": { "type": "string" } }, "required": ["$ref"], "additionalProperties": false }, "formWidget": { "oneOf": [{ "$ref": "./components/accordion.schema.json" }, { "$ref": "./components/alert.schema.json" }, { "$ref": "./components/button.schema.json" }, { "$ref": "./components/calendar.schema.json" }, { "$ref": "./components/checkbox.schema.json" }, { "$ref": "./components/currency.schema.json" }, { "$ref": "./components/dateinput.schema.json" }, { "$ref": "./components/datepicker.schema.json" }, { "$ref": "./components/dropdown.schema.json" }, { "$ref": "./components/list.schema.json" }, { "$ref": "./components/markdown.schema.json" }, { "$ref": "./components/markdowntext.schema.json" }, { "$ref": "./components/number.schema.json" }, { "$ref": "./components/password.schema.json" }, { "$ref": "./components/radiogroup.schema.json" }, { "$ref": "./components/rangecalendar.schema.json" }, { "$ref": "./components/rangedateinput.schema.json" }, { "$ref": "./components/rangedatepicker.schema.json" }, { "$ref": "./components/repeater.schema.json" }, { "$ref": "./components/select.schema.json" }, { "$ref": "./components/flex.schema.json" }, { "$ref": "./components/grid.schema.json" }, { "$ref": "./components/tabs.schema.json" }, { "$ref": "./components/tags.schema.json" }, { "$ref": "./components/textarea.schema.json" }, { "$ref": "./components/textinput.schema.json" }, { "$ref": "./components/toggle.schema.json" }, { "$ref": "#/$defs/chunkRef" }] } };
+const $defs$s = { "chunkRef": { "type": "object", "description": "A reference to an external chunk file whose widget array will be inlined at this position in the form", "properties": { "$ref": { "type": "string", "description": "Relative path to a JSON chunk file" } }, "required": ["$ref"], "additionalProperties": false }, "formWidget": { "oneOf": [{ "$ref": "./components/accordion.schema.json" }, { "$ref": "./components/alert.schema.json" }, { "$ref": "./components/button.schema.json" }, { "$ref": "./components/calendar.schema.json" }, { "$ref": "./components/checkbox.schema.json" }, { "$ref": "./components/currency.schema.json" }, { "$ref": "./components/dateinput.schema.json" }, { "$ref": "./components/datepicker.schema.json" }, { "$ref": "./components/dropdown.schema.json" }, { "$ref": "./components/list.schema.json" }, { "$ref": "./components/markdown.schema.json" }, { "$ref": "./components/markdowntext.schema.json" }, { "$ref": "./components/number.schema.json" }, { "$ref": "./components/password.schema.json" }, { "$ref": "./components/radiogroup.schema.json" }, { "$ref": "./components/rangecalendar.schema.json" }, { "$ref": "./components/rangedateinput.schema.json" }, { "$ref": "./components/rangedatepicker.schema.json" }, { "$ref": "./components/repeater.schema.json" }, { "$ref": "./components/select.schema.json" }, { "$ref": "./components/flex.schema.json" }, { "$ref": "./components/grid.schema.json" }, { "$ref": "./components/tabs.schema.json" }, { "$ref": "./components/tags.schema.json" }, { "$ref": "./components/textarea.schema.json" }, { "$ref": "./components/textinput.schema.json" }, { "$ref": "./components/toggle.schema.json" }, { "$ref": "#/$defs/chunkRef" }] } };
 const formSchema = {
   $schema: $schema$t,
   $id: $id$t,
@@ -401,7 +407,7 @@ const layoutWidgetSchema = {
 const $schema$r = "https://json-schema.org/draft/2020-12/schema";
 const $id$r = "https://golemui.com/schemas/validators.schema.json";
 const title$r = "GolemUI Validator Definitions";
-const $defs$r = { "localizable": { "$ref": "./common.schema.json#/$defs/localizable" }, "stringValidator": { "type": "object", "properties": { "type": { "const": "string" }, "required": { "type": "boolean" }, "minLength": { "type": "number" }, "maxLength": { "type": "number" }, "pattern": { "type": "string", "description": "A regular expression pattern the value must match" }, "format": { "type": "string", "enum": ["email", "hostname", "ipv4", "ipv6", "url", "uuid", "date", "time", "date-time", "duration"] }, "const": {}, "enum": { "type": "array" }, "messages": { "type": "object", "properties": { "invalid": { "$ref": "#/$defs/localizable" }, "required": { "$ref": "#/$defs/localizable" }, "minLength": { "$ref": "#/$defs/localizable" }, "maxLength": { "$ref": "#/$defs/localizable" }, "pattern": { "$ref": "#/$defs/localizable" }, "format": { "$ref": "#/$defs/localizable" }, "enum": { "$ref": "#/$defs/localizable" }, "const": { "$ref": "#/$defs/localizable" } }, "additionalProperties": false } }, "required": ["type"], "additionalProperties": false }, "numberValidator": { "type": "object", "properties": { "type": { "type": "string", "enum": ["number", "integer"] }, "required": { "type": "boolean" }, "minimum": { "type": "number" }, "maximum": { "type": "number" }, "exclusiveMinimum": { "type": "number" }, "exclusiveMaximum": { "type": "number" }, "multipleOf": { "type": "number" }, "const": {}, "enum": { "type": "array" }, "messages": { "type": "object", "properties": { "invalid": { "$ref": "#/$defs/localizable" }, "minimum": { "$ref": "#/$defs/localizable" }, "maximum": { "$ref": "#/$defs/localizable" }, "exclusiveMinimum": { "$ref": "#/$defs/localizable" }, "exclusiveMaximum": { "$ref": "#/$defs/localizable" }, "multipleOf": { "$ref": "#/$defs/localizable" }, "enum": { "$ref": "#/$defs/localizable" }, "const": { "$ref": "#/$defs/localizable" } }, "additionalProperties": false } }, "required": ["type"], "additionalProperties": false }, "booleanValidator": { "type": "object", "properties": { "type": { "const": "boolean" }, "required": { "type": "boolean" }, "const": {}, "messages": { "type": "object", "properties": { "invalid": { "$ref": "#/$defs/localizable" }, "const": { "$ref": "#/$defs/localizable" } }, "additionalProperties": false } }, "required": ["type"], "additionalProperties": false }, "arrayValidator": { "type": "object", "properties": { "type": { "const": "array" }, "required": { "type": "boolean" }, "minItems": { "type": "number" }, "maxItems": { "type": "number" }, "uniqueItems": { "type": "boolean" }, "messages": { "type": "object", "properties": { "invalid": { "$ref": "#/$defs/localizable" }, "required": { "$ref": "#/$defs/localizable" }, "minItems": { "$ref": "#/$defs/localizable" }, "maxItems": { "$ref": "#/$defs/localizable" } }, "additionalProperties": false } }, "required": ["type"], "additionalProperties": false }, "customValidator": { "type": "object", "properties": { "type": { "const": "custom" }, "required": { "type": "boolean" } }, "required": ["type"], "additionalProperties": true }, "validator": { "oneOf": [{ "$ref": "#/$defs/stringValidator" }, { "$ref": "#/$defs/numberValidator" }, { "$ref": "#/$defs/booleanValidator" }, { "$ref": "#/$defs/arrayValidator" }, { "$ref": "#/$defs/customValidator" }] } };
+const $defs$r = { "localizable": { "$ref": "./common.schema.json#/$defs/localizable" }, "stringValidator": { "type": "object", "properties": { "type": { "const": "string" }, "required": { "type": "boolean", "description": "Makes the field mandatory — validation fails if the value is empty or absent" }, "minLength": { "type": "number", "description": "Minimum number of characters the string must contain" }, "maxLength": { "type": "number", "description": "Maximum number of characters the string may contain" }, "pattern": { "type": "string", "description": "A regular expression pattern the value must match" }, "format": { "type": "string", "description": "A named format the string must conform to (e.g. `email`, `url`, `date`, `uuid`)", "enum": ["email", "hostname", "ipv4", "ipv6", "url", "uuid", "date", "time", "date-time", "duration"] }, "const": { "description": "The string must equal exactly this value" }, "enum": { "type": "array", "description": "The string must be one of these allowed values" }, "messages": { "type": "object", "description": "Custom error messages that override the default text for each constraint violation", "properties": { "invalid": { "$ref": "#/$defs/localizable", "description": "Shown when the value fails general type validation" }, "required": { "$ref": "#/$defs/localizable", "description": "Shown when a required field is empty" }, "minLength": { "$ref": "#/$defs/localizable", "description": "Shown when the value is shorter than `minLength`" }, "maxLength": { "$ref": "#/$defs/localizable", "description": "Shown when the value is longer than `maxLength`" }, "pattern": { "$ref": "#/$defs/localizable", "description": "Shown when the value does not match the `pattern` regex" }, "format": { "$ref": "#/$defs/localizable", "description": "Shown when the value does not conform to the specified `format`" }, "enum": { "$ref": "#/$defs/localizable", "description": "Shown when the value is not in the `enum` list" }, "const": { "$ref": "#/$defs/localizable", "description": "Shown when the value does not equal `const`" } }, "additionalProperties": false } }, "required": ["type"], "additionalProperties": false }, "numberValidator": { "type": "object", "properties": { "type": { "type": "string", "enum": ["number", "integer"] }, "required": { "type": "boolean", "description": "Makes the field mandatory — validation fails if the value is absent" }, "minimum": { "type": "number", "description": "The value must be greater than or equal to this number (inclusive)" }, "maximum": { "type": "number", "description": "The value must be less than or equal to this number (inclusive)" }, "exclusiveMinimum": { "type": "number", "description": "The value must be strictly greater than this number (exclusive)" }, "exclusiveMaximum": { "type": "number", "description": "The value must be strictly less than this number (exclusive)" }, "multipleOf": { "type": "number", "description": "The value must be a multiple of this number" }, "const": { "description": "The value must equal exactly this number" }, "enum": { "type": "array", "description": "The value must be one of these allowed numbers" }, "messages": { "type": "object", "description": "Custom error messages that override the default text for each constraint violation", "properties": { "invalid": { "$ref": "#/$defs/localizable", "description": "Shown when the value fails general type validation" }, "minimum": { "$ref": "#/$defs/localizable", "description": "Shown when the value is below `minimum`" }, "maximum": { "$ref": "#/$defs/localizable", "description": "Shown when the value exceeds `maximum`" }, "exclusiveMinimum": { "$ref": "#/$defs/localizable", "description": "Shown when the value is not strictly above `exclusiveMinimum`" }, "exclusiveMaximum": { "$ref": "#/$defs/localizable", "description": "Shown when the value is not strictly below `exclusiveMaximum`" }, "multipleOf": { "$ref": "#/$defs/localizable", "description": "Shown when the value is not a multiple of `multipleOf`" }, "enum": { "$ref": "#/$defs/localizable", "description": "Shown when the value is not in the `enum` list" }, "const": { "$ref": "#/$defs/localizable", "description": "Shown when the value does not equal `const`" } }, "additionalProperties": false } }, "required": ["type"], "additionalProperties": false }, "booleanValidator": { "type": "object", "properties": { "type": { "const": "boolean" }, "required": { "type": "boolean", "description": "Makes the field mandatory — validation fails if the value is absent or false (e.g. an unchecked required checkbox)" }, "const": { "description": "The value must equal exactly this boolean (e.g. `true` to require acceptance)" }, "messages": { "type": "object", "description": "Custom error messages that override the default text for each constraint violation", "properties": { "invalid": { "$ref": "#/$defs/localizable", "description": "Shown when the value fails general type validation" }, "const": { "$ref": "#/$defs/localizable", "description": "Shown when the value does not equal `const`" } }, "additionalProperties": false } }, "required": ["type"], "additionalProperties": false }, "arrayValidator": { "type": "object", "properties": { "type": { "const": "array" }, "required": { "type": "boolean", "description": "Makes the field mandatory — validation fails if the array is empty or absent" }, "minItems": { "type": "number", "description": "The array must contain at least this many items" }, "maxItems": { "type": "number", "description": "The array must contain no more than this many items" }, "uniqueItems": { "type": "boolean", "description": "When true, all items in the array must be distinct values" }, "messages": { "type": "object", "description": "Custom error messages that override the default text for each constraint violation", "properties": { "invalid": { "$ref": "#/$defs/localizable", "description": "Shown when the value fails general type validation" }, "required": { "$ref": "#/$defs/localizable", "description": "Shown when a required array is empty or absent" }, "minItems": { "$ref": "#/$defs/localizable", "description": "Shown when the array has fewer items than `minItems`" }, "maxItems": { "$ref": "#/$defs/localizable", "description": "Shown when the array has more items than `maxItems`" } }, "additionalProperties": false } }, "required": ["type"], "additionalProperties": false }, "customValidator": { "type": "object", "description": "A custom validator that delegates validation to application code. The registered validator function receives these constraint keys and must return a Standard Schema V1-compliant schema object (https://standardschema.dev). Add arbitrary constraint keys alongside `type` — they are passed as-is to the registered validator function.", "properties": { "type": { "const": "custom" }, "required": { "type": "boolean", "description": "Makes the field mandatory — evaluation is still delegated to the custom validator" } }, "required": ["type"], "additionalProperties": true }, "validator": { "description": "Validation rules for this field. The `type` discriminant selects the validator: `string`, `number`, `integer`, `boolean`, `array`, or `custom`.", "oneOf": [{ "$ref": "#/$defs/stringValidator" }, { "$ref": "#/$defs/numberValidator" }, { "$ref": "#/$defs/booleanValidator" }, { "$ref": "#/$defs/arrayValidator" }, { "$ref": "#/$defs/customValidator" }] } };
 const validatorsSchema = {
   $schema: $schema$r,
   $id: $id$r,
@@ -412,9 +418,9 @@ const $schema$q = "https://json-schema.org/draft/2020-12/schema";
 const $id$q = "https://golemui.com/schemas/components/accordion.schema.json";
 const title$q = "Accordion Widget";
 const type$q = "object";
-const $defs$q = { "singleOpenProp": { "type": "boolean" }, "defaultOpenProp": { "type": "object", "additionalProperties": { "type": "boolean" }, "minProperties": 1 }, "renderModeProp": { "enum": ["all", "activeOnly"] }, "sectionsProp": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "label": { "$ref": "../common.schema.json#/$defs/localizable" }, "uid": { "type": "string" } }, "required": ["label", "uid"], "additionalProperties": false } } };
+const $defs$q = { "singleOpenProp": { "type": "boolean", "description": "When true, opening one section automatically closes all others. Defaults to false." }, "defaultOpenProp": { "type": "object", "description": "Map of section UIDs to booleans indicating which sections are open on initial render", "additionalProperties": { "type": "boolean" }, "minProperties": 1 }, "renderModeProp": { "description": "Controls when section content is rendered: `all` keeps all sections in the DOM, `activeOnly` unmounts inactive ones", "enum": ["all", "activeOnly"] }, "sectionsProp": { "type": "array", "description": "Ordered list of section definitions. Each section's `uid` must match the widget UIDs used in `children`.", "minItems": 1, "items": { "type": "object", "properties": { "label": { "$ref": "../common.schema.json#/$defs/localizable" }, "uid": { "type": "string", "description": "Unique identifier linking this section definition to its widgets in `children`" } }, "required": ["label", "uid"], "additionalProperties": false } } };
 const allOf$q = [{ "$ref": "../common.schema.json#/$defs/baseWidget" }];
-const properties$q = { "kind": { "const": "layout" }, "type": { "const": "accordion" }, "on": { "$ref": "../common.schema.json#/$defs/on" }, "children": { "type": "array", "minItems": 1, "items": { "$ref": "../form.schema.json#/$defs/formWidget" } }, "props": { "type": "object", "properties": { "singleOpen": { "$ref": "#/$defs/singleOpenProp" }, "defaultOpen": { "$ref": "#/$defs/defaultOpenProp" }, "renderMode": { "$ref": "#/$defs/renderModeProp" }, "sections": { "$ref": "#/$defs/sectionsProp" } }, "required": ["sections"], "patternProperties": { "^singleOpen\\.[^.]+$": { "$ref": "#/$defs/singleOpenProp" }, "^defaultOpen\\.[^.]+$": { "$ref": "#/$defs/defaultOpenProp" }, "^renderMode\\.[^.]+$": { "$ref": "#/$defs/renderModeProp" }, "^sections\\.[^.]+$": { "$ref": "#/$defs/sectionsProp" } }, "additionalProperties": false } };
+const properties$q = { "kind": { "const": "layout" }, "type": { "const": "accordion" }, "on": { "$ref": "../common.schema.json#/$defs/on" }, "children": { "type": "array", "description": "Flat list of widgets belonging to all sections. Each widget must have a `uid` matching one of the section UIDs in `props.sections`.", "minItems": 1, "items": { "$ref": "../form.schema.json#/$defs/formWidget" } }, "props": { "type": "object", "properties": { "singleOpen": { "$ref": "#/$defs/singleOpenProp" }, "defaultOpen": { "$ref": "#/$defs/defaultOpenProp" }, "renderMode": { "$ref": "#/$defs/renderModeProp" }, "sections": { "$ref": "#/$defs/sectionsProp" } }, "required": ["sections"], "patternProperties": { "^singleOpen\\.[^.]+$": { "$ref": "#/$defs/singleOpenProp" }, "^defaultOpen\\.[^.]+$": { "$ref": "#/$defs/defaultOpenProp" }, "^renderMode\\.[^.]+$": { "$ref": "#/$defs/renderModeProp" }, "^sections\\.[^.]+$": { "$ref": "#/$defs/sectionsProp" } }, "additionalProperties": false } };
 const required$q = ["kind", "type", "children", "props"];
 const unevaluatedProperties$q = false;
 const accordion = {
@@ -474,7 +480,7 @@ const $schema$n = "https://json-schema.org/draft/2020-12/schema";
 const $id$n = "https://golemui.com/schemas/components/calendar.schema.json";
 const title$n = "Calendar Widget";
 const type$n = "object";
-const $defs$n = { "labelDef": { "$ref": "../common.schema.json#/$defs/localizable" }, "disabledDef": { "$ref": "../common.schema.json#/$defs/boolOrWhen" }, "readonlyDef": { "$ref": "../common.schema.json#/$defs/boolOrWhen" }, "hintProp": { "$ref": "../common.schema.json#/$defs/localizable" }, "prevMonthIconProp": { "type": "string" }, "nextMonthIconProp": { "type": "string" }, "prevMonthAriaLabelProp": { "$ref": "../common.schema.json#/$defs/localizable" }, "nextMonthAriaLabelProp": { "$ref": "../common.schema.json#/$defs/localizable" }, "dayFormatProp": { "enum": ["numeric", "2-digit"] }, "weekdayFormatProp": { "enum": ["short", "long", "narrow"] }, "monthFormatProp": { "enum": ["numeric", "2-digit", "long", "short", "narrow"] }, "minDateProp": { "type": "string" }, "maxDateProp": { "type": "string" }, "numberOfMonthsProp": { "type": "number" }, "disabledRangesProp": { "type": "array", "items": { "$ref": "../common.schema.json#/$defs/dateRange" } } };
+const $defs$n = { "labelDef": { "$ref": "../common.schema.json#/$defs/localizable" }, "disabledDef": { "$ref": "../common.schema.json#/$defs/boolOrWhen" }, "readonlyDef": { "$ref": "../common.schema.json#/$defs/boolOrWhen" }, "hintProp": { "$ref": "../common.schema.json#/$defs/localizable" }, "prevMonthIconProp": { "type": "string" }, "nextMonthIconProp": { "type": "string" }, "prevMonthAriaLabelProp": { "$ref": "../common.schema.json#/$defs/localizable" }, "nextMonthAriaLabelProp": { "$ref": "../common.schema.json#/$defs/localizable" }, "dayFormatProp": { "description": "Formatting of day numbers in the calendar grid (`numeric` = 1–31, `2-digit` = 01–31)", "enum": ["numeric", "2-digit"] }, "weekdayFormatProp": { "description": "Formatting of weekday column headers (`short` = Mon, `long` = Monday, `narrow` = M)", "enum": ["short", "long", "narrow"] }, "monthFormatProp": { "description": "Formatting of the month heading (`long` = January, `short` = Jan, `narrow` = J, `numeric` = 1, `2-digit` = 01)", "enum": ["numeric", "2-digit", "long", "short", "narrow"] }, "minDateProp": { "type": "string", "description": "ISO-8601 date string for the earliest selectable date (inclusive)" }, "maxDateProp": { "type": "string", "description": "ISO-8601 date string for the latest selectable date (inclusive)" }, "numberOfMonthsProp": { "type": "number", "description": "Number of month panels to display side by side. Defaults to 1." }, "disabledRangesProp": { "type": "array", "description": "Date ranges that are shown but cannot be selected", "items": { "$ref": "../common.schema.json#/$defs/dateRange" } } };
 const allOf$n = [{ "$ref": "../common.schema.json#/$defs/baseWidget" }];
 const properties$n = { "kind": { "const": "input" }, "type": { "const": "calendar" }, "path": { "$ref": "../common.schema.json#/$defs/dotPath" }, "label": { "$ref": "#/$defs/labelDef" }, "disabled": { "$ref": "#/$defs/disabledDef" }, "readonly": { "$ref": "#/$defs/readonlyDef" }, "on": { "$ref": "../common.schema.json#/$defs/on" }, "validator": { "$ref": "../validators.schema.json#/$defs/validator" }, "props": { "type": "object", "properties": { "hint": { "$ref": "#/$defs/hintProp" }, "prevMonthIcon": { "$ref": "#/$defs/prevMonthIconProp" }, "nextMonthIcon": { "$ref": "#/$defs/nextMonthIconProp" }, "prevMonthAriaLabel": { "$ref": "#/$defs/prevMonthAriaLabelProp" }, "nextMonthAriaLabel": { "$ref": "#/$defs/nextMonthAriaLabelProp" }, "dayFormat": { "$ref": "#/$defs/dayFormatProp" }, "weekdayFormat": { "$ref": "#/$defs/weekdayFormatProp" }, "monthFormat": { "$ref": "#/$defs/monthFormatProp" }, "minDate": { "$ref": "#/$defs/minDateProp" }, "maxDate": { "$ref": "#/$defs/maxDateProp" }, "numberOfMonths": { "$ref": "#/$defs/numberOfMonthsProp" }, "disabledRanges": { "$ref": "#/$defs/disabledRangesProp" } }, "patternProperties": { "^hint\\.[^.]+$": { "$ref": "#/$defs/hintProp" }, "^prevMonthIcon\\.[^.]+$": { "$ref": "#/$defs/prevMonthIconProp" }, "^nextMonthIcon\\.[^.]+$": { "$ref": "#/$defs/nextMonthIconProp" }, "^prevMonthAriaLabel\\.[^.]+$": { "$ref": "#/$defs/prevMonthAriaLabelProp" }, "^nextMonthAriaLabel\\.[^.]+$": { "$ref": "#/$defs/nextMonthAriaLabelProp" }, "^dayFormat\\.[^.]+$": { "$ref": "#/$defs/dayFormatProp" }, "^weekdayFormat\\.[^.]+$": { "$ref": "#/$defs/weekdayFormatProp" }, "^monthFormat\\.[^.]+$": { "$ref": "#/$defs/monthFormatProp" }, "^minDate\\.[^.]+$": { "$ref": "#/$defs/minDateProp" }, "^maxDate\\.[^.]+$": { "$ref": "#/$defs/maxDateProp" }, "^numberOfMonths\\.[^.]+$": { "$ref": "#/$defs/numberOfMonthsProp" }, "^disabledRanges\\.[^.]+$": { "$ref": "#/$defs/disabledRangesProp" } }, "additionalProperties": false } };
 const patternProperties$j = { "^label\\.[^.]+$": { "$ref": "#/$defs/labelDef" }, "^disabled\\.[^.]+$": { "$ref": "#/$defs/disabledDef" }, "^readonly\\.[^.]+$": { "$ref": "#/$defs/readonlyDef" }, "^validator\\.[^.]+$": { "$ref": "../validators.schema.json#/$defs/validator" } };
@@ -584,7 +590,7 @@ const $schema$i = "https://json-schema.org/draft/2020-12/schema";
 const $id$i = "https://golemui.com/schemas/components/dropdown.schema.json";
 const title$i = "Dropdown Widget";
 const type$i = "object";
-const $defs$i = { "disabledDef": { "$ref": "../common.schema.json#/$defs/boolOrWhen" }, "readonlyDef": { "$ref": "../common.schema.json#/$defs/boolOrWhen" }, "labelDef": { "$ref": "../common.schema.json#/$defs/localizable" }, "placeholderProp": { "$ref": "../common.schema.json#/$defs/localizable" }, "hintProp": { "$ref": "../common.schema.json#/$defs/localizable" }, "itemsProp": { "type": "array", "description": "Items are either primitive values (string/number) or arbitrary record objects (paired with `labelField`/`valueField`/`itemRenderer` for custom rendering). Note: widget templates inside items are only supported on `repeater`, not here.", "items": { "type": ["string", "number", "object"] } }, "labelFieldProp": { "type": "string" }, "valueFieldProp": { "type": "string" }, "searchFieldsProp": { "type": "array", "items": { "type": "string" } }, "heightProp": { "type": "number" }, "itemHeightProp": { "type": "number" }, "itemRendererProp": { "type": "string" }, "inputDebounceProp": { "type": "number" }, "autocompleteProp": { "type": "string" } };
+const $defs$i = { "disabledDef": { "$ref": "../common.schema.json#/$defs/boolOrWhen" }, "readonlyDef": { "$ref": "../common.schema.json#/$defs/boolOrWhen" }, "labelDef": { "$ref": "../common.schema.json#/$defs/localizable" }, "placeholderProp": { "$ref": "../common.schema.json#/$defs/localizable" }, "hintProp": { "$ref": "../common.schema.json#/$defs/localizable" }, "itemsProp": { "type": "array", "description": "Items are either primitive values (string/number) or arbitrary record objects (paired with `labelField`/`valueField`/`itemRenderer` for custom rendering). Note: widget templates inside items are only supported on `repeater`, not here.", "items": { "type": ["string", "number", "object"] } }, "labelFieldProp": { "type": "string", "description": 'Object property used as the display label when items are objects (e.g. `"name"` reads `item.name`)' }, "valueFieldProp": { "type": "string", "description": 'Object property used as the stored value when items are objects (e.g. `"id"` stores `item.id`)' }, "searchFieldsProp": { "type": "array", "description": "Object properties searched when the user types in the filter box. Defaults to `labelField` when omitted.", "items": { "type": "string" } }, "heightProp": { "type": "number", "description": "Fixed pixel height of the dropdown list panel (enables virtual scrolling for large lists)" }, "itemHeightProp": { "type": "number", "description": "Fixed pixel height of each item row, required for virtual scrolling when `height` is set" }, "itemRendererProp": { "type": "string", "description": "Name of a registered custom item renderer component used to display each option" }, "inputDebounceProp": { "type": "number", "description": "Milliseconds to debounce the filter input before firing the `on.filter` event (default: 0)" }, "autocompleteProp": { "type": "string", "description": "HTML `autocomplete` attribute applied to the underlying input element" } };
 const allOf$i = [{ "$ref": "../common.schema.json#/$defs/baseWidget" }];
 const properties$i = { "kind": { "const": "input" }, "type": { "const": "dropdown" }, "path": { "$ref": "../common.schema.json#/$defs/dotPath" }, "label": { "$ref": "#/$defs/labelDef" }, "disabled": { "$ref": "#/$defs/disabledDef" }, "readonly": { "$ref": "#/$defs/readonlyDef" }, "on": { "$ref": "../common.schema.json#/$defs/on" }, "validator": { "$ref": "../validators.schema.json#/$defs/validator" }, "props": { "type": "object", "required": ["items"], "properties": { "placeholder": { "$ref": "#/$defs/placeholderProp" }, "hint": { "$ref": "#/$defs/hintProp" }, "items": { "$ref": "#/$defs/itemsProp" }, "labelField": { "$ref": "#/$defs/labelFieldProp" }, "valueField": { "$ref": "#/$defs/valueFieldProp" }, "searchFields": { "$ref": "#/$defs/searchFieldsProp" }, "height": { "$ref": "#/$defs/heightProp" }, "itemHeight": { "$ref": "#/$defs/itemHeightProp" }, "itemRenderer": { "$ref": "#/$defs/itemRendererProp" }, "inputDebounce": { "$ref": "#/$defs/inputDebounceProp" }, "autocomplete": { "$ref": "#/$defs/autocompleteProp" } }, "patternProperties": { "^placeholder\\.[^.]+$": { "$ref": "#/$defs/placeholderProp" }, "^hint\\.[^.]+$": { "$ref": "#/$defs/hintProp" }, "^items\\.[^.]+$": { "$ref": "#/$defs/itemsProp" }, "^labelField\\.[^.]+$": { "$ref": "#/$defs/labelFieldProp" }, "^valueField\\.[^.]+$": { "$ref": "#/$defs/valueFieldProp" }, "^searchFields\\.[^.]+$": { "$ref": "#/$defs/searchFieldsProp" }, "^height\\.[^.]+$": { "$ref": "#/$defs/heightProp" }, "^itemHeight\\.[^.]+$": { "$ref": "#/$defs/itemHeightProp" }, "^itemRenderer\\.[^.]+$": { "$ref": "#/$defs/itemRendererProp" }, "^inputDebounce\\.[^.]+$": { "$ref": "#/$defs/inputDebounceProp" }, "^autocomplete\\.[^.]+$": { "$ref": "#/$defs/autocompleteProp" } }, "additionalProperties": false } };
 const patternProperties$e = { "^label\\.[^.]+$": { "$ref": "#/$defs/labelDef" }, "^disabled\\.[^.]+$": { "$ref": "#/$defs/disabledDef" }, "^readonly\\.[^.]+$": { "$ref": "#/$defs/readonlyDef" }, "^validator\\.[^.]+$": { "$ref": "../validators.schema.json#/$defs/validator" } };
@@ -754,7 +760,7 @@ const $schema$a = "https://json-schema.org/draft/2020-12/schema";
 const $id$a = "https://golemui.com/schemas/components/radiogroup.schema.json";
 const title$a = "RadioGroup Widget";
 const type$a = "object";
-const $defs$a = { "disabledDef": { "$ref": "../common.schema.json#/$defs/boolOrWhen" }, "readonlyDef": { "$ref": "../common.schema.json#/$defs/boolOrWhen" }, "labelDef": { "$ref": "../common.schema.json#/$defs/localizable" }, "hintProp": { "$ref": "../common.schema.json#/$defs/localizable" }, "optionsProp": { "type": "array", "description": "Options may be primitive values (string/number), structured `{ label, value }` records, or arbitrary objects (paired with `labelField`/`valueField` for custom rendering).", "items": { "type": ["string", "number", "object"] } }, "labelFieldProp": { "type": "string" }, "valueFieldProp": { "type": "string" }, "directionProp": { "enum": ["row", "column"], "default": "column" } };
+const $defs$a = { "disabledDef": { "$ref": "../common.schema.json#/$defs/boolOrWhen" }, "readonlyDef": { "$ref": "../common.schema.json#/$defs/boolOrWhen" }, "labelDef": { "$ref": "../common.schema.json#/$defs/localizable" }, "hintProp": { "$ref": "../common.schema.json#/$defs/localizable" }, "optionsProp": { "type": "array", "description": "Options may be primitive values (string/number), structured `{ label, value }` records, or arbitrary objects (paired with `labelField`/`valueField` for custom rendering).", "items": { "type": ["string", "number", "object"] } }, "labelFieldProp": { "type": "string", "description": 'Object property used as the display label when options are objects (e.g. `"name"` reads `item.name`)' }, "valueFieldProp": { "type": "string", "description": 'Object property used as the stored value when options are objects (e.g. `"id"` stores `item.id`)' }, "directionProp": { "description": "Layout direction for the radio buttons (`row` = horizontal, `column` = vertical). Defaults to `column`.", "enum": ["row", "column"], "default": "column" } };
 const allOf$a = [{ "$ref": "../common.schema.json#/$defs/baseWidget" }];
 const properties$a = { "kind": { "const": "input" }, "type": { "const": "radiogroup" }, "path": { "$ref": "../common.schema.json#/$defs/dotPath" }, "label": { "$ref": "#/$defs/labelDef" }, "disabled": { "$ref": "#/$defs/disabledDef" }, "readonly": { "$ref": "#/$defs/readonlyDef" }, "on": { "$ref": "../common.schema.json#/$defs/on" }, "validator": { "$ref": "../validators.schema.json#/$defs/validator" }, "props": { "type": "object", "properties": { "hint": { "$ref": "#/$defs/hintProp" }, "options": { "$ref": "#/$defs/optionsProp" }, "labelField": { "$ref": "#/$defs/labelFieldProp" }, "valueField": { "$ref": "#/$defs/valueFieldProp" }, "direction": { "$ref": "#/$defs/directionProp" } }, "patternProperties": { "^hint\\.[^.]+$": { "$ref": "#/$defs/hintProp" }, "^options\\.[^.]+$": { "$ref": "#/$defs/optionsProp" }, "^labelField\\.[^.]+$": { "$ref": "#/$defs/labelFieldProp" }, "^valueField\\.[^.]+$": { "$ref": "#/$defs/valueFieldProp" }, "^direction\\.[^.]+$": { "$ref": "#/$defs/directionProp" } }, "additionalProperties": false } };
 const patternProperties$9 = { "^label\\.[^.]+$": { "$ref": "#/$defs/labelDef" }, "^disabled\\.[^.]+$": { "$ref": "#/$defs/disabledDef" }, "^readonly\\.[^.]+$": { "$ref": "#/$defs/readonlyDef" }, "^validator\\.[^.]+$": { "$ref": "../validators.schema.json#/$defs/validator" } };
@@ -776,7 +782,7 @@ const $schema$9 = "https://json-schema.org/draft/2020-12/schema";
 const $id$9 = "https://golemui.com/schemas/components/rangecalendar.schema.json";
 const title$9 = "RangeCalendar Widget";
 const type$9 = "object";
-const $defs$9 = { "disabledDef": { "$ref": "../common.schema.json#/$defs/boolOrWhen" }, "readonlyDef": { "$ref": "../common.schema.json#/$defs/boolOrWhen" }, "labelDef": { "$ref": "../common.schema.json#/$defs/localizable" }, "hintProp": { "$ref": "../common.schema.json#/$defs/localizable" }, "prevMonthIconProp": { "type": "string" }, "nextMonthIconProp": { "type": "string" }, "prevMonthAriaLabelProp": { "$ref": "../common.schema.json#/$defs/localizable" }, "nextMonthAriaLabelProp": { "$ref": "../common.schema.json#/$defs/localizable" }, "removePillAriaLabelProp": { "$ref": "../common.schema.json#/$defs/localizable" }, "dayFormatProp": { "enum": ["numeric", "2-digit"] }, "weekdayFormatProp": { "enum": ["short", "long", "narrow"] }, "monthFormatProp": { "enum": ["numeric", "2-digit", "long", "short", "narrow"] }, "minDateProp": { "type": "string" }, "maxDateProp": { "type": "string" }, "numberOfMonthsProp": { "type": "number" }, "disabledRangesProp": { "type": "array", "items": { "$ref": "../common.schema.json#/$defs/dateRange" } } };
+const $defs$9 = { "disabledDef": { "$ref": "../common.schema.json#/$defs/boolOrWhen" }, "readonlyDef": { "$ref": "../common.schema.json#/$defs/boolOrWhen" }, "labelDef": { "$ref": "../common.schema.json#/$defs/localizable" }, "hintProp": { "$ref": "../common.schema.json#/$defs/localizable" }, "prevMonthIconProp": { "type": "string" }, "nextMonthIconProp": { "type": "string" }, "prevMonthAriaLabelProp": { "$ref": "../common.schema.json#/$defs/localizable" }, "nextMonthAriaLabelProp": { "$ref": "../common.schema.json#/$defs/localizable" }, "removePillAriaLabelProp": { "description": "Accessible label for the button that clears the selected range pill", "$ref": "../common.schema.json#/$defs/localizable" }, "dayFormatProp": { "description": "Formatting of day numbers in the calendar grid (`numeric` = 1–31, `2-digit` = 01–31)", "enum": ["numeric", "2-digit"] }, "weekdayFormatProp": { "description": "Formatting of weekday column headers (`short` = Mon, `long` = Monday, `narrow` = M)", "enum": ["short", "long", "narrow"] }, "monthFormatProp": { "description": "Formatting of the month heading (`long` = January, `short` = Jan, `narrow` = J, `numeric` = 1, `2-digit` = 01)", "enum": ["numeric", "2-digit", "long", "short", "narrow"] }, "minDateProp": { "type": "string", "description": "ISO-8601 date string for the earliest selectable date (inclusive)" }, "maxDateProp": { "type": "string", "description": "ISO-8601 date string for the latest selectable date (inclusive)" }, "numberOfMonthsProp": { "type": "number", "description": "Number of month panels to display side by side. Defaults to 1." }, "disabledRangesProp": { "type": "array", "description": "Date ranges that are shown but cannot be selected", "items": { "$ref": "../common.schema.json#/$defs/dateRange" } } };
 const allOf$9 = [{ "$ref": "../common.schema.json#/$defs/baseWidget" }];
 const properties$9 = { "kind": { "const": "input" }, "type": { "const": "rangeCalendar" }, "path": { "$ref": "../common.schema.json#/$defs/dotPath" }, "label": { "$ref": "#/$defs/labelDef" }, "disabled": { "$ref": "#/$defs/disabledDef" }, "readonly": { "$ref": "#/$defs/readonlyDef" }, "on": { "$ref": "../common.schema.json#/$defs/on" }, "validator": { "$ref": "../validators.schema.json#/$defs/validator" }, "props": { "type": "object", "properties": { "hint": { "$ref": "#/$defs/hintProp" }, "prevMonthIcon": { "$ref": "#/$defs/prevMonthIconProp" }, "nextMonthIcon": { "$ref": "#/$defs/nextMonthIconProp" }, "prevMonthAriaLabel": { "$ref": "#/$defs/prevMonthAriaLabelProp" }, "nextMonthAriaLabel": { "$ref": "#/$defs/nextMonthAriaLabelProp" }, "removePillAriaLabel": { "$ref": "#/$defs/removePillAriaLabelProp" }, "dayFormat": { "$ref": "#/$defs/dayFormatProp" }, "weekdayFormat": { "$ref": "#/$defs/weekdayFormatProp" }, "monthFormat": { "$ref": "#/$defs/monthFormatProp" }, "minDate": { "$ref": "#/$defs/minDateProp" }, "maxDate": { "$ref": "#/$defs/maxDateProp" }, "numberOfMonths": { "$ref": "#/$defs/numberOfMonthsProp" }, "disabledRanges": { "$ref": "#/$defs/disabledRangesProp" } }, "patternProperties": { "^hint\\.[^.]+$": { "$ref": "#/$defs/hintProp" }, "^prevMonthIcon\\.[^.]+$": { "$ref": "#/$defs/prevMonthIconProp" }, "^nextMonthIcon\\.[^.]+$": { "$ref": "#/$defs/nextMonthIconProp" }, "^prevMonthAriaLabel\\.[^.]+$": { "$ref": "#/$defs/prevMonthAriaLabelProp" }, "^nextMonthAriaLabel\\.[^.]+$": { "$ref": "#/$defs/nextMonthAriaLabelProp" }, "^removePillAriaLabel\\.[^.]+$": { "$ref": "#/$defs/removePillAriaLabelProp" }, "^dayFormat\\.[^.]+$": { "$ref": "#/$defs/dayFormatProp" }, "^weekdayFormat\\.[^.]+$": { "$ref": "#/$defs/weekdayFormatProp" }, "^monthFormat\\.[^.]+$": { "$ref": "#/$defs/monthFormatProp" }, "^minDate\\.[^.]+$": { "$ref": "#/$defs/minDateProp" }, "^maxDate\\.[^.]+$": { "$ref": "#/$defs/maxDateProp" }, "^numberOfMonths\\.[^.]+$": { "$ref": "#/$defs/numberOfMonthsProp" }, "^disabledRanges\\.[^.]+$": { "$ref": "#/$defs/disabledRangesProp" } }, "additionalProperties": false } };
 const patternProperties$8 = { "^label\\.[^.]+$": { "$ref": "#/$defs/labelDef" }, "^disabled\\.[^.]+$": { "$ref": "#/$defs/disabledDef" }, "^readonly\\.[^.]+$": { "$ref": "#/$defs/readonlyDef" }, "^validator\\.[^.]+$": { "$ref": "../validators.schema.json#/$defs/validator" } };
@@ -842,7 +848,7 @@ const $schema$6 = "https://json-schema.org/draft/2020-12/schema";
 const $id$6 = "https://golemui.com/schemas/components/repeater.schema.json";
 const title$6 = "Repeater Widget";
 const type$6 = "object";
-const $defs$6 = { "labelDef": { "$ref": "../common.schema.json#/$defs/localizable" }, "addLabelProp": { "$ref": "../common.schema.json#/$defs/localizable" }, "removeLabelProp": { "$ref": "../common.schema.json#/$defs/localizable" }, "limitProp": { "type": "number" }, "templateProp": { "$ref": "../layout-widget.schema.json" }, "titleProp": { "$ref": "../common.schema.json#/$defs/localizable" }, "addButtonIconProp": { "type": "string" }, "removeButtonIconProp": { "type": "string" } };
+const $defs$6 = { "labelDef": { "$ref": "../common.schema.json#/$defs/localizable" }, "addLabelProp": { "description": "Label for the button that adds a new repeated item", "$ref": "../common.schema.json#/$defs/localizable" }, "removeLabelProp": { "description": "Label for the button that removes an existing repeated item", "$ref": "../common.schema.json#/$defs/localizable" }, "limitProp": { "type": "number", "description": "Maximum number of items the user can add. No limit when omitted." }, "templateProp": { "description": "Widget tree used as the template for each repeated item. Paths inside are resolved relative to the item's index in the array.", "$ref": "../layout-widget.schema.json" }, "titleProp": { "description": "Title displayed in the header of each item panel (supports reactive expressions referencing the item's index via `$index`)", "$ref": "../common.schema.json#/$defs/localizable" }, "addButtonIconProp": { "type": "string", "description": "Icon name or CSS class for the add-item button icon" }, "removeButtonIconProp": { "type": "string", "description": "Icon name or CSS class for the remove-item button icon" } };
 const allOf$6 = [{ "$ref": "../common.schema.json#/$defs/baseWidget" }];
 const properties$6 = { "kind": { "const": "input" }, "type": { "const": "repeater" }, "path": { "$ref": "../common.schema.json#/$defs/dotPath" }, "label": { "$ref": "#/$defs/labelDef" }, "on": { "$ref": "../common.schema.json#/$defs/on" }, "validator": { "$ref": "../validators.schema.json#/$defs/validator" }, "props": { "type": "object", "properties": { "addLabel": { "$ref": "#/$defs/addLabelProp" }, "removeLabel": { "$ref": "#/$defs/removeLabelProp" }, "limit": { "$ref": "#/$defs/limitProp" }, "template": { "$ref": "#/$defs/templateProp" }, "title": { "$ref": "#/$defs/titleProp" }, "addButtonIcon": { "$ref": "#/$defs/addButtonIconProp" }, "removeButtonIcon": { "$ref": "#/$defs/removeButtonIconProp" } }, "required": ["template"], "patternProperties": { "^addLabel\\.[^.]+$": { "$ref": "#/$defs/addLabelProp" }, "^removeLabel\\.[^.]+$": { "$ref": "#/$defs/removeLabelProp" }, "^limit\\.[^.]+$": { "$ref": "#/$defs/limitProp" }, "^template\\.[^.]+$": { "$ref": "#/$defs/templateProp" }, "^title\\.[^.]+$": { "$ref": "#/$defs/titleProp" }, "^addButtonIcon\\.[^.]+$": { "$ref": "#/$defs/addButtonIconProp" }, "^removeButtonIcon\\.[^.]+$": { "$ref": "#/$defs/removeButtonIconProp" } }, "additionalProperties": false } };
 const patternProperties$5 = { "^label\\.[^.]+$": { "$ref": "#/$defs/labelDef" }, "^validator\\.[^.]+$": { "$ref": "../validators.schema.json#/$defs/validator" } };
@@ -864,7 +870,7 @@ const $schema$5 = "https://json-schema.org/draft/2020-12/schema";
 const $id$5 = "https://golemui.com/schemas/components/select.schema.json";
 const title$5 = "Select Widget";
 const type$5 = "object";
-const $defs$5 = { "disabledDef": { "$ref": "../common.schema.json#/$defs/boolOrWhen" }, "readonlyDef": { "$ref": "../common.schema.json#/$defs/boolOrWhen" }, "labelDef": { "$ref": "../common.schema.json#/$defs/localizable" }, "hintProp": { "$ref": "../common.schema.json#/$defs/localizable" }, "iconProp": { "type": "string" }, "optionsProp": { "type": "array", "description": "Options may be primitive values (string/number), structured `{ label, value }` records, or arbitrary objects (paired with `labelField`/`valueField` for custom rendering).", "items": { "type": ["string", "number", "object"] } }, "placeholderProp": { "$ref": "../common.schema.json#/$defs/localizable" }, "labelFieldProp": { "type": "string" }, "valueFieldProp": { "type": "string" }, "autocompleteProp": { "type": "string" } };
+const $defs$5 = { "disabledDef": { "$ref": "../common.schema.json#/$defs/boolOrWhen" }, "readonlyDef": { "$ref": "../common.schema.json#/$defs/boolOrWhen" }, "labelDef": { "$ref": "../common.schema.json#/$defs/localizable" }, "hintProp": { "$ref": "../common.schema.json#/$defs/localizable" }, "iconProp": { "type": "string" }, "optionsProp": { "type": "array", "description": "Options may be primitive values (string/number), structured `{ label, value }` records, or arbitrary objects (paired with `labelField`/`valueField` for custom rendering).", "items": { "type": ["string", "number", "object"] } }, "placeholderProp": { "$ref": "../common.schema.json#/$defs/localizable" }, "labelFieldProp": { "type": "string", "description": 'Object property used as the display label when options are objects (e.g. `"name"` reads `item.name`)' }, "valueFieldProp": { "type": "string", "description": 'Object property used as the stored value when options are objects (e.g. `"id"` stores `item.id`)' }, "autocompleteProp": { "type": "string", "description": "HTML `autocomplete` attribute applied to the underlying input element" } };
 const allOf$5 = [{ "$ref": "../common.schema.json#/$defs/baseWidget" }];
 const properties$5 = { "kind": { "const": "input" }, "type": { "const": "select" }, "path": { "$ref": "../common.schema.json#/$defs/dotPath" }, "label": { "$ref": "#/$defs/labelDef" }, "disabled": { "$ref": "#/$defs/disabledDef" }, "readonly": { "$ref": "#/$defs/readonlyDef" }, "on": { "$ref": "../common.schema.json#/$defs/on" }, "validator": { "$ref": "../validators.schema.json#/$defs/validator" }, "props": { "type": "object", "properties": { "hint": { "$ref": "#/$defs/hintProp" }, "icon": { "$ref": "#/$defs/iconProp" }, "options": { "$ref": "#/$defs/optionsProp" }, "placeholder": { "$ref": "#/$defs/placeholderProp" }, "labelField": { "$ref": "#/$defs/labelFieldProp" }, "valueField": { "$ref": "#/$defs/valueFieldProp" }, "autocomplete": { "$ref": "#/$defs/autocompleteProp" } }, "patternProperties": { "^hint\\.[^.]+$": { "$ref": "#/$defs/hintProp" }, "^icon\\.[^.]+$": { "$ref": "#/$defs/iconProp" }, "^options\\.[^.]+$": { "$ref": "#/$defs/optionsProp" }, "^placeholder\\.[^.]+$": { "$ref": "#/$defs/placeholderProp" }, "^labelField\\.[^.]+$": { "$ref": "#/$defs/labelFieldProp" }, "^valueField\\.[^.]+$": { "$ref": "#/$defs/valueFieldProp" }, "^autocomplete\\.[^.]+$": { "$ref": "#/$defs/autocompleteProp" } }, "additionalProperties": false } };
 const patternProperties$4 = { "^label\\.[^.]+$": { "$ref": "#/$defs/labelDef" }, "^disabled\\.[^.]+$": { "$ref": "#/$defs/disabledDef" }, "^readonly\\.[^.]+$": { "$ref": "#/$defs/readonlyDef" }, "^validator\\.[^.]+$": { "$ref": "../validators.schema.json#/$defs/validator" } };
@@ -886,9 +892,9 @@ const $schema$4 = "https://json-schema.org/draft/2020-12/schema";
 const $id$4 = "https://golemui.com/schemas/components/tabs.schema.json";
 const title$4 = "Tabs Widget";
 const type$4 = "object";
-const $defs$4 = { "defaultOpenProp": { "type": "string" }, "renderModeProp": { "enum": ["all", "activeOnly"] }, "tabsProp": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "label": { "$ref": "../common.schema.json#/$defs/localizable" }, "uid": { "type": "string" } }, "required": ["label", "uid"], "additionalProperties": false } } };
+const $defs$4 = { "defaultOpenProp": { "type": "string", "description": "UID of the tab that is active on initial render. Defaults to the first tab." }, "renderModeProp": { "description": "Controls when tab content is rendered: `all` keeps all tabs in the DOM, `activeOnly` unmounts inactive ones", "enum": ["all", "activeOnly"] }, "tabsProp": { "type": "array", "description": "Ordered list of tab definitions. Each tab's `uid` must match the widget UIDs used in `children`.", "minItems": 1, "items": { "type": "object", "properties": { "label": { "$ref": "../common.schema.json#/$defs/localizable" }, "uid": { "type": "string", "description": "Unique identifier linking this tab definition to its widgets in `children`" } }, "required": ["label", "uid"], "additionalProperties": false } } };
 const allOf$4 = [{ "$ref": "../common.schema.json#/$defs/baseWidget" }];
-const properties$4 = { "kind": { "const": "layout" }, "type": { "const": "tabs" }, "on": { "$ref": "../common.schema.json#/$defs/on" }, "children": { "type": "array", "minItems": 1, "items": { "$ref": "../form.schema.json#/$defs/formWidget" } }, "props": { "type": "object", "properties": { "defaultOpen": { "$ref": "#/$defs/defaultOpenProp" }, "renderMode": { "$ref": "#/$defs/renderModeProp" }, "tabs": { "$ref": "#/$defs/tabsProp" } }, "required": ["tabs"], "patternProperties": { "^defaultOpen\\.[^.]+$": { "$ref": "#/$defs/defaultOpenProp" }, "^renderMode\\.[^.]+$": { "$ref": "#/$defs/renderModeProp" }, "^tabs\\.[^.]+$": { "$ref": "#/$defs/tabsProp" } }, "additionalProperties": false } };
+const properties$4 = { "kind": { "const": "layout" }, "type": { "const": "tabs" }, "on": { "$ref": "../common.schema.json#/$defs/on" }, "children": { "type": "array", "description": "Flat list of widgets belonging to all tabs. Each widget must have a `uid` matching one of the tab UIDs in `props.tabs`.", "minItems": 1, "items": { "$ref": "../form.schema.json#/$defs/formWidget" } }, "props": { "type": "object", "properties": { "defaultOpen": { "$ref": "#/$defs/defaultOpenProp" }, "renderMode": { "$ref": "#/$defs/renderModeProp" }, "tabs": { "$ref": "#/$defs/tabsProp" } }, "required": ["tabs"], "patternProperties": { "^defaultOpen\\.[^.]+$": { "$ref": "#/$defs/defaultOpenProp" }, "^renderMode\\.[^.]+$": { "$ref": "#/$defs/renderModeProp" }, "^tabs\\.[^.]+$": { "$ref": "#/$defs/tabsProp" } }, "additionalProperties": false } };
 const required$4 = ["kind", "type", "children", "props"];
 const unevaluatedProperties$4 = false;
 const tabs = {
@@ -906,7 +912,7 @@ const $schema$3 = "https://json-schema.org/draft/2020-12/schema";
 const $id$3 = "https://golemui.com/schemas/components/tags.schema.json";
 const title$3 = "Tags Widget";
 const type$3 = "object";
-const $defs$3 = { "disabledDef": { "$ref": "../common.schema.json#/$defs/boolOrWhen" }, "readonlyDef": { "$ref": "../common.schema.json#/$defs/boolOrWhen" }, "labelDef": { "$ref": "../common.schema.json#/$defs/localizable" }, "hintProp": { "$ref": "../common.schema.json#/$defs/localizable" }, "placeholderProp": { "$ref": "../common.schema.json#/$defs/localizable" }, "iconProp": { "type": "string" }, "separatorsProp": { "type": "array", "items": { "type": "string" } }, "allowDuplicatesProp": { "type": "boolean" }, "trimProp": { "type": "boolean" }, "limitProp": { "type": "number" }, "removeAriaLabelProp": { "$ref": "../common.schema.json#/$defs/localizable" }, "removeIconProp": { "type": "string" } };
+const $defs$3 = { "disabledDef": { "$ref": "../common.schema.json#/$defs/boolOrWhen" }, "readonlyDef": { "$ref": "../common.schema.json#/$defs/boolOrWhen" }, "labelDef": { "$ref": "../common.schema.json#/$defs/localizable" }, "hintProp": { "$ref": "../common.schema.json#/$defs/localizable" }, "placeholderProp": { "$ref": "../common.schema.json#/$defs/localizable" }, "iconProp": { "type": "string" }, "separatorsProp": { "type": "array", "description": 'Characters or strings that trigger a new tag when typed (e.g. `[",", " "]`). Defaults to Enter key only.', "items": { "type": "string" } }, "allowDuplicatesProp": { "type": "boolean", "description": "When true, the same tag value may be added more than once. Defaults to false." }, "trimProp": { "type": "boolean", "description": "When true, whitespace is trimmed from each tag before it is added. Defaults to true." }, "limitProp": { "type": "number", "description": "Maximum number of tags the user can add. No limit when omitted." }, "removeAriaLabelProp": { "$ref": "../common.schema.json#/$defs/localizable" }, "removeIconProp": { "type": "string" } };
 const allOf$3 = [{ "$ref": "../common.schema.json#/$defs/baseWidget" }];
 const properties$3 = { "kind": { "const": "input" }, "type": { "const": "tags" }, "path": { "$ref": "../common.schema.json#/$defs/dotPath" }, "label": { "$ref": "#/$defs/labelDef" }, "disabled": { "$ref": "#/$defs/disabledDef" }, "readonly": { "$ref": "#/$defs/readonlyDef" }, "on": { "$ref": "../common.schema.json#/$defs/on" }, "validator": { "$ref": "../validators.schema.json#/$defs/validator" }, "defaultValue": { "type": "array", "items": { "type": "string" } }, "props": { "type": "object", "properties": { "hint": { "$ref": "#/$defs/hintProp" }, "placeholder": { "$ref": "#/$defs/placeholderProp" }, "icon": { "$ref": "#/$defs/iconProp" }, "separators": { "$ref": "#/$defs/separatorsProp" }, "allowDuplicates": { "$ref": "#/$defs/allowDuplicatesProp" }, "trim": { "$ref": "#/$defs/trimProp" }, "limit": { "$ref": "#/$defs/limitProp" }, "removeAriaLabel": { "$ref": "#/$defs/removeAriaLabelProp" }, "removeIcon": { "$ref": "#/$defs/removeIconProp" } }, "patternProperties": { "^hint\\.[^.]+$": { "$ref": "#/$defs/hintProp" }, "^placeholder\\.[^.]+$": { "$ref": "#/$defs/placeholderProp" }, "^icon\\.[^.]+$": { "$ref": "#/$defs/iconProp" }, "^separators\\.[^.]+$": { "$ref": "#/$defs/separatorsProp" }, "^allowDuplicates\\.[^.]+$": { "$ref": "#/$defs/allowDuplicatesProp" }, "^trim\\.[^.]+$": { "$ref": "#/$defs/trimProp" }, "^limit\\.[^.]+$": { "$ref": "#/$defs/limitProp" }, "^removeAriaLabel\\.[^.]+$": { "$ref": "#/$defs/removeAriaLabelProp" }, "^removeIcon\\.[^.]+$": { "$ref": "#/$defs/removeIconProp" } }, "additionalProperties": false } };
 const patternProperties$3 = { "^disabled\\.[^.]+$": { "$ref": "#/$defs/disabledDef" }, "^readonly\\.[^.]+$": { "$ref": "#/$defs/readonlyDef" }, "^label\\.[^.]+$": { "$ref": "#/$defs/labelDef" }, "^validator\\.[^.]+$": { "$ref": "../validators.schema.json#/$defs/validator" } };
@@ -1410,13 +1416,13 @@ function dedupe(errors) {
 }
 function lintReactiveExpressions(formDefinition) {
   const findings = [];
-  walk(formDefinition, "", findings);
+  walk$1(formDefinition, "", findings);
   return findings;
 }
-function walk(node, path, out) {
+function walk$1(node, path, out) {
   if (node === null || typeof node !== "object") return;
   if (Array.isArray(node)) {
-    node.forEach((item, i) => walk(item, `${path}/${i}`, out));
+    node.forEach((item, i) => walk$1(item, `${path}/${i}`, out));
     return;
   }
   const obj = node;
@@ -1444,7 +1450,7 @@ function walk(node, path, out) {
       }
     }
     if (typeof v === "object" && v !== null) {
-      walk(v, `${path}/${k}`, out);
+      walk$1(v, `${path}/${k}`, out);
     }
   }
 }
@@ -1477,12 +1483,12 @@ function checkExpression(expr, path, out) {
     });
     return;
   }
-  if (!/\$form\b|\$meta\b|\$item\b|\$index\b/.test(trimmed)) {
+  if (!/\$form\b|\$meta\b|\$formIsInvalid\b/.test(trimmed)) {
     out.push({
       path,
       expression: expr,
-      message: "Expression does not reference `$form`, `$meta`, `$item`, or `$index`.",
-      suggestion: "GolemUI expressions read form data via `$form.fieldName` or form metadata via `$meta.key`. Did you forget the prefix?"
+      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)) {
@@ -1509,15 +1515,15 @@ function checkExpression(expr, path, out) {
       suggestion: "Use strict equality `===` / `!==` to avoid type coercion (e.g. `$form.x !== undefined` rather than `$form.x != null`)."
     });
   }
-  if (/(?<![=!])!\s*\$(?:form|meta|item|index)\b/.test(trimmed)) {
+  if (/(?<![=!])!\s*\$(?:form|meta)\b/.test(trimmed)) {
     out.push({
       path,
       expression: expr,
-      message: "Expression negates a `$form`/`$meta`/`$item`/`$index` reference (relies on truthy/falsy coercion).",
+      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|item|index)((?:\.[\w?]+)*)/g;
+  const refChainRe = /\$(?:form|meta)\b((?:\.[\w?]+)*)/g;
   let chainFlagged = false;
   let chainMatch;
   while ((chainMatch = refChainRe.exec(trimmed)) !== null) {
@@ -1542,9 +1548,9 @@ function checkExpression(expr, path, out) {
       chainFlagged = true;
     }
   }
-  const refOnly = /^\$(?:form|meta|item|index)(?:\.[\w?]+)*$/;
-  const refBeforeBool = /\$(?:form|meta|item|index)(?:\.[\w?]+)*\s*(?:&&|\|\||\?(?![.?]))/;
-  const refAfterBool = /(?:&&|\|\|)\s*\$(?:form|meta|item|index)(?:\.[\w?]+)*\s*$/;
+  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,
@@ -1553,7 +1559,7 @@ function checkExpression(expr, path, out) {
       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|item)(?:\.[\w?]+)+/g;
+  const refForCmpRe = /\$(?:form|meta)(?:\.[\w?]+)+/g;
   let r5Flagged = false;
   let cmpMatch;
   while ((cmpMatch = refForCmpRe.exec(trimmed)) !== null) {
@@ -1576,11 +1582,128 @@ function checkExpression(expr, path, out) {
     }
   }
 }
+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)) {
+    node.forEach((item, i) => walk(item, `${path}/${i}`, out));
+    return;
+  }
+  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);
+      }
+    }
+  }
+  for (const [key, value] of Object.entries(obj)) {
+    if (key === "params" && isTranslationConfig) {
+      continue;
+    }
+    if (key === "defaultValue" || key.startsWith("defaultValue.")) {
+      continue;
+    }
+    const childPath = `${path}/${key}`;
+    if (typeof value === "string") {
+      checkTemplate(value, childPath, out);
+    } else {
+      walk(value, childPath, out);
+    }
+  }
+}
+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?"
+    });
+  }
+}
+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 (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);
+  }
+}
+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,
+      slot,
+      message: "Interpolation slot contains a single `=` (assignment).",
+      suggestion: "Template slots are read-only. Did you mean `===` for equality?"
+    });
+  }
+}
 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: "/",
@@ -1592,12 +1715,13 @@ function validateFormDefinition(input) {
     valid: errors.length === 0,
     errors,
     warnings,
-    expressionWarnings
+    expressionWarnings,
+    interpolationWarnings
   };
 }
 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 }`. 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`.",
+  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: {
@@ -1775,7 +1899,7 @@ function resolveLocalRef(ref, doc) {
 }
 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 validated form definition. Falls back to operation parameters when no request body is present. Pass either a parsed `document` or a `documentUrl` to fetch.',
+  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: {
@@ -1804,6 +1928,298 @@ const GENERATE_FROM_OPENAPI_TOOL = {
     required: ["operation"]
   }
 };
+const STATES_CONCEPT = {
+  concept: "states",
+  summary: "States are named boolean conditions declared at the form root. Each state name maps to a reactive expression string (using `$form`, `$meta`, or `$formIsInvalid`) that the runtime evaluates continuously as the user interacts with the form. Once declared, state names can gate widget visibility (include / exclude) and swap individual widget properties per-state — a capability unique to named states that has no inline `when` equivalent.",
+  patterns: [
+    {
+      name: "Declare states at the form root",
+      description: 'Add a `"states"` object to the top-level form definition. Each key is a state name; each value is a reactive expression string. Expressions are evaluated at runtime — they have access to `$form` (all current form values), `$meta` (host-supplied metadata), and `$formIsInvalid` (built-in boolean — `true` when any field currently fails validation). State names can contain letters, numbers, hyphens, and underscores. Colons enable hierarchical composition — see the "Composed sub-states (colon notation)" pattern below.',
+      example: {
+        $schema: "https://golemui.com/schemas/form.schema.json",
+        states: {
+          termsAccepted: "$form.terms === true",
+          hasDiscount: "$form.hasDiscountCode === true",
+          limitReached: "$form.users?.length === 5"
+        },
+        form: ["/* ... widgets ... */"]
+      }
+    },
+    {
+      name: "Composed sub-states (colon notation)",
+      description: 'Colons in a state name denote hierarchy: `"register"`, `"register:adult"`, `"register:minor:tall"`. At runtime the form engine rewrites every child expression by ANDing the full ancestor chain in front of it. This means you write only the *incremental* condition in a child — the parent conditions are inherited automatically. A child state is active only when ALL of its ancestors are also active.',
+      example: {
+        // What you write in the form definition:
+        statesAsAuthored: {
+          register: "$form.agreeTerms === true",
+          "register:adult": "$form.user?.age >= 18",
+          "register:minor": "$form.user?.age < 18",
+          "register:minor:tall": "$form.user?.height > 180"
+        },
+        // What the runtime actually evaluates (expandStateExpressions output):
+        statesAtRuntime: {
+          register: "($form.agreeTerms === true)",
+          "register:adult": "($form.agreeTerms === true) && ($form.user?.age >= 18)",
+          "register:minor": "($form.agreeTerms === true) && ($form.user?.age < 18)",
+          "register:minor:tall": "($form.agreeTerms === true) && ($form.user?.age < 18) && ($form.user?.height > 180)"
+        }
+      }
+    },
+    {
+      name: "Conditional rendering with include / exclude",
+      description: 'Use `"include": { "in": ["stateName"] }` on any widget to render it only when the named state is active. Use `"exclude": { "from": ["stateName"] }` to render it only when the state is NOT active. Both `in` and `from` are arrays — a widget can be gated on multiple states simultaneously. Prefer the named-state form (`in`/`from`) over the inline `when` expression when the same condition applies to several widgets; use `when` for one-off conditions with no reuse.',
+      example: {
+        $schema: "https://golemui.com/schemas/form.schema.json",
+        states: {
+          hasDiscount: "$form.hasDiscountCode === true"
+        },
+        form: [
+          {
+            kind: "input",
+            type: "checkbox",
+            path: "hasDiscountCode",
+            label: "I have a discount code"
+          },
+          {
+            kind: "input",
+            type: "textinput",
+            path: "discountCode",
+            label: "Discount code",
+            include: { in: ["hasDiscount"] }
+          },
+          {
+            kind: "display",
+            type: "alert",
+            props: { text: "No discount applied." },
+            exclude: { from: ["hasDiscount"] }
+          }
+        ]
+      }
+    },
+    {
+      name: "State-suffixed props",
+      description: 'Override individual widget properties when a named state is active by appending `".<stateName>"` to the property key. The unsuffixed key holds the default value; each suffixed key supplies the override for that state. This works on root-level widget properties (`label`, `disabled`, `readonly`, `validator`, `size`) AND on any key inside the `props` object (`hint`, `placeholder`, `items`, `addLabel`, etc.). There is NO inline `when` equivalent for this — state-suffixed props REQUIRE a named state. Multiple suffixes can coexist on the same property; when more than one state is active, the last matching suffix in document order wins.',
+      example: {
+        $schema: "https://golemui.com/schemas/form.schema.json",
+        states: {
+          termsAccepted: "$form.terms === true",
+          busy: "$meta.submitting === true"
+        },
+        form: [
+          {
+            kind: "input",
+            type: "checkbox",
+            path: "terms",
+            label: "I accept the terms"
+          },
+          {
+            kind: "action",
+            type: "button",
+            label: "Submit",
+            "label.termsAccepted": "Submit ✓",
+            "label.busy": "Submitting…",
+            disabled: true,
+            "disabled.termsAccepted": false,
+            "disabled.busy": true
+          },
+          {
+            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"
+                }
+              }
+            }
+          }
+        ]
+      }
+    }
+  ],
+  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."
+  ]
+};
+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",
@@ -2021,7 +2437,8 @@ const EXAMPLES = {
 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`."
+    "`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`.",
@@ -2053,13 +2470,19 @@ const NOTES = {
   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>"`.'
+    '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.'
+    '`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)."]
+  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"];
@@ -2115,11 +2538,13 @@ const TOOLS = [
   VALIDATE_FORM_DEFINITION_TOOL,
   GENERATE_FROM_JSON_SCHEMA_TOOL,
   GENERATE_FROM_OPENAPI_TOOL,
-  GET_WIDGET_SPEC_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: {} } }
+  { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS }
 );
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -2134,6 +2559,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         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}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@golemui/gui-mcp",
-  "version": "0.15.1",
+  "version": "0.16.0",
   "description": "Model Context Protocol server for GolemUI — gives AI coding assistants deterministic schema validation and form generation for GolemUI form definitions.",
   "type": "module",
   "main": "./index.js",
@@ -31,7 +31,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "ajv": "^8.17.1",
-    "ajv-formats": "^3.0.1"
+    "ajv-formats": "^3.0.1",
+    "@golemui/gui-schemas": "0.16.0"
   },
   "engines": {
     "node": ">=18.0.0"