browser-debugger-cli 0.3.0 → 0.5.1

package/dist/telemetry/filters.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Default filters for reducing noise in collected data
+ */
+/**
+ * Decision object for whether to fetch a response body.
+ */
+export interface BodyFetchDecision {
+    /** Whether the body should be fetched */
+    should: boolean;
+    /** Reason why the body was skipped (if should is false) */
+    reason?: string;
+}
+/**
+ * Domains to exclude by default (common tracking/analytics)
+ * These generate high volume but are rarely useful for debugging
+ */
+export declare const DEFAULT_EXCLUDED_DOMAINS: string[];
+/**
+ * Console message types to exclude by default (Redux/React DevTools noise)
+ */
+export declare const DEFAULT_EXCLUDED_CONSOLE_TYPES: string[];
+/**
+ * Console message patterns to exclude by default (dev server noise)
+ */
+export declare const DEFAULT_EXCLUDED_CONSOLE_PATTERNS: string[];
+/**
+ * File patterns to skip body fetching by default (assets unlikely to be useful for debugging)
+ * These reduce data volume significantly without losing critical debugging information.
+ */
+export declare const DEFAULT_SKIP_BODY_PATTERNS: string[];
+/**
+ * MIME types to skip body fetching by default
+ * This catches resources that may not have obvious file extensions (e.g., CSS with query params)
+ */
+export declare const DEFAULT_SKIP_BODY_MIME_TYPES: string[];
+/**
+ * Check if a URL should be excluded based on domain filtering.
+ *
+ * @param url - URL to check against exclusion list
+ * @param includeAll - If true, disables all filtering
+ * @returns True if the URL's domain matches an excluded domain
+ */
+export declare function shouldExcludeDomain(url: string, includeAll?: boolean): boolean;
+/**
+ * Check if a console message should be excluded based on type and pattern filtering
+ */
+export declare function shouldExcludeConsoleMessage(text: string, type: string, includeAll?: boolean): boolean;
+/**
+ * Simple wildcard pattern matcher.
+ * Supports only the * wildcard character.
+ *
+ * Examples:
+ *   matchesWildcard("api.json", "*.json") → true
+ *   matchesWildcard("api/users", "*api*") → true
+ *   matchesWildcard("index.html", "*.js") → false
+ *
+ * @param str - The string to test
+ * @param pattern - The pattern with * wildcards
+ * @returns True if the string matches the pattern
+ */
+export declare function matchesWildcard(str: string, pattern: string): boolean;
+/**
+ * Check if a URL matches any pattern in a list.
+ *
+ * Matches against both bare hostname and hostname+pathname to support:
+ * - Bare hostname patterns: `api.example.com` matches all requests to that host
+ * - Hostname wildcard patterns: `*analytics*` matches "analytics.google.com/collect"
+ * - Path patterns: `*\/api\/*` matches "example.com/api/users"
+ * - Combined patterns: `api.example.com\/users` matches specific endpoint
+ *
+ * @param url - The URL to check
+ * @param patterns - Array of wildcard patterns
+ * @returns True if URL matches any pattern
+ */
+/**
+ * Determine if a response body should be fetched based on URL, MIME type, and patterns.
+ *
+ * Pattern precedence (follows include-trumps-exclude rule):
+ * 1. If URL matches includePatterns → FETCH (even if it also matches excludePatterns)
+ * 2. If includePatterns specified but URL doesn't match → SKIP (whitelist mode)
+ * 3. If URL matches excludePatterns → SKIP
+ * 4. If fetchAllBodies flag is true → FETCH
+ * 5. If MIME type matches DEFAULT_SKIP_BODY_MIME_TYPES → SKIP
+ * 6. If URL matches DEFAULT_SKIP_BODY_PATTERNS → SKIP
+ * 7. Otherwise → FETCH (default behavior)
+ *
+ * @param url - The request URL
+ * @param mimeType - The response MIME type (for MIME-based skipping)
+ * @param options - Configuration options
+ * @returns True if the body should be fetched
+ */
+export declare function shouldFetchBody(url: string, mimeType: string | undefined, options?: {
+    fetchAllBodies?: boolean;
+    includePatterns?: string[];
+    excludePatterns?: string[];
+}): boolean;
+/**
+ * Determine if a response body should be fetched with detailed reason.
+ *
+ * Combines all decision logic: MIME type, size limits, smart defaults, and fetch flags.
+ * Returns a decision object with reason string for logging/debugging.
+ *
+ * @param url - Request URL
+ * @param mimeType - Response MIME type
+ * @param encodedDataLength - Response size in bytes
+ * @param options - Configuration options
+ * @returns Decision object with should boolean and optional reason
+ *
+ * @example
+ * ```typescript
+ * const decision = shouldFetchBodyWithReason(
+ *   'https://api.example.com/data',
+ *   'application/json',
+ *   1024,
+ *   { maxBodySize: 5 * 1024 * 1024 }
+ * );
+ * if (!decision.should) {
+ *   console.log(`Skipped: ${decision.reason}`);
+ * }
+ * ```
+ */
+export declare function shouldFetchBodyWithReason(url: string, mimeType: string | undefined, encodedDataLength: number, options?: {
+    fetchAllBodies?: boolean;
+    includePatterns?: string[];
+    excludePatterns?: string[];
+    maxBodySize?: number;
+}): BodyFetchDecision;
+/**
+ * Determine if a network request should be excluded based on URL patterns.
+ *
+ * Pattern precedence (follows include-trumps-exclude rule):
+ * 1. If URL matches includePatterns → CAPTURE (even if it also matches excludePatterns)
+ * 2. If includePatterns specified but URL doesn't match → EXCLUDE (whitelist mode)
+ * 3. If URL matches excludePatterns → EXCLUDE
+ * 4. Otherwise → CAPTURE (default behavior)
+ *
+ * Note: This function is separate from domain filtering (shouldExcludeDomain).
+ * Both filters can be applied: domain filtering happens first, then URL pattern filtering.
+ *
+ * @param url - The request URL
+ * @param options - Configuration options
+ * @returns True if the request should be excluded
+ */
+export declare function shouldExcludeUrl(url: string, options?: {
+    includePatterns?: string[];
+    excludePatterns?: string[];
+}): boolean;
+//# sourceMappingURL=filters.d.ts.map

