@taodigital/crawler 0.0.0-stage → 1.2.0

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/ai-login.d.ts

@@ -0,0 +1,32 @@
+import type { Stagehand } from '@browserbasehq/stagehand';
+import type { Credentials } from './auth.js';
+/**
+ * Recorded login step from the Chrome extension's step recorder.
+ * {username} and {password} in `value` are substituted at replay time.
+ */
+export interface LoginStep {
+    action: 'fill' | 'click' | 'wait';
+    selector: string;
+    value?: string;
+    ms?: number;
+}
+/**
+ * AI-guided login using Stagehand act/extract.
+ *
+ * @param loginInstructions - Optional natural language description of the login flow.
+ *   When provided, an initial stagehand.act() is called with these instructions to
+ *   navigate the UI (e.g. "click Sign In in the nav, fill email, click Continue").
+ *   The standard 3-step credential fill follows immediately after.
+ * @param opts - Optional tenant/project/job IDs for writing AUTH_STEP CrawlEvidence.
+ */
+export declare function loginWithStagehand(stagehand: Stagehand, creds: Credentials, startUrl: string, captchaOpts?: {
+    apiKey?: string;
+    provider?: '2captcha' | 'capsolver';
+}, emailOtpOpts?: {
+    apiKey?: string;
+    inboxId?: string;
+}, loginInstructions?: string, opts?: {
+    tenantId?: string;
+    projectId?: string;
+    jobId?: string;
+}): Promise<boolean>;

package/types/auth-token-rotator.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Auth token rotator — manage a pool of authenticated sessions for multi-account crawls.
+ *
+ * Use case: crawl the same app as admin+user+guest in one crawl job to discover
+ * role-specific screens that only appear when authenticated with different privileges.
+ * Each session is a Playwright storageState JSON string.
+ *
+ * Sessions are checked out (locked) before use and returned after the page is done.
+ * Round-robin assignment with stale-session eviction after maxAgeMs.
+ */
+export interface SessionEntry {
+    id: string;
+    role: string;
+    storageState: string;
+    createdAt: number;
+    checkedOutAt: number | null;
+    requestCount: number;
+}
+export interface SessionPoolOpts {
+    sessions: Array<{
+        role: string;
+        storageState: string;
+    }>;
+    maxAgeMs?: number;
+    maxRequestsPerSession?: number;
+}
+export declare class AuthTokenRotator {
+    private pool;
+    private readonly maxAgeMs;
+    private readonly maxRequests;
+    constructor(opts: SessionPoolOpts);
+    /** Get the next available session. Returns null if all are checked out. */
+    checkout(): SessionEntry | null;
+    /** Return a session to the pool after use. */
+    checkin(sessionId: string, updatedStorageState?: string): void;
+    /** Get all available sessions (for parallel crawl setup). */
+    getAll(): ReadonlyArray<SessionEntry>;
+    /** Stats for monitoring. */
+    stats(): {
+        total: number;
+        available: number;
+        checkedOut: number;
+        stale: number;
+    };
+    /** Add a new session to the pool at runtime. */
+    addSession(role: string, storageState: string): string;
+}

package/types/auth.d.ts

@@ -0,0 +1,20 @@
+import type { Page } from 'playwright';
+export interface Credentials {
+    username: string;
+    password: string;
+    oneTimeCode?: string;
+    getOneTimeCode?: () => Promise<string>;
+}
+/**
+ * Recorded login step captured by the Chrome extension.
+ * {username} and {password} in `value` are substituted at replay time.
+ */
+export interface LoginStep {
+    action: 'fill' | 'click' | 'wait';
+    selector: string;
+    value?: string;
+    ms?: number;
+}
+export declare function login(page: Page, appUrl: string, creds: Credentials & {
+    loginRecipe?: LoginStep[];
+}): Promise<boolean>;

package/types/browser-extension.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Browser extension injection support.
+ *
+ * Chrome extensions require a persistent profile directory — incompatible
+ * with headless Docker by default. This module handles:
+ *   1. Persistent profile directory per extension set
+ *   2. Extension download from .crx URL or load from local path
+ *   3. Launch args for Playwright / Stagehand
+ *
+ * Usage:
+ *   const profile = await prepareExtensionProfile(['/path/to/ext.crx']);
+ *   // pass profile.userDataDir and profile.args to browser launch
+ */
+export interface ExtensionSource {
+    /** Local .crx file path or https:// URL to download from */
+    source: string;
+    /** Friendly name for logging */
+    name?: string;
+}
+export interface ExtensionProfile {
+    /** Chrome user-data-dir containing Preferences + extension unpacked dirs */
+    userDataDir: string;
+    /** Args to append to chromium launch — includes --load-extension and --disable-extensions-except */
+    args: string[];
+    /** Cleanup the profile directory when done */
+    cleanup: () => Promise<void>;
+}
+/**
+ * Prepare a Chrome user-data-dir with the given extensions loaded.
+ * Returns profile info + cleanup function.
+ */
+export declare function prepareExtensionProfile(extensions: ExtensionSource[]): Promise<ExtensionProfile>;
+/**
+ * Ad-blocker extension profile using the uBlock Origin CRX.
+ * Reduces noise from ad networks during crawls.
+ */
+export declare function adBlockerProfile(): Promise<ExtensionProfile>;

