@golemui/gui-mcp 1.0.0-rc.3 → 1.0.0-rc.5

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+## 1.0.0-rc.4 (2026-06-14)
+
+### 🚀 Features
+
+- **mcp:** add type-checked gui.* DX authoring surface ([#185](https://github.com/golemui/golemui/pull/185))
+
+### 🩹 Fixes
+
+- **gui-shared:** make dx event handlers function-only ([#190](https://github.com/golemui/golemui/pull/190))
+- added license field and copied license to all publishable packages ([#189](https://github.com/golemui/golemui/pull/189))
+
+### ❤️ Thank You
+
+- alberto-golem-ui
+- Mud Scientist @mudscientist
+- Raúl Jiménez @Elecash
+
+## 1.0.0-rc.3 (2026-06-13)
+
+This was a version bump only for gui-mcp to align it with other projects, there were no code changes.
+
 ## 1.0.0-rc.2 (2026-06-10)
 
 This was a version bump only for gui-mcp to align it with other projects, there were no code changes.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GolemUI S.L.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -9,6 +9,30 @@ strict enough that one wrong property name breaks the runtime. This server close
 your AI calls it to **validate** what it wrote and to **generate** forms from existing
 JSON Schemas or OpenAPI operations, with the bundled GolemUI schemas as the source of truth.
 
+## Two entry points (one surface, two ways to author it)
+
+A GolemUI form can be written two ways, and the MCP serves both:
+
+- a **JSON form definition**: the serializable object `{ form: [...widgets], states?: {...} }`;
+- **`gui.*` DX code**: the fluent TypeScript builder that _produces_ that same definition.
+
+There is no toggle. On connect the server sends one block of guidance (the MCP `initialize.instructions`
+field, `SERVER_INSTRUCTIONS` in [`src/cli.ts`](./src/cli.ts)) and the agent self-routes by what it is
+producing:
+
+1. **JSON path**: generate or hand-author, then **always finish with `json_validate_form_definition`**.
+2. **`gui.*` path**: call **`dx_list_factories` first** (the complete reference), write the form, then
+   **always finish with `dx_check_code`**.
+
+The two terminal checks are not interchangeable: `dx_check_code` validates `gui.*` _code_,
+`json_validate_form_definition` validates a JSON _object_. Each tool's own `description` reinforces the routing
+(e.g. `json_get_widget_spec` tells a `gui.*` author it isn't needed). To read what a client actually sees, run
+`npm run start:mcp` (the MCP Inspector).
+
+The split is structural, not just textual: the two paths live in separate modules
+([`src/json/`](./src/json) and [`src/dx/`](./src/dx)) over a small shared surface
+([`src/shared/`](./src/shared)); neither imports the other.
+
 ## Install
 
 The server is a standalone Node CLI distributed on npm. Add it to your IDE's MCP config —
@@ -46,7 +70,7 @@ npx -y @golemui/gui-mcp < /dev/null
 
 ## Tools
 
-### `validate_form_definition`
+### `json_validate_form_definition`
 
 Validates a GolemUI form definition against the bundled JSON Schemas. Returns
 `{ valid: true }` on success, or a structured list of errors with JSON Pointer paths
@@ -56,7 +80,7 @@ like missing `$form.` prefixes, single `=` in equality checks, and unbalanced br
 
 **Input:** `{ formDefinition: { form: [...], states?: {...} } }`
 
-### `generate_from_json_schema`
+### `json_generate_from_schema`
 
 Maps a JSON Schema (the form-data shape, e.g. a Zod-derived schema) into a GolemUI
 form definition. Handles strings (with `format` → specialized widgets), numbers,
@@ -66,7 +90,7 @@ not be mapped.
 
 **Input:** `{ jsonSchema, submitAction?, submitLabel?, layout? }`
 
-### `generate_from_openapi`
+### `json_generate_from_openapi`
 
 Resolves an OpenAPI 3.x operation (e.g. `"POST /users"` or an `operationId`), dereferences
 its request body schema, and emits a validated GolemUI form. Falls back to operation
@@ -74,7 +98,7 @@ parameters when no JSON request body is present.
 
 **Input:** `{ document | documentUrl, operation, submitAction?, submitLabel? }`
 
-### `get_widget_spec`
+### `json_get_widget_spec`
 
 Returns the JSON Schema, kind, a minimal working example, and authoring notes for a
 single GolemUI widget. Cheaper than dumping the whole API into the model's context.
@@ -84,12 +108,42 @@ single GolemUI widget. Cheaper than dumping the whole API into the model's conte
 
 ### `get_concept`
 
-Returns a detailed guide for a cross-cutting concept - things that span multiple widgets
-and affect the whole form. Use it when you need state-suffixed props
-(`"label.stateName": "..."`) or to reuse a condition across multiple widgets via
-`include`/`exclude`. Currently supported: `"states"`, `"string-interpolation"`.
+Returns a detailed guide for a cross-cutting concept — things that span multiple widgets
+and affect the whole form: conditional rendering (`include`/`exclude`, named-state and
+inline `when`), state-suffixed props (`"label.stateName": "..."`), the reactive scope
+(`$form`, `$meta`, `$errors`, `$formIsInvalid`), and widget icons.
+
+**Input:** `{ concept }` — one of `"states"`, `"string-interpolation"`, `"reactive-scope"`, `"icons"`
+
+> The five tools above serve the **JSON** surface. The three below serve the **`gui.*`** (DX code) surface —
+> see [Two entry points](#two-entry-points-one-surface-two-ways-to-author-it).
+
+### `dx_list_factories`
 
-**Input:** `{ concept }` - one of `"states"`, `"string-interpolation"`
+**Call this first when writing `gui.*` code.** Returns the complete `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 and the common authoring rules. Its imports + render snippet are **tailored to your
+target framework** (`GOLEMUI_FRAMEWORK`). Self-sufficient for most forms; keep it in context and write from it.
+
+**Input:** none.
+
+### `dx_get_spec`
+
+A rare single-factory deep-dive — one factory's calling convention, example, and notes. Usually unneeded
+(`dx_list_factories` already carries every factory); reach here only to re-confirm one in isolation.
+
+**Input:** `{ factory }` — the camelCase name (`textInput`, `dropdown`, `radiogroup`, `button`, …).
+
+### `dx_check_code`
+
+**The `gui.*` terminal check** — the counterpart of `json_validate_form_definition` for _code_ instead of a JSON
+_object_. Type-checks the snippet against the **real `@golemui` type declarations** (compile-is-truth: GolemUI
+isn't in any model's training data, so generated `gui.*` is often a confident fabrication that doesn't
+compile). Also catches two compiler-invisible footguns — a misplaced `include`/`exclude` on a `gui.*` spread,
+and reactive-expression mistakes in `when` strings. Returns `{ ok, diagnostics }`; each diagnostic carries a
+fix `hint`. Treat `ok: false` as blocking.
+
+**Input:** `{ code }` — the `gui.*` snippet (a bare `gui.inputs.*` array is fine; the import is added if missing).
 
 ## Library usage
 
@@ -126,17 +180,6 @@ const { form } = await generateFromOpenapi({
 The tool descriptor objects (`VALIDATE_FORM_DEFINITION_TOOL`, `GENERATE_FROM_JSON_SCHEMA_TOOL`, ...)
 are also exported if you want to register the tools in your own MCP server.
 
-## How it stays accurate
-
-The server ships a frozen snapshot of the GolemUI JSON Schemas inside its npm package,
-version-locked to a specific GolemUI release. A CI check in this monorepo
-(`npm run check:mcp-schemas`) fails if the snapshot drifts from the source schemas in
-`@golemui/gui-shared`, so a published `@golemui/gui-mcp@X.Y.Z` always validates
-against the exact same schema definitions as `@golemui/gui-*@X.Y.Z`.
-
-No LLM calls happen inside this server — every tool is deterministic. The MCP is the
-_grounding layer_ the host IDE's model calls into.
-
 ## Development
 
 ### Interactive testing with MCP Inspector
@@ -174,7 +217,7 @@ Create or edit the project-level MCP config at .mcp.json in the workspace root:
 }
 ```
 
-Then reload the VS Code window (Cmd+Shift+P -> "Developer: Reload Window"). The 4 tools will appear in Claude's tool list for this workspace.
+Then reload the VS Code window (Cmd+Shift+P -> "Developer: Reload Window"). The tools will appear in Claude's tool list for this workspace.
 
 Remove the entry from .mcp.json when done.
 
@@ -182,6 +225,4 @@ Remove the entry from .mcp.json when done.
 
 ```bash
 npx nx run gui-mcp:vite:test     # run the test suite
-npm run sync:mcp-schemas            # refresh bundled schemas from libs/gui/shared
-npm run check:mcp-schemas           # CI mode — exits non-zero if out of sync
 ```

package/cli.js

@@ -5,7 +5,38 @@ 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, a as GENERATE_FROM_OPENAPI_TOOL, c as GET_WIDGET_SPEC_TOOL, b as GET_CONCEPT_TOOL, e as getConcept, f as getWidgetSpec, d as generateFromOpenapi, g as generateFromJsonSchema, v as validateFormDefinition } from "./get-concept-B7s_l8Qs.js";
+import { r as resolveDxFramework, f as listDxFactoriesCatalog, b as DX_LIST_FACTORIES_TOOL, g as getDxSpec, a as DX_GET_SPEC_TOOL, d as checkDxCode, D as DX_CHECK_CODE_TOOL } from "./list-dx-factories-CF4ExKyx.js";
+import { v as validateFormDefinition, c as JSON_VALIDATE_FORM_DEFINITION_TOOL, g as generateFromJsonSchema, a as JSON_GENERATE_FROM_SCHEMA_TOOL, d as generateFromOpenapi, J as JSON_GENERATE_FROM_OPENAPI_TOOL, f as getWidgetSpec, b as JSON_GET_WIDGET_SPEC_TOOL, e as getConcept, G as GET_CONCEPT_TOOL } from "./get-concept-Cy3zD1BS.js";
+const DX_INSTRUCTIONS = "Writing GolemUI as DX code (the `gui.*` fluent builder in TypeScript) instead of a JSON definition? GolemUI is not in any model training data, so `gui.*` code is easy to fabricate — do NOT guess the API. FIRST call `dx_list_factories` once: it is the COMPLETE reference — every factory with its signature, a compile-verified example, and its gotchas, plus the cross-cutting patterns and common rules. Its imports + render snippet are tailored to your target framework (" + resolveDxFramework() + ") — use them verbatim; import `gui` ONLY from `@golemui/gui-shared`, never hand-write raw `{ kind, type, path }` widget JSON or cast to `any`. Keep it in context and write your whole form from it; it is self-sufficient for most forms. `dx_get_spec` is only a rare single-factory deep-dive — you usually will not need it, and you do NOT need `json_get_widget_spec` here (that is the JSON surface). Then ALWAYS finish by calling `dx_check_code` with the snippet — it type-checks against the real `@golemui` declarations and returns `{ ok, diagnostics }` (each with a fix `hint` for recognized mistakes). Treat `ok: false` as blocking: apply the fixes and re-check until `ok` is true. Use `dx_check_code` for `gui.*` *code* and `json_validate_form_definition` for a JSON *definition object* — they are not interchangeable.\n\n";
+function defineTool(tool, handler) {
+  return { tool, run: (args) => handler(args) };
+}
+function ok(payload) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }]
+  };
+}
+function err(message) {
+  return {
+    isError: true,
+    content: [{ type: "text", text: message }]
+  };
+}
+const dxTools = [
+  // `dx_list_factories` takes no arguments — it defaults the framework from the env, so
+  // its handler ignores the (empty) MCP arguments object.
+  defineTool(DX_LIST_FACTORIES_TOOL, () => listDxFactoriesCatalog()),
+  defineTool(DX_GET_SPEC_TOOL, getDxSpec),
+  defineTool(DX_CHECK_CODE_TOOL, checkDxCode)
+];
+const JSON_INSTRUCTIONS = '1. Starting from an existing schema? Use a generator — both return a pre-validated definition, so check the returned `unmapped` list and surface anything left over to the user. For a raw JSON Schema (e.g. an API request body), call `json_generate_from_schema`. For an OpenAPI 3.x spec, call `json_generate_from_openapi`: pass `operation` as "METHOD /path" (e.g. "POST /users") or an exact operationId, plus the spec as a parsed `document` or a `documentUrl` to fetch — it resolves the operation\'s request body, dereferences `$ref`s, and falls back to the operation\'s parameters when there is no request body.\n2. Building or editing by hand? Look up a single widget with `json_get_widget_spec` (its `kind`, `props`, and `validator` shape), and cross-cutting behavior that spans widgets — conditional rendering, per-state prop overrides — with `get_concept`.\n3. ALWAYS finish by calling `json_validate_form_definition`. It checks the definition against the bundled JSON Schemas and returns `{ valid, errors, warnings, expressionWarnings }`. Treat `errors` as blocking: fix them and re-validate until `valid` is true. `warnings` (likely-custom widgets) and `expressionWarnings` (linted reactive expressions) are advisory — surface them, but they do not flip `valid`.\n\n';
+const jsonTools = [
+  defineTool(JSON_VALIDATE_FORM_DEFINITION_TOOL, validateFormDefinition),
+  defineTool(JSON_GENERATE_FROM_SCHEMA_TOOL, generateFromJsonSchema),
+  defineTool(JSON_GENERATE_FROM_OPENAPI_TOOL, generateFromOpenapi),
+  defineTool(JSON_GET_WIDGET_SPEC_TOOL, getWidgetSpec)
+];
+const sharedTools = [defineTool(GET_CONCEPT_TOOL, getConcept)];
 function readPackageMeta() {
   const here = dirname(fileURLToPath(import.meta.url));
   for (const candidate of [join(here, "package.json"), join(here, "..", "package.json")]) {
@@ -18,51 +49,28 @@ function readPackageMeta() {
   return { name: "@golemui/gui-mcp", version: "0.0.0" };
 }
 const { name: PKG_NAME, version: PKG_VERSION } = readPackageMeta();
-const TOOLS = [
-  VALIDATE_FORM_DEFINITION_TOOL,
-  GENERATE_FROM_JSON_SCHEMA_TOOL,
-  GENERATE_FROM_OPENAPI_TOOL,
-  GET_WIDGET_SPEC_TOOL,
-  GET_CONCEPT_TOOL
-];
-const SERVER_INSTRUCTIONS = 'This server builds and validates GolemUI form definitions — declarative, JSON-serializable forms shaped as `{ form: [...widgets], states?: {...} }`. Its job is to help you produce a form definition that is guaranteed correct before the user pastes it into their codebase.\n\nRecommended workflow:\n1. Starting from an existing schema? Use a generator — both return a pre-validated definition, so check the returned `unmapped` list and surface anything left over to the user. For a raw JSON Schema (e.g. an API request body), call `generate_from_json_schema`. For an OpenAPI 3.x spec, call `generate_from_openapi`: pass `operation` as "METHOD /path" (e.g. "POST /users") or an exact operationId, plus the spec as a parsed `document` or a `documentUrl` to fetch — it resolves the operation\'s request body, dereferences `$ref`s, and falls back to the operation\'s parameters when there is no request body.\n2. Building or editing by hand? Look up a single widget with `get_widget_spec` (its `kind`, `props`, and `validator` shape), and cross-cutting behavior that spans widgets — conditional rendering, per-state prop overrides — with `get_concept`.\n3. ALWAYS finish by calling `validate_form_definition`. It checks the definition against the bundled JSON Schemas and returns `{ valid, errors, warnings, expressionWarnings }`. Treat `errors` as blocking: fix them and re-validate until `valid` is true. `warnings` (likely-custom widgets) and `expressionWarnings` (linted reactive expressions) are advisory — surface them, but they do not flip `valid`.\n\nDo not hand a form definition to the user until `validate_form_definition` reports `valid: true`.';
+const TOOL_ENTRIES = [...jsonTools, ...sharedTools, ...dxTools];
+const TOOL_BY_NAME = new Map(TOOL_ENTRIES.map((e) => [e.tool.name, e]));
+const PREAMBLE = "This server builds and validates GolemUI form definitions — declarative, JSON-serializable forms shaped as `{ form: [...widgets], states?: {...} }`. Its job is to help you produce a form definition that is guaranteed correct before the user pastes it into their codebase.\n\nRecommended workflow:\n";
+const CLOSER = "Do not hand a form definition to the user until `json_validate_form_definition` reports `valid: true`.";
+const SERVER_INSTRUCTIONS = PREAMBLE + JSON_INSTRUCTIONS + DX_INSTRUCTIONS + CLOSER;
 const server = new Server(
   { name: PKG_NAME, version: PKG_VERSION },
   { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS }
 );
-server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: TOOL_ENTRIES.map((e) => e.tool)
+}));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
+  const entry = TOOL_BY_NAME.get(name);
+  if (!entry) return err(`Unknown tool: ${name}`);
   try {
-    switch (name) {
-      case "validate_form_definition":
-        return ok(validateFormDefinition(args));
-      case "generate_from_json_schema":
-        return ok(generateFromJsonSchema(args));
-      case "generate_from_openapi":
-        return ok(await generateFromOpenapi(args));
-      case "get_widget_spec":
-        return ok(getWidgetSpec(args));
-      case "get_concept":
-        return ok(getConcept(args));
-      default:
-        return err(`Unknown tool: ${name}`);
-    }
+    return ok(await entry.run(args));
   } catch (e) {
     return err(e.message);
   }
 });
