@detiq/crawler 1.1.14 → 1.1.16

package/src/stealth/human-behavior.ts

@@ -104,29 +104,62 @@ export async function injectFingerprintOverrides(page: Page): Promise<void> {
 
 export async function infiniteScrollToBottom(
   page: Page,
-  opts: { maxScrolls?: number; scrollDelay?: number; stabilizeMs?: number } = {}
+  opts: { maxScrolls?: number; scrollDelay?: number; stabilizeMs?: number } = {},
+  rawPage?: any,
 ): Promise<{ scrollCount: number; heightReached: number }> {
   const { maxScrolls = 50, scrollDelay = 400, stabilizeMs = 600 } = opts;
   let scrollCount = 0;
   let stableScrollCount = 0;
   let previousHeight = 0;
 
+  // One CDP session for wheel events (triggers IntersectionObserver-based virtual scrollers).
+  // React-window / react-virtualized / TanStack Virtual ignore window.scrollBy but respond to
+  // wheel events because they attach their own scroll listeners to the list container.
+  let cdpForWheel: any = null;
+  let viewW = 1280;
+  let viewH = 800;
+  if (rawPage && typeof rawPage.context === 'function') {
+    try {
+      const ctx = rawPage.context();
+      if (typeof ctx?.newCDPSession === 'function') {
+        cdpForWheel = await ctx.newCDPSession(rawPage);
+        const { result } = await cdpForWheel.send('Runtime.evaluate', {
+          expression: `({"w":window.innerWidth,"h":window.innerHeight})`,
+          returnByValue: true,
+        }).catch(() => ({ result: { value: null } }));
+        if (result?.value) { viewW = result.value.w ?? 1280; viewH = result.value.h ?? 800; }
+      }
+    } catch { cdpForWheel = null; }
+  }
+
   try {
     while (scrollCount < maxScrolls) {
       previousHeight = await page.evaluate(() => document.documentElement.scrollHeight).catch(() => 0);
 
       const scrollBy = 500 + Math.floor(Math.random() * 300);
+      // window.scrollBy handles standard scroll containers
       await page.evaluate((by: number) => window.scrollBy(0, by), scrollBy).catch(() => {});
+      // CDP wheel event triggers IntersectionObserver + virtual list scroll listeners
+      if (cdpForWheel) {
+        await cdpForWheel.send('Input.dispatchMouseEvent', {
+          type: 'mouseWheel',
+          x: Math.floor(viewW / 2),
+          y: Math.floor(viewH / 2),
+          deltaX: 0,
+          deltaY: scrollBy,
+          modifiers: 0,
+        }).catch(() => {});
+      }
       await humanDelay(scrollDelay - 100, scrollDelay + 200);
 
-      // Wait for potential lazy-loaded content
-      await page.waitForTimeout(stabilizeMs).catch(() => {});
+      // Use Node.js setTimeout — page.waitForTimeout may not be available on Stagehand proxy
+      await new Promise<void>(r => setTimeout(r, stabilizeMs));
       scrollCount++;
 
       const newHeight: number = await page.evaluate(() => document.documentElement.scrollHeight).catch(() => 0);
       if (newHeight - previousHeight < 10) {
         stableScrollCount++;
-        if (stableScrollCount >= 3) break; // no meaningful new content after 3 consecutive non-growing scrolls
+        if (stableScrollCount >= 3) break; // no new content after 3 consecutive non-growing scrolls
       } else {
         stableScrollCount = 0;
       }
@@ -134,6 +167,7 @@ export async function infiniteScrollToBottom(
     }
   } catch { /* non-fatal */ }
 
+  if (cdpForWheel) cdpForWheel.detach().catch(() => {});
   return { scrollCount, heightReached: previousHeight };
 }
 

package/src/url-pattern-completer.ts

@@ -27,6 +27,33 @@ interface LlmCfg {
   baseUrl?: string;
 }
 
+// Only these two providers are supported by this module (they use standard SDK calls).
+// NVIDIA, groq, ollama, openrouter, etc. are skipped — fall through to env fallback.
+const SUPPORTED = new Set(['openai', 'anthropic']);
+
+/**
+ * Resolve the effective LLM to use. Priority: openai → anthropic → skip others.
+ * Falls back to env vars when the platform-configured provider is unsupported.
+ */
+function resolveTextLLM(llmCfg: LlmCfg | null | undefined): { provider: 'openai' | 'anthropic'; apiKey: string; model: string; baseUrl?: string } | null {
+  // Use platform config if it's a supported provider with a key
+  if (llmCfg?.provider === 'openai' && llmCfg.apiKey) {
+    return { provider: 'openai', apiKey: llmCfg.apiKey, model: llmCfg.model, baseUrl: llmCfg.baseUrl };
+  }
+  if (llmCfg?.provider === 'anthropic' && llmCfg.apiKey) {
+    return { provider: 'anthropic', apiKey: llmCfg.apiKey, model: llmCfg.model };
+  }
+  // Platform provider is unsupported (nvidia, groq, etc.) or no key — fall back to env vars.
+  // OpenAI takes priority over Anthropic.
+  if (process.env.OPENAI_API_KEY) {
+    return { provider: 'openai', apiKey: process.env.OPENAI_API_KEY, model: 'gpt-4o-mini' };
+  }
+  if (process.env.ANTHROPIC_API_KEY) {
+    return { provider: 'anthropic', apiKey: process.env.ANTHROPIC_API_KEY, model: 'claude-haiku-4-5-20251001' };
+  }
+  return null;
+}
+
 /**
  * Returns validated URL candidates (HEAD=200) predicted by LLM from
  * the pattern of already-discovered URLs.
@@ -36,7 +63,8 @@ export async function runUrlPatternCompletion(
   appUrl: string,
   llmCfg: LlmCfg | null | undefined,
 ): Promise<UrlCandidate[]> {
-  if (!llmCfg?.apiKey || discoveredUrls.length < 2) return [];
+  const effective = resolveTextLLM(llmCfg);
+  if (!effective || discoveredUrls.length < 2) return [];
 
   const origin = (() => { try { return new URL(appUrl).origin; } catch { return ''; } })();
   if (!origin) return [];
@@ -49,7 +77,8 @@ export async function runUrlPatternCompletion(
 
   if (internalUrls.length < 2) return [];
 
-  const prompt = `You are analyzing a web application's URL structure to find screens that exist but weren't discovered during automated crawling.
+  const systemPrompt = 'You are a URL pattern analyst. Always respond with valid JSON only.';
+  const userPrompt = `You are analyzing a web application's URL structure to find screens that exist but weren't discovered during automated crawling.
 
 Discovered URLs:
 ${internalUrls.map(u => { try { return new URL(u).pathname + new URL(u).search; } catch { return u; } }).join('\n')}
@@ -67,18 +96,35 @@ Respond with ONLY valid JSON, no explanation:
 {"candidates":[{"path":"/settings/billing","confidence":0.85,"reason":"settings subpage pattern from /settings/profile"},{"path":"/admin/users","confidence":0.6,"reason":"admin prefix implied by /admin/dashboard"}]}`;
 
   try {
-    const Anthropic = (await import('@anthropic-ai/sdk')).default;
-    const client = new Anthropic({ apiKey: llmCfg.apiKey });
-    const response = await client.messages.create({
-      model: llmCfg.model ?? process.env.CRAWLER_DEFAULT_MODEL ?? 'claude-haiku-4-5-20251001',
-      max_tokens: 1024,
-      temperature: 0,
-      // @ts-ignore: cache_control supported in beta
-      system: [{ type: 'text', text: 'You are a URL pattern analyst. Always respond with valid JSON only.', cache_control: { type: 'ephemeral' } }],
-      messages: [{ role: 'user', content: prompt }],
-    });
-
-    const text = (response.content[0] as any)?.text ?? '';
+    let text = '';
+
+    if (effective.provider === 'openai') {
+      const { OpenAI } = await import('openai');
+      const client = new OpenAI({ apiKey: effective.apiKey, ...(effective.baseUrl ? { baseURL: effective.baseUrl } : {}) });
+      const response = await client.chat.completions.create({
+        model: effective.model ?? 'gpt-4o-mini',
+        max_tokens: 1024,
+        temperature: 0,
+        messages: [
+          { role: 'system', content: systemPrompt },
+          { role: 'user', content: userPrompt },
+        ],
+      });
+      text = response.choices[0]?.message?.content ?? '';
+    } else {
+      const Anthropic = (await import('@anthropic-ai/sdk')).default;
+      const client = new Anthropic({ apiKey: effective.apiKey });
+      const response = await client.messages.create({
+        model: effective.model ?? 'claude-haiku-4-5-20251001',
+        max_tokens: 1024,
+        temperature: 0,
+        // @ts-ignore: cache_control supported in beta
+        system: [{ type: 'text', text: systemPrompt, cache_control: { type: 'ephemeral' } }],
+        messages: [{ role: 'user', content: userPrompt }],
+      });
+      text = (response.content[0] as any)?.text ?? '';
+    }
+
     const jsonMatch = text.match(/\{[\s\S]*\}/);
     if (!jsonMatch) return [];
     const parsed = JSON.parse(jsonMatch[0]);
@@ -106,7 +152,7 @@ Respond with ONLY valid JSON, no explanation:
     }
 
     const hits = results.filter(r => r.status === 'hit');
-    logger.info({ total: results.length, hits: hits.length }, '[url-completer] pattern completion done');
+    logger.info({ total: results.length, hits: hits.length, provider: effective.provider }, '[url-completer] pattern completion done');
     return results;
   } catch (err) {
     logger.warn({ err: String(err) }, '[url-completer] LLM call failed — skipping pattern completion');

package/tsconfig.json

@@ -3,7 +3,7 @@
   "compilerOptions": {
     "rootDir": "src",
     "outDir": "dist",
-    "lib": ["ES2022", "DOM"],
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
     "isolatedModules": true,
     "composite": false,
     "noEmitOnError": false

package/types/accessibility-tree-crawler.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Accessibility tree crawler — extract landmark, heading, and ARIA metadata from crawled pages.
+ *
+ * Captures: landmarks with interactive counts, heading hierarchy with violation detection,
+ * interactive elements missing accessible names, live regions, and skip-link presence.
+ *
+ * This data feeds ZeTa's accessibility test generator to surface WCAG 2.1 Level A/AA
+ * failures (missing names, heading skips, absent skip links, unlabeled live regions).
+ */
+export interface LandmarkInfo {
+    role: string;
+    label: string;
+    elementId: string;
+    interactiveCount: number;
+}
+export interface HeadingInfo {
+    level: number;
+    text: string;
+    elementId: string;
+}
+export interface MissingNameEl {
+    tagName: string;
+    role: string;
+    elementId: string;
+    htmlSnippet: string;
+}
+export interface LiveRegionInfo {
+    role: string;
+    ariaLive: string;
+    ariaAtomic: string;
+    currentText: string;
+}
+export interface AccessibilityTreeResult {
+    landmarkCount: number;
+    landmarks: LandmarkInfo[];
+    headings: HeadingInfo[];
+    headingHierarchyViolations: string[];
+    missingNameElements: MissingNameEl[];
+    missingNameCount: number;
+    liveRegions: LiveRegionInfo[];
+    totalInteractiveCount: number;
+    hasSkipLink: boolean;
+}
+export declare function crawlAccessibilityTree(page: any): Promise<AccessibilityTreeResult>;

package/types/advanced-ui-probes.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Advanced UI probes — detect and exercise drag-drop, date pickers, sliders,
+ * and typeahead/autocomplete widgets on a crawled page.
+ *
+ * Results feed ZeTa's test generator so it can emit interaction-level test
+ * cases for these widget families instead of falling back to generic clicks.
+ *
+ * Each probe is independently try/caught so a broken widget does not abort
+ * the others. All browser-side code runs inside page.evaluate / page.$$eval
+ * to avoid serialisation issues with DOM handles.
+ */
+import type { Page } from 'playwright';
+export interface DragDropCapture {
+    library: 'html5' | 'dnd-kit' | 'react-beautiful-dnd' | 'sortablejs' | 'pointer-event' | 'none';
+    draggableCount: number;
+    dropZoneCount: number;
+    testAttempted: boolean;
+    testCompleted: boolean;
+}
+export interface DatePickerCapture {
+    fieldLabel: string;
+    pickerType: 'calendar-popup' | 'native-date' | 'native-datetime' | 'none';
+    minDate?: string;
+    maxDate?: string;
+    disabledDatesFound: boolean;
+    sampleSelectedValue?: string;
+}
+export interface SliderCapture {
+    label: string;
+    min: number;
+    max: number;
+    step: number;
+    currentValue: number;
+}
+export interface TypeaheadCapture {
+    label: string;
+    minCharsToTrigger: number;
+    sampleSuggestions: string[];
+    noResultsText: string | null;
+}
+export interface AdvancedProbeResult {
+    dragDrop: DragDropCapture;
+    datePickers: DatePickerCapture[];
+    sliders: SliderCapture[];
+    typeaheads: TypeaheadCapture[];
+}
+export declare function probeAdvancedUI(page: Page): Promise<AdvancedProbeResult>;

package/types/crawl-session-manager.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Session management for authenticated crawl sessions.
+ * Detects auth expiry via HTTP status codes and login-page redirects,
+ * then attempts recovery via a token refresh endpoint or re-login flow.
+ * Designed to keep long-running crawls alive without manual intervention.
+ */
+import type { Page } from 'playwright';
+export interface SessionConfig {
+    loginUrl?: string;
+    email?: string;
+    password?: string;
+    healthCheckUrl?: string;
+    refreshEndpoint?: string;
+    tokenLocalStorageKey?: string;
+    maxRefreshAttempts?: number;
+}
+export type SessionEventType = 'HEALTHY' | 'EXPIRY_DETECTED' | 'REFRESH_ATTEMPT' | 'REFRESH_SUCCESS' | 'REFRESH_FAILED' | 'AUTH_FAILURE';
+export interface SessionEvent {
+    type: SessionEventType;
+    isoTimestamp: string;
+    url?: string;
+    strategy?: string;
+    attemptCount?: number;
+}
+export interface SessionManager {
+    onResponse(url: string, status: number): void;
+    onNavigation(url: string): void;
+    isHealthy(): boolean;
+    needsRefresh(): boolean;
+    markHealthy(isoTimestamp: string): void;
+    refresh(page: Page, isoTimestamp: string): Promise<boolean>;
+    getEvents(): SessionEvent[];
+    getStats(): {
+        healthy: boolean;
+        refreshAttempts: number;
+        authFailure: boolean;
+    };
+}
+export declare function createSessionManager(config: SessionConfig): SessionManager;
+/**
+ * Attaches a Playwright response listener to feed HTTP status codes into the
+ * session manager. Returns a cleanup function to remove the listener.
+ */
+export declare function attachSessionWatcher(page: Page, manager: SessionManager): () => void;

package/types/crawler.d.ts

@@ -164,6 +164,7 @@ export declare function crawlProject(opts: {
     segmentIndex: number;
     hasMoreSegments: boolean;
     domHashes: string[];
+    crawlWarnings?: undefined;
 } | {
     screensFound: number;
     screensErrored: number;
@@ -188,9 +189,10 @@ export declare function crawlProject(opts: {
     segmentIndex: number;
     hasMoreSegments: boolean;
     domHashes: string[];
+    crawlWarnings: string[] | undefined;
     discoveredUrls?: undefined;
 }>;
-export declare function domFallbackElements(page: any): Promise<Array<{
+export declare function domFallbackElements(page: any, rawPage?: any): Promise<Array<{
     meaning: string;
     role: string;
     expectedData?: string;

package/types/crud-interaction.d.ts

@@ -0,0 +1,31 @@
+import type { Page } from 'playwright';
+export type EditFlowType = 'inline' | 'modal' | 'navigation' | 'unknown';
+export interface CrudFlowCapture {
+    entityName: string;
+    createTrigger?: string;
+    editFlowType: EditFlowType;
+    editFields: Array<{
+        name: string;
+        type: string;
+        prefilledValue?: string;
+    }>;
+    deleteConfirmation?: {
+        message: string;
+        confirmLabel: string;
+        cancelLabel: string;
+    };
+    createSuccessToast?: string;
+    editSuccessToast?: string;
+    rowCount: number;
+    hasDeleteButton: boolean;
+    hasEditButton: boolean;
+}
+export interface CrudProbeResult {
+    flows: CrudFlowCapture[];
+    toastsObserved: Array<{
+        action: string;
+        text: string;
+        role: string;
+    }>;
+}
+export declare function probeCrudFlows(page: Page, entityName?: string): Promise<CrudProbeResult>;

package/types/dropdown-enumerator.d.ts

@@ -0,0 +1,20 @@
+import type { Page } from 'playwright';
+export interface DropdownOption {
+    value: string;
+    label: string;
+    disabled?: boolean;
+}
+export interface DropdownDef {
+    kind: 'native-select' | 'combobox' | 'listbox' | 'multiselect';
+    label: string;
+    locatorHint: string;
+    options: DropdownOption[];
+    defaultValue?: string;
+    cascadesFrom?: string;
+}
+export interface DropdownEnumerationResult {
+    dropdowns: DropdownDef[];
+    conditionalRevealMap: Record<string, string[]>;
+    totalOptionsFound: number;
+}
+export declare function enumerateDropdowns(page: Page): Promise<DropdownEnumerationResult>;

package/types/filter-pagination-crawler.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Filter state crawling and pagination capture.
+ *
+ * Discovers filter controls (select, checkbox-group, radio-group, search),
+ * applies each meaningful option and records result counts and first-row
+ * values, then detects and walks pagination (numbered, load-more, infinite
+ * scroll). Also captures sort column behaviour.
+ *
+ * All per-filter / per-page errors are caught and skipped so one bad control
+ * never aborts the full crawl.
+ */
+import type { Page } from 'playwright';
+export interface FilterOption {
+    value: string;
+    label: string;
+}
+export interface FilterDef {
+    kind: 'select' | 'checkbox-group' | 'radio-group' | 'search';
+    label: string;
+    locatorHint: string;
+    options: FilterOption[];
+}
+export interface FilterState {
+    filterLabel: string;
+    filterValue: string;
+    resultCount: number | null;
+    firstRowValues: string[];
+}
+export interface PaginationCapture {
+    kind: 'numbered' | 'load-more' | 'infinite-scroll' | 'none';
+    totalPages?: number;
+    totalItems?: number;
+    pageSizes?: number[];
+    pages: Array<{
+        pageNum: number;
+        rowValues: string[];
+    }>;
+}
+export interface FilterPaginationResult {
+    filters: FilterDef[];
+    filterStates: FilterState[];
+    pagination: PaginationCapture;
+    sortColumns: Array<{
+        header: string;
+        ariaSortAfterClick: string | null;
+    }>;
+    searchCapture?: {
+        noResultsText: string | null;
+        sampleSuggestions: string[];
+    };
+}
+export declare function crawlFiltersAndPagination(page: Page): Promise<FilterPaginationResult>;

package/types/gap-pass.d.ts

@@ -26,6 +26,7 @@ interface LlmCfg {
     provider: string;
     model: string;
     apiKey?: string;
+    baseUrl?: string;
 }
 /**
  * Run LLM gap analysis + HEAD validation.

package/types/index.d.ts

@@ -35,5 +35,18 @@ export { startSpan, endSpan, withSpan, increment, flushMetrics } from './telemet
 export type { Span, FinishedSpan } from './telemetry.js';
 export { analyzeFailure } from './failure-analysis-agent.js';
 export type { FailureContext } from './failure-analysis-agent.js';
-export { elementToPlaywrightLocator, elementsToPlaywrightLocators, formatLocatorsForPrompt } from './locator-extractor.js';
+export { elementToPlaywrightLocator, elementsToPlaywrightLocators, formatLocatorsForPrompt, detectAuthWallLocators } from './locator-extractor.js';
 export type { PlaywrightLocator } from './locator-extractor.js';
+export * from './dropdown-enumerator.js';
+export * from './crud-interaction.js';
+export * from './filter-pagination-crawler.js';
+export * from './multi-context-handler.js';
+export * from './advanced-ui-probes.js';
+export * from './state-graph.js';
+export * from './nested-window-crawler.js';
+export * from './shadow-dom-crawler.js';
+export * from './network-action-correlator.js';
+export * from './crawl-session-manager.js';
+export * from './accessibility-tree-crawler.js';
+export * from './performance-metrics.js';
+export * from './service-worker-interceptor.js';

package/types/job-queue.d.ts

@@ -111,22 +111,24 @@ export declare function createTrackedJob(type: string, config: {
     projectId: string;
     [k: string]: any;
 }): Promise<string>;
-/** Mark a tracked job DONE or FAILED. Safe to call in finally — swallows errors. */
+/** Mark a tracked job DONE or FAILED. Safe to call in finally — swallows errors.
+ * Gap 30: When marking FAILED, sets nextRetryAt (1 min) so the retry worker picks it up promptly. */
 export declare function finishTrackedJob(tenantId: string, jobId: string, error?: string): Promise<void>;
 /** Enqueue a generic platform job — returns the job ID immediately. */
 export declare function enqueueJob(type: string, config: any): Promise<string>;
 /** Get the current state of a platform job. */
 export declare function getJob(tenantId: string, jobId: string): Promise<{
     progress: number;
-    error: string | null;
+    id: string;
+    name: string | null;
     type: string;
+    error: string | null;
+    result: import("@prisma/client/runtime/library").JsonValue | null;
     status: string;
     tenantId: string;
     projectId: string;
-    name: string | null;
-    result: import("@prisma/client/runtime/library").JsonValue | null;
-    id: string;
     config: import("@prisma/client/runtime/library").JsonValue;
+    retryCount: number;
     queuedAt: Date;
     startedAt: Date | null;
     finishedAt: Date | null;
@@ -137,19 +139,23 @@ export declare function getJob(tenantId: string, jobId: string): Promise<{
     totalCacheReadTokens: number | null;
     totalEstimatedCostUsd: number | null;
     llmCallCount: number;
+    nextRetryAt: Date | null;
+    dlq: boolean;
+    dlqReason: string | null;
 } | null>;
 /** List recent jobs for a project. */
 export declare function listJobs(tenantId: string, projectId: string): Promise<{
     progress: number;
-    error: string | null;
+    id: string;
+    name: string | null;
     type: string;
+    error: string | null;
+    result: import("@prisma/client/runtime/library").JsonValue | null;
     status: string;
     tenantId: string;
     projectId: string;
-    name: string | null;
-    result: import("@prisma/client/runtime/library").JsonValue | null;
-    id: string;
     config: import("@prisma/client/runtime/library").JsonValue;
+    retryCount: number;
     queuedAt: Date;
     startedAt: Date | null;
     finishedAt: Date | null;
@@ -160,6 +166,9 @@ export declare function listJobs(tenantId: string, projectId: string): Promise<{
     totalCacheReadTokens: number | null;
     totalEstimatedCostUsd: number | null;
     llmCallCount: number;
+    nextRetryAt: Date | null;
+    dlq: boolean;
+    dlqReason: string | null;
 }[]>;
 /** Cancel a RUNNING or QUEUED job. Aborts the in-process crawl and marks DB CANCELLED. */
 export declare function cancelJob(tenantId: string, jobId: string): Promise<void>;

package/types/locator-extractor.d.ts

@@ -22,6 +22,7 @@ export declare function elementToPlaywrightLocator(element: {
 /**
  * Convert an array of DB Element records to deduplicated Playwright locators.
  * Deduplicates by key — higher confidence wins.
+ * Filters out crawl-analysis meta-annotations and produces an auth-wall warning when applicable.
  */
 export declare function elementsToPlaywrightLocators(elements: Array<{
     role?: string | null;
@@ -32,6 +33,12 @@ export declare function elementsToPlaywrightLocators(elements: Array<{
     isInteractive?: boolean | null;
     ariaState?: Record<string, unknown> | null;
 }>): PlaywrightLocator[];
+/**
+ * Detect whether a set of locators was extracted from an auth-wall page.
+ * Returns a warning message if auth-wall detected, null otherwise.
+ * Heuristic: >50% of locators are low-confidence text matches AND at least one matches auth-wall pattern.
+ */
+export declare function detectAuthWallLocators(locators: PlaywrightLocator[]): string | null;
 /**
  * Format locators as a block for injection into LLM script generation prompts.
  * Returns empty string if no locators.

package/types/multi-context-handler.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Multi-context browser handling — detects and records new tabs, iframes,
+ * popups, and file downloads triggered during a page crawl.
+ * This lets ZeTa discover cross-origin flows, OAuth redirects, embedded
+ * third-party content, and downloadable resources that single-page HTTP
+ * crawlers would miss entirely.
+ */
+import type { Page, BrowserContext } from 'playwright';
+export interface NewTabRecord {
+    url: string;
+    linkText: string;
+    isInternal: boolean;
+    httpStatus?: number;
+}
+export interface IframeRecord {
+    src: string;
+    crossOrigin: boolean;
+    sandboxed: boolean;
+    sandboxValue: string | null;
+    accessible: boolean;
+    contentSample: string;
+    hasForm: boolean;
+}
+export interface PopupRecord {
+    url: string;
+    triggerLabel: string;
+    isOAuthLike: boolean;
+}
+export interface DownloadRecord {
+    filename: string;
+    downloadUrl: string;
+    triggerLabel: string;
+}
+export interface MultiContextResult {
+    newTabs: NewTabRecord[];
+    iframes: IframeRecord[];
+    popups: PopupRecord[];
+    downloads: DownloadRecord[];
+}
+/**
+ * Attaches a listener to the BrowserContext that records every new tab
+ * opened while the listener is active. Returns an unsubscribe function.
+ *
+ * Call this before navigating / clicking so that tabs opened during the
+ * crawl are captured, then call the returned function to stop listening.
+ */
+export declare function attachNewTabListener(context: BrowserContext, seedUrl: string, result: MultiContextResult): () => void;
+/**
+ * Probes the current page for multi-context browser events: iframes,
+ * popup windows, and file downloads.
+ *
+ * New-tab tracking is intentionally excluded here — it must be set up at
+ * the crawler level (before navigation) using `attachNewTabListener`.
+ */
+export declare function probeMultiContext(page: Page, context: BrowserContext, seedUrl: string): Promise<MultiContextResult>;