jui-tools-mcp-server 2.14.1 → 2.15.3

package/README.md

@@ -70,7 +70,7 @@ bash ~/.jsonui-mcp-server/uninstall.sh
 | `list_screen_specs` | 画面 spec 一覧（メタデータ付き） |
 | `list_component_specs` | コンポーネント spec 一覧 |
 | `list_layouts` | Layout JSON ファイル一覧 |
-| `read_spec_file` | spec ファイルの内容を返す |
+| `read_spec_file` | spec ファイルの内容を返す。散文フィールド（description / notes / intent / purpose / processing / handling / rule / meaning / note / reason〔`harnessConditions`・`canonicalDivergence` の下を除く〕/ condition〔トップレベルの `transitions` の下のみ〕）の `{"md": "key"}`（`<name>.texts.yaml` への参照）は `{"md", "text"}` に展開して返す（編集は YAML 側）。参照の無い spec はファイルそのまま。`search_specs` は texts ファイルの本文を検索しない |
 | `read_layout_file` | Layout JSON の内容を返す |
 | `search_specs` | 全 spec（画面・サブディレクトリの sub-spec・コンポーネント）をキーワード検索し、ファイル・JSON path・抜粋を返す |
 

package/data/attribute_definitions.json

@@ -697,11 +697,17 @@
         "string",
         "array"
       ],
-      "description": "Click handler function name (selector-based, lowercase) - string only, no binding"
+      "description": "Click handler function name (selector-based, lowercase) - string only, no binding",
+      "notApplicableTo": {
+        "Web": "the embedded page takes the taps; a tap laid over it would break the page's own taps and scrolling (ruling 2026-10-03: not delivered, the build warns)"
+      }
     },
     "onClick": {
       "type": "binding",
-      "description": "Click handler (camelCase) - binding only (@{functionName}). On a type the SSoT does not declare (an app's own component) JsonUI gives the tap no screen-reader role; the component carries its own."
+      "description": "Click handler (camelCase) - binding only (@{functionName}). On a type the SSoT does not declare (an app's own component) JsonUI gives the tap no screen-reader role; the component carries its own.",
+      "notApplicableTo": {
+        "Web": "the embedded page takes the taps; a tap laid over it would break the page's own taps and scrolling (ruling 2026-10-03: not delivered, the build warns)"
+      }
     },
     "onLongPress": {
       "type": "binding",
@@ -714,7 +720,12 @@
     },
     "onPan": {
       "type": "binding",
-      "description": "Pan gesture handler (camelCase) - binding only (@{functionName}). Invoked repeatedly while the user drags. Payload: cumulative translation since the gesture began (iOS CGSize, Android Offset; web passes the PointerEvent). A handler declared () -> Void is called without the payload."
+      "description": "Pan gesture handler (camelCase) - binding only (@{functionName}). Invoked repeatedly while the user drags. Payload: cumulative translation since the gesture began (iOS CGSize, Android Offset; web passes the PointerEvent). A handler declared () -> Void is called without the payload.",
+      "notApplicableTo": {
+        "TextField": "the field's own drag (text selection, caret placement) takes the gesture; a pan laid over it would break editing (ruling 2026-10-03: not delivered, the build warns)",
+        "TextView": "the field's own drag (text selection, caret placement) takes the gesture; a pan laid over it would break editing (ruling 2026-10-03: not delivered, the build warns)",
+        "Slider": "the slider's own drag moves its value; a pan laid over it would break that (ruling 2026-10-03: not delivered, the build warns)"
+      }
     },
     "onPinch": {
       "type": "binding",
@@ -767,7 +778,7 @@
     },
     "include": {
       "type": "string",
-      "description": "Include another JSON layout (filename without extension)"
+      "description": "Include another JSON layout (its path from the layouts root, without extension). An include is an inline expansion: the included layout is drawn where this node is, and it reads the including layout's data — the parent owns the ViewModel. Under an `id`, the id prefixes the included layout's ids and data names, camelCase-joined (id `side` + `title` -> `sideTitle`), so the included layout's `@{title}` reads the including layout's `sideTitle`; without one it reads `title`. The include node's object maps, `shared_data` and then `data`, are laid over the including layout's data: a key is a name the included layout binds, a value is a literal or a binding read in the including layout's scope. The same on every platform and in Dynamic mode (ruling 2026-10-02). Until jsonui-cli 1.9.6 web handed an include without a map none of the including layout's data (the included layout drew its own defaults), and sjui / kjui codegen ignored an object map."
     },
     "variables": {
       "type": "object",
@@ -777,7 +788,7 @@
     },
     "shared_data": {
       "type": "object",
-      "description": "Data passed to included components"
+      "description": "On an include node: an object map laid over the including layout's data for the included layout, before `data` (`data` wins on a key both set). A key is a name the included layout binds; a value is a literal or a binding read in the including layout's scope (see `include`)."
     },
     "style": {
       "type": "string",
@@ -981,7 +992,7 @@
     },
     "data": {
       "type": "array",
-      "description": "Data model definitions for binding"
+      "description": "Data model definitions for binding: an array of declarations ({name, class, defaultValue}). On an include node an array is declarations merged into the included layout's, and an object is a map laid over the including layout's data for the included layout, after `shared_data` — `data` wins on a key both set (see `include`)."
     },
     "bindingScript": {
       "type": "string",
@@ -1233,7 +1244,7 @@
         "string",
         "binding"
       ],
-      "description": "Text content (can be data binding, supports interpolation). PLAIN TEXT: markdown is not interpreted, so \"[label](/path)\", \"**bold**\" and backticks render literally, brackets and all. To emphasise or link part of the string, use partialAttributes ('range' plus font/color/underline, and 'onClick' for a tappable span). Rendering real markdown is out of scope for Label — write a custom component."
+      "description": "Text content: a literal, or one data binding (`@{text}`). A value that mixes literal text with a binding (`Title: @{x}`) is a build warning, binding-mixed-text — compose the string in the ViewModel and bind it as one value (until jsonui-cli 1.9.6 this read \"supports interpolation\"). PLAIN TEXT: markdown is not interpreted, so \"[label](/path)\", \"**bold**\" and backticks render literally, brackets and all. To emphasise or link part of the string, use partialAttributes ('range' plus font/color/underline, and 'onClick' for a tappable span). Rendering real markdown is out of scope for Label — write a custom component."
     },
     "hint": {
       "type": "string",
@@ -2380,7 +2391,7 @@
         "string",
         "binding"
       ],
