@isoldex/sentinel 0.1.0 → 2.0.0

package/dist/core/driver.js

@@ -1,37 +1,114 @@
-import { chromium } from 'playwright';
+import { chromium, firefox, webkit } from 'playwright';
+import * as fs from 'fs';
+import * as path from 'path';
 export class SentinelDriver {
     options;
     browser = null;
     context = null;
-    page = null;
+    pages = [];
+    activePageIndex = 0;
     cdpSession = null;
     constructor(options = { headless: false }) {
         this.options = options;
     }
     async initialize() {
-        this.browser = await chromium.launch({
+        const browserType = this.options.browser ?? 'chromium';
+        const launcher = browserType === 'firefox' ? firefox : browserType === 'webkit' ? webkit : chromium;
+        const launchArgs = browserType === 'chromium'
+            ? ['--disable-blink-features=AutomationControlled', '--no-sandbox', '--disable-dev-shm-usage']
+            : [];
+        this.browser = await launcher.launch({
             headless: this.options.headless ?? false,
-            args: [
-                '--disable-blink-features=AutomationControlled',
-                '--no-sandbox',
-                '--disable-dev-shm-usage',
-            ],
+            args: launchArgs,
+            ...(this.options.proxy ? { proxy: this.options.proxy } : {}),
         });
+        // Load storageState from session file if provided
+        const storageState = this.options.sessionPath && fs.existsSync(this.options.sessionPath)
+            ? JSON.parse(fs.readFileSync(this.options.sessionPath, 'utf-8'))
+            : undefined;
         this.context = await this.browser.newContext({
             viewport: this.options.viewport || { width: 1280, height: 720 },
-            userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36',
+            userAgent: this.getRandomUserAgent(),
             locale: 'de-AT',
             timezoneId: 'Europe/Vienna',
+            ...(storageState ? { storageState } : {}),
         });
-        this.page = await this.context.newPage();
-        this.cdpSession = await this.page.context().newCDPSession(this.page);
-        // Enable Accessibility tree access via CDP
-        await this.cdpSession.send('Accessibility.enable');
+        if (storageState) {
+            console.log(`[Driver] Session loaded from ${this.options.sessionPath}`);
+        }
+        const page = await this.context.newPage();
+        this.pages = [page];
+        this.activePageIndex = 0;
+        // CDP only available for Chromium
+        if (browserType === 'chromium') {
+            this.cdpSession = await page.context().newCDPSession(page);
+            await this.cdpSession.send('Accessibility.enable');
+        }
+    }
+    // ─── Tab Management ───────────────────────────────────────────────────────
+    async newTab(url) {
+        if (!this.context)
+            throw new Error('Driver not initialized');
+        const page = await this.context.newPage();
+        this.pages.push(page);
+        const index = this.pages.length - 1;
+        if (url) {
+            await this.gotoPage(page, url);
+        }
+        console.log(`[Driver] New tab opened (index ${index})`);
+        return index;
+    }
+    async switchTab(index) {
+        if (!this.pages[index])
+            throw new Error(`Tab ${index} does not exist`);
+        this.activePageIndex = index;
+        await this.pages[index].bringToFront();
+        // Re-attach CDP session for new active page (Chromium only)
+        if (this.options.browser !== 'firefox' && this.options.browser !== 'webkit') {
+            this.cdpSession = await this.pages[index].context().newCDPSession(this.pages[index]);
+            await this.cdpSession.send('Accessibility.enable');
+        }
+        console.log(`[Driver] Switched to tab ${index}`);
+    }
+    async closeTab(index) {
+        if (!this.pages[index])
+            throw new Error(`Tab ${index} does not exist`);
+        await this.pages[index].close();
+        this.pages.splice(index, 1);
+        if (this.activePageIndex >= this.pages.length) {
+            this.activePageIndex = Math.max(0, this.pages.length - 1);
+        }
+        console.log(`[Driver] Tab ${index} closed`);
+    }
+    get tabCount() {
+        return this.pages.length;
     }
+    // ─── Session Persistence ──────────────────────────────────────────────────
+    async saveSession(filePath) {
+        if (!this.context)
+            throw new Error('Driver not initialized');
+        const state = await this.context.storageState();
+        const dir = path.dirname(filePath);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(filePath, JSON.stringify(state, null, 2), 'utf-8');
+        console.log(`[Driver] Session saved to ${filePath}`);
+    }
+    async hasLoginForm() {
+        const page = this.getPage();
+        const loginIndicators = await page.evaluate(() => {
+            const inputs = Array.from(document.querySelectorAll('input'));
+            return inputs.some(i => i.type === 'password' ||
+                i.name?.toLowerCase().includes('password') ||
+                i.id?.toLowerCase().includes('password'));
+        });
+        return loginIndicators;
+    }
+    // ─── Accessors ────────────────────────────────────────────────────────────
     getPage() {
-        if (!this.page)
+        if (!this.pages[this.activePageIndex])
             throw new Error('Driver not initialized');
-        return this.page;
+        return this.pages[this.activePageIndex];
     }
     getContext() {
         if (!this.context)
@@ -40,7 +117,7 @@ export class SentinelDriver {
     }
     getCDPSession() {
         if (!this.cdpSession)
-            throw new Error('Driver not initialized');
+            throw new Error('CDP session not available (only supported on Chromium)');
         return this.cdpSession;
     }
     async close() {
@@ -49,13 +126,26 @@ export class SentinelDriver {
         }
     }
     async goto(url) {
-        const page = this.getPage();
-        // Use domcontentloaded as primary – faster and sufficient for most pages
+        await this.gotoPage(this.getPage(), url);
+    }
+    // ─── Internal helpers ─────────────────────────────────────────────────────
+    async gotoPage(page, url) {
         await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
-        // Then wait for network to settle (SPA content), but don't crash if it times out
         await page.waitForLoadState('networkidle', { timeout: 5000 }).catch(() => {
             console.warn(`[Driver] networkidle timeout for ${url} – proceeding anyway`);
         });
+        if (this.options.humanLike) {
+            await page.waitForTimeout(300 + Math.random() * 700);
+        }
+    }
+    getRandomUserAgent() {
+        const agents = [
+            'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36',
+            'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36',
+            'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36',
+            'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:125.0) Gecko/20100101 Firefox/125.0',
+        ];
+        return agents[Math.floor(Math.random() * agents.length)];
     }
 }
 //# sourceMappingURL=driver.js.map

package/dist/core/driver.js.map

@@ -1 +1 @@
-{"version":3,"file":"driver.js","sourceRoot":"","sources":["../../src/core/driver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAQtC,MAAM,OAAO,cAAc;IAML;IALZ,OAAO,GAAmB,IAAI,CAAC;IAC/B,OAAO,GAA0B,IAAI,CAAC;IACtC,IAAI,GAAgB,IAAI,CAAC;IACzB,UAAU,GAAsB,IAAI,CAAC;IAE7C,YAAoB,UAAyB,EAAE,QAAQ,EAAE,KAAK,EAAE;QAA5C,YAAO,GAAP,OAAO,CAAqC;IAAG,CAAC;IAEpE,KAAK,CAAC,UAAU;QACd,IAAI,CAAC,OAAO,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC;YACnC,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,QAAQ,IAAI,KAAK;YACxC,IAAI,EAAE;gBACJ,+CAA+C;gBAC/C,cAAc;gBACd,yBAAyB;aAC1B;SACF,CAAC,CAAC;QAEH,IAAI,CAAC,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC;YAC3C,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,QAAQ,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE;YAC/D,SAAS,EACP,iHAAiH;YACnH,MAAM,EAAE,OAAO;YACf,UAAU,EAAE,eAAe;SAC5B,CAAC,CAAC;QAEH,IAAI,CAAC,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QACzC,IAAI,CAAC,UAAU,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAErE,2CAA2C;QAC3C,MAAM,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;IACrD,CAAC;IAED,OAAO;QACL,IAAI,CAAC,IAAI,CAAC,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;QAC1D,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED,UAAU;QACR,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;QAC7D,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,aAAa;QACX,IAAI,CAAC,IAAI,CAAC,UAAU;YAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;QAChE,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QAC7B,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,GAAW;QACpB,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;QAE5B,yEAAyE;QACzE,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,kBAAkB,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;QAExE,iFAAiF;QACjF,MAAM,IAAI,CAAC,gBAAgB,CAAC,aAAa,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;YACvE,OAAO,CAAC,IAAI,CAAC,oCAAoC,GAAG,sBAAsB,CAAC,CAAC;QAC9E,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}
+{"version":3,"file":"driver.js","sourceRoot":"","sources":["../../src/core/driver.ts"],"names":[],"mappings":"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"}

package/dist/core/state-parser.d.ts

@@ -32,6 +32,7 @@ export declare class StateParser {
     constructor(page: Page, cdp: CDPSession);
     invalidateCache(): void;
     parse(): Promise<SimplifiedState>;
+    private parseDOMSnapshot;
     private isInteractive;
     private nodeToUIElement;
 }

package/dist/core/state-parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state-parser.d.ts","sourceRoot":"","sources":["../../src/core/state-parser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAEnD,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE;QAClB,CAAC,EAAE,MAAM,CAAC;QACV,CAAC,EAAE,MAAM,CAAC;QACV,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,KAAK,CAAC,EAAE;QACN,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;KAC7B,CAAC;CACH;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,SAAS,EAAE,CAAC;CACvB;AAID,qBAAa,WAAW;IAKV,OAAO,CAAC,IAAI;IAAQ,OAAO,CAAC,GAAG;IAJ3C,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,WAAW,CAAgC;IACnD,OAAO,CAAC,cAAc,CAAK;gBAEP,IAAI,EAAE,IAAI,EAAU,GAAG,EAAE,UAAU;IAEvD,eAAe;IAKT,KAAK,IAAI,OAAO,CAAC,eAAe,CAAC;IAwDvC,OAAO,CAAC,aAAa;IAerB,OAAO,CAAC,eAAe;CA8BxB"}
+{"version":3,"file":"state-parser.d.ts","sourceRoot":"","sources":["../../src/core/state-parser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAEnD,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE;QAClB,CAAC,EAAE,MAAM,CAAC;QACV,CAAC,EAAE,MAAM,CAAC;QACV,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,KAAK,CAAC,EAAE;QACN,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;KAC7B,CAAC;CACH;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,SAAS,EAAE,CAAC;CACvB;AAID,qBAAa,WAAW;IAKV,OAAO,CAAC,IAAI;IAAQ,OAAO,CAAC,GAAG;IAJ3C,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,WAAW,CAAgC;IACnD,OAAO,CAAC,cAAc,CAAK;gBAEP,IAAI,EAAE,IAAI,EAAU,GAAG,EAAE,UAAU;IAEvD,eAAe;IAKT,KAAK,IAAI,OAAO,CAAC,eAAe,CAAC;YAmEzB,gBAAgB;IA0D9B,OAAO,CAAC,aAAa;IAerB,OAAO,CAAC,eAAe;CA8BxB"}

package/dist/core/state-parser.js

@@ -45,6 +45,16 @@ export class StateParser {
             element.boundingClientRect = { x, y, width, height };
             uiElements.push(element);
         }
+        // DOM-Snapshot als Fallback wenn AOM zu wenige Elemente liefert (z.B. SPAs wie WhatsApp)
+        if (uiElements.length < 5) {
+            const domElements = await this.parseDOMSnapshot();
+            const existingNames = new Set(uiElements.map(e => e.name));
+            for (const el of domElements) {
+                if (!existingNames.has(el.name)) {
+                    uiElements.push(el);
+                }
+            }
+        }
         const state = {
             url: this.page.url(),
             title: await this.page.title(),
@@ -54,6 +64,56 @@ export class StateParser {
         this.cacheTimestamp = Date.now();
         return state;
     }
+    async parseDOMSnapshot() {
+        const rawElements = await this.page.evaluate(() => {
+            const results = [];
+            const seen = new Set();
+            const candidates = Array.from(document.querySelectorAll('a, button, input, select, textarea, [role], [data-testid], [title], [aria-label], [onclick]'));
+            const MAX_ELEMENTS = 200;
+            const viewportWidth = window.innerWidth;
+            const viewportHeight = window.innerHeight;
+            for (const el of candidates) {
+                if (results.length >= MAX_ELEMENTS)
+                    break;
+                const htmlEl = el;
+                const rect = htmlEl.getBoundingClientRect();
+                if (rect.width < 5 || rect.height < 5)
+                    continue;
+                if (rect.top < 0 || rect.left < 0)
+                    continue;
+                if (rect.left >= viewportWidth || rect.top >= viewportHeight)
+                    continue;
+                const name = htmlEl.getAttribute('aria-label') ||
+                    htmlEl.getAttribute('title') ||
+                    htmlEl.getAttribute('data-testid') ||
+                    htmlEl.getAttribute('placeholder') ||
+                    htmlEl.textContent?.trim().slice(0, 80) ||
+                    '';
+                if (!name)
+                    continue;
+                const key = `${name}|${Math.round(rect.x)}|${Math.round(rect.y)}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                results.push({
+                    tag: htmlEl.tagName.toLowerCase(),
+                    role: htmlEl.getAttribute('role') || htmlEl.tagName.toLowerCase(),
+                    name,
+                    x: rect.x,
+                    y: rect.y,
+                    width: rect.width,
+                    height: rect.height,
+                });
+            }
+            return results;
+        });
+        return rawElements.map((el) => ({
+            id: this.elementCounter++,
+            role: el.role,
+            name: el.name,
+            boundingClientRect: { x: el.x, y: el.y, width: el.width, height: el.height },
+        }));
+    }
     isInteractive(node) {
         const interactiveRoles = [
             // Standard form controls

package/dist/core/state-parser.js.map

@@ -1 +1 @@
-{"version":3,"file":"state-parser.js","sourceRoot":"","sources":["../../src/core/state-parser.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"state-parser.js","sourceRoot":"","sources":["../../src/core/state-parser.ts"],"names":[],"mappings":"AA4BA,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAE/B,MAAM,OAAO,WAAW;IAKF;IAAoB;IAJhC,cAAc,GAAG,CAAC,CAAC;IACnB,WAAW,GAA2B,IAAI,CAAC;IAC3C,cAAc,GAAG,CAAC,CAAC;IAE3B,YAAoB,IAAU,EAAU,GAAe;QAAnC,SAAI,GAAJ,IAAI,CAAM;QAAU,QAAG,GAAH,GAAG,CAAY;IAAG,CAAC;IAE3D,eAAe;QACb,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;QACxB,IAAI,CAAC,cAAc,GAAG,CAAC,CAAC;IAC1B,CAAC;IAED,KAAK,CAAC,KAAK;QACT,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,IAAI,IAAI,CAAC,WAAW,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,kBAAkB,EAAE,CAAC;YACzE,OAAO,IAAI,CAAC,WAAW,CAAC;QAC1B,CAAC;QAED,IAAI,CAAC,cAAc,GAAG,CAAC,CAAC;QACxB,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAC;QAErE,0DAA0D;QAC1D,MAAM,gBAAgB,GAAG,KAAK,CAAC,MAAM,CACnC,CAAC,IAAS,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,gBAAgB,CACjE,CAAC;QAEF,oDAAoD;QACpD,MAAM,eAAe,GAAG,MAAM,OAAO,CAAC,UAAU,CAC9C,gBAAgB,CAAC,GAAG,CAAC,CAAC,IAAS,EAAE,EAAE,CACjC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,iBAAiB,EAAE,EAAE,aAAa,EAAE,IAAI,CAAC,gBAAgB,EAAE,CAAC,CAC3E,CACF,CAAC;QAEF,4CAA4C;QAC5C,MAAM,UAAU,GAAgB,EAAE,CAAC;QACnC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,gBAAgB,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACjD,MAAM,IAAI,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC;YACjC,MAAM,MAAM,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC;YAElC,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,UAAU;gBAAE,SAAS;YAEtD,MAAM,SAAS,GAAG,MAAqC,CAAC;YACxD,MAAM,EAAE,KAAK,EAAE,GAAG,SAAS,CAAC,KAAK,CAAC;YAClC,IAAI,CAAC,KAAK,EAAE,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC;gBAAE,SAAS;YAE1D,MAAM,OAAO,GAAG,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;YAC3C,IAAI,CAAC,OAAO;gBAAE,SAAS;YAEvB,MAAM,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAE,CAAC;YAC5B,MAAM,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAE,CAAC;YAC5B,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAE,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAE,CAAC;YACpD,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAE,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAE,CAAC;YAErD,OAAO,CAAC,kBAAkB,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;YACrD,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC3B,CAAC;QAED,yFAAyF;QACzF,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1B,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAClD,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;YAC3D,KAAK,MAAM,EAAE,IAAI,WAAW,EAAE,CAAC;gBAC7B,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;oBAChC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;gBACtB,CAAC;YACH,CAAC;QACH,CAAC;QAED,MAAM,KAAK,GAAoB;YAC7B,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE;YACpB,KAAK,EAAE,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE;YAC9B,QAAQ,EAAE,UAAU;SACrB,CAAC;QAEF,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC;QACzB,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACjC,OAAO,KAAK,CAAC;IACf,CAAC;IAEO,KAAK,CAAC,gBAAgB;QAC5B,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE;YAChD,MAAM,OAAO,GAAU,EAAE,CAAC;YAC1B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;YAE/B,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,gBAAgB,CACrD,6FAA6F,CAC9F,CAAC,CAAC;YAEH,MAAM,YAAY,GAAG,GAAG,CAAC;YACzB,MAAM,aAAa,GAAG,MAAM,CAAC,UAAU,CAAC;YACxC,MAAM,cAAc,GAAG,MAAM,CAAC,WAAW,CAAC;YAE1C,KAAK,MAAM,EAAE,IAAI,UAAU,EAAE,CAAC;gBAC5B,IAAI,OAAO,CAAC,MAAM,IAAI,YAAY;oBAAE,MAAM;gBAC1C,MAAM,MAAM,GAAG,EAAiB,CAAC;gBACjC,MAAM,IAAI,GAAG,MAAM,CAAC,qBAAqB,EAAE,CAAC;gBAE5C,IAAI,IAAI,CAAC,KAAK,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;oBAAE,SAAS;gBAChD,IAAI,IAAI,CAAC,GAAG,GAAG,CAAC,IAAI,IAAI,CAAC,IAAI,GAAG,CAAC;oBAAE,SAAS;gBAC5C,IAAI,IAAI,CAAC,IAAI,IAAI,aAAa,IAAI,IAAI,CAAC,GAAG,IAAI,cAAc;oBAAE,SAAS;gBAEvE,MAAM,IAAI,GACR,MAAM,CAAC,YAAY,CAAC,YAAY,CAAC;oBACjC,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC;oBAC5B,MAAM,CAAC,YAAY,CAAC,aAAa,CAAC;oBAClC,MAAM,CAAC,YAAY,CAAC,aAAa,CAAC;oBAClC,MAAM,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;oBACvC,EAAE,CAAC;gBAEL,IAAI,CAAC,IAAI;oBAAE,SAAS;gBAEpB,MAAM,GAAG,GAAG,GAAG,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;gBAClE,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;oBAAE,SAAS;gBAC5B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBAEd,OAAO,CAAC,IAAI,CAAC;oBACX,GAAG,EAAE,MAAM,CAAC,OAAO,CAAC,WAAW,EAAE;oBACjC,IAAI,EAAE,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,WAAW,EAAE;oBACjE,IAAI;oBACJ,CAAC,EAAE,IAAI,CAAC,CAAC;oBACT,CAAC,EAAE,IAAI,CAAC,CAAC;oBACT,KAAK,EAAE,IAAI,CAAC,KAAK;oBACjB,MAAM,EAAE,IAAI,CAAC,MAAM;iBACpB,CAAC,CAAC;YACL,CAAC;YAED,OAAO,OAAO,CAAC;QACjB,CAAC,CAAC,CAAC;QAEH,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC,EAAO,EAAE,EAAE,CAAC,CAAC;YACnC,EAAE,EAAE,IAAI,CAAC,cAAc,EAAE;YACzB,IAAI,EAAE,EAAE,CAAC,IAAI;YACb,IAAI,EAAE,EAAE,CAAC,IAAI;YACb,kBAAkB,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE;SAC7E,CAAC,CAAC,CAAC;IACN,CAAC;IAEO,aAAa,CAAC,IAAS;QAC7B,MAAM,gBAAgB,GAAG;YACvB,yBAAyB;YACzB,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU;YACnD,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,WAAW,EAAE,QAAQ;YACrD,YAAY,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU;YACzC,2DAA2D;YAC3D,UAAU,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU;YACvC,mDAAmD;YACnD,kBAAkB,EAAE,eAAe,EAAE,cAAc;SACpD,CAAC;QACF,OAAO,gBAAgB,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC;IACtE,CAAC;IAED,sDAAsD;IAC9C,eAAe,CAAC,IAAS;QAC/B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,KAAK,IAAI,SAAS,CAAC;QAC3C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;QACpC,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,EAAE,KAAK,IAAI,EAAE,CAAC;QAElD,8DAA8D;QAC9D,MAAM,aAAa,GAAG,IAAI,IAAI,WAAW,CAAC;QAE1C,8EAA8E;QAC9E,IAAI,CAAC,aAAa,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QAEtD,MAAM,KAAK,GAAoC,EAAE,CAAC;QAClD,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACpB,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;gBACnC,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU;oBAAE,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;gBAChE,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ;oBAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;gBAC5D,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;oBAAE,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;gBAC9D,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;oBAAE,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;YAChE,CAAC;QACH,CAAC;QAED,OAAO;YACL,EAAE,EAAE,IAAI,CAAC,cAAc,EAAE;YACzB,IAAI;YACJ,IAAI,EAAE,aAAa;YACnB,WAAW;YACX,kBAAkB,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE;YACvD,KAAK;SACN,CAAC;IACJ,CAAC;CACF"}

package/dist/core/vision-grounding.d.ts

@@ -0,0 +1,36 @@
+import type { Page } from 'playwright';
+export interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface VisionElement {
+    description: string;
+    boundingBox: BoundingBox;
+    confidence: number;
+}
+/**
+ * Vision-based element grounding using Gemini's multimodal capabilities.
+ * Used as a fallback when the AOM (Accessibility Tree) cannot find an element.
+ */
+export declare class VisionGrounding {
+    private genAI;
+    private model;
+    constructor(apiKey: string);
+    /**
+     * Takes a screenshot of the current page and returns it as a base64 PNG buffer.
+     */
+    takeScreenshot(page: Page): Promise<Buffer>;
+    /**
+     * Asks Gemini Vision to find an element matching the instruction and return its bounding box.
+     * Returns null if the element cannot be found.
+     */
+    findElement(instruction: string, screenshot: Buffer, viewportWidth: number, viewportHeight: number): Promise<BoundingBox | null>;
+    /**
+     * Describes the current page visually using Gemini Vision.
+     * Useful for debugging and agent context building.
+     */
+    describeScreen(screenshot: Buffer): Promise<string>;
+}
+//# sourceMappingURL=vision-grounding.d.ts.map

package/dist/core/vision-grounding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vision-grounding.d.ts","sourceRoot":"","sources":["../../src/core/vision-grounding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAGvC,MAAM,WAAW,WAAW;IAC1B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,WAAW,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,KAAK,CAAqB;IAClC,OAAO,CAAC,KAAK,CAAM;gBAEP,MAAM,EAAE,MAAM;IAO1B;;OAEG;IACG,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC;IAIjD;;;OAGG;IACG,WAAW,CACf,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAsE9B;;;OAGG;IACG,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAuB1D"}

package/dist/core/vision-grounding.js

@@ -0,0 +1,118 @@
+import { GoogleGenerativeAI } from '@google/generative-ai';
+/**
+ * Vision-based element grounding using Gemini's multimodal capabilities.
+ * Used as a fallback when the AOM (Accessibility Tree) cannot find an element.
+ */
+export class VisionGrounding {
+    genAI;
+    model;
+    constructor(apiKey) {
+        this.genAI = new GoogleGenerativeAI(apiKey);
+        const modelName = process.env.GEMINI_VERSION;
+        if (!modelName)
+            throw new Error('GEMINI_VERSION must be set in .env');
+        this.model = this.genAI.getGenerativeModel({ model: modelName });
+    }
+    /**
+     * Takes a screenshot of the current page and returns it as a base64 PNG buffer.
+     */
+    async takeScreenshot(page) {
+        return await page.screenshot({ type: 'png', fullPage: false });
+    }
+    /**
+     * Asks Gemini Vision to find an element matching the instruction and return its bounding box.
+     * Returns null if the element cannot be found.
+     */
+    async findElement(instruction, screenshot, viewportWidth, viewportHeight) {
+        const base64 = screenshot.toString('base64');
+        const prompt = `
+You are a browser automation assistant analyzing a screenshot.
+
+Task: Find the UI element that matches this instruction: "${instruction}"
+
+The screenshot is ${viewportWidth}x${viewportHeight} pixels.
+
+Return the bounding box of the element as JSON with these fields:
+- x: left edge in pixels
+- y: top edge in pixels  
+- width: element width in pixels
+- height: element height in pixels
+- found: true if element was found, false if not visible
+
+Be precise. If the element is not visible in the screenshot, set found to false.
+    `;
+        const schema = {
+            type: 'object',
+            properties: {
+                found: { type: 'boolean' },
+                x: { type: 'number' },
+                y: { type: 'number' },
+                width: { type: 'number' },
+                height: { type: 'number' },
+                reasoning: { type: 'string' },
+            },
+            required: ['found', 'reasoning'],
+        };
+        try {
+            const result = await this.model.generateContent({
+                contents: [
+                    {
+                        role: 'user',
+                        parts: [
+                            { text: prompt },
+                            { inlineData: { mimeType: 'image/png', data: base64 } },
+                        ],
+                    },
+                ],
+                generationConfig: {
+                    responseMimeType: 'application/json',
+                    responseSchema: schema,
+                },
+            });
+            const parsed = JSON.parse(result.response.text());
+            if (!parsed.found) {
+                console.warn(`[Vision] Element not found: "${instruction}" — ${parsed.reasoning}`);
+                return null;
+            }
+            console.log(`[Vision] Found element: "${instruction}" at (${parsed.x}, ${parsed.y}) — ${parsed.reasoning}`);
+            return {
+                x: parsed.x ?? 0,
+                y: parsed.y ?? 0,
+                width: parsed.width ?? 50,
+                height: parsed.height ?? 30,
+            };
+        }
+        catch (err) {
+            console.error(`[Vision] findElement failed: ${err.message}`);
+            return null;
+        }
+    }
+    /**
+     * Describes the current page visually using Gemini Vision.
+     * Useful for debugging and agent context building.
+     */
+    async describeScreen(screenshot) {
+        const base64 = screenshot.toString('base64');
+        try {
+            const result = await this.model.generateContent({
+                contents: [
+                    {
+                        role: 'user',
+                        parts: [
+                            {
+                                text: 'Describe this webpage screenshot briefly: what page is it, what are the main UI elements visible, and what actions are possible?',
+                            },
+                            { inlineData: { mimeType: 'image/png', data: base64 } },
+                        ],
+                    },
+                ],
+            });
+            return result.response.text();
+        }
+        catch (err) {
+            console.error(`[Vision] describeScreen failed: ${err.message}`);
+            return 'Could not describe screen.';
+        }
+    }
+}
+//# sourceMappingURL=vision-grounding.js.map

package/dist/core/vision-grounding.js.map

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

package/dist/index.d.ts

@@ -1,10 +1,25 @@
+import { EventEmitter } from 'events';
 import type { Page, BrowserContext } from 'playwright';
+import type { BrowserType, ProxyOptions } from './core/driver.js';
+export type { BrowserType, ProxyOptions };
 import type { ActOptions, ActionResult } from './api/act.js';
 import type { ObserveResult } from './api/observe.js';
 import type { SchemaInput } from './utils/gemini.js';
+import type { AgentRunOptions, AgentResult, AgentStepEvent } from './agent/agent-loop.js';
+import type { BoundingBox } from './core/vision-grounding.js';
+import type { LLMProvider } from './utils/llm-provider.js';
+export type { LLMProvider };
+import type { RecordedWorkflow } from './recorder/workflow-recorder.js';
+import { SentinelError, ActionError, ExtractionError, NavigationError, AgentError, NotInitializedError } from './types/errors.js';
+export { SentinelError, ActionError, ExtractionError, NavigationError, AgentError, NotInitializedError };
+export type { RecordedWorkflow };
+export { GeminiProvider } from './utils/providers/gemini-provider.js';
+export { OpenAIProvider } from './utils/providers/openai-provider.js';
+export { ClaudeProvider } from './utils/providers/claude-provider.js';
+export { OllamaProvider } from './utils/providers/ollama-provider.js';
 import { z } from 'zod';
 export { z };
-export type { ActOptions, ActionResult, ObserveResult };
+export type { ActOptions, ActionResult, ObserveResult, AgentRunOptions, AgentResult, AgentStepEvent, BoundingBox };
 export interface SentinelOptions {
     /** Gemini API key */
     apiKey: string;
@@ -25,19 +40,50 @@ export interface SentinelOptions {
      * Set to false to always fetch a fresh AOM state.
      */
     enableCaching?: boolean;
+    /**
+     * Enable Vision Grounding fallback via Gemini Vision when AOM cannot find an element (default: false).
+     */
+    visionFallback?: boolean;
+    /**
+     * Browser engine to use (default: 'chromium'). Firefox and WebKit do not support CDP/AOM.
+     */
+    browser?: BrowserType;
+    /**
+     * Proxy configuration.
+     */
+    proxy?: ProxyOptions;
+    /**
+     * Add random human-like delays between actions (default: false).
+     */
+    humanLike?: boolean;
+    /**
+     * Path to a session file to load/save cookies & storage state.
+     */
+    sessionPath?: string;
+    /**
+     * Custom LLM provider. If set, overrides the default Gemini provider.
+     * @example new OpenAIProvider({ apiKey: '...', model: 'gpt-4o' })
+     */
+    provider?: LLMProvider;
     /**
      * How long (ms) to wait for the DOM to settle after navigation/actions (default: 3000).
      */
     domSettleTimeoutMs?: number;
 }
-export declare class Sentinel {
+export declare class Sentinel extends EventEmitter {
     private driver;
     private stateParser;
     private actionEngine;
     private extractionEngine;
     private observationEngine;
     private verifier;
+    private agentLoop;
+    private visionGrounding;
+    private recorder;
+    private tokenTracker;
     private gemini;
+    private readonly visionFallback;
+    private readonly apiKey;
     private readonly verbose;
     private readonly enableCaching;
     private readonly domSettleTimeoutMs;
@@ -49,6 +95,26 @@ export declare class Sentinel {
     init(): Promise<void>;
     goto(url: string): Promise<void>;
     close(): Promise<void>;
+    /** Start recording all actions into a replayable workflow. */
+    startRecording(name?: string): void;
+    /** Stop recording and return the captured workflow. */
+    stopRecording(): RecordedWorkflow;
+    /** Export a recorded workflow as TypeScript code. */
+    exportWorkflowAsCode(workflow: RecordedWorkflow): string;
+    /** Export a recorded workflow as JSON string. */
+    exportWorkflowAsJSON(workflow: RecordedWorkflow): string;
+    /** Replay a recorded workflow step by step. */
+    replay(workflow: RecordedWorkflow): Promise<void>;
+    /** Get accumulated token usage and estimated cost. */
+    getTokenUsage(): {
+        totalInputTokens: number;
+        totalOutputTokens: number;
+        totalTokens: number;
+        estimatedCostUsd: number;
+        entries: import("./utils/token-tracker.js").TokenUsageEntry[];
+    };
+    /** Export token usage log as JSON to a file path. */
+    exportLogs(filePath: string): void;
     /**
      * Perform an action on the page described in natural language.
      *
@@ -80,6 +146,49 @@ export declare class Sentinel {
      * const actions = await sentinel.observe('Find login-related elements');
      */
     observe(instruction?: string): Promise<ObserveResult[]>;
+    /**
+     * Save the current browser session (cookies, localStorage) to a JSON file.
+     */
+    saveSession(filePath: string): Promise<void>;
+    /**
+     * Open a new browser tab, optionally navigating to a URL.
+     * @returns The index of the new tab.
+     */
+    newTab(url?: string): Promise<number>;
+    /**
+     * Switch to a tab by index.
+     */
+    switchTab(index: number): Promise<void>;
+    /**
+     * Close a tab by index.
+     */
+    closeTab(index: number): Promise<void>;
+    /** Number of open tabs */
+    get tabCount(): number;
+    /**
+     * Check if the current page has a login form.
+     */
+    hasLoginForm(): Promise<boolean>;
+    /**
+     * Take a screenshot of the current page.
+     * @returns PNG image as a Buffer
+     */
+    screenshot(): Promise<Buffer>;
+    /**
+     * Describe the current page visually using Gemini Vision.
+     * Requires visionFallback: true in SentinelOptions.
+     */
+    describeScreen(): Promise<string>;
+    /**
+     * Run an autonomous multi-step agent to achieve a high-level goal.
+     *
+     * @param goal     Natural language goal, e.g. "Go to Amazon, search for laptop, extract top 5 results"
+     * @param options  Optional: maxSteps (default 15), onStep callback
+     *
+     * @example
+     * const result = await sentinel.run('Search for "TypeScript" on Google and extract the first 3 results');
+     */
+    run(goal: string, options?: AgentRunOptions): Promise<AgentResult>;
     private log;
 }
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAKvD,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAG7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,CAAC,EAAE,CAAC;AACb,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,CAAC;AAExD,MAAM,WAAW,eAAe;IAC9B,qBAAqB;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,wCAAwC;IACxC,QAAQ,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7C;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACpB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;OAEG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,qBAAa,QAAQ;IACnB,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,WAAW,CAA4B;IAC/C,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,gBAAgB,CAAiC;IACzD,OAAO,CAAC,iBAAiB,CAAkC;IAC3D,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,MAAM,CAAgB;IAE9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAY;IACpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAU;IACxC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;gBAEhC,OAAO,EAAE,eAAe;IAcpC,kDAAkD;IAClD,IAAI,IAAI,IAAI,IAAI,CAEf;IAED,4DAA4D;IAC5D,IAAI,OAAO,IAAI,cAAc,CAE5B;IAIK,IAAI;IAcJ,IAAI,CAAC,GAAG,EAAE,MAAM;IAMhB,KAAK;IAOX;;;;;;;;OAQG;IACG,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,YAAY,CAAC;IAsClG;;;;;;;;OAQG;IACG,OAAO,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAOzE;;;;;;;OAOG;IACG,OAAO,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAS7D,OAAO,CAAC,GAAG;CAKZ"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}