@golemui/gui-mcp 1.0.0-rc.2 → 1.0.0-rc.4

package/{get-concept-B7s_l8Qs.js → get-concept-DMoitPWv.js}

@@ -1,5 +1,9 @@
 import Ajv2020 from "ajv/dist/2020.js";
 import addFormats from "ajv-formats";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { resolve, join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 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";
@@ -1081,6 +1085,11 @@ function lintReactiveExpressions(formDefinition) {
   walk$1(formDefinition, "", findings);
   return findings;
 }
+function checkReactiveExpression(expression, path = "") {
+  const out = [];
+  checkExpression(expression, path, out);
+  return out;
+}
 function walk$1(node, path, out) {
   if (node === null || typeof node !== "object") return;
   if (Array.isArray(node)) {
@@ -1370,7 +1379,7 @@ function validateFormDefinition(input) {
     errors.push({
       path: "/",
       keyword: "oneOf",
-      message: "Form failed schema validation but no specific error could be localized. The form may contain a widget at a position the form schema does not allow, or a structural shape that our targeted validator missed. Verify each widget against its `get_widget_spec` entry."
+      message: "Form failed schema validation but no specific error could be localized. The form may contain a widget at a position the form schema does not allow, or a structural shape that our targeted validator missed. Verify each widget against its `json_get_widget_spec` entry."
     });
   }
   return {
@@ -1381,8 +1390,8 @@ function validateFormDefinition(input) {
     interpolationWarnings
   };
 }
-const VALIDATE_FORM_DEFINITION_TOOL = {
-  name: "validate_form_definition",
+const JSON_VALIDATE_FORM_DEFINITION_TOOL = {
+  name: "json_validate_form_definition",
   description: "Validate a GolemUI form definition against the bundled JSON Schemas. Use this AFTER generating or modifying a form definition to guarantee it is correct before the user pastes it into their codebase. Returns `{ valid, errors, warnings, expressionWarnings, interpolationWarnings }`. Hard mistakes (typos in widget `type`, missing required props, invalid validator shapes) show up in `errors` and flip `valid` to false. Likely-custom widgets (a `type` value that isn't a built-in and isn't close to one) show up in `warnings` instead — they don't affect `valid`. Reactive expressions (`include.when`, `disabled.when`, etc.) are linted separately into `expressionWarnings`. String interpolation templates (`{{$form.x}}`, `{{$meta.y}}`, expressions like `{{$form.count + 1}}`, etc.) in widget props, and bare expressions inside i18n `params` objects, are linted into `interpolationWarnings`.",
   inputSchema: {
     type: "object",
@@ -1765,8 +1774,8 @@ function generateFromJsonSchema(input) {
   const validation = validateFormDefinition({ formDefinition });
   return { formDefinition, unmapped, validation };
 }
-const GENERATE_FROM_JSON_SCHEMA_TOOL = {
-  name: "generate_from_json_schema",
+const JSON_GENERATE_FROM_SCHEMA_TOOL = {
+  name: "json_generate_from_schema",
   description: "Generate a GolemUI form definition from a JSON Schema describing the form data shape (typically an API request body or a Zod-derived schema). The result is validated against the GolemUI JSON Schemas before being returned, so it is guaranteed to be syntactically correct. Anything the mapper cannot handle is reported in `unmapped` rather than silently dropped — use that list to surface remaining work to the user.",
   inputSchema: {
     type: "object",
@@ -1920,8 +1929,8 @@ function resolveLocalRef(ref, doc) {
   }
   return cur ?? null;
 }
-const GENERATE_FROM_OPENAPI_TOOL = {
-  name: "generate_from_openapi",
+const JSON_GENERATE_FROM_OPENAPI_TOOL = {
+  name: "json_generate_from_openapi",
   description: 'Generate a GolemUI form for a specific OpenAPI 3.x operation (e.g. "POST /users"). Resolves the operation\'s JSON request body, dereferences `$ref`s, then maps it to a form definition that is validated against the GolemUI JSON Schemas before being returned, so it is guaranteed syntactically correct. Falls back to operation parameters when no request body is present. Anything the mapper cannot handle is reported in `unmapped` rather than silently dropped — use that list to surface remaining work to the user. Pass either a parsed `document` or a `documentUrl` to fetch.',
   inputSchema: {
     type: "object",
@@ -2257,9 +2266,9 @@ function getWidgetSpec(input) {
     notes: NOTES[input.widgetType] ?? []
   };
 }
-const GET_WIDGET_SPEC_TOOL = {
-  name: "get_widget_spec",
-  description: "Look up the JSON Schema and a minimal working example for a single GolemUI widget. Use this when you need to know which `props` a widget accepts, what `kind` value it uses, or what shape its `validator` takes. Cheaper than dumping the whole API into context.",
+const JSON_GET_WIDGET_SPEC_TOOL = {
+  name: "json_get_widget_spec",
+  description: "Look up the JSON Schema and a minimal working example for a single GolemUI widget on the **JSON form-definition** surface. Use this when you need to know which `props` a widget accepts, what `kind` value it uses, or what shape its `validator` takes. **If you are writing `gui.*` DX code (TypeScript), you do NOT need this** — use `dx_list_factories` + `dx_get_spec` instead; fetching both surfaces for the same widget is redundant. Cheaper than dumping the whole API into context.",
   inputSchema: {
     type: "object",
     properties: {
@@ -2271,6 +2280,587 @@ const GET_WIDGET_SPEC_TOOL = {
     required: ["widgetType"]
   }
 };
+const CONFIG_FIELDS = ["include", "exclude", "disabled", "readonly"];
+function lintDxSnippet(ts, sourceText, lineOffset) {
+  const sf = ts.createSourceFile("__dx_lint__.ts", sourceText, ts.ScriptTarget.ES2020, true);
+  const diagnostics = [];
+  const expressionWarnings = [];
+  const posOf = (node) => {
+    const p = sf.getLineAndCharacterOfPosition(node.getStart(sf));
+    return { line: p.line + 1 - lineOffset, column: p.character + 1 };
+  };
+  const nameOf = (name) => {
+    if (ts.isIdentifier(name)) return name.text;
+    if (ts.isStringLiteralLike(name)) return name.text;
+    return void 0;
+  };
+  const isGuiCall = (expr) => {
+    if (!ts.isCallExpression(expr)) return false;
+    let e = expr.expression;
+    while (ts.isPropertyAccessExpression(e)) e = e.expression;
+    return ts.isIdentifier(e) && e.text === "gui";
+  };
+  const visit = (node) => {
+    if (ts.isObjectLiteralExpression(node)) {
+      const spreadsGui = node.properties.some(
+        (p) => ts.isSpreadAssignment(p) && isGuiCall(p.expression)
+      );
+      if (spreadsGui) {
+        for (const p of node.properties) {
+          const name = ts.isPropertyAssignment(p) || ts.isShorthandPropertyAssignment(p) ? nameOf(p.name) : void 0;
+          if (name && CONFIG_FIELDS.includes(name)) {
+            const { line, column } = posOf(p);
+            diagnostics.push({
+              code: 0,
+              message: `\`${name}\` is attached as a sibling of a \`gui.*\` spread — it is a silent no-op. The field renders/behaves unconditionally because the factory never receives it.`,
+              line,
+              column,
+              hint: `Pass \`${name}\` INSIDE the factory's config argument, not via a spread: \`gui.inputs.x(path, { /* props */, ${name}: ... })\` — never \`{ ...gui.inputs.x(path, { /* props */ }), ${name}: ... }\`.`
+            });
+          }
+        }
+      }
+    }
+    if (ts.isPropertyAssignment(node) && nameOf(node.name) === "when" && ts.isStringLiteralLike(node.initializer)) {
+      const { line, column } = posOf(node.initializer);
+      for (const f of checkReactiveExpression(node.initializer.text, `when@${line}:${column}`)) {
+        expressionWarnings.push(f);
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  return { diagnostics, expressionWarnings };
+}
+const requireFrom = createRequire(import.meta.url);
+const GOLEMUI_TYPE_PACKAGES = [
+  { spec: "@golemui/gui-shared", rel: "gui/shared/index.d.ts" },
+  { spec: "@golemui/gui-shared/internals", rel: "gui/shared/internals.d.ts" },
+  { spec: "@golemui/gui-validators", rel: "gui/validators/index.d.ts" },
+  { spec: "@golemui/core", rel: "core/index.d.ts" },
+  { spec: "@golemui/core/internals", rel: "core/internals.d.ts" }
+];
+const DIST_SEARCH_DEPTH = 8;
+const SNIPPET_FILE = "__dx_snippet__.ts";
+function resolveStrategy() {
+  try {
+    const pj = requireFrom.resolve("@golemui/gui-shared/package.json");
+    const [root] = pj.split(/[\\/]node_modules[\\/]/);
+    if (root && root !== pj) return { baseUrl: root };
+  } catch {
+  }
+  const typesRoot = findDistTypesRoot();
+  const paths = {};
+  for (const { spec, rel } of GOLEMUI_TYPE_PACKAGES) {
+    const abs = join(typesRoot, rel);
+    if (existsSync(abs)) paths[spec] = [abs];
+  }
+  return { baseUrl: dirname(typesRoot), paths };
+}
+function findDistTypesRoot() {
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < DIST_SEARCH_DEPTH; i++) {
+    const c = join(dir, "dist", "libs");
+    if (existsSync(join(c, "gui", "shared", "index.d.ts"))) return c;
+    dir = dirname(dir);
+  }
+  throw new Error(
+    "dx_check_code: could not locate the @golemui type graph — neither an installed `@golemui/gui-shared` in node_modules nor the monorepo's dist/libs. The DX type-check cannot run without the real declarations."
+  );
+}
+function resolveTypeCheckOptions(ts) {
+  const strat = resolveStrategy();
+  return {
+    noEmit: true,
+    strict: true,
+    skipLibCheck: true,
+    target: ts.ScriptTarget.ES2020,
+    module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    jsx: ts.JsxEmit.ReactJSX,
+    lib: ["lib.es2020.d.ts", "lib.dom.d.ts"],
+    // baseUrl roots node_modules resolution (zod, @standard-schema/spec, and — in the
+    // installed case — the @golemui packages themselves).
+    baseUrl: strat.baseUrl,
+    ...strat.paths ? { paths: strat.paths } : {}
+  };
+}
+function diagnose(ts, code, options) {
+  const sf = ts.createSourceFile(SNIPPET_FILE, code, ts.ScriptTarget.ES2020, true);
+  const host = ts.createCompilerHost(options, true);
+  const originalGet = host.getSourceFile.bind(host);
+  host.getSourceFile = (fileName, languageVersion, onError, shouldCreate) => fileName === SNIPPET_FILE || resolve(fileName) === resolve(SNIPPET_FILE) ? sf : originalGet(fileName, languageVersion, onError, shouldCreate);
+  const originalExists = host.fileExists.bind(host);
+  host.fileExists = (fileName) => fileName === SNIPPET_FILE || resolve(fileName) === resolve(SNIPPET_FILE) || originalExists(fileName);
+  const originalRead = host.readFile.bind(host);
+  host.readFile = (fileName) => fileName === SNIPPET_FILE ? code : originalRead(fileName);
+  const program = ts.createProgram([SNIPPET_FILE], options, host);
+  return ts.getPreEmitDiagnostics(program).filter((d) => d.file?.fileName === SNIPPET_FILE);
+}
+let guardChecked = false;
+function assertTypesAreLive(ts, options) {
+  if (guardChecked) return;
+  const bogus = `import { gui } from '@golemui/gui-shared';
+[gui.inputs.__definitely_not_a_real_member__('x', {})];
+`;
+  if (diagnose(ts, bogus, options).length === 0) {
+    throw new Error(
+      "dx_check_code: internal type-resolution guard failed — a known-invalid snippet type-checked clean, which means the @golemui types resolved to `any`. Refusing to return misleading results."
+    );
+  }
+  const looseEvent = `import { gui } from '@golemui/gui-shared';
+[gui.inputs.textInput('x', { onChange: 'not-a-function' })];
+`;
+  if (diagnose(ts, looseEvent, options).length === 0) {
+    throw new Error(
+      "dx_check_code: internal type-resolution guard failed — a bare-string event handler type-checked clean, so the DxEventHandler type resolved to `any` (likely a stale @golemui build). Refusing to return misleading results."
+    );
+  }
+  guardChecked = true;
+}
+let cachedTs = null;
+async function loadTs() {
+  if (!cachedTs) {
+    cachedTs = (await import("typescript")).default ?? await import("typescript");
+  }
+  return cachedTs;
+}
+function hintFor(d, flat) {
+  if (d.code === 2339 && /submitButton/i.test(flat)) {
+    return "There is no `gui.actions.submitButton`. Use `gui.actions.button({ label, actionType: 'submit' })`.";
+  }
+  if (d.code === 2769 && /validator/i.test(flat)) {
+    return "Choice widgets (`dropdown`, `radiogroup`, `select`) need a typed validator — e.g. `validator: { type: 'string', required: true }` — unlike `textInput`, which accepts the loose `{ required: true }`. Add the `type`, or omit the validator.";
+  }
+  if (/'items'|'options'/.test(flat)) {
+    return "Choice-widget option lists are not symmetric: `gui.inputs.dropdown` takes **`items`**, while `gui.inputs.radiogroup` and `gui.inputs.select` take **`options`** (both `{ value, label }[]`). Swap the key to the one this factory expects.";
+  }
+  if (/'content'/.test(flat)) {
+    return "`gui.displays.alert` uses **`text`** (not `content`); `gui.displays.markdownText` uses **`md`** (not `content`). Use the factory’s own content key.";
+  }
+  return void 0;
+}
+function unfence(code) {
+  const m = code.match(/^\s*```[a-zA-Z]*\n([\s\S]*?)```\s*$/);
+  return m ? m[1] : code;
+}
+async function typeCheckDx(code) {
+  const ts = await loadTs();
+  const options = resolveTypeCheckOptions(ts);
+  assertTypesAreLive(ts, options);
+  const body = unfence(code);
+  const full = /@golemui\/gui-shared/.test(body) ? body : `import { gui } from '@golemui/gui-shared';
+${body}`;
+  const lineOffset = full === body ? 0 : 1;
+  const tscDiagnostics = diagnose(ts, full, options).map((d) => {
+    const flat = ts.flattenDiagnosticMessageText(d.messageText, " ");
+    const pos = d.file && d.start != null ? d.file.getLineAndCharacterOfPosition(d.start) : null;
+    return {
+      code: d.code,
+      message: flat,
+      line: pos ? pos.line + 1 - lineOffset : 0,
+      column: pos ? pos.character + 1 : 0,
+      hint: hintFor(d, flat)
+    };
+  });
+  const { diagnostics: lintDiagnostics, expressionWarnings } = lintDxSnippet(ts, full, lineOffset);
+  const diagnostics = [...tscDiagnostics, ...lintDiagnostics];
+  return { ok: diagnostics.length === 0, diagnostics, expressionWarnings };
+}
+async function checkDxCode(input) {
+  if (typeof input?.code !== "string" || input.code.trim() === "") {
+    throw new Error("dx_check_code requires a non-empty `code` string.");
+  }
+  return typeCheckDx(input.code);
+}
+const DX_CHECK_CODE_TOOL = {
+  name: "dx_check_code",
+  description: "Type-check GolemUI **DX code** (the `gui.*` fluent builder, written in TypeScript) against the real `@golemui` type declarations, and return compiler diagnostics. This is for `gui.*` *code* — distinct from `json_validate_form_definition`, which validates a JSON form-definition *object*. GolemUI is not in any model's training data, so generated `gui.*` code is frequently a confident fabrication that does not compile; this is the only trustworthy check (inspection misses it). Beyond type errors it also catches two defects the compiler cannot see: a misplaced `include`/`exclude` attached as a sibling of a `gui.*` spread (`{ ...gui.inputs.x(...), include }` compiles but silently never hides the field — put `include`/`exclude` INSIDE the config argument), and reactive-expression mistakes in `when` strings (linted by the same engine as `json_validate_form_definition`). Pass the `gui.*` snippet as `code` (a bare array of `gui.inputs.*` items is fine — a `@golemui/gui-shared` import is added if missing). Returns `{ ok, diagnostics, expressionWarnings }`; each diagnostic has a TypeScript `code` (0 for the static lints), `message`, `line`/`column`, and — for recognized GolemUI mistakes — a `hint` with the fix. `expressionWarnings` are advisory and do not flip `ok`. Treat `ok: false` as blocking: apply the fixes and re-check until `ok` is true.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      code: {
+        type: "string",
+        description: "The GolemUI `gui.*` DX snippet to type-check (TypeScript)."
+      }
+    },
+    required: ["code"]
+  }
+};
+const DX_FRAMEWORKS = ["react", "angular", "vue", "lit", "vanilla"];
+function resolveDxFramework() {
+  const raw = typeof process !== "undefined" ? process.env?.["GOLEMUI_FRAMEWORK"]?.toLowerCase() : void 0;
+  return DX_FRAMEWORKS.includes(raw ?? "") ? raw : "react";
+}
+const FRAMEWORK_SETUP = {
+  react: "RENDER (React) — `import { gui } from '@golemui/gui-shared'; import { GuiForm } from '@golemui/gui-react'; import type { FormSubmitEvent } from '@golemui/core';`, then render `<GuiForm config={{ formDef: form }} formSubmit={(e: FormSubmitEvent) => { /* e.data is the form data */ }} />`. A `gui.displays.display(() => <h2>…</h2>)` returns React JSX.",
+  angular: "RENDER (Angular) — `import { gui } from '@golemui/gui-shared'; import { FormComponent } from '@golemui/gui-angular';`, add `FormComponent` to the standalone component's `imports`, then in the template `<gui-form [config]=\"{ formDef: form }\" (formSubmit)=\"onSubmit($event)\"></gui-form>` — `$event` is a `FormSubmitEvent` (type from `@golemui/core`), `$event.data` is the form data.",
+  vue: "RENDER (Vue) — `import { gui } from '@golemui/gui-shared'; import { GuiForm } from '@golemui/gui-vue';`, then `<GuiForm :config=\"{ formDef: form }\" @form-submit=\"onSubmit\" />` — the handler receives a `FormSubmitEvent` (`.data` is the form data). The event is `form-submit` (kebab-case), not `formSubmit`.",
+  lit: "RENDER (Lit) — `import { gui } from '@golemui/gui-shared'; import '@golemui/gui-lit';` (registers the `<gui-form>` custom element), then `<gui-form .config=${{ formDef: form }} @form-submit=${(e: CustomEvent) => { /* e.detail is the FormSubmitEvent; e.detail.data */ }}></gui-form>`.",
+  vanilla: "RENDER (vanilla JS) — `import { gui } from '@golemui/gui-shared'; import '@golemui/gui-lit';` (registers `<gui-form>`), then `const el = document.querySelector('gui-form'); el.config = { formDef: form }; el.addEventListener('form-submit', (e) => { /* e.detail.data */ });`"
+};
+function commonNote(fw = "react") {
+  return "GolemUI builds FORMS — data collection and validation. It is NOT a general-purpose UI toolkit: it never renders documents, page content, or markdown for display. A form is just an array of these items: `export const form = [ /* items */ ];`. " + FRAMEWORK_SETUP[fw] + " Import the component stylesheet ONCE — `@golemui/gui-components/index.css` — or the form renders unstyled. To RECEIVE A SUBMIT: add a `gui.actions.button({ label, actionType: 'submit' })` to the form and listen for the submit on the host component (the RENDER line above shows how for your framework) — the handler gets a `FormSubmitEvent` whose `.data` is the collected form data. To DISABLE submit until the form is valid, add `disabled: { when: '$formIsInvalid' }` to that button (`$formIsInvalid` is a built-in validity flag) — see the conditional-and-state-props pattern. The SAME `formDef` renders in every framework (React/Angular/Vue/Lit/vanilla) — only the host wrapper changes. FORM-LEVEL CONFIG — `formDef` is ALWAYS the bare array. Anything form-wide (named `states`, `validateOn`) goes in a sibling `formConfig` on the config (`config={{ formDef: form, formConfig: { states, validateOn } }}`), NEVER inside `formDef`. Do NOT wrap the array as `{ states, form: [...] }` and pass THAT as `formDef` — `formDef` is typed `Record<string, any>` so it COMPILES, but the `gui.*` items are never resolved and the form renders BLANK with no error. See the form-level-states pattern. Common fields like `include`/`exclude` (conditional visibility) go INSIDE a factory’s config argument — never spread them onto the result (`{ ...gui.inputs.x(...), include }` compiles but silently does nothing). See the conditional-visibility pattern. STATIC CONTENT — a section heading or any non-input text/block is the HOST’s job, not GolemUI’s: use `gui.displays.display(() => <h2>…</h2>)` returning your framework’s own node (React JSX, Vue/Angular/Lit node) — it needs no dependency and always renders. MARKDOWN has exactly ONE use: `gui.inputs.markdown`, an INPUT where the user EDITS markdown (its value is their markdown string). There is NO markdown-for-display widget — never use markdown to render a heading or content; use `display` for that. VALIDATOR `type` — one rule, three cases (so you never have to guess): (1) choice widgets (`dropdown`, `radiogroup`, `select`) REQUIRE an explicit `type`: `validator: { type: 'string', required: true }`. (2) `repeater` (array) validators auto-supply `type: 'array'` — supply only the rules, e.g. `validator: { required: true, minItems: 1 }`, never `type`. (3) everything else (text, number, date) takes the loose validator with NO `type`: `validator: { required: true }`. EVENT HANDLERS — `onChange`/`onLoad`/`onFilter`/`onBlur` (inputs/layouts) and `onClick` (actions) are FUNCTIONS, never bare strings: return a string to dispatch a host event by that name (`onChange: () => 'languageChanged'`), or take the event to push live changes (`onChange: (event) => event.update({ path: 'city', options: [...] })`).";
+}
+const PATTERNS = [
+  {
+    name: "conditionalVisibility",
+    title: "Show or hide a field conditionally (hide-when)",
+    example: "gui.inputs.textInput('promoCode', { label: 'Promo code', include: { when: '$form.hasPromoCode === true' } })",
+    notes: [
+      "`include` and `exclude` are common config fields on EVERY `gui.*` item — pass them inside the factory's config argument (the same object as `label`): `gui.inputs.textInput('promoCode', { label, include: { when: '$form.hasPromoCode === true' } })`. `include` shows the field only while the expression is true; `exclude` hides it while true.",
+      "NEVER attach them by spreading the factory result: `{ ...gui.inputs.textInput('promoCode', { label }), include: { when } }` COMPILES (TypeScript does not flag it) but is a silent no-op — the field renders unconditionally. The `include`/`exclude` must be a key of the config object, not a sibling of the spread.",
+      "The `when` value is a `ReactiveExpression` (a plain string) that reads form state via `$form.<path>` and uses strict equality, e.g. `'$form.hasPromoCode === true'`. When the SAME condition gates two or more fields, define a named state and use `include: { in: ['stateName'] }` / `exclude: { from: [...] }` instead of an inline `when`. Named states are declared in `formConfig.states` — see the form-level-states pattern."
+    ]
+  },
+  {
+    name: "formLevelStates",
+    title: "Declare named form-level states (and gate fields by them)",
+    example: "gui.inputs.textInput('spouseName', { label: 'Spouse name', include: { in: ['familyCoverage'] } })",
+    notes: [
+      "Named states are form-level: declare them in `formConfig.states`, a sibling of `formDef` on the `<GuiForm>` config — NOT a wrapper around the array. `formConfig.states` maps each state name to a `ReactiveExpression` string, e.g. `{ familyCoverage: '$form.coverageType === \\'family\\'' }`. Then any item references it by name: `include: { in: ['familyCoverage'] }` (show while true) / `exclude: { from: ['familyCoverage'] }` (hide while true).",
+      "Full shape: `<GuiForm config={{ formDef: form, formConfig: { states: { familyCoverage: '...' }, validateOn: 'blur' } }} />`. The `formDef` stays the bare `gui.*` array.",
+      "NEVER pass `{ states, form: [...] }` as `formDef`. It type-checks (`formDef` is `Record<string, any>`) but that object is not recognized as a `gui.*` bundle, so the items are never resolved — the form renders BLANK with no console error. The `{ states, form }` shape only exists for hand-written core/JSON widgets, not the `gui.*` facade."
+    ]
+  },
+  {
+    name: "conditionalAndStateProps",
+    title: "Conditional & state-driven props (enable/disable, show/hide, readonly)",
+    example: "gui.actions.button({ label: 'Submit', actionType: 'submit', disabled: { when: '$formIsInvalid' } })",
+    notes: [
+      "ENABLE/DISABLE & READONLY: `disabled` and `readonly` are typed `boolean | { when: <expr> }`. To gate the submit button on validity: `gui.actions.button({ label, actionType: 'submit', disabled: { when: '$formIsInvalid' } })`. `$formIsInvalid` is a built-in validity flag — do not declare it as a state.",
+      "SHOW/HIDE: `include` / `exclude` are typed `{ in: ['stateName'] }` / `{ from: ['stateName'] }` (state lists) or `{ when: <expr> }`. Every state name in `in`/`from` MUST be declared in `formConfig.states`; an undeclared name leaves the widget hidden forever (the engine logs an error to the console).",
+      "These are ALL typed config keys — pass them inside the factory’s config argument. NEVER reach a prop by casting the factory result and assigning a key (`(btn as any)['disabled.formValid'] = false`) or by spreading (`{ ...gui.actions.button(...), disabled }`): keys added that way are SILENTLY ignored and the behavior never fires. If a prop is not on the typed config, you are guessing — it is not a real field."
+    ]
+  }
+];
+const INPUTS = [
+  {
+    factory: "textInput",
+    namespace: "inputs",
+    call: "gui.inputs.textInput(path, { label, placeholder?, defaultValue?, validator? })",
+    example: "gui.inputs.textInput('fullName', { label: 'Full name', validator: { required: true, minLength: 2 } })",
+    notes: [
+      "Text fields accept a loose validator: `{ required, minLength, maxLength, pattern, format }` (no `type` needed).",
+      "Email is a text input with `validator: { required: true, format: 'email' }` — use `format`, not a regex. The full `format` enum: `email`, `url`, `uuid`, `hostname`, `ipv4`, `ipv6`, `date`, `time`, `date-time`, `duration`."
+    ]
+  },
+  {
+    factory: "numberInput",
+    namespace: "inputs",
+    call: "gui.inputs.numberInput(path, { label, defaultValue?, validator? })",
+    example: "gui.inputs.numberInput('age', { label: 'Age', validator: { required: true, minimum: 0, maximum: 120 } })",
+    notes: [
+      "Number validator: `{ required, minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf }`."
+    ]
+  },
+  {
+    factory: "booleanInput",
+    namespace: "inputs",
+    call: "gui.inputs.booleanInput(path, { label, defaultValue? })",
+    example: "gui.inputs.booleanInput('newsletter', { label: 'Subscribe to newsletter', defaultValue: false })",
+    notes: ["The on/off toggle for a single boolean. Use `checkbox` for a checkbox presentation."]
+  },
+  {
+    factory: "checkbox",
+    namespace: "inputs",
+    call: "gui.inputs.checkbox(path, { label, defaultValue? })",
+    example: "gui.inputs.checkbox('terms', { label: 'I accept the terms', defaultValue: false })",
+    notes: ["A single boolean rendered as a checkbox."]
+  },
+  {
+    factory: "textarea",
+    namespace: "inputs",
+    call: "gui.inputs.textarea(path, { label, placeholder?, validator? })",
+    example: "gui.inputs.textarea('bio', { label: 'Bio', validator: { maxLength: 500 } })",
+    notes: ["Multi-line text; same loose string validator as `textInput`."]
+  },
+  {
+    factory: "password",
+    namespace: "inputs",
+    call: "gui.inputs.password(path, { label, validator? })",
+    example: "gui.inputs.password('password', { label: 'Password', validator: { required: true, minLength: 8 } })",
+    notes: ["Masked text input; loose string validator."]
+  },
+  {
+    factory: "dropdown",
+    namespace: "inputs",
+    call: "gui.inputs.dropdown(path, { label, items, validator? })",
+    example: "gui.inputs.dropdown('country', { label: 'Country', items: [{ value: 'us', label: 'United States' }, { value: 'ca', label: 'Canada' }], validator: { type: 'string', required: true } })",
+    notes: [
+      "Choice list uses **`items`** (`{ value, label }[]`).",
+      "WART: choice widgets (`dropdown`, `radiogroup`, `select`) need a **typed** validator — `{ type: 'string', required: true }` — unlike text inputs which accept the loose `{ required: true }`. Add the `type`, or omit the validator."
+    ]
+  },
+  {
+    factory: "radiogroup",
+    namespace: "inputs",
+    call: "gui.inputs.radiogroup(path, { label, options, defaultValue?, validator? })",
+    example: "gui.inputs.radiogroup('accountType', { label: 'Account type', defaultValue: 'personal', options: [{ value: 'personal', label: 'Personal' }, { value: 'business', label: 'Business' }] })",
+    notes: [
+      "Radio group uses **`options`** (`{ value, label }[]`) — note the asymmetry: `dropdown` uses `items`, `radiogroup` uses `options`.",
+      "If required, use a typed validator `{ type: 'string', required: true }` (same wart as `dropdown`)."
+    ]
+  },
+  {
+    factory: "datePicker",
+    namespace: "inputs",
+    call: "gui.inputs.datePicker(path, { label, minDate?, maxDate?, validator? })",
+    example: "gui.inputs.datePicker('startDate', { label: 'Coverage start', minDate: '2025-01-01', validator: { required: true } })",
+    notes: [
+      "THE DEFAULT single-date field: a text field with a popover calendar (click to open). Prefer this for most dates. (`calendar` = always-visible inline calendar; `dateInput` = typed entry, no calendar UI.) Accepts the loose `{ required: true }` validator.",
+      'Bound the selectable range with **`minDate`** / **`maxDate`** — ISO `YYYY-MM-DD` strings. For "today or later" set `minDate` to today’s date; for "not in the future" set `maxDate` to today. Same `minDate`/`maxDate` on `calendar`, `dateInput`, and the range date widgets.'
+    ]
+  },
+  {
+    factory: "currency",
+    namespace: "inputs",
+    call: "gui.inputs.currency(path, { label, validator? })",
+    example: "gui.inputs.currency('price', { label: 'Price', validator: { required: true, minimum: 0 } })",
+    notes: ["Numeric money input; number-style validator."]
+  },
+  {
+    factory: "select",
+    namespace: "inputs",
+    call: "gui.inputs.select(path, { label, options, validator? })",
+    example: "gui.inputs.select('plan', { label: 'Plan', options: [{ value: 'free', label: 'Free' }, { value: 'pro', label: 'Pro' }], validator: { type: 'string', required: true } })",
+    notes: [
+      "Choice widget that uses **`options`** (like `radiogroup`) — NOT `items` (which `dropdown` uses).",
+      "Same validator wart as the other choice widgets: if required, use a typed validator `{ type: 'string', required: true }`."
+    ]
+  },
+  {
+    factory: "dateInput",
+    namespace: "inputs",
+    call: "gui.inputs.dateInput(path, { label, minDate?, maxDate?, validator? })",
+    example: "gui.inputs.dateInput('startDate', { label: 'Start date', validator: { required: true } })",
+    notes: [
+      "Typed date entry, NO calendar UI — use only when keyboard-first entry is wanted. For most dates use `datePicker` (popover calendar) instead. Accepts the loose `{ required: true }`.",
+      "`minDate` / `maxDate` (ISO `YYYY-MM-DD` strings) constrain the accepted range — see `datePicker`."
+    ]
+  },
+  {
+    factory: "calendar",
+    namespace: "inputs",
+    call: "gui.inputs.calendar(path, { label, minDate?, maxDate? })",
+    example: "gui.inputs.calendar('day', { label: 'Pick a day', minDate: '2025-01-01' })",
+    notes: [
+      "An always-visible INLINE calendar (no popover) — use when the calendar should be shown on the page. For a compact single-date field use `datePicker` instead.",
+      "`minDate` / `maxDate` (ISO `YYYY-MM-DD` strings) constrain the selectable range — see `datePicker`."
+    ]
+  },
+  {
+    factory: "markdown",
+    namespace: "inputs",
+    call: "gui.inputs.markdown(path, { label })",
+    example: "gui.inputs.markdown('notes', { label: 'Notes (markdown)' })",
+    notes: [
+      "A markdown *editor input* — the user types markdown and the value IS that markdown string. This is the ONLY use of markdown in GolemUI: there is no markdown-for-display. For a heading or static block, use `gui.displays.display(() => <node>)` (your host renders it), never a markdown widget."
+    ]
+  },
+  {
+    factory: "tags",
+    namespace: "inputs",
+    call: "gui.inputs.tags(path, { label })",
+    example: "gui.inputs.tags('skills', { label: 'Skills' })",
+    notes: ["Free-form multi-value tag input; the value is a string array."]
+  },
+  {
+    factory: "repeater",
+    namespace: "inputs",
+    call: "gui.inputs.repeater(path, { label?, addLabel?, removeLabel?, limit?, template })",
+    example: "gui.inputs.repeater('attendees', { label: 'Attendees', addLabel: 'Add attendee', template: [ gui.inputs.textInput('attendees.items.name', { label: 'Name' }) ] })",
+    notes: [
+      "The variable-length array field: the user adds/removes rows at runtime, each rendering the `template`. This is the idiomatic way to collect an UNKNOWN number of items — do NOT hand-roll N pre-generated copies gated by `include.when` (a common but wrong workaround).",
+      "Child field paths inside the template are **`<path>.items.<field>`** — a repeater on `'attendees'` holds `gui.inputs.textInput('attendees.items.name', …)`. At RUNTIME each `items` token is replaced by the row's array index (`attendees.items.name` → `attendees[0].name`, `attendees[1].name`, …); nesting a repeater inside a template adds another `.items.` segment (`teams.items.members.items.name`).",
+      "`limit` caps the number of rows; `addLabel`/`removeLabel` set the button text."
+    ]
+  },
+  {
+    factory: "list",
+    namespace: "inputs",
+    call: "gui.inputs.list(path, { label, items, height?, itemHeight? })",
+    example: "gui.inputs.list('selection', { label: 'Pick an option', items: ['Option 1', 'Option 2', 'Option 3'], height: 200, itemHeight: 40 })",
+    notes: [
+      "A scrolling selection list. `items` is a string array (or `{ value, label }[]`).",
+      "`height` / `itemHeight` size the scroll viewport (pixels)."
+    ]
+  },
+  {
+    factory: "rangeCalendar",
+    namespace: "inputs",
+    call: "gui.inputs.rangeCalendar(path, { label? })",
+    example: "gui.inputs.rangeCalendar('stayDates', { label: 'Stay dates' })",
+    notes: [
+      "Inline calendar for a start–end date **range** (the value is a date range). For a single date use `calendar`."
+    ]
+  },
+  {
+    factory: "rangeDateInput",
+    namespace: "inputs",
+    call: "gui.inputs.rangeDateInput(path, { label? })",
+    example: "gui.inputs.rangeDateInput('stayDates', { label: 'Stay dates' })",
+    notes: ["Typed start–end date **range** entry (the range sibling of `dateInput`)."]
+  },
+  {
+    factory: "rangeDatePicker",
+    namespace: "inputs",
+    call: "gui.inputs.rangeDatePicker(path, { label? })",
+    example: "gui.inputs.rangeDatePicker('stayDates', { label: 'Stay dates' })",
+    notes: ["Popover calendar for a start–end date **range** (the range sibling of `datePicker`)."]
+  }
+];
+const ACTIONS = [
+  {
+    factory: "button",
+    namespace: "actions",
+    call: "gui.actions.button({ label, actionType?: 'submit', onClick? })",
+    example: "gui.actions.button({ label: 'Sign up', actionType: 'submit' })",
+    notes: [
+      "Submit button: `gui.actions.button({ label, actionType: 'submit' })`.",
+      "There is NO `gui.actions.submitButton` — it was removed. Use `button` with `actionType: 'submit'`.",
+      "For a non-submit action use an `onClick: (event) => { /* event.data is the form data */ }` handler."
+    ]
+  }
+];
+const DISPLAYS = [
+  {
+    factory: "alert",
+    namespace: "displays",
+    call: "gui.displays.alert({ text })",
+    example: "gui.displays.alert({ text: 'Please review your details before submitting.' })",
+    notes: [
+      "Static, non-input callout. Uses **`text`** (not `content`). Displays do not take a `path`."
+    ]
+  },
+  {
+    factory: "display",
+    namespace: "displays",
+    call: "gui.displays.display(render)",
+    example: "gui.displays.display(() => 'Order summary')",
+    notes: [
+      "**The go-to for a static heading or any standalone/formatted block.** Return your framework’s own content from the render function — React: `gui.displays.display(() => <h2>Member enrollment</h2>)`; Vue/Angular/Lit: return that framework’s node. It renders immediately with **zero registration and no parser dependency** — this is how you put a heading or any static block in a form (GolemUI itself never renders content for display).",
+      "Pass the render function **directly** (not wrapped in an object) — `(params) => any`. `params.$form` is the live form data, so content can be dynamic — but a field is **absent until filled**, so guard before indexing: `Array.isArray(params.$form.items) ? params.$form.items : []`, never `params.$form.items.length` raw."
+    ]
+  }
+];
+const LAYOUTS = [
+  {
+    factory: "flex",
+    namespace: "layouts",
+    call: "gui.layouts.flex(children, props?)",
+    example: "gui.layouts.flex([ gui.inputs.textInput('firstName', { label: 'First name' }), gui.inputs.textInput('lastName', { label: 'Last name' }) ])",
+    notes: [
+      "Layouts take the **children array first**, then optional props — unlike inputs (path first).",
+      "Direction-locked variants: `verticalFlex`, `horizontalFlex` (and `grid` / `verticalGrid` / `horizontalGrid`)."
+    ]
+  },
+  {
+    factory: "verticalFlex",
+    namespace: "layouts",
+    call: "gui.layouts.verticalFlex(children, props?)",
+    example: "gui.layouts.verticalFlex([ gui.inputs.textInput('a', { label: 'A' }), gui.inputs.textInput('b', { label: 'B' }) ])",
+    notes: ["A `flex` with direction fixed to vertical."]
+  },
+  {
+    factory: "horizontalFlex",
+    namespace: "layouts",
+    call: "gui.layouts.horizontalFlex(children, props?)",
+    example: "gui.layouts.horizontalFlex([ gui.inputs.textInput('a', { label: 'A' }), gui.inputs.textInput('b', { label: 'B' }) ])",
+    notes: ["A `flex` with direction fixed to horizontal."]
+  },
+  {
+    factory: "grid",
+    namespace: "layouts",
+    call: "gui.layouts.grid(children, props?)",
+    example: "gui.layouts.grid([ gui.inputs.textInput('a', { label: 'A' }), gui.inputs.textInput('b', { label: 'B' }) ])",
+    notes: ["Grid layout; `horizontalGrid` / `verticalGrid` lock the direction."]
+  },
+  {
+    factory: "verticalGrid",
+    namespace: "layouts",
+    call: "gui.layouts.verticalGrid(children, props?)",
+    example: "gui.layouts.verticalGrid([ gui.inputs.textInput('a', { label: 'A' }), gui.inputs.textInput('b', { label: 'B' }) ])",
+    notes: ["A `grid` with direction fixed to vertical."]
+  },
+  {
+    factory: "horizontalGrid",
+    namespace: "layouts",
+    call: "gui.layouts.horizontalGrid(children, props?)",
+    example: "gui.layouts.horizontalGrid([ gui.inputs.textInput('a', { label: 'A' }), gui.inputs.textInput('b', { label: 'B' }) ])",
+    notes: ["A `grid` with direction fixed to horizontal."]
+  },
+  {
+    factory: "tabs",
+    namespace: "layouts",
+    call: "gui.layouts.tabs(sections)",
+    example: "gui.layouts.tabs([ { label: 'Account', children: [ gui.inputs.textInput('email', { label: 'Email' }) ] }, { label: 'Profile', children: [ gui.inputs.textInput('name', { label: 'Name' }) ] } ])",
+    notes: [
+      "Takes `sections: { label, children, uid? }[]` — each section is a tab with its own children."
+    ]
+  },
+  {
+    factory: "accordion",
+    namespace: "layouts",
+    call: "gui.layouts.accordion(sections)",
+    example: "gui.layouts.accordion([ { label: 'Billing', children: [ gui.inputs.textInput('card', { label: 'Card' }) ] } ])",
+    notes: [
+      "Takes `sections: { label, children, uid? }[]` — same shape as `tabs`, rendered as collapsible panels."
+    ]
+  }
+];
+const ALL = [...INPUTS, ...ACTIONS, ...DISPLAYS, ...LAYOUTS];
+const DX_SPECS = Object.fromEntries(ALL.map((s) => [s.factory, s]));
+function listDxFactories() {
+  return Object.keys(DX_SPECS).sort();
+}
+function dxCatalog(framework = "react") {
+  return {
+    factories: ALL.map(({ factory, namespace, call, example, notes }) => ({
+      factory,
+      namespace,
+      call,
+      example,
+      notes
+    })),
+    patterns: PATTERNS,
+    common: commonNote(framework)
+  };
+}
+function getDxSpec(input) {
+  const spec = DX_SPECS[input?.factory];
+  if (!spec) {
+    throw new Error(
+      `Unknown gui.* factory: ${JSON.stringify(input?.factory)}. Known factories: ${listDxFactories().join(", ")}.`
+    );
+  }
+  return { ...spec };
+}
+const DX_GET_SPEC_TOOL = {
+  name: "dx_get_spec",
+  description: "Deep-dive lookup for ONE `gui.*` factory — its calling convention, a compile-verified example, and authoring notes. **In most cases you do not need this: call `dx_list_factories` once and write from it** — it already carries every factory's example and gotchas plus the cross-cutting rules. Reach here only when you want to re-confirm a single factory in isolation. Lean by design: it returns just that factory's payload (no repeated common note/patterns — those live in `dx_list_factories`). Distinct from `json_get_widget_spec`, which returns the JSON form-definition shape. GolemUI is not in any model's training data, so do NOT guess the API. After writing, verify with `dx_check_code`. Pass `factory` as the camelCase name (e.g. `textInput`, `dropdown`, `radiogroup`, `button`).",
+  inputSchema: {
+    type: "object",
+    properties: {
+      factory: {
+        type: "string",
+        description: 'The gui.* factory name, e.g. "textInput", "dropdown", "button".'
+      }
+    },
+    required: ["factory"]
+  }
+};
+function listDxFactoriesCatalog(framework = resolveDxFramework()) {
+  return dxCatalog(framework);
+}
+const DX_LIST_FACTORIES_TOOL = {
+  name: "dx_list_factories",
+  description: "The complete GolemUI `gui.*` DX reference in ONE call: EVERY factory with its namespace, calling convention, a compile-verified example, and its gotchas — plus the cross-cutting patterns (e.g. conditional visibility) and the common authoring rules (incl. the validator `type` rule). **Call this FIRST when authoring `gui.*` DX code, then write from it directly** — it is self-sufficient for most forms, so you rarely need a follow-up lookup. GolemUI is not in any model's training data, so do NOT guess the API; every real name is here. `dx_get_spec(factory)` is only the rare deep-dive for one factory. You do NOT need `json_get_widget_spec` when writing `gui.*` code — that serves the JSON form-definition surface, a different API. Takes no arguments; fetch once and keep it in context.",
+  inputSchema: {
+    type: "object",
+    properties: {}
+  }
+};
 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.",
@@ -2749,7 +3339,7 @@ const ICONS_CONCEPT = {
     "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."
+    "Do not set `props.icon` on widgets that do not support it — the schema will reject it and `json_validate_form_definition` will report an error."
   ]
 };
 const CONCEPTS = {
@@ -2782,14 +3372,25 @@ const GET_CONCEPT_TOOL = {
   }
 };
 export {
-  GENERATE_FROM_JSON_SCHEMA_TOOL as G,
-  VALIDATE_FORM_DEFINITION_TOOL as V,
-  GENERATE_FROM_OPENAPI_TOOL as a,
-  GET_CONCEPT_TOOL as b,
-  GET_WIDGET_SPEC_TOOL as c,
-  generateFromOpenapi as d,
-  getConcept as e,
-  getWidgetSpec as f,
-  generateFromJsonSchema as g,
+  DX_CHECK_CODE_TOOL as D,
+  GET_CONCEPT_TOOL as G,
+  JSON_GENERATE_FROM_OPENAPI_TOOL as J,
+  DX_GET_SPEC_TOOL as a,
+  DX_LIST_FACTORIES_TOOL as b,
+  DX_SPECS as c,
+  JSON_GENERATE_FROM_SCHEMA_TOOL as d,
+  JSON_GET_WIDGET_SPEC_TOOL as e,
+  JSON_VALIDATE_FORM_DEFINITION_TOOL as f,
+  checkDxCode as g,
+  dxCatalog as h,
+  generateFromJsonSchema as i,
+  generateFromOpenapi as j,
+  getConcept as k,
+  getDxSpec as l,
+  getWidgetSpec as m,
+  listDxFactories as n,
+  listDxFactoriesCatalog as o,
+  resolveDxFramework as r,
+  typeCheckDx as t,
   validateFormDefinition as v
 };