package/dist/telemetry/filters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filters.d.ts","sourceRoot":"","sources":["../../src/telemetry/filters.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,yCAAyC;IACzC,MAAM,EAAE,OAAO,CAAC;IAChB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,eAAO,MAAM,wBAAwB,UA6CpC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,8BAA8B,UAAoD,CAAC;AAEhG;;GAEG;AACH,eAAO,MAAM,iCAAiC,UAS7C,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,0BAA0B,UAuCtC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,4BAA4B,UAqBxC,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,GAAE,OAAe,GAAG,OAAO,CAOrF;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,UAAU,GAAE,OAAe,GAC1B,OAAO,CAeT;AAoDD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAQrE;AAED;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,OAAO,GAAE;IACP,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB,GACL,OAAO,CA8CT;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,iBAAiB,EAAE,MAAM,EACzB,OAAO,GAAE;IACP,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;CACjB,GACL,iBAAiB,CAmCnB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,OAAO,GAAE;IACP,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB,GACL,OAAO,CAST"}

package/dist/telemetry/filters.js

@@ -0,0 +1,358 @@
+/**
+ * Default filters for reducing noise in collected data
+ */
+import { extractHostname, extractHostnameWithPath } from '../utils/url.js';
+/**
+ * Domains to exclude by default (common tracking/analytics)
+ * These generate high volume but are rarely useful for debugging
+ */
+export const DEFAULT_EXCLUDED_DOMAINS = [
+    // Google Analytics & Ads
+    'analytics.google.com',
+    'googletagmanager.com',
+    'googleadservices.com',
+    'doubleclick.net',
+    'google-analytics.com',
+    // Microsoft/Bing
+    'clarity.ms',
+    'bat.bing.com',
+    // Social Media Tracking
+    'facebook.com',
+    'connect.facebook.net',
+    'tiktok.com',
+    'linkedin.com',
+    'twitter.com',
+    'snapchat.com',
+    // Product Analytics
+    'mixpanel.com',
+    'segment.com',
+    'segment.io',
+    'amplitude.com',
+    'heap.io',
+    // Session Recording & Heatmaps
+    'fullstory.com',
+    'hotjar.com',
+    'logrocket.com',
+    'smartlook.com',
+    // Ad Networks & Attribution
+    'exactag.com',
+    'criteo.com',
+    'adroll.com',
+    'outbrain.com',
+    'taboola.com',
+    // Other Analytics
+    'confirmit.com',
+    'newrelic.com',
+    'datadoghq.com',
+    'sentry.io',
+];
+/**
+ * Console message types to exclude by default (Redux/React DevTools noise)
+ */
+export const DEFAULT_EXCLUDED_CONSOLE_TYPES = ['startGroup', 'startGroupCollapsed', 'endGroup'];
+/**
+ * Console message patterns to exclude by default (dev server noise)
+ */
+export const DEFAULT_EXCLUDED_CONSOLE_PATTERNS = [
+    'webpack-dev-server',
+    '[HMR]',
+    '[WDS]',
+    'Download the React DevTools',
+    '@@redux', // Redux actions
+    '%c prev state', // Redux logger
+    '%c action', // Redux logger
+    '%c next state', // Redux logger
+];
+/**
+ * File patterns to skip body fetching by default (assets unlikely to be useful for debugging)
+ * These reduce data volume significantly without losing critical debugging information.
+ */
+export const DEFAULT_SKIP_BODY_PATTERNS = [
+    // Images
+    '*.png',
+    '*.jpg',
+    '*.jpeg',
+    '*.gif',
+    '*.svg',
+    '*.ico',
+    '*.webp',
+    '*.bmp',
+    '*.tiff',
+    // Fonts
+    '*.woff',
+    '*.woff2',
+    '*.ttf',
+    '*.eot',
+    '*.otf',
+    // Stylesheets
+    '*.css',
+    // Source maps (can be large and rarely needed)
+    '*.map',
+    '*.js.map',
+    '*.css.map',
+    // Videos
+    '*.mp4',
+    '*.webm',
+    '*.ogg',
+    '*.avi',
+    '*.mov',
+    // Audio
+    '*.mp3',
+    '*.wav',
+    '*.flac',
+    '*.aac',
+];
+/**
+ * MIME types to skip body fetching by default
+ * This catches resources that may not have obvious file extensions (e.g., CSS with query params)
+ */
+export const DEFAULT_SKIP_BODY_MIME_TYPES = [
+    'text/css',
+    'image/svg+xml',
+    'image/png',
+    'image/jpeg',
+    'image/gif',
+    'image/webp',
+    'image/avif',
+    'image/bmp',
+    'image/tiff',
+    'font/woff',
+    'font/woff2',
+    'font/ttf',
+    'font/eot',
+    'font/otf',
+    'application/font-woff',
+    'application/font-woff2',
+    'video/mp4',
+    'video/webm',
+    'audio/mpeg',
+    'audio/wav',
+];
+/**
+ * Check if a URL should be excluded based on domain filtering.
+ *
+ * @param url - URL to check against exclusion list
+ * @param includeAll - If true, disables all filtering
+ * @returns True if the URL's domain matches an excluded domain
+ */
+export function shouldExcludeDomain(url, includeAll = false) {
+    if (includeAll) {
+        return false; // Don't filter anything if --include-all flag is set
+    }
+    const hostname = extractHostname(url).toLowerCase();
+    return DEFAULT_EXCLUDED_DOMAINS.some((domain) => hostname.includes(domain.toLowerCase()));
+}
+/**
+ * Check if a console message should be excluded based on type and pattern filtering
+ */
+export function shouldExcludeConsoleMessage(text, type, includeAll = false) {
+    if (includeAll) {
+        return false; // Don't filter anything if --include-all flag is set
+    }
+    // Check if message type should be excluded (e.g., group messages)
+    if (DEFAULT_EXCLUDED_CONSOLE_TYPES.includes(type)) {
+        return true;
+    }
+    const lowerText = text.toLowerCase();
+    return DEFAULT_EXCLUDED_CONSOLE_PATTERNS.some((pattern) => lowerText.includes(pattern.toLowerCase()));
+}
+/**
+ * Evaluate whether a URL matches pattern rules using include-trumps-exclude logic.
+ *
+ * Provides centralized pattern matching with consistent precedence rules:
+ * 1. If URL matches includePatterns → true (even if it also matches excludePatterns)
+ * 2. If includePatterns specified but URL doesn't match → false (whitelist mode)
+ * 3. If URL matches excludePatterns → false
+ * 4. Otherwise → use defaultBehavior
+ *
+ * This function consolidates the URL parsing and wildcard matching logic that was
+ * previously duplicated across multiple filter functions.
+ *
+ * @param url - The URL to check against patterns
+ * @param config - Pattern matching configuration with include/exclude patterns
+ * @returns True if the URL should be included based on pattern rules
+ */
+function evaluatePatternMatch(url, config) {
+    const { includePatterns = [], excludePatterns = [], defaultBehavior = 'include' } = config;
+    // Parse URL once for all pattern checks
+    const hostname = extractHostname(url);
+    const hostnameWithPath = extractHostnameWithPath(url);
+    // Helper: check if any pattern matches hostname or hostname+path
+    const matchesAny = (patterns) => patterns.some((pattern) => matchesWildcard(hostname, pattern) || matchesWildcard(hostnameWithPath, pattern));
+    // Compute match states
+    const includeSpecified = includePatterns.length > 0;
+    const includeMatch = includeSpecified && matchesAny(includePatterns);
+    const excludeMatch = excludePatterns.length > 0 && matchesAny(excludePatterns);
+    // Decision logic: include trumps exclude, then whitelist mode, then exclude, then default
+    return includeMatch || (!includeSpecified && !excludeMatch && defaultBehavior === 'include');
+}
+/**
+ * Simple wildcard pattern matcher.
+ * Supports only the * wildcard character.
+ *
+ * Examples:
+ *   matchesWildcard("api.json", "*.json") → true
+ *   matchesWildcard("api/users", "*api*") → true
+ *   matchesWildcard("index.html", "*.js") → false
+ *
+ * @param str - The string to test
+ * @param pattern - The pattern with * wildcards
+ * @returns True if the string matches the pattern
+ */
+export function matchesWildcard(str, pattern) {
+    // Escape special regex characters except *
+    const regexPattern = pattern
+        .replace(/[.+?^${}()|[\]\\]/g, '\\$&') // Escape special chars
+        .replace(/\*/g, '.*'); // Replace * with .*
+    const regex = new RegExp(`^${regexPattern}$`, 'i'); // Case-insensitive
+    return regex.test(str);
+}
+/**
+ * Check if a URL matches any pattern in a list.
+ *
+ * Matches against both bare hostname and hostname+pathname to support:
+ * - Bare hostname patterns: `api.example.com` matches all requests to that host
+ * - Hostname wildcard patterns: `*analytics*` matches "analytics.google.com/collect"
+ * - Path patterns: `*\/api\/*` matches "example.com/api/users"
+ * - Combined patterns: `api.example.com\/users` matches specific endpoint
+ *
+ * @param url - The URL to check
+ * @param patterns - Array of wildcard patterns
+ * @returns True if URL matches any pattern
+ */
+/**
+ * Determine if a response body should be fetched based on URL, MIME type, and patterns.
+ *
+ * Pattern precedence (follows include-trumps-exclude rule):
+ * 1. If URL matches includePatterns → FETCH (even if it also matches excludePatterns)
+ * 2. If includePatterns specified but URL doesn't match → SKIP (whitelist mode)
+ * 3. If URL matches excludePatterns → SKIP
+ * 4. If fetchAllBodies flag is true → FETCH
+ * 5. If MIME type matches DEFAULT_SKIP_BODY_MIME_TYPES → SKIP
+ * 6. If URL matches DEFAULT_SKIP_BODY_PATTERNS → SKIP
+ * 7. Otherwise → FETCH (default behavior)
+ *
+ * @param url - The request URL
+ * @param mimeType - The response MIME type (for MIME-based skipping)
+ * @param options - Configuration options
+ * @returns True if the body should be fetched
+ */
+export function shouldFetchBody(url, mimeType, options = {}) {
+    const { fetchAllBodies = false, includePatterns = [], excludePatterns = [] } = options;
+    // If includePatterns specified, act as whitelist (trumps everything else)
+    if (includePatterns.length > 0) {
+        return evaluatePatternMatch(url, {
+            includePatterns,
+            defaultBehavior: 'exclude',
+        });
+    }
+    // If excludePatterns specified and URL matches → skip (trumps fetchAllBodies)
+    if (excludePatterns.length > 0) {
+        const matchesExclude = evaluatePatternMatch(url, {
+            includePatterns: excludePatterns,
+            defaultBehavior: 'exclude',
+        });
+        if (matchesExclude) {
+            return false;
+        }
+    }
+    // If fetchAllBodies flag is set → fetch everything
+    if (fetchAllBodies) {
+        return true;
+    }
+    // Check MIME type against default skip list (case-insensitive)
+    if (mimeType) {
+        const normalizedMimeType = mimeType.toLowerCase().split(';')[0]?.trim() ?? ''; // Remove charset etc.
+        if (normalizedMimeType &&
+            DEFAULT_SKIP_BODY_MIME_TYPES.some((skipType) => normalizedMimeType === skipType.toLowerCase())) {
+            return false;
+        }
+    }
+    // Apply default auto-skip URL patterns
+    const matchesDefaultSkip = evaluatePatternMatch(url, {
+        includePatterns: DEFAULT_SKIP_BODY_PATTERNS,
+        defaultBehavior: 'exclude',
+    });
+    // Default: fetch the body unless it matches default skip patterns
+    return !matchesDefaultSkip;
+}
+/**
+ * Determine if a response body should be fetched with detailed reason.
+ *
+ * Combines all decision logic: MIME type, size limits, smart defaults, and fetch flags.
+ * Returns a decision object with reason string for logging/debugging.
+ *
+ * @param url - Request URL
+ * @param mimeType - Response MIME type
+ * @param encodedDataLength - Response size in bytes
+ * @param options - Configuration options
+ * @returns Decision object with should boolean and optional reason
+ *
+ * @example
+ * ```typescript
+ * const decision = shouldFetchBodyWithReason(
+ *   'https://api.example.com/data',
+ *   'application/json',
+ *   1024,
+ *   { maxBodySize: 5 * 1024 * 1024 }
+ * );
+ * if (!decision.should) {
+ *   console.log(`Skipped: ${decision.reason}`);
+ * }
+ * ```
+ */
+export function shouldFetchBodyWithReason(url, mimeType, encodedDataLength, options = {}) {
+    const { maxBodySize = 5 * 1024 * 1024 } = options;
+    // Check if response is text-based
+    const isTextResponse = (mimeType?.includes('json') ?? false) ||
+        (mimeType?.includes('javascript') ?? false) ||
+        (mimeType?.includes('text') ?? false) ||
+        (mimeType?.includes('html') ?? false);
+    if (!isTextResponse) {
+        return { should: false, reason: 'Non-text response type' };
+    }
+    // Check size limits
+    if (encodedDataLength > maxBodySize) {
+        const sizeStr = `${(encodedDataLength / 1024 / 1024).toFixed(2)}MB`;
+        const limitStr = `${(maxBodySize / 1024 / 1024).toFixed(2)}MB`;
+        return {
+            should: false,
+            reason: `Response too large (${sizeStr} > ${limitStr})`,
+        };
+    }
+    // Use existing shouldFetchBody for pattern matching
+    const shouldFetch = shouldFetchBody(url, mimeType, options);
+    if (!shouldFetch) {
+        return {
+            should: false,
+            reason: 'Auto-optimization (see DEFAULT_SKIP_BODY_PATTERNS)',
+        };
+    }
+    return { should: true };
+}
+/**
+ * Determine if a network request should be excluded based on URL patterns.
+ *
+ * Pattern precedence (follows include-trumps-exclude rule):
+ * 1. If URL matches includePatterns → CAPTURE (even if it also matches excludePatterns)
+ * 2. If includePatterns specified but URL doesn't match → EXCLUDE (whitelist mode)
+ * 3. If URL matches excludePatterns → EXCLUDE
+ * 4. Otherwise → CAPTURE (default behavior)
+ *
+ * Note: This function is separate from domain filtering (shouldExcludeDomain).
+ * Both filters can be applied: domain filtering happens first, then URL pattern filtering.
+ *
+ * @param url - The request URL
+ * @param options - Configuration options
+ * @returns True if the request should be excluded
+ */
+export function shouldExcludeUrl(url, options = {}) {
+    const { includePatterns = [], excludePatterns = [] } = options;
+    // Use unified pattern matching - invert result since we want exclusion logic
+    return !evaluatePatternMatch(url, {
+        includePatterns,
+        excludePatterns,
+        defaultBehavior: 'include',
+    });
+}
+//# sourceMappingURL=filters.js.map