-function ok(payload) {
-  return {
-    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }]
-  };
-}
-function err(message) {
-  return {
-    isError: true,
-    content: [{ type: "text", text: message }]
-  };
-}
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);

package/dx/check-dx-code.d.ts

@@ -0,0 +1,25 @@
+import { DxCheckResult } from './typecheck';
+export type CheckDxCodeInput = {
+    /** A `gui.*` DX snippet (TypeScript). May be a bare array of `gui.inputs.*` items. */
+    code: string;
+};
+export type CheckDxCodeResult = DxCheckResult;
+/**
+ * Type-check GolemUI DX code against the real `@golemui` declarations and return
+ * compiler diagnostics. Async because the TypeScript compiler is loaded lazily.
+ */
+export declare function checkDxCode(input: CheckDxCodeInput): Promise<CheckDxCodeResult>;
+export declare const DX_CHECK_CODE_TOOL: {
+    readonly name: "dx_check_code";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly code: {
+                readonly type: "string";
+                readonly description: "The GolemUI `gui.*` DX snippet to type-check (TypeScript).";
+            };
+        };
+        readonly required: readonly ["code"];
+    };
+};

package/dx/dx-lint.d.ts

@@ -0,0 +1,27 @@
+import { ExpressionFinding } from '../shared/lint/reactive-expressions';
+import { DxDiagnostic } from './typecheck';
+import type * as TS from 'typescript';
+/**
+ * Static lints over a `gui.*` DX snippet that the TypeScript compiler cannot catch.
+ *
+ * The compiler is the truthful gate for *type* errors, but two real defects slip past
+ * it because the code is structurally valid TypeScript:
+ *
+ *  1. **Misplaced `include`/`exclude` (the silent no-op).** Spreading a factory result
+ *     and attaching `include`/`exclude`/`disabled`/`readonly` as a SIBLING
+ *     (`{ ...gui.inputs.x(...), include: { when } }`) compiles — TS suppresses excess-property
+ *     checks on object literals containing a spread — but the field never sees the
+ *     condition, so it renders/behaves unconditionally. The arena caught this on a real
+ *     "hide when" task. Reported as a blocking `diagnostic`.
+ *
+ *  2. **Reactive-expression quality.** The `when` strings inside `include`/`exclude`/etc.
+ *     are opaque to the type-checker. We funnel each through the SAME engine the JSON
+ *     `json_validate_form_definition` path uses ({@link checkReactiveExpression}), so the two
+ *     surfaces share one set of rules. Reported as non-blocking `expressionWarnings`,
+ *     mirroring the JSON path.
+ */
+export interface DxLintResult {
+    diagnostics: DxDiagnostic[];
+    expressionWarnings: ExpressionFinding[];
+}
+export declare function lintDxSnippet(ts: typeof TS, sourceText: string, lineOffset: number): DxLintResult;

