athena-browser-mcp 2.0.4 → 2.0.5

package/README.md

@@ -6,12 +6,42 @@
 
 MCP server for AI browser automation - 18 tools with semantic element targeting.
 
-## Design Philosophy
+## Why Athena?
 
-1. **Semantic element IDs** - Stable `eid` references survive DOM mutations
-2. **XML state responses** - Structured page state with layers, actionables, and diffs
-3. **Multi-frame support** - Extract content from iframes (cookie consent, widgets)
-4. **Automatic retry** - Stale element recovery with fresh snapshot
+LLM agents face two hard constraints: limited context windows and expensive tokens. Yet browser automation requires understanding complex, ever-changing page state. Traditional tools dump raw accessibility trees or screenshots, wasting precious context and creating needle-in-haystack problems where agents struggle to locate relevant elements.
+
+Athena solves this with **semantic page snapshots** - compact, structured representations designed for LLM consumption:
+
+- **Token-efficient** - Hierarchical layers and regions eliminate noise, fitting more page understanding into less context
+- **High recall** - Structured XML with semantic element IDs lets agents find elements without scanning entire DOM trees
+- **Intuitive querying** - `find_elements` with semantic filters (kind, label, region) so agents ask for what they need
+- **Stable references** - Semantic `eid`s survive DOM mutations, eliminating stale element errors
+
+The result: fewer tokens, faster task completion, and higher-quality outputs with fewer errors.
+
+## Benchmark
+
+Comparison between Athena Browser MCP and Playwright MCP on real-world browser automation tasks. Tests run in Claude Code with Claude Opus 4.5.
+
+| #   | Task                                                                                  | Agent          | Result     | Tokens Used | Time Taken |
+| --- | ------------------------------------------------------------------------------------- | -------------- | ---------- | ----------- | ---------- |
+| 1   | Login → Create wishlist "Summer Escapes" → Add beach property (Airbnb)                | **Athena**     | ✅ Success | 92,870      | 2m 08s     |
+|     |                                                                                       | **Playwright** | ✅ Success | 137,063     | 5m 23s     |
+| 2   | Bangkok Experiences → Food tour → Extract itinerary & pricing (Airbnb)                | **Athena**     | ✅ Success | 87,194      | 3m 27s     |
+|     |                                                                                       | **Playwright** | ✅ Success | 94,942      | 3m 38s     |
+| 3   | Miami → Beachfront stays under $300 → Top 3 names + prices (Airbnb)                   | **Athena**     | ✅ Success | 124,597     | 5m 38s     |
+|     |                                                                                       | **Playwright** | ✅ Success | 122,077     | 4m 51s     |
+| 4   | Paris → "Play" section → Top 5 titles + descriptions (Airbnb)                         | **Athena**     | ❌ Failed  | 146,575     | 4m 15s     |
+|     |                                                                                       | **Playwright** | ❌ Failed  | 189,495     | 7m 37s     |
+| 5   | Navigate Apple → find iPhone → configure iPhone 17 → add 256GB Black → confirm in bag | **Athena**     | ✅ Success | 65,629      | 3m 30s     |
+|     |                                                                                       | **Playwright** | ✅ Success | 102,754     | 6m 59s     |
+
+**Total Results:**
+
+- **Tokens**: Athena used **125,341 fewer tokens** (~19.4% more efficient)
+- **Time**: Athena completed tasks **9m 30s faster** (~33.4% faster)
+
+_Benchmark on a larger dataset coming soon._
 
 ## Architecture
 

