jui-tools-mcp-server 2.6.0 → 2.8.0

package/data/attribute_definitions.json

@@ -1544,6 +1544,24 @@
     "hintAttributes": {
       "type": "object",
       "description": "Hint text attributes (font, fontSize, fontColor). The nested keys win over the flat spellings (hintColor / hintFont / hintFontSize): a bag scoped to the hint is the more specific statement. That is the ordinary cascade rule and what all four readers do (rjui label_converter, kjui text_component, sjui Label and SelectBox) - it was unwritten until 2026-08-05, when the one converter that had it backwards was found by contradicting its own comment.",
+      "properties": {
+        "font": {
+          "type": "string",
+          "description": "Font name"
+        },
+        "fontSize": {
+          "type": "number",
+          "description": "Font size"
+        },
+        "fontColor": {
+          "type": "string",
+          "description": "Font color - hex string or color name from colors.json"
+        },
+        "lineHeightMultiple": {
+          "type": "number",
+          "description": "Line height multiplier"
+        }
+      },
       "platform": "swift"
     },
     "font": {
@@ -1971,7 +1989,25 @@
     },
     "hintAttributes": {
       "type": "object",
-      "description": "Hint styling attributes. The nested keys win over the flat spellings (hintColor / hintFont / hintFontSize): a bag scoped to the hint is the more specific statement. That is the ordinary cascade rule and what all four readers do (rjui label_converter, kjui text_component, sjui Label and SelectBox) - it was unwritten until 2026-08-05, when the one converter that had it backwards was found by contradicting its own comment."
+      "description": "Hint styling attributes. The nested keys win over the flat spellings (hintColor / hintFont / hintFontSize): a bag scoped to the hint is the more specific statement. That is the ordinary cascade rule and what all four readers do (rjui label_converter, kjui text_component, sjui Label and SelectBox) - it was unwritten until 2026-08-05, when the one converter that had it backwards was found by contradicting its own comment.",
+      "properties": {
+        "font": {
+          "type": "string",
+          "description": "Font name"
+        },
+        "fontSize": {
+          "type": "number",
+          "description": "Font size"
+        },
+        "fontColor": {
+          "type": "string",
+          "description": "Font color - hex string or color name from colors.json"
+        },
+        "lineHeightMultiple": {
+          "type": "number",
+          "description": "Line height multiplier"
+        }
+      }
     },
     "hideOnFocused": {
       "type": "boolean",

package/data/attribute_semantics.json

@@ -8,28 +8,26 @@
       "styleAlone": "no-draw",
       "ruling": "A border is drawn only when BOTH borderWidth and borderColor are declared; borderWidth alone renders nothing on every platform — there is no default border color (2026-08-03 user ruling; supersedes the transient gray-default direction of d2c8628, unified across toolchains in 3e87b96). borderColor alone renders nothing for the same reason — the pair is what requests a border, and neither half requests one on its own (measured 2026-08-04, plan 34 re-measure: 0 px against the control on all three platforms; the android codegen does emit on the attribute's PRESENCE, which is a codegen-stage fact plan 41 tracks, not a rendered difference). borderStyle alone likewise renders nothing: it styles a border the width+color pair requests, it never summons one (2026-08-03 user ruling #2). NOTE: TextField.borderStyle is a DIFFERENT attribute (UIKit text-field chrome: roundedRect/line/bezel/none) and is outside this entry. The `__*_with_border` fixtures are the paired variants (borderStyle declared ALONGSIDE borderWidth + borderColor) that plan 49 added once three lanes had implemented the attribute with nothing measuring it — the lone-style fixtures above stay inert and keep testing the AND rule. `solid_with_border` is inert for a different reason from the lone ones: solid is the declared default of borderStyle, so stating it explicitly draws the same picture as omitting it (codegen_effect calls this class `value-is-default`). dashed/dotted are the two that must differ from the control. If the 3PF measurement comes back split rather than uniform, the honest record is a per-platform map like skinIdioms uses, not a forced uniform verdict: plan 34 caught ios emitting identical text for solid and dashed (C2/presence-only), and B/C/A implemented the three platforms separately in this wave. MEASURED 2026-08-05 (conformance-mobile run 30950551601 @ 5aada98), and the split the paragraph above anticipated is what happened: dashed and dotted are active on android and web and INERT on ios — the three borderStyle values render pixel-identical to each other and to the control on ios, which is the same symptom plan 34 recorded at the codegen stage (sjui emitting the same text for solid and dashed, C2/presence-only). They are therefore recorded as per-platform maps, not forced to a uniform verdict. This records today's reality; it does not bless it. If ios is supposed to draw a dashed border, the entry moves to uniformly-active once it does. solid_with_border stays uniformly-inert on all three because solid is borderStyle's declared default. RESOLVED 2026-08-05 on run 30990560599: ios draws both dashed and dotted, so the per-platform split is folded back to uniformly-active. The gap was never in sjui's codegen — that emitted StrokeStyle from dc35e82 — but in the SwiftUI dynamic renderer's applyBorder, which stroked with lineWidth only and so drew every style as solid. Recorded because the shape recurs: a codegen and a dynamic path disagreeing looks exactly like a platform not implementing an attribute.",
       "observable": {
-        "common/borderWidth__static": "uniformly-inert",
-        "common/borderColor__static": "uniformly-inert",
+        "common/borderWidth__static": "uniformly-active",
+        "common/borderColor__static": "uniformly-active",
         "common/borderStyle__solid": "uniformly-inert",
         "common/borderStyle__dashed": "uniformly-inert",
         "common/borderStyle__dotted": "uniformly-inert",
         "common/borderStyle__solid_with_border": "uniformly-inert",
         "common/borderStyle__dashed_with_border": "uniformly-active",
         "common/borderStyle__dotted_with_border": "uniformly-active"
-      }
+      },
+      "observableNote": "MEASURED 2026-08-08 (run 31243724782 + local-env): uniformly active — the divergence this entry recorded was fixed in-wave (ios Blur bridge / ios highlighted swap / ios distribution fill / ios loadingImage via pending.invalid / border emit on all faces)."
     },
     "highlight": {
       "highlightedAlone": "no-draw",
       "highlightBackgroundAlone": "no-draw",
       "ruling": "The highlighted appearance is drawn only when BOTH `highlighted` and a highlight colour are declared — the same pair-required shape as `border`, and ruled the same way. `highlighted: true` alone swaps the background to a colour that was never given, so nothing changes; `highlightBackground` alone names a colour for a state the view is never in. Every codegen already treats them as a pair (kjui modifier_builder.rb:490 combines highlight_cond with highlight_bg; sjui apply_highlighted_to_bag does the same), so a single-attribute fixture measures the absence of the companion rather than the converter. Established by measurement, not assumption: plan 41's paired probe carried View.highlighted as its one PROVISIONAL entry, and giving it `highlightBackground` made the ios/C0 and android/C0 findings disappear — the converters were correct and the fixture was missing the other half. This entry retires that PROVISIONAL: the pairing is now derived from the ledger like every other family (2026-08-05, plan 49-E, on plan 41's evidence). MEASURED 2026-08-05 (same run): web is active — A routed the highlight background through an inline style instead of a losing Tailwind class — while ios and android are still inert, so the verdict is recorded per platform. NOTE for anyone tidying this block: `common/highlightBackground__static` carries no control in the generated fixture set, so it is never compared and its verdict here is not checked against anything. It must NOT be deleted regardless — companions.py derives the pairing from this topic's `observable` KEYS, and a topic with fewer than two members stops producing companions at all. Same permanent-unverifiable note as networkImage's loadingImage applies to `common/highlightBackground__static`: rules.py scopes it to the paired form, so the bare fixture has no control and the entry can never be checked at the render stage. It stays because companions.py derives the View.highlighted pairing from these keys — deleting it would stop the pairing, not just the check. MEASURED 2026-08-06 on run 31068716186: android is now active (152,960 px) — the highlighted+highlightBackground pair landed on android; ios remains inert.",
       "observable": {
-        "View/highlighted__true": {
-          "ios": "inert",
-          "android": "active",
-          "web": "active"
-        },
+        "View/highlighted__true": "uniformly-active",
         "common/highlightBackground__static": "uniformly-inert"
-      }
+      },
+      "observableNote": "MEASURED 2026-08-08 (run 31243724782 + local-env): uniformly active — the divergence this entry recorded was fixed in-wave (ios Blur bridge / ios highlighted swap / ios distribution fill / ios loadingImage via pending.invalid / border emit on all faces)."
     },
     "image": {
       "defaultContentMode": "fit",
@@ -70,11 +68,9 @@
         },
         "NetworkImage/hint__static": "uniformly-inert",
         "NetworkImage/errorImage__static": "uniformly-active",
