mobridge-mcp 0.0.1

package/dist/protocol/schemas/action.schema.json

@@ -0,0 +1,170 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "msm:action.schema.json",
+  "title": "Action + Result",
+  "description": "An action performed on a NodeRef (or a global/app action), plus its verified result. performAction()==true is NOT success; a VerificationPolicy must be satisfied.",
+  "$defs": {
+    "actionVerb": {
+      "enum": [
+        "CLICK", "LONG_CLICK", "SET_TEXT", "CLEAR_TEXT", "FOCUS",
+        "SCROLL_FORWARD", "SCROLL_BACKWARD", "SELECT", "EXPAND", "COLLAPSE",
+        "DISMISS", "COPY", "PASTE"
+      ]
+    },
+    "globalAction": {
+      "enum": ["BACK", "HOME", "RECENTS", "NOTIFICATION_SHADE"]
+    },
+    "appAction": {
+      "enum": ["APP_OPEN", "APP_DEEP_LINK", "APP_BRING_TO_FRONT", "APP_CLOSE_UI"],
+      "description": "APP_OPEN launches the launcher intent; APP_DEEP_LINK opens a URI; APP_BRING_TO_FRONT foregrounds an existing task; APP_CLOSE_UI = Back/Home and does NOT guarantee process death. Killing a process (force-stop) is a DESTRUCTIVE op and is NOT available here — use mobile.app.forceStop under MSM_APP_CONTROL (per-package authorize + critical denylist)."
+    },
+    "verificationPolicy": {
+      "enum": [
+        "NODE_STATE_CHANGED", "NODE_VALUE_EQUALS", "NODE_DISAPPEARED", "NODE_APPEARED",
+        "PACKAGE_CHANGED", "WINDOW_CHANGED", "COLLECTION_POSITION_CHANGED",
+        "CLIPBOARD_EQUALS", "EXPLICIT_CONDITION", "DISPATCH_ONLY"
+      ],
+      "description": "How success is verified. DISPATCH_ONLY is FORBIDDEN for destructive/financial/external-side-effect actions."
+    },
+    "dispatchStatus": {
+      "enum": ["DISPATCHED", "REJECTED", "FAILED"],
+      "description": "Purely whether the native action was SENT — never business success. DISPATCHED = the accessibility/gesture action was performed; REJECTED = a precondition blocked it; FAILED = native dispatch failed. Precondition rejections (TARGET_NOT_FOUND / AMBIGUOUS_MATCH / STALE_NODE_REF) are returned as errors, not here."
+    },
+    "verificationResult": {
+      "enum": ["CONDITION_MET", "CONDITION_NOT_MET", "CONDITION_UNKNOWN"],
+      "description": "Result of evaluating a SPECIFIC predicate (caller-supplied `expect`, or an intrinsic device-operation postcondition). This is predicate measurement, NOT task/business success — the AI concludes success from the evidence."
+    },
+    "stability": {
+      "enum": ["STABLE", "TRANSITIONING", "UNKNOWN"],
+      "description": "Whether the after-snapshot was captured on a settled screen."
+    },
+    "actionMethod": {
+      "enum": ["ACCESSIBILITY_ACTION", "ACCESSIBILITY_ACTION_ANCESTOR", "GESTURE_FALLBACK"]
+    },
+
+    "actionRequest": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["action"],
+      "properties": {
+        "action": { "$ref": "#/$defs/actionVerb" },
+        "target": {
+          "$ref": "msm:node-ref.schema.json",
+          "description": "Required for node actions."
+        },
+        "value": {
+          "type": ["string", "null"],
+          "description": "Literal text for SET_TEXT/PASTE. Mutually exclusive with valueRef."
+        },
+        "valueRef": {
+          "type": ["string", "null"],
+          "pattern": "^secret://",
+          "description": "Opaque secret reference, e.g. secret://account/password. Host never sends plaintext; runtime/broker resolves at execution; plaintext never appears in logs/diff/audit/result."
+        },
+        "allowGestureFallback": {
+          "type": "boolean",
+          "default": false,
+          "description": "Permit coordinate gesture into bounds if no accessibility action path exists."
+        },
+        "verify": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["policy"],
+          "properties": {
+            "policy": { "$ref": "#/$defs/verificationPolicy" },
+            "expected": {
+              "description": "Policy-specific expectation (e.g. value string for NODE_VALUE_EQUALS, a wait-condition for EXPLICIT_CONDITION).",
+              "$ref": "msm:wait.schema.json#/$defs/condition"
+            },
+            "timeoutMs": { "type": "integer", "minimum": 0, "default": 8000 },
+            "stableForMs": { "type": "integer", "minimum": 0, "default": 400 }
+          }
+        },
+        "idempotencyKey": {
+          "type": ["string", "null"],
+          "description": "Required for side-effect actions to make retry safe."
+        },
+        "generation": {
+          "type": ["integer", "null"],
+          "description": "Capture generation the target ref was built against (from screen.find/target). When set, the runtime hard-checks it and returns STALE_NODE_REF if the screen advanced — it never re-resolves a stale ref to a similar node."
+        }
+      },
+      "allOf": [
+        {
+          "$comment": "value and valueRef are mutually exclusive.",
+          "not": {
+            "type": "object",
+            "required": ["value", "valueRef"],
+            "properties": {
+              "value": { "type": "string" },
+              "valueRef": { "type": "string" }
+            }
+          }
+        }
+      ]
+    },
+
+    "actionResult": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Three separated layers. (1) dispatch = was the native action sent. (2) observation = objective before/after device measurement. (3) verification = OPTIONAL predicate evaluation, present only when a caller `expect` OR an intrinsic device postcondition applies. There is intentionally NO 'SUCCESS_VERIFIED' and NO 'verifiedBy': MCP never infers business success (login/payment/order); the AI concludes that from the evidence.",
+      "required": ["dispatch", "observation"],
+      "properties": {
+        "dispatch": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["status"],
+          "properties": {
+            "status": { "$ref": "#/$defs/dispatchStatus" },
+            "method": { "$ref": "#/$defs/actionMethod" },
+            "fallbackUsed": { "type": "boolean", "default": false },
+            "fallbackType": { "enum": ["VISION_COORDINATE", "GESTURE", null], "default": null }
+          }
+        },
+        "target": {
+          "type": "object",
+          "description": "Human-readable identity of the acted node.",
+          "properties": {
+            "role": { "$ref": "msm:common.schema.json#/$defs/role" },
+            "label": { "type": ["string", "null"] }
+          }
+        },
+        "mutationClass": {
+          "enum": ["READ_ONLY", "REVERSIBLE", "SIDE_EFFECT", "EXTERNAL_SIDE_EFFECT", "DESTRUCTIVE"],
+          "description": "Advisory, payload-derived classification of how mutating this specific action was. Metadata for the host, not a gate."
+        },
+        "observation": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Objective measurement of how the device changed. No success semantics.",
+          "required": ["beforeSnapshotId", "stability", "screenChanged", "windowChanged"],
+          "properties": {
+            "beforeSnapshotId": { "type": "string" },
+            "afterSnapshotId": { "type": ["string", "null"] },
+            "stability": { "$ref": "#/$defs/stability" },
+            "screenChanged": { "type": "boolean", "description": "treeHash differs (UI content changed) — NOT success." },
+            "windowChanged": { "type": "boolean", "description": "window IDENTITY changed (windowId, else app/package) — never derived from treeHash." },
+            "diff": { "type": ["object", "null"], "additionalProperties": true, "description": "added/removed/moved/changed node deltas." },
+            "diffRef": { "type": ["string", "null"], "description": "beforeSnapshotId:afterSnapshotId." }
+          }
+        },
+        "verification": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Present ONLY when a predicate applies. Measures that predicate, nothing more.",
+          "required": ["predicate", "result"],
+          "properties": {
+            "predicate": {
+              "type": "object",
+              "additionalProperties": true,
+              "description": "The evaluated predicate: an intrinsic postcondition (via `policy`) or a caller-supplied condition.",
+              "properties": { "policy": { "$ref": "#/$defs/verificationPolicy" }, "source": { "enum": ["CALLER", "INTRINSIC"] } }
+            },
+            "result": { "$ref": "#/$defs/verificationResult" },
+            "evidence": { "type": "array", "items": { "type": "object", "additionalProperties": true } }
+          }
+        }
+      }
+    }
+  }
+}

