sentience-ts 0.10.3

package/README.md

@@ -0,0 +1,193 @@
+# Sentience TypeScript SDK
+
+**📜 License**: Apache License 2.0
+
+TypeScript SDK for Sentience AI Agent Browser Automation.
+
+## Installation
+
+```bash
+cd sdk-ts
+npm install
+npm run build
+
+# Install Playwright browsers (required)
+npx playwright install chromium
+```
+
+## Quick Start
+
+```typescript
+import { SentienceBrowser, snapshot, find, click } from './src';
+
+async function main() {
+  const browser = new SentienceBrowser(undefined, undefined, false);
+  
+  try {
+    await browser.start();
+    
+    await browser.getPage().goto('https://example.com');
+    await browser.getPage().waitForLoadState('networkidle');
+    
+    // Take snapshot
+    const snap = await snapshot(browser);
+    console.log(`Found ${snap.elements.length} elements`);
+    
+    // Find and click a link
+    const link = find(snap, 'role=link');
+    if (link) {
+      const result = await click(browser, link.id);
+      console.log(`Click success: ${result.success}`);
+    }
+  } finally {
+    await browser.close();
+  }
+}
+```
+
+## Running Examples
+
+**⚠️ Important**: You cannot use `node` directly to run TypeScript files. Use one of these methods:
+
+**Option 1: Using npm scripts (recommended)**
+```bash
+npm run example:hello
+npm run example:basic
+```
+
+**Option 2: Using ts-node directly**
+```bash
+npx ts-node examples/hello.ts
+# or if ts-node is installed globally:
+ts-node examples/hello.ts
+```
+
+**Option 3: Compile then run (not recommended for examples)**
+```bash
+npm run build
+# Examples would need to be compiled separately
+```
+
+## Features
+
+### Day 2: Browser Harness
+- `SentienceBrowser` - Launch Playwright with extension loaded
+- Automatic extension loading and verification
+
+### Day 3: Snapshot
+- `snapshot(browser, options)` - Capture page state
+- TypeScript types for type safety
+
+### Content Reading & Screenshots
+- `read(browser, options)` - Read page content as text or markdown
+  - Enhanced markdown conversion using `turndown` (better than extension's lightweight conversion)
+  - Supports `enhance_markdown` option to use improved conversion
+- `screenshot(browser, options)` - Capture standalone screenshot
+  - Returns base64-encoded data URL
+  - Supports PNG and JPEG formats with quality control
+
+### Day 4: Query Engine
+- `query(snapshot, selector)` - Find elements matching selector
+- `find(snapshot, selector)` - Find single best match
+- String DSL: `"role=button text~'Sign in'"`
+- **📖 [Complete DSL Query Guide](docs/QUERY_DSL.md)** - Comprehensive documentation with all operators, fields, and examples
+
+### Day 5: Actions
+- `click(browser, elementId)` - Click element
+- `typeText(browser, elementId, text)` - Type into element
+- `press(browser, key)` - Press keyboard key
+
+### Day 6: Wait & Assert
+- `waitFor(browser, selector, timeout)` - Wait for element
+- `expect(browser, selector)` - Assertion helper
+  - `.toExist()`
+  - `.toBeVisible()`
+  - `.toHaveText(text)`
+  - `.toHaveCount(n)`
+
+### Content Reading
+- `read(browser, options)` - Read page content
+  - **Default format: `"raw"`** - Returns HTML suitable for Turndown
+  - `format: "raw"` - Get cleaned HTML
+  - `format: "markdown"` - Get high-quality markdown (uses Turndown internally)
+  - `format: "text"` - Get plain text
+  
+  **Examples:**
+  ```typescript
+  import { read } from './src';
+  
+  // Get raw HTML (default)
+  const result = await read(browser);
+  const html = result.content;
+  
+  // Get high-quality markdown (uses Turndown automatically)
+  const result = await read(browser, { format: 'markdown' });
+  const markdown = result.content;
+  ```
+  
+  See `examples/read-markdown.ts` for complete examples.
+
+## Examples
+
+See `examples/` directory:
+- `hello.ts` - Extension bridge verification
+- `basic-agent.ts` - Basic snapshot
+- `query-demo.ts` - Query engine
+- `wait-and-click.ts` - Wait and actions
+- `read-markdown.ts` - Reading page content and converting to markdown
+
+### Content Reading Example
+
+```typescript
+import { SentienceBrowser, read } from './src';
+
+const browser = new SentienceBrowser();
+await browser.start();
+
+await browser.getPage().goto('https://example.com');
+await browser.getPage().waitForLoadState('networkidle');
+
+// Read as enhanced markdown (better quality)
+const result = await read(browser, { 
+  format: 'markdown', 
+  enhance_markdown: true 
+});
+console.log(result.content);  // High-quality markdown
+
+await browser.close();
+```
+
+### Screenshot Example
+
+```typescript
+import { SentienceBrowser, screenshot } from './src';
+import { writeFileSync } from 'fs';
+
+const browser = new SentienceBrowser();
+await browser.start();
+
+await browser.getPage().goto('https://example.com');
+await browser.getPage().waitForLoadState('networkidle');
+
+// Capture PNG screenshot
+const dataUrl = await screenshot(browser, { format: 'png' });
+
+// Save to file
+const base64Data = dataUrl.split(',')[1];
+const imageData = Buffer.from(base64Data, 'base64');
+writeFileSync('screenshot.png', imageData);
+
+await browser.close();
+```
+
+## Testing
+
+```bash
+npm test
+```
+
+## Documentation
+
+- **📖 [Query DSL Guide](docs/QUERY_DSL.md)** - Complete guide to the semantic query language
+- API Contract: `../spec/SNAPSHOT_V1.md`
+- Type Definitions: `../spec/sdk-types.md`

package/dist/actions.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Actions v1 - click, type, press
+ */
+import { SentienceBrowser } from './browser';
+import { ActionResult } from './types';
+export declare function click(browser: SentienceBrowser, elementId: number, takeSnapshot?: boolean): Promise<ActionResult>;
+export declare function typeText(browser: SentienceBrowser, elementId: number, text: string, takeSnapshot?: boolean): Promise<ActionResult>;
+export declare function press(browser: SentienceBrowser, key: string, takeSnapshot?: boolean): Promise<ActionResult>;
+//# sourceMappingURL=actions.d.ts.map

package/dist/actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAY,MAAM,SAAS,CAAC;AAGjD,wBAAsB,KAAK,CACzB,OAAO,EAAE,gBAAgB,EACzB,SAAS,EAAE,MAAM,EACjB,YAAY,GAAE,OAAe,GAC5B,OAAO,CAAC,YAAY,CAAC,CA2CvB;AAED,wBAAsB,QAAQ,CAC5B,OAAO,EAAE,gBAAgB,EACzB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,YAAY,GAAE,OAAe,GAC5B,OAAO,CAAC,YAAY,CAAC,CA6CvB;AAED,wBAAsB,KAAK,CACzB,OAAO,EAAE,gBAAgB,EACzB,GAAG,EAAE,MAAM,EACX,YAAY,GAAE,OAAe,GAC5B,OAAO,CAAC,YAAY,CAAC,CA6BvB"}

package/dist/actions.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * Actions v1 - click, type, press
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.click = click;
+exports.typeText = typeText;
+exports.press = press;
+const snapshot_1 = require("./snapshot");
+async function click(browser, elementId, takeSnapshot = false) {
+    const page = browser.getPage();
+    const startTime = Date.now();
+    const urlBefore = page.url();
+    // Call extension click method
+    const success = await page.evaluate((id) => {
+        return window.sentience.click(id);
+    }, elementId);
+    // Wait a bit for navigation/DOM updates
+    await page.waitForTimeout(500);
+    const durationMs = Date.now() - startTime;
+    const urlAfter = page.url();
+    const urlChanged = urlBefore !== urlAfter;
+    // Determine outcome
+    let outcome;
+    if (urlChanged) {
+        outcome = 'navigated';
+    }
+    else if (success) {
+        outcome = 'dom_updated';
+    }
+    else {
+        outcome = 'error';
+    }
+    // Optional snapshot after
+    let snapshotAfter;
+    if (takeSnapshot) {
+        snapshotAfter = await (0, snapshot_1.snapshot)(browser);
+    }
+    return {
+        success,
+        duration_ms: durationMs,
+        outcome,
+        url_changed: urlChanged,
+        snapshot_after: snapshotAfter,
+        error: success
+            ? undefined
+            : { code: 'click_failed', reason: 'Element not found or not clickable' },
+    };
+}
+async function typeText(browser, elementId, text, takeSnapshot = false) {
+    const page = browser.getPage();
+    const startTime = Date.now();
+    const urlBefore = page.url();
+    // Focus element first
+    const focused = await page.evaluate((id) => {
+        const el = window.sentience_registry[id];
+        if (el) {
+            el.focus();
+            return true;
+        }
+        return false;
+    }, elementId);
+    if (!focused) {
+        return {
+            success: false,
+            duration_ms: Date.now() - startTime,
+            outcome: 'error',
+            error: { code: 'focus_failed', reason: 'Element not found' },
+        };
+    }
+    // Type using Playwright keyboard
+    await page.keyboard.type(text);
+    const durationMs = Date.now() - startTime;
+    const urlAfter = page.url();
+    const urlChanged = urlBefore !== urlAfter;
+    const outcome = urlChanged ? 'navigated' : 'dom_updated';
+    let snapshotAfter;
+    if (takeSnapshot) {
+        snapshotAfter = await (0, snapshot_1.snapshot)(browser);
+    }
+    return {
+        success: true,
+        duration_ms: durationMs,
+        outcome,
+        url_changed: urlChanged,
+        snapshot_after: snapshotAfter,
+    };
+}
+async function press(browser, key, takeSnapshot = false) {
+    const page = browser.getPage();
+    const startTime = Date.now();
+    const urlBefore = page.url();
+    // Press key using Playwright
+    await page.keyboard.press(key);
+    // Wait a bit for navigation/DOM updates
+    await page.waitForTimeout(500);
+    const durationMs = Date.now() - startTime;
+    const urlAfter = page.url();
+    const urlChanged = urlBefore !== urlAfter;
+    const outcome = urlChanged ? 'navigated' : 'dom_updated';
+    let snapshotAfter;
+    if (takeSnapshot) {
+        snapshotAfter = await (0, snapshot_1.snapshot)(browser);
+    }
+    return {
+        success: true,
+        duration_ms: durationMs,
+        outcome,
+        url_changed: urlChanged,
+        snapshot_after: snapshotAfter,
+    };
+}
+//# sourceMappingURL=actions.js.map

package/dist/actions.js.map

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

package/dist/browser.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Playwright browser harness with extension loading
+ */
+import { Page } from 'playwright';
+export declare class SentienceBrowser {
+    private context;
+    private browser;
+    private page;
+    private extensionPath;
+    private userDataDir;
+    private _apiKey?;
+    private _apiUrl?;
+    private headless;
+    constructor(apiKey?: string, apiUrl?: string, headless?: boolean);
+    start(): Promise<void>;
+    goto(url: string): Promise<void>;
+    private waitForExtension;
+    getPage(): Page;
+    private _copyRecursive;
+    getApiKey(): string | undefined;
+    getApiUrl(): string | undefined;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAA4B,IAAI,EAAW,MAAM,YAAY,CAAC;AAKrE,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,OAAO,CAAC,QAAQ,CAAU;gBAGxB,MAAM,CAAC,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,OAAO;IAqBd,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAgFtB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAqBxB,gBAAgB;IAkB9B,OAAO,IAAI,IAAI;IAQf,OAAO,CAAC,cAAc;IAYtB,SAAS,IAAI,MAAM,GAAG,SAAS;IAI/B,SAAS,IAAI,MAAM,GAAG,SAAS;IAIzB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CA8C7B"}

package/dist/browser.js

@@ -0,0 +1,236 @@
+"use strict";
+/**
+ * Playwright browser harness with extension loading
+ */
+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.SentienceBrowser = void 0;
+const playwright_1 = require("playwright");
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+class SentienceBrowser {
+    constructor(apiKey, apiUrl, headless) {
+        this.context = null;
+        this.browser = null;
+        this.page = null;
+        this.extensionPath = null;
+        this.userDataDir = null;
+        this._apiKey = apiKey;
+        // Determine headless mode
+        if (headless === undefined) {
+            // Default to true in CI, false locally
+            const ci = process.env.CI?.toLowerCase();
+            this.headless = ci === 'true' || ci === '1' || ci === 'yes';
+        }
+        else {
+            this.headless = headless;
+        }
+        // Configure API URL
+        if (apiKey) {
+            this._apiUrl = apiUrl || 'https://api.sentienceapi.com';
+        }
+        else {
+            this._apiUrl = undefined;
+        }
+    }
+    async start() {
+        // 1. Resolve Extension Path
+        // Handle: src/extension (local dev), dist/extension (prod), or ../sentience-chrome (monorepo)
+        let extensionSource = '';
+        const candidates = [
+            // Production / Installed Package
+            path.resolve(__dirname, '../extension'),
+            path.resolve(__dirname, 'extension'),
+            // Local Monorepo Dev
+            path.resolve(__dirname, '../../sentience-chrome'),
+            path.resolve(__dirname, '../../../sentience-chrome'),
+            // CI Artifact
+            path.resolve(process.cwd(), 'extension')
+        ];
+        for (const loc of candidates) {
+            if (fs.existsSync(path.join(loc, 'manifest.json'))) {
+                extensionSource = loc;
+                break;
+            }
+        }
+        if (!extensionSource) {
+            throw new Error(`Sentience extension not found. Checked:\n${candidates.map(c => `- ${c}`).join('\n')}\n` +
+                'Ensure the extension is built/downloaded.');
+        }
+        // 2. Setup Temp Profile (Avoids locking issues)
+        this.userDataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'sentience-ts-'));
+        this.extensionPath = path.join(this.userDataDir, 'extension');
+        // Copy extension to temp dir
+        this._copyRecursive(extensionSource, this.extensionPath);
+        // 3. Build Args
+        const args = [
+            `--disable-extensions-except=${this.extensionPath}`,
+            `--load-extension=${this.extensionPath}`,
+            '--disable-blink-features=AutomationControlled',
+            '--no-sandbox',
+            '--disable-infobars',
+        ];
+        // CRITICAL: Headless Extensions Support
+        // headless: true -> NO extensions.
+        // headless: false + args: '--headless=new' -> YES extensions.
+        if (this.headless) {
+            args.push('--headless=new');
+        }
+        // 4. Launch Browser
+        this.context = await playwright_1.chromium.launchPersistentContext(this.userDataDir, {
+            headless: false, // Must be false here, handled via args above
+            args: args,
+            viewport: { width: 1920, height: 1080 },
+            // Clean User-Agent to avoid "HeadlessChrome" detection
+            userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36'
+        });
+        this.page = this.context.pages()[0] || await this.context.newPage();
+        // 5. Apply Stealth (Basic)
+        await this.page.addInitScript(() => {
+            Object.defineProperty(navigator, 'webdriver', { get: () => false });
+        });
+        // Inject API Key if present
+        if (this._apiKey) {
+            await this.page.addInitScript((key) => {
+                window.__SENTIENCE_API_KEY__ = key;
+            }, this._apiKey);
+        }
+        // Wait for extension background pages to spin up
+        await new Promise(r => setTimeout(r, 500));
+    }
+    async goto(url) {
+        const page = this.getPage();
+        await page.goto(url, { waitUntil: 'domcontentloaded' });
+        if (!(await this.waitForExtension(15000))) {
+            // Gather Debug Info
+            const diag = await page.evaluate(() => ({
+                sentience_global: typeof window.sentience !== 'undefined',
+                wasm_ready: window.sentience && window.sentience._wasmModule !== null,
+                ext_id: document.documentElement.dataset.sentienceExtensionId || 'not set',
+                url: window.location.href
+            })).catch(e => ({ error: String(e) }));
+            throw new Error('Extension failed to load after navigation.\n' +
+                `Path: ${this.extensionPath}\n` +
+                `Diagnostics: ${JSON.stringify(diag, null, 2)}`);
+        }
+    }
+    async waitForExtension(timeoutMs) {
+        const start = Date.now();
+        while (Date.now() - start < timeoutMs) {
+            try {
+                const ready = await this.page.evaluate(() => {
+                    // Check for API AND Wasm Module (set by injected_api.js)
+                    const s = window.sentience;
+                    return s && s._wasmModule !== null; // Strict check for null (it's initialized as null)
+                });
+                if (ready)
+                    return true;
+            }
+            catch (e) {
+                // Context invalid errors expected during navigation
+            }
+            await new Promise(r => setTimeout(r, 100));
+        }
+        return false;
+    }
+    getPage() {
+        if (!this.page) {
+            throw new Error('Browser not started. Call start() first.');
+        }
+        return this.page;
+    }
+    // Helper for recursive copy (fs.cp is Node 16.7+)
+    _copyRecursive(src, dest) {
+        if (fs.statSync(src).isDirectory()) {
+            if (!fs.existsSync(dest))
+                fs.mkdirSync(dest);
+            fs.readdirSync(src).forEach(child => {
+                this._copyRecursive(path.join(src, child), path.join(dest, child));
+            });
+        }
+        else {
+            fs.copyFileSync(src, dest);
+        }
+    }
+    // Expose API configuration (read-only)
+    getApiKey() {
+        return this._apiKey;
+    }
+    getApiUrl() {
+        return this._apiUrl;
+    }
+    async close() {
+        const cleanup = [];
+        // Close context first (this also closes the browser for persistent contexts)
+        if (this.context) {
+            cleanup.push(this.context.close().catch(() => {
+                // Ignore errors during cleanup
+            }));
+            this.context = null;
+        }
+        // Close browser if it exists (for non-persistent contexts)
+        if (this.browser) {
+            cleanup.push(this.browser.close().catch(() => {
+                // Ignore errors during cleanup
+            }));
+            this.browser = null;
+        }
+        // Wait for all cleanup to complete
+        await Promise.all(cleanup);
+        // Clean up extension directory
+        if (this.extensionPath && fs.existsSync(this.extensionPath)) {
+            try {
+                fs.rmSync(this.extensionPath, { recursive: true, force: true });
+            }
+            catch (e) {
+                // Ignore cleanup errors
+            }
+            this.extensionPath = null;
+        }
+        // Clean up user data directory
+        if (this.userDataDir && fs.existsSync(this.userDataDir)) {
+            try {
+                fs.rmSync(this.userDataDir, { recursive: true, force: true });
+            }
+            catch (e) {
+                // Ignore cleanup errors
+            }
+            this.userDataDir = null;
+        }
+    }
+}
+exports.SentienceBrowser = SentienceBrowser;
+//# sourceMappingURL=browser.js.map

package/dist/browser.js.map

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

package/dist/cli.d.ts

@@ -0,0 +1,5 @@
+/**
+ * CLI commands for Sentience SDK
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

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