jui-tools-mcp-server 2.5.0

package/data/attribute_semantics.json

@@ -0,0 +1,137 @@
+{
+  "version": 1,
+  "title": "JsonUI attribute semantics — observable cross-platform contract",
+  "notes": "Hand-authored canonical rulings (semantic-drift track 33, established 2026-08-03). Each adjudicated attribute-semantics ruling is declared ONCE here; the 'observable' block states the cross-platform effect expectation that `jui conformance gate --cross-effect` verifies mechanically against every platform's control-diff verdicts (expectation values: 'uniformly-inert' = the fixture must render identically to its control on every in-scope platform; 'uniformly-active' = it must differ on every in-scope platform). Toolchain code comments must POINT here instead of restating the rule — comment canon rots (the border ruling reversed direction twice within 48 hours while living as comments in three toolchains). Canonical choices are design decisions, not majority votes of existing implementations. Add one entry per ruling as the cross-effect adjudication queue is consumed.",
+  "semantics": {
+    "border": {
+      "widthAlone": "no-draw",
+      "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). 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.",
+      "observable": {
+        "common/borderWidth__static": "uniformly-inert",
+        "common/borderStyle__solid": "uniformly-inert",
+        "common/borderStyle__dashed": "uniformly-inert",
+        "common/borderStyle__dotted": "uniformly-inert"
+      }
+    },
+    "image": {
+      "defaultContentMode": "fit",
+      "fill": "stretch",
+      "ruling": "2026-08-03 user rulings: (a) the default contentMode is fit on every platform — web's implicit cover default was drift (fixed in rjui, 22d96b4); (b) fill is the stretch (scaleToFill synonym) — AspectFill is the crop. All three platforms now implement the full mapping including the positional modes (unscaled + aligned + cropped; sjui/kjui/SwiftJsonUI/KotlinJsonUI, 33 wave). Observables: fit-valued fixtures equal the default rendering (uniformly inert); fill/scaleToFill differ from it everywhere (uniformly active). Verified on the 33 round-3 measurement.",
+      "observable": {
+        "Image/contentMode__fit": "uniformly-inert",
+        "Image/contentMode__aspectfit": "uniformly-inert",
+        "NetworkImage/contentMode__fit": "uniformly-inert",
+        "NetworkImage/contentMode__aspectfit": "uniformly-inert",
+        "Image/contentMode__fill": "uniformly-active",
+        "Image/contentMode__scaletofill": "uniformly-active"
+      }
+    },
+    "textView": {
+      "flexibleHeight": "declared height is the growth floor",
+      "ruling": "2026-08-03 user ruling (31 handoff): with flexible enabled, the declared height is the floor the view GROWS from — it never shrinks below it to follow smaller content. android's behavior is canonical; ios (both paths) shrank with content and must adopt the floor formula min = minHeight ?? height ?? default (landed in the 33 wave: SwiftJsonUI dynamic + sjui codegen, floor formula min = minHeight ?? height). web measures 'has effect' — verify it matches floor semantics before recording it anywhere. No activeness observable: at fixture content size a correct floor renders identically to the control (that is WHY the android control_diff entry was removed in e78af64); the mechanical check belongs to the geometry probe (systematic-detection optimization track).",
+      "observable": {}
+    },
+    "size": {
+      "maxBoundsClampFill": "matchParent is clamped by maxWidth/maxHeight",
+      "ruling": "2026-08-03 user ruling (31 handoff): matchParent + maxWidth/maxHeight resolves to min(parent extent, bound) — the bound clamps the fill. Generated code is canonical (kjui emits the constraint before the fill since 847fb56); KJUI dynamic ordered fillMaxWidth before widthIn, ignoring the bound entirely — reordered in the 33 wave (bounds precede a fill, stay after an explicit size). The composite clamp fixtures below are the observable: a clamping platform renders visibly narrower/shorter than its filled control (active); ignoring the bound renders identically (inert). Companion precedence (2026-08-03 campaign adjudication): an EXPLICIT numeric dimension pins the constraints and its bound stays inert (kjui codegen 847fb56, ios 35efc2b, rjui skips max-* under an explicit size); bounds in turn clamp a FILL. Order: explicit > bounds > fill.",
+      "observable": {
+        "common/maxWidth__fill_clamp": "uniformly-active",
+        "common/maxHeight__fill_clamp": "uniformly-active"
+      },
+      "explicitOverBounds": "an explicit numeric dimension wins over its min/max bound"
+    },
+    "networkImage": {
+      "noSrc": "defaultImage",
+      "ruling": "2026-08-03 user ruling: with no src, NetworkImage displays defaultImage; while loading it displays the first of hint/placeholder/loadingImage; on error it displays errorImage, falling back to defaultImage. Implemented on all platforms in the 33 wave (KotlinJsonUI defaultImage read + Coil fallback chain; ios placeholder no longer collapses over defaultImage; rjui defaultImage prop + template state machine). State-image fixtures use the DISTINCT conformance_sample_alt asset, so a hijacked no-src state renders visibly — the uniformly-inert observables verify the chain end-to-end.",
+      "observable": {
+        "NetworkImage/placeholder__static": "uniformly-inert",
+        "NetworkImage/hint__static": "uniformly-inert",
+        "NetworkImage/errorImage__static": "uniformly-inert",
+        "NetworkImage/loadingImage__static": "uniformly-inert"
+      }
+    },
+    "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",
+      "ruling": "2026-08-03 campaign adjudication (31/33 rounds, measured bbox evidence in the 33 geometry diagnosis table): an overlay (ZStack) child offsets by the FULL margin on each declared edge; declaring centerInParent/centerHorizontal/centerVertical disables the margin on the centered axis; the margins array and the RTL start/endMargin spellings resolve as padding-equivalent insets. Divergent rows are ledgered per-fixture with their measured deltas; the mechanical closure is the geometry probe (systematic-detection optimization track, de-scoped from the completion gate). No activeness observable: position deltas are invisible to fixture-vs-control activeness when every platform moves.",
+      "observable": {}
+    },
+    "gravityDefaults": {
+      "defaultGravity": "top|start",
+      "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.",
+      "observable": {}
+    },
+    "shadow": {
+      "stringPipe": "five-field strict",
+      "ruling": "2026-08-03 campaign adjudication (31 wave, unified in 3e87b96/ca65fb6): the shadow string pipe format is exactly five fields (color|offsetX|offsetY|blur|opacity); any other count renders NOTHING on every platform — no partial parsing, no platform default. The conformance fixtures ship the valid five-field pipe; a malformed-count probe belongs to the validator, not the render layer.",
+      "observable": {}
+    },
+    "gradient": {
+      "defaultDirection": "vertical",
+      "ruling": "2026-08-03 campaign adjudication (31 gradient family): the default gradient direction is vertical (top to bottom) on every platform; an explicit \"vertical\" therefore equals the default rendering.",
+      "observable": {
+        "GradientView/gradientDirection__vertical": "uniformly-inert"
+      }
+    },
+    "skinIdioms": {
+      "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 (ios hides tab labels, android/web keep the labeled bar). 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"
+        },
+        "TextField/borderStyle__bezel": {
+          "ios": "inert",
+          "android": "active",
+          "web": "inert"
+        },
+        "TextField/borderStyle__bezel_2": {
+          "ios": "inert",
+          "android": "active",
+          "web": "inert"
+        },
+        "TextField/borderStyle__line": {
+          "ios": "inert",
+          "android": "active",
+          "web": "active"
+        },
+        "TextField/borderStyle__line_2": {
+          "ios": "inert",
+          "android": "active",
+          "web": "active"
+        },
+        "TextField/borderStyle__roundedrect": {
+          "ios": "active",
+          "android": "active",
+          "web": "inert"
+        },
+        "TextField/borderStyle__roundedrect_2": {
+          "ios": "active",
+          "android": "active",
+          "web": "inert"
+        },
+        "TabView/showLabels__true": {
+          "ios": "active",
+          "android": "inert",
+          "web": "inert"
+        }
+      }
+    },
+    "progressValue": {
+      "canonical": "progress",
+      "legacy": "value",
+      "undeclaredDefault": "0 (empty bar) on a determinate ProgressView; kjui renders indeterminate chrome when nothing is declared",
+      "ruling": "2026-08-04 campaign adjudication (closing the last unreviewed cross-effect row): `progress` is the canonical determinate value attribute (declared 0..1 in attribute_definitions); `value` is the undeclared legacy runtime spelling every reader keeps as fallback, canonical-first. Undeclared progress must NOT default to a nonzero fill — ios (dynamic + sjui codegen) defaulted to 0.5, which made the control half-full and the progress:0.5 fixture measured inert; android (both paths) read only the legacy `value` and ignored the canonical attribute entirely. Fixed canonical-first on every path (SwiftJsonUI ProgressConverter, sjui progress_converter.rb, KotlinJsonUI DynamicProgressComponent, kjui progress_component.rb, rjui progress_converter.rb). The observable pins the repair: a half-full bar must differ from its undeclared control on every platform.",
+      "observable": {
+        "Progress/progress__static": "uniformly-active"
+      }
+    }
+  }
+}