package/dist/protocol/schemas/common.schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "msm:common.schema.json",
+  "title": "Common definitions",
+  "description": "Shared primitives for the Mobile Semantic MCP protocol. schemaVersion frozen at 1.",
+  "$defs": {
+    "schemaVersion": {
+      "const": 1,
+      "description": "Protocol schema version. Bump on any breaking change to any schema."
+    },
+    "deviceId": { "type": "string", "minLength": 1, "maxLength": 128 },
+    "snapshotId": {
+      "type": "string",
+      "pattern": "^s_[0-9a-zA-Z]+$",
+      "description": "Opaque snapshot id, e.g. s_1832. Valid only within its snapshot lifetime."
+    },
+    "nodeId": {
+      "type": "string",
+      "description": "Node id UNIQUE ONLY within one snapshot. Never reuse across snapshots; never click an old nodeId directly. Vision nodes use the 'vision:' prefix.",
+      "pattern": "^(n[0-9]+|vision:[0-9]+)$"
+    },
+    "timestampMs": { "type": "integer", "minimum": 0 },
+    "packageName": {
+      "type": "string",
+      "pattern": "^[a-zA-Z][a-zA-Z0-9_]*(\\.[a-zA-Z][a-zA-Z0-9_]*)+$"
+    },
+    "bundleId": {
+      "type": "string",
+      "description": "iOS bundle identifier (reverse-DNS, hyphens allowed), e.g. com.apple.Preferences.",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9-]*(\\.[A-Za-z0-9][A-Za-z0-9-]*)+$",
+      "maxLength": 255
+    },
+    "bounds": {
+      "type": "array",
+      "description": "[left, top, right, bottom] in device pixels.",
+      "items": { "type": "integer" },
+      "minItems": 4,
+      "maxItems": 4
+    },
+    "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+    "source": {
+      "enum": ["ACCESSIBILITY", "APP_SDK", "VISION"],
+      "description": "Origin of a node's data. Always reported so the AI knows semantic vs vision."
+    },
+    "role": {
+      "enum": [
+        "SCREEN", "DIALOG", "LIST", "LIST_ITEM", "BUTTON", "TEXT", "INPUT",
+        "IMAGE", "CHECKBOX", "RADIO", "SWITCH", "TAB", "MENU", "LINK",
+        "SLIDER", "PROGRESS", "WEB_VIEW", "CANVAS", "UNKNOWN"
+      ],
+      "description": "Normalized role. Raw Android class names are NEVER exposed as roles."
+    },
+    "hash": {
+      "type": "string",
+      "pattern": "^[0-9a-f]+$",
+      "description": "Lowercase hex hash (node/subtree/tree fingerprint)."
+    }
+  }
+}

