agent-web-interface 4.0.0

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

@@ -0,0 +1,235 @@
+/**
+ * Page Network Tracker
+ *
+ * Tracks in-flight network requests for a page and provides a reliable
+ * "network quiet" wait mechanism. Unlike Puppeteer's waitForNetworkIdle(),
+ * 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) {
+        if (this.page) {
+            this.detach();
+        }
+        this.page = page;
+        this.generation++;
+        this.currentGeneration = this.generation;
+        this.inflightCount = 0;
+        this.createAndAttachHandlers(page);
+    }
+    /**
+     * Detach all event listeners and cleanup timers.
+     *
+     * Call this when the page is closed or no longer needs tracking.
+     */
+    detach() {
+        if (this.page) {
+            this.removeHandlers(this.page);
+        }
+        this.onRequest = null;
+        this.onRequestFinished = null;
+        this.onRequestFailed = null;
+        this.page = null;
+        this.cancelQuietTimer();
+        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();
+        if (this.page) {
+            this.removeHandlers(this.page);
+            this.createAndAttachHandlers(this.page);
+        }
+    }
+    /**
+     * 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() {
+        this.cancelQuietTimer();
+        this.quietTimer = setTimeout(() => {
+            this.quietTimer = null;
+            for (const { resolve, timeoutId } of this.quietResolvers) {
+                clearTimeout(timeoutId);
+                resolve(true);
+            }
+            this.quietResolvers = [];
+        }, this.quietWindowMs);
+    }
+    /**
+     * Create and attach event handlers for the current generation.
+     */
+    createAndAttachHandlers(page) {
+        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);
+    }
+    /**
+     * Remove event handlers from a page.
+     */
+    removeHandlers(page) {
+        if (this.onRequest) {
+            page.off('request', this.onRequest);
+        }
+        if (this.onRequestFinished) {
+            page.off('requestfinished', this.onRequestFinished);
+        }
+        if (this.onRequestFailed) {
+            page.off('requestfailed', this.onRequestFailed);
+        }
+    }
+}
+// --- 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-registry.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Page Registry
+ *
+ * Tracks active Puppeteer pages and their CDP sessions.
+ * Provides a central registry for page lifecycle management.
+ */
+import type { Page } from 'puppeteer-core';
+import type { CdpClient } from '../cdp/cdp-client.interface.js';
+/**
+ * Handle to a registered page with its CDP session
+ */
+export interface PageHandle {
+    /** Unique identifier for this page */
+    page_id: string;
+    /** Puppeteer Page instance */
+    page: Page;
+    /** CDP client for this page */
+    cdp: CdpClient;
+    /** When the page was registered */
+    created_at: Date;
+    /** Current URL (may be stale) */
+    url?: string;
+    /** Page title (may be stale) */
+    title?: string;
+}
+/**
+ * Registry for tracking active pages
+ */
+export declare class PageRegistry {
+    private readonly pages;
+    /** Most recently used page ID for default resolution */
+    private mruPageId;
+    /**
+     * Register a new page with its CDP session
+     *
+     * @param page - Puppeteer Page instance
+     * @param cdp - CDP client for the page
+     * @returns PageHandle with unique page_id
+     * @throws Error if page is already closed
+     */
+    register(page: Page, cdp: CdpClient): PageHandle;
+    /**
+     * Get a page handle by its ID
+     *
+     * @param page_id - The page identifier
+     * @returns PageHandle if found, undefined otherwise
+     */
+    get(page_id: string): PageHandle | undefined;
+    /**
+     * Remove a page from the registry
+     *
+     * @param page_id - The page identifier
+     * @returns true if page was removed, false if not found
+     */
+    remove(page_id: string): boolean;
+    /**
+     * List all registered pages
+     *
+     * @returns Array of all PageHandle objects
+     */
+    list(): PageHandle[];
+    /**
+     * Remove all pages from the registry
+     */
+    clear(): void;
+    /**
+     * Get the number of registered pages
+     *
+     * @returns Current page count
+     */
+    size(): number;
+    /**
+     * Check if a page is registered
+     *
+     * @param page_id - The page identifier
+     * @returns true if page exists
+     */
+    has(page_id: string): boolean;
+    /**
+     * Replace a page handle in the registry.
+     *
+     * Used for CDP session rebinding - keeps the same page_id but
+     * updates the handle with a new CDP session.
+     *
+     * @param page_id - Page ID to replace
+     * @param handle - New handle to store
+     * @returns true if replaced, false if page_id not found
+     */
+    replace(page_id: string, handle: PageHandle): boolean;
+    /**
+     * Update metadata for a page
+     *
+     * @param page_id - The page identifier
+     * @param metadata - Partial metadata to update
+     * @returns true if updated, false if page not found
+     */
+    updateMetadata(page_id: string, metadata: Partial<Pick<PageHandle, 'url' | 'title'>>): boolean;
+    /**
+     * Find a handle by its Puppeteer Page instance
+     *
+     * @param page - Puppeteer Page instance to find
+     * @returns PageHandle if found, undefined otherwise
+     */
+    findByPage(page: Page): PageHandle | undefined;
+    /**
+     * Find all handles with a matching URL
+     *
+     * @param url - URL to search for
+     * @returns Array of matching PageHandle objects
+     */
+    findByUrl(url: string): PageHandle[];
+    /**
+     * Check if a page handle is still valid (page not closed, CDP active)
+     *
+     * Use this to detect stale handles before performing operations.
+     *
+     * @param page_id - The page identifier
+     * @returns true if the handle exists and both page and CDP session are active
+     */
+    isValid(page_id: string): boolean;
+    /**
+     * Touch a page to mark it as most recently used.
+     *
+     * @param page_id - The page identifier
+     * @returns true if the page exists and was touched, false otherwise
+     */
+    touch(page_id: string): boolean;
+    /**
+     * Get the most recently used page.
+     *
+     * Falls back to the first registered page if MRU is not set.
+     *
+     * @returns PageHandle for MRU page, or undefined if no pages
+     */
+    getMostRecent(): PageHandle | undefined;
+}
+//# sourceMappingURL=page-registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"page-registry.d.ts","sourceRoot":"","sources":["../../../src/browser/page-registry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAGhE;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;IAEhB,8BAA8B;IAC9B,IAAI,EAAE,IAAI,CAAC;IAEX,+BAA+B;IAC/B,GAAG,EAAE,SAAS,CAAC;IAEf,mCAAmC;IACnC,UAAU,EAAE,IAAI,CAAC;IAEjB,iCAAiC;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;IACvD,wDAAwD;IACxD,OAAO,CAAC,SAAS,CAAuB;IAExC;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,SAAS,GAAG,UAAU;IAsBhD;;;;;OAKG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI5C;;;;;OAKG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAUhC;;;;OAIG;IACH,IAAI,IAAI,UAAU,EAAE;IAIpB;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;;;OAIG;IACH,IAAI,IAAI,MAAM;IAId;;;;;OAKG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAI7B;;;;;;;;;OASG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO;IAQrD;;;;;;OAMG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,KAAK,GAAG,OAAO,CAAC,CAAC,GAAG,OAAO;IAgB9F;;;;;OAKG;IACH,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,UAAU,GAAG,SAAS;IAI9C;;;;;OAKG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,EAAE;IAIpC;;;;;;;OAOG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IASjC;;;;;OAKG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAQ/B;;;;;;OAMG;IACH,aAAa,IAAI,UAAU,GAAG,SAAS;CAOxC"}

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