package/types/bull-worker.d.ts

@@ -0,0 +1,6 @@
+import { Worker } from 'bullmq';
+export declare function startBullWorker(redisUrl?: string): Worker<{
+    jobId: string;
+    tenantId: string;
+    config: any;
+}, any, string>;

package/types/captcha-solver.d.ts

@@ -0,0 +1,16 @@
+/**
+ * CAPTCHA auto-solving via 2captcha or CapSolver APIs.
+ * Supports reCAPTCHA v2, hCaptcha, and Cloudflare Turnstile.
+ */
+export type CaptchaSolverProvider = '2captcha' | 'capsolver';
+interface SolveResult {
+    token: string;
+    provider: CaptchaSolverProvider;
+}
+/**
+ * Detect CAPTCHA type and sitekey on the page, then solve it.
+ * Returns null if no CAPTCHA found or solver not configured.
+ * Throws on solve failure.
+ */
+export declare function solveCaptcha(page: any, pageUrl: string, apiKey: string, provider?: CaptchaSolverProvider): Promise<SolveResult | null>;
+export {};

package/types/color-contrast.d.ts

@@ -0,0 +1,30 @@
+/**
+ * WCAG color contrast checker.
+ *
+ * Evaluates text contrast ratios against backgrounds for all visible text elements.
+ * Reports elements that fail WCAG 2.1 AA (4.5:1 for normal text, 3:1 for large text)
+ * or AAA (7:1 for normal, 4.5:1 for large text) requirements.
+ *
+ * Uses computedStyle to get actual rendered colors — accounts for CSS variables
+ * and inheritance.
+ */
+import type { Page } from 'playwright';
+export interface ContrastViolation {
+    selector: string;
+    text: string;
+    foreground: string;
+    background: string;
+    ratio: number;
+    required: number;
+    level: 'AA' | 'AAA';
+    isLargeText: boolean;
+    severity: 'fail' | 'warn';
+}
+export interface ContrastAuditResult {
+    url: string;
+    violations: ContrastViolation[];
+    passCount: number;
+    score: number;
+    auditedAt: string;
+}
+export declare function auditColorContrast(page: Page, url: string): Promise<ContrastAuditResult>;

package/types/content-chunker.d.ts

@@ -0,0 +1,18 @@
+export type ChunkingStrategy = 'fixed' | 'overlap' | 'sentence' | 'paragraph' | 'markdown-heading' | 'semantic' | 'recursive';
+export interface ChunkOpts {
+    strategy: ChunkingStrategy;
+    chunkSize?: number;
+    overlap?: number;
+    separators?: string[];
+}
+export interface Chunk {
+    index: number;
+    text: string;
+    tokenEstimate: number;
+    startChar: number;
+    endChar: number;
+    heading?: string;
+}
+export declare function estimateTokens(text: string): number;
+export declare function chunkContent(text: string, opts: ChunkOpts): Chunk[];
+export declare function mergeSmallChunks(chunks: Chunk[], minTokens: number): Chunk[];

package/types/content-dedup.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Content deduplication — detect near-duplicate pages during crawl.
+ *
+ * Uses MinHash-inspired approach: instead of full MinHash (needs many hash functions),
+ * we use 8 structural fingerprints extracted from the markdown to detect pages that
+ * share the same layout/template even if the data differs.
+ *
+ * Typical duplicates: /products?page=1 vs /products?page=2 (same template, different data).
+ * These waste crawl budget and generate redundant test cases.
+ */
+export interface DedupResult {
+    isDuplicate: boolean;
+    similarUrl?: string;
+    similarityScore: number;
+}
+export declare class ContentDeduplicator {
+    private seen;
+    private readonly threshold;
+    constructor(threshold?: number);
+    check(url: string, markdown: string): DedupResult;
+    size(): number;
+    reset(): void;
+}