package/dist/src/browser/page-network-tracker.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Page Network Tracker
+ *
+ * Tracks in-flight network requests for a page and provides a reliable
+ * "network quiet" wait mechanism. Unlike Playwright's waitForLoadState('networkidle'),
+ * this tracks requests triggered after page load (e.g., by user actions).
+ *
+ * Uses a generation counter to safely handle navigation - late events from
+ * previous documents are ignored.
+ */
+import type { Page } from 'playwright';
+/**
+ * Tracks network requests for a single page.
+ *
+ * Attach to a page via `attach()`, then use `waitForQuiet()` to wait for
+ * network activity to settle. Call `markNavigation()` when navigating to
+ * safely reset state without race conditions.
+ */
+export declare class PageNetworkTracker {
+    private page;
+    private inflightCount;
+    private generation;
+    private currentGeneration;
+    private quietTimer;
+    private quietWindowMs;
+    private quietResolvers;
+    private onRequest;
+    private onRequestFinished;
+    private onRequestFailed;
+    /**
+     * Attach network event listeners to a page.
+     *
+     * Must be called before `waitForQuiet()` can be used.
+     * Safe to call multiple times - will detach previous listeners first.
+     */
+    attach(page: Page): void;
+    /**
+     * Detach all event listeners and cleanup timers.
+     *
+     * Call this when the page is closed or no longer needs tracking.
+     */
+    detach(): void;
+    /**
+     * Mark that a navigation occurred.
+     *
+     * This safely resets state by bumping the generation counter, so any
+     * late events from the previous document are ignored. Use this instead
+     * of directly resetting state to avoid race conditions.
+     */
+    markNavigation(): void;
+    /**
+     * Wait for network to become quiet (no inflight requests for quietWindowMs).
+     *
+     * @param timeoutMs - Maximum time to wait before returning false
+     * @param quietWindowMs - Time with 0 inflight requests to consider "idle"
+     * @returns true if network became quiet, false if timed out (never throws)
+     */
+    waitForQuiet(timeoutMs: number, quietWindowMs?: number): Promise<boolean>;
+    /**
+     * Get current inflight request count (for debugging/testing).
+     */
+    getInflightCount(): number;
+    /**
+     * Check if tracker is attached to a page.
+     */
+    isAttached(): boolean;
+    private cancelQuietTimer;
+    private checkQuiet;
+    private startQuietTimer;
+}
+/**
+ * Get or create a network tracker for a page.
+ *
+ * Note: This does NOT automatically attach the tracker.
+ * Call `tracker.attach(page)` after getting the tracker.
+ */
+export declare function getOrCreateTracker(page: Page): PageNetworkTracker;
+/**
+ * Remove and detach the tracker for a page.
+ *
+ * Call this when a page is closed to ensure proper cleanup.
+ */
+export declare function removeTracker(page: Page): void;
+/**
+ * Check if a page has a tracker attached.
+ */
+export declare function hasTracker(page: Page): boolean;
+//# sourceMappingURL=page-network-tracker.d.ts.map

package/dist/src/browser/page-network-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-network-tracker.d.ts","sourceRoot":"","sources":["../../../src/browser/page-network-tracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAW,MAAM,YAAY,CAAC;AAKhD;;;;;;GAMG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,iBAAiB,CAAK;IAG9B,OAAO,CAAC,UAAU,CAA+B;IACjD,OAAO,CAAC,aAAa,CAAmC;IACxD,OAAO,CAAC,cAAc,CAAyE;IAG/F,OAAO,CAAC,SAAS,CAAyC;IAC1D,OAAO,CAAC,iBAAiB,CAAyC;IAClE,OAAO,CAAC,eAAe,CAAyC;IAEhE;;;;;OAKG;IACH,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IA6CxB;;;;OAIG;IACH,MAAM,IAAI,IAAI;IA6Bd;;;;;;OAMG;IACH,cAAc,IAAI,IAAI;IAkDtB;;;;;;OAMG;IACG,YAAY,CAChB,SAAS,EAAE,MAAM,EACjB,aAAa,GAAE,MAAgC,GAC9C,OAAO,CAAC,OAAO,CAAC;IAuBnB;;OAEG;IACH,gBAAgB,IAAI,MAAM;IAI1B;;OAEG;IACH,UAAU,IAAI,OAAO;IAMrB,OAAO,CAAC,gBAAgB;IAOxB,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,eAAe;CAexB;AAYD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,kBAAkB,CAOjE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAM9C;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAE9C"}

package/dist/src/browser/page-network-tracker.js