package/data/binding_semantics.json

@@ -0,0 +1,115 @@
+{
+  "version": 1,
+  "title": "JsonUI binding resolution semantics (canonical)",
+  "notes": "Hand-authored canonical source (renderer SSoT track 15, declared 2026-07-24). This file IS the SSoT for how '@{...}' expressions resolve; runtimes and code generators conform to it, not the other way around. Companion test vectors: shared/core/binding_vectors.json. Canonical choices are design decisions, not majority votes of existing implementations.",
+  "syntax": {
+    "expression": "@{ inner }",
+    "inner": "path [ '??' default ] | '!' path (boolean value context only)",
+    "path": "identifier segments joined by '.', with optional bracket index: profile.name, items[0].title",
+    "whitespace": "Whitespace around 'inner', around '??', and around the default literal is insignificant."
+  },
+  "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,
+      "features": ["path", "default"],
+      "unresolved": "emptyString"
+    },
+    "value": {
+      "description": "Whole-value binding for typed attributes (number / bool / color / enum / src / visibility / ...). The whole attribute value must be exactly one '@{...}' expression; no surrounding text.",
+      "interpolation": false,
+      "features": ["path", "default", "negationIfBool"],
+      "unresolved": "attributeDefault"
+    },
+    "embedParams": {
+      "description": "Embed 'params' leaf values. Leaves are scalar literals or one whole '@{...}' expression resolved against the PARENT screen's data. Intermediate nodes are literal objects; arrays are unsupported (validator error, established by the embed isolated+params track).",
+      "interpolation": false,
+      "features": ["path"],
+      "unresolved": "dropKey"
+    },
+    "nameRef": {
+      "description": "Event / handler name references (onclick etc.). '@{name}' and the bare name are equivalent spellings of a handler NAME; this is name extraction, not value resolution. Path, default, and negation are not applicable.",
+      "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.",
+      "interpolation": false,
+      "features": [],
+      "unresolved": "attributeDefault"
+    }
+  },
+  "pathResolution": {
+    "order": ["flatKey", "pathTraversal"],
+    "rule": "Look up the raw inner string as a flat key in the data map first; if absent, split on '.' and traverse. A data map that literally contains the key 'a.b' therefore shadows the nested path a.b (determinism guarantee).",
+    "arrayIndex": {
+      "syntax": "name[index] with a non-negative integer literal",
+      "rule": "Canonical array access is bracket syntax (items[0].title). Out-of-range or non-array => the path is unresolved (never a crash).",
+      "nonCanonical": "Dot-numeric segments (items.0.title) are a frozen UIKit-runtime legacy; not canonical, not to be added elsewhere."
+    },
+    "intermediateMiss": "A missing or non-object intermediate node makes the whole path unresolved; it must never crash or throw (web: generated user data paths use optional chaining)."
+  },
+  "defaultOperator": {
+    "spelling": "@{path ?? default}",
+    "contexts": ["text", "value"],
+    "arity": "Exactly one '??' per expression. More than one is a validator error; runtimes split on the FIRST '??' only (the remainder is part of the default literal parse and fails closed to unresolved).",
+    "defaultLiteral": {
+      "string": "Quoted with double OR single quotes: \"x\" or 'x' (single quotes are canonical-new; historical KJUI accepted only double quotes).",
+      "boolean": "true | false",
+      "number": "Integer or decimal literal",
+      "null": "null => treated as unresolved (falls through to the context's unresolved behavior)"
+    },
+    "rule": "If the path resolves (including to false, 0, or empty string), the resolved value wins. Only an UNRESOLVED path yields the default. In 'value' context the default is typed (true stays a bool, 42 stays a number)."
+  },
+  "unresolved": {
+    "text": "Empty string per occurrence (plus a debug-level log listing available keys).",
+    "value": "The attribute's default value applies (component-defined). Never a crash, never a rendered error.",
+    "embedParams": "The key is OMITTED from the resolved params object so the embedded screen's own data-section defaultValue applies.",
+    "twoWay": "The attribute's default; write-back targets the declared identifier regardless."
+  },
+  "fallbackPrecedence": [
+    "1. data-section defaultValue (merged into the data map before any binding resolves)",
+    "2. inline '??' default (only reached when the key is absent after step 1)",
+    "3. context unresolved behavior (emptyString / attributeDefault / dropKey)"
+  ],
+  "negation": {
+    "spelling": "@{!path}",
+    "contexts": ["value (boolean attributes only)"],
+    "rule": "Resolve the path, coerce to bool (see coercion), then invert. An unresolved path stays unresolved (attribute default applies WITHOUT inversion). Any other context is a validator error; runtimes treat the token as an ordinary (unresolvable) key and fall through to the context's unresolved behavior."
+  },
+  "coercion": {
+    "bool": {
+      "accepts": ["bool", "int (non-zero => true)", "string 'true'/'1' => true, 'false'/'0' => false (case-insensitive)"],
+      "otherwise": "unresolved"
+    },
+    "number": {
+      "accepts": ["number", "numeric string"],
+      "otherwise": "unresolved"
+    },
+    "string": {
+      "accepts": ["any scalar via text stringification rules"],
+      "otherwise": "unresolved (objects/arrays do not stringify into value context)"
+    }
+  },
+  "textStringification": {
+    "number": "JSON-faithful: integral numbers render with no decimal point ('5', not '5.0'); non-integral render with their decimal digits.",
+    "bool": "'true' / 'false'",
+    "null": "unresolved (empty string)",
+    "objectOrArray": "unresolved (empty string) — never a platform debug dump"
+  },
+  "embedParamsTypes": "Resolved leaves keep native JSON types (bool stays bool, 5 stays integer 5). Unresolved leaves are dropped (see unresolved.embedParams).",
+  "collectionCellScope": {
+    "guaranteed": "The item object's own fields, flat, plus the reserved key 'index' (0-based).",
+    "parentData": "NOT guaranteed. Depending on parent-screen keys inside a cell is non-portable (validator warning).",
+    "itemPrefix": "'@{item.xxx}' is NOT canonical; scaffolds must emit flat field names."
+  },
+  "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-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."}
+  ]
+}