package/dist/telemetry/filters.js.map

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

package/dist/telemetry/navigation.d.ts

@@ -0,0 +1,49 @@
+import type { CDPConnection } from '../connection/cdp.js';
+import type { CleanupFunction } from '../types';
+/**
+ * Navigation event information.
+ */
+export interface NavigationEvent {
+    /** URL navigated to */
+    url: string;
+    /** Timestamp of navigation */
+    timestamp: number;
+    /** Navigation counter (increments with each main frame navigation) */
+    navigationId: number;
+}
+/**
+ * Start tracking page navigation events.
+ *
+ * Monitors main frame navigations (page loads, URL changes) and maintains
+ * a navigation counter that increments with each navigation. This counter
+ * can be used to detect stale references (e.g., network request indices
+ * from a previous page load).
+ *
+ * @param cdp - CDP connection instance
+ * @param navigations - Array to populate with navigation events
+ * @returns Object with cleanup function and getCurrentNavigationId getter
+ *
+ * @remarks
+ * - Only tracks main frame navigations (ignores iframe navigations)
+ * - Navigation ID starts at 0 and increments with each navigation
+ * - Initial page load counts as navigation 0
+ *
+ * @example
+ * ```typescript
+ * const navs: NavigationEvent[] = [];
+ * const { cleanup, getCurrentNavigationId } = await startNavigationTracking(cdp, navs);
+ *
+ * // Later, validate if a reference is stale:
+ * const currentNavId = getCurrentNavigationId();
+ * if (referenceNavId !== currentNavId) {
+ *   throw new Error('Stale reference - page has navigated');
+ * }
+ *
+ * cleanup();
+ * ```
+ */
+export declare function startNavigationTracking(cdp: CDPConnection, navigations: NavigationEvent[]): Promise<{
+    cleanup: CleanupFunction;
+    getCurrentNavigationId: () => number;
+}>;
+//# sourceMappingURL=navigation.d.ts.map