@@ -0,0 +1,271 @@
+/**
+ * Page Network Tracker
+ *
+ * Tracks in-flight network requests for a page and provides a reliable
+ * "network quiet" wait mechanism. Unlike Playwright's waitForLoadState('networkidle'),
+ * this tracks requests triggered after page load (e.g., by user actions).
+ *
+ * Uses a generation counter to safely handle navigation - late events from
+ * previous documents are ignored.
+ */
+/** Default quiet window - time with 0 inflight requests to consider "idle" */
+const DEFAULT_QUIET_WINDOW_MS = 500;
+/**
+ * Tracks network requests for a single page.
+ *
+ * Attach to a page via `attach()`, then use `waitForQuiet()` to wait for
+ * network activity to settle. Call `markNavigation()` when navigating to
+ * safely reset state without race conditions.
+ */
+export class PageNetworkTracker {
+    page = null;
+    inflightCount = 0;
+    generation = 0;
+    currentGeneration = 0;
+    // Quiet window state
+    quietTimer = null;
+    quietWindowMs = DEFAULT_QUIET_WINDOW_MS;
+    quietResolvers = [];
+    // Event handlers (stored for cleanup via page.off())
+    onRequest = null;
+    onRequestFinished = null;
+    onRequestFailed = null;
+    /**
+     * Attach network event listeners to a page.
+     *
+     * Must be called before `waitForQuiet()` can be used.
+     * Safe to call multiple times - will detach previous listeners first.
+     */
+    attach(page) {
+        // Detach from previous page if any
+        if (this.page) {
+            this.detach();
+        }
+        this.page = page;
+        this.generation++;
+        this.currentGeneration = this.generation;
+        this.inflightCount = 0;
+        const gen = this.currentGeneration;
+        this.onRequest = (req) => {
+            // Ignore stale events from previous document
+            if (this.currentGeneration !== gen)
+                return;
+            // Ignore websockets (persistent connections)
+            if (req.resourceType() === 'websocket')
+                return;
+            this.inflightCount++;
+            this.cancelQuietTimer();
+        };
+        this.onRequestFinished = (req) => {
+            if (this.currentGeneration !== gen)
+                return;
+            if (req.resourceType() === 'websocket')
+                return;
+            // Never go below 0 (handles edge cases)
+            this.inflightCount = Math.max(0, this.inflightCount - 1);
+            this.checkQuiet();
+        };
+        this.onRequestFailed = (req) => {
+            if (this.currentGeneration !== gen)
+                return;
+            if (req.resourceType() === 'websocket')
+                return;
+            this.inflightCount = Math.max(0, this.inflightCount - 1);
+            this.checkQuiet();
+        };
+        page.on('request', this.onRequest);
+        page.on('requestfinished', this.onRequestFinished);
+        page.on('requestfailed', this.onRequestFailed);
+    }
+    /**
+     * Detach all event listeners and cleanup timers.
+     *
+     * Call this when the page is closed or no longer needs tracking.
+     */
+    detach() {
+        if (this.page) {
+            if (this.onRequest) {
+                this.page.off('request', this.onRequest);
+            }
+            if (this.onRequestFinished) {
+                this.page.off('requestfinished', this.onRequestFinished);
+            }
+            if (this.onRequestFailed) {
+                this.page.off('requestfailed', this.onRequestFailed);
+            }
+        }
+        this.onRequest = null;
+        this.onRequestFinished = null;
+        this.onRequestFailed = null;
+        this.page = null;
+        // Cancel any pending quiet timers
+        this.cancelQuietTimer();
+        // Reject all pending waiters with false (not idle)
+        for (const { resolve, timeoutId } of this.quietResolvers) {
+            clearTimeout(timeoutId);
+            resolve(false);
+        }
+        this.quietResolvers = [];
+    }
+    /**
+     * Mark that a navigation occurred.
+     *
+     * This safely resets state by bumping the generation counter, so any
+     * late events from the previous document are ignored. Use this instead
+     * of directly resetting state to avoid race conditions.
+     */
+    markNavigation() {
+        this.generation++;
+        this.currentGeneration = this.generation;
+        this.inflightCount = 0;
+        this.cancelQuietTimer();
+        // Re-attach handlers with new generation if we have a page
+        if (this.page) {
+            const page = this.page;
+            // Detach old handlers
+            if (this.onRequest) {
+                page.off('request', this.onRequest);
+            }
+            if (this.onRequestFinished) {
+                page.off('requestfinished', this.onRequestFinished);
+            }
+            if (this.onRequestFailed) {
+                page.off('requestfailed', this.onRequestFailed);
+            }
+            // Create new handlers with updated generation
+            const gen = this.currentGeneration;
+            this.onRequest = (req) => {
+                if (this.currentGeneration !== gen)
+                    return;
+                if (req.resourceType() === 'websocket')
+                    return;
+                this.inflightCount++;
+                this.cancelQuietTimer();
+            };
+            this.onRequestFinished = (req) => {
+                if (this.currentGeneration !== gen)
+                    return;
+                if (req.resourceType() === 'websocket')
+                    return;
+                this.inflightCount = Math.max(0, this.inflightCount - 1);
+                this.checkQuiet();
+            };
+            this.onRequestFailed = (req) => {
+                if (this.currentGeneration !== gen)
+                    return;
+                if (req.resourceType() === 'websocket')
+                    return;
+                this.inflightCount = Math.max(0, this.inflightCount - 1);
+                this.checkQuiet();
+            };
+            page.on('request', this.onRequest);
+            page.on('requestfinished', this.onRequestFinished);
+            page.on('requestfailed', this.onRequestFailed);
+        }
+    }
+    /**
+     * Wait for network to become quiet (no inflight requests for quietWindowMs).
+     *
+     * @param timeoutMs - Maximum time to wait before returning false
+     * @param quietWindowMs - Time with 0 inflight requests to consider "idle"
+     * @returns true if network became quiet, false if timed out (never throws)
+     */
+    async waitForQuiet(timeoutMs, quietWindowMs = DEFAULT_QUIET_WINDOW_MS) {
+        // Store the quiet window for checkQuiet() to use
+        this.quietWindowMs = quietWindowMs;
+        return new Promise((resolve) => {
+            const hardTimeout = setTimeout(() => {
+                // Remove this resolver from the list
+                const index = this.quietResolvers.findIndex((r) => r.timeoutId === hardTimeout);
+                if (index !== -1) {
+                    this.quietResolvers.splice(index, 1);
+                }
+                resolve(false);
+            }, timeoutMs);
+            this.quietResolvers.push({ resolve, timeoutId: hardTimeout });
+            // If already idle, start quiet timer immediately
+            if (this.inflightCount === 0) {
+                this.startQuietTimer();
+            }
+        });
+    }
+    /**
+     * Get current inflight request count (for debugging/testing).
+     */
+    getInflightCount() {
+        return this.inflightCount;
+    }
+    /**
+     * Check if tracker is attached to a page.
+     */
+    isAttached() {
+        return this.page !== null;
+    }
+    // --- Private methods ---
+    cancelQuietTimer() {
+        if (this.quietTimer) {
+            clearTimeout(this.quietTimer);
+            this.quietTimer = null;
+        }
+    }
+    checkQuiet() {
+        if (this.inflightCount === 0 && this.quietResolvers.length > 0) {
+            this.startQuietTimer();
+        }
+    }
+    startQuietTimer() {
+        // Cancel any existing timer first
+        this.cancelQuietTimer();
+        // Start quiet window timer
+        this.quietTimer = setTimeout(() => {
+            this.quietTimer = null;
+            // Resolve all pending waiters
+            for (const { resolve, timeoutId } of this.quietResolvers) {
+                clearTimeout(timeoutId);
+                resolve(true);
+            }
+            this.quietResolvers = [];
+        }, this.quietWindowMs);
+    }
+}
+// --- Global Registry ---
+/**
+ * WeakMap registry for page-scoped trackers.
+ *
+ * Using WeakMap keyed by Page object provides automatic cleanup when
+ * the Page is garbage collected, avoiding memory leaks.
+ */
+const trackers = new WeakMap();
+/**
+ * Get or create a network tracker for a page.
+ *
+ * Note: This does NOT automatically attach the tracker.
+ * Call `tracker.attach(page)` after getting the tracker.
+ */
+export function getOrCreateTracker(page) {
+    let tracker = trackers.get(page);
+    if (!tracker) {
+        tracker = new PageNetworkTracker();
+        trackers.set(page, tracker);
+    }
+    return tracker;
+}
+/**
+ * Remove and detach the tracker for a page.
+ *
+ * Call this when a page is closed to ensure proper cleanup.
+ */
+export function removeTracker(page) {
+    const tracker = trackers.get(page);
+    if (tracker) {
+        tracker.detach();
+        trackers.delete(page);
+    }
+}
+/**
+ * Check if a page has a tracker attached.
+ */
+export function hasTracker(page) {
+    return trackers.has(page);
+}
+//# sourceMappingURL=page-network-tracker.js.map

