sentience-ts 0.10.3

package/spec/snapshot.schema.json

@@ -0,0 +1,148 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Sentience Snapshot Schema v1",
+  "description": "Single source of truth for snapshot data structure between extension and SDKs",
+  "version": "1.0.0",
+  "type": "object",
+  "required": ["status", "url", "elements"],
+  "properties": {
+    "status": {
+      "type": "string",
+      "enum": ["success", "error"],
+      "description": "Operation status"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of snapshot"
+    },
+    "url": {
+      "type": "string",
+      "format": "uri",
+      "description": "Current page URL"
+    },
+    "viewport": {
+      "type": "object",
+      "required": ["width", "height"],
+      "properties": {
+        "width": {
+          "type": "number",
+          "description": "Viewport width in pixels"
+        },
+        "height": {
+          "type": "number",
+          "description": "Viewport height in pixels"
+        }
+      }
+    },
+    "elements": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/Element"
+      },
+      "description": "Array of analyzed elements, sorted by importance (descending)"
+    },
+    "screenshot": {
+      "type": "string",
+      "description": "Base64-encoded screenshot data URL (optional)",
+      "pattern": "^data:image/(png|jpeg);base64,"
+    },
+    "screenshot_format": {
+      "type": "string",
+      "enum": ["png", "jpeg"],
+      "description": "Screenshot format (optional)"
+    },
+    "error": {
+      "type": "string",
+      "description": "Error message if status is 'error'"
+    },
+    "requires_license": {
+      "type": "boolean",
+      "description": "True if operation requires license key (headless mode)"
+    }
+  },
+  "definitions": {
+    "Element": {
+      "type": "object",
+      "required": ["id", "role", "importance", "bbox", "visual_cues"],
+      "properties": {
+        "id": {
+          "type": "integer",
+          "description": "Unique element identifier (index in registry)"
+        },
+        "role": {
+          "type": "string",
+          "enum": ["button", "link", "textbox", "searchbox", "checkbox", "radio", "combobox", "image", "generic"],
+          "description": "Semantic role of the element"
+        },
+        "text": {
+          "type": ["string", "null"],
+          "description": "Text content, aria-label, or placeholder (max 100 chars)"
+        },
+        "importance": {
+          "type": "integer",
+          "description": "Importance score (-300 to ~1800), higher = more important"
+        },
+        "bbox": {
+          "$ref": "#/definitions/BBox"
+        },
+        "visual_cues": {
+          "$ref": "#/definitions/VisualCues"
+        },
+        "in_viewport": {
+          "type": "boolean",
+          "description": "True if element is visible in viewport"
+        },
+        "is_occluded": {
+          "type": "boolean",
+          "description": "True if element is covered by another element"
+        },
+        "z_index": {
+          "type": "integer",
+          "description": "CSS z-index value (0 if auto or not set)"
+        }
+      }
+    },
+    "BBox": {
+      "type": "object",
+      "required": ["x", "y", "width", "height"],
+      "properties": {
+        "x": {
+          "type": "number",
+          "description": "X coordinate (left edge) in pixels"
+        },
+        "y": {
+          "type": "number",
+          "description": "Y coordinate (top edge) in pixels"
+        },
+        "width": {
+          "type": "number",
+          "description": "Width in pixels"
+        },
+        "height": {
+          "type": "number",
+          "description": "Height in pixels"
+        }
+      }
+    },
+    "VisualCues": {
+      "type": "object",
+      "required": ["is_primary", "is_clickable"],
+      "properties": {
+        "is_primary": {
+          "type": "boolean",
+          "description": "True if element is visually prominent primary action"
+        },
+        "background_color_name": {
+          "type": ["string", "null"],
+          "description": "Nearest named color from 32-color palette (e.g., 'blue', 'red')"
+        },
+        "is_clickable": {
+          "type": "boolean",
+          "description": "True if element has pointer cursor or actionable role"
+        }
+      }
+    }
+  }
+}
+