package/dx/dx-specs.d.ts

@@ -0,0 +1,70 @@
+/**
+ * DX grounding registry — the real `gui.*` builder surface, one entry per factory.
+ *
+ * GolemUI is not in any model's training data, so a cold model fabricates the
+ * `gui.*` API wholesale. This registry is what `dx_get_spec` serves so the model
+ * writes the real thing. Every `example` here is **compile-verified against the
+ * real `@golemui` types** by `dx-specs.spec.ts` — if an example is wrong, the test
+ * suite fails. (Hand-written references are unreliable even with repo access; the
+ * compile gate is the cure.)
+ */
+export type DxNamespace = 'inputs' | 'actions' | 'displays' | 'layouts';
+export interface DxSpec {
+    /** Factory name, e.g. `textInput`. */
+    factory: string;
+    namespace: DxNamespace;
+    /** Human-readable calling convention. */
+    call: string;
+    /** A compiling `gui.*` snippet (verified by the suite). */
+    example: string;
+    /** Authoring notes and gotchas. */
+    notes: string[];
+}
+/**
+ * A cross-cutting authoring pattern that is NOT a single factory — e.g. conditional
+ * visibility, which is a common field available on every `gui.*` item. Same compile
+ * guarantee as `DxSpec`: every `example` is verified by `dx-specs.spec.ts`.
+ */
+export interface DxPattern {
+    /** Short identifier, e.g. `conditionalVisibility`. */
+    name: string;
+    /** One-line title. */
+    title: string;
+    /** A compiling `gui.*` snippet (verified by the suite). */
+    example: string;
+    notes: string[];
+}
+export type DxFramework = 'react' | 'angular' | 'vue' | 'lit' | 'vanilla';
+export declare function resolveDxFramework(): DxFramework;
+export declare const DX_SPECS: Record<string, DxSpec>;
+export declare function listDxFactories(): string[];
+/**
+ * One catalog row — enough to WRITE the factory without a follow-up lookup: name, namespace,
+ * signature, a compile-verified example, and the authoring gotchas.
+ */
+export interface DxCatalogEntry {
+    factory: string;
+    namespace: DxNamespace;
+    call: string;
+    example: string;
+    notes: string[];
+}
+export interface DxCatalog {
+    /** Every factory, in `inputs → actions → displays → layouts` order — call + example + notes. */
+    factories: DxCatalogEntry[];
+    /** Cross-cutting patterns (e.g. conditional visibility) — full example + notes, resident once. */
+    patterns: DxPattern[];
+    /** The cross-cutting authoring note shared by all factories (incl. the validator `type` rule). */
+    common: string;
+}
+/**
+ * The whole `gui.*` surface as a SELF-SUFFICIENT reference in one payload: every factory's
+ * signature, a compile-verified example, and its gotchas, plus the cross-cutting patterns and the
+ * common note. Serves `dx_list_factories`. The agentic intent: the model fetches this ONCE, keeps
+ * it resident, and writes most forms from it directly — `dx_get_spec` becomes the rare deep-dive,
+ * not a per-factory round-trip. (Richer than a name-only index by design: in a resumed session
+ * this is paid once and reused, so front-loading the examples removes mid-task lookups and turns.)
+ */
+export declare function dxCatalog(framework?: DxFramework): DxCatalog;
+export declare function dxCommonNote(framework?: DxFramework): string;
+export declare function dxPatterns(): DxPattern[];