package/dist/src/browser/page-network-tracker.js.map

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

package/dist/src/browser/page-stabilization.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Page Stabilization Utilities
+ *
+ * Shared utilities for waiting on network activity to settle.
+ * Used by session-manager and execute-action.
+ *
+ * IMPORTANT: This module uses PageNetworkTracker for reliable network idle
+ * detection. Unlike Playwright's waitForLoadState('networkidle'), the tracker
+ * monitors actual request/response events and works for in-page actions
+ * (not just navigation load states).
+ */
+import type { Page } from 'playwright';
+/** Default timeout for network idle waiting after actions (ms) */
+export declare const ACTION_NETWORK_IDLE_TIMEOUT_MS = 3000;
+/** Default timeout for network idle waiting after navigation (ms) */
+export declare const NAVIGATION_NETWORK_IDLE_TIMEOUT_MS = 5000;
+/** Default quiet window - time with 0 inflight requests to consider "idle" (ms) */
+export declare const DEFAULT_QUIET_WINDOW_MS = 500;
+/**
+ * Wait for network to become quiet (no pending requests for 500ms).
+ *
+ * This catches pending API calls triggered by actions. Uses PageNetworkTracker
+ * which monitors request/response events directly, providing reliable detection
+ * of network activity for both navigation and in-page actions.
+ *
+ * Unlike Playwright's waitForLoadState('networkidle'), this works correctly
+ * for fetch/XHR requests triggered by user actions after page load.
+ *
+ * @param page - Playwright Page instance
+ * @param timeoutMs - Maximum time to wait for network idle
+ * @param quietWindowMs - Time with 0 inflight requests to consider "idle" (default: 500ms)
+ * @returns Whether network became idle (false = timed out, but that's OK - never throws)
+ */
+export declare function waitForNetworkQuiet(page: Page, timeoutMs: number, quietWindowMs?: number): Promise<boolean>;
+//# sourceMappingURL=page-stabilization.d.ts.map

