browser-debugger-cli 0.2.0 → 0.5.1

package/dist/telemetry/dialogs.js

@@ -0,0 +1,51 @@
+import { CDPHandlerRegistry } from '../connection/handlers.js';
+import { createLogger } from '../ui/logging/index.js';
+const log = createLogger('dialogs');
+/**
+ * Start auto-dismissing JavaScript dialogs to prevent collection blocking.
+ *
+ * Automatically accepts all alert(), confirm(), and prompt() dialogs that appear
+ * during collection. Without this, dialogs would block the page and prevent
+ * further telemetry collection.
+ *
+ * @param cdp - CDP connection instance
+ * @returns Cleanup function to remove event handlers
+ *
+ * @remarks
+ * - All dialogs are automatically accepted (user cannot interact)
+ * - Prompt dialogs receive empty string as input
+ * - beforeunload dialogs are accepted to allow navigation
+ * - Dialog occurrences are logged in debug mode for visibility
+ *
+ * @example
+ * ```typescript
+ * const cleanup = await startDialogHandling(cdp);
+ * // ... page may show alert("Hello") - automatically dismissed
+ * cleanup(); // Stop handling dialogs
+ * ```
+ */
+export async function startDialogHandling(cdp) {
+    const registry = new CDPHandlerRegistry();
+    // Enable Page domain to receive dialog events
+    await cdp.send('Page.enable');
+    // Listen for JavaScript dialog opening events
+    registry.register(cdp, 'Page.javascriptDialogOpening', (params) => {
+        log.debug(`Auto-dismissing ${params.type} dialog: "${params.message}" from ${params.url}`);
+        // Auto-accept all dialogs to prevent blocking
+        // For prompt dialogs, use empty string as input
+        // Fire and forget - we don't await the response but handle errors
+        void cdp
+            .send('Page.handleJavaScriptDialog', {
+            accept: true,
+            promptText: params.type === 'prompt' ? '' : undefined,
+        })
+            .catch((error) => {
+            log.debug(`Failed to dismiss dialog: ${error.message}`);
+        });
+    });
+    // Return cleanup function
+    return () => {
+        registry.cleanup(cdp);
+    };
+}
+//# sourceMappingURL=dialogs.js.map

package/dist/telemetry/dialogs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dialogs.js","sourceRoot":"","sources":["../../src/telemetry/dialogs.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,SAAS,CAAC,CAAC;AAkBpC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,GAAkB;IAC1D,MAAM,QAAQ,GAAG,IAAI,kBAAkB,EAAE,CAAC;IAE1C,8CAA8C;IAC9C,MAAM,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAE9B,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,CACf,GAAG,EACH,8BAA8B,EAC9B,CAAC,MAAwC,EAAE,EAAE;QAC3C,GAAG,CAAC,KAAK,CAAC,mBAAmB,MAAM,CAAC,IAAI,aAAa,MAAM,CAAC,OAAO,UAAU,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC;QAE3F,8CAA8C;QAC9C,gDAAgD;QAChD,kEAAkE;QAClE,KAAK,GAAG;aACL,IAAI,CAAC,6BAA6B,EAAE;YACnC,MAAM,EAAE,IAAI;YACZ,UAAU,EAAE,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS;SACtD,CAAC;aACD,KAAK,CAAC,CAAC,KAAY,EAAE,EAAE;YACtB,GAAG,CAAC,KAAK,CAAC,6BAA6B,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QAC1D,CAAC,CAAC,CAAC;IACP,CAAC,CACF,CAAC;IAEF,0BAA0B;IAC1B,OAAO,GAAG,EAAE;QACV,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC,CAAC;AACJ,CAAC"}

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"}