package/dist/protocol/schemas/diff.schema.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "msm:diff.schema.json",
+  "title": "ScreenDiff",
+  "description": "Delta between two snapshots. 'moved' is distinguished from removed+added; tiny animation-only bounds changes are ignored when semantics are unchanged. Target typical size < 5 KB.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "fromSnapshot", "toSnapshot", "added", "removed", "moved", "changed", "screenChanged"],
+  "properties": {
+    "schemaVersion": { "$ref": "msm:common.schema.json#/$defs/schemaVersion" },
+    "fromSnapshot": { "$ref": "msm:common.schema.json#/$defs/snapshotId" },
+    "toSnapshot": { "$ref": "msm:common.schema.json#/$defs/snapshotId" },
+    "added": {
+      "type": "array",
+      "description": "Newly present nodes (full SemanticNode).",
+      "items": { "$ref": "msm:semantic-node.schema.json" }
+    },
+    "removed": {
+      "type": "array",
+      "items": { "$ref": "msm:common.schema.json#/$defs/nodeId" }
+    },
+    "moved": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["node"],
+        "properties": {
+          "node": { "$ref": "msm:common.schema.json#/$defs/nodeId" },
+          "fromBounds": { "$ref": "msm:common.schema.json#/$defs/bounds" },
+          "toBounds": { "$ref": "msm:common.schema.json#/$defs/bounds" }
+        }
+      }
+    },
+    "changed": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["node", "fields"],
+        "properties": {
+          "node": { "$ref": "msm:common.schema.json#/$defs/nodeId" },
+          "fields": {
+            "type": "object",
+            "description": "Map of fieldName -> {before, after}.",
+            "additionalProperties": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["before", "after"],
+              "properties": {
+                "before": {},
+                "after": {}
+              }
+            }
+          }
+        }
+      }
+    },
+    "focusChanged": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "description": "null = no focus on either side. Otherwise a tri-state: focus identity is resolved by stable identity across snapshots, never by raw nodeId. UNKNOWN when the old focused element cannot be resolved uniquely (no fabricated boolean).",
+      "properties": {
+        "state": { "type": "string", "enum": ["UNCHANGED", "CHANGED", "UNKNOWN"] },
+        "from": { "type": ["string", "null"] },
+        "to": { "type": ["string", "null"] }
+      }
+    },
+    "screenChanged": {
+      "type": "boolean",
+      "description": "true when screenStateId/treeHash indicates a materially different screen."
+    }
+  }
+}