package/dist/src/browser/page-stabilization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-stabilization.d.ts","sourceRoot":"","sources":["../../../src/browser/page-stabilization.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAGvC,kEAAkE;AAClE,eAAO,MAAM,8BAA8B,OAAO,CAAC;AAEnD,qEAAqE;AACrE,eAAO,MAAM,kCAAkC,OAAO,CAAC;AAEvD,mFAAmF;AACnF,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAE3C;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,MAAM,EACjB,aAAa,GAAE,MAAgC,GAC9C,OAAO,CAAC,OAAO,CAAC,CASlB"}

package/dist/src/browser/page-stabilization.js

@@ -0,0 +1,42 @@
+/**
+ * Page Stabilization Utilities
+ *
+ * Shared utilities for waiting on network activity to settle.
+ * Used by session-manager and execute-action.
+ *
+ * IMPORTANT: This module uses PageNetworkTracker for reliable network idle
+ * detection. Unlike Playwright's waitForLoadState('networkidle'), the tracker
+ * monitors actual request/response events and works for in-page actions
+ * (not just navigation load states).
+ */
+import { getOrCreateTracker } from './page-network-tracker.js';
+/** Default timeout for network idle waiting after actions (ms) */
+export const ACTION_NETWORK_IDLE_TIMEOUT_MS = 3000;
+/** Default timeout for network idle waiting after navigation (ms) */
+export const NAVIGATION_NETWORK_IDLE_TIMEOUT_MS = 5000;
+/** Default quiet window - time with 0 inflight requests to consider "idle" (ms) */
+export const DEFAULT_QUIET_WINDOW_MS = 500;
+/**
+ * Wait for network to become quiet (no pending requests for 500ms).
+ *
+ * This catches pending API calls triggered by actions. Uses PageNetworkTracker
+ * which monitors request/response events directly, providing reliable detection
+ * of network activity for both navigation and in-page actions.
+ *
+ * Unlike Playwright's waitForLoadState('networkidle'), this works correctly
+ * for fetch/XHR requests triggered by user actions after page load.
+ *
+ * @param page - Playwright Page instance
+ * @param timeoutMs - Maximum time to wait for network idle
+ * @param quietWindowMs - Time with 0 inflight requests to consider "idle" (default: 500ms)
+ * @returns Whether network became idle (false = timed out, but that's OK - never throws)
+ */
+export async function waitForNetworkQuiet(page, timeoutMs, quietWindowMs = DEFAULT_QUIET_WINDOW_MS) {
+    const tracker = getOrCreateTracker(page);
+    // Ensure tracker is attached (may not be if page was created outside SessionManager)
+    if (!tracker.isAttached()) {
+        tracker.attach(page);
+    }
+    return tracker.waitForQuiet(timeoutMs, quietWindowMs);
+}
+//# sourceMappingURL=page-stabilization.js.map

package/dist/src/browser/page-stabilization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-stabilization.js","sourceRoot":"","sources":["../../../src/browser/page-stabilization.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE/D,kEAAkE;AAClE,MAAM,CAAC,MAAM,8BAA8B,GAAG,IAAI,CAAC;AAEnD,qEAAqE;AACrE,MAAM,CAAC,MAAM,kCAAkC,GAAG,IAAI,CAAC;AAEvD,mFAAmF;AACnF,MAAM,CAAC,MAAM,uBAAuB,GAAG,GAAG,CAAC;AAE3C;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,IAAU,EACV,SAAiB,EACjB,gBAAwB,uBAAuB;IAE/C,MAAM,OAAO,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;IAEzC,qFAAqF;IACrF,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;QAC1B,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACvB,CAAC;IAED,OAAO,OAAO,CAAC,YAAY,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;AACxD,CAAC"}

