@webability/core 1.2.1 → 1.3.1

package/dist/index.d.cts

@@ -1,238 +1,5 @@
-/**
- * @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_landmark' | 'heading_skip' | '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' | 'placeholder_link' | 'missing_aria_required' | 'missing_pattern_title' | 'missing_autocomplete' | 'missing_media_controls' | 'unsafe_autoplay' | 'invalid_aria_role' | 'zoom_restriction' | 'missing_button_type' | 'link_consistency' | 'semantic_emphasis' | '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' | 'combobox_name_missing' | 'landmark_duplicate_unlabeled' | 'motion_uncontrollable' | 'auto_refresh' | 'motion_without_reduced_motion' | 'flashing_content' | 'animated_gif_no_pause' | 'missing_required_indicator' | 'background_image_unlabeled' | 'missing_h1' | 'multiple_h1' | 'empty_heading' | 'javascript_link' | 'broken_aria_reference' | 'main_content_hidden' | 'scrollable_not_focusable' | 'meaningful_sequence' | 'sensory_characteristic' | 'orientation_lock' | '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' | 'insufficient_navigation' | '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 finding is ambiguous and should land in
-     * `ScanResult.incomplete[]` (e.g. contrast against a gradient). The scanner
-     * propagates this to ScanIssue.confidence so the confidence classifier
-     * doesn't have to reverse-engineer the situation from HTML strings.
-     */
-    needsReview?: boolean;
-    /** Why this finding needs review — surfaced to MCP/SDK consumers. */
-    reviewReason?: 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';
-/**
- * Confidence tier for a scan finding. Mirrors axe-core's three-tier output —
- * `high` is a confirmed violation safe to act on; `needs_review` is ambiguous
- * (e.g. text on a gradient background, mid-animation opacity, marketing imagery
- * that may legitimately contain text). Consumers should never auto-apply fixes
- * to `needs_review` findings — they belong in the `incomplete[]` bucket and
- * require human judgment.
- */
-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;
-    /** When set, this issue is ambiguous and lives in `ScanResult.incomplete[]`. */
-    confidence?: IssueConfidence;
-    /** Why the classifier demoted this issue. Surfaced to MCP/SDK consumers. */
-    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;
-}
-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[];
-    /** Engine (core package) version that produced this result — provenance */
-    engine?: string;
-    /**
-     * Findings the classifier or axe-core flagged as ambiguous. Show to the user
-     * for review — never auto-fix. Empty array (not omitted) when no incompletes,
-     * so consumers can rely on the field.
-     */
-    incomplete: ScanIssue[];
-    summary: {
-        total: number;
-        critical: number;
-        serious: number;
-        moderate: number;
-        minor: number;
-        /** Count of items in `incomplete[]`. */
-        incomplete: number;
-    };
-    axeResults?: unknown;
-}
-type ViewportPreset = 'mobile' | 'tablet' | 'desktop';
-declare const VIEWPORT_SIZES: Record<ViewportPreset, {
-    width: number;
-    height: number;
-}>;
-interface ScanOptions {
-    wcagTags?: string[];
-    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;
-}
+import { P as PageLike, a as ScanOptions, S as ScanResult, b as SiteTheme, D as DetectedIssue, c as ScanIssue } from './types-10iqML3X.cjs';
+export { B as BrowserDetector, F as FixDetector, d as FixIssueType, I as IssueImpact, e as IssueSource, V as VIEWPORT_SIZES, f as ViewportPreset, W as WCAG_BY_ISSUE, g as WcagLevel } from './types-10iqML3X.cjs';
 
 declare function scan(target: string | PageLike, options?: ScanOptions): Promise<ScanResult>;
 
@@ -246,7 +13,17 @@ type TruncationEntry = {
  * injection blocked by CSP) that silently disable a category of checks.
  * Both arrays are per-invocation (caller-owned), never module state.
  */