package/dist/telemetry/navigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../src/telemetry/navigation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAK/C;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,uBAAuB;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,YAAY,EAAE,MAAM,CAAC;CACtB;AAmBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,aAAa,EAClB,WAAW,EAAE,eAAe,EAAE,GAC7B,OAAO,CAAC;IAAE,OAAO,EAAE,eAAe,CAAC;IAAC,sBAAsB,EAAE,MAAM,MAAM,CAAA;CAAE,CAAC,CA4C7E"}

package/dist/telemetry/navigation.js

@@ -0,0 +1,69 @@
+import { CDPHandlerRegistry } from '../connection/handlers.js';
+import { createLogger } from '../ui/logging/index.js';
+const log = createLogger('navigation');
+/**
+ * Start tracking page navigation events.
+ *
+ * Monitors main frame navigations (page loads, URL changes) and maintains
+ * a navigation counter that increments with each navigation. This counter
+ * can be used to detect stale references (e.g., network request indices
+ * from a previous page load).
+ *
+ * @param cdp - CDP connection instance
+ * @param navigations - Array to populate with navigation events
+ * @returns Object with cleanup function and getCurrentNavigationId getter
+ *
+ * @remarks
+ * - Only tracks main frame navigations (ignores iframe navigations)
+ * - Navigation ID starts at 0 and increments with each navigation
+ * - Initial page load counts as navigation 0
+ *
+ * @example
+ * ```typescript
+ * const navs: NavigationEvent[] = [];
+ * const { cleanup, getCurrentNavigationId } = await startNavigationTracking(cdp, navs);
+ *
+ * // Later, validate if a reference is stale:
+ * const currentNavId = getCurrentNavigationId();
+ * if (referenceNavId !== currentNavId) {
+ *   throw new Error('Stale reference - page has navigated');
+ * }
+ *
+ * cleanup();
+ * ```
+ */
+export async function startNavigationTracking(cdp, navigations) {
+    const registry = new CDPHandlerRegistry();
+    let navigationCounter = 0;
+    // Enable Page domain to receive navigation events
+    await cdp.send('Page.enable');
+    // Record initial navigation (the page we're currently on)
+    const initialNavigation = {
+        url: '', // Will be updated by first frameNavigated event or from session metadata
+        timestamp: Date.now(),
+        navigationId: navigationCounter,
+    };
+    navigations.push(initialNavigation);
+    // Listen for frame navigation events
+    registry.register(cdp, 'Page.frameNavigated', (params) => {
+        // Only track main frame navigations (parentId is undefined for main frame)
+        if (params.frame.parentId === undefined) {
+            navigationCounter++;
+            const navigation = {
+                url: params.frame.url,
+                timestamp: Date.now(),
+                navigationId: navigationCounter,
+            };
+            navigations.push(navigation);
+            log.debug(`Main frame navigation detected [${navigationCounter}]: ${params.frame.url}`);
+        }
+    });
+    // Return cleanup function and navigation ID getter
+    return {
+        cleanup: () => {
+            registry.cleanup(cdp);
+        },
+        getCurrentNavigationId: () => navigationCounter,
+    };
+}
+//# sourceMappingURL=navigation.js.map