package/dist/src/browser/session-manager.d.ts

@@ -194,6 +194,10 @@ export declare class SessionManager {
     /**
      * Navigate a page to a URL
      *
+     * Waits for both DOM ready and network idle to ensure the page is fully loaded.
+     * Network idle timeout is generous (5s) but never throws - pages with persistent
+     * connections (websockets, long-polling, analytics) may never reach idle.
+     *
      * @param page_id - The page identifier
      * @param url - URL to navigate to
      * @throws Error if page not found or navigation fails

package/dist/src/browser/session-manager.d.ts.map

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

package/dist/src/browser/session-manager.js

@@ -9,6 +9,9 @@ import { PlaywrightCdpClient } from '../cdp/playwright-cdp-client.js';
 import { PageRegistry } from './page-registry.js';
 import { getLogger } from '../shared/services/logging.service.js';
 import { BrowserSessionError } from '../shared/errors/browser-session.error.js';
+import { observationAccumulator } from '../observation/index.js';
+import { waitForNetworkQuiet, NAVIGATION_NETWORK_IDLE_TIMEOUT_MS } from './page-stabilization.js';
+import { getOrCreateTracker, removeTracker } from './page-network-tracker.js';
 /** Default CDP port for Athena Browser */
 const DEFAULT_CDP_PORT = 9223;
 /** Default CDP host */
@@ -307,6 +310,13 @@ export class SessionManager {
         this.registry.updateMetadata(handle.page_id, {
             url: page.url(),
         });
+        // Inject observation accumulator for DOM mutation tracking
+        await observationAccumulator.inject(page);
+        // Attach network tracker for this page
+        const tracker = getOrCreateTracker(page);
+        tracker.attach(page);
+        // Cleanup tracker on unexpected page close
+        page.on('close', () => removeTracker(page));
         this.logger.debug('Adopted page', { page_id: handle.page_id, url: page.url() });
         return handle;
     }
@@ -336,6 +346,13 @@ export class SessionManager {
                 url: page.url(),
             });
         }
+        // Inject observation accumulator for DOM mutation tracking
+        await observationAccumulator.inject(page);
+        // Attach network tracker for this page
+        const tracker = getOrCreateTracker(page);
+        tracker.attach(page);
+        // Cleanup tracker on unexpected page close
+        page.on('close', () => removeTracker(page));
         return handle;
     }
     /**
@@ -406,6 +423,8 @@ export class SessionManager {
         if (!handle) {
             return false;
         }
+        // Cleanup network tracker before closing
+        removeTracker(handle.page);
         try {
             // Close CDP session first
             await handle.cdp.close();
@@ -434,6 +453,10 @@ export class SessionManager {
     /**
      * Navigate a page to a URL
      *
+     * Waits for both DOM ready and network idle to ensure the page is fully loaded.
+     * Network idle timeout is generous (5s) but never throws - pages with persistent
+     * connections (websockets, long-polling, analytics) may never reach idle.
+     *
      * @param page_id - The page identifier
      * @param url - URL to navigate to
      * @throws Error if page not found or navigation fails
@@ -444,10 +467,21 @@ export class SessionManager {
             throw new Error('Page not found');
         }
         try {
+            // Wait for DOM ready first (fast baseline)
             await handle.page.goto(url, { waitUntil: 'domcontentloaded' });
+            // Mark navigation on tracker (bumps generation to ignore stale events)
+            const tracker = getOrCreateTracker(handle.page);
+            tracker.markNavigation();
+            // Then wait for network to settle (catches API calls)
+            const networkIdle = await waitForNetworkQuiet(handle.page, NAVIGATION_NETWORK_IDLE_TIMEOUT_MS);
+            if (!networkIdle) {
+                this.logger.debug('Network did not reach idle state', { page_id, url });
+            }
             this.registry.updateMetadata(page_id, {
                 url: handle.page.url(),
             });
+            // Re-inject observation accumulator (new document context)
+            await observationAccumulator.inject(handle.page);
             this.logger.debug('Navigated page', { page_id, url });
         }
         catch (error) {