package/dist/protocol/schemas/error.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "msm:error.schema.json",
+  "title": "Error",
+  "description": "Uniform error envelope. Every error carries a recovery hint list.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["error", "message", "recovery"],
+  "properties": {
+    "error": { "$ref": "#/$defs/code" },
+    "message": { "type": "string" },
+    "recovery": {
+      "type": "array",
+      "description": "Ordered, human/AI-actionable recovery suggestions.",
+      "items": { "type": "string" }
+    },
+    "candidates": {
+      "type": "array",
+      "description": "For AMBIGUOUS_MATCH: the competing NodeRefs so the caller can disambiguate.",
+      "items": { "$ref": "msm:node-ref.schema.json" }
+    }
+  },
+  "$defs": {
+    "code": {
+      "enum": [
+        "DEVICE_OFFLINE", "SESSION_EXPIRED", "PERMISSION_REQUIRED", "WINDOW_UNAVAILABLE",
+        "SECURE_WINDOW", "NODE_NOT_FOUND", "AMBIGUOUS_MATCH", "STALE_NODE_REF",
+        "WEAK_REFERENCE_UNRESOLVABLE",
+        "ACTION_UNSUPPORTED", "ACTION_REJECTED", "NO_EFFECT", "VERIFY_TIMEOUT",
+        "VISION_REQUIRED", "POLICY_BLOCKED", "USER_CONFIRMATION_REQUIRED"
+      ]
+    }
+  }
+}

package/dist/protocol/schemas/node-ref.schema.json