package/dist/telemetry/navigation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation.js","sourceRoot":"","sources":["../../src/telemetry/navigation.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAE9D,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAErD,MAAM,GAAG,GAAG,YAAY,CAAC,YAAY,CAAC,CAAC;AA+BvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,GAAkB,EAClB,WAA8B;IAE9B,MAAM,QAAQ,GAAG,IAAI,kBAAkB,EAAE,CAAC;IAC1C,IAAI,iBAAiB,GAAG,CAAC,CAAC;IAE1B,kDAAkD;IAClD,MAAM,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAE9B,0DAA0D;IAC1D,MAAM,iBAAiB,GAAoB;QACzC,GAAG,EAAE,EAAE,EAAE,yEAAyE;QAClF,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;QACrB,YAAY,EAAE,iBAAiB;KAChC,CAAC;IACF,WAAW,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;IAEpC,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,CACf,GAAG,EACH,qBAAqB,EACrB,CAAC,MAA+B,EAAE,EAAE;QAClC,2EAA2E;QAC3E,IAAI,MAAM,CAAC,KAAK,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;YACxC,iBAAiB,EAAE,CAAC;YAEpB,MAAM,UAAU,GAAoB;gBAClC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG;gBACrB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;gBACrB,YAAY,EAAE,iBAAiB;aAChC,CAAC;YAEF,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAE7B,GAAG,CAAC,KAAK,CAAC,mCAAmC,iBAAiB,MAAM,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC;QAC1F,CAAC;IACH,CAAC,CACF,CAAC;IAEF,mDAAmD;IACnD,OAAO;QACL,OAAO,EAAE,GAAG,EAAE;YACZ,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACxB,CAAC;QACD,sBAAsB,EAAE,GAAG,EAAE,CAAC,iBAAiB;KAChD,CAAC;AACJ,CAAC"}

package/dist/telemetry/network.d.ts

@@ -8,6 +8,7 @@ export interface NetworkCollectionOptions {
     networkInclude?: string[];
     networkExclude?: string[];
     maxBodySize?: number;
+    getCurrentNavigationId?: (() => number) | undefined;
 }
 /**
  * Start collecting network requests via CDP Network domain.

package/dist/telemetry/network.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../src/telemetry/network.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAUzD,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EAMhB,MAAM,SAAS,CAAC;AAIjB,MAAM,WAAW,wBAAwB;IACvC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,aAAa,EAClB,QAAQ,EAAE,cAAc,EAAE,EAC1B,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,eAAe,CAAC,CAwN1B"}
+{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../src/telemetry/network.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAWzD,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EAMhB,MAAM,SAAS,CAAC;AAIjB,MAAM,WAAW,wBAAwB;IACvC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sBAAsB,CAAC,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAC;CACrD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,aAAa,EAClB,QAAQ,EAAE,cAAc,EAAE,EAC1B,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,eAAe,CAAC,CAkN1B"}