@xberg-io/crawlberg 1.10.2 → 1.11.0

package/index.d.ts

@@ -1,132 +1,110 @@
-/* auto-generated by NAPI-RS */
+// This file is auto-generated by alef — DO NOT EDIT.
+// alef:hash:760ec0215fe97398ca13eabd5625cdc092e885d8a65d635b7fb1d3a6044f1005
+// To regenerate: alef generate
+// To verify freshness: alef verify
 /* eslint-disable */
-/**
- * This type implements JavaScript's async iterable protocol.
- * It can be used with `for await...of` loops.
- *
- * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols
- */
-export declare class BatchCrawlStreamIterator {
 
-}
+export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
+
+/** Crawl multiple seed URLs concurrently, each following links to configured depth. */
+export declare function batchCrawl(engine: CrawlEngineHandle, urls: Array<string>): Promise<BatchCrawlResults>;
+
+/** Scrape multiple URLs concurrently. */
+export declare function batchScrape(engine: CrawlEngineHandle, urls: Array<string>): Promise<BatchScrapeResults>;
+
+/** Crawl a website starting from `url`, following links up to the configured depth. */
+export declare function crawl(engine: CrawlEngineHandle, url: string): Promise<CrawlResult>;
 
 /**
- * Opaque handle to a configured crawl engine.
+ * Create a new crawl engine with the given configuration.
  *
- * Constructed via `create_engine` with an optional `CrawlConfig`.
- * Default implementations for all pluggable components are used internally.
+ * If `config` is `None`, uses `CrawlConfig.default()`.
+ * Returns an error if the configuration is invalid.
  */
-export declare class CrawlEngineHandle {
-  /**
-   * Stream a single-URL crawl, yielding `CrawlEvent`s as pages are processed.
-   *
-   * Returns an async stream that emits one event per crawled page, plus a
-   * terminal `Complete` event. On per-URL failure during the crawl, emits an
-   * `Error` event followed by `Complete`. The stream item type is wrapped in
-   * a `Result` to surface transport-level errors; today every emit is `Ok`.
-   *
-   * Language bindings expose this as the native streaming shape for each
-   * target. WASM does not expose native streaming wrappers.
-   */
-  crawlStream(req: JsCrawlStreamRequest): Promise<CrawlStreamIterator>
-  /**
-   * Stream a multi-URL crawl, yielding `CrawlEvent`s across all seeds.
-   *
-   * Returns an async stream that emits one event per crawled page across all
-   * seeds, plus terminal `Complete` and `Error` events as appropriate. The
-   * stream item type is wrapped in a `Result` to surface transport-level
-   * errors; today every emit is `Ok`.
-   *
-   * Language bindings expose this as the native streaming shape for each
-   * target. WASM does not expose native streaming wrappers.
-   */
-  batchCrawlStream(req: BatchCrawlStreamRequest): Promise<BatchCrawlStreamIterator>
-}
-export type JsCrawlEngineHandle = CrawlEngineHandle
+export declare function createEngine(config?: CrawlConfig | undefined | null): CrawlEngineHandle;
 
 /**
- * This type implements JavaScript's async iterable protocol.
- * It can be used with `for await...of` loops.
+ * Convert markdown links to numbered citations.
  *
- * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols
+ * `[Example](https://example.com)` becomes `Example[1]`
+ * with `[1]: https://example.com` in the reference list.
+ * Images `![alt](url)` are preserved unchanged.
  */
-export declare class CrawlStreamIterator {
+export declare function generateCitations(markdown: string): CitationResult;
 
-}
+/** Execute browser actions on a single page. */
+export declare function interact(
+  engine: CrawlEngineHandle,
+  url: string,
+  actions: Array<PageAction>,
+): Promise<InteractionResult>;
 
 /** Result from a single page action execution. */
 export interface ActionResult {
   /** Zero-based index of the action in the sequence. */
-  actionIndex?: number
+  readonly actionIndex?: number;
   /** The type of action that was executed. */
-  actionType?: string
+  readonly actionType?: string;
   /** Whether the action completed successfully. */
-  success?: boolean
+  readonly success?: boolean;
   /** Action-specific return data (screenshot bytes, JS return value, scraped HTML). */
-  data?: any
+  readonly data?: JsonValue;
   /** Error message if the action failed. */
-  error?: string
+  readonly error?: string;
 }
 
 /** Article metadata extracted from `article:*` Open Graph tags. */
 export interface ArticleMetadata {
   /** The article publication time. */
-  publishedTime?: string
+  readonly publishedTime?: string;
   /** The article modification time. */
-  modifiedTime?: string
+  readonly modifiedTime?: string;
   /** The article author. */
-  author?: string
+  readonly author?: string;
   /** The article section. */
-  section?: string
+  readonly section?: string;
   /** The article tags. */
-  tags?: Array<string>
+  readonly tags?: Array<string>;
 }
 
 /** The category of a downloaded asset. */
-export declare const enum AssetCategory {
+export declare enum AssetCategory {
   /** A document file (PDF, DOC, etc.). */
-  Document = 'document',
+  Document = "document",
   /** An image file. */
-  Image = 'image',
+  Image = "image",
   /** An audio file. */
-  Audio = 'audio',
+  Audio = "audio",
   /** A video file. */
-  Video = 'video',
+  Video = "video",
   /** A font file. */
-  Font = 'font',
+  Font = "font",
   /** A CSS stylesheet. */
-  Stylesheet = 'stylesheet',
+  Stylesheet = "stylesheet",
   /** A JavaScript file. */
-  Script = 'script',
+  Script = "script",
   /** An archive file (ZIP, TAR, etc.). */
-  Archive = 'archive',
+  Archive = "archive",
   /** A data file (JSON, XML, CSV, etc.). */
-  Data = 'data',
+  Data = "data",
   /** An unrecognized asset type. */
-  Other = 'other'
+  Other = "other",
 }
 
 /** Authentication configuration. */
-export interface AuthConfig {
-  type: string
-  username?: string
-  password?: string
-  token?: string
-  name?: string
-  value?: string
-}
-
-/** Crawl multiple seed URLs concurrently, each following links to configured depth. */
-export declare function batchCrawl(engine: CrawlEngineHandle, urls: Array<string>): Promise<BatchCrawlResults>
+export type AuthConfig =
+  | { type: "basic"; username: string; password: string }
+  | { type: "bearer"; token: string }
+  | { type: "header"; name: string; value: string };
 
 /** Result from a single URL in a batch crawl operation. */
 export interface BatchCrawlResult {
   /** The seed URL that was crawled. */
-  url?: string
+  readonly url?: string;
   /** The crawl result, if successful. */
-  result?: JsCrawlResult
+  readonly result?: CrawlResult;
   /** The error message, if the crawl failed. */
-  error?: string
+  readonly error?: string;
 }
 
 /**
@@ -137,17 +115,15 @@ export interface BatchCrawlResult {
  */
 export interface BatchCrawlResults {
   /** Per-URL crawl results, in the order seed URLs were submitted. */
-  results?: Array<BatchCrawlResult>
+  readonly results?: Array<BatchCrawlResult>;
   /** Total number of seed URLs in the batch (equal to `results.len()`). */
-  totalCount?: number
+  readonly totalCount?: number;
   /** Number of seed URLs whose crawl succeeded (`error` is `None`). */
-  completedCount?: number
+  readonly completedCount?: number;
   /** Number of seed URLs whose crawl failed (`error` is `Some`). */
-  failedCount?: number
+  readonly failedCount?: number;
 }
 
-export declare function batchCrawlStream(engine: CrawlEngineHandle, urls: Array<string>): Promise<BatchCrawlStreamIterator>
-
 /**
  * Request to begin a multi-URL streaming crawl.
  *
@@ -160,20 +136,17 @@ export interface BatchCrawlStreamRequest {
    * The seed URLs to crawl. Each URL is followed independently up to the
    * engine's configured depth.
    */
-  urls?: Array<string>
+  readonly urls?: Array<string>;
 }
 
-/** Scrape multiple URLs concurrently. */
-export declare function batchScrape(engine: CrawlEngineHandle, urls: Array<string>): Promise<BatchScrapeResults>
-
 /** Result from a single URL in a batch scrape operation. */
 export interface BatchScrapeResult {
   /** The URL that was scraped. */
-  url?: string
+  readonly url?: string;
   /** The scrape result, if successful. */
-  result?: JsScrapeResult
+  readonly result?: ScrapeResult;
   /** The error message, if the scrape failed. */
-  error?: string
+  readonly error?: string;
 }
 
 /**
@@ -184,72 +157,76 @@ export interface BatchScrapeResult {
  */
 export interface BatchScrapeResults {
   /** Per-URL scrape results, in the order URLs were submitted. */
-  results?: Array<BatchScrapeResult>
+  readonly results?: Array<BatchScrapeResult>;
   /** Total number of URLs in the batch (equal to `results.len()`). */
-  totalCount?: number
+  readonly totalCount?: number;
   /** Number of URLs whose scrape succeeded (`error` is `None`). */
-  completedCount?: number
+  readonly completedCount?: number;
   /** Number of URLs whose scrape failed (`error` is `Some`). */
-  failedCount?: number
+  readonly failedCount?: number;
 }
 
 /** Browser backend used for JavaScript rendering. */
