@predicatelabs/sdk 0.99.9

package/dist/browser.js

@@ -0,0 +1,920 @@
+"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.PredicateBrowser = exports.SentienceBrowser = void 0;
+exports.normalizeDomain = normalizeDomain;
+exports.domainMatches = domainMatches;
+exports.extractHost = extractHost;
+exports.isDomainAllowed = isDomainAllowed;
+const playwright_1 = require("playwright");
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const url_1 = require("url");
+const snapshot_1 = require("./snapshot");
+function normalizeDomain(domain) {
+    const raw = domain.trim();
+    let host = raw;
+    if (raw.includes('://')) {
+        try {
+            host = new url_1.URL(raw).hostname || '';
+        }
+        catch {
+            host = raw;
+        }
+    }
+    else {
+        host = raw.split('/', 1)[0];
+    }
+    host = host.split(':', 1)[0];
+    return host.trim().toLowerCase().replace(/^\./, '');
+}
+function domainMatches(host, pattern) {
+    const hostNorm = normalizeDomain(host);
+    let pat = normalizeDomain(pattern);
+    if (pat.startsWith('*.')) {
+        pat = pat.slice(2);
+    }
+    return hostNorm === pat || hostNorm.endsWith(`.${pat}`);
+}
+function extractHost(url) {
+    let raw = url.trim();
+    if (!raw.includes('://')) {
+        raw = `https://${raw}`;
+    }
+    try {
+        const parsed = new url_1.URL(raw);
+        return parsed.hostname || null;
+    }
+    catch {
+        return null;
+    }
+}
+function isDomainAllowed(host, allowed, prohibited) {
+    if (!host)
+        return false;
+    if (prohibited && prohibited.length > 0) {
+        for (const pattern of prohibited) {
+            if (domainMatches(host, pattern)) {
+                return false;
+            }
+        }
+    }
+    if (allowed && allowed.length > 0) {
+        return allowed.some(pattern => domainMatches(host, pattern));
+    }
+    return true;
+}
+class SentienceBrowser {
+    /**
+     * Create a new SentienceBrowser instance
+     *
+     * @param apiKey - Optional API key for server-side processing (Pro/Enterprise tiers)
+     * @param apiUrl - Optional API URL (defaults to https://api.sentienceapi.com if apiKey provided)
+     * @param headless - Whether to run in headless mode (defaults to true in CI, false locally)
+     * @param proxy - Optional proxy server URL (e.g., 'http://user:pass@proxy.example.com:8080')
+     * @param userDataDir - Optional path to user data directory for persistent sessions
+     * @param storageState - Optional storage state to inject (cookies + localStorage)
+     * @param recordVideoDir - Optional directory path to save video recordings
+     * @param recordVideoSize - Optional video resolution as object with 'width' and 'height' keys
+     * @param viewport - Optional viewport size as object with 'width' and 'height' keys
+     * @param deviceScaleFactor - Optional device scale factor to emulate high-DPI (Retina) screens.
+     *                          Examples: 1.0 (default, standard DPI), 2.0 (Retina/high-DPI, like MacBook Pro), 3.0 (very high DPI)
+     *                          If undefined, defaults to 1.0 (standard DPI).
+     * @param allowedDomains - Optional list of allowed domains for navigation.
+     * @param prohibitedDomains - Optional list of prohibited domains for navigation.
+     * @param keepAlive - Keep browser alive after close() (no teardown).
+     */
+    constructor(apiKey, apiUrl, headless, proxy, userDataDir, storageState, recordVideoDir, recordVideoSize, viewport, deviceScaleFactor, allowedDomains, prohibitedDomains, keepAlive = false, permissionPolicy) {
+        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;
+        }
+        // Support proxy from parameter or environment variable
+        // Only use env var if it's a valid non-empty string
+        const envProxy = process.env.SENTIENCE_PROXY;
+        this._proxy = proxy || (envProxy && envProxy.trim() ? envProxy : undefined);
+        // Auth injection support
+        this._userDataDir = userDataDir;
+        this._storageState = storageState;
+        // Video recording support
+        this._recordVideoDir = recordVideoDir;
+        this._recordVideoSize = recordVideoSize || { width: 1280, height: 800 };
+        // Viewport configuration
+        this._viewport = viewport || { width: 1280, height: 800 };
+        // Device scale factor for high-DPI emulation
+        this._deviceScaleFactor = deviceScaleFactor;
+        this._allowedDomains = allowedDomains;
+        this._prohibitedDomains = prohibitedDomains;
+        this._keepAlive = keepAlive;
+        this._permissionPolicy = permissionPolicy;
+    }
+    async applyPermissionPolicy(context, policy) {
+        const defaultPolicy = policy.default ?? 'clear';
+        if (defaultPolicy === 'clear' || defaultPolicy === 'deny') {
+            await context.clearPermissions();
+        }
+        if (policy.geolocation) {
+            await context.setGeolocation(policy.geolocation);
+        }
+        if (policy.autoGrant && policy.autoGrant.length > 0) {
+            const options = policy.origin ? { origin: policy.origin } : undefined;
+            await context.grantPermissions(policy.autoGrant, options);
+        }
+    }
+    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 User Data Directory
+        if (this._userDataDir) {
+            // Use provided directory for persistent sessions
+            this.userDataDir = this._userDataDir;
+            if (!fs.existsSync(this.userDataDir)) {
+                fs.mkdirSync(this.userDataDir, { recursive: true });
+            }
+        }
+        else {
+            // Create temp directory (ephemeral, existing behavior)
+            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');
+        }
+        // CRITICAL: WebRTC leak protection for datacenter usage with proxies
+        // Prevents WebRTC from leaking the real IP address even when using proxies
+        if (this._proxy) {
+            args.push('--disable-features=WebRtcHideLocalIpsWithMdns');
+            args.push('--force-webrtc-ip-handling-policy=disable_non_proxied_udp');
+        }
+        // 4. Parse proxy configuration
+        const proxyConfig = this.parseProxy(this._proxy);
+        // 5. Setup video recording directory if requested
+        if (this._recordVideoDir) {
+            if (!fs.existsSync(this._recordVideoDir)) {
+                fs.mkdirSync(this._recordVideoDir, { recursive: true });
+            }
+            console.log(`🎥 [Sentience] Recording video to: ${this._recordVideoDir}`);
+            console.log(`   Resolution: ${this._recordVideoSize.width}x${this._recordVideoSize.height}`);
+        }
+        // 6. Launch Browser
+        const launchOptions = {
+            headless: false, // Must be false here, handled via args above
+            args: args,
+            viewport: this._viewport,
+            // 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',
+            proxy: proxyConfig, // Pass proxy configuration
+            // CRITICAL: Ignore HTTPS errors when using proxy (proxies often use self-signed certs)
+            ignoreHTTPSErrors: proxyConfig !== undefined,
+        };
+        // Add device scale factor if configured
+        if (this._deviceScaleFactor !== undefined) {
+            launchOptions.deviceScaleFactor = this._deviceScaleFactor;
+        }
+        // Add video recording if configured
+        if (this._recordVideoDir) {
+            launchOptions.recordVideo = {
+                dir: this._recordVideoDir,
+                size: this._recordVideoSize,
+            };
+        }
+        this.context = await playwright_1.chromium.launchPersistentContext(this.userDataDir, launchOptions);
+        if (this._permissionPolicy) {
+            await this.applyPermissionPolicy(this.context, this._permissionPolicy);
+        }
+        this.page = this.context.pages()[0] || (await this.context.newPage());
+        // Inject storage state if provided (must be after context creation)
+        if (this._storageState) {
+            await this.injectStorageState(this._storageState);
+        }
+        // Apply context-level stealth patches (runs on every new page)
+        await this.context.addInitScript(() => {
+            // Early webdriver hiding - runs before any page script
+            // Use multiple strategies to completely hide webdriver
+            // Strategy 1: Try to delete it first
+            try {
+                delete navigator.webdriver;
+            }
+            catch {
+                // Property might not be deletable
+            }
+            // Strategy 2: Redefine to return undefined and hide from enumeration
+            Object.defineProperty(navigator, 'webdriver', {
+                get: () => undefined,
+                configurable: true,
+                enumerable: false,
+                writable: false,
+            });
+            // Strategy 3: Override 'in' operator check
+            const originalHasOwnProperty = Object.prototype.hasOwnProperty;
+            Object.prototype.hasOwnProperty = function (prop) {
+                if (this === navigator && (prop === 'webdriver' || prop === 'Webdriver')) {
+                    return false;
+                }
+                return originalHasOwnProperty.call(this, prop);
+            };
+        });
+        // 5. Apply Comprehensive Stealth Patches
+        // Use both CDP (earlier) and addInitScript (backup) for maximum coverage
+        // Strategy A: Use CDP to inject at the earliest possible moment
+        const client = await this.page.context().newCDPSession(this.page);
+        await client.send('Page.addScriptToEvaluateOnNewDocument', {
+            source: `
+        // Aggressive webdriver hiding - must run before ANY page script
+        Object.defineProperty(navigator, 'webdriver', {
+          get: () => undefined,
+          configurable: true,
+          enumerable: false
+        });
+        
+        // Override Object.getOwnPropertyDescriptor
+        const originalGetOwnPropertyDescriptor = Object.getOwnPropertyDescriptor;
+        Object.getOwnPropertyDescriptor = function(obj, prop) {
+          if (obj === navigator && (prop === 'webdriver' || prop === 'Webdriver')) {
+            return undefined;
+          }
+          return originalGetOwnPropertyDescriptor(obj, prop);
+        };
+        
+        // Override Object.keys
+        const originalKeys = Object.keys;
+        Object.keys = function(obj) {
+          const keys = originalKeys(obj);
+          if (obj === navigator) {
+            return keys.filter(k => k !== 'webdriver' && k !== 'Webdriver');
+          }
+          return keys;
+        };
+        
+        // Override Object.getOwnPropertyNames
+        const originalGetOwnPropertyNames = Object.getOwnPropertyNames;
+        Object.getOwnPropertyNames = function(obj) {
+          const names = originalGetOwnPropertyNames(obj);
+          if (obj === navigator) {
+            return names.filter(n => n !== 'webdriver' && n !== 'Webdriver');
+          }
+          return names;
+        };
+        
+        // Override 'in' operator check
+        const originalHasOwnProperty = Object.prototype.hasOwnProperty;
+        Object.prototype.hasOwnProperty = function(prop) {
+          if (this === navigator && (prop === 'webdriver' || prop === 'Webdriver')) {
+            return false;
+          }
+          return originalHasOwnProperty.call(this, prop);
+        };
+      `,
+        });
+        // Strategy B: Also use addInitScript as backup (runs after CDP but before page scripts)
+        await this.page.addInitScript(() => {
+            // 1. Hide navigator.webdriver (comprehensive approach for advanced detection)
+            // Advanced detection checks for property descriptor, so we need multiple strategies
+            try {
+                // Strategy 1: Try to delete the property
+                delete navigator.webdriver;
+            }
+            catch {
+                // Property might not be deletable, continue with redefine
+            }
+            // Strategy 2: Redefine to return undefined (better than false)
+            // Also set enumerable: false to hide from Object.keys() checks
+            Object.defineProperty(navigator, 'webdriver', {
+                get: () => undefined,
+                configurable: true,
+                enumerable: false,
+            });
+            // Strategy 3: Override Object.getOwnPropertyDescriptor only for navigator.webdriver
+            // This prevents advanced detection that checks the property descriptor
+            const originalGetOwnPropertyDescriptor = Object.getOwnPropertyDescriptor;
+            Object.getOwnPropertyDescriptor = function (obj, prop) {
+                if (obj === navigator && (prop === 'webdriver' || prop === 'Webdriver')) {
+                    return undefined;
+                }
+                return originalGetOwnPropertyDescriptor(obj, prop);
+            };
+            // Strategy 4: Hide from Object.keys() and Object.getOwnPropertyNames()
+            const originalKeys = Object.keys;
+            Object.keys = function (obj) {
+                const keys = originalKeys(obj);
+                if (obj === navigator) {
+                    return keys.filter(k => k !== 'webdriver' && k !== 'Webdriver');
+                }
+                return keys;
+            };
+            // Strategy 5: Hide from Object.getOwnPropertyNames()
+            const originalGetOwnPropertyNames = Object.getOwnPropertyNames;
+            Object.getOwnPropertyNames = function (obj) {
+                const names = originalGetOwnPropertyNames(obj);
+                if (obj === navigator) {
+                    return names.filter(n => n !== 'webdriver' && n !== 'Webdriver');
+                }
+                return names;
+            };
+            // Strategy 6: Override hasOwnProperty to hide from 'in' operator checks
+            const originalHasOwnProperty = Object.prototype.hasOwnProperty;
+            Object.prototype.hasOwnProperty = function (prop) {
+                if (this === navigator && (prop === 'webdriver' || prop === 'Webdriver')) {
+                    return false;
+                }
+                return originalHasOwnProperty.call(this, prop);
+            };
+            // 2. Inject window.chrome object (required for Chrome detection)
+            if (typeof window.chrome === 'undefined') {
+                window.chrome = {
+                    runtime: {},
+                    loadTimes: function () { },
+                    csi: function () { },
+                    app: {},
+                };
+            }
+            // 3. Patch navigator.plugins (should have length > 0)
+            // Only patch if plugins array is empty (headless mode issue)
+            const originalPlugins = navigator.plugins;
+            if (originalPlugins.length === 0) {
+                // Create a PluginArray-like object with minimal plugins
+                const fakePlugins = [
+                    {
+                        name: 'Chrome PDF Plugin',
+                        filename: 'internal-pdf-viewer',
+                        description: 'Portable Document Format',
+                        length: 1,
+                        item: function () {
+                            return null;
+                        },
+                        namedItem: function () {
+                            return null;
+                        },
+                    },
+                    {
+                        name: 'Chrome PDF Viewer',
+                        filename: 'mhjfbmdgcfjbbpaeojofohoefgiehjai',
+                        description: '',
+                        length: 0,
+                        item: function () {
+                            return null;
+                        },
+                        namedItem: function () {
+                            return null;
+                        },
+                    },
+                    {
+                        name: 'Native Client',
+                        filename: 'internal-nacl-plugin',
+                        description: '',
+                        length: 0,
+                        item: function () {
+                            return null;
+                        },
+                        namedItem: function () {
+                            return null;
+                        },
+                    },
+                ];
+                // Create PluginArray-like object (array-like but not a real array)
+                // This needs to behave like the real PluginArray for detection to pass
+                const pluginArray = {};
+                fakePlugins.forEach((plugin, index) => {
+                    Object.defineProperty(pluginArray, index.toString(), {
+                        value: plugin,
+                        enumerable: true,
+                        configurable: true,
+                    });
+                });
+                Object.defineProperty(pluginArray, 'length', {
+                    value: fakePlugins.length,
+                    enumerable: false,
+                    configurable: false,
+                });
+                pluginArray.item = function (index) {
+                    return this[index] || null;
+                };
+                pluginArray.namedItem = function (name) {
+                    for (let i = 0; i < this.length; i++) {
+                        if (this[i] && this[i].name === name)
+                            return this[i];
+                    }
+                    return null;
+                };
+                // Make it iterable (for for...of loops)
+                pluginArray[Symbol.iterator] = function* () {
+                    for (let i = 0; i < this.length; i++) {
+                        yield this[i];
+                    }
+                };
+                // Make it array-like for Array.from() and spread
+                Object.setPrototypeOf(pluginArray, Object.create(null));
+                Object.defineProperty(navigator, 'plugins', {
+                    get: () => pluginArray,
+                    configurable: true,
+                    enumerable: true,
+                });
+            }
+            // 4. Ensure navigator.languages exists and has values
+            if (!navigator.languages || navigator.languages.length === 0) {
+                Object.defineProperty(navigator, 'languages', {
+                    get: () => ['en-US', 'en'],
+                    configurable: true,
+                });
+            }
+            // 5. Patch permissions API (should exist)
+            if (!navigator.permissions) {
+                navigator.permissions = {
+                    query: (_parameters) => {
+                        return { state: 'granted', onchange: null };
+                    },
+                };
+            }
+        });
+        // 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();
+        if (!page) {
+            throw new Error('Browser not started. Call start() first.');
+        }
+        const host = extractHost(url);
+        if (!isDomainAllowed(host, this._allowedDomains, this._prohibitedDomains)) {
+            throw new Error(`domain not allowed: ${host}`);
+        }
+        await page.goto(url, { waitUntil: 'domcontentloaded' });
+        if (!(await this.waitForExtension(page, 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(page, timeoutMs) {
+        const start = Date.now();
+        while (Date.now() - start < timeoutMs) {
+            try {
+                const ready = await 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 {
+                // Context invalid errors expected during navigation
+            }
+            await new Promise(r => setTimeout(r, 100));
+        }
+        return false;
+    }
+    getPage() {
+        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;
+    }
+    /**
+     * Take a snapshot of the current page
+     * Implements IBrowser interface
+     */
+    async snapshot(options) {
+        return (0, snapshot_1.snapshot)(this, options);
+    }
+    /**
+     * Parse proxy connection string into Playwright format.
+     *
+     * @param proxyString - Standard format "http://username:password@host:port"
+     *                    or "socks5://user:pass@host:port"
+     * @returns Playwright proxy object or undefined if invalid
+     */
+    parseProxy(proxyString) {
+        if (!proxyString || !proxyString.trim()) {
+            return undefined;
+        }
+        try {
+            const parsed = new url_1.URL(proxyString);
+            // Validate scheme
+            const validSchemes = ['http:', 'https:', 'socks5:'];
+            if (!validSchemes.includes(parsed.protocol)) {
+                throw new Error(`Unsupported proxy scheme: ${parsed.protocol}`);
+            }
+            // Validate host and port
+            if (!parsed.hostname || !parsed.port) {
+                throw new Error('Proxy URL must include hostname and port');
+            }
+            // Build Playwright proxy object
+            const proxyConfig = {
+                server: `${parsed.protocol}//${parsed.hostname}:${parsed.port}`,
+            };
+            // Add credentials if present
+            if (parsed.username && parsed.password) {
+                proxyConfig.username = parsed.username;
+                proxyConfig.password = parsed.password;
+            }
+            return proxyConfig;
+        }
+        catch (e) {
+            console.warn(`⚠️  [Sentience] Invalid proxy configuration: ${e.message}`);
+            console.warn('   Expected format: http://username:password@host:port');
+            return undefined;
+        }
+    }
+    /**
+     * Inject storage state (cookies + localStorage) into browser context.
+     *
+     * @param storageState - Path to JSON file, StorageState object, or plain object
+     */
+    async injectStorageState(storageState) {
+        // Load storage state
+        let state;
+        if (typeof storageState === 'string') {
+            // Load from file
+            const content = fs.readFileSync(storageState, 'utf-8');
+            state = JSON.parse(content);
+        }
+        else if (typeof storageState === 'object' && storageState !== null) {
+            // Already an object (StorageState or plain object)
+            state = storageState;
+        }
+        else {
+            throw new Error(`Invalid storageState type: ${typeof storageState}. ` +
+                'Expected string (file path), StorageState, or object.');
+        }
+        // Inject cookies (works globally)
+        if (state.cookies && Array.isArray(state.cookies) && state.cookies.length > 0) {
+            // Convert to Playwright cookie format
+            const playwrightCookies = state.cookies.map(cookie => {
+                const playwrightCookie = {
+                    name: cookie.name,
+                    value: cookie.value,
+                    domain: cookie.domain,
+                    path: cookie.path || '/',
+                };
+                if (cookie.expires !== undefined) {
+                    playwrightCookie.expires = cookie.expires;
+                }
+                if (cookie.httpOnly !== undefined) {
+                    playwrightCookie.httpOnly = cookie.httpOnly;
+                }
+                if (cookie.secure !== undefined) {
+                    playwrightCookie.secure = cookie.secure;
+                }
+                if (cookie.sameSite !== undefined) {
+                    playwrightCookie.sameSite = cookie.sameSite;
+                }
+                return playwrightCookie;
+            });
+            await this.context.addCookies(playwrightCookies);
+            console.log(`✅ [Sentience] Injected ${state.cookies.length} cookie(s)`);
+        }
+        // Inject LocalStorage (requires navigation to each domain)
+        if (state.origins && Array.isArray(state.origins)) {
+            for (const originData of state.origins) {
+                const origin = originData.origin;
+                if (!origin) {
+                    continue;
+                }
+                try {
+                    // Navigate to origin
+                    await this.page.goto(origin, { waitUntil: 'domcontentloaded', timeout: 10000 });
+                    // Inject localStorage
+                    if (originData.localStorage && Array.isArray(originData.localStorage)) {
+                        // Convert to dict format for JavaScript
+                        const localStorageDict = {};
+                        for (const item of originData.localStorage) {
+                            localStorageDict[item.name] = item.value;
+                        }
+                        await this.page.evaluate((localStorageData) => {
+                            for (const [key, value] of Object.entries(localStorageData)) {
+                                localStorage.setItem(key, value);
+                            }
+                        }, localStorageDict);
+                        console.log(`✅ [Sentience] Injected ${originData.localStorage.length} localStorage item(s) for ${origin}`);
+                    }
+                }
+                catch (error) {
+                    console.warn(`⚠️  [Sentience] Failed to inject localStorage for ${origin}: ${error.message}`);
+                }
+            }
+        }
+    }
+    /**
+     * Get the browser context (for utilities like saveStorageState)
+     */
+    getContext() {
+        return this.context;
+    }
+    /**
+     * Create SentienceBrowser from an existing Playwright BrowserContext.
+     *
+     * This allows you to use Sentience SDK with a browser context you've already created,
+     * giving you more control over browser initialization.
+     *
+     * @param context - Existing Playwright BrowserContext
+     * @param apiKey - Optional API key for server-side processing
+     * @param apiUrl - Optional API URL (defaults to https://api.sentienceapi.com if apiKey provided)
+     * @returns SentienceBrowser instance configured to use the existing context
+     *
+     * @example
+     * ```typescript
+     * import { chromium } from 'playwright';
+     * import { SentienceBrowser } from '@sentience/sdk';
+     *
+     * const context = await chromium.launchPersistentContext(...);
+     * const browser = SentienceBrowser.fromExisting(context);
+     * await browser.getPage().goto('https://example.com');
+     * ```
+     */
+    static async fromExisting(context, apiKey, apiUrl) {
+        const instance = new SentienceBrowser(apiKey, apiUrl);
+        instance.context = context;
+        const pages = context.pages();
+        instance.page = pages.length > 0 ? pages[0] : await context.newPage();
+        // Wait for extension to be ready (if extension is loaded)
+        // Note: In TypeScript, we can't easily apply stealth here without the page
+        // The user should ensure stealth is applied to their context if needed
+        return instance;
+    }
+    /**
+     * Create SentienceBrowser from an existing Playwright Page.
+     *
+     * This allows you to use Sentience SDK with a page you've already created,
+     * giving you more control over browser initialization.
+     *
+     * @param page - Existing Playwright Page
+     * @param apiKey - Optional API key for server-side processing
+     * @param apiUrl - Optional API URL (defaults to https://api.sentienceapi.com if apiKey provided)
+     * @returns SentienceBrowser instance configured to use the existing page
+     *
+     * @example
+     * ```typescript
+     * import { chromium } from 'playwright';
+     * import { SentienceBrowser } from '@sentience/sdk';
+     *
+     * const browserInstance = await chromium.launch();
+     * const context = await browserInstance.newContext();
+     * const page = await context.newPage();
+     * await page.goto('https://example.com');
+     *
+     * const browser = SentienceBrowser.fromPage(page);
+     * ```
+     */
+    static fromPage(page, apiKey, apiUrl) {
+        const instance = new SentienceBrowser(apiKey, apiUrl);
+        instance.page = page;
+        instance.context = page.context();
+        // Wait for extension to be ready (if extension is loaded)
+        // Note: In TypeScript, we can't easily apply stealth here without the page
+        // The user should ensure stealth is applied to their context if needed
+        return instance;
+    }
+    async close(outputPath) {
+        if (this._keepAlive) {
+            return null;
+        }
+        let tempVideoPath = null;
+        // Get video path before closing (if recording was enabled)
+        // Note: Playwright saves videos when pages/context close, but we can get the
+        // expected path before closing. The actual file will be available after close.
+        if (this._recordVideoDir) {
+            try {
+                // Try to get video path from the first page
+                if (this.page) {
+                    const video = this.page.video();
+                    if (video) {
+                        tempVideoPath = await video.path();
+                    }
+                }
+                // If that fails, check all pages in the context (before closing)
+                if (!tempVideoPath && this.context) {
+                    const pages = this.context.pages();
+                    for (const page of pages) {
+                        try {
+                            const video = page.video();
+                            if (video) {
+                                tempVideoPath = await video.path();
+                                break;
+                            }
+                        }
+                        catch {
+                            // Continue to next page
+                        }
+                    }
+                }
+            }
+            catch {
+                // Video path might not be available until after close
+                // We'll use fallback mechanism below
+            }
+        }
+        const cleanup = [];
+        // Close context first (this also closes the browser for persistent contexts)
+        // This triggers video file finalization
+        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 {
+                // Ignore cleanup errors
+            }
+            this.extensionPath = null;
+        }
+        // After context closes, verify video file exists if we have a path
+        let finalPath = tempVideoPath;
+        if (tempVideoPath && fs.existsSync(tempVideoPath)) {
+            // Video file exists, proceed with rename if needed
+        }
+        else if (this._recordVideoDir && fs.existsSync(this._recordVideoDir)) {
+            // Fallback: If we couldn't get the path but recording was enabled,
+            // check the directory for video files
+            try {
+                const videoFiles = fs
+                    .readdirSync(this._recordVideoDir)
+                    .filter(f => f.endsWith('.webm'))
+                    .map(f => ({
+                    path: path.join(this._recordVideoDir, f),
+                    mtime: fs.statSync(path.join(this._recordVideoDir, f)).mtime.getTime(),
+                }))
+                    .sort((a, b) => b.mtime - a.mtime); // Most recent first
+                if (videoFiles.length > 0) {
+                    finalPath = videoFiles[0].path;
+                }
+            }
+            catch {
+                // Ignore errors when scanning directory
+            }
+        }
+        // Rename/move video if output_path is specified
+        if (finalPath && outputPath && fs.existsSync(finalPath)) {
+            try {
+                // Ensure parent directory exists
+                const outputDir = path.dirname(outputPath);
+                if (!fs.existsSync(outputDir)) {
+                    fs.mkdirSync(outputDir, { recursive: true });
+                }
+                fs.renameSync(finalPath, outputPath);
+                finalPath = outputPath;
+            }
+            catch (error) {
+                console.warn(`Failed to rename video file: ${error.message}`);
+                // Return original path if rename fails
+            }
+        }
+        // Clean up user data directory (only if it's a temp directory)
+        // If user provided a custom userDataDir, we don't delete it (persistent sessions)
+        if (this.userDataDir && fs.existsSync(this.userDataDir)) {
+            // Only delete if it's a temp directory (starts with os.tmpdir())
+            const isTempDir = this.userDataDir.startsWith(os.tmpdir());
+            if (isTempDir) {
+                try {
+                    fs.rmSync(this.userDataDir, { recursive: true, force: true });
+                }
+                catch {
+                    // Ignore cleanup errors
+                }
+            }
+            this.userDataDir = null;
+        }
+        return finalPath;
+    }
+}
+exports.SentienceBrowser = SentienceBrowser;
+/**
+ * Predicate rebrand alias for SentienceBrowser.
+ * Kept as a runtime alias to avoid breaking existing integrations.
+ */
+exports.PredicateBrowser = SentienceBrowser;
+//# sourceMappingURL=browser.js.map