package/dx/get-dx-spec.d.ts

@@ -0,0 +1,27 @@
+import { DxSpec } from './dx-specs';
+export type GetDxSpecInput = {
+    /** The `gui.*` factory name, e.g. `textInput`, `dropdown`, `button`. */
+    factory: string;
+};
+export type GetDxSpecResult = DxSpec;
+/**
+ * Return the real `gui.*` builder signature, a compile-verified example, and authoring notes
+ * for a SINGLE factory — the deep-dive lookup. Lean by design: the cross-cutting common note
+ * and patterns are NOT re-shipped here (they ride in `dx_list_factories`, fetched once), so a
+ * follow-up lookup adds only the factory's own payload to the agent's context.
+ */
+export declare function getDxSpec(input: GetDxSpecInput): GetDxSpecResult;
+export declare const DX_GET_SPEC_TOOL: {
+    readonly name: "dx_get_spec";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly factory: {
+                readonly type: "string";
+                readonly description: "The gui.* factory name, e.g. \"textInput\", \"dropdown\", \"button\".";
+            };
+        };
+        readonly required: readonly ["factory"];
+    };
+};

package/dx/instructions.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The `gui.*` DX half of the server's connect-time guidance (the MCP
+ * `initialize.instructions` field). Composed with the JSON half in `cli.ts`. The target
+ * framework name is interpolated from the environment at module load, the same as the
+ * `dx_list_factories` catalog, so the agent is steered to the correct host wiring.
+ */
+export declare const DX_INSTRUCTIONS: string;