package/types/cookie-consent.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Cookie consent auto-acceptor.
+ *
+ * Detects and clicks "Accept" on common cookie consent banners before the
+ * crawler proceeds. Without this, many EU sites show a consent wall that
+ * blocks content or shows a different layout, making crawl results unreliable.
+ *
+ * Supports: Cookiebot, OneTrust, TrustArc, Usercentrics, GDPR Cookie Compliance,
+ * generic "Accept All" / "Accept Cookies" buttons.
+ *
+ * Strategy: try known selectors first, then fall back to text-based button search.
+ * Non-blocking — if no banner is found or click fails, crawl proceeds normally.
+ */
+import type { Page } from 'playwright';
+export interface ConsentResult {
+    found: boolean;
+    clicked: boolean;
+    method?: string;
+    error?: string;
+}
+export declare function acceptCookieConsent(page: Page, opts?: {
+    waitMs?: number;
+}): Promise<ConsentResult>;
+/** Check if a consent banner is still visible after attempted dismissal */
+export declare function isConsentBannerVisible(page: Page): Promise<boolean>;

package/types/cookie-jar.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Cookie jar — persist and restore Playwright storageState cookies between
+ * crawl segments and restarts. Enables continuous auth across session boundaries
+ * (e.g. segment 1 logs in, segment 2–N inherit the session without re-login).
+ *
+ * Storage: JSON file per project in the crawl cache dir.
+ * Format: Playwright's storageState shape (cookies + origins).
+ */
+export interface CookieJarEntry {
+    projectId: string;
+    tenantId: string;
+    storageState: string;
+    savedAt: string;
+    domain: string;
+}
+export declare function saveCookieJar(cacheDir: string, projectId: string, tenantId: string, storageState: string, domain: string): Promise<void>;
+export declare function loadCookieJar(cacheDir: string, projectId: string, maxAgeMs?: number): Promise<string | null>;
+export declare function clearCookieJar(cacheDir: string, projectId: string): Promise<void>;
+/** Merge two storageState JSON strings — second takes priority for same-domain cookies. */
+export declare function mergeStorageStates(base: string, overlay: string): string;

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

