@webability/core 1.7.0 → 1.9.0

package/dist/types-g-bI_MhR.d.cts

@@ -0,0 +1,514 @@
+/**
+ * Rendered-pixel contrast judge for text on a gradient / image / overlapped
+ * background — the cases where axe reports `incomplete` and CSS cannot give a
+ * background colour.
+ *
+ * What the user actually sees behind the glyphs IS measurable: hide every
+ * glyph, screenshot the text's own boxes, and compare the text colour with
+ * the pixels that were behind it.
+ *
+ *   - every pixel fails the threshold  -> the text fails wherever it sits: VIOLATION
+ *   - any pixel passes                 -> the background is not uniformly bad: DROP
+ *     (a mixed gradient is not a confident failure, and never a pass we claim)
+ *
+ * Anything we cannot measure reliably (semi-transparent text, text over
+ * <video>/<canvas>/<iframe>, background-clip:text, transformed or clipped
+ * boxes, no screenshot support) is dropped, never judged.
+ */
+
+interface PixelVerdict {
+    selector: string;
+    fail: boolean;
+    /** Best (highest) contrast ratio found anywhere behind the text. */
+    bestRatio: number;
+    /** Worst (lowest) contrast ratio found anywhere behind the text. */
+    worstRatio: number;
+    /** The background pixel behind the text that gave `worstRatio`, as rgb(r,g,b). */
+    worstBg?: string;
+    /** The background pixel behind the text that gave `bestRatio`, as rgb(r,g,b). */
+    bestBg?: string;
+    threshold: number;
+    fg: string;
+}
+
+/**
+ * AI judge for the undecided set.
+ *
+ * The scanner never hands the user a "needs review" bucket. Findings the
+ * engines could not decide (axe `incomplete`, a detector's `needsReview`)
+ * first go through the deterministic resolvers (rendered-pixel contrast,
+ * captions). What is still undecided after that reaches this judge, which
+ * turns each item into one of:
+ *
+ *   - `violation` + a concrete fix  → promoted into `issues[]`
+ *   - `pass` + a one-line reason    → recorded in `judged[]`, not reported
+ *
+ * Anything the judge cannot settle — no model configured, malformed output,
+ * timeout, a contrast background that cannot be sampled — is DROPPED, exactly
+ * as before. The judge never invents a verdict.
+ *
+ * Deterministic pre-judges run before any model call (declared-decorative
+ * images, images named by their link text, CSS backgrounds outside any
+ * control or on a control that already has a name, motion that a
+ * `prefers-reduced-motion: reduce` rule stops on that element). Contrast items carry a real pixel measurement
+ * (best/worst ratio behind the glyphs, AA threshold for the font size) so the
+ * verdict states a ratio the scanner measured, not one the model guessed.
+ *
+ * Models (local, via an OpenAI-compatible chat endpoint — OpenRouter by
+ * default): vision `anthropic/claude-haiku-4.5`, text-only
+ * `deepseek/deepseek-v4-flash`. Hosted: POST `${apiUrl}/api/judge-incomplete`.
+ */
+
+declare const JUDGE_DEFAULT_TIMEOUT_MS = 20000;
+declare const DEFAULT_JUDGE_BASE_URL = "https://openrouter.ai/api/v1";
+declare const DEFAULT_JUDGE_VISION_MODEL = "anthropic/claude-haiku-4.5";
+declare const DEFAULT_JUDGE_TEXT_MODEL = "deepseek/deepseek-v4-flash";
+type JudgeVerdictKind = 'pass' | 'violation';
+/** One judged finding, as recorded on `ScanResult.judged`. Small on purpose. */
+interface JudgedEntry$1 {
+    id: string;
+    type: string;
+    verdict: JudgeVerdictKind;
+    reason: string;
+}
+/** One undecided finding as sent to the model / hosted endpoint. */
+interface JudgeItem {
+    id: string;
+    type: string;
+    wcag: string;
+    message: string;
+    selector: string;
+    /** outerHTML, ≤400 chars */
+    html: string;
+    /** Computed context: colours/threshold/ratios for contrast, src/alt/link text for images, … */
+    context: Record<string, unknown>;
+    /** PNG, base64 (no data: prefix). Present only on the vision path. */
+    screenshot?: string;
+}
+interface JudgeRequest {
+    url: string;
+    level: WcagLevel;
+    vision: boolean;
+    items: JudgeItem[];
+}
+interface JudgeVerdict {
+    id: string;
+    verdict: JudgeVerdictKind;
+    reason?: string;
+    fix?: {
+        attribute?: string;
+        value?: string;
+    };
+}
+/** Returns the raw model output (a JSON array string) or an already-parsed `{verdicts}` / array. */
+type JudgeTransport = (req: JudgeRequest, signal: AbortSignal) => Promise<unknown>;
+interface JudgeOptions {
+    /** OpenAI-compatible chat-completions key (OpenRouter). Enables the local path. */
+    apiKey?: string;
+    /** Base URL of the chat-completions API. Default https://openrouter.ai/api/v1 */
+    baseUrl?: string;
+    visionModel?: string;
+    textModel?: string;
+    /** Hosted path: WebAbility API origin; POST `${apiUrl}/api/judge-incomplete`. */
+    apiUrl?: string;
+    /** Bearer token for the hosted path. */
+    apiToken?: string;
+    /**
+     * Hosted path only: the shared secret that identifies the hosted MCP server
+     * to the platform (sent as `x-mcp-internal`). Lets the platform judge scans
+     * that carry no user token. Never set on local installs.
+     */
+    internalSecret?: string;
+    /** Total judge budget per scan (all batches). Default 20 000 ms. */
+    timeoutMs?: number;
+    /** Conformance ceiling: only criteria at or below this level are promoted. Default AA. */
+    level?: WcagLevel;
+    /** false = HTML/text only (scan_html, DOM path). Default: screenshots when the page can take them. */
+    vision?: boolean;
+    /** Test / custom model injection. Wins over apiKey/apiUrl. */
+    transport?: JudgeTransport;
+    /**
+     * Largest element crop (base64 chars) to send. Default: JUDGE_MAX_CROP_CHARS on
+     * the hosted path (the endpoint answers 413 above it, PNG only), none elsewhere.
+     */
+    maxCropChars?: number;
+}
+interface JudgeRunOptions extends JudgeOptions {
+    url: string;
+    /** Pixel measurements already taken by the contrast resolver (by selector). */
+    measured?: Map<string, PixelVerdict>;
+}
+interface JudgeOutcome {
+    /** Verdict=violation, now confirmed findings with a fix. Not yet deduped against `issues`. */
+    promoted: ScanIssue[];
+    /** Every verdict reached (pass and violation), id = the original finding id. */
+    judged: JudgedEntry$1[];
+}
+declare function resetJudgeCache(): void;
+/** The judge's system prompt. Exported so a server-side judge (platform /api/judge-incomplete) sends the same rules, not a copy. */
+declare const JUDGE_SYSTEM_PROMPT = "You are the final accessibility judge for a WCAG scanner. Automated engines could not decide the findings below. You MUST decide each one: \"pass\" (not a violation) or \"violation\". There is no third option \u2014 never answer \"unsure\", never defer to a human.\n\nRules:\n- Images (1.1.1): \"pass\" when the image is decorative, purely presentational, a spacer/tracking pixel, or is named by the text of its enclosing link/button. Otherwise \"violation\" with fix.attribute=\"alt\" and a concrete alt text written from the image and its context: \u2264125 characters, no \"image of\"/\"picture of\" prefix, no file names.\n- CSS background images (1.1.1) on a control with no accessible name (context.control.accessibleName is empty): the image is the control's only content, so \"violation\" with fix.value = a short name for what the control does, written from the crop and nearby text (\u2264125 characters, no \"image of\"). \"pass\" only if the control is clearly not meant to be operated.\n- Images of text (1.4.5): logos, wordmarks and brand signatures are exempt \u2192 \"pass\". Essential informational text rendered as an image \u2192 \"violation\".\n- Text contrast (1.4.3 / 1.4.6): you receive the text colour, the required ratio for its font size, and the best/worst measured ratio behind the glyphs plus a crop. \"violation\" when the text is not readable at the required ratio over a meaningful part of its background; then fix.attribute=\"style\" and fix.value = a 6-digit hex text colour that meets the ratio against the background's dominant colour. \"pass\" when the text clearly meets the ratio everywhere the glyphs sit.\n- Link purpose (2.4.4): the context is the link text plus its sentence, paragraph, list item or table cell (nearbyText). \"pass\" when the text names the destination page or topic (Home, About, Info, Contact, Pricing, a product or article name), even as a single word in a site menu. \"violation\" only for generic text that names no destination (here, click here, more, read more, learn more, link) when that context does not supply it.\n- Dead in-page link (2.4.1): the item is an <a href=\"#fragment\"> near the top of the page whose fragment matches no id or <a name> (context.engineNote names it). WCAG 2.4.1 is about bypassing repeated blocks. \"violation\" only when the link is the page's bypass mechanism (a skip link that should jump past the header or navigation) and its target is missing, so activating it goes nowhere. Any other dead fragment link is \"pass\" for 2.4.1: an ordinary or script-driven link (tab, accordion, modal or menu trigger, back-to-top).\n- Form with no submit control (3.2.2): the item is a <form> with visible fields and no submit button, input type=submit/image or outside button. \"violation\" only when changing a field or pressing Enter causes an unexpected change of context (navigation, submission, reload) and no submit control exists to ask for it. \"pass\" for a script-driven form, a single search box, or a form whose fields change nothing until the user acts.\n- Decorative image with a title (1.1.1): the item is an <img alt=\"\"> that also has a non-empty title (context.engineNote gives it). \"violation\" when the picture conveys information the title names (a logo, chart, labelled icon, photo of a named subject), so the empty alt hides it. \"pass\" when the picture is purely decorative and the title only repeats nearby text or adds nothing. Do not write alt text for this item.\n- Non-text contrast (1.4.11), motion (2.2.2 / 2.3.3), duplicate ids, ARIA references, captions and everything else: decide from the markup, the context and the crop. For a \"violation\", give fix.attribute/fix.value only when you are certain of the exact value.\n- Be strict: \"pass\" only when confident the finding is not a real barrier.\n\nRespond with ONLY a JSON array, one object per item, same ids:\n[{\"id\": \"...\", \"verdict\": \"pass\" | \"violation\", \"reason\": \"one sentence\", \"fix\": {\"attribute\": \"...\", \"value\": \"...\"}}]\nOmit \"fix\" for passes.";
+interface JudgeChatBody {
+    model: string;
+    temperature: number;
+    max_tokens: number;
+    reasoning?: {
+        enabled: false;
+    };
+    messages: Array<{
+        role: 'system' | 'user';
+        content: unknown;
+    }>;
+}
+/**
+ * The chat-completions body for one judge batch: the vision model only when the
+ * batch is a vision batch AND carries a crop (crops as image_url parts), else the
+ * text model. `disableTextModelReasoning`: the default text model reasons unless
+ * told not to, and on a real 30-item batch spent all 4096 tokens reasoning (no
+ * verdicts, 48 s); set it only for endpoints that accept the `reasoning` field.
+ */
+declare function buildJudgeChatBody(req: JudgeRequest, cfg?: {
+    visionModel?: string;
+    textModel?: string;
+    disableTextModelReasoning?: boolean;
+}): JudgeChatBody;
+/** OpenAI-compatible chat completions (OpenRouter). Vision → image_url parts; text-only → text model. */
+declare function openAiCompatibleTransport(cfg: {
+    apiKey: string;
+    baseUrl?: string;
+    visionModel?: string;
+    textModel?: string;
+}): JudgeTransport;
+/**
+ * Hosted path: the platform judges on the server. Request body = JudgeRequest;
+ * response = `{ verdicts: JudgeVerdict[] }`. Any non-2xx → items stay dropped.
+ * The platform answers only a user bearer or the hosted MCP's `x-mcp-internal`.
+ */
+declare function hostedJudgeTransport(cfg: {
+    apiUrl: string;
+    token?: string;
+    internalSecret?: string;
+}): JudgeTransport;
+declare function judgeUndecided(page: PageLike | null, undecided: readonly ScanIssue[], opts: JudgeRunOptions): Promise<JudgeOutcome>;
+
+/**
+ * @webability/core — type definitions
+ */
+/**
+ * Minimal page interface satisfied by both Playwright and Puppeteer.
+ * No runtime wrapper needed — both libraries implement these methods natively.
+ */
+interface PageLike {
+    evaluate<R>(pageFunction: string | ((...args: any[]) => R | Promise<R>), ...args: any[]): Promise<R>;
+    addScriptTag(options: {
+        content: string;
+    }): Promise<unknown>;
+    url(): string;
+    /**
+     * Real keyboard event dispatch (Playwright & Puppeteer both expose this).
+     * Optional so minimal PageLike shims still typecheck. The focusVisible
+     * detector uses `keyboard.press('Tab')` to put the browser into keyboard
+     * interaction modality before probing focus styles — otherwise
+     * `:focus-visible` / keyboard-detection-class patterns (focus-visible
+     * polyfill, `.user-is-tabbing` body class) never activate under a bare
+     * programmatic `.focus()`, producing mass false positives.
+     */
+    keyboard?: {
+        press(key: string): Promise<void>;
+    };
+}
+/** All fix issue types the pipeline can detect and fix. */
+type FixIssueType = 'weak_button_name' | 'weak_link_name' | 'weak_heading' | 'weak_iframe_title' | 'weak_page_title' | 'weak_svg_name' | 'weak_skip_link' | 'missing_button_role' | 'missing_semantic_role' | 'missing_document_language' | 'missing_landmark' | 'svg_missing_name' | 'aria_hidden_focusable' | 'adjacent_redundant_link' | 'contrast_insufficient' | 'non_text_contrast_insufficient' | 'target_too_small' | 'focus_not_visible' | 'empty_link' | 'unlabeled_button' | 'missing_label' | 'decorative_icon' | 'skip_link' | 'aria_live' | 'missing_alt' | 'identify_input_purpose' | 'redundant_role' | 'duplicate_id' | 'new_window_link' | 'missing_fieldset_legend' | 'missing_table_header' | 'missing_table_caption' | 'missing_table_scope' | 'external_link_warning' | 'download_link_warning' | 'broken_anchor' | 'form_missing_submit' | 'decorative_image_with_title' | 'placeholder_link' | 'missing_pattern_title' | 'missing_autocomplete' | 'missing_media_controls' | 'unsafe_autoplay' | 'zoom_restriction' | 'missing_button_type' | 'link_consistency' | 'keyboard_trap' | 'focus_order_disruption' | 'missing_captions' | 'color_only_link' | 'label_in_name' | 'onfocus_context_change' | 'focus_obscured_by_sticky' | 'text_spacing_blocked' | 'nested_landmark' | 'motion_uncontrollable' | 'auto_refresh' | 'motion_without_reduced_motion' | 'flashing_content' | 'animated_gif_no_pause' | 'missing_required_indicator' | 'background_image_unlabeled' | 'empty_heading' | 'javascript_link' | 'broken_aria_reference' | 'main_content_hidden' | 'scrollable_not_focusable' | 'meaningful_sequence' | 'sensory_characteristic' | 'image_of_text' | 'reflow_overflow' | 'missing_audio_description' | 'missing_transcript' | 'character_key_shortcut' | 'on_input_change' | 'pointer_gesture' | 'pointer_cancellation' | 'motion_actuation' | 'error_prevention_missing' | 'inconsistent_navigation';
+/** WCAG criterion for each issue type. */
+declare const WCAG_BY_ISSUE: Record<FixIssueType, string>;
+/** A single accessibility issue detected on the page. */
+interface DetectedIssue {
+    /** Unique CSS selector targeting the element. */
+    selector: string;
+    /** HTML/ARIA attribute to set (alt, aria-label, role, tabindex, etc.) */
+    attribute: string;
+    /** What the element currently has (empty string if missing). */
+    currentValue: string;
+    /** Classification of the issue. */
+    issueType: FixIssueType;
+    /** WCAG success criterion reference. */
+    wcag: string;
+    /** Contextual info for Claude: nearby heading, parent tag, href, page section. */
+    context: string;
+    /** true = needs Claude to generate the fix value; false = rule already knows it. */
+    needsAI: boolean;
+    /** When needsAI is false, this is the known fix value. */
+    fixValue?: string;
+    /** Optional: image src for alt text generation via vision. */
+    imageSrc?: string;
+    /** Optional: outer HTML snippet (first 300 chars) for Claude context. */
+    outerHtml?: string;
+    /**
+     * Detector-side signal that the VERDICT is uncertain (e.g. contrast against
+     * a gradient). The scanner never reports such a finding: it is resolved to a
+     * verdict by an engine resolver or dropped. For "verdict certain, fix not
+     * mechanical" use `manualFix`.
+     */
+    needsReview?: boolean;
+    /**
+     * The verdict is certain but the suggested fix cannot be applied
+     * mechanically. Sets `fix.needsManualReview`; never changes the verdict.
+     */
+    manualFix?: boolean;
+    /** Why this finding needs review — surfaced to MCP/SDK consumers. */
+    reviewReason?: string;
+    /**
+     * Optional exact user-facing message. Use when the generic
+     * attribute/currentValue template ("missing X", "X is \"Y\"") would state
+     * something false or fabricated — e.g. a weak button name whose name comes
+     * from text content has no missing aria-label to report (persona round 3,
+     * P069: 'weak button name: missing aria-label' on a named control).
+     * formatMessage prefers this verbatim when present.
+     */
+    message?: string;
+}
+/** Every fix detector must implement this interface. */
+interface FixDetector {
+    name: string;
+    detect(page: PageLike): Promise<DetectedIssue[]>;
+    /** Per-page emission cap, when the detector has one. When a run returns
+     *  >= cap findings the results are TRUNCATED (DOM-order biased) and the
+     *  scan reports it via ScanResult.truncated — silent truncation reads as
+     *  "covered everything" when it didn't (loop iter8 / honesty infra). */
+    cap?: number;
+}
+/**
+ * Browser-runtime detector signature.
+ *
+ * Each detector exports a pure, zero-argument browser function that uses the
+ * `document` global directly and returns DetectedIssue[]. No Puppeteer, no
+ * Node imports, no closures over module-scope variables — so it both:
+ *   1. Survives serialization via `page.evaluate(fn)` on the server (puppeteer
+ *      stringifies and re-parses the function inside the browser context).
+ *   2. Bundles directly into the widget via webpack and runs against the
+ *      live customer DOM.
+ *
+ * Single source of truth — same rules run in both runtimes.
+ */
+type BrowserDetector = () => DetectedIssue[];
+interface SiteTheme {
+    cssVars: Record<string, string>;
+    topBgColors: Array<{
+        color: string;
+        count: number;
+    }>;
+    topTextColors: Array<{
+        color: string;
+        count: number;
+    }>;
+}
+type IssueSource = 'webability' | 'axe-core' | 'deep-analysis';
+type IssueImpact = 'critical' | 'serious' | 'moderate' | 'minor';
+type WcagLevel = 'A' | 'AA' | 'AAA';
+/**
+ * Internal confidence marker. `needs_review` means an engine could not decide
+ * (text on a gradient, marketing imagery that may be a logo, …). Such findings
+ * never reach the result: the pixel/caption resolvers and the AI judge turn
+ * them into a verdict, or they are dropped. No reported issue carries it.
+ */
+type IssueConfidence = 'high' | 'needs_review';
+interface ScanIssue {
+    id: string;
+    source: IssueSource;
+    type: FixIssueType | string;
+    wcag: string;
+    level: WcagLevel;
+    impact: IssueImpact;
+    message: string;
+    selector: string;
+    html?: string;
+    /** Internal: set by an engine that could not decide; stripped before the result. */
+    confidence?: IssueConfidence;
+    /** Internal: why the engine could not decide; handed to the judge as context, never reported. */
+    reviewReason?: string;
+    fix?: {
+        attribute: string;
+        currentValue: string;
+        suggestedValue?: string;
+        needsManualReview: boolean;
+    };
+}
+/**
+ * Signal that the scan never reached the intended page — the target served a
+ * bot-challenge / interstitial (Cloudflare "Just a moment…", "Access Denied",
+ * a CAPTCHA wall) or the main document returned an HTTP error status. When
+ * present, `issues`/`incomplete` are empty and MUST NOT be read as "the page is
+ * clean": nothing real was scanned. Lets a caller distinguish "scanned and
+ * clean" from "was never actually scanned".
+ */
+interface BlockedInfo {
+    /** Human-readable explanation of why the page could not be scanned. */
+    reason: string;
+    /** Challenge vendor when identifiable (e.g. 'Cloudflare', 'PerimeterX/HUMAN'). */
+    vendor?: string;
+    /** HTTP status of the main document response, when known. */
+    status?: number;
+    /** The specific signal that matched (page title, marker selector, or status). */
+    signal?: string;
+}
+/** One judged finding — see `ScanResult.judged`. */
+interface JudgedEntry {
+    id: string;
+    type: string;
+    verdict: 'pass' | 'violation';
+    reason: string;
+}
+/**
+ * A finding or a page change the scanner's own tooling caused (invariant P).
+ * Gate metric, bar = 0: any entry means the scan measured our state, not the page.
+ * - state-not-restored: a tool left focus / focus-visible / scroll / selection /
+ *   injected nodes changed (the scanner restored it)
+ * - finding-dropped: a finding sat on an injected (marked) node or on an
+ *   element a tool left focused; it was not reported
+ */
+interface InternalBug {
+    tool: string;
+    kind: 'state-not-restored' | 'finding-dropped';
+    detail: string;
+    selector?: string;
+    /**
+     * Diagnosis only: what the page DOM did inside this tool's window (the
+     * mutation-log slice). Pages mutate themselves, so this is never used to
+     * attribute a finding; it is there so a bug is traceable. Capped.
+     */
+    mutations?: Array<{
+        type: string;
+        attr?: string | null;
+        target: string;
+        added: string[];
+    }>;
+}
+interface ScanResult {
+    url: string;
+    timestamp: string;
+    /**
+     * Set when the target served a bot-challenge/interstitial or an HTTP error
+     * instead of the real page. When present, treat `issues`/`incomplete` as
+     * "not scanned" (they are empty), NOT as "no problems found".
+     */
+    blocked?: BlockedInfo;
+    /** High-confidence violations. Safe to surface as bugs. */
+    issues: ScanIssue[];
+    /** Detectors that hit their per-page cap this run — their counts are lower
+     *  bounds, not a census. Additive field; absent = nothing truncated. */
+    truncated?: Array<{
+        detector: string;
+        cap: number;
+    }>;
+    /**
+     * Non-fatal engine subsystem failures that silently disable a category of
+     * checks. Consumers MUST surface these to the user — a result with
+     * `engineWarnings` is NOT a full scan. Currently: `'color:kernel-injection-failed'`
+     * disables all contrast checks for the page. Absent = all subsystems healthy.
+     */
+    engineWarnings?: string[];
+    /**
+     * Undecided findings dropped with no verdict: no resolver measurement, no
+     * model-free rule and no judge verdict (judge off, failed or silent). For
+     * these criteria an absent issue is NOT evidence of a pass. Absent = every
+     * undecided finding within the level got a verdict.
+     */
+    unsettled?: {
+        count: number;
+        wcag: string[];
+    };
+    /** Invariant P: findings / page changes caused by our own tooling. Always present; `[]` = clean. */
+    internal_bugs?: InternalBug[];
+    /** Engine (core package) version that produced this result — provenance */
+    engine?: string;
+    /**
+     * @deprecated Always `[]`. The scanner judges uncertain findings itself:
+     * each becomes a verdict in `issues` or is dropped. The field stays only so
+     * existing consumers that read it keep compiling.
+     */
+    incomplete: ScanIssue[];
+    /**
+     * Verdicts on findings the engines could not decide: model-free rules (a
+     * measured contrast pass, a decorative or 1x1 image, a reduced-motion rule)
+     * and, when configured, the AI judge. `pass` = cleared with a reason,
+     * `violation` = promoted into `issues`. Absent when nothing got a verdict.
+     */
+    judged?: JudgedEntry[];
+    summary: {
+        total: number;
+        critical: number;
+        serious: number;
+        moderate: number;
+        minor: number;
+        /** @deprecated Always 0 — there is no incomplete bucket. */
+        incomplete: number;
+    };
+    axeResults?: unknown;
+}
+type ViewportPreset = 'mobile' | 'tablet' | 'desktop';
+declare const VIEWPORT_SIZES: Record<ViewportPreset, {
+    width: number;
+    height: number;
+}>;
+interface ScanOptions {
+    wcagTags?: string[];
+    /** @internal test seam: extra detectors run serially, each in its own state guard. */
+    extraSerialDetectors?: FixDetector[];
+    /**
+     * Highest WCAG conformance level to report. Default 'AA': findings whose
+     * criteria are all Level AAA are not reported anywhere (issues, incomplete,
+     * summary). 'AAA' opts in (and adds axe's wcag2aaa rules); 'A' keeps Level A only.
+     */
+    level?: WcagLevel;
+    /**
+     * Run axe-core (default true). axe is the only engine for the checks it
+     * covers on the ACT test suite: form-field / select / combobox names and
+     * valid ARIA roles have no WebAbility detector. false = detector-only scan
+     * without those checks.
+     */
+    includeAxe?: boolean;
+    deep?: boolean;
+    deepApiUrl?: string;
+    deepApiKey?: string;
+    dismissModals?: boolean;
+    viewport?: ViewportPreset | {
+        width: number;
+        height: number;
+    };
+    browser?: {
+        headless?: boolean;
+        timeout?: number;
+    };
+    review?: boolean;
+    /** Limit scan to elements within this CSS selector. */
+    rootSelector?: string;
+    /** Include annotated screenshots of violations in results. */
+    enableScreenshots?: boolean;
+    /** Scan content inside iframes. Default: false. */
+    includeIframes?: boolean;
+    /**
+     * Wait for entrance animations to finish before scanning (prevents false
+     * contrast failures on mid-fade text). `false` disables, a number sets the
+     * wait cap in ms. Default: enabled with a 4000ms cap.
+     */
+    settle?: boolean | number;
+    /**
+     * HTTP status of the main-document response, for the Page-object call shape
+     * where the CALLER navigated (e.g. mcp's flow_scan does its own `page.goto`).
+     * The URL-string path captures this itself; on the Page path core cannot see
+     * the response, so a plain 4xx/5xx error page with no challenge DOM markers
+     * would otherwise be scanned as a clean page. Pass the caller's
+     * `response.status()` here so bot-challenge/error-page detection works
+     * uniformly across both entrypoints. Ignored on the URL-string path.
+     */
+    mainStatus?: number;
+    /**
+     * AI judge for findings the engines could not decide. With a model key
+     * (local, OpenRouter-compatible) or `apiUrl` (hosted), each such finding
+     * becomes a verdict: a violation with a fix in `issues`, or a recorded pass
+     * in `judged`. Unset / empty = no model calls: only the model-free verdicts
+     * run, and findings they cannot settle are dropped (listed in `unsettled`).
+     */
+    judge?: JudgeOptions;
+}
+
+export { type BrowserDetector as B, type DetectedIssue as D, type FixDetector as F, type InternalBug as I, JUDGE_DEFAULT_TIMEOUT_MS as J, type PageLike as P, type ScanOptions as S, VIEWPORT_SIZES as V, type WcagLevel as W, type ScanResult as a, type SiteTheme as b, type ScanIssue as c, DEFAULT_JUDGE_BASE_URL as d, DEFAULT_JUDGE_TEXT_MODEL as e, DEFAULT_JUDGE_VISION_MODEL as f, type FixIssueType as g, type IssueImpact as h, type IssueSource as i, JUDGE_SYSTEM_PROMPT as j, type JudgeChatBody as k, type JudgeItem as l, type JudgeOptions as m, type JudgeRequest as n, type JudgeTransport as o, type JudgeVerdict as p, type JudgedEntry as q, type ViewportPreset as r, WCAG_BY_ISSUE as s, buildJudgeChatBody as t, hostedJudgeTransport as u, judgeUndecided as v, openAiCompatibleTransport as w, resetJudgeCache as x };