@@ -0,0 +1,100 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "msm:node-ref.schema.json",
+  "title": "NodeRef",
+  "description": "A re-resolvable reference to a node. Actions take a NodeRef, never a bare nodeId. Before every action the runtime fetches the newest snapshot and re-resolves: 0 match=NODE_NOT_FOUND, >1=AMBIGUOUS_MATCH, 1 with far fingerprint=STALE_NODE_REF, 1 valid=perform. Never auto-pick the first of many.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["snapshotId", "nodeId", "fingerprint", "locators"],
+  "properties": {
+    "snapshotId": { "$ref": "msm:common.schema.json#/$defs/snapshotId" },
+    "nodeId": { "$ref": "msm:common.schema.json#/$defs/nodeId" },
+    "fingerprint": {
+      "$ref": "msm:common.schema.json#/$defs/hash",
+      "description": "Node attribute hash captured at ref creation; large drift on re-resolve => STALE_NODE_REF."
+    },
+    "ancestorFingerprint": {
+      "$ref": "msm:common.schema.json#/$defs/hash",
+      "description": "OPTIONAL (added N=1 migration window). Fingerprint of the node's ancestor chain; lets the runtime distinguish a moved/duplicated node from the intended one before acting. Absent on N-1 refs => decode still valid, no ancestor cross-check."
+    },
+    "source": {
+      "type": "string",
+      "enum": ["SEMANTIC", "VISION", "COORDINATE"],
+      "description": "OPTIONAL. Provenance of this ref. Absent => SEMANTIC (back-compat)."
+    },
+    "confidence": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1,
+      "description": "OPTIONAL. Resolver confidence at ref creation. Absent => 1 (back-compat)."
+    },
+    "locators": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Ordered by strength; resolver tries strongest first.",
+      "items": { "$ref": "#/$defs/locator" }
+    }
+  },
+  "$defs": {
+    "locator": {
+      "type": "object",
+      "required": ["type"],
+      "oneOf": [
+        {
+          "properties": {
+            "type": { "const": "RESOURCE_ID" },
+            "value": { "type": "string" }
+          },
+          "required": ["type", "value"],
+          "additionalProperties": false
+        },
+        {
+          "properties": {
+            "type": { "const": "RESOURCE_ID_SCOPED" },
+            "value": { "type": "string" },
+            "windowId": { "type": "integer" },
+            "ancestor": { "type": "string" }
+          },
+          "required": ["type", "value"],
+          "additionalProperties": false
+        },
+        {
+          "properties": {
+            "type": { "const": "ROLE_LABEL_ANCESTOR" },
+            "role": { "$ref": "msm:common.schema.json#/$defs/role" },
+            "label": { "type": "string" },
+            "ancestor": { "type": ["string", "null"] }
+          },
+          "required": ["type", "role", "label"],
+          "additionalProperties": false
+        },
+        {
+          "properties": {
+            "type": { "const": "ROLE_STATE_COLLECTION_ITEM" },
+            "role": { "$ref": "msm:common.schema.json#/$defs/role" },
+            "itemKey": { "type": "string" },
+            "scrollContainer": { "type": ["string", "null"] }
+          },
+          "required": ["type", "role", "itemKey"],
+          "additionalProperties": false
+        },
+        {
+          "properties": {
+            "type": { "const": "STRUCTURAL_PATH" },
+            "value": { "type": "string", "description": "e.g. '0/2/1' child-index path from root." }
+          },
+          "required": ["type", "value"],
+          "additionalProperties": false
+        },
+        {
+          "properties": {
+            "type": { "const": "BOUNDS_NEAREST" },
+            "bounds": { "$ref": "msm:common.schema.json#/$defs/bounds" }
+          },
+          "required": ["type", "bounds"],
+          "additionalProperties": false
+        }
+      ]
+    }
+  }
+}

