cbrowser 10.5.0 → 10.5.1

package/dist/browser.js

@@ -10,6 +10,9 @@ import { mergeConfig, getPaths, ensureDirectories } from "./config.js";
 import { BUILTIN_PERSONAS, getPersona } from "./personas.js";
 import { DEVICE_PRESETS, LOCATION_PRESETS } from "./types.js";
 import { runCognitiveJourney, isApiKeyConfigured, } from "./cognitive/index.js";
+import { SessionManager } from "./browser/session-manager.js";
+import { SelectorCacheManager } from "./browser/selector-cache.js";
+import { OverlayHandler } from "./browser/overlay-handler.js";
 // Browser-specific fast launch args for performance optimization
 const BROWSER_LAUNCH_ARGS = {
     // Chromium args - reduces cold start time significantly
@@ -41,7 +44,7 @@ const BROWSER_LAUNCH_ARGS = {
     webkit: [],
 };
 // Legacy alias for backward compatibility
-const FAST_LAUNCH_ARGS = BROWSER_LAUNCH_ARGS.chromium;
+const _FAST_LAUNCH_ARGS = BROWSER_LAUNCH_ARGS.chromium;
 export class CBrowser {
     config;
     paths;
@@ -54,9 +57,27 @@ export class CBrowser {
     harEntries = [];
     isRecordingHar = false;
     skipSessionRestore = false;
+    // Modular components (extracted for maintainability)
+    sessionManager;
+    selectorCacheManager;
+    overlayHandler;
     constructor(userConfig = {}) {
         this.config = mergeConfig(userConfig);
         this.paths = ensureDirectories(getPaths(this.config.dataDir));
+        // Initialize modular components
+        this.sessionManager = new SessionManager({
+            sessionsDir: this.paths.sessionsDir,
+            viewportWidth: this.config.viewportWidth,
+            viewportHeight: this.config.viewportHeight,
+            verbose: this.config.verbose,
+        });
+        this.selectorCacheManager = new SelectorCacheManager({
+            dataDir: this.paths.dataDir,
+            verbose: this.config.verbose,
+        });
+        this.overlayHandler = new OverlayHandler({
+            verbose: this.config.verbose,
+        });
     }
     // =========================================================================
     // Session State Persistence
@@ -380,7 +401,7 @@ export class CBrowser {
      * Add a network mock at runtime.
      */
     async addNetworkMock(mock) {
-        const page = await this.getPage();
+        await this.getPage(); // Ensure page exists
         await this.setupNetworkMocks([mock]);
     }
     /**
@@ -428,7 +449,7 @@ export class CBrowser {
         });
         this.page.on("response", async (response) => {
             const key = response.url() + response.request().method();
-            const networkResponse = {
+            const _networkResponse = {
                 url: response.url(),
                 status: response.status(),
                 statusText: response.statusText(),
@@ -1277,7 +1298,7 @@ export class CBrowser {
      */
     async selectCustomDropdownOption(trigger, optionValue, options = {}) {
         const page = await this.getPage();
-        const timeout = options.timeout ?? 5000;
+        const _timeout = options.timeout ?? 5000;
         try {
             // Click the trigger to open the dropdown
             if (options.verbose)
@@ -1285,7 +1306,7 @@ export class CBrowser {
             await trigger.click();
             // Wait for dropdown options to appear
             // Try multiple common patterns for option containers
-            const optionSelectors = [
+            const _optionSelectors = [
                 // Alpine.js / Headless UI patterns
                 '[x-show]:not([x-show="false"])',
                 '[role="listbox"]',
@@ -1379,7 +1400,6 @@ export class CBrowser {
      * Prioritizes: exact text match > non-sticky elements > shorter text (closer match)
      */
     async findBestClickCandidate(locator, searchText) {
-        const page = await this.getPage();
         const count = await locator.count();
         if (count === 0)
             return null;
@@ -1394,7 +1414,6 @@ export class CBrowser {
             try {
                 const info = await el.evaluate((element, search) => {
                     const text = element.textContent?.trim() || '';
-                    const style = getComputedStyle(element);
                     // Check if element is in a sticky/fixed container
                     let inStickyContainer = false;
                     let parent = element;
@@ -1690,7 +1709,7 @@ export class CBrowser {
      * Handle filling a custom input (hidden input with custom UI).
      * Handles autocomplete, datepickers, custom text inputs, etc.
      */
-    async handleCustomInput(hiddenInput, value, options = {}) {
+    async handleCustomInput(hiddenInput, value, _options = {}) {
         const page = await this.getPage();
         try {
             // Get input info to help find its visible counterpart
@@ -1861,320 +1880,22 @@ export class CBrowser {
     }
     // =========================================================================
     // Overlay Detection & Dismissal (v7.4.14)
+    // Delegated to OverlayHandler module for maintainability
     // =========================================================================
-    /** Common overlay patterns for detection */
-    static OVERLAY_PATTERNS = [
-        {
-            type: "cookie",
-            selectors: [
-                '[class*="cookie"]', '[id*="cookie"]', '[class*="consent"]', '[id*="consent"]',
-                '[class*="gdpr"]', '[id*="gdpr"]', '[class*="cc-"]', '[id*="cc-"]',
-                '[class*="CookieBanner"]', '[class*="cookie-banner"]', '[class*="cookie_banner"]',
-                '[aria-label*="cookie" i]', '[aria-label*="consent" i]',
-            ],
-            closeButtons: [
-                'button:has-text("Accept")', 'button:has-text("Accept All")', 'button:has-text("Accept all")',
-                'button:has-text("I agree")', 'button:has-text("Agree")', 'button:has-text("Got it")',
-                'button:has-text("OK")', 'button:has-text("Allow")', 'button:has-text("Allow All")',
-                'button:has-text("Close")', '[class*="accept"]', '[class*="agree"]',
-                '[id*="accept"]', '[data-action="accept"]',
-            ],
-        },
-        {
-            type: "age-verify",
-            selectors: [
-                '[class*="age-verif"]', '[id*="age-verif"]', '[class*="age_verif"]',
-                '[class*="age-gate"]', '[id*="age-gate"]', '[class*="agegate"]',
-                '[class*="age-check"]', '[id*="age-check"]',
-                '[role="dialog"]', '[aria-modal="true"]',
-            ],
-            closeButtons: [
-                'button:has-text("I am 18")', 'button:has-text("I am 21")',
-                'button:has-text("I\'m 18")', 'button:has-text("I\'m 21")',
-                'button:has-text("I am over")', 'button:has-text("I\'m over")',
-                'button:has-text("Yes")', 'button:has-text("Enter")',
-                'button:has-text("Confirm")', 'button:has-text("Verify")',
-                'button:has-text("Enter Site")', 'button:has-text("Continue")',
-            ],
-        },
-        {
-            type: "newsletter",
-            selectors: [
-                '[class*="newsletter"]', '[id*="newsletter"]',
-                '[class*="popup"]', '[id*="popup"]',
-                '[class*="subscribe"]', '[id*="subscribe"]',
-                '[class*="signup-modal"]', '[class*="email-capture"]',
-            ],
-            closeButtons: [
-                'button:has-text("Close")', 'button:has-text("No thanks")',
-                'button:has-text("Not now")', 'button:has-text("Maybe later")',
-                '[class*="close"]', '[aria-label="Close"]', '[aria-label="close"]',
-                'button[class*="dismiss"]',
-            ],
-        },
-    ];
     /**
      * Detect and dismiss overlays (cookie consent, age verification, newsletter popups).
      * Constitutional safety: Yellow zone - logs all dismissed overlays.
      */
     async dismissOverlay(options = { type: "auto" }) {
         const page = await this.getPage();
-        const timeout = options.timeout ?? 5000;
-        const details = [];
-        const maxPasses = 5; // Prevent infinite loops
-        try {
-            // Multi-pass dismissal: some sites reveal new overlays after dismissing the first
-            for (let pass = 0; pass < maxPasses; pass++) {
-                const detected = await this.detectOverlays(page, options);
-                // Custom selector fallback on first pass if nothing detected
-                if (pass === 0 && detected.length === 0 && options.customSelector) {
-                    try {
-                        const customEl = page.locator(options.customSelector).first();
-                        if (await customEl.isVisible({ timeout: 2000 })) {
-                            await customEl.click();
-                            await page.waitForTimeout(500);
-                            this.audit("dismiss-overlay", options.customSelector, "yellow", "success");
-                            details.push({
-                                type: "custom",
-                                selector: options.customSelector,
-                                dismissed: true,
-                                closeMethod: "custom-selector-click",
-                            });
-                            continue; // Re-detect after custom dismiss
-                        }
-                    }
-                    catch { }
-                }
-                if (detected.length === 0)
-                    break; // No more overlays
-                // Attempt to dismiss each detected overlay
-                let dismissedThisPass = false;
-                for (const overlay of detected) {
-                    const result = await this.tryDismissOverlay(page, overlay, timeout);
-                    details.push(result);
-                    if (result.dismissed) {
-                        this.audit("dismiss-overlay", result.selector, "yellow", "success");
-                        dismissedThisPass = true;
-                    }
-                }
-                if (!dismissedThisPass)
-                    break; // Can't dismiss anything, stop
-                // Wait for any new overlays to appear
-                await page.waitForTimeout(800);
-            }
-            const overlaysDismissed = details.filter(d => d.dismissed).length;
-            const overlaysFound = details.length;
-            return {
-                dismissed: overlaysDismissed > 0,
-                overlaysFound,
-                overlaysDismissed,
-                details,
-                screenshot: await this.screenshot(),
-                suggestion: overlaysDismissed === 0 && overlaysFound > 0
-                    ? "Overlays detected but could not be dismissed automatically. Try providing a custom selector."
-                    : undefined,
-            };
-        }
-        catch (error) {
-            return {
-                dismissed: false,
-                overlaysFound: 0,
-                overlaysDismissed: 0,
-                details,
-                screenshot: await this.screenshot(),
-                suggestion: `Error during overlay detection: ${error instanceof Error ? error.message : String(error)}`,
-            };
-        }
-    }
-    /** Text content keywords for overlay type classification */
-    static OVERLAY_TEXT_PATTERNS = {
-        "age-verify": ["age verif", "18+", "21+", "over 18", "over 21", "years or older", "age gate", "age check", "must be 18", "must be 21", "legal age", "adult content"],
-        "cookie": ["cookie", "consent", "gdpr", "privacy policy", "we use cookies", "this site uses cookies", "accept cookies"],
-        "newsletter": ["newsletter", "subscribe", "sign up for", "email updates", "stay updated", "join our mailing"],
-    };
-    /**
-     * Classify an overlay by its text content.
-     */
-    classifyOverlayType(text) {
-        const lowerText = text.toLowerCase();
-        for (const [type, keywords] of Object.entries(CBrowser.OVERLAY_TEXT_PATTERNS)) {
-            if (keywords.some(kw => lowerText.includes(kw))) {
-                return type;
-            }
-        }
-        return "unknown";
-    }
-    /**
-     * Detect overlays on the page by analyzing position, z-index, pattern matching, and text content.
-     * Returns overlays sorted by z-index (highest first) so the topmost blocking overlay is dismissed first.
-     */
-    async detectOverlays(page, options) {
-        const detected = [];
-        try {
-            // Unified detection: find all high-z-index fixed/absolute elements AND known pattern selectors
-            const rawOverlays = await page.evaluate(() => {
-                const results = [];
-                const seen = new Set();
-                const allElements = Array.from(document.querySelectorAll("*"));
-                for (let i = 0; i < allElements.length; i++) {
-                    const el = allElements[i];
-                    if (seen.has(el))
-                        continue;
-                    const cs = window.getComputedStyle(el);
-                    const pos = cs.position;
-                    const zIndex = parseInt(cs.zIndex) || 0;
-                    const rect = el.getBoundingClientRect();
-                    const isDialog = el.getAttribute("role") === "dialog" || el.getAttribute("aria-modal") === "true";
-                    // Match: high z-index overlay OR dialog role
-                    if (((pos === "fixed" || pos === "absolute") && zIndex > 100 && rect.width > 200 && rect.height > 80) || isDialog) {
-                        if (rect.width < 50 || rect.height < 30)
-                            continue;
-                        if (cs.display === "none" || cs.visibility === "hidden" || cs.opacity === "0")
-                            continue;
-                        const text = (el.textContent || "").substring(0, 300).trim();
-                        let selector = el.tagName.toLowerCase();
-                        if (el.id)
-                            selector = `#${el.id}`;
-                        else if (el.className && typeof el.className === "string") {
-                            const cls = el.className.split(/\s+/).filter((c) => c.length > 0 && c.length < 40)[0];
-                            if (cls)
-                                selector = `.${cls}`;
-                        }
-                        seen.add(el);
-                        results.push({
-                            selector,
-                            text,
-                            zIndex: zIndex || (isDialog ? 99999 : 0),
-                            position: pos,
-                            role: el.getAttribute("role"),
-                            ariaModal: el.getAttribute("aria-modal"),
-                            width: Math.round(rect.width),
-                            height: Math.round(rect.height),
-                        });
-                    }
-                }
-                return results;
-            });
-            // Classify and filter overlays
-            for (const raw of rawOverlays) {
-                const type = this.classifyOverlayType(raw.text);
-                // Filter by requested type
-                if (options.type && options.type !== "auto" && type !== options.type && type !== "unknown")
-                    continue;
-                detected.push({
-                    type,
-                    selector: raw.selector,
-                    text: raw.text.substring(0, 200),
-                    zIndex: raw.zIndex,
-                    position: raw.position,
-                });
+        const result = await this.overlayHandler.dismissOverlays(page, options, () => this.screenshot());
+        // Log dismissed overlays to audit trail
+        for (const detail of result.details) {
+            if (detail.dismissed) {
+                this.audit("dismiss-overlay", detail.selector, "yellow", "success");
             }
         }
-        catch { }
-        // Sort by z-index descending — dismiss topmost overlay first
-        detected.sort((a, b) => b.zIndex - a.zIndex);
-        // Deduplicate: keep only one per type (highest z-index)
-        const seen = new Set();
-        const deduped = [];
-        for (const d of detected) {
-            if (d.type !== "unknown" && seen.has(d.type))
-                continue;
-            seen.add(d.type);
-            deduped.push(d);
-        }
-        return deduped;
-    }
-    /**
-     * Try clicking a button, with force fallback if another element intercepts.
-     */
-    async tryClickOverlayButton(btn, timeout) {
-        try {
-            await btn.click({ timeout: Math.min(timeout, 3000) });
-            return true;
-        }
-        catch {
-            // If normal click fails (e.g., another overlay intercepts), try force click
-            try {
-                await btn.click({ force: true, timeout: Math.min(timeout, 2000) });
-                return true;
-            }
-            catch {
-                return false;
-            }
-        }
-    }
-    /**
-     * Attempt to dismiss a single detected overlay.
-     */
-    async tryDismissOverlay(page, overlay, timeout) {
-        // Collect all close button selectors to try: matched pattern first, then all patterns, then generic
-        const closeButtonSets = [];
-        // First: close buttons from the matched overlay type pattern
-        const matchedPattern = CBrowser.OVERLAY_PATTERNS.find(p => p.type === overlay.type);
-        if (matchedPattern) {
-            closeButtonSets.push({ source: "matched-pattern", selectors: matchedPattern.closeButtons });
-        }
-        // Second: close buttons from all other patterns (in case classification was imperfect)
-        for (const pattern of CBrowser.OVERLAY_PATTERNS) {
-            if (pattern.type !== overlay.type) {
-                closeButtonSets.push({ source: `${pattern.type}-pattern`, selectors: pattern.closeButtons });
-            }
-        }
-        // Third: generic close buttons
-        closeButtonSets.push({
-            source: "generic",
-            selectors: [
-                'button[aria-label="Close"]', 'button[aria-label="close"]',
-                'button[aria-label="Dismiss"]', '[role="button"][aria-label="Close"]',
-                'button[class*="close"]', '[class*="close-btn"]', '[class*="closeBtn"]',
-                'button:has-text("×")', 'button:has-text("✕")', 'button:has-text("X")',
-                'button:has-text("Close")', 'button:has-text("Dismiss")',
-                'button:has-text("No thanks")', 'button:has-text("Not now")',
-            ],
-        });
-        // Try all close button sets
-        for (const set of closeButtonSets) {
-            for (const btnSelector of set.selectors) {
-                try {
-                    const btn = page.locator(btnSelector).first();
-                    if (await btn.isVisible({ timeout: 800 })) {
-                        const clicked = await this.tryClickOverlayButton(btn, timeout);
-                        if (clicked) {
-                            await page.waitForTimeout(500);
-                            return {
-                                type: overlay.type,
-                                selector: overlay.selector,
-                                dismissed: true,
-                                closeMethod: `${set.source}: ${btnSelector}`,
-                            };
-                        }
-                    }
-                }
-                catch { }
-            }
-        }
-        // Last resort: Try pressing Escape
-        try {
-            await page.keyboard.press("Escape");
-            await page.waitForTimeout(500);
-            // Check if overlay is still visible
-            const stillVisible = await page.$(overlay.selector);
-            if (!stillVisible || !(await stillVisible.isVisible())) {
-                return {
-                    type: overlay.type,
-                    selector: overlay.selector,
-                    dismissed: true,
-                    closeMethod: "escape-key",
-                };
-            }
-        }
-        catch { }
-        return {
-            type: overlay.type,
-            selector: overlay.selector,
-            dismissed: false,
-            error: "Could not find a way to dismiss this overlay",
-        };
+        return result;
     }
     /**
      * Find alternative selectors for an element.
@@ -2188,9 +1909,9 @@ export class CBrowser {
             for (const el of elements.slice(0, 10)) {
                 const text = await el.textContent().catch(() => "");
                 const ariaLabel = await el.getAttribute("aria-label").catch(() => "");
-                const title = await el.getAttribute("title").catch(() => "");
+                const _title = await el.getAttribute("title").catch(() => "");
                 const id = await el.getAttribute("id").catch(() => "");
-                const className = await el.getAttribute("class").catch(() => "");
+                const _className = await el.getAttribute("class").catch(() => "");
                 // Check if text matches original selector
                 if (text && originalSelector.toLowerCase().includes(text.toLowerCase().trim().substring(0, 20))) {
                     alternatives.push({
@@ -2226,54 +1947,10 @@ export class CBrowser {
     }
     // =========================================================================
     // Tier 5: Self-Healing Selector Cache (v5.0.0)
+    // Delegated to SelectorCache module for maintainability
     // =========================================================================
-    selectorCache = null;
     /**
-     * Get the selector cache file path.
-     */
-    getSelectorCachePath() {
-        return join(this.paths.dataDir, "selector-cache.json");
-    }
-    /**
-     * Load the selector cache from disk.
-     */
-    loadSelectorCache() {
-        if (this.selectorCache)
-            return this.selectorCache;
-        const cachePath = this.getSelectorCachePath();
-        if (existsSync(cachePath)) {
-            try {
-                const data = readFileSync(cachePath, "utf-8");
-                this.selectorCache = JSON.parse(data);
-                return this.selectorCache;
-            }
-            catch (e) {
-                if (this.config.verbose) {
-                    console.debug(`[CBrowser] Corrupted selector cache, starting fresh: ${e.message}`);
-                }
-            }
-        }
-        this.selectorCache = { version: 1, entries: {} };
-        return this.selectorCache;
-    }
-    /**
-     * Save the selector cache to disk.
-     */
-    saveSelectorCache() {
-        if (!this.selectorCache)
-            return;
-        const cachePath = this.getSelectorCachePath();
-        writeFileSync(cachePath, JSON.stringify(this.selectorCache, null, 2));
-    }
-    /**
-     * Get cache key for a selector (includes domain for context).
-     */
-    getSelectorCacheKey(selector, domain) {
-        const d = domain || this.getCurrentDomain();
-        return `${d}::${selector.toLowerCase()}`;
-    }
-    /**
-     * Get current page domain.
+     * Get current page domain for cache key generation.
      */
     getCurrentDomain() {
         try {
@@ -2287,122 +1964,50 @@ export class CBrowser {
         }
         return "unknown";
     }
+    /**
+     * Sync the current domain to the selector cache manager.
+     */
+    syncCacheDomain() {
+        this.selectorCacheManager.setCurrentDomain(this.getCurrentDomain());
+    }
     /**
      * Cache a working alternative selector for future use.
      */
     cacheAlternativeSelector(original, working, reason = "Alternative found") {
-        // Reject empty or meaningless selectors
-        if (!working || working.trim() === "" || working === 'text=""' || working === "text=''") {
-            if (this.config.verbose) {
-                console.log(`⚠️ Rejected invalid selector for caching: "${working}"`);
-            }
-            return;
-        }
-        const cache = this.loadSelectorCache();
-        const key = this.getSelectorCacheKey(original);
-        const domain = this.getCurrentDomain();
-        cache.entries[key] = {
-            originalSelector: original,
-            workingSelector: working,
-            domain,
-            successCount: 1,
-            failCount: 0,
-            lastUsed: new Date().toISOString(),
-            reason,
-        };
-        this.saveSelectorCache();
-        if (this.config.verbose) {
-            console.log(`📦 Cached healed selector: "${original}" → "${working}"`);
-        }
+        this.syncCacheDomain();
+        this.selectorCacheManager.cacheAlternative(original, working, reason);
     }
     /**
      * Get a cached alternative selector if available.
      */
     getCachedSelector(original) {
-        const cache = this.loadSelectorCache();
-        const key = this.getSelectorCacheKey(original);
-        const entry = cache.entries[key] || null;
-        if (entry && (entry.workingSelector === 'text=""' || entry.workingSelector === "text=''" || entry.workingSelector.trim() === "")) {
-            return null; // Reject invalid cached selectors
-        }
-        return entry;
+        this.syncCacheDomain();
+        return this.selectorCacheManager.getCached(original);
     }
     /**
      * Update cache entry statistics.
      */
     updateCacheStats(original, success) {
-        const cache = this.loadSelectorCache();
-        const key = this.getSelectorCacheKey(original);
-        const entry = cache.entries[key];
-        if (entry) {
-            if (success) {
-                entry.successCount++;
-            }
-            else {
-                entry.failCount++;
-            }
-            entry.lastUsed = new Date().toISOString();
-            this.saveSelectorCache();
-        }
+        this.syncCacheDomain();
+        this.selectorCacheManager.updateStats(original, success);
     }
     /**
      * Get selector cache statistics.
      */
     getSelectorCacheStats() {
-        const cache = this.loadSelectorCache();
-        const entries = Object.values(cache.entries);
-        const byDomain = {};
-        for (const entry of entries) {
-            byDomain[entry.domain] = (byDomain[entry.domain] || 0) + 1;
-        }
-        const topHealedSelectors = entries
-            .sort((a, b) => b.successCount - a.successCount)
-            .slice(0, 10)
-            .map(e => ({
-            original: e.originalSelector,
-            working: e.workingSelector,
-            heals: e.successCount,
-        }));
-        return {
-            totalEntries: entries.length,
-            totalHeals: entries.reduce((sum, e) => sum + e.successCount, 0),
-            byDomain,
-            topHealedSelectors,
-        };
+        return this.selectorCacheManager.getStats();
     }
     /**
      * Clear the selector cache.
      */
     clearSelectorCache(domain) {
-        const cache = this.loadSelectorCache();
-        let cleared = 0;
-        if (domain) {
-            // Clear only for specific domain
-            for (const [key, entry] of Object.entries(cache.entries)) {
-                if (entry.domain === domain) {
-                    delete cache.entries[key];
-                    cleared++;
-                }
-            }
-        }
-        else {
-            // Clear all
-            cleared = Object.keys(cache.entries).length;
-            cache.entries = {};
-        }
-        this.saveSelectorCache();
-        return cleared;
+        return this.selectorCacheManager.clear(domain);
     }
     /**
      * List all cached selectors.
      */
     listCachedSelectors(domain) {
-        const cache = this.loadSelectorCache();
-        let entries = Object.values(cache.entries);
-        if (domain) {
-            entries = entries.filter(e => e.domain === domain);
-        }
-        return entries.sort((a, b) => b.successCount - a.successCount);
+        return this.selectorCacheManager.list(domain);
     }
     // =========================================================================
     // Tier 5: AI Test Generation (v5.0.0)
@@ -2675,7 +2280,7 @@ export class CBrowser {
         let code = `// Playwright Test Code\n// Generated for: ${url}\n// Date: ${new Date().toISOString()}\n\n`;
         code += `import { test, expect } from '@playwright/test';\n\n`;
         for (const testDef of tests) {
-            const testName = testDef.name.toLowerCase().replace(/\s+/g, "-");
+            const _testName = testDef.name.toLowerCase().replace(/\s+/g, "-");
             code += `test('${testDef.name}', async ({ page }) => {\n`;
             code += `  // ${testDef.description}\n\n`;
             for (const step of testDef.steps) {
@@ -2913,7 +2518,7 @@ export class CBrowser {
      * Assert a condition using natural language.
      */
     async assert(assertion) {
-        const page = await this.getPage();
+        await this.getPage(); // Ensure page exists
         try {
             // Parse the assertion
             const result = await this.evaluateAssertion(assertion);
@@ -3272,238 +2877,56 @@ export class CBrowser {
      */
     async saveSession(name) {
         const page = await this.getPage();
-        const context = this.context;
-        const cookies = await context.cookies();
-        let localStorage = {};
-        try {
-            localStorage = await page.evaluate(() => {
-                const data = {};
-                for (let i = 0; i < window.localStorage.length; i++) {
-                    const key = window.localStorage.key(i);
-                    if (key)
-                        data[key] = window.localStorage.getItem(key) || "";
-                }
-                return data;
-            });
-        }
-        catch {
-            // localStorage may be inaccessible on about:blank or restricted pages
-        }
-        let sessionStorage = {};
-        try {
-            sessionStorage = await page.evaluate(() => {
-                const data = {};
-                for (let i = 0; i < window.sessionStorage.length; i++) {
-                    const key = window.sessionStorage.key(i);
-                    if (key)
-                        data[key] = window.sessionStorage.getItem(key) || "";
-                }
-                return data;
-            });
-        }
-        catch {
-            // sessionStorage may be inaccessible on about:blank or restricted pages
-        }
-        const url = page.url();
-        const domain = new URL(url).hostname;
-        const session = {
-            name,
-            created: new Date().toISOString(),
-            lastUsed: new Date().toISOString(),
-            domain,
-            url,
-            viewport: {
-                width: this.config.viewportWidth,
-                height: this.config.viewportHeight,
-            },
-            cookies: cookies,
-            localStorage,
-            sessionStorage,
-        };
-        const sessionPath = join(this.paths.sessionsDir, `${name}.json`);
-        writeFileSync(sessionPath, JSON.stringify(session, null, 2));
+        await this.sessionManager.save(name, page, this.context);
     }
     /**
      * Load a saved session.
      */
     async loadSession(name) {
-        const sessionPath = join(this.paths.sessionsDir, `${name}.json`);
-        if (!existsSync(sessionPath)) {
-            return { success: false, name, cookiesRestored: 0, localStorageKeysRestored: 0, sessionStorageKeysRestored: 0 };
-        }
-        const session = JSON.parse(readFileSync(sessionPath, "utf-8"));
         const page = await this.getPage();
-        const context = this.context;
-        const result = {
-            success: true,
-            name,
-            cookiesRestored: session.cookies.length,
-            localStorageKeysRestored: Object.keys(session.localStorage).length,
-            sessionStorageKeysRestored: Object.keys(session.sessionStorage).length,
-        };
-        // Cross-domain warning
-        const currentUrl = page.url();
-        if (currentUrl && currentUrl !== "about:blank") {
-            try {
-                const currentDomain = new URL(currentUrl).hostname;
-                if (session.domain && currentDomain !== session.domain) {
-                    result.warning = `Session '${name}' was saved for ${session.domain} but current page is ${currentDomain}. Some cookies may not apply.`;
-                }
-            }
-            catch {
-                // URL parsing failed, skip warning
-            }
-        }
-        // Restore cookies
-        if (session.cookies.length > 0) {
-            await context.addCookies(session.cookies);
-        }
-        // Navigate to saved URL
-        await page.goto(session.url, { waitUntil: "networkidle" });
-        // Restore localStorage
-        await page.evaluate((data) => {
-            for (const [key, value] of Object.entries(data)) {
-                window.localStorage.setItem(key, value);
-            }
-        }, session.localStorage);
-        // Restore sessionStorage
-        await page.evaluate((data) => {
-            for (const [key, value] of Object.entries(data)) {
-                window.sessionStorage.setItem(key, value);
-            }
-        }, session.sessionStorage);
-        // Refresh to apply storage
-        await page.reload({ waitUntil: "networkidle" });
-        // Update lastUsed
-        session.lastUsed = new Date().toISOString();
-        writeFileSync(sessionPath, JSON.stringify(session, null, 2));
-        return result;
+        return this.sessionManager.load(name, page, this.context);
     }
     /**
      * List all saved session names.
      */
     listSessions() {
-        const files = readdirSync(this.paths.sessionsDir);
-        return files.filter((f) => f.endsWith(".json") && f !== "last-session.json").map((f) => f.replace(".json", ""));
+        return this.sessionManager.list();
     }
     /**
      * List all saved sessions with rich metadata.
      */
     listSessionsDetailed() {
-        const files = readdirSync(this.paths.sessionsDir);
-        const sessions = [];
-        for (const file of files) {
-            if (!file.endsWith(".json") || file === "last-session.json")
-                continue;
-            const filePath = join(this.paths.sessionsDir, file);
-            try {
-                const data = JSON.parse(readFileSync(filePath, "utf-8"));
-                const stats = statSync(filePath);
-                sessions.push({
-                    name: data.name || file.replace(".json", ""),
-                    created: data.created,
-                    lastUsed: data.lastUsed,
-                    domain: data.domain,
-                    url: data.url,
-                    cookies: data.cookies?.length || 0,
-                    localStorageKeys: Object.keys(data.localStorage || {}).length,
-                    sessionStorageKeys: Object.keys(data.sessionStorage || {}).length,
-                    sizeBytes: stats.size,
-                });
-            }
-            catch (e) {
-                if (this.config.verbose) {
-                    console.debug(`[CBrowser] Skipping malformed session file ${file}: ${e.message}`);
-                }
-            }
-        }
-        return sessions.sort((a, b) => new Date(b.lastUsed).getTime() - new Date(a.lastUsed).getTime());
+        return this.sessionManager.listDetailed();
     }
     /**
      * Get detailed info for a single session.
      */
     getSessionDetails(name) {
-        const sessionPath = join(this.paths.sessionsDir, `${name}.json`);
-        if (!existsSync(sessionPath))
-            return null;
-        try {
-            return JSON.parse(readFileSync(sessionPath, "utf-8"));
-        }
-        catch (e) {
-            if (this.config.verbose) {
-                console.debug(`[CBrowser] Failed to load session ${name}: ${e.message}`);
-            }
-            return null;
-        }
+        return this.sessionManager.getDetails(name);
     }
     /**
      * Delete a saved session.
      */
     deleteSession(name) {
-        const sessionPath = join(this.paths.sessionsDir, `${name}.json`);
-        if (existsSync(sessionPath)) {
-            unlinkSync(sessionPath);
-            return true;
-        }
-        return false;
+        return this.sessionManager.delete(name);
     }
     /**
      * Delete sessions older than a given number of days.
      */
     cleanupSessions(olderThanDays) {
-        const cutoff = Date.now() - olderThanDays * 24 * 60 * 60 * 1000;
-        const deleted = [];
-        const kept = [];
-        const files = readdirSync(this.paths.sessionsDir);
-        for (const file of files) {
-            if (!file.endsWith(".json") || file === "last-session.json")
-                continue;
-            const filePath = join(this.paths.sessionsDir, file);
-            const name = file.replace(".json", "");
-            try {
-                const data = JSON.parse(readFileSync(filePath, "utf-8"));
-                const lastUsed = new Date(data.lastUsed).getTime();
-                if (lastUsed < cutoff) {
-                    unlinkSync(filePath);
-                    deleted.push(name);
-                }
-                else {
-                    kept.push(name);
-                }
-            }
-            catch {
-                kept.push(name);
-            }
-        }
-        return { deleted, kept };
+        return this.sessionManager.cleanup(olderThanDays);
     }
     /**
      * Export a session to a portable JSON file.
      */
     exportSession(name, outputPath) {
-        const sessionPath = join(this.paths.sessionsDir, `${name}.json`);
-        if (!existsSync(sessionPath))
-            return false;
-        const data = readFileSync(sessionPath, "utf-8");
-        writeFileSync(outputPath, data);
-        return true;
+        return this.sessionManager.export(name, outputPath);
     }
     /**
      * Import a session from a JSON file.
      */
     importSession(inputPath, name) {
-        if (!existsSync(inputPath))
-            return false;
-        try {
-            const data = JSON.parse(readFileSync(inputPath, "utf-8"));
-            data.name = name;
-            const sessionPath = join(this.paths.sessionsDir, `${name}.json`);
-            writeFileSync(sessionPath, JSON.stringify(data, null, 2));
-            return true;
-        }
-        catch {
-            return false;
-        }
+        return this.sessionManager.import(inputPath, name);
     }
     // =========================================================================
     // Journeys
@@ -3537,7 +2960,7 @@ export class CBrowser {
                 return {
                     persona: personaName,
                     goal,
-                    steps: cognitiveResult.frictionPoints.map((fp, i) => ({
+                    steps: cognitiveResult.frictionPoints.map((fp, _i) => ({
                         action: fp.type,
                         target: fp.element || 'page',
                         result: fp.monologue.substring(0, 100),