-        "NetworkImage/loadingImage__static": {
-          "ios": "inert",
-          "android": "active"
-        }
-      }
+        "NetworkImage/loadingImage__static": "uniformly-active"
+      },
+      "observableNote": "MEASURED 2026-08-08 (run 31243724782 + local-env): uniformly active — the divergence this entry recorded was fixed in-wave (ios Blur bridge / ios highlighted swap / ios distribution fill / ios loadingImage via pending.invalid / border emit on all faces)."
     },
     "margins": {
       "offsetModel": "ZStack/overlay child margins are full-margin offsets; an explicit center declaration disables that axis margin; margins arrays and start/endMargin apply as padding",
@@ -86,7 +82,11 @@
       "ruling": "2026-08-03 campaign adjudication: the default content gravity is top|start on every container (CollectionStack pins Top; SafeAreaView spacer layouts anchor start). A platform centering by default is the deviant. No activeness observable — default-vs-default renders identically; the geometry probe closes it mechanically. 2026-08-07 (plan 51-E), Wave 2 carry-over: what happens to the axis a single-value gravity does NOT name. Ruled from the declaration alone, as the semantics rule requires, not from any platform's behaviour. common.gravity declares an enum of SINGLE-AXIS values (top, bottom, left, right, centerVertical, centerHorizontal) alongside an array type whose whole purpose is naming both axes at once. If a single-axis value left the other axis undefined, then `gravity: \"left\"` would have no defined rendering at all, and a declaration cannot leave its own enum values meaningless — so each axis resolves independently, and the axis that is not named takes the default already ruled above (top | start). It does NOT inherit the parent's gravity and it is not \"unset\". CONSEQUENCE, stated because it looks like a bug when measured: in LTR, `gravity: \"left\"` and `gravity: \"top\"` both resolve to (start, top) and are therefore observationally IDENTICAL. The Wave 2 note that ios draws `left` and `top` the same picture is the contract being honoured, not a defect; a fixture that expects those two to differ is testing something the SSoT never promised. Whether a given fixture can see the horizontal axis at all is a separate, real question — a child that fills the container's width makes it unobservable (D's lane). 2026-08-07 (plan 51-E), B's follow-up measurement: sjui emits `alignment: .topLeading` for every NAMED form (`left|top`, `left`, `top`) but drops the `alignment:` argument entirely when gravity is omitted, so SwiftUI falls to `.center` (51-B-progress). That is the deviation this ruling already named — \"a platform centering by default is the deviant\" — and the argument is the same one that settled the unspecified axis: if a partially specified gravity fills the unnamed axis with the default, then an omitted gravity fills BOTH axes with it. Any other reading makes omitting gravity mean something different from naming the default explicitly, which no declaration says. So the omitted form must also emit topLeading. NOTE FOR ROLLOUT, not for the canon: every View in every project that does not declare gravity goes through this line, so the fix wants a 3PF measurement and a fixture that can actually see it (a fixed-size container whose child does not stretch — with a stretching child the Spacer construction is identical in all four forms and the difference is unobservable). Sequencing is the orchestrator's; the canon is not in doubt.",
       "observable": {},
       "unspecifiedAxis": "falls to the container default for that axis (top vertically, start horizontally) — never \"unset\", never inherited from the parent",
-      "omittedEntirely": "same as the default: top | start. Omitting gravity must render identically to naming the default explicitly"
+      "omittedEntirely": "same as the default: top | start. Omitting gravity must render identically to naming the default explicitly",
+      "leafOwnFrameChannel": {
+        "default": "center",
+        "ruling": "2026-08-08 adjudication (gravity leaf-scope hotfix, v1.5.2/10.15.1): the container default above scopes to CONTAINERS — nodes whose content the framework itself lays out. A childless node's own-frame content (a fit image's bitmap inside its declared box, a custom component's internals, a text block smaller than its fixed box) is a SEPARATE channel whose default is Center: Compose's Image/extension alignment default, which kjui never overrides, and the position the android face measurably draws a shrunken autoShrink line in its fixed box. ios converged in SwiftJsonUI 245d059+4d41bf9 (codegen gravity_to_frame_alignment leaf scope; dynamic fixed-frame text drop). A DECLARED gravity or textAlign still applies to any node — this entry names only the omitted-spelling default. Implementations were aligned BEFORE this text landed; the entry records the ruling the code already obeys."
+      }
     },
     "shadow": {
       "stringPipe": "five-field strict",
@@ -104,16 +104,8 @@
       "demarcation": "control chrome may differ per platform; the DIFFERENCE ITSELF is contract-pinned",
       "ruling": "2026-08-03 campaign adjudication: platform-owned control chrome is a legitimate difference, but only in its adjudicated SHAPE — the observable pins each accepted divergence as an expected-difference pattern, so both disappearing and mutating fail the gate. Members: Blur effectStyle (android material variants differ visibly, ios materials render alike on flat surfaces per the 31 saturation analysis, web CSS blur is single-variant), TextField.borderStyle (UIKit field chrome — each platform draws its own; web renders none for the UIKit-only bezel variants), TabView.showLabels WAS a member on the strength of a `__true` measurement — the DEFAULT value — and left the topic on 2026-08-05 when run 30990560599 measured both values on all three: `true` is inert everywhere (it is the default, so declaring it draws what omitting it draws) and `false` is active everywhere (ios 1491 px, android 8427, web 3019), with the two values distinguishable on every platform. There is no ios-only divergence to pin, so the entry moves to `__false` as a plain uniformly-active fact and the attribute is no longer a skin idiom. The original reading came from comparing the default value against its control, which cannot show what a non-default value does. The tabview glyph-source family is the codegen-side counterpart, pinned permanently in codegen_parity.json (2026-08-03 user ruling).",
       "observable": {
-        "Blur/effectStyle__extralight": {
-          "ios": "inert",
-          "android": "active",
-          "web": "inert"
-        },
-        "Blur/effectStyle__light": {
-          "ios": "inert",
-          "android": "active",
-          "web": "inert"
-        },
+        "Blur/effectStyle__extralight": "uniformly-active",
+        "Blur/effectStyle__light": "uniformly-active",
         "TextField/borderStyle__bezel": {
           "ios": "inert",
           "android": "active",
@@ -145,7 +137,8 @@
           "web": "inert"
         },
         "TabView/showLabels__false": "uniformly-active"
-      }
+      },
+      "observableNote": "MEASURED 2026-08-08 (run 31243724782 + local-env): uniformly active — the divergence this entry recorded was fixed in-wave (ios Blur bridge / ios highlighted swap / ios distribution fill / ios loadingImage via pending.invalid / border emit on all faces)."
     },
     "progressValue": {
       "canonical": "progress",
@@ -179,11 +172,7 @@
       "spacingWins": "an explicit spacing pins the gap; distribution still governs size",
       "ruling": "2026-08-05 (plan 49-E), raised by F/G and measured across all three toolchains. The vocabulary is UIStackView's, and its four values split into TWO KINDS that the current implementations conflate: `fill` and `fillEqually` distribute SIZE among the children, while `equalSpacing` and `equalCentering` distribute the FREE SPACE between them. fill = children grow to consume the axis, leaving no free space (proportional to their content size); fillEqually = every child gets the SAME size regardless of content; equalSpacing = equal gaps between adjacent children, with no leading or trailing gap; equalCentering = equal centre-to-centre distances. CONSEQUENCE, and this is the part every platform gets wrong today: the two size values are NOT an arrangement. They are `Modifier.weight(1f)` on each child in Compose, `.frame(maxWidth: .infinity)` (or equal weights) in SwiftUI, and `flex-1` in CSS — not Arrangement.* and not justify-content. Mapping `fill` to SpaceBetween/justify-between is precisely backwards: fill means there is no free space left to distribute. MEASURED STATE 2026-08-05 — all three disagree with the canon AND with each other, and each collapses a DIFFERENT pair of values into one output, so no fixture comparing two declared values can tell them apart: android (kjui container_component.rb:129-140) sends fillEqually and equalCentering both to Arrangement.SpaceEvenly; web (rjui view_converter.rb:184-195) sends the same pair both to justify-evenly; ios (sjui view_converter.rb:217,367,383) synthesises identical Spacer sets for equalSpacing and equalCentering, and gives fillEqually between-only spacers, which is space-between rather than equal sizes. `fill` emits nothing on ios (correct by accident) and a space-between arrangement on the other two (wrong). WHY NO GATE CAUGHT IT: --inert-complete asks whether a fixture differs from its CONTROL. Two declared values that both differ from the control but are identical to EACH OTHER pass that check, and android parity passes too because codegen and dynamic collapse them the same way. A value-vs-value comparison is the missing instrument — this is the 'both wrong in the same direction reads as green' shape. SPACING PRECEDENCE: `spacing` and `distribution` are not mutually exclusive and the current Compose behaviour (spacing != null wins outright, distribution never read) is wrong for the size values. An explicit `spacing` pins the GAP, so it overrides the gap that equalSpacing/equalCentering would compute; it says nothing about size, so fill/fillEqually still apply underneath it. Same shape as the size topic's explicit > bounds > fill ordering: the more specific declaration wins the axis it speaks about, and only that axis. No observable entries yet: the fixtures that would prove this need to compare two declared VALUES against each other rather than each against the control, which the current generator does not emit. That instrument is the follow-up this ruling asks for. PER-VALUE MAPPING added 2026-08-05 after A implemented the ruling on web (jsonui-cli 651403e) — recorded so B and C match that choice instead of re-deriving it, which is how the three drifted apart in the first place. The `perValueMapping` block above is the table; the two decisions worth calling out are that the SIZE values are carried to the CHILDREN (a per-child flex/weight instruction, not a container arrangement) and that equalCentering maps to SpaceAround / justify-around rather than SpaceEvenly — SpaceEvenly equalises the GAPS, which is equalSpacing's job, and collapsing the two is precisely the conflation this ruling exists to undo. web landed first and is the reference implementation; ios (sjui view_converter.rb, still synthesising Spacers for both gap values) and android (kjui container_component.rb:129, still mapping four values onto two Arrangements) are outstanding. CHILD SIZE PRECEDENCE, ruled 2026-08-05 after G measured android and found `fill` leaving 60dp unconsumed: an EXPLICIT width/height on the child wins over the size half of distribution, so `fill` and `fillEqually` do not override a declared child size. This is not a new principle — the `size` topic's 2026-08-03 campaign adjudication already ordered explicit > bounds > fill, and distribution's size half IS a fill instruction on the child's axis, so it sits at the bottom of that order like any other. It is also what `spacingWins` says one line up: the more specific declaration wins the axis it speaks about. CONSEQUENCE for the measurement, and the reason this had to be ruled rather than implemented: a fixture whose children declare `width: 40` cannot demonstrate `fill` at all — the 60dp G measured is the correct outcome, not a defect. The fixture has to omit the child dimension on the distribution axis for the attribute to have anything to do. That makes it the fourth case of a fixture shape hiding the attribute it is supposed to measure (after SafeAreaView's matchParent, alignTop/LeftOfView off-screen, and SelectBox with nothing to decorate). android's current implementation is correct as it stands; no three-platform change follows from this. FIRST VALUE-VS-VALUE MEASUREMENT 2026-08-05, on run 30972192150's artifacts once D's fixtures (0035321) and H's --value-discrimination gate (f54d3d5) existed, with control_diff.ignore_bands applied. It confirms the collapse this ruling was written from, platform by platform and by measurement rather than by reading converters: ios draws equalSpacing and equalCentering pixel-identically, android and web draw fillEqually and equalCentering pixel-identically. Three platforms, two different collapsed pairs, nobody agreeing — recorded in `collapsedPairs` so the fix can be checked off per platform. `fill` is ALSO inert against its control on ios while active on android and web, which is not a contradiction of explicitChildSizeWins: the fixture's children carry an explicit width, so no platform should be moving them, and the two that do are moving the TRACK rather than the child. The entry is per-platform for that reason and must not be flattened to uniformly-inert until the fixture drops the child width — at which point fill becomes measurable and this entry gets re-measured, not edited. RE-MEASURED on run 30990560599 after D removed the child width from the size-half fixtures (661bfba). web now distinguishes all four values — A's implementation is the first to satisfy the ruling end to end, and `collapsedPairs` loses its web row. ios still collapses equalSpacing with equalCentering and android now collapses fill with fillEqually (it had been fillEqually with equalCentering): the pair moved because the fixture changed, so android's remaining defect is in the SIZE half, where fill and fillEqually must differ — fill grows children from their content, fillEqually makes them equal regardless of it. `fill` stays inert on ios: with the child width gone the fixture can finally demonstrate it, and ios does not. Run 31068716186 (2026-08-06) measured android fill != fillEqually with both active against the control — C's 27b9b13 (codegen) and G's c7d2dfb (DistributionFillRow) closed the SIZE-half collapse, so the android collapsedPairs row is deleted BY MEASUREMENT, not by edit. The ios pair (equalSpacing == equalCentering) persists: run-5 geometry shows identical child positions and a 32 px gap for both values. Run 31080217407 (2026-08-06) measured ios distinguishing equalSpacing from equalCentering — B (b57e327/3dc3795) and F (e8f99c7) implemented the pinned iosGapConstruction, and the geometry is exactly the canon's: equalCentering shifts the first child right by the half-gap edge spacer (box_a 154 -> 168 px) while every child keeps its declared size (118 px). collapsedPairs is now EMPTY — all three platforms distinguish all four values, which is the state this ruling was written to reach. The empty map stays as the healthy-state marker, same convention as companions.py's emptied PROVISIONAL.",
       "observable": {
-        "View/distribution__fill": {
-          "ios": "inert",
-          "android": "active",
-          "web": "active"
-        },
+        "View/distribution__fill": "uniformly-active",
         "View/distribution__fillequally": "uniformly-active",
         "View/distribution__equalspacing": "uniformly-active",
         "View/distribution__equalcentering": "uniformly-active"
@@ -220,7 +209,8 @@
         "note": "Pinned 2026-08-06 (E's proposal, orchestrator-approved: implement this release, B codegen + F dynamic) so the two ios paths emit ONE counting instead of deriving Spacer arithmetic twice — two paths growing children separately is exactly what collapsed distribution's SIZE half before c7d2dfb. Spacer counting suffices because HStack/VStack split free space equally among unconstrained Spacers: the 1:2 end:between count ratio IS space-around's half-gap. No custom Layout, no measurement pass. Acceptance is already wired: when this lands, run 6 must delete collapsedPairs' ios row and turn the two value_discrimination receiving rows stale. Regression-test discipline from F's landing: a partial reversion (between 2->1 only) builds an equal-three-spacer structure the first sample points slipped past — pin BOTH sides of the computed boundary (55 in the 300pt fixture) so partial and full reversion both fail."
       },
       "explicitChildSizeWins": "an explicit child width/height beats distribution's size half — size topic's explicit > bounds > fill",
-      "collapsedPairs": {}
+      "collapsedPairs": {},
+      "observableNote": "MEASURED 2026-08-08 (run 31243724782 + local-env): uniformly active — the divergence this entry recorded was fixed in-wave (ios Blur bridge / ios highlighted swap / ios distribution fill / ios loadingImage via pending.invalid / border emit on all faces)."
     },
     "trackColors": {
       "sliderTrack": "trackTintColor is the UNFILLED track; progressTintColor is the filled one",

package/data/coverage.json

@@ -2,52 +2,6 @@
   "schemaVersion": 1,
   "_comment": "Declared attributes no platform converter reads. Hand-maintained: close a gap by implementing it (then delete the entry) or by narrowing platform/mode in attribute_definitions.json. reason is one of: dynamic-key, legacy, platform-na, runtime-only, unimplemented.",
   "entries": [
-    {
-      "component": "Collection",
-      "attribute": "cellHeight",
-      "platforms": [
-        "web"
-      ],
-      "reason": "unimplemented"
-    },
-    {
-      "component": "Collection",
-      "attribute": "cellWidth",
-      "platforms": [
-        "android",
-        "web"
-      ],
-      "reason": "unimplemented"
-    },
-    {
-      "component": "Collection",
-      "attribute": "hideSeparator",
-      "platforms": [
-        "ios",
-        "android",
-        "web"
-      ],
-      "reason": "runtime-only",
-      "note": "ios dynamic implements it (SwiftJsonUI CollectionConverter.swift:662 / TableConverter.swift:46,49); no codegen face reads it. Not \"unimplemented\" — this scan only walks the Ruby codegen. attribute_semantics.json -> collectionSeparators (plan 51-E)."
-    },
-    {
-      "component": "Collection",
-      "attribute": "listStyle",
-      "platforms": [
-        "android",
-        "web"
-      ],
-      "reason": "unimplemented",
-      "note": "Was runtime-only while no codegen face read it; B implemented the ios codegen face against the enum (collection_converter.rb LIST_STYLES), so android and web are now a genuine implementation gap. attribute_semantics.json -> collectionSeparators (plan 51-E)."
-    },
-    {
-      "component": "ScrollView",
-      "attribute": "defaultScrollAnchor",
-      "platforms": [
-        "android"
-      ],
-      "reason": "unimplemented"
-    },
     {
       "component": "ScrollView",
       "attribute": "minZoom",
@@ -65,14 +19,6 @@
       ],
       "reason": "unimplemented"
     },
-    {
-      "component": "TextField",
-      "attribute": "hintLineHeightMultiple",
-      "platforms": [
-        "android"
-      ],
-      "reason": "unimplemented"
-    },
     {
       "component": "common",
       "attribute": "binding",

package/data/platform_semantics.json

@@ -0,0 +1,70 @@
+{
+  "version": 1,
+  "title": "Platform-scoped layout semantics",
+  "purpose": "How to make a node render differently (or not at all) on one platform: the node-level 'platform' directive, the layout-root 'platforms' whitelist, and how they differ from 'responsive'. Canonical implementation: jui_tools/jui_cli/core/platform_resolver.py — this file restates it for lookup and must follow it, never lead it.",
+  "keywords": [
+    "platform", "platforms", "ios only", "android only", "web only",
+    "per-platform", "override", "platform-specific", "platform limited",
+    "プラットフォーム", "限定", "出し分け", "iosだけ", "androidだけ", "webだけ",
+    "プラットフォーム別", "機種別"
+  ],
+  "nodeDirective": {
+    "attribute": "platform",
+    "consumedAt": "distribution (jui build). The key never appears in distributed per-platform output; platform-specific emit is produced from it.",
+    "objectForm": {
+      "summary": "Per-platform attribute overrides, merged into the node for the matching platform only. Override wins over the base value; merge is per top-level key (the override value replaces the base value for that key wholesale — it is not deep-merged into it).",
+      "example": {
+        "prompt": "Change fontColor only on iOS",
+        "layout": {
+          "type": "Label",
+          "text": "@{title}",
+          "fontColor": "#333333",
+          "platform": { "ios": { "fontColor": "#FFD700" } }
+        },
+        "resolved": {
+          "ios": { "type": "Label", "text": "@{title}", "fontColor": "#FFD700" },
+          "android": { "type": "Label", "text": "@{title}", "fontColor": "#333333" },
+          "web": { "type": "Label", "text": "@{title}", "fontColor": "#333333" }
+        }
+      },
+      "multiPlatformExample": {
+        "prompt": "Different heights everywhere, plus a web-only extra attribute",
+        "layout": {
+          "type": "View",
+          "height": 200,
+          "platform": {
+            "ios": { "height": 220 },
+            "android": { "height": 180 },
+            "web": { "height": "100vh", "maxWidth": 1200 }
+          }
+        }
+      },
+      "detection": "A dict counts as an override map ONLY when every key is one of 'ios' / 'android' / 'web'. Any other key (e.g. a stray 'class') makes the whole value a non-override, so nothing merges — keep override maps pure.",
+      "nesting": "Override values are themselves resolved recursively, so an override may contain child nodes with their own 'platform' directives."
+    },
+    "stringForm": {
+      "summary": "Node filter: the node (and its whole subtree) is DROPPED on platforms that do not match. Comma-separated tokens allowed.",
+      "example": {
+        "prompt": "Render this node on Android only",
+        "layout": { "type": "View", "platform": "android", "child": [] }
+      },
+      "tokens": {
+        "ios": ["ios", "swift", "swiftui", "uikit"],
+        "android": ["android", "kotlin", "java", "compose", "xml"],
+        "web": ["web", "typescript", "javascript", "react"]
+      }
+    }
+  },
+  "layoutRootPlatforms": {
+    "attribute": "platforms",
+    "summary": "Layout-root array whitelisting the distribution targets of the ENTIRE file (e.g. [\"ios\", \"android\"]). Distinct from the node-level 'platform' directive: 'platforms' picks which platforms get the file at all; 'platform' shapes a single node per platform."
+  },
+  "vsResponsive": {
+    "summary": "'responsive' is resolved at RUNTIME by each platform's framework (window size class / orientation); 'platform' is resolved at BUILD time and is invisible at runtime. Use 'platform' for per-OS differences, 'responsive' for per-form-factor differences. The resolver leaves 'responsive' untouched."
+  },
+  "authoringGuidance": {
+    "spec": "Screen specs stay platform-agnostic; when a node intentionally differs per platform, note the difference in the spec text of the section that owns the node (do not fork the spec per platform). Large screens split into sub-specs list them in the parent's 'subSpecs' array — the sub-spec that owns the node carries the note.",
+    "precedence": "Per-node 'platform' override > inline base attribute > 'style'-provided value. Distribution bakes the override into the node as a plain inline attribute; style merge (applied later, at codegen or dynamic runtime) always yields to inline attributes.",
+    "dynamicFace": "Distribution has already resolved 'platform' by the time a layout reaches a device, so the dynamic face never sees the key either — declaring it costs nothing at runtime on any face."
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jui-tools-mcp-server",
-  "version": "2.6.0",
+  "version": "2.8.0",
   "description": "MCP server for JsonUI project management - wraps jui and jsonui-doc CLIs plus component spec lookup",
   "main": "dist/index.js",
   "scripts": {

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.5.0";
+const JSONUI_CLI_TAG = "v1.6.0";
 const BASE_URL =
   process.env.JSONUI_CLI_RAW_BASE ||
   `https://raw.githubusercontent.com/Tai-Kimura/jsonui-cli/${JSONUI_CLI_TAG}`;

package/scripts/fetch-manifest.js

@@ -33,6 +33,13 @@ export const FILES = [
     remote: "shared/core/attribute_semantics.json",
     local: "attribute_semantics.json",
   },
+  // Canonical platform-scoping semantics (node 'platform' directive, root
+  // 'platforms', vs 'responsive') — backs get_platform_rules and the
+  // search-side topic-guide index.
+  {
+    remote: "shared/core/platform_semantics.json",
+    local: "platform_semantics.json",
+  },
   // Canonical binding-resolution semantics. This was bundled in data/ but
   // missing from FILES, so the snapshot only ever refreshed by hand and
   // silently went stale — the same trap the screen-identity asset would

package/src/index.ts

@@ -14,6 +14,7 @@ import { register as registerGetBindingRules } from "./tools/spec/get_binding_ru
 import { register as registerGetScreenIdentity } from "./tools/spec/get_screen_identity.js";
 import { register as registerGetPlatformMapping } from "./tools/spec/get_platform_mapping.js";
 import { register as registerGetDataSource } from "./tools/spec/get_data_source.js";
+import { register as registerGetPlatformRules } from "./tools/spec/get_platform_rules.js";
 
 // --- Group B: Project Context ---
 import { register as registerGetProjectConfig } from "./tools/context/get_project_config.js";
@@ -22,6 +23,7 @@ import { register as registerListComponentSpecs } from "./tools/context/list_com
 import { register as registerListLayouts } from "./tools/context/list_layouts.js";
 import { register as registerReadSpecFile } from "./tools/context/read_spec_file.js";
 import { register as registerReadLayoutFile } from "./tools/context/read_layout_file.js";
+import { register as registerSearchSpecs } from "./tools/context/search_specs.js";
 
 // --- Group C: jui CLI ---
 import { register as registerJuiInit } from "./tools/jui/jui_init.js";
@@ -89,7 +91,7 @@ log(
 // Initialize server config for Groups B/C/D
 const config = new ServerConfig();
 
-// Register Group A: Component Spec Lookup (7 tools)
+// Register Group A: Component Spec Lookup (9 tools)
 registerLookupComponent(server, loader);
 registerLookupAttribute(server, loader);
 registerSearchComponents(server, loader);
@@ -98,14 +100,16 @@ registerGetBindingRules(server, loader);
 registerGetScreenIdentity(server, loader);
 registerGetPlatformMapping(server, loader);
 registerGetDataSource(server, loader);
+registerGetPlatformRules(server, loader);
 
-// Register Group B: Project Context (6 tools)
+// Register Group B: Project Context (7 tools)
 registerGetProjectConfig(server, config);
 registerListScreenSpecs(server, config);
 registerListComponentSpecs(server, config);
 registerListLayouts(server, config);
 registerReadSpecFile(server, config);
 registerReadLayoutFile(server, config);
+registerSearchSpecs(server, config);
 
 // Register Group C: jui CLI (8 tools)
 registerJuiInit(server, config);

package/src/spec_loader.ts

@@ -61,6 +61,10 @@ export interface DataSourceInfo {
   /// contract (cross-effect rulings, plan 33). Optional: absent on older
   /// jsonui-cli checkouts.
   attributeSemantics: FileInfo | null;
+  /// shared/core/platform_semantics.json — platform-scoped layout semantics
+  /// (the node-level 'platform' directive, root 'platforms', vs
+  /// 'responsive'). Optional: absent on older jsonui-cli checkouts.
+  platformSemantics: FileInfo | null;
   /// conformance/coverage.json — declared-but-unimplemented (component,
   /// attribute, platform) pairs with their recorded reasons. Optional: absent
   /// on older jsonui-cli checkouts.
@@ -102,6 +106,7 @@ export class SpecLoader {
   private commonAttributesRaw: Record<string, any> = {};
   private bindingSemantics: Record<string, any> | null = null;
   private attributeSemantics: Record<string, any> | null = null;
+  private platformSemantics: Record<string, any> | null = null;
   /// `${component}.${attribute}` -> [{platform, reason, note}] from the
   /// coverage ledger. The ledger tracks pairs that ARE declared (platform
   /// field includes them) but that the platform's codegen does not consume —
@@ -243,9 +248,56 @@ export class SpecLoader {
       }
     }
 
+    // Topic-guide index: task vocabulary ("iOSだけ色を変える", "ios only",
+    // "platform override") does not contain any component or attribute
+    // name, so the loops above can't surface the mechanism. Each guide
+    // declares its own keywords (en + ja) in its semantics file; a hit
+    // pins a pointer to the dedicated tool at the top of the results.
+    for (const guide of this.topicGuides()) {
+      const hit = guide.keywords.some(
+        (kw) => q.includes(kw) || (q.length >= 3 && kw.includes(q))
+      );
+      if (hit) {
+        results.push({
+          guide: guide.topic,
+          score: 100,
+          matches: [guide.summary],
+          nextTool: guide.tool,
+        });
+      }
+    }
+
     return results.sort((a, b) => b.score - a.score);
   }
 
+  /** Keyword-indexed topical guides, each backed by a dedicated MCP tool. */
+  private topicGuides(): Array<{
+    topic: string;
+    tool: string;
+    summary: string;
+    keywords: string[];
+  }> {
+    const guides: Array<{
+      topic: string;
+      tool: string;
+      summary: string;
+      keywords: string[];
+    }> = [];
+    if (this.platformSemantics) {
+      const kws = Array.isArray(this.platformSemantics.keywords)
+        ? (this.platformSemantics.keywords as string[])
+        : [];
+      guides.push({
+        topic: "platform_rules",
+        tool: "get_platform_rules",
+        summary:
+          "Per-platform styling/visibility (e.g. change fontColor on iOS only): node-level 'platform' directive (object form = per-platform overrides, string form = platform filter), root 'platforms' whitelist, vs 'responsive'. Call get_platform_rules for the full semantics with examples.",
+        keywords: kws.map((k) => k.toLowerCase()),
+      });
+    }
+    return guides;
+  }
+
   getModifierOrder(platform?: string): any {
     if (platform) return (MODIFIER_ORDER as any)[platform] || null;
     return MODIFIER_ORDER;
@@ -275,6 +327,7 @@ export class SpecLoader {
       this.dataSource.screenIdentity,
       this.dataSource.bindingSemantics,
       this.dataSource.attributeSemantics,
+      this.dataSource.platformSemantics,
       this.dataSource.coverage,
     ].filter((f): f is FileInfo => f != null);
 
@@ -309,6 +362,15 @@ export class SpecLoader {
     };
   }
 
+  getPlatformRules(): any {
+    // Canonical platform-scoping semantics (SSoT:
+    // shared/core/platform_semantics.json — restates
+    // jui_tools/jui_cli/core/platform_resolver.py). Null on jsonui-cli
+    // checkouts that predate the file; the tool reports that instead of
+    // inventing rules.
+    return this.platformSemantics;
+  }
+
   getPlatformMapping(category?: string): any {
     if (category) return (PLATFORM_MAPPING as any)[category] || null;
     return PLATFORM_MAPPING;
@@ -376,6 +438,23 @@ export class SpecLoader {
       this.attributeSemantics = null;
     }
 
+    // Platform-scoped layout semantics (node 'platform' directive, root
+    // 'platforms', vs 'responsive'). Optional for the same backward-compat
+    // reason.
+    let platformSemanticsResolution: FileInfo | null = null;
+    try {
+      const platSemResolution = this.resolveFile(
+        "shared/core/platform_semantics.json",
+        "data/platform_semantics.json"
+      );
+      this.platformSemantics = JSON.parse(
+        readFileSync(platSemResolution.path, "utf-8")
+      ) as Record<string, any>;
+      platformSemanticsResolution = platSemResolution;
+    } catch {
+      this.platformSemantics = null;
+    }
+
     // Canonical screen identity (screen-identity track). Optional so older
     // jsonui-cli checkouts without the file still load.
     try {
@@ -462,6 +541,7 @@ export class SpecLoader {
       screenIdentity: screenIdentityResolution,
       bindingSemantics: bindingResolution,
       attributeSemantics: attributeSemanticsResolution,
+      platformSemantics: platformSemanticsResolution,
       coverage: coverageResolution,
       componentCount,
       commonAttributeCount: Object.keys(this.commonAttributesRaw).filter(

package/src/tools/context/list_screen_specs.ts

@@ -22,20 +22,38 @@ export function register(server: McpServer, config: ServerConfig) {
         }
 
         const files = readdirSync(specDir).filter((f) => f.endsWith(".spec.json"));
-        const specs = files.map((file) => {
+        const specs: any[] = [];
+        for (const file of files) {
           try {
             const data = JSON.parse(readFileSync(join(specDir, file), "utf-8"));
-            return {
+            specs.push({
               file,
               name: data.metadata?.name || file.replace(".spec.json", ""),
               displayName: data.metadata?.displayName || "",
               type: data.type || "screen_spec",
               layoutFile: data.metadata?.layoutFile || null,
-            };
+            });
+            // A parent spec splits one screen across sub-spec files (its
+            // 'subSpecs' array). Surface them inline so a session can see
+            // the split and read_spec_file the right part without first
+            // opening the parent.
+            if (Array.isArray(data.subSpecs)) {
+              for (const sub of data.subSpecs) {
+                if (!sub?.file) continue;
+                specs.push({
+                  file: sub.file,
+                  name: sub.name || sub.file,
+                  displayName: sub.description || "",
+                  type: "screen_sub_spec",
+                  parent: file,
+                  layoutFile: data.metadata?.layoutFile || null,
+                });
+              }
+            }
           } catch {
-            return { file, name: file.replace(".spec.json", ""), displayName: "", type: "unknown", layoutFile: null };
+            specs.push({ file, name: file.replace(".spec.json", ""), displayName: "", type: "unknown", layoutFile: null });
           }
-        });
+        }
 
         return { content: [{ type: "text", text: JSON.stringify(specs, null, 2) }] };
       } catch (e: any) {

package/src/tools/context/search_specs.ts

@@ -0,0 +1,124 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { readFileSync, readdirSync, existsSync, statSync } from "fs";
+import { join, relative } from "path";
+import { ServerConfig } from "../../config.js";
+
+const MAX_RESULTS = 30;
+const SNIPPET_LEN = 200;
+
+/** Recursively collect *.spec.json / *.component.json under dir. */
+function collectSpecFiles(dir: string, out: string[] = []): string[] {
+  for (const entry of readdirSync(dir)) {
+    const p = join(dir, entry);
+    if (statSync(p).isDirectory()) {
+      collectSpecFiles(p, out);
+    } else if (entry.endsWith(".spec.json") || entry.endsWith(".component.json")) {
+      out.push(p);
+    }
+  }
+  return out;
+}
+
+/**
+ * Walk a parsed spec and report the JSON paths whose keys or string values
+ * contain the query. One entry per path, with a short snippet.
+ */
+function findMatches(
+  node: any,
+  q: string,
+  path: string,
+  out: { path: string; snippet: string }[]
+) {
+  if (out.length >= MAX_RESULTS) return;
+  if (typeof node === "string") {
+    if (node.toLowerCase().includes(q)) {
+      out.push({ path, snippet: node.slice(0, SNIPPET_LEN) });
+    }
+    return;
+  }
+  if (Array.isArray(node)) {
+    node.forEach((v, i) => findMatches(v, q, `${path}[${i}]`, out));
+    return;
+  }
+  if (node && typeof node === "object") {
+    for (const [k, v] of Object.entries(node)) {
+      const childPath = path ? `${path}.${k}` : k;
+      if (k.toLowerCase().includes(q)) {
+        const snippet =
+          typeof v === "string"
+            ? v.slice(0, SNIPPET_LEN)
+            : JSON.stringify(v)?.slice(0, SNIPPET_LEN) ?? "";
+        out.push({ path: childPath, snippet });
+        if (out.length >= MAX_RESULTS) return;
+      }
+      findMatches(v, q, childPath, out);
+      if (out.length >= MAX_RESULTS) return;
+    }
+  }
+}
+
+export function register(server: McpServer, config: ServerConfig) {
+  server.tool(
+    "search_specs",
+    "Keyword-search across ALL project spec files (screen specs, sub-specs in subdirectories, component specs). Returns file + JSON path + snippet per match — the fast way to find which spec (or which sub-spec of a split screen) covers a topic",
+    {
+      query: z.string().describe("Search keyword (matched case-insensitively against keys and string values)"),
+      project_dir: z.string().optional().describe("Project directory (overrides JUI_PROJECT_DIR env)"),
+    },
+    async ({ query, project_dir }) => {
+      try {
+        const projectDir = config.resolveProjectDir(project_dir);
+        const projectConfig = config.readProjectConfig(projectDir);
+        const q = query.toLowerCase();
+        if (!q.trim()) {
+          return { content: [{ type: "text", text: "Empty query." }] };
+        }
+
+        const dirs = new Set<string>();
+        for (const field of ["spec_directory", "component_spec_directory"] as const) {
+          try {
+            const d = config.resolveDir(projectConfig, field, projectDir);
+            if (existsSync(d)) dirs.add(d);
+          } catch {
+            /* directory not configured */
+          }
+        }
+        if (dirs.size === 0) {
+          return { content: [{ type: "text", text: "No spec directories found." }] };
+        }
+
+        const results: any[] = [];
+        for (const dir of dirs) {
+          for (const filePath of collectSpecFiles(dir)) {
+            if (results.length >= MAX_RESULTS) break;
+            let matches: { path: string; snippet: string }[] = [];
+            try {
+              const data = JSON.parse(readFileSync(filePath, "utf-8"));
+              findMatches(data, q, "", matches);
+            } catch {
+              continue;
+            }
+            if (matches.length > 0) {
+              results.push({
+                file: relative(dir, filePath),
+                matchCount: matches.length,
+                matches: matches.slice(0, 5),
+              });
+            }
+          }
+        }
+
+        if (results.length === 0) {
+          return { content: [{ type: "text", text: `No matches for '${query}'.` }] };
+        }
+        results.sort((a, b) => b.matchCount - a.matchCount);
+        return {
+          content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+        };
+      } catch (e: any) {
+        return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+      }
+    }
+  );
+}

package/src/tools/spec/get_platform_rules.ts

@@ -0,0 +1,26 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { SpecLoader } from "../../spec_loader.js";
+
+export function register(server: McpServer, loader: SpecLoader) {
+  server.tool(
+    "get_platform_rules",
+    "Get platform-scoping rules for layouts: how to change an attribute on one platform only (node-level 'platform' object form, e.g. iOS-only fontColor), how to drop a node per platform (string form + language tokens), the layout-root 'platforms' whitelist, precedence, and how this differs from 'responsive'",
+    {},
+    async () => {
+      const result = loader.getPlatformRules();
+      if (!result) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "platform_semantics.json not found — the connected jsonui-cli checkout predates it. Fall back to lookup_attribute('platform') for the short definition.",
+            },
+          ],
+        };
+      }
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+      };
+    }
+  );
+}

package/tests/snapshot_completeness.test.ts

@@ -45,6 +45,7 @@ function reportedFiles(source: DataSourceInfo) {
     source.screenIdentity,
     source.bindingSemantics,
     source.attributeSemantics,
+    source.platformSemantics,
     source.coverage,
   ].filter((f): f is NonNullable<typeof f> => f != null);
 }

package/tests/spec_loader.test.ts

@@ -386,6 +386,61 @@ describe("SpecLoader spec model", () => {
   });
 });
 
+describe("SpecLoader platform rules + topic-guide search", () => {
+  const SEMANTICS = {
+    version: 1,
+    title: "Platform-scoped layout semantics",
+    keywords: ["platform", "ios only", "iosだけ", "出し分け"],
+    nodeDirective: { attribute: "platform" },
+  };
+
+  function loaderWithSemantics(): SpecLoader {
+    const mcpRoot = makeTempDir("mcp-root");
+    makeBundledDataset(mcpRoot);
+    writeJson(join(mcpRoot, "data/platform_semantics.json"), SEMANTICS);
+    return new SpecLoader(mcpRoot);
+  }
+
+  it("getPlatformRules returns the semantics file verbatim", () => {
+    expect(loaderWithSemantics().getPlatformRules()).toEqual(SEMANTICS);
+  });
+
+  it("getPlatformRules is null (not invented) without the file", () => {
+    const mcpRoot = makeTempDir("mcp-root");
+    makeBundledDataset(mcpRoot);
+    expect(new SpecLoader(mcpRoot).getPlatformRules()).toBeNull();
+  });
+
+  it("task vocabulary surfaces the guide pointer at the top of search", () => {
+    // No component or attribute name in the query — only the guide can hit.
+    const results = loaderWithSemantics().searchComponents(
+      "iosだけフォントカラーを変えたい"
+    );
+    expect(results[0]).toMatchObject({
+      guide: "platform_rules",
+      nextTool: "get_platform_rules",
+      score: 100,
+    });
+  });
+
+  it("an english task query hits the guide too", () => {
+    const results = loaderWithSemantics().searchComponents("ios only color");
+    expect(results.some((r: any) => r.guide === "platform_rules")).toBe(true);
+  });
+
+  it("guide keywords do not fire on unrelated queries", () => {
+    const results = loaderWithSemantics().searchComponents("zebra");
+    expect(results.every((r: any) => r.guide == null)).toBe(true);
+  });
+
+  it("no guide entries without the semantics file", () => {
+    const mcpRoot = makeTempDir("mcp-root");
+    makeBundledDataset(mcpRoot);
+    const results = new SpecLoader(mcpRoot).searchComponents("ios only");
+    expect(results.every((r: any) => r.guide == null)).toBe(true);
+  });
+});
+
 // ----- root helper ----------------------------------------------------------
 
 describe("mcpRootFromImportMetaUrl", () => {

package/tests/tools_context.test.ts

@@ -13,6 +13,7 @@ import { register as registerListComponentSpecs } from "../src/tools/context/lis
 import { register as registerListLayouts } from "../src/tools/context/list_layouts.js";
 import { register as registerReadSpecFile } from "../src/tools/context/read_spec_file.js";
 import { register as registerReadLayoutFile } from "../src/tools/context/read_layout_file.js";
+import { register as registerSearchSpecs } from "../src/tools/context/search_specs.js";
 import {
   cleanupTempDirs,
   createToolHarness,
@@ -38,8 +39,46 @@ beforeEach(() => {
   registerListLayouts(harness.server, config);
   registerReadSpecFile(harness.server, config);
   registerReadLayoutFile(harness.server, config);
+  registerSearchSpecs(harness.server, config);
 });
 
+/** A screen split across a parent spec + sub-spec files in a subdirectory. */
+function writeSplitSpecFixture(root: string) {
+  writeJson(join(root, "docs/screens/json/messages.spec.json"), {
+    type: "screen_parent_spec",
+    metadata: {
+      name: "Messages",
+      displayName: "Messages Screen",
+      layoutFile: "messages",
+    },
+    subSpecs: [
+      {
+        file: "messages/messages-core.spec.json",
+        name: "Messages - Core",
+        description: "Core structure and message list",
+      },
+      {
+        file: "messages/messages-composer.spec.json",
+        name: "Messages - Composer",
+        description: "Input area and attachments",
+      },
+    ],
+  });
+  writeJson(join(root, "docs/screens/json/messages/messages-core.spec.json"), {
+    type: "screen_spec",
+    metadata: { name: "Messages - Core" },
+    structure: { messageList: { paging: true, currentPage: "@{currentPage}" } },
+  });
+  writeJson(
+    join(root, "docs/screens/json/messages/messages-composer.spec.json"),
+    {
+      type: "screen_spec",
+      metadata: { name: "Messages - Composer" },
+      structure: { attachButton: { note: "opens the attachment sheet" } },
+    }
+  );
+}
+
 afterEach(() => {
   delete process.env.JUI_PROJECT_DIR;
   cleanupTempDirs();
@@ -121,6 +160,81 @@ describe("list_screen_specs", () => {
     const text = await harness.call("list_screen_specs", { project_dir: proj });
     expect(text).toContain("Spec directory not found");
   });
+
+  it("expands a parent spec's subSpecs inline so the split is visible", async () => {
+    writeSplitSpecFixture(projectDir);
+    const specs = JSON.parse(
+      await harness.call("list_screen_specs", { project_dir: projectDir })
+    );
+    const core = specs.find(
+      (s: any) => s.file === "messages/messages-core.spec.json"
+    );
+    expect(core).toEqual({
+      file: "messages/messages-core.spec.json",
+      name: "Messages - Core",
+      displayName: "Core structure and message list",
+      type: "screen_sub_spec",
+      parent: "messages.spec.json",
+      layoutFile: "messages",
+    });
+    // The parent itself still lists normally.
+    expect(
+      specs.find((s: any) => s.file === "messages.spec.json")?.type
+    ).toBe("screen_parent_spec");
+  });
+});
+
+describe("search_specs", () => {
+  it("finds a keyword inside a sub-spec file in a subdirectory", async () => {
+    writeSplitSpecFixture(projectDir);
+    const results = JSON.parse(
+      await harness.call("search_specs", {
+        query: "currentPage",
+        project_dir: projectDir,
+      })
+    );
+    const hit = results.find(
+      (r: any) => r.file === "messages/messages-core.spec.json"
+    );
+    expect(hit).toBeTruthy();
+    expect(hit.matches[0].path).toContain("structure.messageList");
+    expect(hit.matches[0].snippet).toContain("@{currentPage}");
+  });
+
+  it("matches keys as well as string values, case-insensitively", async () => {
+    writeSplitSpecFixture(projectDir);
+    const results = JSON.parse(
+      await harness.call("search_specs", {
+        query: "ATTACHMENT",
+        project_dir: projectDir,
+      })
+    );
+    expect(
+      results.some(
+        (r: any) => r.file === "messages/messages-composer.spec.json"
+      )
+    ).toBe(true);
+  });
+
+  it("searches component specs too", async () => {
+    const results = JSON.parse(
+      await harness.call("search_specs", {
+        query: "ExampleCard",
+        project_dir: projectDir,
+      })
+    );
+    expect(
+      results.some((r: any) => r.file === "example_card.component.json")
+    ).toBe(true);
+  });
+
+  it("reports no matches as a plain message", async () => {
+    const text = await harness.call("search_specs", {
+      query: "zzz_nothing_zzz",
+      project_dir: projectDir,
+    });
+    expect(text).toContain("No matches");
+  });
 });
 
 describe("list_component_specs", () => {