package/dist/protocol/schemas/query.schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "msm:query.schema.json",
+  "title": "SemanticQuery",
+  "description": "Declarative node query. Result always reports match count, NodeRef(s), match reason, confidence, and other candidates when ambiguous.",
+  "type": "object",
+  "additionalProperties": false,
+  "minProperties": 1,
+  "properties": {
+    "role": { "$ref": "msm:common.schema.json#/$defs/role" },
+    "text": { "$ref": "#/$defs/textMatch" },
+    "label": { "$ref": "#/$defs/textMatch" },
+    "resourceId": { "type": "string" },
+    "state": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "clickable": { "type": "boolean" },
+        "checked": { "type": "boolean" },
+        "selected": { "type": "boolean" },
+        "focused": { "type": "boolean" }
+      }
+    },
+    "within": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Restrict to descendants of a matching ancestor.",
+      "properties": {
+        "role": { "$ref": "msm:common.schema.json#/$defs/role" },
+        "text": { "$ref": "#/$defs/textMatch" },
+        "resourceId": { "type": "string" }
+      }
+    },
+    "firstVisible": { "type": "boolean", "description": "Return only the first on-screen match." },
+    "nth": { "type": "integer", "minimum": 0, "description": "Zero-based index among ordered matches." }
+  },
+  "$defs": {
+    "textMatch": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["value"],
+      "properties": {
+        "value": { "type": "string" },
+        "match": {
+          "enum": ["EXACT", "NORMALIZED_EXACT", "CONTAINS", "REGEX", "SEMANTIC_SYNONYM"],
+          "default": "NORMALIZED_EXACT",
+          "description": "REGEX is length/complexity limited. SEMANTIC_SYNONYM is opt-in only."
+        }
+      }
+    }
+  }
+}

package/dist/protocol/schemas/screen-snapshot.schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "msm:screen-snapshot.schema.json",
+  "title": "ScreenSnapshot",
+  "description": "A point-in-time semantic capture of the foreground window(s). May be full or compact.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion", "deviceId", "snapshotId", "timestamp",
+    "packageName", "windowId", "orientation", "screenStateId", "compact", "nodes", "treeHash"
+  ],
+  "properties": {
+    "schemaVersion": { "$ref": "msm:common.schema.json#/$defs/schemaVersion" },
+    "deviceId": { "$ref": "msm:common.schema.json#/$defs/deviceId" },
+    "snapshotId": { "$ref": "msm:common.schema.json#/$defs/snapshotId" },
+    "timestamp": { "$ref": "msm:common.schema.json#/$defs/timestampMs" },
+    "packageName": { "$ref": "msm:common.schema.json#/$defs/packageName" },
+    "windowId": { "type": "integer" },
+    "orientation": { "enum": ["portrait", "landscape"] },
+    "screenStateId": {
+      "type": "string",
+      "description": "Coarse screen identity, e.g. 'login:a91f' — role+structure hash. Used to detect same-screen."
+    },
+    "compact": {
+      "type": "boolean",
+      "description": "true => pruned to actionable/meaningful nodes (target < 30 KB). false => full raw tree."
+    },
+    "truncated": {
+      "type": "boolean",
+      "default": false,
+      "description": "true when node set was capped by a token/size budget."
+    },
+    "nodes": {
+      "type": "array",
+      "items": { "$ref": "msm:semantic-node.schema.json" }
+    },
+    "treeHash": {
+      "$ref": "msm:common.schema.json#/$defs/hash",
+      "description": "Hash of the whole tree; equal treeHash => identical semantic screen."
+    },
+    "platform": {
+      "enum": ["ANDROID", "IOS"],
+      "description": "Originating platform. Optional for back-compat; absent => ANDROID. iOS snapshots set IOS."
+    },
+    "appId": {
+      "type": ["string", "null"],
+      "description": "Platform-neutral foreground app id: Android package name, iOS bundle identifier. Mirrors packageName (the legacy Android alias)."
+    }
+  }
+}

package/dist/protocol/schemas/semantic-node.schema.json