@@ -0,0 +1,233 @@
+/**
+ * ZeTa-AI Crawler — Stagehand hybrid architecture
+ *
+ * Three-layer stack:
+ *   Layer 1 — Playwright (deterministic): navigation, screenshots, DOM fallbacks
+ *   Layer 2 — Stagehand act/extract (AI): login, element understanding, smart link discovery
+ *   Layer 3 — Skyvern (vision): fallback for CAPTCHAs, legacy apps, visual-only flows
+ *
+ * enableCaching: true → repeat crawls of the same site cost ~zero AI tokens after first run.
+ */
+import type { Credentials } from './auth.js';
+import { type SkyvernConfig } from './skyvern.js';
+import { type TraversalStrategy } from './frontier.js';
+import { type ApiEndpointObservationInput } from './network-observer.js';
+import type { ProxyTierConfig } from './proxy.js';
+interface PerformanceMetric {
+    url: string;
+    screenName: string;
+    lcp?: number;
+    fcp?: number;
+    ttfb?: number;
+    cls?: number;
+}
+export interface DiscoveredLinkMeta {
+    url: string;
+    text?: string;
+    landmark?: string;
+    source: 'DOM' | 'AI' | 'INTERACTIVE';
+}
+export declare function getNonHeadlessUserAgent(executablePath?: string): Promise<string>;
+/**
+ * Lightweight pre-crawl link discovery: loads the app URL in a headless (proxy-aware) browser
+ * and returns same-site `<a href>` links. Complements sitemap discovery for SPA/app sites that
+ * have no sitemap.xml. Best-effort — returns [] on any failure (bot wall, timeout, etc.).
+ * chromium.launch({ proxy }) handles proxy 407 auth itself (same client), so no CDP handler needed.
+ */
+export declare function discoverLinksViaBrowser(appUrl: string, opts?: {
+    proxyUrl?: string;
+    maxLinks?: number;
+}): Promise<string[]>;
+export declare function crawlProject(opts: {
+    tenantId: string;
+    projectId: string;
+    appUrl: string;
+    /** The viewport used for this crawl pass */
+    viewport?: 'DESKTOP' | 'MOBILE_PORTRAIT' | 'TABLET';
+    credentials?: Credentials;
+    /** Playwright storageState JSON string — if present, session is restored and AI login is skipped. */
+    storageState?: string;
+    screenshotDir?: string;
+    /** Cloud storage config for immediate screenshot upload. If set, screenshots are uploaded to cloud immediately after capture and cloudUrl is persisted. */
+    storageConfig?: {
+        provider: string;
+        bucket: string;
+        region?: string;
+        accountId?: string;
+        endpointUrl?: string;
+        accessKeyId?: string;
+        secretAccessKey?: string;
+        prefix?: string;
+        publicUrl?: string;
+    } | null;
+    /** When true, run a fast URL-only discovery crawl — skips screenshots, DB saves, and AI element extraction. Returns discoveredUrls in the result object. */
+    discoveryMode?: boolean;
+    maxScreens?: number;
+    /** Seed URLs added to the initial crawl queue — link discovery still runs from each page. */
+    startUrls?: string[];
+    /** When provided, crawl ONLY these exact URLs (no link-following, no full screen clear). Used for selected-screen recrawl. */
+    selectiveUrls?: string[];
+    /**
+     * URL path patterns that bypass the CUID/UUID generated-ID filter during BFS link discovery.
+     * Use {id} as a placeholder for any generated path segment (CUID, UUID, numeric ID, etc.).
+     * Example: ['/projects/{id}/tests', '/workspaces/{id}/settings']
+     * Without this, all URLs containing generated IDs are silently skipped by the BFS.
+     */
+    seedPathPatterns?: string[];
+    /** When true, run the interactive probe after static crawl to capture real validation errors, toasts, and modals. */
+    interactive?: boolean;
+    /** Optional abort signal — abort() cancels the crawl between page navigations. */
+    abortSignal?: AbortSignal;
+    /** Platform job ID — stored on screens so we can diff which were found in each crawl. */
+    jobId?: string;
+    /** Device profiles to capture screenshots for after the main DESKTOP crawl.
+     *  Values: 'MOBILE_PORTRAIT' | 'TABLET'
+     *  The main crawl always runs as DESKTOP. Extra profiles trigger a screenshot-only pass.
+     */
+    deviceProfiles?: string[];
+    /** HTTP Basic Auth credentials — injected as Authorization header on same-origin requests. */
+    httpBasicUsername?: string;
+    httpBasicPassword?: string;
+    /** Bearer/API token — injected as a request header and into localStorage. Skips AI login. */
+    authToken?: string;
+    /** Header name for authToken (default: 'Authorization'). */
+    authTokenHeader?: string;
+    /** Prefix for authToken value (default: 'Bearer '). */
+    authTokenPrefix?: string;
+    /** CAPTCHA solving API key (2captcha or CapSolver). */
+    captchaSolverApiKey?: string;
+    /** CAPTCHA solving service provider (default: '2captcha'). */
+    captchaSolverProvider?: '2captcha' | 'capsolver';
+    /**
+     * Path to a Chrome user data directory for profile inheritance.
+     * When set, the crawler exports the existing session from this profile and injects it,
+     * so the agent is already logged in. Works for local/self-hosted deployments only.
+     * Ignored on cloud/Docker (headless env cannot open another Chrome instance safely).
+     */
+    chromeProfilePath?: string;
+    /** MailSlurp API key for email OTP auto-retrieval (GAP 5). */
+    mailslurpApiKey?: string;
+    /** MailSlurp inbox ID to poll for OTP emails (GAP 5). */
+    mailslurpInboxId?: string;
+    /** SSO provider for ROPC token flow — 'okta' | 'azure_ad' | 'generic_oidc' (GAP 18). */
+    ssoProvider?: string;
+    /** SSO domain or Azure tenant ID (GAP 18). */
+    ssoDomain?: string;
+    /** SSO OAuth2 client ID (GAP 18). */
+    ssoClientId?: string;
+    /** SSO OAuth2 client secret (GAP 18). */
+    ssoClientSecret?: string;
+    /** SSO scopes (space-separated, default: 'openid profile') (GAP 18). */
+    ssoScope?: string;
+    /** HTTP/HTTPS/SOCKS5 proxy URL — e.g. 'http://user:pass@proxy.example.com:8080' or 'socks5://proxy:1080'.
+     *  Useful for sites that block datacenter IPs (Akamai, Cloudflare Bot Manager). */
+    proxyUrl?: string;
+    /** Tiered proxy configuration for automatic per-domain escalation (free → datacenter → residential → premium). */
+    proxyTiers?: ProxyTierConfig[];
+    /** Use Camoufox (Firefox) as a cookie bootstrapper before the main Chromium crawl.
+     *  Camoufox visits the URL first to solve Cloudflare JS challenges and extract session
+     *  cookies, which are then injected into the Chromium crawl as storageState.
+     *  Enable via Project Settings → Crawl Config → useFirefox: true. */
+    useFirefox?: boolean;
+    /** Natural language login instructions for Stagehand AI login. E.g. "Click Sign In in the nav, fill email, click Continue". */
+    loginInstructions?: string;
+    /** Skyvern vision fallback config from workspace settings (overrides SKYVERN_API_URL/KEY env vars). */
+    skyvernConfig?: SkyvernConfig;
+    /**
+     * Max screens to crawl per segment (default 50).
+     * After this limit the crawl pauses and remaining URLs are saved so the
+     * next job can continue. Total crawl is unlimited — just runs in multiple jobs.
+     */
+    segmentSize?: number;
+    /** URLs still queued from a previous segment — injected by the job-queue auto-continuation. */
+    resumeUrls?: string[];
+    /** Segment number (1-based) — used for progress display only. */
+    segmentIndex?: number;
+    /** Seed the crawl queue from the project's sitemap.xml, in addition to link-following. */
+    useSitemap?: boolean;
+    /** Explicit sitemap URL override — defaults to `${origin}/sitemap.xml` when useSitemap is set. */
+    sitemapUrl?: string;
+    /** Crawl queue traversal order. Default BFS — unchanged behavior from before this option existed. */
+    traversalStrategy?: TraversalStrategy;
+    /** BEST_FIRST only: URLs containing any of these (case-insensitive) are prioritized. */
+    bestFirstKeywords?: string[];
+    /** When true, skip URLs disallowed by the site's robots.txt. Default false. */
+    respectRobotsTxt?: boolean;
+    /** When true, dynamically slow crawl speed when server response latency is high (Scrapy-style AutoThrottle). Default false. */
+    autoThrottle?: boolean;
+    /** Regex pattern — only crawl URLs whose path+query match this pattern. */
+    urlFilter?: string;
+    /** Glob patterns — only enqueue URLs whose pathname matches at least one (supports * and **). */
+    includePatterns?: string[];
+    /** Glob patterns — skip URLs whose pathname matches any of these (supports * and **). */
+    excludePatterns?: string[];
+    /** Already-captured URLs from a previous failed job — pre-seeded into visited map so they're never re-crawled. */
+    skipUrls?: string[];
+    /** DOM hashes collected in a prior segment — prevents re-screenshotting structurally identical pages across segments. */
+    knownDomHashes?: string[];
+    /** When false, disables the puppeteer-extra stealth plugin (playwright-extra) for this crawl.
+     *  Default true — stealth is applied unless explicitly set to false. */
+    stealth?: boolean;
+    /** Desktop viewport width in pixels (default: 1440). */
+    viewportWidth?: number;
+    /** Desktop viewport height in pixels (default: 900). */
+    viewportHeight?: number;
+    /** Called every 10 successful screen captures with current visited URLs and remaining queue — used for checkpoint persistence. */
+    onCheckpoint?: (visitedUrls: string[], pendingQueue: string[]) => Promise<void>;
+    /** Discovery mode only: called after each page with the current set of discovered original URLs — enables streaming partial results to callers. */
+    onUrlsDiscovered?: (urls: string[]) => Promise<void>;
+}, onProgress?: (pct: number, step: string) => Promise<void>): Promise<{
+    discoveredUrls: string[];
+    screensFound: number;
+    screensErrored: number;
+    screensSkippedToNextSegment: number;
+    isPartial: boolean;
+    discovered: never[];
+    apiEndpoints: never[];
+    performanceMetrics: never[];
+    pendingUrls: never[];
+    segmentIndex: number;
+    hasMoreSegments: boolean;
+    domHashes: string[];
+    visitedUrls?: undefined;
+    wasTimeout?: undefined;
+    crawlWarnings?: undefined;
+} | {
+    screensFound: number;
+    screensErrored: number;
+    screensSkippedToNextSegment: number;
+    isPartial: boolean;
+    discovered: {
+        url: string;
+        screenId?: string;
+        elements?: number;
+        elementFacts?: Array<{
+            meaning: string;
+            role: string;
+            expectedData?: string;
+        }>;
+        screenshotPath?: string;
+        version?: number;
+        error?: string;
+    }[];
+    apiEndpoints: ApiEndpointObservationInput[];
+    performanceMetrics: PerformanceMetric[];
+    pendingUrls: string[];
+    visitedUrls: string[];
+    wasTimeout: boolean;
+    segmentIndex: number;
+    hasMoreSegments: boolean;
+    domHashes: string[];
+    crawlWarnings: string[] | undefined;
+    discoveredUrls?: undefined;
+}>;
+export declare function domFallbackElements(page: any, rawPage?: any): Promise<Array<{
+    meaning: string;
+    role: string;
+    expectedData?: string;
+    notes?: string;
+    boundingRect?: Record<string, number>;
+    ariaState?: Record<string, string>;
+    parentLandmark?: string;
+}>>;
+export {};

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>;