jui-tools-mcp-server 2.13.0 → 2.14.0

package/data/component_metadata.json

@@ -2,6 +2,7 @@
   "_description": "Per-component presentation metadata consumed by jsonui-mcp-server. Augments attribute_definitions.json (which defines the raw attribute schema, including binding_direction per attribute) with human descriptions, aliases, platform availability, platform-specific implementation notes, and agent-facing rules. Edit this file to change what `lookup_component` / `search_components` / `lookup_attribute` return from the MCP.",
   "_schema": {
     "description": "string",
+    "interactive": "boolean — REQUIRED on every type: whether a user can operate this component on its own (a control, an input, or a scrolling / embedding container). A tappable that holds one is not flattened into a single button for screen readers (shared/core/tap_accessibility.rb). Declared, never derived: Button, Radio and Web declare no two-way binding and are operable.",
     "aliases": "string[]",
     "platforms": {
       "swift_generated": "boolean",
@@ -15,6 +16,7 @@
   },
   "Label": {
     "description": "Text display component",
+    "interactive": false,
     "aliases": [
       "Text"
     ],
@@ -49,6 +51,7 @@
   },
   "TextField": {
     "description": "Text input field",
+    "interactive": true,
     "aliases": [
       "EditText",
       "Input"
@@ -86,6 +89,7 @@
   },
   "Button": {
     "description": "Tappable button component",
+    "interactive": true,
     "aliases": [],
     "platforms": {
       "swift_generated": true,
@@ -117,6 +121,7 @@
   },
   "Image": {
     "description": "Local image component",
+    "interactive": false,
     "aliases": [
       "CircleImage",
       "CircleImageView",
@@ -153,6 +158,7 @@
   },
   "NetworkImage": {
     "description": "Remote/network image component",
+    "interactive": false,
     "aliases": [],
     "platforms": {
       "swift_generated": true,
@@ -174,12 +180,12 @@
       }
     },
     "rules": [
-      "Default contentMode is .center for matchParent (Swift)",
       "Supports placeholder/error images via defaultImage"
     ]
   },
   "View": {
     "description": "Container view (HStack/VStack/ZStack)",
+    "interactive": false,
     "aliases": [],
     "platforms": {
       "swift_generated": true,
@@ -212,6 +218,7 @@
   },
   "ScrollView": {
     "description": "Scrollable container",
+    "interactive": true,
     "aliases": [],
     "platforms": {
       "swift_generated": true,
@@ -238,6 +245,7 @@
   },
   "Collection": {
     "description": "List/grid collection with data binding",
+    "interactive": true,
     "aliases": [
       "Table",
       "TableView",
@@ -270,11 +278,12 @@
       "Sections support different cell types per section",
       "cellIdProperty extracts unique keys from item data",
       "scrollTo binding enables programmatic scrolling",
-      "lazy (default true) controls virtualization: true uses LazyVStack/LazyColumn/LazyVerticalGrid with internal scroll; false renders eagerly in a plain VStack/Column with NO scroll container (use when nested in an already-scrollable parent). Sticky headers and paging require lazy: true."
+      "lazy (default 'lazy') is the outer container: 'lazy' virtualizes (LazyVStack/LazyColumn/LazyVerticalGrid with internal scroll); 'eager' draws every cell in a scroll container, with no virtualization; 'none' draws them with NO scroll container (use when nested in an already-scrollable parent). Sticky headers and paging require 'lazy'."
     ]
   },
   "Switch": {
     "description": "Toggle switch (iOS style)",
+    "interactive": true,
     "aliases": [],
     "platforms": {
       "swift_generated": true,
@@ -302,6 +311,7 @@
   },
   "Toggle": {
     "description": "Toggle control (checkbox style)",
+    "interactive": true,
     "aliases": [],
     "platforms": {
       "swift_generated": true,
@@ -328,6 +338,7 @@
   },
   "CheckBox": {
     "description": "Checkbox input",
+    "interactive": true,
     "aliases": [
       "Check",
       "Checkbox"
@@ -357,6 +368,7 @@
   },
   "Radio": {
     "description": "Radio button group",
+    "interactive": true,
     "aliases": [],
     "platforms": {
       "swift_generated": true,
@@ -382,6 +394,7 @@
   },
   "SelectBox": {
     "description": "Dropdown/picker selection",
+    "interactive": true,
     "aliases": [],
     "platforms": {
       "swift_generated": true,
@@ -407,6 +420,7 @@
   },
   "Segment": {
     "description": "Segmented control",
+    "interactive": true,
     "aliases": [],
     "platforms": {
       "swift_generated": true,
@@ -433,6 +447,7 @@
   },
   "Slider": {
     "description": "Slider/range input",
+    "interactive": true,
     "aliases": [],
     "platforms": {
       "swift_generated": true,
@@ -454,12 +469,13 @@
     },
     "rules": [
       "value/bind is two-way binding",
-      "minimumValue/maximumValue define range (default 0-100)",
+      "minimum / maximum define the range (default 0 and 1: with neither set the range is 0 .. 1); minimumValue / minValue and maximumValue / maxValue are alias spellings",
       "step defines discrete steps"
     ]
   },
   "Progress": {
     "description": "Progress bar/indicator",
+    "interactive": false,
     "aliases": [],
     "platforms": {
       "swift_generated": true,
@@ -485,6 +501,7 @@
   },
   "Indicator": {
     "description": "Activity indicator / loading spinner",
+    "interactive": false,
     "aliases": [],
     "platforms": {
       "swift_generated": true,
@@ -508,11 +525,12 @@
   },
   "CircleView": {
     "description": "Circular shape view",
+    "interactive": false,
     "aliases": [],
     "platforms": {
       "swift_generated": false,
       "swift_dynamic": false,
-      "kotlin_generated": false,
+      "kotlin_generated": true,
       "kotlin_dynamic": true,
       "react": true
     },
@@ -531,6 +549,7 @@
   },
   "GradientView": {
     "description": "Gradient background view",
+    "interactive": false,
     "aliases": [],
     "platforms": {
       "swift_generated": true,
@@ -556,6 +575,7 @@
   },
   "Blur": {
     "description": "Blur effect view",
+    "interactive": false,
     "aliases": [],
     "platforms": {
       "swift_generated": true,
@@ -581,6 +601,7 @@
   },
   "IconLabel": {
     "description": "Icon with label combination",
+    "interactive": false,
     "aliases": [],
     "platforms": {
       "swift_generated": true,
@@ -606,6 +627,7 @@
   },
   "Web": {
     "description": "Web view / embedded browser",
+    "interactive": true,
     "aliases": [],
     "platforms": {
       "swift_generated": true,
@@ -626,11 +648,13 @@
       }
     },
     "rules": [
-      "url attribute specifies the web page to load"
+      "url attribute specifies the web page to load",
+      "Error face + retry (iOS / Android only): bind onLoadFailed to a ViewModel method that hides the Web and shows the error, and bind reloadToken to an Int the retry method increments — the Web reloads its own url each time the value changes. Rewriting url to the same value does not reload."
     ]
   },
   "SafeAreaView": {
     "description": "Safe area respecting container",
+    "interactive": false,
     "aliases": [],
     "platforms": {
       "swift_generated": true,
@@ -653,6 +677,7 @@
   },
   "TabView": {
     "description": "Tab-based navigation container",
+    "interactive": true,
     "aliases": [],
     "platforms": {
       "swift_generated": true,
@@ -678,6 +703,7 @@
   },
   "TextView": {
     "description": "Multi-line text input",
+    "interactive": true,
     "aliases": [],
     "platforms": {
       "swift_generated": true,
@@ -704,11 +730,12 @@
   },
   "EditText": {
     "description": "Text input (Android naming convention)",
+    "interactive": true,
     "aliases": [],
     "platforms": {
       "swift_generated": true,
       "swift_dynamic": true,
-      "kotlin_generated": false,
+      "kotlin_generated": true,
       "kotlin_dynamic": true,
       "react": true
     },
@@ -724,11 +751,12 @@
   },
   "Input": {
     "description": "Generic input (React naming convention)",
+    "interactive": true,
     "aliases": [],
     "platforms": {
       "swift_generated": true,
       "swift_dynamic": true,
-      "kotlin_generated": false,
+      "kotlin_generated": true,
       "kotlin_dynamic": true,
       "react": true
     },
@@ -744,6 +772,7 @@
   },
   "Embed": {
     "description": "Embeds another screen as a region of this layout. The embedded screen owns its own ViewModel — independent from the parent VM.",
+    "interactive": true,
     "aliases": [],
     "platforms": {
       "swift_generated": true,

package/data/type_synonyms.json

@@ -0,0 +1,167 @@
+{
+  "_description": [
+    "Type-spelling synonyms: a node `type` that is not a section of attribute_definitions.json, mapped to the section that declares it (`canonical`).",
+    "The one table. Validation and the renderers are to read it, and hold no list of their own; which of them do is measured by their own tests (the type_synonyms_draw specs, SwiftJsonUI's TypeSynonymsDrawTests), not recorded here. It does not apply to sjui's UIKit mode, a separate renderer with its own set of UIKit components and its own spellings for them (Table is its SJUITableView); that mode draws what it has.",
+    "A renderer draws a synonym as its canonical type — except where the entry names `render_as`: the spelling draws differently from its canonical type (CircleImage clips to a circle), and the renderer draws `render_as` with the converter of that name, while validation still reads the canonical section. A type an app registers as its own component is the app's, whatever its spelling, and is never rewritten.",
+    "Any other key of an entry is an attribute the spelling itself means, of the canonical section: HStack and Row are a View with `orientation: horizontal`, VStack and Column one with `vertical`. A renderer adds it when the node does not set it. When the node sets it otherwise (an HStack with `orientation: vertical`), the node's value is drawn and the renderer warns, naming both. ZStack and Box add nothing: a View without orientation is already the stack they mean.",
+    "Not here: EditText / Input / Check / Toggle. They are sections of attribute_definitions.json that point at their canonical section with `_alias_of`; the exact-match lookup finds them first. Spacer / Divider / Triangle are neither declared nor synonyms, and draw as undeclared types."
+  ],
+  "synonyms": {
+    "Text": {
+      "canonical": "Label"
+    },
+    "MultiLineEditText": {
+      "canonical": "TextView"
+    },
+    "Textarea": {
+      "canonical": "TextView"
+    },
+    "ImageView": {
+      "canonical": "Image"
+    },
+    "Img": {
+      "canonical": "Image"
+    },
+    "NetworkImageView": {
+      "canonical": "NetworkImage"
+    },
+    "CircleImage": {
+      "canonical": "Image",
+      "render_as": "CircleImage"
+    },
+    "CircleImageView": {
+      "canonical": "Image",
+      "render_as": "CircleImage"
+    },
+    "AsyncImage": {
+      "canonical": "NetworkImage"
+    },
+    "Spinner": {
+      "canonical": "SelectBox"
+    },
+    "DatePicker": {
+      "canonical": "SelectBox"
+    },
+    "Select": {
+      "canonical": "SelectBox"
+    },
+    "Picker": {
+      "canonical": "SelectBox"
+    },
+    "Checkbox": {
+      "canonical": "CheckBox"
+    },
+    "RadioButton": {
+      "canonical": "Radio"
+    },
+    "RadioGroup": {
+      "canonical": "Radio"
+    },
+    "SegmentedControl": {
+      "canonical": "Segment"
+    },
+    "TabLayout": {
+      "canonical": "Segment"
+    },
+    "TabGroup": {
+      "canonical": "Segment"
+    },
+    "SeekBar": {
+      "canonical": "Slider"
+    },
+    "Range": {
+      "canonical": "Slider"
+    },
+    "ProgressBar": {
+      "canonical": "Progress"
+    },
+    "ActivityIndicator": {
+      "canonical": "Indicator"
+    },
+    "Loading": {
+      "canonical": "Indicator"
+    },
+    "LinearLayout": {
+      "canonical": "View"
+    },
+    "RelativeLayout": {
+      "canonical": "View"
+    },
+    "FrameLayout": {
+      "canonical": "View"
+    },
+    "HStack": {
+      "canonical": "View",
+      "orientation": "horizontal"
+    },
+    "VStack": {
+      "canonical": "View",
+      "orientation": "vertical"
+    },
+    "ZStack": {
+      "canonical": "View"
+    },
+    "Div": {
+      "canonical": "View"
+    },
+    "Box": {
+      "canonical": "View"
+    },
+    "Container": {
+      "canonical": "View"
+    },
+    "Column": {
+      "canonical": "View",
+      "orientation": "vertical"
+    },
+    "Row": {
+      "canonical": "View",
+      "orientation": "horizontal"
+    },
+    "ConstraintLayout": {
+      "canonical": "View"
+    },
+    "Scroll": {
+      "canonical": "ScrollView"
+    },
+    "CollectionView": {
+      "canonical": "Collection"
+    },
+    "RecyclerView": {
+      "canonical": "Collection"
+    },
+    "Table": {
+      "canonical": "Collection"
+    },
+    "TableView": {
+      "canonical": "Collection"
+    },
+    "List": {
+      "canonical": "Collection"
+    },
+    "Grid": {
+      "canonical": "Collection"
+    },
+    "LazyGrid": {
+      "canonical": "Collection"
+    },
+    "ListView": {
+      "canonical": "Collection"
+    },
+    "LazyColumn": {
+      "canonical": "Collection"
+    },
+    "Gradient": {
+      "canonical": "GradientView"
+    },
+    "BlurView": {
+      "canonical": "Blur"
+    },
+    "WebView": {
+      "canonical": "Web"
+    },
+    "Iframe": {
+      "canonical": "Web"
+    }
+  }
+}

package/dist/cli_runner.js

@@ -2,7 +2,7 @@ import { execFile } from "child_process";
 export async function runCli(command, args, options) {
     const timeout = options.timeout ?? 60_000;
     return new Promise((resolve) => {
-        execFile(command, args, {
+        const child = execFile(command, args, {
             cwd: options.cwd,
             timeout,
             maxBuffer: 10 * 1024 * 1024,
@@ -22,6 +22,12 @@ export async function runCli(command, args, options) {
                 stderr: stderr || "",
             });
         });
+        // Nothing is ever written to the child's stdin: end it now, so a CLI that
+        // reads stdin — an overwrite prompt — sees end-of-file instead of waiting
+        // for a line that never comes. Through 2.13.1 the pipe stayed open, and such
+        // a child waited until the timeout above killed it (`jui g converter` on
+        // an existing component, measured 2026-09-26).
+        child.stdin?.end();
     });
 }
 export function formatResult(result) {

package/dist/spec_loader.d.ts

@@ -58,6 +58,13 @@ export interface ReloadRecord {
     ok: boolean;
     error?: string;
 }
+export interface TypeSynonym {
+    spelling: string;
+    canonical: string;
+    renderAs?: string;
+    implies?: Record<string, unknown>;
+    source: string;
+}
 export interface DataSourceInfo {
     attributeDefinitions: FileInfo;
     componentMetadata: FileInfo;
@@ -66,6 +73,7 @@ export interface DataSourceInfo {
     attributeSemantics: FileInfo | null;
     platformSemantics: FileInfo | null;
     coverage: FileInfo | null;
+    typeSynonyms: FileInfo | null;
     componentCount: number;
     commonAttributeCount: number;
 }
@@ -92,6 +100,7 @@ export declare class SpecLoader {
     private screenIdentity;
     private commonAttributes;
     private aliasMap;
+    private typeSynonyms;
     private metadata;
     private dataSource;
     /** When this process read the files. Data is cached in memory from then
@@ -156,6 +165,22 @@ export declare class SpecLoader {
     listComponents(): string[];
     getDataSource(): DataSourceInfo;
     private load;
+    /**
+     * Type spellings the build accepts for a section they are not
+     * (shared/core/type_synonyms.json, jsonui-cli 1.9.0 — the one table the
+     * tools and the dynamic runtimes read). Until then lookup_component knew
+     * only `_alias_of` sections and metadata aliases, and answered "not found"
+     * for `ProgressBar`, which the build draws as a Progress.
+     *
+     * A section, an `_alias_of` section or a metadata alias of the same
+     * spelling wins: the exact match is found first, as in the tools. An entry
+     * whose canonical is not a section here is skipped.
+     *
+     * Absent (older jsonui-cli): no synonyms. Present but not JSON: the load
+     * throws, so an automatic reload keeps the last content that parsed rather
+     * than swapping in a loader that silently lost every synonym.
+     */
+    private loadTypeSynonyms;
     private normalizeMetadata;
     private getMetadata;
     private buildComponentSpec;

package/dist/spec_loader.js

@@ -59,6 +59,10 @@ export class SpecLoader {
     screenIdentity = null;
     commonAttributes = null;
     aliasMap = new Map();
+    /// Lower-cased spelling -> its entry in type_synonyms.json, for the
+    /// spellings that resolve through it (not a section, `_alias_of` or
+    /// metadata alias of their own).
+    typeSynonyms = new Map();
     metadata = {};
     dataSource;
     /** When this process read the files. Data is cached in memory from then
@@ -123,6 +127,13 @@ export class SpecLoader {
         const comp = this.getComponent(name);
         if (!comp)
             return null;
+        // Say which spelling was asked for and why it resolved: the build
+        // accepts `ProgressBar` as a Progress, and an HStack is a View that
+        // also means `orientation: horizontal`.
+        const synonym = this.typeSynonyms.get(name.toLowerCase());
+        if (synonym) {
+            return { ...comp, typeSynonym: synonym, commonAttributes: this.commonAttributes };
+        }
         return { ...comp, commonAttributes: this.commonAttributes };
     }
     getAttribute(name) {
@@ -202,6 +213,15 @@ export class SpecLoader {
                     matches.push(`rule: ${rule}`);
                 }
             }
+            // A spelling the build accepts for this type (type_synonyms.json).
+            for (const synonym of this.typeSynonyms.values()) {
+                if (this.getComponent(synonym.spelling) !== comp)
+                    continue;
+                if (synonym.spelling.toLowerCase().includes(q)) {
+                    score += 8;
+                    matches.push(`type synonym: ${synonym.spelling}`);
+                }
+            }
             if (score > 0)
                 results.push({ component: comp.name, score, matches });
         }
@@ -290,6 +310,7 @@ export class SpecLoader {
             this.dataSource.attributeSemantics,
             this.dataSource.platformSemantics,
             this.dataSource.coverage,
+            this.dataSource.typeSynonyms,
         ].filter((f) => f != null);
         const changed = [];
         for (const file of tracked) {
@@ -458,6 +479,7 @@ export class SpecLoader {
             }
             componentCount++;
         }
+        const typeSynonymsResolution = this.loadTypeSynonyms();
         this.dataSource = {
             attributeDefinitions: attrResolution,
             componentMetadata: metaResolution,
@@ -466,10 +488,59 @@ export class SpecLoader {
             attributeSemantics: attributeSemanticsResolution,
             platformSemantics: platformSemanticsResolution,
             coverage: coverageResolution,
+            typeSynonyms: typeSynonymsResolution,
             componentCount,
             commonAttributeCount: Object.keys(this.commonAttributesRaw).filter((k) => !k.startsWith("_")).length,
         };
     }
+    /**
+     * Type spellings the build accepts for a section they are not
+     * (shared/core/type_synonyms.json, jsonui-cli 1.9.0 — the one table the
+     * tools and the dynamic runtimes read). Until then lookup_component knew
+     * only `_alias_of` sections and metadata aliases, and answered "not found"
+     * for `ProgressBar`, which the build draws as a Progress.
+     *
+     * A section, an `_alias_of` section or a metadata alias of the same
+     * spelling wins: the exact match is found first, as in the tools. An entry
+     * whose canonical is not a section here is skipped.
+     *
+     * Absent (older jsonui-cli): no synonyms. Present but not JSON: the load
+     * throws, so an automatic reload keeps the last content that parsed rather
+     * than swapping in a loader that silently lost every synonym.
+     */
+    loadTypeSynonyms() {
+        this.typeSynonyms = new Map();
+        let resolution;
+        try {
+            resolution = this.resolveFile("shared/core/type_synonyms.json", "data/type_synonyms.json");
+        }
+        catch {
+            return null;
+        }
+        const doc = JSON.parse(readFileSync(resolution.path, "utf-8"));
+        for (const [spelling, entry] of Object.entries(doc.synonyms ?? {})) {
+            if (typeof entry !== "object" || entry === null)
+                continue;
+            const { canonical, render_as: renderAs, ...implies } = entry;
+            if (typeof canonical !== "string" || canonical.length === 0)
+                continue;
+            const key = spelling.toLowerCase();
+            if (this.components.has(key) || this.aliasMap.has(key))
+                continue;
+            const target = this.aliasMap.get(canonical.toLowerCase()) ?? canonical.toLowerCase();
+            if (!this.components.has(target))
+                continue;
+            this.aliasMap.set(key, target);
+            this.typeSynonyms.set(key, {
+                spelling,
+                canonical,
+                ...(typeof renderAs === "string" ? { renderAs } : {}),
+                ...(Object.keys(implies).length > 0 ? { implies } : {}),
+                source: "shared/core/type_synonyms.json",
+            });
+        }
+        return resolution;
+    }
     normalizeMetadata(raw) {
         return {
             description: raw.description ?? "",

package/dist/tools/jui/jui_generate_converter.js

@@ -6,7 +6,10 @@ export function register(server, config) {
         from_spec: z.string().optional().describe("Generate from component spec file path"),
         all: z.boolean().optional().describe("Generate from all component specs"),
         attributes: z.string().optional().describe("Attributes in key:type format (e.g., 'prop1:String,prop2:Int')"),
-        container: z.boolean().optional().describe("Mark as container component"),
+        container: z.boolean().optional().describe("true: a container (it draws its children). false: a leaf (it takes no " +
+            "children, and a layout that gives it some is refused by name) — needs " +
+            "jsonui-cli 1.9.0 or later (earlier `jui` rejects --no-container). " +
+            "Absent: the default form."),
         skip_existing: z.boolean().optional().describe("Leave existing converter and scaffold files untouched, without the " +
             "overwrite prompt — for idempotent scaffold runs. Wins over `force` " +
             "when both are set."),
@@ -31,9 +34,14 @@ export function register(server, config) {
             if (params.attributes) {
                 args.push("--attributes", params.attributes);
             }
-            if (params.container) {
+            // `false` asks for a leaf. It used to pass nothing, so the command ran
+            // in the default form and the request was dropped without a word.
+            if (params.container === true) {
                 args.push("--container");
             }
+            if (params.container === false) {
+                args.push("--no-container");
+            }
             if (params.skip_existing) {
                 args.push("--skip-existing");
             }

package/dist/tools/jui/jui_generate_project.js

@@ -1,9 +1,18 @@
 import { z } from "zod";
 import { runCli, formatResult } from "../../cli_runner.js";
 export function register(server, config) {
-    server.tool("jui_generate_project", "Generate Layout JSON and ViewModel files from screen specs (all or single spec)", {
+    server.tool("jui_generate_project", "Generate Layout JSON and ViewModel files from screen specs (all or single spec). " +
+        "A Layout JSON it generates — a screen's, or a Collection cell / header / footer's — is " +
+        "written when it is not there, left as it is when it already holds exactly what the spec " +
+        "generates, and otherwise KEPT (the Layout JSON is hand-edited after generation) and named " +
+        "in the output with \"Kept existing … layout: <file> … --force replaces it\". From " +
+        "jsonui-cli 1.9.0; an earlier jui rewrote an existing layout on every run.", {
         spec_file: z.string().optional().describe("Single spec file to process (e.g., 'login.spec.json')"),
-        force: z.boolean().optional().describe("Force overwrite declaration files"),
+        force: z.boolean().optional().describe("Replace the ViewModel declaration files, and each Layout JSON that already exists and " +
+            "differs from what the spec generates (kept and named without it). A layout whose data " +
+            "section holds entries the spec does not declare is not replaced even with force — the " +
+            "output names them. Called from here the command has no terminal, so it never asks: " +
+            "without force an existing layout is kept."),
         skip_layout: z.boolean().optional().describe("Skip Layout JSON generation"),
         dry_run: z.boolean().optional().describe("Show what would be generated without writing"),
         platform: z.enum(["ios", "android", "web"]).optional().describe("Generate for single platform only"),