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

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 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.
+
 ## 1.0.0-rc.1 (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,37 @@ 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, o as listDxFactoriesCatalog, b as DX_LIST_FACTORIES_TOOL, l as getDxSpec, a as DX_GET_SPEC_TOOL, g as checkDxCode, D as DX_CHECK_CODE_TOOL, v as validateFormDefinition, f as JSON_VALIDATE_FORM_DEFINITION_TOOL, i as generateFromJsonSchema, d as JSON_GENERATE_FROM_SCHEMA_TOOL, j as generateFromOpenapi, J as JSON_GENERATE_FROM_OPENAPI_TOOL, m as getWidgetSpec, e as JSON_GET_WIDGET_SPEC_TOOL, k as getConcept, G as GET_CONCEPT_TOOL } from "./get-concept-DMoitPWv.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 +48,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>;