package/dx/list-dx-factories.d.ts

@@ -0,0 +1,19 @@
+import { DxCatalog, DxFramework } from './dx-specs';
+export type ListDxFactoriesResult = DxCatalog;
+/**
+ * Return the entire `gui.*` DX surface in one payload: every factory name + one-line
+ * signature, the cross-cutting pattern names, and the common note. The catalog the agent
+ * fetches ONCE before authoring, instead of paying a `dx_get_spec` round-trip per factory.
+ *
+ * The common note's imports + render snippet are tailored to `framework` (defaults to the
+ * `GOLEMUI_FRAMEWORK` env, else react) so the agent is shown the correct host wiring.
+ */
+export declare function listDxFactoriesCatalog(framework?: DxFramework): ListDxFactoriesResult;
+export declare const DX_LIST_FACTORIES_TOOL: {
+    readonly name: "dx_list_factories";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {};
+    };
+};

package/dx/tools.d.ts

@@ -0,0 +1,3 @@
+import { ToolEntry } from '../shared/tool';
+/** The `gui.*` DX path's MCP tools: list the catalog, deep-dive one factory, type-check. */
+export declare const dxTools: ToolEntry[];

package/dx/type-graph.d.ts

@@ -0,0 +1,10 @@
+import type * as TS from 'typescript';
+/** Build the compiler options that resolve `gui.*` against the real `@golemui` types. */
+export declare function resolveTypeCheckOptions(ts: typeof TS): TS.CompilerOptions;
+/**
+ * Compile a single in-memory file against the type graph and return ONLY that file's
+ * diagnostics (the host serves {@link SNIPPET_FILE} from memory; every other file is read
+ * from disk as usual).
+ */
+export declare function diagnose(ts: typeof TS, code: string, options: TS.CompilerOptions): readonly TS.Diagnostic[];
+export declare function assertTypesAreLive(ts: typeof TS, options: TS.CompilerOptions): void;