@@ -0,0 +1,95 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "msm:semantic-node.schema.json",
+  "title": "SemanticNode",
+  "description": "One normalized node in a ScreenSnapshot. nodeId is valid only within its snapshot. Wire economy: fields carrying their default value are OMITTED (state defaults, empty actions, source=ACCESSIBILITY, confidence=1). A reader MUST apply the documented default when a field is absent; absence never means unknown. Relaxing these from required is backward compatible — a payload that spells every field out still validates.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["nodeId", "role"],
+  "properties": {
+    "nodeId": { "$ref": "msm:common.schema.json#/$defs/nodeId" },
+    "parentId": {
+      "oneOf": [
+        { "$ref": "msm:common.schema.json#/$defs/nodeId" },
+        { "type": "null" }
+      ],
+      "description": "Parent nodeId, or null for the snapshot root."
+    },
+    "role": { "$ref": "msm:common.schema.json#/$defs/role" },
+    "label": {
+      "type": ["string", "null"],
+      "description": "Best human label: contentDescription, or accessible name."
+    },
+    "text": { "type": ["string", "null"], "description": "Visible text content." },
+    "value": {
+      "type": ["string", "null"],
+      "description": "Current value (e.g. INPUT text, SLIDER position). NOT the same as text."
+    },
+    "hint": { "type": ["string", "null"], "description": "Placeholder / hint text." },
+    "resourceId": {
+      "type": ["string", "null"],
+      "description": "LEGACY Android locator alias (== automationId on Android). e.g. com.example.app:id/login. Strongest cheap locator when unique."
+    },
+    "className": {
+      "type": ["string", "null"],
+      "description": "Raw Android class, kept only for disambiguation; omitted from compact snapshot when not needed."
+    },
+    "automationId": {
+      "type": ["string", "null"],
+      "description": "Platform-neutral stable identifier: Android resource-id, iOS accessibilityIdentifier. Preferred cheap locator; resourceId is the Android alias."
+    },
+    "nativeType": {
+      "type": ["string", "null"],
+      "description": "Raw platform element type for disambiguation only, e.g. XCUIElementTypeButton on iOS (className is the Android equivalent)."
+    },
+    "state": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Omitted entirely when every field is at its default. Defaults: enabled=true, everything else false, checked=null.",
+      "properties": {
+        "enabled": { "type": "boolean", "default": true },
+        "clickable": { "type": "boolean", "default": false },
+        "focused": { "type": "boolean", "default": false },
+        "selected": { "type": "boolean", "default": false },
+        "checked": { "type": ["boolean", "null"], "description": "null when not a checkable node." },
+        "password": { "type": "boolean", "default": false, "description": "true => value is redacted before leaving device." }
+      }
+    },
+    "actions": {
+      "type": "array",
+      "default": [],
+      "description": "Actions this node supports (subset of the action verb set). Omitted when empty.",
+      "items": { "type": "string" },
+      "uniqueItems": true
+    },
+    "bounds": {
+      "oneOf": [
+        { "$ref": "msm:common.schema.json#/$defs/bounds" },
+        { "type": "null" }
+      ],
+      "description": "Omitted from compact snapshot when a strong locator exists."
+    },
+    "collection": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "description": "Present on LIST_ITEM / collection children. Index is never sole identity (views recycle).",
+      "properties": {
+        "index": { "type": "integer", "minimum": 0 },
+        "itemKey": { "type": ["string", "null"], "description": "Stable item key/text used as identity." },
+        "rowCount": { "type": ["integer", "null"] },
+        "scrollContainerId": { "$ref": "msm:common.schema.json#/$defs/nodeId" },
+        "ancestorFingerprint": { "$ref": "msm:common.schema.json#/$defs/hash" }
+      }
+    },
+    "source": {
+      "allOf": [{ "$ref": "msm:common.schema.json#/$defs/source" }],
+      "default": "ACCESSIBILITY",
+      "description": "Omitted when ACCESSIBILITY. A VISION node always states source and confidence explicitly."
+    },
+    "confidence": {
+      "allOf": [{ "$ref": "msm:common.schema.json#/$defs/confidence" }],
+      "default": 1,
+      "description": "Omitted when 1."
+    }
+  }
+}