-      "description": "Button text (can be data binding, supports interpolation)"
+      "description": "Button text: a literal, or one data binding (`@{title}`). A value that mixes literal text with a binding is a build warning, binding-mixed-text — compose the string in the ViewModel and bind it as one value (until jsonui-cli 1.9.6 this read \"supports interpolation\")."
     },
     "font": {
       "type": "string",
@@ -2617,7 +2628,13 @@
       "valueAliases": {
         "ScaleToFill": "fill"
       },
-      "description": "Content mode (binding supported). ScaleToFill is a declared synonym of fill (the stretch — see attribute_semantics.json#semantics.image); the normalizer folds it, fixtures are generated for the canonical spelling only."
+      "description": "Content mode (binding supported). ScaleToFill is a declared synonym of fill (the stretch — see attribute_semantics.json#semantics.image); the normalizer folds it, fixtures are generated for the canonical spelling only.",
+      "bindingInfo": {
+        "platform": [
+          "swift"
+        ],
+        "note": "a contentMode bound to a value that is AspectFill at run time is cropped to its frame by the generated code only when width and height are numbers; on a frame that is not two numbers the image can be drawn past the frame (jsonui-cli ticket sjui-aspectfill-image-is-not-cropped-to-its-frame, known gap). A literal contentMode is cropped on every frame."
+      }
     },
     "renderingMode": {
       "type": "string",
@@ -2753,7 +2770,13 @@
         "AspectFit",
         "Center"
       ],
-      "description": "Content mode (binding supported)"
+      "description": "Content mode (binding supported)",
+      "bindingInfo": {
+        "platform": [
+          "swift"
+        ],
+        "note": "a contentMode bound to a value that is AspectFill at run time is cropped to its frame by the generated code only when width and height are numbers; on a frame that is not two numbers the image can be drawn past the frame (jsonui-cli ticket sjui-aspectfill-image-is-not-cropped-to-its-frame, known gap). A literal contentMode is cropped on every frame."
+      }
     },
     "cachePolicy": {
       "type": "string",
@@ -3094,11 +3117,10 @@
     },
     "onValueChange": {
       "type": "binding",
-      "description": "Value change handler - binding only (@{functionName}). The handler receives the new value of the selection binding, the same on every platform: with selectedIndex bound it is the Int index (declare ((Int) -> Void)?, or ((String, Int) -> Void)? for viewId + index); with selectedItem / selectedValue bound it is the String item (declare ((String, String) -> Void)? for viewId + item). A lone (String) parameter is the selected item as a String, with selectedIndex bound too; the viewId comes only as the first of two parameters. (() -> Void)? receives nothing and the ViewModel reads the bound value back."
-    },
-    "onValueChanged": {
-      "type": "binding",
-      "description": "Value change handler (alias for onValueChange) - binding only (@{functionName})"
+      "description": "Value change handler - binding only (@{functionName}). The handler receives the new value of the selection binding, the same on every platform: with selectedIndex bound it is the Int index (declare ((Int) -> Void)?, or ((String, Int) -> Void)? for viewId + index); with selectedItem / selectedValue bound it is the String item (declare ((String, String) -> Void)? for viewId + item). A lone (String) parameter is the selected item as a String, with selectedIndex bound too; the viewId comes only as the first of two parameters. (() -> Void)? receives nothing and the ViewModel reads the bound value back. `onValueChanged` folds here, as on Slider, Collection and CheckBox; it was declared as its own attribute, so the normalizer never folded it and sjui codegen called nothing for it (ticket sjui-selectbox-onvaluechanged-alias-is-never-called).",
+      "aliases": [
+        "onValueChanged"
+      ]
     },
     "colorScheme": {
       "type": "string",
@@ -4089,7 +4111,7 @@
         "binding"
       ],
       "binding_direction": "one-way",
-      "description": "Collection page/selection change handler. Canonical; prefer over onPageChanged.",
+      "description": "Collection page/selection change handler. Canonical; prefer over onPageChanged. Called when the page changes — by a swipe, a scrollTo or a currentPage write — with the new page; not called when the pager first appears (ruling 2026-10-02).",
       "platform": [
         "swift",
         "kotlin",
@@ -4836,7 +4858,7 @@
         "binding"
       ],
       "binding_direction": "one-way",