@@ -0,0 +1,194 @@
+/**
+ * Page Registry
+ *
+ * Tracks active Puppeteer pages and their CDP sessions.
+ * Provides a central registry for page lifecycle management.
+ */
+import { randomUUID } from 'crypto';
+/**
+ * Registry for tracking active pages
+ */
+export class PageRegistry {
+    pages = new Map();
+    /** Most recently used page ID for default resolution */
+    mruPageId = null;
+    /**
+     * Register a new page with its CDP session
+     *
+     * @param page - Puppeteer Page instance
+     * @param cdp - CDP client for the page
+     * @returns PageHandle with unique page_id
+     * @throws Error if page is already closed
+     */
+    register(page, cdp) {
+        // Validate page is not closed (Puppeteer uses isClosed())
+        if (page.isClosed()) {
+            throw new Error('Cannot register a closed page');
+        }
+        const page_id = `page-${randomUUID()}`;
+        const handle = {
+            page_id,
+            page,
+            cdp,
+            created_at: new Date(),
+            url: page.url?.(),
+        };
+        this.pages.set(page_id, handle);
+        this.mruPageId = page_id;
+        return handle;
+    }
+    /**
+     * Get a page handle by its ID
+     *
+     * @param page_id - The page identifier
+     * @returns PageHandle if found, undefined otherwise
+     */
+    get(page_id) {
+        return this.pages.get(page_id);
+    }
+    /**
+     * Remove a page from the registry
+     *
+     * @param page_id - The page identifier
+     * @returns true if page was removed, false if not found
+     */
+    remove(page_id) {
+        const deleted = this.pages.delete(page_id);
+        if (deleted && this.mruPageId === page_id) {
+            // Transfer MRU to first remaining page, or null if empty
+            const firstRemaining = this.pages.values().next().value;
+            this.mruPageId = firstRemaining?.page_id ?? null;
+        }
+        return deleted;
+    }
+    /**
+     * List all registered pages
+     *
+     * @returns Array of all PageHandle objects
+     */
+    list() {
+        return Array.from(this.pages.values());
+    }
+    /**
+     * Remove all pages from the registry
+     */
+    clear() {
+        this.pages.clear();
+        this.mruPageId = null;
+    }
+    /**
+     * Get the number of registered pages
+     *
+     * @returns Current page count
+     */
+    size() {
+        return this.pages.size;
+    }
+    /**
+     * Check if a page is registered
+     *
+     * @param page_id - The page identifier
+     * @returns true if page exists
+     */
+    has(page_id) {
+        return this.pages.has(page_id);
+    }
+    /**
+     * Replace a page handle in the registry.
+     *
+     * Used for CDP session rebinding - keeps the same page_id but
+     * updates the handle with a new CDP session.
+     *
+     * @param page_id - Page ID to replace
+     * @param handle - New handle to store
+     * @returns true if replaced, false if page_id not found
+     */
+    replace(page_id, handle) {
+        if (!this.pages.has(page_id)) {
+            return false;
+        }
+        this.pages.set(page_id, handle);
+        return true;
+    }
+    /**
+     * Update metadata for a page
+     *
+     * @param page_id - The page identifier
+     * @param metadata - Partial metadata to update
+     * @returns true if updated, false if page not found
+     */
+    updateMetadata(page_id, metadata) {
+        const handle = this.pages.get(page_id);
+        if (!handle) {
+            return false;
+        }
+        if (metadata.url !== undefined) {
+            handle.url = metadata.url;
+        }
+        if (metadata.title !== undefined) {
+            handle.title = metadata.title;
+        }
+        return true;
+    }
+    /**
+     * Find a handle by its Puppeteer Page instance
+     *
+     * @param page - Puppeteer Page instance to find
+     * @returns PageHandle if found, undefined otherwise
+     */
+    findByPage(page) {
+        return this.list().find((h) => h.page === page);
+    }
+    /**
+     * Find all handles with a matching URL
+     *
+     * @param url - URL to search for
+     * @returns Array of matching PageHandle objects
+     */
+    findByUrl(url) {
+        return this.list().filter((h) => h.url === url);
+    }
+    /**
+     * Check if a page handle is still valid (page not closed, CDP active)
+     *
+     * Use this to detect stale handles before performing operations.
+     *
+     * @param page_id - The page identifier
+     * @returns true if the handle exists and both page and CDP session are active
+     */
+    isValid(page_id) {
+        const handle = this.pages.get(page_id);
+        if (!handle) {
+            return false;
+        }
+        return !handle.page.isClosed() && handle.cdp.isActive();
+    }
+    /**
+     * Touch a page to mark it as most recently used.
+     *
+     * @param page_id - The page identifier
+     * @returns true if the page exists and was touched, false otherwise
+     */
+    touch(page_id) {
+        if (this.pages.has(page_id)) {
+            this.mruPageId = page_id;
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Get the most recently used page.
+     *
+     * Falls back to the first registered page if MRU is not set.
+     *
+     * @returns PageHandle for MRU page, or undefined if no pages
+     */
+    getMostRecent() {
+        if (this.mruPageId && this.pages.has(this.mruPageId)) {
+            return this.pages.get(this.mruPageId);
+        }
+        // Fallback to first page
+        return this.pages.values().next().value;
+    }
+}
+//# sourceMappingURL=page-registry.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"page-registry.js","sourceRoot":"","sources":["../../../src/browser/page-registry.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 Puppeteer's waitForNetworkIdle(), the tracker
+ * monitors actual request/response events and works for in-page actions
+ * (not just navigation load states).
+ */
+import type { Page } from 'puppeteer-core';
+/** 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 Puppeteer's waitForNetworkIdle(), this works correctly
+ * for fetch/XHR requests triggered by user actions after page load.
+ *
+ * @param page - Puppeteer 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,gBAAgB,CAAC;AAG3C,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 Puppeteer's waitForNetworkIdle(), 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 Puppeteer's waitForNetworkIdle(), this works correctly
+ * for fetch/XHR requests triggered by user actions after page load.
+ *
+ * @param page - Puppeteer 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"}