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

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

@@ -1,9 +1,5 @@
 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";
@@ -2280,587 +2276,6 @@ const JSON_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.",
@@ -3372,25 +2787,15 @@ const GET_CONCEPT_TOOL = {
   }
 };
 export {
-  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,
+  JSON_GENERATE_FROM_SCHEMA_TOOL as a,
+  JSON_GET_WIDGET_SPEC_TOOL as b,
+  JSON_VALIDATE_FORM_DEFINITION_TOOL as c,
+  generateFromOpenapi as d,
+  getConcept as e,
+  getWidgetSpec as f,
+  generateFromJsonSchema as g,
+  checkReactiveExpression as h,
   validateFormDefinition as v
 };

package/json.d.ts

@@ -0,0 +1,7 @@
+export { validateFormDefinition, JSON_VALIDATE_FORM_DEFINITION_TOOL, } from './json/validate-form-definition';
+export type { ValidateInput, ValidateResult } from './json/validate-form-definition';
+export { generateFromJsonSchema, JSON_GENERATE_FROM_SCHEMA_TOOL, } from './json/generate-from-json-schema';
+export type { GenerateFromJsonSchemaInput, GenerateFromJsonSchemaResult, } from './json/generate-from-json-schema';
+export { generateFromOpenapi, JSON_GENERATE_FROM_OPENAPI_TOOL } from './json/generate-from-openapi';
+export { getWidgetSpec, JSON_GET_WIDGET_SPEC_TOOL } from './json/get-widget-spec';
+export { getConcept, GET_CONCEPT_TOOL } from './shared/get-concept';