playwright-archaeologist 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,1948 @@
+import { z } from 'zod';
+import { Page, Response, BrowserContext, Browser } from 'playwright';
+
+/**
+ * playwright-archaeologist configuration schema.
+ *
+ * Validated with Zod at CLI entry before any crawl work begins.
+ * ConfigError is thrown for all validation failures with a clear
+ * user-facing message indicating which field failed and why.
+ *
+ * Validation rules and edge cases:
+ *   --depth 0              Valid (crawl only the entry URL)
+ *   --depth -1             Invalid: must be >= 0
+ *   --depth 999999         Valid but warn: clamped to 100 with warning
+ *   --concurrency 0        Invalid: must be >= 1
+ *   --concurrency 100      Valid but warn: clamped to 20 with warning
+ *   --viewport invalid     Invalid: must match /^\d+x\d+$/
+ *   --viewport 100x100     Valid
+ *   --output /nonexistent  Validated at startup: parent dir must exist and be writable
+ *   --auth missing.ts      AuthError('script_not_found')
+ *   --cookies bad.json     AuthError('cookie_file_malformed')
+ *   URL without protocol   Auto-prepend https:// with warning
+ *   --timeout 0            Invalid: must be >= 1000
+ *   --max-time 0           Invalid: must be >= 10
+ *   --delay -1             Invalid: must be >= 0
+ *   --max-pages 0          Invalid: must be >= 1
+ *
+ * The Zod schema produces a strongly-typed CrawlConfig object that is
+ * passed to the Orchestrator and threaded through to all collectors.
+ */
+
+declare const ViewportSchema: z.ZodObject<{
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    width: number;
+    height: number;
+}, {
+    width: number;
+    height: number;
+}>;
+type Viewport = z.infer<typeof ViewportSchema>;
+/**
+ * Parse a "WxH" string into a Viewport object.
+ * Returns null if the format is invalid.
+ */
+declare function parseViewport(input: string): Viewport | null;
+declare const OutputFormatSchema: z.ZodEnum<["html", "json", "openapi", "both"]>;
+type OutputFormat = z.infer<typeof OutputFormatSchema>;
+/**
+ * Normalize the user-provided entry URL.
+ * - Prepend https:// if no protocol is provided
+ * - Validate it is http or https
+ * Returns { url, warnings } where warnings contains any auto-corrections.
+ */
+declare function normalizeEntryUrl(raw: string): {
+    url: string;
+    warnings: string[];
+};
+declare const CrawlConfigSchema: z.ZodObject<{
+    /** Entry URL to start crawling. Must be http or https. */
+    targetUrl: z.ZodString;
+    /** Maximum crawl depth from the entry URL. 0 = entry URL only. */
+    depth: z.ZodDefault<z.ZodNumber>;
+    /** Maximum total pages to visit. */
+    maxPages: z.ZodDefault<z.ZodNumber>;
+    /** URL glob patterns to include. Only URLs matching at least one pattern are crawled. */
+    include: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** URL glob patterns to exclude. URLs matching any pattern are skipped. */
+    exclude: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Whether to follow links to external origins. Default: false (same-origin only). */
+    followExternal: z.ZodDefault<z.ZodBoolean>;
+    /** Enable Tier 3 clicking: click non-link interactive elements to discover SPA states. */
+    deepClick: z.ZodDefault<z.ZodBoolean>;
+    /** Crawl cross-origin iframe content. Default: false (record URL only). */
+    includeIframes: z.ZodDefault<z.ZodBoolean>;
+    /** Number of parallel browser contexts. */
+    concurrency: z.ZodDefault<z.ZodNumber>;
+    /** Delay in milliseconds between page visits per context. */
+    delay: z.ZodDefault<z.ZodNumber>;
+    /** Per-page navigation timeout in milliseconds. */
+    timeout: z.ZodDefault<z.ZodNumber>;
+    /** Global crawl timeout in seconds. 0 = no limit. */
+    maxTime: z.ZodDefault<z.ZodNumber>;
+    /** Path to auth script (.ts or .js) exporting a default async function. */
+    authScript: z.ZodOptional<z.ZodString>;
+    /** Path to cookies JSON file for session injection. */
+    cookiesFile: z.ZodOptional<z.ZodString>;
+    /** Include cookies/auth headers in output (default: scrubbed). */
+    includeCookies: z.ZodDefault<z.ZodBoolean>;
+    /** Output directory path. Created if it does not exist. Parent must exist. */
+    outputDir: z.ZodDefault<z.ZodString>;
+    /** Output format(s). */
+    format: z.ZodDefault<z.ZodEnum<["html", "json", "openapi", "both"]>>;
+    /** Skip screenshot capture entirely. */
+    noScreenshots: z.ZodDefault<z.ZodBoolean>;
+    /** Skip HAR recording entirely. */
+    noHar: z.ZodDefault<z.ZodBoolean>;
+    /** Primary viewport dimensions. */
+    viewport: z.ZodDefault<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        width: number;
+        height: number;
+    }, {
+        width: number;
+        height: number;
+    }>>;
+    /** Additional viewports for responsive screenshots (empty = primary only). */
+    additionalViewports: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        width: number;
+        height: number;
+    }, {
+        width: number;
+        height: number;
+    }>, "many">>;
+    /** Resume from last checkpoint in the output directory. */
+    resume: z.ZodDefault<z.ZodBoolean>;
+    /** Skip confirmation prompts (auth script execution, etc.). */
+    yes: z.ZodDefault<z.ZodBoolean>;
+    /** Allow crawling private/internal IP ranges (SSRF protection bypass). */
+    allowPrivate: z.ZodDefault<z.ZodBoolean>;
+    /** Pixel diff threshold (0-1 scale, lower = more sensitive). */
+    diffThreshold: z.ZodDefault<z.ZodNumber>;
+    /** Maximum diff ratio (0-100%) before a screenshot is considered "changed". */
+    diffMaxRatio: z.ZodDefault<z.ZodNumber>;
+    /** Fields to ignore during API diff (comma-separated or array). */
+    diffIgnoreFields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    depth: number;
+    concurrency: number;
+    delay: number;
+    timeout: number;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    outputDir: string;
+    targetUrl: string;
+    maxPages: number;
+    include: string[];
+    exclude: string[];
+    followExternal: boolean;
+    deepClick: boolean;
+    includeIframes: boolean;
+    maxTime: number;
+    includeCookies: boolean;
+    format: "html" | "json" | "openapi" | "both";
+    noScreenshots: boolean;
+    noHar: boolean;
+    additionalViewports: {
+        width: number;
+        height: number;
+    }[];
+    resume: boolean;
+    yes: boolean;
+    allowPrivate: boolean;
+    diffThreshold: number;
+    diffMaxRatio: number;
+    diffIgnoreFields: string[];
+    authScript?: string | undefined;
+    cookiesFile?: string | undefined;
+}, {
+    targetUrl: string;
+    depth?: number | undefined;
+    concurrency?: number | undefined;
+    delay?: number | undefined;
+    timeout?: number | undefined;
+    viewport?: {
+        width: number;
+        height: number;
+    } | undefined;
+    outputDir?: string | undefined;
+    maxPages?: number | undefined;
+    include?: string[] | undefined;
+    exclude?: string[] | undefined;
+    followExternal?: boolean | undefined;
+    deepClick?: boolean | undefined;
+    includeIframes?: boolean | undefined;
+    maxTime?: number | undefined;
+    authScript?: string | undefined;
+    cookiesFile?: string | undefined;
+    includeCookies?: boolean | undefined;
+    format?: "html" | "json" | "openapi" | "both" | undefined;
+    noScreenshots?: boolean | undefined;
+    noHar?: boolean | undefined;
+    additionalViewports?: {
+        width: number;
+        height: number;
+    }[] | undefined;
+    resume?: boolean | undefined;
+    yes?: boolean | undefined;
+    allowPrivate?: boolean | undefined;
+    diffThreshold?: number | undefined;
+    diffMaxRatio?: number | undefined;
+    diffIgnoreFields?: string[] | undefined;
+}>;
+type CrawlConfig = z.infer<typeof CrawlConfigSchema>;
+declare const DiffConfigSchema: z.ZodObject<{
+    /** Path to the "old" .archaeologist bundle. */
+    oldBundle: z.ZodString;
+    /** Path to the "new" .archaeologist bundle. */
+    newBundle: z.ZodString;
+    /** Output directory for diff report and artifacts. */
+    outputDir: z.ZodDefault<z.ZodString>;
+    /** Pixel diff threshold. */
+    diffThreshold: z.ZodDefault<z.ZodNumber>;
+    /** Maximum diff ratio. */
+    diffMaxRatio: z.ZodDefault<z.ZodNumber>;
+    /** Fields to ignore during API response diff. */
+    diffIgnoreFields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Normalize dynamic values (UUIDs, timestamps, JWTs) before diffing. */
+    normalizeDynamicValues: z.ZodDefault<z.ZodBoolean>;
+    /** Show detailed value-level diffs (default: schema-level only). */
+    detailed: z.ZodDefault<z.ZodBoolean>;
+    /** Output formats for the diff report. */
+    outputFormats: z.ZodDefault<z.ZodObject<{
+        html: z.ZodOptional<z.ZodString>;
+        json: z.ZodOptional<z.ZodString>;
+        junit: z.ZodOptional<z.ZodString>;
+        markdown: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        html?: string | undefined;
+        json?: string | undefined;
+        junit?: string | undefined;
+        markdown?: string | undefined;
+    }, {
+        html?: string | undefined;
+        json?: string | undefined;
+        junit?: string | undefined;
+        markdown?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    outputDir: string;
+    diffThreshold: number;
+    diffMaxRatio: number;
+    diffIgnoreFields: string[];
+    oldBundle: string;
+    newBundle: string;
+    normalizeDynamicValues: boolean;
+    detailed: boolean;
+    outputFormats: {
+        html?: string | undefined;
+        json?: string | undefined;
+        junit?: string | undefined;
+        markdown?: string | undefined;
+    };
+}, {
+    oldBundle: string;
+    newBundle: string;
+    outputDir?: string | undefined;
+    diffThreshold?: number | undefined;
+    diffMaxRatio?: number | undefined;
+    diffIgnoreFields?: string[] | undefined;
+    normalizeDynamicValues?: boolean | undefined;
+    detailed?: boolean | undefined;
+    outputFormats?: {
+        html?: string | undefined;
+        json?: string | undefined;
+        junit?: string | undefined;
+        markdown?: string | undefined;
+    } | undefined;
+}>;
+type DiffConfig = z.infer<typeof DiffConfigSchema>;
+/**
+ * ResolvedConfig is the fully validated and resolved config passed to
+ * the Orchestrator. All paths are absolute, all defaults are applied,
+ * and the entry URL is normalized.
+ */
+interface ResolvedConfig extends CrawlConfig {
+    /** Absolute path to the resolved output directory. */
+    outputDir: string;
+    /** Absolute path to the auth script, if provided. */
+    authScript?: string;
+    /** Absolute path to the cookies file, if provided. */
+    cookiesFile?: string;
+    /** Warnings generated during config resolution (e.g. auto-prepended https://). */
+    warnings: string[];
+}
+
+/**
+ * playwright-archaeologist error types.
+ *
+ * Error hierarchy:
+ *   ArchaeologistError (base)
+ *   +-- ConfigError              Invalid CLI options or config file
+ *   +-- AuthError                Auth script loading, execution, or validation failure
+ *   +-- CrawlError (base)       Any error during the crawl phase
+ *   |   +-- NavigationError      page.goto failure (timeout, network, HTTP >= 400)
+ *   |   +-- CollectorError       A collector (scanner/prober/logger/capturer) failed on a page
+ *   |   +-- BrowserContextError  Context crashed or was killed
+ *   |   +-- FrontierError        URL queue corruption or checkpoint I/O failure
+ *   |   +-- SecurityBlockError   SSRF or protocol violation blocked a request
+ *   +-- AssemblerError           Data merging or dedup failure
+ *   +-- ReportError              Report generation failure (HTML, JSON, OpenAPI, Mermaid)
+ *   +-- DiffError                Bundle loading, comparison, or diff report failure
+ *   +-- BundleError              .archaeologist bundle I/O or integrity failure
+ *
+ * Error propagation rules:
+ *   - NavigationError on one page:  log + skip page, crawl continues
+ *   - CollectorError on one page:   log + partial data, crawl continues
+ *   - BrowserContextError:          recycle context, re-enqueue URL, crawl continues
+ *   - FrontierError (checkpoint):   warn, crawl continues without checkpointing
+ *   - SecurityBlockError:           log + skip URL, crawl continues
+ *   - ConfigError:                  abort with user-facing message before crawl starts
+ *   - AuthError:                    abort with user-facing message before crawl starts
+ *   - AssemblerError:               abort, partial output may exist
+ *   - ReportError:                  degrade gracefully (skip failed section, warn)
+ *   - DiffError:                    abort with exit code 2
+ *   - BundleError:                  abort with exit code 2
+ */
+declare class ArchaeologistError extends Error {
+    /** Machine-readable error code for programmatic handling. */
+    readonly code: string;
+    constructor(message: string, code: string, options?: ErrorOptions);
+}
+declare class ConfigError extends ArchaeologistError {
+    /** The config field that failed validation (e.g. "depth", "viewport"). */
+    readonly field: string;
+    /** The invalid value the user supplied. */
+    readonly value: unknown;
+    constructor(field: string, message: string, value?: unknown);
+}
+type AuthErrorReason = 'script_not_found' | 'script_import_failed' | 'script_no_default_export' | 'script_execution_failed' | 'script_dangerous_import' | 'script_user_declined' | 'cookie_file_not_found' | 'cookie_file_malformed' | 'auth_verification_failed';
+declare class AuthError extends ArchaeologistError {
+    readonly reason: AuthErrorReason;
+    readonly scriptPath?: string;
+    constructor(reason: AuthErrorReason, message: string, scriptPath?: string, options?: ErrorOptions);
+}
+declare class CrawlError extends ArchaeologistError {
+    /** The URL being processed when the error occurred. */
+    readonly url: string;
+    constructor(message: string, code: string, url: string, options?: ErrorOptions);
+}
+type NavigationStatus = 'timeout' | 'network_error' | 'http_error' | 'no_response' | 'aborted' | 'redirect_loop';
+declare class NavigationError extends CrawlError {
+    readonly status: NavigationStatus;
+    /** HTTP status code, if applicable (e.g. 404, 500). */
+    readonly httpStatus?: number;
+    constructor(url: string, status: NavigationStatus, message: string, httpStatus?: number, options?: ErrorOptions);
+}
+type CollectorName = 'page-scanner' | 'form-prober' | 'network-logger' | 'screenshot-capturer';
+declare class CollectorError extends CrawlError {
+    readonly collector: CollectorName;
+    constructor(collector: CollectorName, url: string, message: string, options?: ErrorOptions);
+}
+type SecurityBlockReason = 'private_ip' | 'blocked_protocol' | 'dns_rebinding' | 'metadata_endpoint' | 'redirect_to_private';
+type DiffErrorReason = 'bundle_not_found' | 'bundle_corrupt' | 'manifest_invalid' | 'incompatible_config' | 'screenshot_size_mismatch' | 'diff_generation_failed';
+declare class DiffError extends ArchaeologistError {
+    readonly reason: DiffErrorReason;
+    constructor(reason: DiffErrorReason, message: string, options?: ErrorOptions);
+}
+type BundleErrorReason = 'create_failed' | 'extract_failed' | 'integrity_check_failed' | 'missing_manifest' | 'unsupported_version' | 'output_dir_not_writable';
+declare class BundleError extends ArchaeologistError {
+    readonly reason: BundleErrorReason;
+    readonly bundlePath?: string;
+    constructor(reason: BundleErrorReason, message: string, bundlePath?: string, options?: ErrorOptions);
+}
+interface CrawlErrorEntry {
+    timestamp: string;
+    url: string;
+    code: string;
+    message: string;
+    collector?: CollectorName;
+    status?: NavigationStatus;
+    httpStatus?: number;
+    securityReason?: SecurityBlockReason;
+}
+
+/**
+ * playwright-archaeologist artifact type definitions.
+ *
+ * Data flow through the system:
+ *
+ *   CLI (ResolvedConfig)
+ *     |
+ *     v
+ *   Orchestrator ----> per-page collectors (parallel)
+ *     |                  |
+ *     |   PageScanner  ---> PageScanResult
+ *     |   FormProber   ---> FormProbeResult
+ *     |   NetworkLogger -> NetworkLogResult
+ *     |   ScreenshotCapturer -> ScreenshotResult
+ *     |                  |
+ *     v                  v
+ *   PageVisitResult  (aggregates all collector results for one URL)
+ *     |
+ *     v
+ *   CrawlResult (all pages + crawl metadata + errors)
+ *     |
+ *     v
+ *   Assembler  --->  AssembledArtifacts
+ *     |               (deduplicated, correlated, structured)
+ *     v
+ *   ReportGenerator
+ *     |-- HTML report  (ReportData -> report.html)
+ *     |-- JSON output  (AssembledArtifacts -> *.json files)
+ *     |-- OpenAPI spec (ApiEndpointGroup[] -> openapi.json)
+ *     |-- Bundle       (AssembledArtifacts + screenshots -> .archaeologist ZIP)
+ *     v
+ *   DiffModule
+ *     |-- loads two BundleManifest + their contents
+ *     |-- produces DiffResult
+ *     |-- renders diff report (HTML, JSON, JUnit, Markdown)
+ */
+
+interface HeadingEntry {
+    level: 1 | 2 | 3 | 4 | 5 | 6;
+    text: string;
+}
+interface MetaTag {
+    name?: string;
+    property?: string;
+    content: string;
+}
+interface LandmarkInfo {
+    role: string;
+    tagName: string;
+    label?: string;
+}
+interface LinkInfo {
+    href: string;
+    text: string;
+    /** Whether the link is internal (same-origin) or external. */
+    isExternal: boolean;
+    /** Relationship attribute value if present (e.g. "nofollow"). */
+    rel?: string;
+}
+interface InteractiveElement {
+    tagName: string;
+    type?: string;
+    text: string;
+    role?: string;
+    ariaLabel?: string;
+    /** CSS selector that uniquely identifies this element on the page. */
+    selector: string;
+}
+interface PageTiming {
+    /** Total time from navigation start to load event (ms). */
+    loadTime: number;
+    /** DOM content loaded time (ms). */
+    domContentLoaded: number;
+    /** First contentful paint (ms), if available. */
+    firstContentfulPaint?: number;
+}
+/**
+ * Output of the PageScanner collector for a single URL.
+ * The Orchestrator receives this and stores it in PageVisitResult.
+ */
+interface PageScanResult {
+    url: string;
+    /** Canonical URL if different from requested URL (e.g. after redirect). */
+    canonicalUrl?: string;
+    /** HTTP status code of the final response. */
+    statusCode: number;
+    /** Page <title> text. */
+    title: string;
+    /** Meta description and other meta tags. */
+    metaTags: MetaTag[];
+    /** Heading hierarchy. */
+    headings: HeadingEntry[];
+    /** Semantic landmark elements found on the page. */
+    landmarks: LandmarkInfo[];
+    /** All links discovered on the page (both <a href> and SPA navigation targets). */
+    links: LinkInfo[];
+    /** Buttons, dropdowns, and other interactive elements (not links). */
+    interactiveElements: InteractiveElement[];
+    /** Navigation Timing API data. */
+    timing: PageTiming;
+    /** SHA-256 hash of the page's main text content (for change detection). */
+    contentHash: string;
+    /** Whether hash-based routing was detected on this page. */
+    hashRoutingDetected: boolean;
+}
+interface FormFieldOption {
+    value: string;
+    label: string;
+    selected: boolean;
+}
+interface FormField {
+    /** Input name attribute. */
+    name: string;
+    /** Input type (text, email, password, select, radio, checkbox, file, hidden, etc.). */
+    type: string;
+    /** Whether the field is required (HTML5 required attribute or aria-required). */
+    required: boolean;
+    /** Validation pattern attribute value. */
+    pattern?: string;
+    /** Placeholder text. */
+    placeholder?: string;
+    /** Associated label text (from <label>, aria-label, or aria-labelledby). */
+    label?: string;
+    /** For select, radio, and checkbox: the available options. */
+    options?: FormFieldOption[];
+    /** Min/max/step for numeric inputs. */
+    min?: string;
+    max?: string;
+    step?: string;
+    /** Maxlength constraint. */
+    maxLength?: number;
+    /** Whether the field accepts multiple values (e.g. multi-select, multiple file). */
+    multiple?: boolean;
+    /** Accept attribute for file inputs. */
+    accept?: string;
+    /** Default/current value (redacted for password fields). */
+    defaultValue?: string;
+}
+interface ValidationMessage {
+    fieldName: string;
+    message: string;
+    /** Whether this is a browser-native validation or custom JS validation. */
+    type: 'native' | 'custom';
+}
+/**
+ * Output of the FormProber collector for a single URL.
+ * A page may contain zero or more forms.
+ */
+interface FormProbeResult {
+    /** The page URL where these forms were found. */
+    pageUrl: string;
+    forms: FormInfo[];
+}
+interface FormInfo {
+    /** Form action URL (resolved to absolute). Empty string if no action attribute. */
+    action: string;
+    /** HTTP method (GET, POST, etc.). Default: GET. */
+    method: string;
+    /** Form id attribute, if present. */
+    id?: string;
+    /** Form name attribute, if present. */
+    name?: string;
+    /** Whether this is an explicit <form> or an implicit form (input group without wrapper). */
+    isImplicit: boolean;
+    /** All fields in the form. */
+    fields: FormField[];
+    /** Submit button text. */
+    submitButtonText?: string;
+    /** Encoding type (application/x-www-form-urlencoded, multipart/form-data, text/plain). */
+    enctype?: string;
+    /** Validation messages captured by attempting an empty submission. */
+    validationMessages: ValidationMessage[];
+    /** ARIA attributes on the form element. */
+    ariaLabel?: string;
+    /** Whether the form was hidden and required clicking (tab/accordion) to reveal. */
+    wasHidden: boolean;
+}
+type RequestClassification = 'api' | 'static' | 'analytics' | 'third-party' | 'websocket' | 'other';
+interface CapturedRequest {
+    /** Unique request ID within this crawl. */
+    requestId: string;
+    /** Request URL. */
+    url: string;
+    /** HTTP method. */
+    method: string;
+    /** Request headers (sensitive headers scrubbed unless --include-cookies). */
+    headers: Record<string, string>;
+    /** Request body (truncated to 100KB, null for GET). */
+    body?: string;
+    /** Content type of the request body. */
+    contentType?: string;
+    /** Resource type as classified by the browser. */
+    resourceType: string;
+    /** Our classification of the request. */
+    classification: RequestClassification;
+    /** Whether this request was initiated by user interaction or automatic. */
+    initiator: 'navigation' | 'script' | 'fetch' | 'xhr' | 'other';
+}
+interface CapturedResponse {
+    /** Corresponding request ID. */
+    requestId: string;
+    /** HTTP status code. */
+    statusCode: number;
+    /** Response headers (sensitive headers scrubbed unless --include-cookies). */
+    headers: Record<string, string>;
+    /** Response body (truncated to 100KB). Null for redirects and non-text responses. */
+    body?: string;
+    /** Content type of the response. */
+    contentType?: string;
+    /** Response body size in bytes (before truncation). */
+    bodySize: number;
+    /** Response timing in milliseconds. */
+    timing: number;
+}
+interface FailedRequest {
+    requestId: string;
+    url: string;
+    method: string;
+    /** Error message (e.g. "net::ERR_CONNECTION_REFUSED"). */
+    errorText: string;
+    classification: RequestClassification;
+}
+interface GraphQLOperation {
+    /** The page URL where this operation was captured. */
+    pageUrl: string;
+    /** Endpoint URL (typically /graphql). */
+    endpointUrl: string;
+    /** Operation name from the query. */
+    operationName: string;
+    /** Operation type. */
+    operationType: 'query' | 'mutation' | 'subscription';
+    /** GraphQL variables sent with the operation. */
+    variables?: Record<string, unknown>;
+    /** Full query string. */
+    query: string;
+    /** Response data (truncated). */
+    responseData?: unknown;
+}
+interface WebSocketConnection {
+    /** WebSocket URL. */
+    url: string;
+    /** The page URL that opened this WebSocket. */
+    pageUrl: string;
+    /** Whether the connection was successfully established. */
+    connected: boolean;
+    /** Number of messages observed (sent + received). */
+    messageCount: number;
+    /** Sample messages (first 5 sent, first 5 received). */
+    sampleMessages: Array<{
+        direction: 'sent' | 'received';
+        data: string;
+        timestamp: string;
+    }>;
+}
+/**
+ * Output of the NetworkLogger collector for a single URL.
+ */
+interface NetworkLogResult {
+    /** The page URL this network activity was captured on. */
+    pageUrl: string;
+    /** All captured request/response pairs. */
+    requests: CapturedRequest[];
+    responses: CapturedResponse[];
+    /** Requests that failed (network error, CORS, timeout). */
+    failedRequests: FailedRequest[];
+    /** GraphQL operations detected. */
+    graphqlOperations: GraphQLOperation[];
+    /** WebSocket connections detected. */
+    webSocketConnections: WebSocketConnection[];
+    /** Cookie mutations observed (cookies set or deleted during page visit). */
+    cookieMutations: Array<{
+        name: string;
+        action: 'set' | 'deleted';
+        domain: string;
+        path: string;
+    }>;
+}
+interface ScreenshotResult {
+    /** The page URL this screenshot was taken on. */
+    pageUrl: string;
+    /** Filesystem path where the full-page screenshot was saved. */
+    fullPagePath: string;
+    /** Filesystem path where the viewport-only screenshot was saved. */
+    viewportPath: string;
+    /** Viewport dimensions used for capture. */
+    viewport: Viewport;
+    /** SHA-256 hash of the full-page screenshot file. */
+    fullPageHash: string;
+    /** SHA-256 hash of the viewport screenshot file. */
+    viewportHash: string;
+    /** Full-page screenshot dimensions. */
+    dimensions: {
+        width: number;
+        height: number;
+    };
+    /** File size in bytes. */
+    fileSizeBytes: number;
+    /** Whether a dialog or modal was detected and captured. */
+    modalDetected: boolean;
+}
+type PageVisitStatus = 'ok' | 'http_error' | 'timeout' | 'network_error' | 'no_response' | 'security_blocked' | 'skipped';
+/**
+ * The Orchestrator produces one PageVisitResult per visited URL.
+ * It aggregates results from all collectors plus navigation metadata.
+ * Passed to the Assembler in bulk via CrawlResult.
+ */
+interface PageVisitResult {
+    url: string;
+    /** Final URL after redirects. */
+    finalUrl: string;
+    status: PageVisitStatus;
+    /** HTTP status code (undefined if navigation failed before response). */
+    httpStatus?: number;
+    /** Crawl depth from the entry URL. */
+    depth: number;
+    /** Which page linked to this one (undefined for the entry URL). */
+    referrer?: string;
+    /** How this URL was discovered. */
+    discoveryMethod: 'link' | 'pushState' | 'replaceState' | 'navigation-api' | 'click' | 'sitemap.xml' | 'entry';
+    /** Timestamp when the page visit started. */
+    visitedAt: string;
+    /** Duration of the entire page visit (navigation + all collectors) in ms. */
+    durationMs: number;
+    pageScan?: PageScanResult;
+    formProbe?: FormProbeResult;
+    networkLog?: NetworkLogResult;
+    screenshot?: ScreenshotResult;
+    /** Per-collector errors (collector ran but threw). */
+    collectorErrors: Array<{
+        collector: CollectorName;
+        message: string;
+    }>;
+    /** Navigation edges discovered from this page. */
+    navigationEdges: NavigationEdge[];
+}
+type NavigationTrigger = 'link' | 'form-submit' | 'redirect' | 'pushState' | 'replaceState' | 'navigation-api' | 'click' | 'meta-refresh' | 'js-redirect';
+interface NavigationEdge {
+    from: string;
+    to: string;
+    trigger: NavigationTrigger;
+    /** Text of the element that triggered navigation (link text, button text). */
+    triggerText?: string;
+    /** CSS selector of the element that triggered navigation. */
+    triggerSelector?: string;
+}
+/**
+ * CrawlResult is the complete output of the Orchestrator.
+ * Passed to the Assembler for deduplication, correlation, and structuring.
+ */
+interface CrawlResult {
+    /** Crawl configuration that was used. */
+    config: {
+        targetUrl: string;
+        depth: number;
+        maxPages: number;
+        concurrency: number;
+        viewport: Viewport;
+        followExternal: boolean;
+        deepClick: boolean;
+    };
+    /** When the crawl started. */
+    startedAt: string;
+    /** When the crawl finished. */
+    finishedAt: string;
+    /** Total crawl duration in milliseconds. */
+    durationMs: number;
+    /** All page visit results, one per visited URL. */
+    pages: PageVisitResult[];
+    /** URLs that were discovered but not visited (depth/max-pages limit reached). */
+    unvisitedUrls: string[];
+    /** Errors encountered during the crawl. */
+    errors: CrawlErrorEntry[];
+    /** Whether the crawl completed fully or was interrupted. */
+    completionStatus: 'complete' | 'max_pages_reached' | 'max_time_reached' | 'interrupted' | 'error';
+}
+interface RouteNode {
+    /** URL path segment (e.g. "users" or ":id"). */
+    segment: string;
+    /** Full URL for this route. */
+    url: string;
+    /** Page title. */
+    title: string;
+    /** HTTP status code. */
+    statusCode: number;
+    /** Content hash for change detection. */
+    contentHash: string;
+    /** Headings on this page. */
+    headings: HeadingEntry[];
+    /** Landmarks on this page. */
+    landmarks: LandmarkInfo[];
+    /** Depth from root. */
+    depth: number;
+    /** Child route nodes. */
+    children: RouteNode[];
+    /** Number of forms on this page. */
+    formCount: number;
+    /** Number of API calls made from this page. */
+    apiCallCount: number;
+    /** Whether this page has a screenshot. */
+    hasScreenshot: boolean;
+}
+interface ApiEndpointGroup {
+    /** URL pattern with parameter placeholders (e.g. "/api/users/:id"). */
+    pattern: string;
+    /** HTTP method. */
+    method: string;
+    /** Classification. */
+    classification: RequestClassification;
+    /** All observed concrete URLs that matched this pattern. */
+    observedUrls: string[];
+    /** Number of times this endpoint was called across the crawl. */
+    callCount: number;
+    /** Pages that called this endpoint. */
+    callingPages: string[];
+    /** Example request (first observed). */
+    exampleRequest: {
+        url: string;
+        headers: Record<string, string>;
+        body?: string;
+        contentType?: string;
+    };
+    /** Example response (first observed). */
+    exampleResponse: {
+        statusCode: number;
+        headers: Record<string, string>;
+        body?: string;
+        contentType?: string;
+        bodySize: number;
+    };
+    /** All unique status codes observed. */
+    observedStatusCodes: number[];
+    /** Response content types observed. */
+    observedContentTypes: string[];
+    /** Whether this endpoint appears to be GraphQL. */
+    isGraphQL: boolean;
+    /** GraphQL operation names if applicable. */
+    graphqlOperations?: string[];
+}
+interface FlowGraph$1 {
+    /** All unique nodes (URLs). */
+    nodes: Array<{
+        url: string;
+        title: string;
+        /** Route group this node belongs to (for clustering). */
+        cluster: string;
+    }>;
+    /** All navigation edges. */
+    edges: NavigationEdge[];
+    /** Entry point URL. */
+    entryPoint: string;
+    /** Dead-end pages (no outgoing links). */
+    deadEnds: string[];
+    /** Pages that form cycles. */
+    cycles: string[][];
+}
+interface FlowDiagramSet {
+    /** Top-level overview diagram (max 50 nodes). */
+    overview: MermaidDiagram;
+    /** Per-section sub-diagrams. */
+    sections: Array<{
+        /** Route prefix for this section (e.g. "/users"). */
+        prefix: string;
+        diagram: MermaidDiagram;
+    }>;
+}
+interface MermaidDiagram {
+    /** Raw Mermaid definition text (for .mmd file output). */
+    definition: string;
+    /** Pre-rendered SVG string (for HTML report embedding). Undefined if rendering failed. */
+    svg?: string;
+}
+interface ScreenshotManifestEntry {
+    /** Page URL. */
+    url: string;
+    /** Page title. */
+    title: string;
+    /** Relative path to the full-page screenshot (from output dir). */
+    fullPagePath: string;
+    /** Relative path to the viewport screenshot. */
+    viewportPath: string;
+    /** Viewport dimensions. */
+    viewport: Viewport;
+    /** Full-page image dimensions. */
+    dimensions: {
+        width: number;
+        height: number;
+    };
+    /** SHA-256 hash of the full-page screenshot. */
+    fullPageHash: string;
+    /** Base64-encoded JPEG thumbnail (320px wide, quality 60). */
+    thumbnailBase64: string;
+}
+/**
+ * AssembledArtifacts is the structured, deduplicated output of the Assembler.
+ * This is the primary input to the ReportGenerator.
+ */
+interface AssembledArtifacts {
+    /** Crawl metadata. */
+    meta: CrawlMeta;
+    /** Hierarchical route tree. */
+    routeTree: RouteNode;
+    /** Flat list of all discovered routes (for search/filter). */
+    routes: RouteInfo[];
+    /** All forms discovered, deduplicated by (pageUrl + action + method). */
+    forms: FormInfo[];
+    /** API endpoints grouped by URL pattern. */
+    apiEndpoints: ApiEndpointGroup[];
+    /** GraphQL operations discovered. */
+    graphqlOperations: GraphQLOperation[];
+    /** WebSocket connections discovered. */
+    webSocketConnections: WebSocketConnection[];
+    /** Navigation flow graph. */
+    flowGraph: FlowGraph$1;
+    /** Mermaid diagrams (overview + sections). */
+    flowDiagrams: FlowDiagramSet;
+    /** Screenshot manifest with thumbnail data. */
+    screenshots: ScreenshotManifestEntry[];
+    /** Crawl errors summary. */
+    errors: CrawlErrorEntry[];
+}
+interface RouteInfo {
+    url: string;
+    title: string;
+    statusCode: number;
+    contentHash: string;
+    depth: number;
+    formCount: number;
+    apiCallCount: number;
+    hasScreenshot: boolean;
+    discoveryMethod: PageVisitResult['discoveryMethod'];
+}
+interface CrawlMeta {
+    /** Tool version (from package.json). */
+    toolVersion: string;
+    /** Target URL that was crawled. */
+    targetUrl: string;
+    /** When the crawl started (ISO 8601). */
+    crawlDate: string;
+    /** Total crawl duration in milliseconds. */
+    duration: number;
+    /** Total pages visited. */
+    pagesVisited: number;
+    /** Total pages discovered (visited + unvisited). */
+    pagesDiscovered: number;
+    /** Total forms found. */
+    formsFound: number;
+    /** Total unique API endpoint patterns found. */
+    apiEndpointsFound: number;
+    /** Total screenshots taken. */
+    screenshotsTaken: number;
+    /** Total errors encountered. */
+    errorCount: number;
+    /** How the crawl ended. */
+    completionStatus: CrawlResult['completionStatus'];
+    /** Viewport used for primary screenshots. */
+    viewport: Viewport;
+}
+interface BundleManifest {
+    /** Schema version for forward compatibility. */
+    version: 1;
+    /** Tool identifier. */
+    tool: 'playwright-archaeologist';
+    /** Tool version that created this bundle. */
+    toolVersion: string;
+    /** When the bundle was created (ISO 8601). */
+    createdAt: string;
+    /** Crawl configuration (for diff compatibility checking). */
+    config: {
+        targetUrl: string;
+        depth: number;
+        viewport: Viewport;
+        concurrency: number;
+        maxPages: number;
+        followExternal: boolean;
+        deepClick: boolean;
+    };
+    /** Crawl statistics. */
+    stats: {
+        pagesVisited: number;
+        formsFound: number;
+        apiEndpoints: number;
+        screenshotCount: number;
+        duration: number;
+    };
+    /** All files in the bundle with checksums. */
+    files: BundleFileEntry[];
+}
+interface BundleFileEntry {
+    /** Relative path within the ZIP archive. */
+    path: string;
+    /** SHA-256 hex digest. */
+    sha256: string;
+    /** Uncompressed size in bytes. */
+    size: number;
+    /** File category. */
+    type: 'screenshot' | 'json' | 'api-snapshot' | 'manifest';
+}
+interface DiffResult {
+    /** Metadata about the comparison. */
+    meta: {
+        oldBundle: {
+            path: string;
+            createdAt: string;
+            targetUrl: string;
+            toolVersion: string;
+        };
+        newBundle: {
+            path: string;
+            createdAt: string;
+            targetUrl: string;
+            toolVersion: string;
+        };
+        comparedAt: string;
+    };
+    /** Overall change status. */
+    hasChanges: boolean;
+    /** Route/sitemap diff. */
+    sitemap: SitemapDiff;
+    /** Form diff. */
+    forms: FormDiff;
+    /** API endpoint diff. */
+    api: ApiDiff;
+    /** Screenshot diff. */
+    screenshots: ScreenshotDiff;
+    /** Summary counts for terminal and CI output. */
+    summary: DiffSummary;
+}
+interface DiffSummary {
+    routes: {
+        added: number;
+        removed: number;
+        changed: number;
+        unchanged: number;
+    };
+    forms: {
+        added: number;
+        removed: number;
+        changed: number;
+        unchanged: number;
+    };
+    api: {
+        added: number;
+        removed: number;
+        changed: number;
+        unchanged: number;
+    };
+    screenshots: {
+        changed: number;
+        unchanged: number;
+        added: number;
+        removed: number;
+    };
+}
+interface SitemapDiff {
+    added: RouteInfo[];
+    removed: RouteInfo[];
+    changed: SitemapRouteChange[];
+    unchangedCount: number;
+}
+interface SitemapRouteChange {
+    url: string;
+    changes: {
+        title?: {
+            old: string;
+            new: string;
+        };
+        statusCode?: {
+            old: number;
+            new: number;
+        };
+        contentHash?: {
+            old: string;
+            new: string;
+        };
+    };
+}
+interface FormDiff {
+    added: FormInfo[];
+    removed: FormInfo[];
+    changed: FormChange[];
+    unchangedCount: number;
+}
+interface FormChange {
+    /** Identity key (action:method or id). */
+    formId: string;
+    /** Page URL where the form lives. */
+    pageUrl: string;
+    changes: {
+        fieldsAdded?: FormField[];
+        fieldsRemoved?: FormField[];
+        fieldsChanged?: FieldChange[];
+        actionChanged?: {
+            old: string;
+            new: string;
+        };
+        methodChanged?: {
+            old: string;
+            new: string;
+        };
+    };
+}
+interface FieldChange {
+    name: string;
+    changes: {
+        type?: {
+            old: string;
+            new: string;
+        };
+        required?: {
+            old: boolean;
+            new: boolean;
+        };
+        options?: {
+            added: string[];
+            removed: string[];
+        };
+        validationPattern?: {
+            old: string;
+            new: string;
+        };
+        placeholder?: {
+            old: string;
+            new: string;
+        };
+    };
+}
+interface ApiDiff {
+    added: ApiEndpointGroup[];
+    removed: ApiEndpointGroup[];
+    changed: ApiEndpointChange[];
+    unchangedCount: number;
+}
+interface ApiEndpointChange {
+    /** Endpoint pattern (e.g. "GET /api/users/:id"). */
+    endpointId: string;
+    changes: {
+        /** Status codes that appeared/disappeared. */
+        statusCodesAdded?: number[];
+        statusCodesRemoved?: number[];
+        /** Response content type changed. */
+        contentTypeChanged?: {
+            old: string;
+            new: string;
+        };
+        /** Response schema fields added/removed (jsondiffpatch delta). */
+        schemaDelta?: unknown;
+        /** Response body size changed significantly. */
+        bodySizeChange?: {
+            old: number;
+            new: number;
+            percentChange: number;
+        };
+    };
+}
+interface ScreenshotDiff {
+    added: Array<{
+        url: string;
+        screenshotPath: string;
+    }>;
+    removed: Array<{
+        url: string;
+    }>;
+    changed: ScreenshotChange[];
+    unchangedCount: number;
+}
+interface ScreenshotChange {
+    url: string;
+    /** Percentage of pixels that differ (0-100). */
+    diffPercentage: number;
+    /** Number of pixels that differ. */
+    diffPixelCount: number;
+    /** Total pixels in the image. */
+    totalPixels: number;
+    /** Path to the diff image (red overlay on semi-transparent original). */
+    diffImagePath: string;
+    /** Path to the old screenshot. */
+    oldScreenshotPath: string;
+    /** Path to the new screenshot. */
+    newScreenshotPath: string;
+    /** Whether the image dimensions changed. */
+    dimensionChange?: {
+        old: {
+            width: number;
+            height: number;
+        };
+        new: {
+            width: number;
+            height: number;
+        };
+    };
+}
+interface CheckpointState {
+    /** Schema version. */
+    version: 1;
+    /** When the crawl started. */
+    startedAt: string;
+    /** When this checkpoint was written. */
+    checkpointedAt: string;
+    /** URLs still in the frontier queue (to visit). */
+    frontier: Array<{
+        url: string;
+        depth: number;
+        referrer?: string;
+    }>;
+    /** URLs already visited (normalized). */
+    visited: string[];
+    /** URLs that were skipped (security block, scope violation, etc.). */
+    skipped: string[];
+    /** Partial artifacts path (relative to output dir). */
+    artifactsDir: string;
+    /** Number of pages visited so far. */
+    pagesVisited: number;
+    /** Errors accumulated so far. */
+    errors: CrawlErrorEntry[];
+    /** Crawl config hash to verify resume compatibility. */
+    configHash: string;
+}
+/**
+ * The public programmatic API returns AssembledArtifacts plus file paths
+ * to the generated output.
+ */
+interface DigResult {
+    artifacts: AssembledArtifacts;
+    outputPaths: {
+        outputDir: string;
+        reportHtml?: string;
+        sitemapJson?: string;
+        formsJson?: string;
+        apiMapJson?: string;
+        openapiJson?: string;
+        flowGraphMmd?: string;
+        harFile?: string;
+        screenshotsDir?: string;
+        bundle?: string;
+    };
+    errors: CrawlErrorEntry[];
+    completionStatus: CrawlResult['completionStatus'];
+}
+
+/**
+ * Crawl orchestrator — the heart of M1.
+ *
+ * Coordinates browser launch, secure context creation, BFS frontier loop,
+ * per-page navigation and scanning, SSRF protection, graceful shutdown,
+ * and output generation.
+ *
+ * Error strategy:
+ *   - Per-page errors are logged and the page is skipped (crawl continues).
+ *   - SIGINT triggers graceful shutdown: stop loop, write partial results, close browser.
+ *   - Fatal errors (browser crash, output dir unwritable) abort the crawl.
+ */
+
+/**
+ * Run a full crawl of the target URL.
+ *
+ * @param config - Fully validated and resolved crawl configuration.
+ * @returns The assembled artifacts, output paths, and completion status.
+ */
+declare function dig(config: ResolvedConfig): Promise<DigResult>;
+
+/**
+ * Leveled logger for playwright-archaeologist.
+ *
+ * Provides debug, info, warn, error, and success log methods
+ * with timestamps and ANSI color output. Debug messages are
+ * suppressed unless verbose mode is enabled.
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+declare class Logger {
+    private level;
+    constructor(level?: LogLevel);
+    /** Update the minimum log level at runtime. */
+    setLevel(level: LogLevel): void;
+    /** Get the current minimum log level. */
+    getLevel(): LogLevel;
+    /** Check whether a given level would be emitted. */
+    isLevelEnabled(level: LogLevel): boolean;
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+    /** Success message — always shown at info level or below. */
+    success(message: string, ...args: unknown[]): void;
+}
+/**
+ * Shared singleton logger instance.
+ * The CLI sets its level to 'debug' when --verbose is passed.
+ */
+declare const logger: Logger;
+
+/**
+ * PageScanner collector — extracts structural information from a page.
+ *
+ * Receives a Playwright Page that has already navigated to the target URL.
+ * Does NOT navigate, click, or scroll — it only reads the current DOM state.
+ *
+ * Extracts:
+ *   - URL, canonical URL, title
+ *   - Meta tags (name, property, content)
+ *   - Heading hierarchy (h1-h6)
+ *   - Landmark elements (nav, main, aside, footer, header, [role])
+ *   - Links (<a href>) with internal/external classification
+ *   - Interactive elements (buttons, inputs, selects) with CSS selectors
+ *   - Navigation Timing data
+ *   - Content hash for change detection
+ *   - Hash-routing detection
+ */
+
+/**
+ * Scan a page and extract its structural information.
+ *
+ * @param page       Playwright Page already navigated to the target URL.
+ * @param baseUrl    The crawl's starting URL, used for same-origin checks.
+ * @param response   The navigation response (for HTTP status code).
+ *                   Pass null/undefined if not available; statusCode defaults to 200.
+ */
+declare function scanPage(page: Page, baseUrl: string, response?: Response | null): Promise<PageScanResult>;
+
+/**
+ * ScreenshotCapturer collector — captures full-page and viewport screenshots.
+ *
+ * Receives a Playwright Page that has already navigated to the target URL.
+ * Takes two screenshots per page:
+ *   1. Full-page screenshot (captures entire scrollable area)
+ *   2. Viewport-only screenshot (captures visible area only)
+ *
+ * Before capturing, performs limited scrolling (up to 3 viewport increments)
+ * to trigger lazy-loaded content, then scrolls back to the top.
+ *
+ * Detects visible modals/dialogs on the page for metadata.
+ * Gracefully degrades: returns an empty result if screenshots fail.
+ */
+
+/**
+ * Capture full-page and viewport screenshots of a page.
+ *
+ * @param page      Playwright Page already navigated to the target URL.
+ * @param baseUrl   The crawl's starting URL (unused here, kept for collector interface consistency).
+ * @param outputDir Directory where screenshot files will be saved.
+ * @param viewport  Viewport dimensions used for capture. Defaults to 1280x720.
+ * @returns         ScreenshotResult with paths, hashes, and metadata.
+ */
+declare function captureScreenshots(page: Page, baseUrl: string, outputDir: string, viewport?: Viewport): Promise<ScreenshotResult>;
+
+/**
+ * FormProber collector — extracts form metadata from a page.
+ *
+ * Receives a Playwright Page that has already navigated to the target URL.
+ * Does NOT submit forms or trigger validation — it only reads the current DOM state.
+ *
+ * Extracts:
+ *   - Explicit <form> elements with all fields, options, and attributes
+ *   - Implicit forms (orphaned input groups outside any <form> wrapper)
+ *   - Submit button text
+ *   - Field labels, validation attributes, and default values
+ *   - Password field values are redacted
+ */
+
+/**
+ * Probe all forms on the page and extract their metadata.
+ *
+ * @param page     Playwright Page already navigated to the target URL.
+ * @param pageUrl  The URL of the page being probed.
+ */
+declare function probeForms(page: Page, pageUrl: string): Promise<FormProbeResult>;
+
+/**
+ * NetworkLogger collector — captures all network activity on a page.
+ *
+ * Attaches to Playwright Page events to record:
+ *   - HTTP requests and responses (with header scrubbing)
+ *   - Failed requests (network errors, CORS, timeouts)
+ *   - GraphQL operations (detected from POST to /graphql endpoints)
+ *   - WebSocket connections and sample messages
+ *
+ * Usage:
+ *   const logger = createNetworkLogger(page, pageUrl);
+ *   logger.start();
+ *   // ... navigate, interact ...
+ *   const result = logger.stop();
+ */
+
+interface NetworkLoggerOptions {
+    includeCookies?: boolean;
+}
+interface NetworkLogger {
+    start(): void;
+    stop(): NetworkLogResult;
+}
+/**
+ * Create a NetworkLogger that captures all network activity on a page.
+ *
+ * @param page     Playwright Page to attach listeners to.
+ * @param pageUrl  The page URL (used for origin comparison and GraphQL context).
+ * @param options  Optional configuration (e.g. whether to include cookies).
+ */
+declare function createNetworkLogger(page: Page, pageUrl: string, options?: NetworkLoggerOptions): NetworkLogger;
+
+/**
+ * Auth Handler
+ *
+ * Manages authentication flows for the crawler. Supports three methods
+ * in priority order: storage state, cookie injection, and auth scripts.
+ *
+ * Storage state is the most direct method (restores full browser state).
+ * Cookie injection loads cookies from a JSON file.
+ * Auth scripts execute user-provided Playwright automation to log in.
+ */
+
+interface AuthOptions {
+    /** Path to auth script (JS/TS file that exports default async function(page)) */
+    authScript?: string;
+    /** Path to cookies JSON file */
+    cookiesFile?: string;
+    /** Path to save/load storage state */
+    storageStatePath?: string;
+}
+interface AuthResult {
+    success: boolean;
+    method: 'script' | 'cookies' | 'storageState';
+    /** Error message if auth failed */
+    error?: string;
+    /** URL after auth completed */
+    finalUrl?: string;
+    /** Cookies set during auth */
+    cookieCount: number;
+}
+/**
+ * Detect whether the current page state indicates an auth failure.
+ *
+ * Checks:
+ * - URL matches common login page patterns
+ * - Page title or response status hints at auth problems
+ */
+declare function detectAuthFailure(page: Page): Promise<{
+    failed: boolean;
+    reason?: string;
+}>;
+/**
+ * Execute an authentication flow.
+ *
+ * Priority order: storageState > cookies > authScript.
+ * Uses the most direct method available. If storage state path is provided
+ * but doesn't exist yet, falls through to script execution and saves state after.
+ *
+ * @param page - Playwright Page instance
+ * @param context - Playwright BrowserContext instance
+ * @param options - Auth configuration
+ * @returns Result describing the auth outcome
+ */
+declare function executeAuth(page: Page, context: BrowserContext, options: AuthOptions): Promise<AuthResult>;
+/**
+ * Re-run the authentication flow. Used when a session expires during a crawl.
+ *
+ * This is a thin wrapper around executeAuth that clears existing cookies
+ * before re-running to avoid stale state.
+ */
+declare function refreshAuth(page: Page, context: BrowserContext, options: AuthOptions): Promise<AuthResult>;
+
+/**
+ * URL Frontier -- BFS queue with deduplication.
+ *
+ * Maintains a queue of URLs to visit with:
+ * - BFS ordering (FIFO)
+ * - Deduplication using normalized URLs
+ * - Depth tracking per URL
+ *
+ * Uses a dequeue pointer instead of Array.shift() to avoid O(n)
+ * cost on large queues. Compacts the internal array when more than
+ * half of its entries have been consumed.
+ */
+interface FrontierEntry {
+    url: string;
+    depth: number;
+    referrer?: string;
+}
+declare class Frontier {
+    private queue;
+    private head;
+    private seen;
+    private maxDepth;
+    constructor(options?: {
+        maxDepth?: number;
+    });
+    /**
+     * Add a URL to the queue. Returns false if already seen or exceeds max depth.
+     */
+    enqueue(entry: FrontierEntry): boolean;
+    /**
+     * Remove and return the next URL from the queue (FIFO).
+     * Returns undefined if queue is empty.
+     */
+    dequeue(): FrontierEntry | undefined;
+    /**
+     * Check if a URL has been seen (ever enqueued, whether still queued or already dequeued).
+     */
+    hasSeen(url: string): boolean;
+    /**
+     * Get the number of URLs remaining in the queue.
+     */
+    get size(): number;
+    /**
+     * Get the total number of URLs seen (visited + queued).
+     */
+    get totalSeen(): number;
+    /**
+     * Check if the queue is empty.
+     */
+    get isEmpty(): boolean;
+}
+
+/**
+ * Browser context pool for concurrent crawling.
+ *
+ * Manages a pool of Playwright BrowserContexts with:
+ * - Concurrency limiting via async semaphore
+ * - Automatic context recycling after N page visits
+ * - Shared context options and storage state
+ *
+ * Callers acquire a context before visiting a page and release it
+ * when done. If the pool is at capacity, acquire() blocks until a
+ * context is released.
+ */
+
+interface ContextPoolOptions {
+    /** Max concurrent contexts (default 3) */
+    concurrency: number;
+    /** Pages per context before recycling (default 50) */
+    recycleAfter: number;
+    /** Context options to apply to all contexts */
+    contextOptions: Record<string, unknown>;
+    /** Storage state to share across contexts */
+    storageState?: string;
+}
+declare class ContextPool {
+    private readonly browser;
+    private readonly concurrency;
+    private readonly recycleAfter;
+    private readonly contextOptions;
+    private readonly storageState?;
+    /** Contexts currently in use by callers */
+    private acquired;
+    /** Contexts sitting idle, ready to be acquired */
+    private idle;
+    /** Waiters blocked on acquire() when pool is full */
+    private waiters;
+    /** Whether closeAll() has been called */
+    private closed;
+    constructor(browser: Browser, options: ContextPoolOptions);
+    /**
+     * Acquire a browser context from the pool.
+     * Blocks if the pool is at full capacity until a context is released.
+     */
+    acquire(): Promise<BrowserContext>;
+    /**
+     * Release a context back to the pool. Increments the page count
+     * and recycles the context if it has exceeded recycleAfter.
+     */
+    release(context: BrowserContext): Promise<void>;
+    /**
+     * Close all contexts (both idle and acquired) and reject future operations.
+     */
+    closeAll(): Promise<void>;
+    /** Current number of active (acquired) contexts */
+    get activeCount(): number;
+    /** Current number of available (idle) contexts */
+    get availableCount(): number;
+    private createEntry;
+    private drainWaiters;
+}
+
+/**
+ * Checkpoint module -- pause/resume support for large crawls.
+ *
+ * Persists crawl state to disk so that an interrupted crawl can be
+ * resumed from the last checkpoint rather than restarting from scratch.
+ *
+ * Uses atomic writes (write to .tmp, then rename) to prevent corruption
+ * if the process is killed mid-write.
+ */
+
+/**
+ * Persist checkpoint state to disk using an atomic write strategy.
+ *
+ * Writes to a temporary file first, then renames it to the final path.
+ * This prevents a half-written file if the process is killed mid-write.
+ *
+ * Updates `state.checkpointedAt` to the current timestamp before writing.
+ */
+declare function writeCheckpoint(state: CheckpointState, outputDir: string): Promise<void>;
+/**
+ * Read and validate a checkpoint file from disk.
+ *
+ * Returns `null` if no checkpoint file exists.
+ * Throws if the file exists but contains invalid data.
+ */
+declare function readCheckpoint(outputDir: string): Promise<CheckpointState | null>;
+/**
+ * Remove checkpoint files (both the main file and any leftover tmp file).
+ * Silently ignores files that do not exist.
+ */
+declare function deleteCheckpoint(outputDir: string): Promise<void>;
+/**
+ * Create an initial empty checkpoint state.
+ *
+ * Used at the start of a new crawl to initialize the checkpoint
+ * before any pages have been visited.
+ */
+declare function createCheckpointState(params: {
+    configHash: string;
+    artifactsDir: string;
+}): CheckpointState;
+/**
+ * Start a periodic auto-checkpoint timer.
+ *
+ * Calls `writeCheckpoint` every `intervalMs` milliseconds with the
+ * current state obtained from `getState()`.
+ *
+ * Returns an object with a `stop()` method that clears the interval.
+ */
+declare function setupAutoCheckpoint(getState: () => CheckpointState, outputDir: string, intervalMs?: number): {
+    stop: () => void;
+};
+
+/**
+ * API Endpoint Grouper
+ *
+ * Groups discovered API endpoints by URL pattern, replacing dynamic
+ * segments with parameter placeholders:
+ * - Numeric IDs: /users/123 -> /users/:id
+ * - UUIDs: /items/550e8400-... -> /items/:id
+ * - Slugs: /posts/hello-world -> /posts/:slug
+ */
+interface ApiEndpoint {
+    method: string;
+    url: string;
+    statusCode?: number;
+    requestBody?: unknown;
+    responseBody?: unknown;
+    headers?: Record<string, string>;
+}
+interface ApiGroup {
+    pattern: string;
+    method: string;
+    examples: ApiEndpoint[];
+    parameterTypes: Record<string, 'id' | 'uuid' | 'slug' | 'unknown'>;
+}
+/**
+ * Group a list of API endpoints by their parameterized pattern + method.
+ */
+declare function groupEndpoints(endpoints: ApiEndpoint[]): ApiGroup[];
+
+/**
+ * Flow Graph Builder
+ *
+ * Takes navigation edges from a crawl and produces:
+ * - A FlowGraph with node metadata, cycle detection, and clustering
+ * - A Mermaid diagram definition for visualization
+ *
+ * Used by the Assembler to generate flow diagrams in the HTML report.
+ */
+
+interface FlowGraphNode {
+    url: string;
+    /** Short label derived from URL path */
+    label: string;
+    /** Whether this is the entry point */
+    isEntry: boolean;
+    /** Whether this is a dead-end (no outgoing edges) */
+    isExit: boolean;
+    /** Number of incoming edges */
+    inDegree: number;
+    /** Number of outgoing edges */
+    outDegree: number;
+    /** Cluster/group based on URL path prefix */
+    cluster?: string;
+}
+interface FlowGraph {
+    nodes: FlowGraphNode[];
+    edges: NavigationEdge[];
+    /** Entry URL */
+    entryUrl: string;
+    /** Whether cycles were detected */
+    hasCycles: boolean;
+    /** URLs involved in cycles */
+    cycleNodes: string[];
+    /** Cluster groups (path prefix -> URLs) */
+    clusters: Map<string, string[]>;
+}
+/**
+ * DFS-based cycle detection.
+ * Returns an array of URLs that participate in at least one cycle.
+ */
+declare function detectCycles(edges: NavigationEdge[]): string[];
+/**
+ * Build a FlowGraph from navigation edges and an entry URL.
+ * Deduplicates edges, computes node metadata, detects cycles, and clusters URLs.
+ */
+declare function buildFlowGraph(edges: NavigationEdge[], entryUrl: string): FlowGraph;
+/**
+ * Generate a Mermaid flowchart definition from a FlowGraph.
+ *
+ * If the graph exceeds maxNodes (default 50), URLs are auto-clustered
+ * by first path segment and rendered as Mermaid subgraphs.
+ */
+declare function generateMermaidDefinition(graph: FlowGraph, options?: {
+    maxNodes?: number;
+}): string;
+
+/**
+ * HTML Report Template
+ *
+ * Generates the self-contained HTML report from assembled artifacts.
+ * All target-site data is HTML-entity-encoded via escape.ts.
+ * Includes CSP meta tag for XSS prevention.
+ */
+interface ReportPage {
+    url: string;
+    title: string;
+    status: number;
+    depth?: number;
+    contentHash?: string;
+}
+interface ReportForm {
+    url: string;
+    action: string;
+    method: string;
+    fields: Array<{
+        name: string;
+        type: string;
+        required: boolean;
+    }>;
+}
+interface ReportApiEndpoint {
+    url?: string;
+    pattern?: string;
+    method: string;
+    status?: number;
+    examples?: Array<{
+        url: string;
+        status: number;
+    }>;
+}
+interface ReportScreenshot {
+    url: string;
+    thumbnailBase64: string;
+    fullPath: string;
+}
+interface ReportInput {
+    title?: string;
+    targetUrl: string;
+    crawlDate: string;
+    duration: number;
+    pagesVisited: number;
+    errors: number;
+    pages?: ReportPage[];
+    sitemap?: ReportPage[];
+    forms: ReportForm[];
+    apiEndpoints: ReportApiEndpoint[];
+    screenshots?: ReportScreenshot[];
+    flowDiagramSvg?: string;
+}
+/**
+ * Generate the complete HTML report string.
+ * All user-provided data is escaped to prevent XSS.
+ */
+declare function generateReportHtml(input: ReportInput): string;
+
+/**
+ * HTML Escaping — XSS Prevention
+ *
+ * All data from the target site MUST be HTML-entity-encoded
+ * before embedding in reports. This is a critical security boundary.
+ */
+/**
+ * Escape a string for safe inclusion in HTML content.
+ * Encodes: & < > " '
+ * Strips null bytes.
+ * Preserves Unicode characters.
+ */
+declare function escapeHtml(input: string): string;
+/**
+ * Escape a string for safe inclusion in an HTML attribute value.
+ * More aggressive than content escaping.
+ */
+declare function escapeAttribute(input: string): string;
+/**
+ * Sanitize a string for inclusion in a JSON block embedded in HTML.
+ * Prevents </script> injection.
+ */
+declare function escapeJsonInHtml(jsonString: string): string;
+
+/**
+ * Progress tracker for crawl operations.
+ *
+ * Tracks page visits, errors, currently-active URLs, and provides
+ * ETA estimates using a rolling window of recent visit timestamps.
+ */
+interface ProgressState {
+    pagesVisited: number;
+    pagesTotal: number;
+    currentUrls: string[];
+    errorsCount: number;
+    startTime: number;
+    elapsedMs: number;
+    estimatedRemainingMs: number;
+    pagesPerSecond: number;
+}
+declare class ProgressTracker {
+    private pagesVisited;
+    private pagesTotal;
+    private errorsCount;
+    private readonly startTime;
+    private readonly currentUrls;
+    /** Rolling window of timestamps (ms) when pages were recorded as visited */
+    private readonly visitTimestamps;
+    constructor(estimatedTotal?: number);
+    /** Record a page visit. */
+    recordVisit(url: string): void;
+    /** Record an error. */
+    recordError(): void;
+    /** Mark a URL as currently being crawled. */
+    startPage(url: string): void;
+    /** Mark a URL as done crawling. */
+    endPage(url: string): void;
+    /** Update the estimated total page count. */
+    updateTotal(total: number): void;
+    /** Get the current progress state snapshot. */
+    getState(): ProgressState;
+    /**
+     * Format the current progress as a terminal-friendly string.
+     *
+     * Example: `[12/50] 2.3 p/s | ETA: 16s | Errors: 0 | Crawling: /about, /api/users`
+     */
+    format(): string;
+    /**
+     * Calculate pages per second from the rolling window of visit timestamps.
+     * Uses the time span between the oldest and newest entry in the window.
+     */
+    private calculatePagesPerSecond;
+    /**
+     * Estimate remaining milliseconds: (remaining pages) / pagesPerSecond * 1000
+     */
+    private calculateRemainingMs;
+}
+
+/**
+ * Bundle Creator
+ *
+ * Scans a crawl output directory and creates a structured bundle directory
+ * with a manifest.json at the root. The bundle layout:
+ *
+ *   manifest.json         -- BundleManifest describing all files
+ *   screenshots/          -- PNG screenshot files
+ *   data/                 -- JSON artifacts (sitemap.json, forms.json, api-map.json, etc.)
+ *   report.html           -- HTML report (if present)
+ *
+ * No external dependencies -- uses Node.js built-in crypto and fs.
+ */
+
+/**
+ * Create a bundle directory from crawl output.
+ *
+ * @param outputDir - The crawl output directory containing artifacts
+ * @param bundlePath - The destination bundle directory to create
+ * @returns The BundleManifest describing the bundle contents
+ */
+declare function createBundle(outputDir: string, bundlePath: string): Promise<BundleManifest>;
+
+/**
+ * Diff Engine
+ *
+ * Compares two bundle directories to detect regressions.
+ * Produces a DiffResult with structured change information for:
+ *   - Routes (sitemap diff)
+ *   - Forms (field-level diff)
+ *   - API endpoints (status code, content type, body size diff)
+ *   - Screenshots (hash-based change detection)
+ *
+ * No external diff dependencies -- uses JSON comparison and SHA-256 hashes.
+ */
+
+/**
+ * Compare two bundle directories and produce a DiffResult.
+ *
+ * @param oldDir - Path to the older bundle directory
+ * @param newDir - Path to the newer bundle directory
+ * @returns Structured diff result
+ */
+declare function diffBundles(oldDir: string, newDir: string): Promise<DiffResult>;
+
+/**
+ * Diff Report Generator
+ *
+ * Generates a self-contained HTML report showing all changes between
+ * two crawl bundles. Color-coded: green for added, red for removed,
+ * yellow for modified.
+ *
+ * Uses the same CSP and escaping as the main report.
+ */
+
+/**
+ * Generate a self-contained HTML diff report.
+ *
+ * @param diff - The DiffResult to render
+ * @returns Complete HTML document as a string
+ */
+declare function generateDiffReportHtml(diff: DiffResult): string;
+
+/**
+ * OpenAPI 3.0.3 Specification Generator
+ *
+ * Converts discovered ApiEndpointGroup[] into a valid OpenAPI 3.0.3 spec.
+ * Used to produce machine-readable API documentation from crawl results.
+ */
+
+interface OpenApiOptions {
+    /** Title for the API specification. */
+    title: string;
+    /** Base URL of the crawled site (used for servers[].url). */
+    targetUrl: string;
+    /** API version string. Defaults to "1.0.0". */
+    version?: string;
+    /** Optional human-readable description. */
+    description?: string;
+}
+interface OpenApiSpec {
+    openapi: '3.0.3';
+    info: {
+        title: string;
+        version: string;
+        description?: string;
+    };
+    servers: Array<{
+        url: string;
+    }>;
+    paths: Record<string, Record<string, OpenApiOperation>>;
+}
+interface OpenApiOperation {
+    summary: string;
+    operationId: string;
+    parameters?: OpenApiParameter[];
+    requestBody?: {
+        content: Record<string, {
+            schema: unknown;
+            example?: unknown;
+        }>;
+    };
+    responses: Record<string, {
+        description: string;
+        content?: Record<string, {
+            schema: unknown;
+            example?: unknown;
+        }>;
+    }>;
+    tags?: string[];
+}
+interface OpenApiParameter {
+    name: string;
+    in: 'path' | 'query';
+    required: boolean;
+    schema: {
+        type: string;
+    };
+}
+/**
+ * Generate an OpenAPI 3.0.3 specification from discovered API endpoint groups.
+ */
+declare function generateOpenApiSpec(endpoints: ApiEndpointGroup[], options: OpenApiOptions): OpenApiSpec;
+/**
+ * Write an OpenAPI spec to disk as JSON with 2-space indentation.
+ */
+declare function writeOpenApiSpec(spec: OpenApiSpec, outputPath: string): Promise<void>;
+
+export { ArchaeologistError, type AssembledArtifacts, AuthError, type AuthOptions, type AuthResult, BundleError, type BundleManifest, CollectorError, ConfigError, ContextPool, type CrawlConfig, CrawlConfigSchema, CrawlError, type CrawlResult, type DiffConfig, DiffConfigSchema, DiffError, type DiffResult, type DigResult, type FormProbeResult, Frontier, Logger, NavigationError, type NetworkLogResult, type OutputFormat, type PageScanResult, type PageVisitResult, ProgressTracker, type ResolvedConfig, type ScreenshotResult, type Viewport, ViewportSchema, buildFlowGraph, captureScreenshots, createBundle, createCheckpointState, createNetworkLogger, deleteCheckpoint, detectAuthFailure, detectCycles, diffBundles, dig, escapeAttribute, escapeHtml, escapeJsonInHtml, executeAuth, generateDiffReportHtml, generateMermaidDefinition, generateOpenApiSpec, generateReportHtml, groupEndpoints, logger, normalizeEntryUrl, parseViewport, probeForms, readCheckpoint, refreshAuth, scanPage, setupAutoCheckpoint, writeCheckpoint, writeOpenApiSpec };