Merge pull request #1 from SentienceAPI/week2

Week 2 completed

Author: rcholic

README.md

@@ -10,6 +10,9 @@ TypeScript SDK for Sentience AI Agent Browser Automation.
 cd sdk-ts
 npm install
 npm run build
+
+# Install Playwright browsers (required)
+npx playwright install chromium
 ```
 
 ## Quick Start
@@ -42,6 +45,29 @@ async function main() {
 }
 ```
 
+## 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
@@ -78,12 +104,6 @@ See `examples/` directory:
 - `query-demo.ts` - Query engine
 - `wait-and-click.ts` - Wait and actions
 
-Run examples:
-```bash
-npm run example:hello
-npm run example:basic
-```
-
 ## Testing
 
 ```bash

examples/basic-agent.ts

@@ -2,7 +2,7 @@
  * Day 3 Example: Basic snapshot functionality
  */
 
-import { SentienceBrowser, snapshot } from '../src';
+import { SentienceBrowser, snapshot } from '../src/index';
 import * as fs from 'fs';
 
 async function main() {

examples/hello.ts

@@ -2,26 +2,59 @@
  * Day 2 Example: Verify extension bridge is loaded
  */
 
-import { SentienceBrowser } from '../src';
+import { SentienceBrowser } from '../src/index';
 
 async function main() {
   const browser = new SentienceBrowser(undefined, false);
 
   try {
     await browser.start();
 
+    // Browser.start() already navigates to example.com, but we can navigate elsewhere if needed
+    // The extension should already be loaded at this point
+    
     // Check if extension API is available
     const bridgeOk = await browser.getPage().evaluate(
-      () => typeof (window as any).sentience !== 'undefined'
+      () => {
+        const win = window as any;
+        return typeof win.sentience !== 'undefined' && 
+               typeof win.sentience.snapshot === 'function';
+      }
     );
 
     console.log(`bridge_ok=${bridgeOk}`);
 
     if (bridgeOk) {
       console.log('✅ Extension loaded successfully!');
+      // Try a quick snapshot to verify it works
+      try {
+        const result = await browser.getPage().evaluate(
+          () => (window as any).sentience.snapshot({ limit: 1 })
+        );
+        if (result.status === 'success') {
+          console.log(`✅ Snapshot test: Found ${result.elements?.length || 0} elements`);
+        } else {
+          console.log(`⚠️  Snapshot returned: ${result.status}`);
+        }
+      } catch (e: any) {
+        console.log(`⚠️  Snapshot test failed: ${e.message}`);
+      }
     } else {
       console.log('❌ Extension not loaded');
+      // Debug info
+      const debugInfo = await browser.getPage().evaluate(() => {
+        const win = window as any;
+        return {
+          sentience_defined: typeof win.sentience !== 'undefined',
+          registry_defined: typeof win.sentience_registry !== 'undefined',
+          snapshot_defined: typeof win.sentience?.snapshot !== 'undefined'
+        };
+      });
+      console.log(`Debug info: ${JSON.stringify(debugInfo, null, 2)}`);
     }
+  } catch (e: any) {
+    console.error(`❌ Error: ${e.message}`);
+    console.error(e.stack);
   } finally {
     await browser.close();
   }

examples/query-demo.ts

@@ -2,7 +2,7 @@
  * Day 4 Example: Query engine demonstration
  */
 
-import { SentienceBrowser, snapshot, query, find } from '../src';
+import { SentienceBrowser, snapshot, query, find } from '../src/index';
 
 async function main() {
   const browser = new SentienceBrowser(undefined, false);

examples/wait-and-click.ts

@@ -2,7 +2,7 @@
  * Day 5-6 Example: Wait for element and click
  */
 
-import { SentienceBrowser, snapshot, find, waitFor, click, expect } from '../src';
+import { SentienceBrowser, snapshot, find, waitFor, click, expect } from '../src/index';
 
 async function main() {
   const browser = new SentienceBrowser(undefined, false);

src/browser.ts

@@ -19,8 +19,16 @@ export class SentienceBrowser {
   ) {}
 
   async start(): Promise<void> {
-    // Get extension source path
-    const repoRoot = path.resolve(__dirname, '../../..');
+    // Get extension source path (relative to project root)
+    // Handle both ts-node (src/) and compiled (dist/src/) cases
+    let repoRoot: string;
+    if (__dirname.includes('dist')) {
+      // Compiled: dist/src/ -> go up 3 levels to project root (Sentience/)
+      repoRoot = path.resolve(__dirname, '../../..');
+    } else {
+      // ts-node: src/ -> go up 2 levels to project root (Sentience/)
+      repoRoot = path.resolve(__dirname, '../..');
+    }
     const extensionSource = path.join(repoRoot, 'sentience-chrome');
 
     if (!fs.existsSync(extensionSource)) {
@@ -32,7 +40,7 @@ export class SentienceBrowser {
 
     // Create temporary extension bundle
     const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'sentience-ext-'));
-    this.extensionPath = tempDir;
+    this.extensionPath = tempDir; // tempDir is already a string
 
     // Copy extension files
     const filesToCopy = [
@@ -61,8 +69,8 @@ export class SentienceBrowser {
     this.browser = await chromium.launch({
       headless: this.headless,
       args: [
-        `--load-extension=${tempDir.name}`,
-        `--disable-extensions-except=${tempDir.name}`,
+        `--load-extension=${tempDir}`,
+        `--disable-extensions-except=${tempDir}`,
       ],
     });
 
@@ -74,8 +82,28 @@ export class SentienceBrowser {
     // Create page
     this.page = await this.context.newPage();
 
-    // Wait for extension
-    await this.waitForExtension();
+    // Navigate to a real page so extension can inject
+    // Extension content scripts only run on actual pages (not about:blank)
+    // Use a simple page that loads quickly
+    await this.page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
+
+    // Give extension time to initialize (WASM loading is async)
+    await this.page.waitForTimeout(1000);
+
+    // Wait for extension to load
+    if (!(await this.waitForExtension())) {
+      // Extension might need more time, try waiting a bit longer
+      await this.page.waitForTimeout(2000);
+      if (!(await this.waitForExtension())) {
+        throw new Error(
+          'Extension failed to load after navigation. Make sure:\n' +
+          '1. Extension is built (cd sentience-chrome && ./build.sh)\n' +
+          '2. All files are present (manifest.json, content.js, injected_api.js, pkg/)\n' +
+          '3. Check browser console for errors\n' +
+          `4. Extension path: ${tempDir}`
+        );
+      }
+    }
   }
 
   private copyDirectory(src: string, dest: string): void {
@@ -97,27 +125,36 @@ export class SentienceBrowser {
     }
   }
 
-  private async waitForExtension(timeout: number = 10000): Promise<boolean> {
+  private async waitForExtension(timeout: number = 15000): Promise<boolean> {
     if (!this.page) return false;
 
     const start = Date.now();
     while (Date.now() - start < timeout) {
       try {
         const result = await this.page.evaluate(() => {
-          return (
-            typeof (window as any).sentience !== 'undefined' &&
-            typeof (window as any).sentience.snapshot === 'function'
-          );
+          // Check if sentience API exists
+          if (typeof (window as any).sentience === 'undefined') {
+            return { ready: false, reason: 'window.sentience not defined' };
+          }
+          // Check if snapshot function exists
+          if (typeof (window as any).sentience.snapshot !== 'function') {
+            return { ready: false, reason: 'snapshot function not available' };
+          }
+          // Check if WASM module is loaded
+          if ((window as any).sentience_registry === undefined) {
+            return { ready: false, reason: 'registry not initialized' };
+          }
+          return { ready: true };
         });
 
-        if (result) {
+        if (result && (result as any).ready) {
           return true;
         }
       } catch (e) {
-        // Ignore errors during initialization
+        // Continue waiting on errors
       }
 
-      await new Promise((resolve) => setTimeout(resolve, 100));
+      await new Promise((resolve) => setTimeout(resolve, 200));
     }
 
     return false;

tsconfig.json

@@ -2,7 +2,7 @@
   "compilerOptions": {
     "target": "ES2020",
     "module": "commonjs",
-    "lib": ["ES2020"],
+    "lib": ["ES2020", "DOM"],
     "outDir": "./dist",
     "rootDir": "./src",
     "strict": true,
@@ -11,9 +11,15 @@
     "forceConsistentCasingInFileNames": true,
     "declaration": true,
     "declarationMap": true,
-    "sourceMap": true
+    "sourceMap": true,
+    "types": ["node"]
   },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist", "tests"]
+  "include": ["src/**/*", "examples/**/*"],
+  "exclude": ["node_modules", "dist", "tests"],
+  "ts-node": {
+    "compilerOptions": {
+      "lib": ["ES2020", "DOM"]
+    }
+  }
 }