@golemui/gui-mcp 0.16.2 → 1.0.0-rc.0

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+## 0.17.0 (2026-06-08)
+
+### 🩹 Fixes
+
+- **mcp:** fill documentation gaps and deduplicate get_concept/get_widget_spec tools ([#153](https://github.com/golemui/golemui/pull/153))
+
+### ❤️ Thank You
+
+- Mud Scientist @mudscientist
+- Raúl Jiménez @Elecash
+
+## 0.16.2 (2026-05-30)
+
+### 🩹 Fixes
+
+- **mcp:** add missing rollup-generated chunk files ([#147](https://github.com/golemui/golemui/pull/147))
+
+### ❤️ Thank You
+
+- Mud Scientist @mudscientist
+
 ## 0.16.1 (2026-05-30)
 
 ### 🚀 Features

package/cli.js

@@ -5,7 +5,7 @@ import { fileURLToPath } from "node:url";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
-import { V as VALIDATE_FORM_DEFINITION_TOOL, G as GENERATE_FROM_JSON_SCHEMA_TOOL, b as GENERATE_FROM_OPENAPI_TOOL, d as GET_WIDGET_SPEC_TOOL, f as GET_CONCEPT_TOOL, e as getConcept, c as getWidgetSpec, a as generateFromOpenapi, g as generateFromJsonSchema, v as validateFormDefinition } from "./get-concept-CHgtnDXr.js";
+import { V as VALIDATE_FORM_DEFINITION_TOOL, G as GENERATE_FROM_JSON_SCHEMA_TOOL, b as GENERATE_FROM_OPENAPI_TOOL, d as GET_WIDGET_SPEC_TOOL, f as GET_CONCEPT_TOOL, e as getConcept, c as getWidgetSpec, a as generateFromOpenapi, g as generateFromJsonSchema, v as validateFormDefinition } from "./get-concept-ChE67L3a.js";
 function readPackageMeta() {
   const here = dirname(fileURLToPath(import.meta.url));
   for (const candidate of [join(here, "package.json"), join(here, "..", "package.json")]) {

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

@@ -482,7 +482,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": { "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 $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.", "$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" } };
@@ -781,7 +781,18 @@ function rewriteRefs(node, baseId) {
   }
   for (const v of Object.values(obj)) rewriteRefs(v, baseId);
 }
-const STRING_FORMATS = ["email", "hostname", "ipv4", "ipv6", "url", "uuid", "date", "time", "date-time", "duration"];
+const STRING_FORMATS = [
+  "email",
+  "hostname",
+  "ipv4",
+  "ipv6",
+  "url",
+  "uuid",
+  "date",
+  "time",
+  "date-time",
+  "duration"
+];
 const WIDGET_TYPES = Object.keys(COMPONENT_SCHEMAS);
 function levenshtein(a, b) {
   if (a === b) return 0;
@@ -817,7 +828,25 @@ function nearest(target, candidates) {
 }
 function suggestForAdditional(propertyName, instancePath) {
   if (/\/validator(\/|$)/.test(instancePath)) {
-    const validatorKeys = ["type", "required", "minLength", "maxLength", "minimum", "maximum", "pattern", "format", "const", "enum", "messages", "minItems", "maxItems", "uniqueItems", "multipleOf", "exclusiveMinimum", "exclusiveMaximum"];
+    const validatorKeys = [
+      "type",
+      "required",
+      "minLength",
+      "maxLength",
+      "minimum",
+      "maximum",
+      "pattern",
+      "format",
+      "const",
+      "enum",
+      "messages",
+      "minItems",
+      "maxItems",
+      "uniqueItems",
+      "multipleOf",
+      "exclusiveMinimum",
+      "exclusiveMaximum"
+    ];
     const guess = nearest(propertyName, validatorKeys);
     if (guess && guess !== propertyName) return `Did you mean \`${guess}\`?`;
     return void 0;
@@ -829,7 +858,8 @@ function suggestForEnum(value, allowed) {
   const stringAllowed = allowed.filter((v) => typeof v === "string");
   if (!stringAllowed.length) return void 0;
   const guess = nearest(value, stringAllowed);
-  if (guess) return `Did you mean \`${guess}\`? Allowed values: ${stringAllowed.map((v) => `\`${v}\``).join(", ")}.`;
+  if (guess)
+    return `Did you mean \`${guess}\`? Allowed values: ${stringAllowed.map((v) => `\`${v}\``).join(", ")}.`;
   return `Allowed values: ${stringAllowed.map((v) => `\`${v}\``).join(", ")}.`;
 }
 const VALIDATOR_TYPES = ["string", "number", "integer", "boolean", "array", "custom"];
@@ -959,15 +989,13 @@ function collectWidgetErrors(widget, widgetPath, out, warnings) {
   if (!intended) {
     const widgetType = widget?.type;
     if (typeof widgetType !== "string" || !widgetType) {
-      out.push(
-        {
-          keyword: "required",
-          instancePath: widgetPath,
-          schemaPath: "",
-          params: { missingProperty: "type" },
-          message: `Widget at ${widgetPath} is missing or has an invalid \`type\``
-        }
-      );
+      out.push({
+        keyword: "required",
+        instancePath: widgetPath,
+        schemaPath: "",
+        params: { missingProperty: "type" },
+        message: `Widget at ${widgetPath} is missing or has an invalid \`type\``
+      });
     } else {
       warnings.push({
         path: `${widgetPath}/type`,
@@ -1805,7 +1833,9 @@ async function generateFromOpenapi(input) {
 async function fetchDoc(url) {
   const res = await fetch(url);
   if (!res.ok) {
-    throw new Error(`Failed to fetch OpenAPI document from ${url}: ${res.status} ${res.statusText}`);
+    throw new Error(
+      `Failed to fetch OpenAPI document from ${url}: ${res.status} ${res.statusText}`
+    );
   }
   const text = await res.text();
   try {
@@ -2139,7 +2169,8 @@ const NOTES = {
   textinput: [
     "`path` is the dot-path into form data this field writes to.",
     "`validator.format` supports: `email`, `hostname`, `ipv4`, `ipv6`, `url`, `uuid`, `date`, `time`, `date-time`, `duration`.",
-    'Root props `label`, `disabled`, `readonly`, `validator`, and `size` accept state suffixes — e.g. `"label.<stateName>": "New label"` overrides the label only when that named state is active. Props inside `props` (e.g. `hint`, `placeholder`) also accept suffixes as `"hint.<stateName>"`. Call `get_concept({ concept: "states" })` for the full pattern.'
+    '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.',
+    '`props.icon` accepts a Google Material Icons ligature name (e.g. `"search"`, `"email"`, `"lock"`) to display a decorative icon inside the input field. Supports state suffix: `"icon.<stateName>": "check"` to swap the icon when a state is active. Call `get_concept({ concept: "icons" })` for setup and the full list of icon-capable widgets.'
   ],
   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`.",
@@ -2158,8 +2189,24 @@ const NOTES = {
     '`props.options[]` is the simple form: `[{ label: "United States", value: "us" }, ...]`. Use this for ANY plain text list — countries, plans, sizes, status enums. Only switch to `dropdown` if you need custom per-item rendering (icons, flags, rich layouts).',
     "For very large lists (>50 items) consider `dropdown` for its virtualization (`height`, `itemHeight`, `searchFields`)."
   ],
-  flex: ["`children` is an array of any widgets (inputs, displays, nested layouts)."],
-  grid: ["`children` is an array of any widgets. `props.columns` controls layout."],
+  flex: [
+    "Use `flex` for page scaffolding and directional grouping: a column stack of sections, a row of side-by-side panels, a row of action buttons. For field-level layout (inputs that should sit in columns with aligned labels), prefer `grid` instead.",
+    '`props.direction`: `"row"` (default) | `"column"` | `"row-reverse"` | `"column-reverse"` — controls the main axis. `"column"` stacks children vertically; `"row"` places them side by side.',
+    "`props.gap`: number (pixels) — uniform spacing between all children along the main axis.",
+    '`props.justify`: `"center"` | `"start"` | `"end"` | `"stretch"` — aligns children along the cross-axis (perpendicular to `direction`).',
+    '`props.align`: `"center"` | `"start"` | `"end"` | `"space-between"` | `"space-around"` | `"space-evenly"` — distributes children along the main axis.',
+    'All `flex` props support state suffixes: `"direction.<stateName>": "column"` swaps the direction when a state is active. Call `get_concept({ concept: "states" })` for the full pattern.'
+  ],
+  grid: [
+    "Use `grid` when you want multiple form fields to sit side by side with their labels and inputs aligned across columns. GolemUI's `grid` uses CSS subgrid internally: each child widget gets two implicit sub-tracks (one for its label, one for its input) that align to the parent grid columns, giving consistent label/input alignment across all rows without manual sizing.",
+    "For loose page scaffolding — stacking sections, wrapping a group in a header — use `flex` instead.",
+    "`props.columnGap`: number (pixels) — horizontal gap between columns.",
+    "`props.rowGap`: number (pixels) — vertical gap between rows.",
+    "`props.autoFit`: boolean — when `true`, the grid auto-fits as many columns as will fit in the available container width, using `columnGap` as the gutter. Useful for responsive layouts where the number of columns should adapt to the viewport.",
+    '`props.direction`: `"row"` | `"column"` — controls how children flow into the grid tracks.',
+    "`props.align` and `props.justify` accept the same values as `flex`.",
+    'All `grid` props support state suffixes. Call `get_concept({ concept: "states" })` for the full pattern.'
+  ],
   tabs: [
     "Children are associated with tabs by **`uid` matching**, not by array order: each direct child must have a `uid` field at the widget level (alongside `kind`/`type`) whose string value equals one of the `props.tabs[].uid` entries. There is no `tag` property — that is not a real GolemUI field.",
     "Children are typically written in display order for readability, but rearranging them does not change which tab they belong to — only the `uid` string match does."
@@ -2177,7 +2224,8 @@ const NOTES = {
   button: [
     "`actionType` controls the button's role. `actionType: \"submit\"` makes the button fire the form's `formSubmit` event natively — the host listens for it via `(formSubmit)` (Angular), `@formSubmit` (Vue), `onFormSubmit` (React), or the `form-submit` event (Lit). No custom handler needed. Use this for the primary submit button on a form.",
     '`actionType: "button"` (the default, can be omitted) is a regular action button. Wire it via `on.click: "<handlerName>"` where `<handlerName>` is registered in the form config\'s event handlers.',
-    'Supports state-suffixed props: `"label.<stateName>"` and `"disabled.<stateName>"` swap the label or disabled state when a named state is active — e.g. disable the submit button until terms are accepted, then re-enable it. Call `get_concept({ concept: "states" })` for the full pattern.'
+    '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.',
+    '`props.icon` accepts a Google Material Icons ligature name (e.g. `"send"`, `"check"`, `"arrow_forward"`) to render an icon on the button. `props.iconPosition` controls placement: `"left"` (default) or `"right"`. Both support state suffixes: `"icon.<stateName>": "hourglass_empty"` swaps the icon while a state is active. Call `get_concept({ concept: "icons" })` for setup instructions and the full list of icon-capable widgets.'
   ],
   checkbox: ["Set `validator.const: true` to require the user to tick it (e.g. terms acceptance)."],
   alert: [
@@ -2229,7 +2277,7 @@ const STATES_CONCEPT = {
   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.',
+      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`. 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: {
@@ -2261,8 +2309,8 @@ const STATES_CONCEPT = {
       }
     },
     {
-      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.',
+      name: "Conditional rendering with include / exclude (named-state form)",
+      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.',
       example: {
         $schema: "https://golemui.com/schemas/form.schema.json",
         states: {
@@ -2291,6 +2339,37 @@ const STATES_CONCEPT = {
         ]
       }
     },
+    {
+      name: "Inline conditional rendering with `when`",
+      description: 'For a one-off condition that applies to a single widget only, use the inline `when` form: `"include": { "when": "expression" }` or `"exclude": { "when": "expression" }`. The expression is evaluated exactly like a state expression — it has access to `$form`, `$meta`, and `$formIsInvalid`, uses the same safe operator subset, and must use optional chaining for nested fields. No entry in the root `states` map is required. Use this form when the condition is not shared with any other widget; use the named-state form (`in`/`from`) when the same condition gates two or more widgets.',
+      example: {
+        $schema: "https://golemui.com/schemas/form.schema.json",
+        form: [
+          {
+            kind: "input",
+            type: "checkbox",
+            path: "agreeTerms",
+            label: "I agree to the terms"
+          },
+          {
+            kind: "action",
+            type: "button",
+            actionType: "submit",
+            label: "Continue",
+            // Show only after terms are accepted — one-off condition, no state needed.
+            include: { when: "$form.agreeTerms === true" }
+          },
+          {
+            kind: "input",
+            type: "textinput",
+            path: "companyName",
+            label: "Company name",
+            // Hide when the user selects "individual" account type — one-off condition.
+            exclude: { when: "$form.accountType === 'individual'" }
+          }
+        ]
+      }
+    },
     {
       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.',
@@ -2357,10 +2436,9 @@ const STATES_CONCEPT = {
     "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" }`).',
+    "Reactive expressions must reference `$form`, `$meta`, or `$formIsInvalid`. A bare identifier like `termsAccepted` without a root reference is invalid.",
     "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`."
   ]
@@ -2475,8 +2553,7 @@ const STRING_INTERPOLATION_CONCEPT = {
     }
   ],
   rules: [
-    "Slots must reference at least one of `$form`, `$meta`, `$errors`, or `$formIsInvalid`. A bare identifier without a scope prefix is invalid inside `{{}}`: use `{{$form.name}}` not `{{name}}`.",
-    "`$formIsInvalid` is a built-in boolean — use it as-is: `{{$formIsInvalid}}`. Do not chain properties onto it.",
+    "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 bare boolean — 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.",
@@ -2484,13 +2561,202 @@ const STRING_INTERPOLATION_CONCEPT = {
     "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."
+    'The expression language is the same as reactive expressions — see `get_concept({ concept: "reactive-scope" })` for the operator reference and safe-expression constraints.'
+  ]
+};
+const REACTIVE_SCOPE_CONCEPT = {
+  concept: "reactive-scope",
+  summary: "GolemUI reactive expressions (used in `states`, `include.when`, `exclude.when`, and `{{}}` template slots) share a common read-only scope object. The scope exposes four variables: `$form` (live form data), `$meta` (host-supplied metadata), `$errors` (validation error messages), and `$formIsInvalid` (built-in boolean). All variables are read-only — expressions can only read from them, never write to them.",
+  patterns: [
+    {
+      name: "$form — live form data",
+      description: '`$form` is a plain object whose keys are the field paths currently registered in the form. Each key equals the `path` property of an input widget. A simple field `path: "firstName"` is accessed as `$form.firstName`. A nested field `path: "address.city"` is accessed as `$form.address?.city` — the dot segments in the path become dot-property accesses, and optional chaining (`?.`) is required at each intermediate segment because the parent object may not yet exist while the user is filling in the form. `$form` itself is always a defined object; only leaf values may be `undefined` before the user fills them in.',
+      example: {
+        states: {
+          // path: "firstName" -> $form.firstName
+          hasName: '$form.firstName !== undefined && $form.firstName !== ""',
+          // path: "address.city" -> $form.address?.city (optional chaining at "address" segment)
+          hasCity: '$form.address?.city !== undefined && $form.address?.city !== ""',
+          // path: "user.profile.age" -> $form.user?.profile?.age
+          isAdult: "$form.user?.profile?.age >= 18"
+        }
+      }
+    },
+    {
+      name: "$meta — host-supplied metadata",
+      description: "`$meta` is a free-form key/value object supplied by the host application at mount time. It is useful for passing server-side flags, the current user's role, locale, or any context that is not part of the form data itself. The host sets the `meta` prop on the GolemUI form component; the MCP tool has no knowledge of which keys the host will supply. Access values with `$meta.keyName`. Use optional chaining if a key may not always be present.",
+      example: {
+        states: {
+          isAdmin: "$meta.role === 'admin'",
+          isOnline: '$meta.connectionStatus === "online"'
+        },
+        form: [
+          {
+            kind: "input",
+            type: "textinput",
+            path: "apiKey",
+            label: "API key",
+            // Show only for admin users — the role comes from $meta, not from $form.
+            include: { when: "$meta.role === 'admin'" }
+          }
+        ]
+      }
+    },
+    {
+      name: "$errors — validation error messages",
+      description: '`$errors` is a plain object keyed by widget `uid`. `$errors.myField` is the current validation error message string for the widget with `uid: "myField"`, or `undefined` if that field is currently valid. Use it to display a field\'s error message inside another widget (e.g. an `alert`). Note: a widget must have an explicit `uid` value set for its errors to appear in `$errors`; auto-generated uids are not predictable.',
+      example: {
+        $schema: "https://golemui.com/schemas/form.schema.json",
+        form: [
+          {
+            uid: "emailField",
+            kind: "input",
+            type: "textinput",
+            path: "email",
+            label: "Email",
+            validator: { type: "string", required: true, format: "email" }
+          },
+          {
+            kind: "display",
+            type: "alert",
+            props: {
+              level: "error",
+              // Render the live validation error message for the emailField widget.
+              text: "{{$errors.emailField}}"
+            },
+            // Only show this alert when the field actually has an error.
+            include: { when: "$errors.emailField !== undefined" }
+          }
+        ]
+      }
+    },
+    {
+      name: "$formIsInvalid — whole-form validity flag",
+      description: "`$formIsInvalid` is a built-in boolean that the runtime maintains automatically. It is `true` when ANY field in the form currently fails its validator; `false` otherwise. Use it to disable the submit button, show a banner, or guard a navigation step. It is NOT a property of `$form` — use it as a bare identifier. Do NOT chain properties onto it: `$formIsInvalid.something` is invalid.",
+      example: {
+        $schema: "https://golemui.com/schemas/form.schema.json",
+        form: [
+          {
+            kind: "action",
+            type: "button",
+            actionType: "submit",
+            label: "Submit",
+            // Disable the submit button while any field is invalid.
+            disabled: true,
+            "disabled.formValid": false
+          },
+          {
+            kind: "display",
+            type: "alert",
+            props: { level: "warning", text: "Please fix the errors above before submitting." },
+            include: { when: "$formIsInvalid" }
+          }
+        ],
+        states: {
+          formValid: "!$formIsInvalid"
+        }
+      }
+    }
+  ],
+  rules: [
+    "All four scope variables are read-only. Expressions may only read values, never assign them.",
+    "`$form` is always a defined object. Its leaf values (`$form.someField`) may be `undefined` until the user fills them in.",
+    "Use optional chaining (`?.`) at every intermediate segment of a nested path. `$form.address?.city` is safe; `$form.address.city` throws if `address` is undefined.",
+    'A widget\'s `path` value maps directly to a `$form` key path using the same dot segments. `path: "shipping.address.zip"` -> `$form.shipping?.address?.zip`.',
+    '`$formIsInvalid` is a built-in bare boolean — use it directly: `disabled: { when: "$formIsInvalid" }` or `states: { formValid: "!$formIsInvalid" }`. Never chain: `$formIsInvalid.value` is invalid.',
+    "`$errors` keys are widget `uid` values, not field path values. A widget must have an explicit `uid` for its errors to be addressable.",
+    "`$meta` keys are arbitrary — they depend entirely on what the host application passes to the form component. Use optional chaining if a key may be absent.",
+    "Supported operators across all expressions: arithmetic (`+`, `-`, `*`, `/`, `%`), comparison (`===`, `!==`, `<`, `>`, `<=`, `>=`), logical (`&&`, `||`, `!`), ternary (`? :`), optional chaining (`?.`), nullish coalescing (`??`).",
+    "Use `===` / `!==` for equality. Avoid `==` / `!=` (loose equality causes unexpected coercions with `undefined`).",
+    "No function calls, no `eval`, no side effects. The expression must be a pure read."
+  ]
+};
+const ICONS_CONCEPT = {
+  concept: "icons",
+  summary: 'GolemUI uses Google Material Icons for all icon props. An icon value is a Material Icons ligature name — a lowercase string with underscores, such as `"search"`, `"home"`, `"arrow_forward"`, or `"check_circle"`. The icon font must be loaded by the host page; without it, the icon value renders as raw text. Several widgets accept a `props.icon` property; `button` additionally has `props.iconPosition`. All icon props support state suffixes for reactive icon swapping.',
+  patterns: [
+    {
+      name: "Widget icon props",
+      description: "The following widgets accept `props.icon` (a Material Icons ligature name string): `button`, `textinput`, `password`, `select`, `currency`, `tags`, `dateInput`, `datePicker`, `rangeCalendar`, `rangedateinput`, `rangedatepicker`. The `button` widget additionally accepts `props.iconPosition` to control where the icon appears relative to the label. All other icon-capable widgets render the icon at a default position determined by the component.",
+      example: {
+        $schema: "https://golemui.com/schemas/form.schema.json",
+        form: [
+          {
+            kind: "action",
+            type: "button",
+            actionType: "submit",
+            label: "Send",
+            props: {
+              // "send" is the Google Material Icons ligature name for the send icon.
+              icon: "send",
+              iconPosition: "right"
+            }
+          },
+          {
+            kind: "input",
+            type: "textinput",
+            path: "email",
+            label: "Email",
+            props: {
+              icon: "email",
+              placeholder: "you@example.com"
+            }
+          },
+          {
+            kind: "input",
+            type: "select",
+            path: "country",
+            label: "Country",
+            props: {
+              icon: "public",
+              options: [
+                { label: "United States", value: "us" },
+                { label: "Canada", value: "ca" }
+              ]
+            }
+          }
+        ]
+      }
+    },
+    {
+      name: "Reactive icon swapping with state suffixes",
+      description: 'Like other widget props, `icon` supports state suffixes: `"icon.<stateName>": "checkName"` swaps the icon when the named state is active. This is useful for toggling between a default and a confirmation icon, or for indicating a loading state on a button.',
+      example: {
+        $schema: "https://golemui.com/schemas/form.schema.json",
+        states: {
+          submitted: "$meta.submitting === true"
+        },
+        form: [
+          {
+            kind: "action",
+            type: "button",
+            actionType: "submit",
+            label: "Submit",
+            "label.submitted": "Submitting...",
+            props: {
+              icon: "send",
+              // Swap to a spinner/hourglass icon while the form is being submitted.
+              "icon.submitted": "hourglass_empty"
+            }
+          }
+        ]
+      }
+    }
+  ],
+  rules: [
+    'Icon values are Google Material Icons ligature names — lowercase strings, words separated by underscores: `"search"`, `"arrow_forward"`, `"check_circle"`. Wrong casing or spaces will not render correctly.',
+    'The Material Icons font MUST be loaded in the host page\'s `<head>`. Without it, `props.icon` renders as the raw string (e.g. the word "search") rather than an icon glyph.',
+    "Widgets that support `props.icon`: `button`, `textinput`, `password`, `select`, `currency`, `tags`, `dateInput`, `datePicker`, `rangeCalendar`, `rangedateinput`, `rangedatepicker`.",
+    '`button` is the only widget with `props.iconPosition`. Allowed values: `"left"` (default) and `"right"`.',
+    'All icon props support state suffixes: `"icon.<stateName>": "check"` swaps the icon when that state is active. Call `get_concept({ concept: "states" })` for the full state-suffix pattern.',
+    "Do not set `props.icon` on widgets that do not support it — the schema will reject it and `validate_form_definition` will report an error."
   ]
 };
 const CONCEPTS = {
   states: STATES_CONCEPT,
-  "string-interpolation": STRING_INTERPOLATION_CONCEPT
+  "string-interpolation": STRING_INTERPOLATION_CONCEPT,
+  "reactive-scope": REACTIVE_SCOPE_CONCEPT,
+  icons: ICONS_CONCEPT
 };
 function getConcept(input) {
   const result = CONCEPTS[input.concept];
@@ -2502,7 +2768,7 @@ function getConcept(input) {
 }
 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`.',
+  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) conditionally show or hide widgets (`include`/`exclude`) — both the named-state form (`in`/`from`) and the inline `when` expression form are covered under the `states` concept; (2) change a widget\'s props based on form state (state-suffixed props like `"label.stateName": "…"`); (3) understand what `$form`, `$meta`, `$errors`, and `$formIsInvalid` are and how to reference form data in reactive expressions — use the `reactive-scope` concept; (4) add icons to widgets — use the `icons` concept. Currently supported concepts: `states`, `string-interpolation`, `reactive-scope`, `icons`.',
   inputSchema: {
     type: "object",
     properties: {

package/lib.js

@@ -1,4 +1,4 @@
-import { G, b, f, d, V, g, a, e, c, v } from "./get-concept-CHgtnDXr.js";
+import { G, b, f, d, V, g, a, e, c, v } from "./get-concept-ChE67L3a.js";
 export {
   G as GENERATE_FROM_JSON_SCHEMA_TOOL,
   b as GENERATE_FROM_OPENAPI_TOOL,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@golemui/gui-mcp",
-  "version": "0.16.2",
+  "version": "1.0.0-rc.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": "./lib.js",
@@ -36,7 +36,7 @@
   "dependencies": {
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
-    "@golemui/gui-schemas": "0.16.2"
+    "@golemui/gui-schemas": "1.0.0-rc.0"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0"