-      "description": "Tab/page selection change handler. Canonical; prefer over onTabChange/onPageChanged.",
+      "description": "Tab/page selection change handler. Canonical; prefer over onTabChange/onPageChanged. Called when the selected tab changes — by a tap on another tab or a selectedIndex write — with the new index; not called when the TabView first appears, nor when the selected tab is tapped again (ruling 2026-10-02).",
       "platform": [
         "swift",
         "kotlin",

package/data/binding_semantics.json

@@ -10,8 +10,8 @@
   },
   "contexts": {
     "text": {
-      "description": "Mixed-text interpolation. A string attribute may contain any number of '@{...}' occurrences with surrounding literal text; each occurrence is replaced by the stringified resolved value.",
-      "interpolation": true,
+      "description": "A text attribute's binding: the whole value is one '@{...}' expression, stringified. A value that mixes literal text with a binding ('Title: @{x}', '@{a} / @{b}') is a warning, binding-mixed-text (ruling 2026-10-02): compose the string in the ViewModel and bind it as one value — a layout holds no logic, and a composed string cannot be localized as one text. Until jsonui-cli 1.9.6 this context declared mixed-text interpolation (each occurrence replaced by its stringified value); sjui and rjui still interpolate such a value and kjui draws its first binding alone, outside any guarantee.",
+      "interpolation": false,
       "features": ["path", "default"],
       "unresolved": "emptyString"
     },
@@ -28,14 +28,14 @@
       "unresolved": "dropKey"
     },
     "nameRef": {
-      "readBy": "Hand-mirrored per face, measured 2026-09-10 and pinned per face: sjui_tools/lib/swiftui/views/base_view_converter.rb (onClick = binding, onclick = bare selector name) pinned by sjui_tools/spec/swiftui/views/handler_name_spelling_spec.rb; kjui_tools/lib/compose/helpers/modifier_builder.rb (camelCase events require the binding form) pinned by kjui_tools/spec/compose/components/handler_name_spelling_spec.rb; rjui_tools/lib/react/converters/base_converter.rb (onClick = binding only, onclick = bare only) pinned by rjui_tools/spec/react/converters/handler_name_spelling_spec.rb. 0 vectors: this context is code generation, not runtime resolution. Known gap, declared here and not a rule: a bare camelCase handler compiles to a no-op with no build-time report (an inline ERROR comment on kjui and rjui, nothing on sjui). A validator rule would need scoping to the declared event attributes first — consumer layouts also use camelCase keys as custom-component props (measured 2026-09-10).",
-      "description": "Event / handler NAME references. The camelCase event attributes (onClick, onAppear, onLongPress, …) take the binding form only: '@{name}' names the handler, and a bare string is NOT a handler on any face (measured 2026-09-10: kjui and rjui emit an inline ERROR comment and no call; sjui emits an empty action). The lowercase `onclick` is the UIKit selector legacy and takes the bare name only. Name extraction, not value resolution: path, default and negation are not applicable. Until 2026-09-10 this entry said the two spellings were equivalent; no generator ever implemented that, and the sentence was corrected to what they do.",
+      "readBy": "Hand-mirrored per face and pinned per face: sjui_tools/lib/swiftui/views/base_view_converter.rb (onClick = binding, onclick = bare selector name; handler_reference? = binding or bare name for the string-declared events) pinned by sjui_tools/spec/swiftui/views/handler_name_spelling_spec.rb and sjui_tools/spec/swiftui/bare_handler_on_string_events_spec.rb; kjui_tools/lib/compose/helpers/modifier_builder.rb pinned by kjui_tools/spec/compose/components/handler_name_spelling_spec.rb; rjui_tools/lib/react/converters/base_converter.rb (onClick = binding only, onclick = bare only) pinned by rjui_tools/spec/react/converters/handler_name_spelling_spec.rb. The binding-only rule is shared/core/binding_validator_core.rb check_bare_event, pinned by each face's spec/core/binding_bare_event_spec.rb, scoped to the types the SSoT declares (consumer layouts use camelCase keys as custom-component props). 0 vectors: this context is code generation, not runtime resolution. Measured 2026-10-02 over 48 event attributes: a bare name on a string-declared event was still dropped by kjui and rjui on a Collection's onValueChange / onItemAppear and TabView onValueChange (sjui calls it from jsonui-cli 1.9.6) — ticket bare-event-handler-is-dropped-without-a-warning.",
+      "description": "Event / handler NAME references. What a camelCase event attribute takes is its declared type (attribute_definitions): declared binding-only (type \"binding\" with no \"string\": onClick, onLongPress, Switch / Slider / Segment / CheckBox / Radio / SelectBox onValueChange, …) it takes '@{name}' only, and a bare string is not a handler — the binding validator reports one (binding-bare-event); declared with \"string\" (onAppear, TextField / TextView onTextChange, TextField onSubmit, a Collection's onValueChange / onItemAppear, TabView onValueChange, …) it takes '@{name}' or the bare name, both naming the data's closure. The lowercase `onclick` is the UIKit selector legacy and takes the bare name only. Name extraction, not value resolution: path, default and negation are not applicable. Until 2026-09-10 this entry said the two spellings were equivalent everywhere, and from then until 2026-10-02 that every camelCase event took the binding form only; neither matched the declarations (the conformance generator writes onAppear's bare name), and the sentence follows the declared types since.",
       "interpolation": false,
       "features": [],
       "unresolved": "platformEventContract"
     },
     "twoWay": {
-      "description": "Two-way bindings (TextField text, Switch isOn, ...). The expression must be a single flat identifier: no dots, no brackets, no '??', no '!'. This keeps write-back and change-handler wiring trivially derivable on every platform.",
+      "description": "Two-way bindings (TextField text, Switch isOn, ...). The whole value must be one binding of a single flat identifier: no literal text around it, no second binding, and no dots, no brackets, no '??', no '!' in the expression. This keeps write-back and change-handler wiring trivially derivable on every platform.",
       "interpolation": false,
       "features": [],
       "unresolved": "attributeDefault"
@@ -118,10 +118,12 @@
   },
   "validatorRules": [
     {"id": "binding-double-default", "severity": "error", "context": "any", "rule": "More than one '??' in a single binding expression."},
-    {"id": "binding-two-way-complex", "severity": "error", "context": "twoWay", "rule": "Two-way binding expression is not a single flat identifier (contains '.', '[', '??', or '!')."},
+    {"id": "binding-two-way-complex", "severity": "error", "context": "twoWay", "rule": "A two-way value is not one flat binding: the whole value must be a single flat identifier binding — no literal text mixed with it, no second binding, and no '.', '[', '??', or '!' in the expression."},
     {"id": "binding-negation-context", "severity": "error", "context": "text|embedParams|nameRef|twoWay", "rule": "'!' negation used outside a boolean value context."},
     {"id": "binding-default-in-params", "severity": "error", "context": "embedParams", "rule": "'??' default used in an embed params leaf (defaults belong to the embedded screen's data section)."},
     {"id": "binding-params-array", "severity": "error", "context": "embedParams", "rule": "Array anywhere inside params (pre-existing rule from the embed isolated+params track; restated here)."},
-    {"id": "binding-cell-parent-scope", "severity": "warning", "context": "collectionCell", "rule": "Cell layout binds a key that is only present in the parent screen's data."}
+    {"id": "binding-cell-parent-scope", "severity": "warning", "context": "collectionCell", "rule": "Cell layout binds a key that is only present in the parent screen's data."},
+    {"id": "binding-mixed-text", "severity": "warning", "context": "text|value", "rule": "A value of an attribute the component declares holds a binding and is not one binding (literal text around it, or two bindings). Compose the string in the ViewModel (it also keeps the text localizable) and bind it as one value; a layout holds no logic."},
+    {"id": "binding-bare-event", "severity": "warning", "context": "nameRef", "rule": "A bare name given to an event attribute of a declared type whose declared type is binding-only (\"binding\" with no \"string\")."}
   ]
 }