package/dx/typecheck.d.ts

@@ -0,0 +1,41 @@
+import { ExpressionFinding } from '../shared/lint/reactive-expressions';
+/**
+ * In-process TypeScript type-check of a `gui.*` DX snippet against the real `@golemui`
+ * type graph. This is the *truthful* gate: the arena spike proved that regex and even
+ * careful human inspection score hallucinated GolemUI code as "valid" — only the compiler
+ * tells the truth.
+ *
+ * `typescript` is imported lazily (see {@link loadTs}) so this module — and the heavy
+ * compiler dependency — is only ever loaded when a DX tool is actually called; the JSON
+ * validation path never touches it. The fragile part — locating and compiling against the
+ * `@golemui` declarations — lives in `./type-graph`; this file only orchestrates a check
+ * and turns compiler output into GolemUI-flavored diagnostics.
+ */
+export interface DxDiagnostic {
+    /** TypeScript diagnostic code, e.g. 2769. */
+    code: number;
+    /** Flattened, single-line diagnostic message. */
+    message: string;
+    /** 1-based line within the submitted snippet (0 if unknown). */
+    line: number;
+    /** 1-based column within the submitted snippet (0 if unknown). */
+    column: number;
+    /** A GolemUI-specific fix suggestion, when we recognize the error. */
+    hint?: string;
+}
+export interface DxCheckResult {
+    /** True when the snippet type-checks clean AND carries no blocking lint diagnostics. */
+    ok: boolean;
+    diagnostics: DxDiagnostic[];
+    /**
+     * Non-blocking reactive-expression findings (the `when` strings inside `include`/`exclude`/
+     * etc.), linted by the same engine as the JSON path. Advisory — they do not flip `ok`.
+     */
+    expressionWarnings: ExpressionFinding[];
+}
+/**
+ * Type-check a `gui.*` DX snippet against the real `@golemui` types.
+ * If the snippet does not import `gui`, a `@golemui/gui-shared` import is prepended,
+ * so a bare array of `gui.inputs.*` items can be checked directly.
+ */
+export declare function typeCheckDx(code: string): Promise<DxCheckResult>;

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

@@ -1081,6 +1081,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 +1375,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 +1386,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 +1770,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 +1925,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 +2262,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: {
@@ -2749,7 +2754,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 +2787,15 @@ 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,
+  GET_CONCEPT_TOOL as G,
+  JSON_GENERATE_FROM_OPENAPI_TOOL as J,
+  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
 };