-declare function runDetectors(page: PageLike, outTruncated?: TruncationEntry[], outWarnings?: string[]): Promise<DetectedIssue[]>;
+interface RunDetectorsOptions {
+    /**
+     * Skip the two serial FOCUS-MUTATING detectors (focusVisible moves real
+     * focus element-by-element; focusObscured scrolls anchor targets). Set by
+     * DOM-mode consumers scanning a page the user is LOOKING AT — stealing
+     * focus and scrolling their live tab is not acceptable there, and without
+     * page.keyboard those checks mostly land in needs-review anyway.
+     */
+    skipFocusMutating?: boolean;
+}
+declare function runDetectors(page: PageLike, outTruncated?: TruncationEntry[], outWarnings?: string[], options?: RunDetectorsOptions): Promise<DetectedIssue[]>;
 declare function extractSiteTheme(page: PageLike): Promise<SiteTheme>;
 
 interface AxeViolation {
@@ -348,4 +125,4 @@ interface DevSuggestion {
 }
 declare function generateDevSuggestion(issue: ScanIssue, framework: Framework, elementClasses?: string, fgColor?: string, bgColor?: string): DevSuggestion;
 
-export { type BrowserDetector, type ContrastSuggestion, type DetectedIssue, type DevSuggestion, type FixDetector, type FixIssueType, type Framework, type FrameworkInfo, type IssueImpact, type IssueSource, type PageLike, type ScanIssue, type ScanOptions, type ScanResult, type SiteTheme, type TailwindSuggestion, VIEWPORT_SIZES, type ViewportPreset, WCAG_BY_ISSUE, type WcagLevel, detectFramework, dismissModals, extractSiteTheme, generateDevSuggestion, getContrastRatio, runAxe, runDetectors, scan, solveContrast, suggestTailwindFix, toHtmlReport };
+export { type ContrastSuggestion, DetectedIssue, type DevSuggestion, type Framework, type FrameworkInfo, PageLike, ScanIssue, ScanOptions, ScanResult, SiteTheme, type TailwindSuggestion, detectFramework, dismissModals, extractSiteTheme, generateDevSuggestion, getContrastRatio, runAxe, runDetectors, scan, solveContrast, suggestTailwindFix, toHtmlReport };

package/dist/index.d.ts

@@ -1,238 +1,5 @@
-/**
- * @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_landmark' | 'heading_skip' | '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' | 'placeholder_link' | 'missing_aria_required' | 'missing_pattern_title' | 'missing_autocomplete' | 'missing_media_controls' | 'unsafe_autoplay' | 'invalid_aria_role' | 'zoom_restriction' | 'missing_button_type' | 'link_consistency' | 'semantic_emphasis' | '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' | 'combobox_name_missing' | 'landmark_duplicate_unlabeled' | 'motion_uncontrollable' | 'auto_refresh' | 'motion_without_reduced_motion' | 'flashing_content' | 'animated_gif_no_pause' | 'missing_required_indicator' | 'background_image_unlabeled' | 'missing_h1' | 'multiple_h1' | 'empty_heading' | 'javascript_link' | 'broken_aria_reference' | 'main_content_hidden' | 'scrollable_not_focusable' | 'meaningful_sequence' | 'sensory_characteristic' | 'orientation_lock' | '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' | 'insufficient_navigation' | '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 finding is ambiguous and should land in
-     * `ScanResult.incomplete[]` (e.g. contrast against a gradient). The scanner
-     * propagates this to ScanIssue.confidence so the confidence classifier
-     * doesn't have to reverse-engineer the situation from HTML strings.
-     */
-    needsReview?: boolean;
-    /** Why this finding needs review — surfaced to MCP/SDK consumers. */
-    reviewReason?: 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';
-/**
- * Confidence tier for a scan finding. Mirrors axe-core's three-tier output —
- * `high` is a confirmed violation safe to act on; `needs_review` is ambiguous
- * (e.g. text on a gradient background, mid-animation opacity, marketing imagery
- * that may legitimately contain text). Consumers should never auto-apply fixes
- * to `needs_review` findings — they belong in the `incomplete[]` bucket and
- * require human judgment.
- */
-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;
-    /** When set, this issue is ambiguous and lives in `ScanResult.incomplete[]`. */
-    confidence?: IssueConfidence;
-    /** Why the classifier demoted this issue. Surfaced to MCP/SDK consumers. */
-    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;
-}
-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[];
-    /** Engine (core package) version that produced this result — provenance */
-    engine?: string;
-    /**
-     * Findings the classifier or axe-core flagged as ambiguous. Show to the user
-     * for review — never auto-fix. Empty array (not omitted) when no incompletes,
-     * so consumers can rely on the field.
-     */
-    incomplete: ScanIssue[];
-    summary: {
-        total: number;
-        critical: number;
-        serious: number;
-        moderate: number;
-        minor: number;
-        /** Count of items in `incomplete[]`. */
-        incomplete: number;
-    };
-    axeResults?: unknown;
-}
-type ViewportPreset = 'mobile' | 'tablet' | 'desktop';
-declare const VIEWPORT_SIZES: Record<ViewportPreset, {
-    width: number;
-    height: number;
-}>;
-interface ScanOptions {
-    wcagTags?: string[];
-    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;
-}
+import { P as PageLike, a as ScanOptions, S as ScanResult, b as SiteTheme, D as DetectedIssue, c as ScanIssue } from './types-10iqML3X.js';
+export { B as BrowserDetector, F as FixDetector, d as FixIssueType, I as IssueImpact, e as IssueSource, V as VIEWPORT_SIZES, f as ViewportPreset, W as WCAG_BY_ISSUE, g as WcagLevel } from './types-10iqML3X.js';
 
 declare function scan(target: string | PageLike, options?: ScanOptions): Promise<ScanResult>;
 