package/data/component_metadata.json

@@ -43,7 +43,7 @@
       }
     },
     "rules": [
-      "text attribute supports interpolation with @{binding} syntax",
+      "text is a literal or one binding (@{name}); a value that mixes literal text with a binding is the binding-mixed-text warning",
       "partialAttributes allows styling ranges within text",
       "linkable enables auto-detection of URLs",
       "Frame alignment must be .leading for textAlign to work correctly (Swift)"

package/dist/spec_texts.d.ts

@@ -0,0 +1,18 @@
+export declare const TEXT_KEYS: readonly string[];
+export declare const TEXT_KEY_SCOPE: Readonly<Record<string, ["not-under" | "only-under", readonly string[]]>>;
+/** Whether `key`, reached through `ancestors` (the dict keys above it, list
+ * indices left out), is a prose field a reference may stand in. */
+export declare function isTextField(ancestors: readonly string[], key: string): boolean;
+export interface TextsExpansion {
+    /** The spec with each reference expanded, or the input when it has none. */
+    data: unknown;
+    /** How many references were found / expanded. */
+    found: number;
+    expanded: number;
+    /** One line per reference that could not be expanded. */
+    problems: string[];
+    /** Texts files read (relative to the spec's directory). */
+    files: string[];
+}
+export declare function pairedTextsName(specFile: string): string;
+export declare function expandSpecTexts(data: unknown, specPath: string): TextsExpansion;

package/dist/spec_texts.js

@@ -0,0 +1,145 @@
+// Expands `{"md": ...}` prose references in a spec for a reader.
+//
+// A spec's prose fields (TEXT_KEYS below, scoped by TEXT_KEY_SCOPE) may
+// point into a YAML texts file instead of holding the text inline (jsonui-cli
+// shared/core/spec_texts.py is the definition, and `isTextField` mirrors its
+// `is_text_field`):
+//
+//   {"md": "a.b.c"}                   -> <spec name>.texts.yaml, key path a.b.c
+//   {"md": "shared/x.texts.yaml#a.b"} -> that file (relative to the spec)
+//
+// This is a READER, not the validator. It expands what it can and marks what
+// it cannot; the YAML rules (string keys, no '.', no duplicates, ...) are
+// enforced by `jsonui-doc validate spec`, and are deliberately not copied
+// here — a second copy of a rule is the drift this codebase keeps removing.
+//
+// Each reference becomes `{"md": <as written>, "text": <the text>}` rather
+// than the bare text: an agent reading the spec must see both what it says
+// and WHERE it lives, or it edits the JSON and the YAML stays stale. The
+// `text` key is not valid in a spec, so a copy pasted back is refused by the
+// validator instead of silently kept.
+import { existsSync, readFileSync } from "fs";
+import { basename, dirname, join } from "path";
+import { parse } from "yaml";
+// Mirrors TEXT_KEYS / TEXT_KEY_SCOPE / is_text_field in jsonui-cli
+// shared/core/spec_texts.py. Prose only: a key a tool parses, matches as a
+// name or emits as code is not here, and at the paths TEXT_KEY_SCOPE names
+// the same key is not prose either.
+export const TEXT_KEYS = [
+    "description", "notes", "intent", "purpose", "processing",
+    "handling", "rule", "meaning", "note", "reason", "condition",
+];
+// key -> [mode, ancestor keys]. "not-under": prose unless one of those keys
+// is an ancestor; "only-under": prose only when the first (top-level)
+// ancestor is one of them.
+export const TEXT_KEY_SCOPE = {
+    reason: ["not-under", ["harnessConditions", "canonicalDivergence"]],
+    condition: ["only-under", ["transitions"]],
+};
+/** Whether `key`, reached through `ancestors` (the dict keys above it, list
+ * indices left out), is a prose field a reference may stand in. */
+export function isTextField(ancestors, key) {
+    if (!TEXT_KEYS.includes(key))
+        return false;
+    const scope = Object.prototype.hasOwnProperty.call(TEXT_KEY_SCOPE, key)
+        ? TEXT_KEY_SCOPE[key]
+        : undefined;
+    if (scope === undefined)
+        return true;
+    const [mode, names] = scope;
+    if (mode === "not-under")
+        return !ancestors.some((a) => names.includes(a));
+    return ancestors.length > 0 && names.includes(ancestors[0]);
+}
+const REF_KEY = "md";
+export function pairedTextsName(specFile) {
+    let name = basename(specFile);
+    for (const suffix of [".spec.json", ".component.json", ".json"]) {
+        if (name.endsWith(suffix)) {
+            name = name.slice(0, -suffix.length);
+            break;
+        }
+    }
+    return `${name}.texts.yaml`;
+}
+function isReference(value) {
+    return (typeof value === "object" && value !== null && !Array.isArray(value) &&
+        REF_KEY in value);
+}
+export function expandSpecTexts(data, specPath) {
+    const baseDir = dirname(specPath);
+    const paired = pairedTextsName(specPath);
+    const cache = new Map();
+    const result = { data, found: 0, expanded: 0, problems: [], files: [] };
+    const load = (rel) => {
+        if (!cache.has(rel)) {
+            const abs = join(baseDir, rel);
+            if (!existsSync(abs)) {
+                cache.set(rel, new Error(`${rel} does not exist`));
+            }
+            else {
+                try {
+                    cache.set(rel, parse(readFileSync(abs, "utf-8")));
+                    result.files.push(rel);
+                }
+                catch (e) {
+                    cache.set(rel, new Error(`${rel} could not be parsed: ${e.message}`));
+                }
+            }
+        }
+        return cache.get(rel);
+    };
+    const expand = (ref, where) => {
+        result.found += 1;
+        const target = ref[REF_KEY];
+        if (typeof target !== "string" || !target.trim()) {
+            result.problems.push(`${where}: malformed reference`);
+            return ref;
+        }
+        const hash = target.indexOf("#");
+        const file = hash >= 0 ? target.slice(0, hash) : paired;
+        const key = hash >= 0 ? target.slice(hash + 1) : target;
+        const doc = load(file);
+        if (doc instanceof Error) {
+            result.problems.push(`${where}: ${doc.message}`);
+            return ref;
+        }
+        let node = doc;
+        for (const part of key.split(".")) {
+            node = typeof node === "object" && node !== null && !Array.isArray(node)
+                ? node[part]
+                : undefined;
+        }
+        if (typeof node !== "string") {
+            result.problems.push(`${where}: '${file}#${key}' is ${node === undefined ? "not defined" : "not a text"}`);
+            return ref;
+        }
+        result.expanded += 1;
+        return { ...ref, text: node };
+    };
+    const walk = (node, path, inText, ancestors) => {
+        if (Array.isArray(node)) {
+            // `notes: [...]` — each entry is prose too. Deeper lists under a text
+            // key are not prose, so the flag is not carried past one.
+            return node.map((v, i) => walk(v, `${path}[${i}]`, inText && !Array.isArray(v), ancestors));
+        }
+        if (typeof node === "object" && node !== null) {
+            if (isReference(node)) {
+                if (inText)
+                    return expand(node, path);
+                // Outside a prose field the validator refuses it; a reader leaves it.
+                return node;
+            }
+            const out = {};
+            for (const [k, v] of Object.entries(node)) {
+                out[k] = walk(v, path ? `${path}.${k}` : k, isTextField(ancestors, k), [...ancestors, k]);
+            }
+            return out;
+        }
+        return node;
+    };
+    const walked = walk(data, "", false, []);
+    if (result.found > 0)
+        result.data = walked;
+    return result;
+}

package/dist/tools/context/read_spec_file.js

@@ -1,8 +1,18 @@
 import { z } from "zod";
 import { readFileSync, existsSync } from "fs";
 import { join } from "path";
+import { expandSpecTexts } from "../../spec_texts.js";
 export function register(server, config) {
-    server.tool("read_spec_file", "Read the contents of a screen or component spec file", {
+    server.tool("read_spec_file", "Read the contents of a screen or component spec file. Prose fields " +
+        "(description / notes / intent / purpose / processing / handling / " +
+        "rule / meaning / note / reason — not under harnessConditions or " +
+        "canonicalDivergence — and condition under transitions only) written " +
+        "as {\"md\": \"key\"} live in a " +
+        "YAML texts file (<name>.texts.yaml beside the spec, or " +
+        "{\"md\": \"file.texts.yaml#key\"}); they are returned expanded as " +
+        "{\"md\": ..., \"text\": ...} — edit the text in the YAML file, not " +
+        "here. A spec without such references is returned byte-for-byte. " +
+        "search_specs does not search text held in a texts file.", {
         file: z.string().describe("Filename (e.g., 'login.spec.json' or 'my_card.component.json')"),
         project_dir: z.string().optional().describe("Project directory (overrides JUI_PROJECT_DIR env)"),
     }, async ({ file, project_dir }) => {
@@ -18,7 +28,29 @@ export function register(server, config) {
                 return { content: [{ type: "text", text: `File not found: ${filePath}` }] };
             }
             const content = readFileSync(filePath, "utf-8");
-            return { content: [{ type: "text", text: content }] };
+            // Only a spec that uses texts references is re-serialised; every
+            // other spec comes back exactly as it is on disk.
+            let parsed;
+            try {
+                parsed = JSON.parse(content);
+            }
+            catch {
+                return { content: [{ type: "text", text: content }] };
+            }
+            const texts = expandSpecTexts(parsed, filePath);
+            if (texts.found === 0) {
+                return { content: [{ type: "text", text: content }] };
+            }
+            const blocks = [{ type: "text", text: JSON.stringify(texts.data, null, 2) }];
+            const summary = `texts: ${texts.expanded}/${texts.found} reference(s) expanded as ` +
+                `{"md", "text"} from ${texts.files.join(", ") || "(no file read)"} — ` +
+                `the "text" key is for reading only; edit the YAML file.`;
+            const problems = texts.problems.length
+                ? "\nunresolved (run jsonui-doc validate spec for the full check):\n" +
+                    texts.problems.map((p) => `  - ${p}`).join("\n")
+                : "";
+            blocks.push({ type: "text", text: summary + problems });
+            return { content: blocks };
         }
         catch (e) {
             return { content: [{ type: "text", text: `Error: ${e.message}` }] };

package/docs/design.md

@@ -100,7 +100,7 @@ These are served directly by the `get_modifier_order`,
 | `list_screen_specs` | Screen-spec index with metadata. |
 | `list_component_specs` | Component-spec index with metadata. |
 | `list_layouts` | Layout JSON inventory. |
-| `read_spec_file` | One spec file (no parsing beyond `JSON.parse`). |
+| `read_spec_file` | One spec file. Byte-for-byte unless it carries `{"md": ...}` prose references (jsonui-cli `shared/core/spec_texts.py`); those are expanded to `{"md", "text"}` from the YAML texts file by `src/spec_texts.ts` — a reader only, the YAML rules stay in `jsonui-doc validate`. Which fields are prose is path-aware and mirrors `is_text_field` (description / notes / intent / purpose / processing / handling / rule / meaning / note / reason — not under `harnessConditions` / `canonicalDivergence` — and `condition` under top-level `transitions` only). `search_specs` does not search texts-file text. |
 | `read_layout_file` | One layout JSON file. |
 
 ### Group C — `jui` CLI wrappers (8)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jui-tools-mcp-server",
-  "version": "2.14.1",
+  "version": "2.15.3",
   "description": "MCP server for JsonUI project management - wraps jui and jsonui-doc CLIs plus component spec lookup",
   "main": "dist/index.js",
   "scripts": {
@@ -15,6 +15,7 @@
   "type": "module",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
+    "yaml": "^2.9.1",
     "zod": "^3.23.0"
   },
   "devDependencies": {

package/scripts/fetch-definitions.js

@@ -44,7 +44,7 @@ const DATA_DIR = join(PROJECT_ROOT, "data");
 //   3. `npm run fetch-definitions` and commit the data/ diff together with
 //      this pin in one commit
 // JSONUI_CLI_RAW_BASE still overrides the whole base URL for manual testing.
-const JSONUI_CLI_TAG = "v1.9.2";
+const JSONUI_CLI_TAG = "v1.9.8";
 const BASE_URL =
   process.env.JSONUI_CLI_RAW_BASE ||
   `https://raw.githubusercontent.com/Tai-Kimura/jsonui-cli/${JSONUI_CLI_TAG}`;

package/src/spec_texts.ts

@@ -0,0 +1,167 @@
+// Expands `{"md": ...}` prose references in a spec for a reader.
+//
+// A spec's prose fields (TEXT_KEYS below, scoped by TEXT_KEY_SCOPE) may
+// point into a YAML texts file instead of holding the text inline (jsonui-cli
+// shared/core/spec_texts.py is the definition, and `isTextField` mirrors its
+// `is_text_field`):
+//
+//   {"md": "a.b.c"}                   -> <spec name>.texts.yaml, key path a.b.c
+//   {"md": "shared/x.texts.yaml#a.b"} -> that file (relative to the spec)
+//
+// This is a READER, not the validator. It expands what it can and marks what
+// it cannot; the YAML rules (string keys, no '.', no duplicates, ...) are
+// enforced by `jsonui-doc validate spec`, and are deliberately not copied
+// here — a second copy of a rule is the drift this codebase keeps removing.
+//
+// Each reference becomes `{"md": <as written>, "text": <the text>}` rather
+// than the bare text: an agent reading the spec must see both what it says
+// and WHERE it lives, or it edits the JSON and the YAML stays stale. The
+// `text` key is not valid in a spec, so a copy pasted back is refused by the
+// validator instead of silently kept.
+
+import { existsSync, readFileSync } from "fs";
+import { basename, dirname, join } from "path";
+import { parse } from "yaml";
+
+// Mirrors TEXT_KEYS / TEXT_KEY_SCOPE / is_text_field in jsonui-cli
+// shared/core/spec_texts.py. Prose only: a key a tool parses, matches as a
+// name or emits as code is not here, and at the paths TEXT_KEY_SCOPE names
+// the same key is not prose either.
+export const TEXT_KEYS: readonly string[] = [
+  "description", "notes", "intent", "purpose", "processing",
+  "handling", "rule", "meaning", "note", "reason", "condition",
+];
+
+// key -> [mode, ancestor keys]. "not-under": prose unless one of those keys
+// is an ancestor; "only-under": prose only when the first (top-level)
+// ancestor is one of them.
+export const TEXT_KEY_SCOPE: Readonly<Record<string, ["not-under" | "only-under", readonly string[]]>> = {
+  reason: ["not-under", ["harnessConditions", "canonicalDivergence"]],
+  condition: ["only-under", ["transitions"]],
+};
+
+/** Whether `key`, reached through `ancestors` (the dict keys above it, list
+ * indices left out), is a prose field a reference may stand in. */
+export function isTextField(ancestors: readonly string[], key: string): boolean {
+  if (!TEXT_KEYS.includes(key)) return false;
+  const scope = Object.prototype.hasOwnProperty.call(TEXT_KEY_SCOPE, key)
+    ? TEXT_KEY_SCOPE[key]
+    : undefined;
+  if (scope === undefined) return true;
+  const [mode, names] = scope;
+  if (mode === "not-under") return !ancestors.some((a) => names.includes(a));
+  return ancestors.length > 0 && names.includes(ancestors[0]);
+}
+const REF_KEY = "md";
+
+export interface TextsExpansion {
+  /** The spec with each reference expanded, or the input when it has none. */
+  data: unknown;
+  /** How many references were found / expanded. */
+  found: number;
+  expanded: number;
+  /** One line per reference that could not be expanded. */
+  problems: string[];
+  /** Texts files read (relative to the spec's directory). */
+  files: string[];
+}
+
+export function pairedTextsName(specFile: string): string {
+  let name = basename(specFile);
+  for (const suffix of [".spec.json", ".component.json", ".json"]) {
+    if (name.endsWith(suffix)) {
+      name = name.slice(0, -suffix.length);
+      break;
+    }
+  }
+  return `${name}.texts.yaml`;
+}
+
+function isReference(value: unknown): value is Record<string, unknown> {
+  return (
+    typeof value === "object" && value !== null && !Array.isArray(value) &&
+    REF_KEY in (value as object)
+  );
+}
+
+export function expandSpecTexts(data: unknown, specPath: string): TextsExpansion {
+  const baseDir = dirname(specPath);
+  const paired = pairedTextsName(specPath);
+  const cache = new Map<string, unknown | Error>();
+  const result: TextsExpansion = { data, found: 0, expanded: 0, problems: [], files: [] };
+
+  const load = (rel: string): unknown | Error => {
+    if (!cache.has(rel)) {
+      const abs = join(baseDir, rel);
+      if (!existsSync(abs)) {
+        cache.set(rel, new Error(`${rel} does not exist`));
+      } else {
+        try {
+          cache.set(rel, parse(readFileSync(abs, "utf-8")));
+          result.files.push(rel);
+        } catch (e: any) {
+          cache.set(rel, new Error(`${rel} could not be parsed: ${e.message}`));
+        }
+      }
+    }
+    return cache.get(rel);
+  };
+
+  const expand = (ref: Record<string, unknown>, where: string): unknown => {
+    result.found += 1;
+    const target = ref[REF_KEY];
+    if (typeof target !== "string" || !target.trim()) {
+      result.problems.push(`${where}: malformed reference`);
+      return ref;
+    }
+    const hash = target.indexOf("#");
+    const file = hash >= 0 ? target.slice(0, hash) : paired;
+    const key = hash >= 0 ? target.slice(hash + 1) : target;
+    const doc = load(file);
+    if (doc instanceof Error) {
+      result.problems.push(`${where}: ${doc.message}`);
+      return ref;
+    }
+    let node: unknown = doc;
+    for (const part of key.split(".")) {
+      node = typeof node === "object" && node !== null && !Array.isArray(node)
+        ? (node as Record<string, unknown>)[part]
+        : undefined;
+    }
+    if (typeof node !== "string") {
+      result.problems.push(
+        `${where}: '${file}#${key}' is ${node === undefined ? "not defined" : "not a text"}`);
+      return ref;
+    }
+    result.expanded += 1;
+    return { ...ref, text: node };
+  };
+
+  const walk = (
+    node: unknown, path: string, inText: boolean, ancestors: readonly string[],
+  ): unknown => {
+    if (Array.isArray(node)) {
+      // `notes: [...]` — each entry is prose too. Deeper lists under a text
+      // key are not prose, so the flag is not carried past one.
+      return node.map((v, i) =>
+        walk(v, `${path}[${i}]`, inText && !Array.isArray(v), ancestors));
+    }
+    if (typeof node === "object" && node !== null) {
+      if (isReference(node)) {
+        if (inText) return expand(node, path);
+        // Outside a prose field the validator refuses it; a reader leaves it.
+        return node;
+      }
+      const out: Record<string, unknown> = {};
+      for (const [k, v] of Object.entries(node)) {
+        out[k] = walk(v, path ? `${path}.${k}` : k, isTextField(ancestors, k), [...ancestors, k]);
+      }
+      return out;
+    }
+    return node;
+  };
+
+  const walked = walk(data, "", false, []);
+  if (result.found > 0) result.data = walked;
+  return result;
+}

package/src/tools/context/read_spec_file.ts

@@ -3,11 +3,21 @@ import { z } from "zod";
 import { readFileSync, existsSync } from "fs";
 import { join } from "path";
 import { ServerConfig } from "../../config.js";
+import { expandSpecTexts } from "../../spec_texts.js";
 
 export function register(server: McpServer, config: ServerConfig) {
   server.tool(
     "read_spec_file",
-    "Read the contents of a screen or component spec file",
+    "Read the contents of a screen or component spec file. Prose fields " +
+      "(description / notes / intent / purpose / processing / handling / " +
+      "rule / meaning / note / reason — not under harnessConditions or " +
+      "canonicalDivergence — and condition under transitions only) written " +
+      "as {\"md\": \"key\"} live in a " +
+      "YAML texts file (<name>.texts.yaml beside the spec, or " +
+      "{\"md\": \"file.texts.yaml#key\"}); they are returned expanded as " +
+      "{\"md\": ..., \"text\": ...} — edit the text in the YAML file, not " +
+      "here. A spec without such references is returned byte-for-byte. " +
+      "search_specs does not search text held in a texts file.",
     {
       file: z.string().describe("Filename (e.g., 'login.spec.json' or 'my_card.component.json')"),
       project_dir: z.string().optional().describe("Project directory (overrides JUI_PROJECT_DIR env)"),
@@ -29,7 +39,29 @@ export function register(server: McpServer, config: ServerConfig) {
         }
 
         const content = readFileSync(filePath, "utf-8");
-        return { content: [{ type: "text", text: content }] };
+        // Only a spec that uses texts references is re-serialised; every
+        // other spec comes back exactly as it is on disk.
+        let parsed: unknown;
+        try {
+          parsed = JSON.parse(content);
+        } catch {
+          return { content: [{ type: "text", text: content }] };
+        }
+        const texts = expandSpecTexts(parsed, filePath);
+        if (texts.found === 0) {
+          return { content: [{ type: "text", text: content }] };
+        }
+        const blocks = [{ type: "text" as const, text: JSON.stringify(texts.data, null, 2) }];
+        const summary =
+          `texts: ${texts.expanded}/${texts.found} reference(s) expanded as ` +
+          `{"md", "text"} from ${texts.files.join(", ") || "(no file read)"} — ` +
+          `the "text" key is for reading only; edit the YAML file.`;
+        const problems = texts.problems.length
+          ? "\nunresolved (run jsonui-doc validate spec for the full check):\n" +
+            texts.problems.map((p) => `  - ${p}`).join("\n")
+          : "";
+        blocks.push({ type: "text" as const, text: summary + problems });
+        return { content: blocks };
       } catch (e: any) {
         return { content: [{ type: "text", text: `Error: ${e.message}` }] };
       }

package/tests/tools_context.test.ts

@@ -2,11 +2,12 @@
  * Group B tools (project context) — exercised against a tmp-dir fixture
  * project (jui.config.json + specs + layouts). No real project is touched.
  */
-import { symlinkSync, writeFileSync } from "fs";
+import { mkdirSync, symlinkSync, writeFileSync } from "fs";
 import { join } from "path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 
 import { ServerConfig } from "../src/config.js";
+import { isTextField } from "../src/spec_texts.js";
 import { register as registerGetProjectConfig } from "../src/tools/context/get_project_config.js";
 import { register as registerListScreenSpecs } from "../src/tools/context/list_screen_specs.js";
 import { register as registerListComponentSpecs } from "../src/tools/context/list_component_specs.js";
@@ -341,6 +342,115 @@ describe("read_spec_file", () => {
   });
 });
 
+describe("read_spec_file — texts-file prose", () => {
+  // `{"md": ...}` in a prose field (description / notes / intent / ...,
+  // path-scoped for reason and condition) points into a YAML file
+  // (jsonui-cli shared/core/spec_texts.py). The reader expands it next to the
+  // reference, so an agent sees the text AND where to edit it.
+  const specDir = () => join(projectDir, "docs/screens/json");
+  const spec = {
+    type: "app_contracts_spec",
+    version: "1.0",
+    metadata: { name: "app", description: { md: "overview" } },
+    unitContracts: [
+      {
+        target: "ApiClient",
+        cases: [
+          { name: "retries", intent: { md: "cases.api.retries" } },
+          { name: "shared", intent: { md: "shared/net.texts.yaml#timeout" } },
+          { name: "inline", intent: "plain" },
+        ],
+      },
+    ],
+  };
+
+  async function callFull(file: string) {
+    const tool = harness.tools.get("read_spec_file")!;
+    const result = await tool.handler({ file, project_dir: projectDir });
+    return result.content.map((c: { text: string }) => c.text);
+  }
+
+  beforeEach(() => {
+    writeJson(join(specDir(), "app.spec.json"), spec);
+    writeFileSync(
+      join(specDir(), "app.texts.yaml"),
+      "overview: |\n  # Title\n\n  - item\ncases:\n  api:\n    retries: \"**once**\"\n"
+    );
+  });
+
+  it("expands paired and named references as {md, text}", async () => {
+    const shared = join(specDir(), "shared");
+    mkdirSync(shared, { recursive: true });
+    writeFileSync(join(shared, "net.texts.yaml"), "timeout: ten seconds\n");
+    const [json, summary] = await callFull("app.spec.json");
+    const data = JSON.parse(json);
+    expect(data.metadata.description).toEqual({ md: "overview", text: "# Title\n\n- item\n" });
+    const cases = data.unitContracts[0].cases;
+    expect(cases[0].intent).toEqual({ md: "cases.api.retries", text: "**once**" });
+    expect(cases[1].intent.text).toBe("ten seconds");
+    expect(cases[2].intent).toBe("plain");
+    expect(summary).toContain("3/3 reference(s) expanded");
+    expect(summary).toContain("edit the YAML file");
+  });
+
+  it("names a reference it cannot expand and leaves it as written", async () => {
+    const [json, summary] = await callFull("app.spec.json");
+    const cases = JSON.parse(json).unitContracts[0].cases;
+    expect(cases[1].intent).toEqual({ md: "shared/net.texts.yaml#timeout" });
+    expect(summary).toContain("2/3 reference(s) expanded");
+    expect(summary).toContain("shared/net.texts.yaml does not exist");
+  });
+
+  it("expands purpose / reason / condition-under-transitions, and leaves reason and condition where they are not prose", async () => {
+    const scoped = {
+      type: "screen_spec",
+      metadata: { name: "Scoped" },
+      decorativeElements: [{ id: "bg", purpose: { md: "p" } }],
+      apiOutcomeRules: [{ op: "get", reason: { md: "r" } }],
+      transitions: [{ destination: "Next", condition: { md: "c" } }],
+      harnessConditions: [{ name: "h", reason: { md: "r" } }],
+      contracts: { canonicalDivergence: [{ reason: { md: "r" } }] },
+      displayLogic: [{ condition: { md: "c" } }],
+      navigation: { transitions: [{ condition: { md: "c" } }] },
+    };
+    writeJson(join(specDir(), "scoped.spec.json"), scoped);
+    writeFileSync(join(specDir(), "scoped.texts.yaml"), "p: the purpose\nr: the reason\nc: the condition\n");
+    const [json, summary] = await callFull("scoped.spec.json");
+    const data = JSON.parse(json);
+    expect(data.decorativeElements[0].purpose).toEqual({ md: "p", text: "the purpose" });
+    expect(data.apiOutcomeRules[0].reason).toEqual({ md: "r", text: "the reason" });
+    expect(data.transitions[0].condition).toEqual({ md: "c", text: "the condition" });
+    // Not prose at these paths: found, left exactly as written.
+    expect(data.harnessConditions[0].reason).toEqual({ md: "r" });
+    expect(data.contracts.canonicalDivergence[0].reason).toEqual({ md: "r" });
+    expect(data.displayLogic[0].condition).toEqual({ md: "c" });
+    // `transitions` must be the FIRST ancestor, not any ancestor.
+    expect(data.navigation.transitions[0].condition).toEqual({ md: "c" });
+    expect(summary).toContain("3/3 reference(s) expanded");
+  });
+
+  it("isTextField matches jsonui-cli is_text_field", () => {
+    expect(isTextField([], "description")).toBe(true);
+    expect(isTextField(["userActions"], "processing")).toBe(true);
+    expect(isTextField(["apiOutcomeRules"], "reason")).toBe(true);
+    expect(isTextField(["harnessConditions"], "reason")).toBe(false);
+    expect(isTextField(["x", "canonicalDivergence", "y"], "reason")).toBe(false);
+    expect(isTextField(["transitions"], "condition")).toBe(true);
+    expect(isTextField([], "condition")).toBe(false);
+    expect(isTextField(["validation", "serverSide"], "condition")).toBe(false);
+    expect(isTextField(["a", "transitions"], "condition")).toBe(false);
+    expect(isTextField([], "displayName")).toBe(false);
+    expect(isTextField([], "toString")).toBe(false);
+  });
+
+  it("returns a spec without references byte-for-byte", async () => {
+    const raw = '{"type":"screen_spec",  "metadata":{"name":"X","description":"a\\nb"}}';
+    writeFileSync(join(specDir(), "raw.spec.json"), raw);
+    const texts = await callFull("raw.spec.json");
+    expect(texts).toEqual([raw]);
+  });
+});
+
 describe("read_layout_file", () => {
   it("reads a top-level layout", async () => {
     const text = await harness.call("read_layout_file", {