sentienceapi 0.90.1

package/dist/types.d.ts

@@ -0,0 +1,110 @@
+/**
+ * TypeScript type definitions - matches spec/sdk-types.md
+ */
+export interface BBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface Viewport {
+    width: number;
+    height: number;
+}
+export interface VisualCues {
+    is_primary: boolean;
+    background_color_name: string | null;
+    is_clickable: boolean;
+}
+export interface Element {
+    id: number;
+    role: string;
+    text: string | null;
+    importance: number;
+    bbox: BBox;
+    visual_cues: VisualCues;
+    in_viewport: boolean;
+    is_occluded: boolean;
+    z_index: number;
+}
+export interface Snapshot {
+    status: "success" | "error";
+    timestamp?: string;
+    url: string;
+    viewport?: Viewport;
+    elements: Element[];
+    screenshot?: string;
+    screenshot_format?: "png" | "jpeg";
+    error?: string;
+    requires_license?: boolean;
+}
+export interface ActionResult {
+    success: boolean;
+    duration_ms: number;
+    outcome?: "navigated" | "dom_updated" | "no_change" | "error";
+    url_changed?: boolean;
+    snapshot_after?: Snapshot;
+    error?: {
+        code: string;
+        reason: string;
+        recovery_hint?: string;
+    };
+}
+export interface WaitResult {
+    found: boolean;
+    element?: Element;
+    duration_ms: number;
+    timeout: boolean;
+}
+export interface QuerySelectorObject {
+    role?: string;
+    text?: string;
+    name?: string;
+    clickable?: boolean;
+    isPrimary?: boolean;
+    importance?: number | {
+        min?: number;
+        max?: number;
+    };
+}
+export type QuerySelector = string | QuerySelectorObject;
+/**
+ * Cookie definition for storage state injection.
+ * Matches Playwright's cookie format for storage_state.
+ */
+export interface Cookie {
+    name: string;
+    value: string;
+    domain: string;
+    path?: string;
+    expires?: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: "Strict" | "Lax" | "None";
+}
+/**
+ * LocalStorage item for a specific origin.
+ * Playwright stores localStorage as an array of {name, value} objects.
+ */
+export interface LocalStorageItem {
+    name: string;
+    value: string;
+}
+/**
+ * Storage state for a specific origin (localStorage).
+ * Represents localStorage data for a single domain.
+ */
+export interface OriginStorage {
+    origin: string;
+    localStorage: LocalStorageItem[];
+}
+/**
+ * Complete browser storage state (cookies + localStorage).
+ * This is the format used by Playwright's storage_state() method.
+ * Can be saved to/loaded from JSON files for session injection.
+ */
+export interface StorageState {
+    cookies: Cookie[];
+    origins: OriginStorage[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * TypeScript type definitions - matches spec/sdk-types.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;GAEG"}

package/dist/utils.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Utility functions for Sentience SDK
+ */
+import { BrowserContext } from 'playwright';
+/**
+ * Save current browser storage state (cookies + localStorage) to a file.
+ *
+ * This is useful for capturing a logged-in session to reuse later.
+ *
+ * @param context - Playwright BrowserContext
+ * @param filePath - Path to save the storage state JSON file
+ *
+ * @example
+ * ```typescript
+ * import { SentienceBrowser, saveStorageState } from 'sentience-ts';
+ *
+ * const browser = new SentienceBrowser();
+ * await browser.start();
+ *
+ * // User logs in manually or via agent
+ * await browser.getPage().goto('https://example.com');
+ * // ... login happens ...
+ *
+ * // Save session for later
+ * await saveStorageState(browser.getContext(), 'auth.json');
+ * ```
+ */
+export declare function saveStorageState(context: BrowserContext, filePath: string): Promise<void>;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAI5C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAQf"}

package/dist/utils.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Utility functions for Sentience SDK
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.saveStorageState = saveStorageState;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Save current browser storage state (cookies + localStorage) to a file.
+ *
+ * This is useful for capturing a logged-in session to reuse later.
+ *
+ * @param context - Playwright BrowserContext
+ * @param filePath - Path to save the storage state JSON file
+ *
+ * @example
+ * ```typescript
+ * import { SentienceBrowser, saveStorageState } from 'sentience-ts';
+ *
+ * const browser = new SentienceBrowser();
+ * await browser.start();
+ *
+ * // User logs in manually or via agent
+ * await browser.getPage().goto('https://example.com');
+ * // ... login happens ...
+ *
+ * // Save session for later
+ * await saveStorageState(browser.getContext(), 'auth.json');
+ * ```
+ */
+async function saveStorageState(context, filePath) {
+    const storageState = await context.storageState();
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(filePath, JSON.stringify(storageState, null, 2));
+    console.log(`✅ [Sentience] Saved storage state to ${filePath}`);
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":";AAAA;;GAEG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BH,4CAWC;AArCD,uCAAyB;AACzB,2CAA6B;AAE7B;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACI,KAAK,UAAU,gBAAgB,CACpC,OAAuB,EACvB,QAAgB;IAEhB,MAAM,YAAY,GAAG,MAAM,OAAO,CAAC,YAAY,EAAE,CAAC;IAClD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACnC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACxB,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACzC,CAAC;IACD,EAAE,CAAC,aAAa,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAClE,OAAO,CAAC,GAAG,CAAC,wCAAwC,QAAQ,EAAE,CAAC,CAAC;AAClE,CAAC"}

package/dist/wait.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Wait functionality
+ */
+import { SentienceBrowser } from './browser';
+import { WaitResult, QuerySelector } from './types';
+/**
+ * Wait for element matching selector to appear
+ *
+ * @param browser - SentienceBrowser instance
+ * @param selector - String DSL or dict query
+ * @param timeout - Maximum time to wait (milliseconds). Default: 10000ms (10 seconds)
+ * @param interval - Polling interval (milliseconds). If undefined, auto-detects:
+ *                   - 250ms for local extension (useApi=false, fast)
+ *                   - 1500ms for remote API (useApi=true or default, network latency)
+ * @param useApi - Force use of server-side API if true, local extension if false.
+ *                 If undefined, uses API if apiKey is set, otherwise uses local extension.
+ * @returns WaitResult
+ */
+export declare function waitFor(browser: SentienceBrowser, selector: QuerySelector, timeout?: number, interval?: number, useApi?: boolean): Promise<WaitResult>;
+//# sourceMappingURL=wait.d.ts.map

package/dist/wait.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait.d.ts","sourceRoot":"","sources":["../src/wait.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAW,aAAa,EAAE,MAAM,SAAS,CAAC;AAI7D;;;;;;;;;;;;GAYG;AACH,wBAAsB,OAAO,CAC3B,OAAO,EAAE,gBAAgB,EACzB,QAAQ,EAAE,aAAa,EACvB,OAAO,GAAE,MAAc,EACvB,QAAQ,CAAC,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,OAAO,GACf,OAAO,CAAC,UAAU,CAAC,CA6CrB"}

package/dist/wait.js

@@ -0,0 +1,63 @@
+"use strict";
+/**
+ * Wait functionality
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.waitFor = waitFor;
+const snapshot_1 = require("./snapshot");
+const query_1 = require("./query");
+/**
+ * Wait for element matching selector to appear
+ *
+ * @param browser - SentienceBrowser instance
+ * @param selector - String DSL or dict query
+ * @param timeout - Maximum time to wait (milliseconds). Default: 10000ms (10 seconds)
+ * @param interval - Polling interval (milliseconds). If undefined, auto-detects:
+ *                   - 250ms for local extension (useApi=false, fast)
+ *                   - 1500ms for remote API (useApi=true or default, network latency)
+ * @param useApi - Force use of server-side API if true, local extension if false.
+ *                 If undefined, uses API if apiKey is set, otherwise uses local extension.
+ * @returns WaitResult
+ */
+async function waitFor(browser, selector, timeout = 10000, interval, useApi) {
+    // Auto-detect optimal interval based on API usage
+    if (interval === undefined) {
+        // Determine if using API
+        const willUseApi = useApi !== undefined
+            ? useApi
+            : (browser.getApiKey() !== undefined);
+        if (willUseApi) {
+            interval = 1500; // Longer interval for API calls (network latency)
+        }
+        else {
+            interval = 250; // Shorter interval for local extension (fast)
+        }
+    }
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeout) {
+        // Take snapshot (may be local extension or remote API)
+        const snap = await (0, snapshot_1.snapshot)(browser, { use_api: useApi });
+        // Try to find element
+        const element = (0, query_1.find)(snap, selector);
+        if (element) {
+            const durationMs = Date.now() - startTime;
+            return {
+                found: true,
+                element,
+                duration_ms: durationMs,
+                timeout: false,
+            };
+        }
+        // Wait before next poll
+        await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+    // Timeout
+    const durationMs = Date.now() - startTime;
+    return {
+        found: false,
+        element: undefined,
+        duration_ms: durationMs,
+        timeout: true,
+    };
+}
+//# sourceMappingURL=wait.js.map

package/dist/wait.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait.js","sourceRoot":"","sources":["../src/wait.ts"],"names":[],"mappings":";AAAA;;GAEG;;AAoBH,0BAmDC;AAnED,yCAAsC;AACtC,mCAA+B;AAE/B;;;;;;;;;;;;GAYG;AACI,KAAK,UAAU,OAAO,CAC3B,OAAyB,EACzB,QAAuB,EACvB,UAAkB,KAAK,EACvB,QAAiB,EACjB,MAAgB;IAEhB,kDAAkD;IAClD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,yBAAyB;QACzB,MAAM,UAAU,GAAG,MAAM,KAAK,SAAS;YACrC,CAAC,CAAC,MAAM;YACR,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,KAAK,SAAS,CAAC,CAAC;QACxC,IAAI,UAAU,EAAE,CAAC;YACf,QAAQ,GAAG,IAAI,CAAC,CAAC,kDAAkD;QACrE,CAAC;aAAM,CAAC;YACN,QAAQ,GAAG,GAAG,CAAC,CAAC,8CAA8C;QAChE,CAAC;IACH,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAE7B,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,GAAG,OAAO,EAAE,CAAC;QACxC,uDAAuD;QACvD,MAAM,IAAI,GAAG,MAAM,IAAA,mBAAQ,EAAC,OAAO,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;QAE1D,sBAAsB;QACtB,MAAM,OAAO,GAAG,IAAA,YAAI,EAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAErC,IAAI,OAAO,EAAE,CAAC;YACZ,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;YAC1C,OAAO;gBACL,KAAK,EAAE,IAAI;gBACX,OAAO;gBACP,WAAW,EAAE,UAAU;gBACvB,OAAO,EAAE,KAAK;aACf,CAAC;QACJ,CAAC;QAED,wBAAwB;QACxB,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;IAChE,CAAC;IAED,UAAU;IACV,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;IAC1C,OAAO;QACL,KAAK,EAAE,KAAK;QACZ,OAAO,EAAE,SAAS;QAClB,WAAW,EAAE,UAAU;QACvB,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "sentienceapi",
+  "version": "0.90.1",
+  "description": "TypeScript SDK for Sentience AI Agent Browser Automation",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm test && npm run build",
+    "example:hello": "ts-node examples/hello.ts",
+    "example:basic": "ts-node examples/basic-agent.ts",
+    "example:agent-google": "ts-node examples/agent-google-search.ts",
+    "example:agent-amazon": "ts-node examples/agent-amazon-shopping.ts",
+    "example:agent-claude": "ts-node examples/agent-with-anthropic.ts",
+    "example:conversational-google": "ts-node examples/conversational-google-search.ts",
+    "example:conversational-amazon": "ts-node examples/conversational-amazon-shopping.ts",
+    "example:tracing": "ts-node examples/agent-with-tracing.ts",
+    "example:trace-replay": "ts-node examples/trace-replay-demo.ts",
+    "example:cloud-tracing": "ts-node examples/cloud-tracing-agent.ts",
+    "cli": "ts-node src/cli.ts"
+  },
+  "bin": {
+    "sentience": "./dist/cli.js"
+  },
+  "dependencies": {
+    "playwright": "^1.40.0",
+    "turndown": "^7.2.2",
+    "uuid": "^9.0.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "@types/node": "^20.0.0",
+    "@types/turndown": "^5.0.3",
+    "@types/uuid": "^9.0.0",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.0.0"
+  },
+  "optionalDependencies": {
+    "openai": "^4.0.0",
+    "@anthropic-ai/sdk": "^0.20.0"
+  },
+  "files": [
+    "dist",
+    "spec",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "browser-automation",
+    "playwright",
+    "ai-agent",
+    "web-automation",
+    "sentience"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SentienceAPI/sentience-ts.git"
+  },
+  "bugs": {
+    "url": "https://github.com/SentienceAPI/sentience-ts/issues"
+  },
+  "homepage": "https://github.com/SentienceAPI/sentience-ts#readme",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/spec/README.md

@@ -0,0 +1,72 @@
+# Sentience API Specification
+
+This directory contains the **single source of truth** for the API contract between the Chrome extension and SDKs.
+
+## Files
+
+- **`snapshot.schema.json`** - JSON Schema for snapshot response validation
+- **`SNAPSHOT_V1.md`** - Human-readable snapshot API contract
+- **`sdk-types.md`** - SDK-level type definitions (ActionResult, WaitResult, TraceStep)
+
+## Purpose
+
+These specifications ensure:
+1. **Consistency**: Both Python and TypeScript SDKs implement the same contract
+2. **Validation**: SDKs can validate extension responses
+3. **Type Safety**: Strong typing in both languages
+4. **Documentation**: Clear reference for developers
+
+## Usage
+
+### For SDK Developers
+
+1. **Read** `SNAPSHOT_V1.md` for human-readable contract
+2. **Use** `snapshot.schema.json` for JSON Schema validation
+3. **Reference** `sdk-types.md` for SDK-level types
+
+### For Extension Developers
+
+1. **Ensure** extension output matches `snapshot.schema.json`
+2. **Update** schema when adding new fields
+3. **Version** schema for breaking changes
+
+## Versioning
+
+- **v1.0.0**: Initial stable version (Day 1)
+- Future versions: Increment major version for breaking changes
+- SDKs should validate version and handle compatibility
+
+## Validation
+
+Both SDKs should validate extension responses:
+
+**Python**:
+```python
+import jsonschema
+from spec.snapshot.schema import load_schema
+
+schema = load_schema()
+jsonschema.validate(snapshot_data, schema)
+```
+
+**TypeScript**:
+```typescript
+import Ajv from 'ajv';
+import schema from './spec/snapshot.schema.json';
+
+const ajv = new Ajv();
+const validate = ajv.compile(schema);
+validate(snapshot_data);
+```
+
+## Testing
+
+- Validate against real extension output
+- Test with edge cases (empty pages, many elements, errors)
+- Verify type coercion and defaults
+
+---
+
+**Last Updated**: Day 1 Implementation  
+**Status**: ✅ Stable
+

package/spec/SNAPSHOT_V1.md

@@ -0,0 +1,208 @@
+# Sentience Snapshot API Contract v1
+
+**Version**: 1.0.0  
+**Last Updated**: [Current Date]  
+**Status**: Stable
+
+This document defines the **single source of truth** for the snapshot data structure returned by `window.sentience.snapshot()`. Both Python and TypeScript SDKs must implement this contract exactly.
+
+## Overview
+
+The snapshot API returns a structured representation of the current page state, including:
+- All interactive elements with semantic roles
+- Element positions (bounding boxes)
+- Importance scores (AI-optimized ranking)
+- Visual cues (primary actions, colors, clickability)
+- Optional screenshot
+
+## Response Structure
+
+### Top-Level Object
+
+```typescript
+{
+  status: "success" | "error",
+  timestamp?: string,           // ISO 8601
+  url: string,
+  viewport?: { width: number, height: number },
+  elements: Element[],
+  screenshot?: string,          // Base64 data URL
+  screenshot_format?: "png" | "jpeg",
+  error?: string,              // If status is "error"
+  requires_license?: boolean   // If license required
+}
+```
+
+### Element Object
+
+```typescript
+{
+  id: number,                  // REQUIRED: Unique identifier (registry index)
+  role: string,                // REQUIRED: Semantic role
+  text: string | null,         // Text content, aria-label, or placeholder
+  importance: number,          // REQUIRED: Importance score (-300 to ~1800)
+  bbox: BBox,                  // REQUIRED: Bounding box
+  visual_cues: VisualCues,     // REQUIRED: Visual analysis
+  in_viewport: boolean,        // Is element visible in viewport
+  is_occluded: boolean,        // Is element covered by overlay
+  z_index: number              // CSS z-index (0 if auto)
+}
+```
+
+### BBox (Bounding Box)
+
+```typescript
+{
+  x: number,       // Left edge in pixels
+  y: number,       // Top edge in pixels
+  width: number,   // Width in pixels
+  height: number   // Height in pixels
+}
+```
+
+### VisualCues
+
+```typescript
+{
+  is_primary: boolean,                    // Visually prominent primary action
+  background_color_name: string | null,   // Named color from palette
+  is_clickable: boolean                   // Has pointer cursor or actionable role
+}
+```
+
+## Field Details
+
+### `id` (required)
+- **Type**: `integer`
+- **Description**: Unique element identifier, corresponds to index in `window.sentience_registry`
+- **Usage**: Used for actions like `click(id)`
+- **Stability**: May change between page loads (not persistent)
+
+### `role` (required)
+- **Type**: `string`
+- **Values**: `"button"`, `"link"`, `"textbox"`, `"searchbox"`, `"checkbox"`, `"radio"`, `"combobox"`, `"image"`, `"generic"`
+- **Description**: Semantic role inferred from HTML tag, ARIA attributes, and context
+- **Usage**: Primary filter for query engine
+
+### `text` (optional)
+- **Type**: `string | null`
+- **Description**: Text content extracted from element:
+  - `aria-label` if present
+  - `value` or `placeholder` for inputs
+  - `alt` for images
+  - `innerText` for other elements (truncated to 100 chars)
+- **Usage**: Text matching in query engine
+
+### `importance` (required)
+- **Type**: `integer`
+- **Range**: -300 to ~1800
+- **Description**: AI-optimized importance score calculated from:
+  - Role priority (inputs: 1000, buttons: 500, links: 100)
+  - Area score (larger elements score higher, capped at 200)
+  - Visual prominence (+200 for primary actions)
+  - Viewport/occlusion penalties (-500 off-screen, -800 occluded)
+- **Usage**: Ranking and filtering elements
+
+### `bbox` (required)
+- **Type**: `BBox` object
+- **Description**: Element position and size in viewport coordinates
+- **Coordinates**: Relative to viewport (0,0) at top-left
+- **Usage**: Spatial queries, visual grounding, click coordinates
+
+### `visual_cues` (required)
+- **Type**: `VisualCues` object
+- **Description**: Visual analysis results
+- **Fields**:
+  - `is_primary`: True if element is visually prominent primary action
+  - `background_color_name`: Nearest named color (32-color palette) or null
+  - `is_clickable`: True if element has pointer cursor or actionable role
+
+### `in_viewport` (optional)
+- **Type**: `boolean`
+- **Description**: True if element is visible in current viewport
+- **Default**: `true` (if not present, assume visible)
+
+### `is_occluded` (optional)
+- **Type**: `boolean`
+- **Description**: True if element is covered by another element
+- **Default**: `false` (if not present, assume not occluded)
+
+### `z_index` (optional)
+- **Type**: `integer`
+- **Description**: CSS z-index value (0 if "auto" or not set)
+- **Default**: `0`
+
+## Element Sorting
+
+Elements in the `elements` array are sorted by:
+1. **Primary sort**: `importance` (descending) - most important first
+2. **Secondary sort**: `bbox.y` (ascending) - top-to-bottom reading order (if limit applied)
+
+## Example Response
+
+```json
+{
+  "status": "success",
+  "timestamp": "2025-01-20T10:30:00Z",
+  "url": "https://example.com",
+  "viewport": {
+    "width": 1280,
+    "height": 800
+  },
+  "elements": [
+    {
+      "id": 42,
+      "role": "button",
+      "text": "Sign In",
+      "importance": 850,
+      "bbox": {
+        "x": 100,
+        "y": 200,
+        "width": 120,
+        "height": 40
+      },
+      "visual_cues": {
+        "is_primary": true,
+        "background_color_name": "blue",
+        "is_clickable": true
+      },
+      "in_viewport": true,
+      "is_occluded": false,
+      "z_index": 0
+    }
+  ]
+}
+```
+
+## Error Response
+
+```json
+{
+  "status": "error",
+  "error": "Headless mode requires a valid license key...",
+  "requires_license": true
+}
+```
+
+## SDK Implementation Requirements
+
+Both Python and TypeScript SDKs must:
+
+1. **Validate** snapshot response against this schema
+2. **Parse** all required fields correctly
+3. **Handle** optional fields gracefully (defaults)
+4. **Type-check** all fields (Pydantic for Python, TypeScript types for TS)
+5. **Preserve** field names exactly (no renaming)
+
+## Versioning
+
+- **v1.0.0**: Initial stable version
+- Future versions will increment major version for breaking changes
+- SDKs should validate version and handle compatibility
+
+## Related Documents
+
+- `snapshot.schema.json` - JSON Schema validation
+- Extension implementation: `sentience-chrome/injected_api.js`
+- WASM implementation: `sentience-chrome/src/lib.rs`
+