-export declare const enum BrowserBackend {
+export declare enum BrowserBackend {
   /** Existing Chromium/CDP backend powered by chromiumoxide. */
-  Chromiumoxide = 'chromiumoxide',
+  Chromiumoxide = "chromiumoxide",
   /** Crawlberg-owned native browser backend derived from Obscura. */
-  Native = 'native'
+  Native = "native",
 }
 
 /** Browser fallback configuration. */
 export interface BrowserConfig {
   /** When to use the headless browser fallback. */
-  mode?: BrowserMode | 'auto' | 'always' | 'never' | 'stealth'
+  readonly mode?: BrowserMode;
   /** Browser backend used to render JavaScript-heavy pages. */
-  backend?: BrowserBackend | 'chromiumoxide' | 'native'
+  readonly backend?: BrowserBackend;
   /**
    * CDP WebSocket endpoint for connecting to an external browser instance.
    * Crawlberg disconnects during teardown but never closes the external browser process. <!-- -->
    */
-  endpoint?: string
+  readonly endpoint?: string;
   /** Timeout for browser page load and rendering (in milliseconds when serialized). */
-  timeout?: number
+  readonly timeout?: number;
   /**
    * Overall deadline for a single browser fetch, covering browser launch (or
    * page acquisition from a shared pool), page setup, navigation, rendering,
-   * and screenshot capture. Must exceed `timeout` to leave room for launch
-   * and setup overhead; a fetch that has not returned within this deadline
-   * fails with a timeout error (in milliseconds when serialized).
+   * screenshot capture, and every retry of the fetch. Must exceed `timeout`
+   * to leave room for launch and setup overhead; a fetch that has not
+   * returned within this deadline fails with a timeout error (in
+   * milliseconds when serialized). The wait for the delay of the domain
+   * (`rate_limit_ms`) is not counted, so a delay longer than this deadline
+   * does not fail the page. A scrape with the native backend is not bounded
+   * by this deadline.
    *
    * Shutdown/teardown is governed separately by `shutdown_timeout` and is
    * not counted against this deadline: an already-computed result is
    * delivered to the caller without waiting for the browser process to
    * exit.
    */
-  overallTimeout?: number
+  readonly overallTimeout?: number;
   /**
    * How long to wait for the browser process to close and exit cleanly
    * during teardown before the process is forcibly killed (in milliseconds
    * when serialized).
    */
-  shutdownTimeout?: number
+  readonly shutdownTimeout?: number;
   /** Wait strategy after browser navigation. */
-  wait?: BrowserWait | 'network_idle' | 'selector' | 'fixed'
+  readonly wait?: BrowserWait;
   /** CSS selector to wait for when `wait` is `Selector`. */
-  waitSelector?: string
+  readonly waitSelector?: string;
   /** Extra time to wait after the wait condition is met. */
-  extraWait?: number
+  readonly extraWait?: number;
   /**
    * Proxy for browser fetches. Overrides `CrawlConfig.proxy` when set.
    * Native backend supports http/https only (no SOCKS5).
    */
-  proxy?: JsProxyConfig
+  readonly proxy?: ProxyConfig;
   /**
    * URL patterns to block before the network request fires. Supports `*`
    * wildcards. Useful for skipping ads/analytics/large images. Honored by
-   * `BrowserBackend.Native`; chromiumoxide ignores this field today.
+   * both browser backends.
    */
-  blockUrlPatterns?: Array<string>
+  readonly blockUrlPatterns?: Array<string>;
   /**
    * JavaScript snippet evaluated after navigation completes.
    *
@@ -257,23 +234,24 @@ export interface BrowserConfig {
    * Interactions run this script before page actions on both browser backends but do
    * not include the script result in `InteractionResult`.
    */
-  evalScript?: string
+  readonly evalScript?: string;
   /**
    * User-agent used when fetching robots.txt. Defaults to `BrowserConfig.user_agent`
    * (or crawlberg's default) if unset. Native only.
    */
-  robotsUserAgent?: string
+  readonly robotsUserAgent?: string;
   /**
    * Capture the full network event stream into the result. Default false
    * (only the document event is captured). Native only.
    */
-  captureNetworkEvents?: boolean
+  readonly captureNetworkEvents?: boolean;
   /**
    * Enable session affinity: reuse chromiumoxide Pages for same-domain
    * requests so cookies + fingerprint + solved challenges persist.
-   * Default: true. When false, each request gets a fresh Page.
+   * Default: true. Session reuse requires `CrawlConfig.browser_session_pool` alongside a browser pool.
+   * Without a session pool, or when false, each request gets a fresh Page.
    */
-  sessionAffinity?: boolean
+  readonly sessionAffinity?: boolean;
   /**
    * Chrome or Chromium executable to launch. When set, crawlberg launches only this
    * binary, and a path that is missing or not executable is an error that names the
@@ -282,7 +260,7 @@ export interface BrowserConfig {
    * Chromium or Edge. Chromiumoxide backend only: ignored, with a warning, when `endpoint`
    * is set, with the native backend, and by scrapes and crawls that use a shared browser pool.
    */
-  chromePath?: string
+  readonly chromePath?: string;
   /**
    * Extra Chrome command-line flags, each written as `--flag` or `--flag=value`, for example
    * `--user-agent=...`. A flag here replaces a crawlberg default flag of the same name
@@ -295,11 +273,9 @@ export interface BrowserConfig {
    * when `endpoint` is set, with the native backend, and by scrapes and crawls that use a
    * shared browser pool.
    */
-  chromeArgs?: Array<string>
+  readonly chromeArgs?: Array<string>;
 }
 
-export declare function browserConfigDefault(): BrowserConfig
-
 /**
  * Browser-specific extras populated when the native browser backend was used.
  *
@@ -307,27 +283,27 @@ export declare function browserConfigDefault(): BrowserConfig
  */
 export interface BrowserExtras {
   /** Return value of `BrowserConfig.eval_script`, if provided. */
-  evalResult?: any
+  readonly evalResult?: JsonValue;
   /**
    * Network events captured during page navigation (only populated when
    * `BrowserConfig.capture_network_events` is true).
    */
-  networkEvents?: Array<JsResponseMeta>
+  readonly networkEvents?: Array<ResponseMeta>;
   /**
    * All non-expired cookies present in the browser's cookie jar after
    * navigation completes (includes both prior cookies and server Set-Cookie).
    */
-  cookies?: Array<JsCookieInfo>
+  readonly cookies?: Array<CookieInfo>;
 }
 
 /** When to use the headless browser fallback. */
-export declare const enum BrowserMode {
+export declare enum BrowserMode {
   /** Automatically detect when JS rendering is needed and fall back to browser. */
-  Auto = 'auto',
+  Auto = "auto",
   /** Always use the browser for every request. */
-  Always = 'always',
+  Always = "always",
   /** Never use the browser fallback. */
-  Never = 'never',
+  Never = "never",
   /**
    * Always use the browser with all stealth surfaces enabled.
    *
@@ -343,17 +319,17 @@ export declare const enum BrowserMode {
    * Use this instead of setting the now-removed `BrowserConfig.stealth`
    * boolean field.
    */
-  Stealth = 'stealth'
+  Stealth = "stealth",
 }
 
 /** Wait strategy for browser page rendering. */
-export declare const enum BrowserWait {
+export declare enum BrowserWait {
   /** Wait until network activity is idle. */
-  NetworkIdle = 'network_idle',
+  NetworkIdle = "network_idle",
   /** Wait for a specific CSS selector to appear in the DOM. */
-  Selector = 'selector',
+  Selector = "selector",
   /** Wait for a fixed duration after navigation. */
-  Fixed = 'fixed'
+  Fixed = "fixed",
 }
 
 /**
@@ -362,19 +338,19 @@ export declare const enum BrowserWait {
  */
 export interface CitationReference {
   /** 1-based reference number as it appears in the source text. */
-  index?: number
+  readonly index?: number;
   /** Resolved absolute URL for this reference. */
-  url?: string
+  readonly url?: string;
   /** Human-readable anchor text or title for the reference. */
-  text?: string
+  readonly text?: string;
 }
 
 /** Result of citation conversion. */
 export interface CitationResult {
   /** Markdown with links replaced by numbered citations. */
-  content?: string
+  readonly content?: string;
   /** Numbered reference list: (index, url, text). */
-  references?: Array<CitationReference>
+  readonly references?: Array<CitationReference>;
 }
 
 /**
@@ -386,7 +362,7 @@ export interface CitationResult {
  */
 export interface ContentConfig {
   /** Output format: `"markdown"` (default), `"plain"`, `"djot"`. */
-  outputFormat?: string
+  readonly outputFormat?: string;
   /**
    * Preprocessing aggressiveness: `"minimal"`, `"standard"` (default), `"aggressive"`.
    *
@@ -394,18 +370,18 @@ export interface ContentConfig {
    * - Standard: also removes nav, nav-hinted headers/footers/asides, forms.
    * - Aggressive: removes all footers/asides unconditionally.
    */
-  preprocessingPreset?: string
+  readonly preprocessingPreset?: string;
   /** Remove navigation elements (nav, breadcrumbs, menus). Default: `true`. */
-  removeNavigation?: boolean
+  readonly removeNavigation?: boolean;
   /** Remove form elements. Default: `true`. */
-  removeForms?: boolean
+  readonly removeForms?: boolean;
   /**
    * HTML tag names to strip (render children only, remove the tag wrapper).
    * Default: `[]`.
    */
-  stripTags?: Array<string>
+  readonly stripTags?: Array<string>;
   /** HTML tag names to preserve as raw HTML in output. */
-  preserveTags?: Array<string>
+  readonly preserveTags?: Array<string>;
   /**
    * CSS selectors for elements to exclude entirely (element + all content).
    *
@@ -421,17 +397,17 @@ export interface ContentConfig {
    *
    * Example: `[".cookie-banner", "#ad-container", "[role='complementary']"]`
    */
-  excludeSelectors?: Array<string>
+  readonly excludeSelectors?: Array<string>;
   /** Skip image elements in output. Default: `false`. */
-  skipImages?: boolean
+  readonly skipImages?: boolean;
   /** Max DOM traversal depth. Prevents stack overflow on deeply nested HTML. */
-  maxDepth?: number
+  readonly maxDepth?: number;
   /** Enable line wrapping. Default: `false`. */
-  wrap?: boolean
+  readonly wrap?: boolean;
   /** Wrap width when `wrap` is enabled. Default: `80`. */
-  wrapWidth?: number
+  readonly wrapWidth?: number;
   /** Include document structure tree in output. Default: `true`. */
-  includeDocumentStructure?: boolean
+  readonly includeDocumentStructure?: boolean;
   /**
    * Prepend a YAML frontmatter block (`title`, `description`, etc., extracted from
    * `<head>`) to the markdown output. Default: `true`.
@@ -441,64 +417,89 @@ export interface ContentConfig {
    * is populated independently by `crate.html.metadata.extract_metadata` from the
    * parsed DOM, so turning this off does not lose any metadata field.
    */
-  extractMetadata?: boolean
+  readonly extractMetadata?: boolean;
+  /** Replace paragraph source line breaks with spaces. Default: `false`. */
+  readonly stripNewlines?: boolean;
+  /** Markdown unordered-list markers, cycled by nesting level. Default: `"-*+"`. */
+  readonly bullets?: string;
+  /** Spaces per nested list level. Default: `2`. */
+  readonly listIndentWidth?: number;
+  /** Markdown emphasis marker: `"*"` (default) or `"_"`. */
+  readonly strongEmSymbol?: string;
+  /** Render tables without column-width padding. Default: `false`. */
+  readonly compactTables?: boolean;
+  /** HTML elements whose inline images stay images instead of alt text. Default: `[]`. */
+  readonly keepInlineImagesIn?: Array<string>;
+  /**
+   * Keep hidden elements, including body templates, in converted output. Default: `false`.
+   * Scripts and styles remain excluded; explicit exclusions and image settings still apply.
+   */
+  readonly keepHidden?: boolean;
 }
 
-export declare function contentConfigDefault(): ContentConfig
-
 /** Content filter applied to each crawled page before it reaches the result. */
-export declare const enum ContentFilterKind {
+export declare enum ContentFilterKind {
   /** Keep only pages scoring at or above `bm25_threshold` for `bm25_query`. */
-  Bm25 = 'bm_25'
+  Bm25 = "bm_25",
 }
 
-/** Information about an HTTP cookie received from a response. */
+/**
+ * Information about a cookie that a crawled page set.
+ *
+ * A crawl result gives `domain` and `path` as the browser stores the cookie, so a cookie has
+ * the same fields whether an HTTP fetch or the browser received it.
+ */
 export interface CookieInfo {
   /** The cookie name. */
-  name?: string
+  readonly name?: string;
   /** The cookie value. */
-  value?: string
-  /** The cookie domain, if specified. */
-  domain?: string
-  /** The cookie path, if specified. */
-  path?: string
+  readonly value?: string;
+  /**
+   * The hosts that get the cookie back. A host-only cookie (no `Domain` attribute) has the
+   * host that set it, such as `example.com`. A domain cookie has its domain with a leading
+   * dot, such as `.example.com`. A `Domain` equal to an IP address or a one-label host gives
+   * a host-only cookie.
+   */
+  readonly domain?: string;
+  /**
+   * The path that gets the cookie back: the `Path` attribute when it starts with `/`,
+   * otherwise the directory of the page that set the cookie (RFC 6265 default path).
+   */
+  readonly path?: string;
 }
 
-/** Crawl a website starting from `url`, following links up to the configured depth. */
-export declare function crawl(engine: CrawlEngineHandle, url: string): Promise<CrawlResult>
-
 /** Configuration for crawl, scrape, and map operations. */
 export interface CrawlConfig {
   /** Maximum crawl depth (number of link hops from the start URL). */
-  maxDepth?: number
+  readonly maxDepth?: number;
   /** Maximum number of pages to crawl. */
-  maxPages?: number
+  readonly maxPages?: number;
   /**
    * Maximum links enqueued from a single page. Defaults to 10000.
    *
    * Bounds the work one hostile or pathological page can create; links past the
    * cap are dropped and a warning is logged.
    */
-  maxLinksPerPage?: number
+  readonly maxLinksPerPage?: number;
   /** Maximum number of concurrent requests. */
-  maxConcurrent?: number
+  readonly maxConcurrent?: number;
   /**
    * Traversal order. Defaults to breadth-first.
    *
    * A frontier or strategy set explicitly on `CrawlEngineBuilder` takes precedence over
    * this field.
    */
-  crawlStrategy?: CrawlStrategyKind | 'bfs' | 'dfs' | 'best_first' | 'adaptive'
+  readonly crawlStrategy?: CrawlStrategyKind;
   /**
    * Content filter applied to each page. `None` keeps every page.
    *
    * A content filter set explicitly on `CrawlEngineBuilder` takes precedence.
    */
-  contentFilter?: ContentFilterKind | 'bm_25'
+  readonly contentFilter?: ContentFilterKind;
   /** Query the BM25 content filter scores pages against. Required by `ContentFilterKind.Bm25`. */
-  bm25Query?: string
+  readonly bm25Query?: string;
   /** Minimum BM25 score a page must reach to be kept. Defaults to `0.0`. */
-  bm25Threshold?: number
+  readonly bm25Threshold?: number;
   /**
    * Whether to respect robots.txt directives. A crawl that respects them also honours
    * the page's own robots instructions: it does not follow the links of a page marked
@@ -507,7 +508,7 @@ export interface CrawlConfig {
    * page is still crawled and its links followed; the page result marks it with
    * `noindex_detected`.
    */
-  respectRobotsTxt?: boolean
+  readonly respectRobotsTxt?: boolean;
   /**
    * When true, HTTP-level error responses (404 NotFound, 403 Forbidden, WAF blocks)
    * are surfaced as `ScrapeResult` records with the matching `status_code` rather
@@ -519,9 +520,9 @@ export interface CrawlConfig {
    * the user opted into redirect-following, so receiving a 404 there is part of
    * the normal flow rather than an unexpected error.
    */
-  softHttpErrors?: boolean
+  readonly softHttpErrors?: boolean;
   /** Custom user-agent string. */
-  userAgent?: string
+  readonly userAgent?: string;
   /**
    * Whether to confine *document* links (`.pdf`, `.docx`, `.zip`, ...) to the seed domain.
    *
@@ -531,18 +532,18 @@ export interface CrawlConfig {
    * are followed cross-host by default -- the usual case being documents served from a CDN
    * or object store. Set this to `true` to require documents to live on the seed domain too.
    */
-  stayOnDomain?: boolean
+  readonly stayOnDomain?: boolean;
   /**
    * Whether subdomains of the seed host are in scope.
    *
    * Applies to page links unconditionally, and to document links when
    * `Self.stay_on_domain` is set.
    */
-  allowSubdomains?: boolean
+  readonly allowSubdomains?: boolean;
   /** Regex patterns for paths to include during crawling. */
-  includePaths?: Array<string>
+  readonly includePaths?: Array<string>;
   /** Regex patterns for paths to exclude during crawling. */
-  excludePaths?: Array<string>
+  readonly excludePaths?: Array<string>;
   /**
    * Whether `include_paths`/`exclude_paths` match against `path?query` instead of just
    * `path`. Defaults to `false`, matching path only: a pattern anchored with `$` (e.g.
@@ -550,7 +551,7 @@ export interface CrawlConfig {
    * opt-in rather than silently changing what an existing config matches. Has no effect
    * when `Self.path_patterns_match_url` is `true`.
    */
-  pathPatternsMatchQuery?: boolean
+  readonly pathPatternsMatchQuery?: boolean;
   /**
    * Whether `include_paths`/`exclude_paths` match against the full URL,
    * `scheme://host[:port]/path?query`, so a pattern can scope by host. Defaults to `false`.
@@ -559,20 +560,20 @@ export interface CrawlConfig {
    * `user:password@`, a fragment or a default port, and the host is in punycode
    * (`bücher.de` is matched as `xn--bcher-kva.de`).
    */
-  pathPatternsMatchUrl?: boolean
+  readonly pathPatternsMatchUrl?: boolean;
   /**
-   * Whether the crawl-dedup key includes the (sorted) query string. Defaults to `false`,
-   * matching historical behavior: `/item?id=1` and `/item?id=2` are treated as one page and
-   * only the first is fetched. `true` keeps the query, sorted, in the key, so each distinct
-   * query is fetched once.
+   * Whether the crawl-dedup key includes the query string, sorted by parameter name.
+   * Defaults to `true`: `/item?id=1` and `/item?id=2` are distinct pages, each fetched once.
+   * Set to `false` to merge query variants and fetch only the first. Session parameters
+   * produce a page for each distinct value unless removed with `strip_tracking_params`.
    */
-  dedupIncludeQuery?: boolean
+  readonly dedupIncludeQuery?: boolean;
   /**
    * Whether to strip `tracking_params` from a discovered URL before it is deduplicated,
    * fetched, and reported. Defaults to `false`, so no tracking parameters are stripped
    * unless explicitly enabled.
    */
-  stripTrackingParams?: boolean
+  readonly stripTrackingParams?: boolean;
   /**
    * Query parameter name patterns to strip when `strip_tracking_params` is `true`. A
    * pattern ending in `*` matches by prefix (`utm_*` matches `utm_source`, `utm_campaign`,
@@ -580,46 +581,47 @@ export interface CrawlConfig {
    * `["utm_*", "fbclid", "gclid", "ref"]`, applied only once `strip_tracking_params` is
    * enabled.
    */
-  trackingParams?: Array<string>
+  readonly trackingParams?: Array<string>;
   /**
    * Custom HTTP headers to send with each request to the seed URL's host. A request to another host
    * does not carry them.
    */
-  customHeaders?: Record<string, string>
+  readonly customHeaders?: Record<string, string>;
   /** Timeout for individual HTTP requests (in milliseconds when serialized). */
-  requestTimeout?: number
+  readonly requestTimeout?: number;
   /**
    * Per-domain rate limit in milliseconds. When set, enforces a minimum delay
-   * between requests to the same domain. Defaults to 200ms when `None`.
+   * between requests to the same domain, in HTTP mode and before each page load in
+   * browser mode. When `None`, HTTP mode uses 200ms and browser mode applies no delay.
    */
-  rateLimitMs?: number
+  readonly rateLimitMs?: number;
   /** Maximum number of redirects to follow. */
-  maxRedirects?: number
+  readonly maxRedirects?: number;
   /** Number of retry attempts for failed requests. Bounded by `MAX_RETRY_COUNT`. */
-  retryCount?: number
+  readonly retryCount?: number;
   /**
    * HTTP status codes that should trigger a retry. When empty, every rate limit, server
    * error, bad gateway and timeout is retried. When set, only a failure whose status is
    * listed is retried, so a timeout without a response is not.
    */
-  retryCodes?: Array<number>
+  readonly retryCodes?: Array<number>;
   /**
    * Initial delay, in milliseconds, before the first retry. Doubled on each
    * subsequent attempt (capped at `retry_max_delay_ms`). Defaults to 100ms.
    */
-  retryInitialDelayMs?: number
+  readonly retryInitialDelayMs?: number;
   /** Upper bound, in milliseconds, on the exponential retry backoff. Defaults to 60s. */
-  retryMaxDelayMs?: number
+  readonly retryMaxDelayMs?: number;
   /**
    * Fraction of the per-domain rate-limit delay to randomly jitter by, in `[0.0, 1.0]`.
    * `0.0` (the default) applies no jitter and preserves the previous fixed-interval
    * behaviour; `0.1` jitters the delay by up to ±10%.
    */
-  rateLimitJitterRatio?: number
+  readonly rateLimitJitterRatio?: number;
   /** Whether to enable cookie handling. */
-  cookiesEnabled?: boolean
+  readonly cookiesEnabled?: boolean;
   /** Authentication configuration. */
-  auth?: JsAuthConfig
+  readonly auth?: AuthConfig;
   /**
    * Maximum response body size in bytes.
    *
@@ -628,27 +630,27 @@ export interface CrawlConfig {
    * hundred compressed bytes can otherwise expand to gigabytes in memory. To read
    * bodies larger than that, set this explicitly.
    */
-  maxBodySize?: number
+  readonly maxBodySize?: number;
   /** CSS selectors for tags to remove from HTML before processing. */
-  removeTags?: Array<string>
+  readonly removeTags?: Array<string>;
   /** Content extraction and conversion configuration. */
-  content?: ContentConfig
+  readonly content?: ContentConfig;
   /** Maximum number of URLs to return from a map operation. */
-  mapLimit?: number
+  readonly mapLimit?: number;
   /** Search filter for map results (case-insensitive substring match on URLs). */
-  mapSearch?: string
+  readonly mapSearch?: string;
   /** Whether to download assets (CSS, JS, images, etc.) from the page. */
-  downloadAssets?: boolean
+  readonly downloadAssets?: boolean;
   /** Filter for asset categories to download. */
-  assetTypes?: Array<AssetCategory | 'document' | 'image' | 'audio' | 'video' | 'font' | 'stylesheet' | 'script' | 'archive' | 'data' | 'other'>
+  readonly assetTypes?: Array<AssetCategory>;
   /** Maximum size in bytes for individual asset downloads. */
-  maxAssetSize?: number
+  readonly maxAssetSize?: number;
   /** Browser configuration. */
-  browser?: BrowserConfig
+  readonly browser?: BrowserConfig;
   /** Proxy configuration for HTTP requests. */
-  proxy?: JsProxyConfig
+  readonly proxy?: ProxyConfig;
   /** List of user-agent strings for rotation. If non-empty, overrides `user_agent`. */
-  userAgents?: Array<string>
+  readonly userAgents?: Array<string>;
   /**
    * Whether to capture a screenshot when using the browser.
    *
@@ -660,29 +662,29 @@ export interface CrawlConfig {
    * `BrowserMode.Auto`/`Never`, or during `crawl()`) has no effect and logs a
    * warning rather than silently doing nothing.
    */
-  captureScreenshot?: boolean
+  readonly captureScreenshot?: boolean;
   /**
    * Re-enqueue discovered `LinkType.Document` URLs into the crawl frontier so
    * the crawl follows links *from* document pages (PDFs, etc.) as it would
    * from HTML pages. Default: `false` (documents terminate at materialisation).
    */
-  followDocumentUrls?: boolean
+  readonly followDocumentUrls?: boolean;
   /**
    * Maximum document-depth (from the seed URL through document links only)
    * when `follow_document_urls` is true. `None` means inherit `max_depth`.
    * Independent of `max_depth`: a document URL is enqueued only if BOTH the
    * outer `max_depth` and (if set) `document_url_depth` permit it.
    */
-  documentUrlDepth?: number
+  readonly documentUrlDepth?: number;
   /**
    * Whether to download non-HTML documents (PDF, DOCX, images, code, etc.) instead of skipping them.
    * Defaults to `true` — unlike `download_assets` and `capture_screenshot`, which default to `false`.
    */
-  downloadDocuments?: boolean
+  readonly downloadDocuments?: boolean;
   /** Maximum size in bytes for document downloads. Defaults to 50 MB. */
-  documentMaxSize?: number
+  readonly documentMaxSize?: number;
   /** Allowlist of MIME types to download. If empty, uses built-in defaults. */
-  documentMimeTypes?: Array<string>
+  readonly documentMimeTypes?: Array<string>;
   /**
    * Directory to stream downloaded document bytes into instead of holding them in
    * memory on `DownloadedDocument.content`. When set, `content` is left empty and
@@ -690,16 +692,16 @@ export interface CrawlConfig {
    * `None` (default) preserves today's in-memory-only behavior. Has no effect on
    * wasm32, which has no filesystem — use `document_content_encoding` there instead.
    */
-  documentOutputDir?: string
+  readonly documentOutputDir?: string;
   /**
    * Opt-in encoding that duplicates `DownloadedDocument.content` into a serializable
    * field for language bindings that need the bytes in-memory (`content` itself is
    * `alef(skip)`ed). `None` (default) means no encoding is produced. Independent of
    * `document_output_dir` — set both to get a file on disk and an in-memory copy.
    */
-  documentContentEncoding?: DocumentContentEncoding | 'base_64'
+  readonly documentContentEncoding?: DocumentContentEncoding;
   /** Path to write WARC output. If `None`, WARC output is disabled. */
-  warcOutput?: string
+  readonly warcOutput?: string;
   /**
    * Named browser profile for persistent sessions (cookies, localStorage).
    *
@@ -710,9 +712,9 @@ export interface CrawlConfig {
    * exists) or when connecting to an external CDP endpoint whose process crawlberg
    * does not own.
    */
-  browserProfile?: string
+  readonly browserProfile?: string;
   /** Whether to save changes back to the browser profile on exit. */
-  saveBrowserProfile?: boolean
+  readonly saveBrowserProfile?: boolean;
   /**
    * SSRF policy for outbound network requests. Default: deny private networks,
    * allow http/https only, max 5 redirects.
@@ -727,7 +729,7 @@ export interface CrawlConfig {
    * `deny_private = true`. Enforce egress restrictions at the network layer for that
    * deployment target; do not rely on this field. See `crawlberg.net.validate_url`.
    */
-  ssrf?: JsSsrfPolicy
+  readonly ssrf?: SsrfPolicy;
   /**
    * Pins `SsrfPolicy.deny_private` to a caller-chosen value, bypassing the
    * `CRAWLBERG_ALLOW_PRIVATE_NETWORK` operator override entirely for this config.
@@ -747,10 +749,43 @@ export interface CrawlConfig {
    * `ssrf.deny_private` to `false`. `Some(value)` pins `ssrf.deny_private` to `value`
    * and the environment variable is not consulted for this config.
    */
-  ssrfDenyPrivateExplicit?: boolean
+  readonly ssrfDenyPrivateExplicit?: boolean;
 }
 
-export declare function crawlConfigDefault(): CrawlConfig
+/**
+ * Opaque handle to a configured crawl engine.
+ *
+ * Constructed via `create_engine` with an optional `CrawlConfig`.
+ * Default implementations for all pluggable components are used internally.
+ */
+export declare class CrawlEngineHandle {
+  /**
+   * Stream a single-URL crawl, yielding `CrawlEvent`s as pages are processed.
+   *
+   * Returns an async stream that emits one event per crawled page, plus a
+   * terminal `Complete` event. On per-URL failure during the crawl, emits an
+   * `Error` event followed by `Complete`. The stream item type is wrapped in
+   * a `Result` to surface transport-level errors; today every emit is `Ok`.
+   *
+   * Language bindings expose this as the native streaming shape for each
+   * target. WASM does not expose native streaming wrappers.
+   */
+  crawlStream(req?: CrawlStreamRequest | undefined | null): Promise<AsyncGenerator<CrawlEvent, void, undefined>>;
+  /**
+   * Stream a multi-URL crawl, yielding `CrawlEvent`s across all seeds.
+   *
+   * Returns an async stream that emits one event per crawled page across all
+   * seeds, plus terminal `Complete` and `Error` events as appropriate. The
+   * stream item type is wrapped in a `Result` to surface transport-level
+   * errors; today every emit is `Ok`.
+   *
+   * Language bindings expose this as the native streaming shape for each
+   * target. WASM does not expose native streaming wrappers.
+   */
+  batchCrawlStream(
+    req?: BatchCrawlStreamRequest | undefined | null,
+  ): Promise<AsyncGenerator<CrawlEvent, void, undefined>>;
+}
 
 /**
  * An event emitted during a streaming crawl operation.
@@ -760,101 +795,103 @@ export declare function crawlConfigDefault(): CrawlConfig
  *
  * Delivered to bindings through each target's native streaming idiom.
  */
-export interface CrawlEvent {
-  type: string
-  result?: CrawlPageResult
-  url?: string
-  error?: string
-  pagesCrawled?: number
-}
+export type CrawlEvent =
+  | { type: "page"; result: CrawlPageResult }
+  | { type: "error"; url: string; error: string }
+  | { type: "complete"; pagesCrawled: number };
 
 /** The result of crawling a single page during a crawl operation. */
 export interface CrawlPageResult {
   /** The original URL of the page. */
-  url?: string
+  readonly url?: string;
   /** The normalized URL of the page. */
-  normalizedUrl?: string
+  readonly normalizedUrl?: string;
   /** The HTTP status code of the response. */
-  statusCode?: number
+  readonly statusCode?: number;
   /** The Content-Type header value. */
-  contentType?: string
+  readonly contentType?: string;
   /** The HTML body of the response. */
-  html?: string
+  readonly html?: string;
   /** The size of the response body in bytes. */
-  bodySize?: number
+  readonly bodySize?: number;
   /** Extracted metadata from the page. */
-  metadata?: JsPageMetadata
+  readonly metadata?: PageMetadata;
   /** Links found on the page. */
-  links?: Array<JsLinkInfo>
+  readonly links?: Array<LinkInfo>;
   /** Images found on the page. */
-  images?: Array<JsImageInfo>
+  readonly images?: Array<ImageInfo>;
   /** Feed links found on the page. */
-  feeds?: Array<JsFeedInfo>
+  readonly feeds?: Array<FeedInfo>;
   /** JSON-LD entries found on the page. */
-  jsonLd?: Array<JsJsonLdEntry>
+  readonly jsonLd?: Array<JsonLdEntry>;
   /** The depth of this page from the start URL. */
-  depth?: number
+  readonly depth?: number;
   /** Whether this page is on the same domain as the start URL. */
-  stayedOnDomain?: boolean
+  readonly stayedOnDomain?: boolean;
   /** Whether this page was skipped (binary or PDF content). */
-  wasSkipped?: boolean
+  readonly wasSkipped?: boolean;
   /** Whether the content is a PDF. */
-  isPdf?: boolean
+  readonly isPdf?: boolean;
   /** The detected character set encoding. */
-  detectedCharset?: string
+  readonly detectedCharset?: string;
   /** Markdown conversion of the page content. */
-  markdown?: JsMarkdownResult
+  readonly markdown?: MarkdownResult;
   /** Structured data extracted by LLM. Populated when extraction is configured. */
-  extractedData?: any
+  readonly extractedData?: JsonValue;
   /** Metadata about the LLM extraction pass (cost, tokens, model). */
-  extractionMeta?: JsExtractionMeta
+  readonly extractionMeta?: ExtractionMeta;
   /** Downloaded non-HTML document (PDF, DOCX, image, code, etc.). */
-  downloadedDocument?: JsDownloadedDocument
+  readonly downloadedDocument?: DownloadedDocument;
   /** Whether the browser fallback was used to fetch this page. */
-  browserUsed?: boolean
+  readonly browserUsed?: boolean;
   /**
    * The URL this page's content was actually fetched from, after following any HTTP,
    * `Refresh` header, or `<meta http-equiv="refresh">` redirect `url` pointed at.
    * Equal to `url` when the fetch did not redirect.
    */
-  finalUrl?: string
+  readonly finalUrl?: string;
   /** Redirect hops taken to reach `final_url` from `url`. */
-  redirectCount?: number
+  readonly redirectCount?: number;
   /**
    * Whether the page asked not to be indexed, by its robots meta tag or `X-Robots-Tag`
    * header. The page is still crawled and its links still followed.
    */
-  noindexDetected?: boolean
+  readonly noindexDetected?: boolean;
   /**
    * Whether the page asked that its links not be followed, by its robots meta tag or
    * `X-Robots-Tag` header. When the crawl respects robots, its links are not followed.
    */
-  nofollowDetected?: boolean
+  readonly nofollowDetected?: boolean;
   /**
    * URLs of the requests the page sent in browser mode that the SSRF policy refused, without
    * their credentials, each listed once. The page is kept; only the refused requests failed.
    */
-  ssrfRefusedUrls?: Array<string>
+  readonly ssrfRefusedUrls?: Array<string>;
+  /**
+   * Seed address as supplied, or the discovered link address resolved against its base.
+   * Preserves source spelling through redirects; URL credentials are removed. <!-- -->
+   */
+  readonly originalUrl?: string;
 }
 
 /** The result of a multi-page crawl operation. */
 export interface CrawlResult {
   /** The list of crawled pages. */
-  pages?: Array<CrawlPageResult>
+  readonly pages?: Array<CrawlPageResult>;
   /** The final URL after following redirects. */
-  finalUrl?: string
+  readonly finalUrl?: string;
   /** The number of redirects followed. */
-  redirectCount?: number
+  readonly redirectCount?: number;
   /** Whether any page was skipped during crawling. */
-  wasSkipped?: boolean
+  readonly wasSkipped?: boolean;
   /** An error message, if the crawl encountered an issue. */
-  error?: string
+  readonly error?: string;
   /** Cookies collected during the crawl. */
-  cookies?: Array<CookieInfo>
+  readonly cookies?: Array<CookieInfo>;
   /** Whether all crawled pages stayed on the same domain as the start URL. */
-  stayedOnDomain?: boolean
+  readonly stayedOnDomain?: boolean;
   /** Whether the browser fallback was used for any page in this crawl. */
-  browserUsed?: boolean
+  readonly browserUsed?: boolean;
 }
 
 /**
@@ -864,19 +901,17 @@ export interface CrawlResult {
  * property of the frontier: the engine hands its bounded selection window to the strategy, so
  * a strategy alone can only reorder URLs that have already been dequeued.
  */
-export declare const enum CrawlStrategyKind {
+export declare enum CrawlStrategyKind {
   /** Breadth-first: a FIFO frontier visits every URL at one depth before the next. */
-  Bfs = 'bfs',
+  Bfs = "bfs",
   /** Depth-first: a LIFO frontier descends into a page's children before its siblings. */
-  Dfs = 'dfs',
+  Dfs = "dfs",
   /** Highest-priority-first within the selection window, scored by `CrawlStrategy.score_url`. */
-  BestFirst = 'best_first',
+  BestFirst = "best_first",
   /** Like `BestFirst`, but stops once newly crawled pages stop contributing new terms. */
-  Adaptive = 'adaptive'
+  Adaptive = "adaptive",
 }
 
-export declare function crawlStream(engine: CrawlEngineHandle, url: string): Promise<CrawlStreamIterator>
-
 /**
  * Request to begin a single-URL streaming crawl.
  *
@@ -886,17 +921,9 @@ export declare function crawlStream(engine: CrawlEngineHandle, url: string): Pro
  */
 export interface CrawlStreamRequest {
   /** The seed URL to crawl. */
-  url?: string
+  readonly url?: string;
 }
 
-/**
- * Create a new crawl engine with the given configuration.
- *
- * If `config` is `None`, uses `CrawlConfig.default()`.
- * Returns an error if the configuration is invalid.
- */
-export declare function createEngine(config?: CrawlConfig | undefined | null): CrawlEngineHandle
-
 /**
  * Opt-in encoding applied to a downloaded document's bytes for callers who need the
  * content available in a serializable field rather than reading it from disk.
@@ -905,25 +932,25 @@ export declare function createEngine(config?: CrawlConfig | undefined | null): C
  * screenshots, base64-encoding a document by default would duplicate an already
  * up-to-`document_max_size` buffer (50 MB default) in memory per document.
  */
-export declare const enum DocumentContentEncoding {
+export declare enum DocumentContentEncoding {
   /** Populate `DownloadedDocument.content_base64` with a base64-encoded copy. */
-  Base64 = 'base_64'
+  Base64 = "base_64",
 }
 
 /** A downloaded asset from a page. */
 export interface DownloadedAsset {
   /** The original URL of the asset. */
-  url?: string
+  readonly url?: string;
   /** The SHA-256 content hash of the asset. */
-  contentHash?: string
+  readonly contentHash?: string;
   /** The MIME type from the Content-Type header. */
-  mimeType?: string
+  readonly mimeType?: string;
   /** The size of the asset in bytes. */
-  size?: number
+  readonly size?: number;
   /** The category of the asset. */
-  assetCategory?: AssetCategory | 'document' | 'image' | 'audio' | 'video' | 'font' | 'stylesheet' | 'script' | 'archive' | 'data' | 'other'
+  readonly assetCategory?: AssetCategory;
   /** The HTML tag that referenced this asset (e.g., "link", "script", "img"). */
-  htmlTag?: string
+  readonly htmlTag?: string;
 }
 
 /**
@@ -935,95 +962,86 @@ export interface DownloadedAsset {
  */
 export interface DownloadedDocument {
   /** The URL the document was fetched from. */
-  url?: string
+  readonly url?: string;
   /** The MIME type from the Content-Type header. */
-  mimeType?: string
+  readonly mimeType?: string;
   /** Size of the document in bytes. */
-  size?: number
+  readonly size?: number;
   /** Filename extracted from Content-Disposition or URL path. */
-  filename?: string
+  readonly filename?: string;
   /** SHA-256 hex digest of the content. */
-  contentHash?: string
+  readonly contentHash?: string;
   /** Selected response headers. */
-  headers?: Record<string, string>
+  readonly headers?: Record<string, string>;
   /**
    * True when `content` (or the file at `content_path`) was truncated to
    * `document_max_size`; `size` still reports the original, untruncated length.
    */
-  truncated?: boolean
+  readonly truncated?: boolean;
   /**
    * Filesystem path the document was streamed to when `document_output_dir` was
    * set. `content` is empty in memory when this is populated.
    */
-  contentPath?: string
+  readonly contentPath?: string;
   /**
    * Base64-encoded copy of `content`, populated only when
    * `document_content_encoding` was set to `Base64`.
    */
-  contentBase64?: string
+  readonly contentBase64?: string;
 }
 
 /** Metadata about an LLM extraction pass. */
 export interface ExtractionMeta {
   /** Estimated cost of the LLM call in USD. */
-  cost?: number
+  readonly cost?: number;
   /** Number of prompt (input) tokens consumed. */
-  promptTokens?: number
+  readonly promptTokens?: number;
   /** Number of completion (output) tokens generated. */
-  completionTokens?: number
+  readonly completionTokens?: number;
   /** The model identifier used for extraction. */
-  model?: string
+  readonly model?: string;
   /** Number of content chunks sent to the LLM. */
-  chunksProcessed?: number
+  readonly chunksProcessed?: number;
 }
 
 /** Information about a favicon or icon link. */
 export interface FaviconInfo {
   /** The icon URL. */
-  url?: string
+  readonly url?: string;
   /** The `rel` attribute (e.g., "icon", "apple-touch-icon"). */
-  rel?: string
+  readonly rel?: string;
   /** The `sizes` attribute, if present. */
-  sizes?: string
+  readonly sizes?: string;
   /** The MIME type, if present. */
-  mimeType?: string
+  readonly mimeType?: string;
 }
 
 /** Information about a feed link found on a page. */
 export interface FeedInfo {
   /** The feed URL. */
-  url?: string
+  readonly url?: string;
   /** The feed title, if present. */
-  title?: string
+  readonly title?: string;
   /** The type of feed. */
-  feedType?: FeedType | 'rss' | 'atom' | 'json_feed'
+  readonly feedType?: FeedType;
 }
 
 /** The type of a feed (RSS, Atom, or JSON Feed). */
-export declare const enum FeedType {
+export declare enum FeedType {
   /** RSS feed. */
-  Rss = 'rss',
+  Rss = "rss",
   /** Atom feed. */
-  Atom = 'atom',
+  Atom = "atom",
   /** JSON Feed. */
-  JsonFeed = 'json_feed'
+  JsonFeed = "json_feed",
 }
 
-/**
- * Convert markdown links to numbered citations.
- *
- * `[Example](https://example.com)` becomes `Example[1]`
- * with `[1]: https://example.com` in the reference list.
- * Images `![alt](url)` are preserved unchanged.
- */
-export declare function generateCitations(markdown: string): CitationResult
-
 /** A heading element extracted from the page. */
 export interface HeadingInfo {
   /** The heading level (1-6). */
-  level?: number
+  readonly level?: number;
   /** The heading text content. */
-  text?: string
+  readonly text?: string;
 }
 
 /**
@@ -1043,125 +1061,125 @@ export interface HeadingInfo {
  *
  * `Exact`: HostMatcher.Exact
  */
-export interface HostMatcher {
-  type: string
-  value?: string
-}
+export type HostMatcher =
+  | { type: "exact"; value: string }
+  | { type: "suffix"; value: string }
+  | { type: "cidr"; value: string };
 
 /** An hreflang alternate link entry. */
 export interface HreflangEntry {
   /** The language code (e.g., "en", "fr", "x-default"). */
-  lang?: string
+  readonly lang?: string;
   /** The URL for this language variant. */
-  url?: string
+  readonly url?: string;
 }
 
 /** Information about an image found on a page. */
 export interface ImageInfo {
   /** The image URL. */
-  url?: string
+  readonly url?: string;
   /** The alt text, if present. */
-  alt?: string
+  readonly alt?: string;
   /** The width attribute, if present and parseable. */
-  width?: number
+  readonly width?: number;
   /** The height attribute, if present and parseable. */
-  height?: number
+  readonly height?: number;
   /** The source of the image reference. */
-  source?: ImageSource | 'img' | 'picture_source' | 'og:image' | 'twitter:image'
+  readonly source?: ImageSource;
 }
 
 /** The source of an image reference. */
-export declare const enum ImageSource {
+export declare enum ImageSource {
   /** An `<img>` tag. */
-  Img = 'img',
+  Img = "img",
   /** A `<source>` tag inside `<picture>`. */
-  PictureSource = 'picture_source',
+  PictureSource = "picture_source",
   /** An `og:image` meta tag. */
-  OgImage = 'og:image',
+  OgImage = "og:image",
   /** A `twitter:image` meta tag. */
-  TwitterImage = 'twitter:image'
+  TwitterImage = "twitter:image",
 }
 
-/** Execute browser actions on a single page. */
-export declare function interact(engine: CrawlEngineHandle, url: string, actions: Array<PageAction>): Promise<InteractionResult>
-
 /** Result of executing a sequence of page interaction actions. */
 export interface InteractionResult {
   /** Results from each executed action. */
-  actionResults?: Array<ActionResult>
+  readonly actionResults?: Array<ActionResult>;
   /** Final page HTML after all actions completed. */
-  finalHtml?: string
+  readonly finalHtml?: string;
   /** Final page URL (may have changed due to navigation). */
-  finalUrl?: string
+  readonly finalUrl?: string;
   /**
    * Base64-encoded PNG screenshot taken after all actions.
    *
    * Populated only when a `PageAction.Screenshot` action actually ran, so
    * callers that never request a screenshot do not pay the encoding cost.
    */
-  screenshotBase64?: string
+  readonly screenshotBase64?: string;
   /**
    * URLs of the requests the page sent during the session that the SSRF policy refused,
    * including during the extra wait, without their credentials, each listed once.
    */
-  ssrfRefusedUrls?: Array<string>
+  readonly ssrfRefusedUrls?: Array<string>;
 }
 
 /** A JSON-LD structured data entry found on a page. */
 export interface JsonLdEntry {
   /** The `@type` value from the JSON-LD object. */
-  schemaType?: string
+  readonly schemaType?: string;
   /** The `name` value, if present. */
-  name?: string
+  readonly name?: string;
   /** The raw JSON-LD string. */
-  raw?: string
+  readonly raw?: string;
 }
 
 /** Information about a link found on a page. */
 export interface LinkInfo {
   /** The resolved URL of the link. */
-  url?: string
+  readonly url?: string;
   /** The visible text of the link. */
-  text?: string
+  readonly text?: string;
   /** The classification of the link. */
-  linkType?: LinkType | 'internal' | 'external' | 'anchor' | 'document'
+  readonly linkType?: LinkType;
   /** The `rel` attribute value, if present. */
-  rel?: string
+  readonly rel?: string;
   /** Whether the link has `rel="nofollow"`. */
-  nofollow?: boolean
+  readonly nofollow?: boolean;
+  /**
+   * Link address resolved against the page's base without changing path spelling.
+   * Percent escapes, Unicode, spaces, backslashes and dot segments are preserved.
+   * URL credentials are removed. <!-- -->
+   */
+  readonly originalUrl?: string;
 }
 
 /** The classification of a link. */
-export declare const enum LinkType {
+export declare enum LinkType {
   /** A link to the same domain. */
-  Internal = 'internal',
+  Internal = "internal",
   /** A link to a different domain. */
-  External = 'external',
-  /** A fragment-only link (e.g., `#section`). */
-  Anchor = 'anchor',
+  External = "external",
+  /** A link into the page it is on: its address without the fragment is the page address (e.g., `#section`). */
+  Anchor = "anchor",
   /** A link to a downloadable document (PDF, DOC, etc.). */
-  Document = 'document'
+  Document = "document",
 }
 
 /** The result of a map operation, containing discovered URLs. */
 export interface MapResult {
   /** The list of discovered URLs. */
-  urls?: Array<JsSitemapUrl>
+  readonly urls?: Array<SitemapUrl>;
 }
 
-/** Discover all pages on a website by following links and sitemaps. */
-export declare function mapUrls(engine: CrawlEngineHandle, url: string): Promise<MapResult>
-
 /** Rich markdown conversion result from HTML processing. */
 export interface MarkdownResult {
   /** Converted markdown text. */
-  content?: string
+  readonly content?: string;
   /** Structured document tree with semantic nodes. */
-  documentStructure?: any
+  readonly documentStructure?: JsonValue;
   /** Extracted tables with structured cell data. */
-  tables?: Array<any>
+  readonly tables?: Array<JsonValue>;
   /** Non-fatal processing warnings. */
-  warnings?: Array<string>
+  readonly warnings?: Array<string>;
   /**
    * Whether citation conversion was applied and produced at least one reference.
    *
@@ -1170,9 +1188,9 @@ export interface MarkdownResult {
    * is available in `content`; the full reference list is accessible via
    * `generate_citations` if needed separately.
    */
-  citations?: boolean
+  readonly citations?: boolean;
   /** Content-filtered markdown optimized for LLM consumption. */
-  fitContent?: string
+  readonly fitContent?: string;
 }
 
 /**
@@ -1181,193 +1199,188 @@ export interface MarkdownResult {
  * Actions are serialized with a `type` tag using camelCase naming,
  * except `ExecuteJs` which is explicitly renamed to `"executeJs"`.
  */
-export interface PageAction {
-  type: string
-  selector?: string
-  text?: string
-  key?: string
-  direction?: JsScrollDirection
-  amount?: number
-  milliseconds?: number
-  fullPage?: boolean
-  script?: string
-}
+export type PageAction =
+  | { type: "click"; selector: string }
+  | { type: "type"; selector: string; text: string }
+  | { type: "press"; key: string }
+  | { type: "scroll"; direction: ScrollDirection; selector: string; amount: number }
+  | { type: "wait"; milliseconds: number; selector: string }
+  | { type: "screenshot"; fullPage: boolean }
+  | { type: "executeJs"; script: string }
+  | { type: "scrape" };
 
 /** Metadata extracted from an HTML page's `<meta>` tags and `<title>` element. */
 export interface PageMetadata {
   /** The page title from the `<title>` element. */
-  title?: string
+  readonly title?: string;
   /** The meta description. */
-  description?: string
+  readonly description?: string;
   /** The canonical URL from `<link rel="canonical">`. */
-  canonicalUrl?: string
+  readonly canonicalUrl?: string;
   /** Keywords from `<meta name="keywords">`. */
-  keywords?: string
+  readonly keywords?: string;
   /** Author from `<meta name="author">`. */
-  author?: string
+  readonly author?: string;
   /** Viewport content from `<meta name="viewport">`. */
-  viewport?: string
+  readonly viewport?: string;
   /** Theme color from `<meta name="theme-color">`. */
-  themeColor?: string
+  readonly themeColor?: string;
   /** Generator from `<meta name="generator">`. */
-  generator?: string
+  readonly generator?: string;
   /** Robots content from `<meta name="robots">`. */
-  robots?: string
+  readonly robots?: string;
   /** The `lang` attribute from the `<html>` element. */
-  htmlLang?: string
+  readonly htmlLang?: string;
   /** The `dir` attribute from the `<html>` element. */
-  htmlDir?: string
+  readonly htmlDir?: string;
   /** Open Graph title. */
-  ogTitle?: string
+  readonly ogTitle?: string;
   /** Open Graph type. */
-  ogType?: string
+  readonly ogType?: string;
   /** Open Graph image URL. */
-  ogImage?: string
+  readonly ogImage?: string;
   /** Open Graph description. */
-  ogDescription?: string
+  readonly ogDescription?: string;
   /** Open Graph URL. */
-  ogUrl?: string
+  readonly ogUrl?: string;
   /** Open Graph site name. */
-  ogSiteName?: string
+  readonly ogSiteName?: string;
   /** Open Graph locale. */
-  ogLocale?: string
+  readonly ogLocale?: string;
   /** Open Graph video URL. */
-  ogVideo?: string
+  readonly ogVideo?: string;
   /** Open Graph audio URL. */
-  ogAudio?: string
+  readonly ogAudio?: string;
   /** Open Graph locale alternates. */
-  ogLocaleAlternates?: Array<string>
+  readonly ogLocaleAlternates?: Array<string>;
   /** Twitter card type. */
-  twitterCard?: string
+  readonly twitterCard?: string;
   /** Twitter title. */
-  twitterTitle?: string
+  readonly twitterTitle?: string;
   /** Twitter description. */
-  twitterDescription?: string
+  readonly twitterDescription?: string;
   /** Twitter image URL. */
-  twitterImage?: string
+  readonly twitterImage?: string;
   /** Twitter site handle. */
-  twitterSite?: string
+  readonly twitterSite?: string;
   /** Twitter creator handle. */
-  twitterCreator?: string
+  readonly twitterCreator?: string;
   /** Dublin Core title. */
-  dcTitle?: string
+  readonly dcTitle?: string;
   /** Dublin Core creator. */
-  dcCreator?: string
+  readonly dcCreator?: string;
   /** Dublin Core subject. */
-  dcSubject?: string
+  readonly dcSubject?: string;
   /** Dublin Core description. */
-  dcDescription?: string
+  readonly dcDescription?: string;
   /** Dublin Core publisher. */
-  dcPublisher?: string
+  readonly dcPublisher?: string;
   /** Dublin Core date. */
-  dcDate?: string
+  readonly dcDate?: string;
   /** Dublin Core type. */
-  dcType?: string
+  readonly dcType?: string;
   /** Dublin Core format. */
-  dcFormat?: string
+  readonly dcFormat?: string;
   /** Dublin Core identifier. */
-  dcIdentifier?: string
+  readonly dcIdentifier?: string;
   /** Dublin Core language. */
-  dcLanguage?: string
+  readonly dcLanguage?: string;
   /** Dublin Core rights. */
-  dcRights?: string
+  readonly dcRights?: string;
   /** Article metadata from `article:*` Open Graph tags. */
-  article?: ArticleMetadata
+  readonly article?: ArticleMetadata;
   /** Hreflang alternate links. */
-  hreflangs?: Array<HreflangEntry>
+  readonly hreflangs?: Array<HreflangEntry>;
   /** Favicon and icon links. */
-  favicons?: Array<FaviconInfo>
+  readonly favicons?: Array<FaviconInfo>;
   /** Heading elements (h1-h6). */
-  headings?: Array<HeadingInfo>
+  readonly headings?: Array<HeadingInfo>;
   /** Computed word count of the page body text. */
-  wordCount?: number
+  readonly wordCount?: number;
 }
 
 /** Proxy configuration for HTTP requests. */
 export interface ProxyConfig {
   /** Proxy URL (e.g. "http://proxy:8080"). <!-- --> */
-  url?: string
+  readonly url?: string;
   /** Optional username for proxy authentication. */
-  username?: string
+  readonly username?: string;
   /** Optional password for proxy authentication. */
-  password?: string
+  readonly password?: string;
 }
 
 /** Response metadata extracted from HTTP headers. */
 export interface ResponseMeta {
   /** The ETag header value. */
-  etag?: string
+  readonly etag?: string;
   /** The Last-Modified header value. */
-  lastModified?: string
+  readonly lastModified?: string;
   /** The Cache-Control header value. */
-  cacheControl?: string
+  readonly cacheControl?: string;
   /** The Server header value. */
-  server?: string
+  readonly server?: string;
   /** The X-Powered-By header value. */
-  xPoweredBy?: string
+  readonly xPoweredBy?: string;
   /** The Content-Language header value. */
-  contentLanguage?: string
+  readonly contentLanguage?: string;
   /** The Content-Encoding header value. */
-  contentEncoding?: string
+  readonly contentEncoding?: string;
 }
 
-/** Scrape a single URL, returning extracted page data. */
-export declare function scrape(engine: CrawlEngineHandle, url: string): Promise<ScrapeResult>
-
 /** The result of a single-page scrape operation. */
 export interface ScrapeResult {
   /** The HTTP status code of the response. */
-  statusCode?: number
+  readonly statusCode?: number;
   /** The final URL after following all redirects. */
-  finalUrl?: string
+  readonly finalUrl?: string;
   /** The Content-Type header value. */
-  contentType?: string
+  readonly contentType?: string;
   /** The HTML body of the response. */
-  html?: string
+  readonly html?: string;
   /** The size of the response body in bytes. */
-  bodySize?: number
+  readonly bodySize?: number;
   /** Extracted metadata from the page. */
-  metadata?: PageMetadata
+  readonly metadata?: PageMetadata;
   /** Links found on the page. */
-  links?: Array<LinkInfo>
+  readonly links?: Array<LinkInfo>;
   /** Images found on the page. */
-  images?: Array<ImageInfo>
+  readonly images?: Array<ImageInfo>;
   /** Feed links found on the page. */
-  feeds?: Array<FeedInfo>
+  readonly feeds?: Array<FeedInfo>;
   /** JSON-LD entries found on the page. */
-  jsonLd?: Array<JsonLdEntry>
+  readonly jsonLd?: Array<JsonLdEntry>;
   /** Whether the URL is allowed by robots.txt. */
-  isAllowed?: boolean
+  readonly isAllowed?: boolean;
   /** The crawl delay from robots.txt, in seconds. */
-  crawlDelay?: number
+  readonly crawlDelay?: number;
   /** Whether a noindex directive was detected. */
-  noindexDetected?: boolean
+  readonly noindexDetected?: boolean;
   /** Whether a nofollow directive was detected. */
-  nofollowDetected?: boolean
+  readonly nofollowDetected?: boolean;
   /** The X-Robots-Tag header values, joined with `, ` when the response sent more than one. */
-  xRobotsTag?: string
+  readonly xRobotsTag?: string;
   /** Whether the content is a PDF. */
-  isPdf?: boolean
+  readonly isPdf?: boolean;
   /** Whether the page was skipped (binary or PDF content). */
-  wasSkipped?: boolean
+  readonly wasSkipped?: boolean;
   /** The detected character set encoding. */
-  detectedCharset?: string
+  readonly detectedCharset?: string;
   /** Whether an authentication header was sent with the request. */
-  authHeaderSent?: boolean
+  readonly authHeaderSent?: boolean;
   /** Response metadata extracted from HTTP headers. */
-  responseMeta?: ResponseMeta
+  readonly responseMeta?: ResponseMeta;
   /** Downloaded assets from the page. */
-  assets?: Array<DownloadedAsset>
+  readonly assets?: Array<DownloadedAsset>;
   /** Whether the page content suggests JavaScript rendering is needed. */
-  jsRenderHint?: boolean
+  readonly jsRenderHint?: boolean;
   /** Whether the browser fallback was used to fetch this page. */
-  browserUsed?: boolean
+  readonly browserUsed?: boolean;
   /** Markdown conversion of the page content. */
-  markdown?: MarkdownResult
+  readonly markdown?: MarkdownResult;
   /** Structured data extracted by LLM. Populated when extraction is configured. */
-  extractedData?: any
+  readonly extractedData?: JsonValue;
   /** Metadata about the LLM extraction pass (cost, tokens, model). */
-  extractionMeta?: ExtractionMeta
+  readonly extractionMeta?: ExtractionMeta;
   /**
    * Base64-encoded PNG screenshot of the page.
    *
@@ -1375,45 +1388,45 @@ export interface ScrapeResult {
    * request, so callers that never requested a screenshot do not pay the
    * encoding cost.
    */
-  screenshotBase64?: string
+  readonly screenshotBase64?: string;
   /** Downloaded non-HTML document (PDF, DOCX, image, code, etc.). */
-  downloadedDocument?: DownloadedDocument
+  readonly downloadedDocument?: DownloadedDocument;
   /**
    * Browser-specific extras (eval result, network events, cookies). Only
    * populated when `BrowserBackend.Native` was used for this request.
    */
-  browser?: BrowserExtras
+  readonly browser?: BrowserExtras;
   /**
    * URLs of the requests the page sent in browser mode that the SSRF policy refused, without
    * their credentials, each listed once. The page is kept; only the refused requests failed.
    */
-  ssrfRefusedUrls?: Array<string>
+  readonly ssrfRefusedUrls?: Array<string>;
 }
 
 /** Direction for a scroll action. */
-export declare const enum ScrollDirection {
+export declare enum ScrollDirection {
   /** Scroll upward. */
-  Up = 'up',
+  Up = "up",
   /** Scroll downward. */
-  Down = 'down'
+  Down = "down",
 }
 
 /** A URL entry from a sitemap. */
 export interface SitemapUrl {
   /** The URL. */
-  url?: string
+  readonly url?: string;
   /** The last modification date, if present. */
-  lastmod?: string
+  readonly lastmod?: string;
   /** The change frequency, if present. */
-  changefreq?: string
+  readonly changefreq?: string;
   /** The priority, if present. */
-  priority?: string
+  readonly priority?: string;
 }
 
 /** SSRF policy configuration. */
 export interface SsrfPolicy {
   /** If true, reject URLs that resolve to private/metadata IP ranges. */
-  denyPrivate?: boolean
+  readonly denyPrivate?: boolean;
   /**
    * Hostnames and IP ranges permitted regardless of `deny_private`, unless a matching
    * address is in `denylist`.
@@ -1433,7 +1446,7 @@ export interface SsrfPolicy {
    * An empty allowlist therefore denies nothing by itself — it simply leaves
    * `deny_private` and the deny-list in sole control.
    */
-  allowlist?: Array<JsHostMatcher>
+  readonly allowlist?: Array<HostMatcher>;
   /**
    * IP ranges refused regardless of `deny_private` and `allowlist`.
    *
@@ -1443,37 +1456,29 @@ export interface SsrfPolicy {
    * and cannot weaken it. A hostname is refused when an upstream proxy or remote browser
    * performs the connection lookup, because that lookup cannot be bound to these checks.
    */
-  denylist?: Array<JsHostMatcher>
+  readonly denylist?: Array<HostMatcher>;
   /** Maximum number of HTTP redirects to follow during validation. */
-  maxRedirects?: number
+  readonly maxRedirects?: number;
   /**
    * Allowed URI schemes. Default: `["http", "https"]`.
    *
    * Only `http` and `https` are supported. An empty list denies every URL.
    */
-  schemeAllowlist?: Array<string>
+  readonly schemeAllowlist?: Array<string>;
 }
 
-export declare function ssrfPolicyDefault(): SsrfPolicy
+/** Discover all pages on a website by following links and sitemaps. */
+export declare function mapUrls(engine: CrawlEngineHandle, url: string): Promise<MapResult>;
 
-/**
- * Create a policy from environment variables.
- *
- * On native platforms, reads `CRAWLBERG_ALLOW_PRIVATE_NETWORK` — if set to "1" or "true"
- * (case-insensitive), sets `deny_private = false`. Otherwise, defaults to `deny_private = true`.
- *
- * On wasm32 targets (browser/Node.js), environment variables are not accessible to the
- * compiled module. Defaults to `deny_private = false` because:
- * - Outbound requests in a browser go through the fetch API, which enforces its own network policies.
- * - Rust-side SSRF checking is unenforceable and redundant in a wasm32 context.
- * - For testing and localhost access, the host's network sandbox is the enforcing boundary.
- *
- * **Node.js caveat:** `deny_private` and `denylist` have no effect on hostname-based requests
- * under `wasm32`. There is no DNS resolution on this target, so `validate_url` only ever
- * checks a literal IP host; a domain name falls straight through to `Ok(())`. In a browser
- * this is covered by same-origin/CORS. Node's `fetch` enforces no CORS, so a Node service
- * embedding this wasm module can be driven to internal hosts by domain name despite the
- * policy. Enforce egress restrictions (network policy, firewall, proxy allowlist) outside
- * the process.
- */
-export declare function ssrfPolicyFromEnv(): SsrfPolicy
+/** Scrape a single URL, returning extracted page data. */
+export declare function scrape(engine: CrawlEngineHandle, url: string): Promise<ScrapeResult>;
+
+export declare class BatchCrawlStreamIterator {
+  next(value?: undefined): Promise<IteratorResult<CrawlEvent, void>>;
+  [Symbol.asyncIterator](): AsyncGenerator<CrawlEvent, void, undefined>;
+}
+
+export declare class CrawlStreamIterator {
+  next(value?: undefined): Promise<IteratorResult<CrawlEvent, void>>;
+  [Symbol.asyncIterator](): AsyncGenerator<CrawlEvent, void, undefined>;
+}