@@ -246,7 +13,17 @@ type TruncationEntry = {
  * injection blocked by CSP) that silently disable a category of checks.
  * Both arrays are per-invocation (caller-owned), never module state.
  */
-declare function runDetectors(page: PageLike, outTruncated?: TruncationEntry[], outWarnings?: string[]): Promise<DetectedIssue[]>;
+interface RunDetectorsOptions {
+    /**
+     * Skip the two serial FOCUS-MUTATING detectors (focusVisible moves real
+     * focus element-by-element; focusObscured scrolls anchor targets). Set by
+     * DOM-mode consumers scanning a page the user is LOOKING AT — stealing
+     * focus and scrolling their live tab is not acceptable there, and without
+     * page.keyboard those checks mostly land in needs-review anyway.
+     */
+    skipFocusMutating?: boolean;
+}
+declare function runDetectors(page: PageLike, outTruncated?: TruncationEntry[], outWarnings?: string[], options?: RunDetectorsOptions): Promise<DetectedIssue[]>;
 declare function extractSiteTheme(page: PageLike): Promise<SiteTheme>;
 
 interface AxeViolation {
@@ -348,4 +125,4 @@ interface DevSuggestion {
 }
 declare function generateDevSuggestion(issue: ScanIssue, framework: Framework, elementClasses?: string, fgColor?: string, bgColor?: string): DevSuggestion;
 
-export { type BrowserDetector, type ContrastSuggestion, type DetectedIssue, type DevSuggestion, type FixDetector, type FixIssueType, type Framework, type FrameworkInfo, type IssueImpact, type IssueSource, type PageLike, type ScanIssue, type ScanOptions, type ScanResult, type SiteTheme, type TailwindSuggestion, VIEWPORT_SIZES, type ViewportPreset, WCAG_BY_ISSUE, type WcagLevel, detectFramework, dismissModals, extractSiteTheme, generateDevSuggestion, getContrastRatio, runAxe, runDetectors, scan, solveContrast, suggestTailwindFix, toHtmlReport };
+export { type ContrastSuggestion, DetectedIssue, type DevSuggestion, type Framework, type FrameworkInfo, PageLike, ScanIssue, ScanOptions, ScanResult, SiteTheme, type TailwindSuggestion, detectFramework, dismissModals, extractSiteTheme, generateDevSuggestion, getContrastRatio, runAxe, runDetectors, scan, solveContrast, suggestTailwindFix, toHtmlReport };