@webability/core 1.1.3 → 1.2.0

package/dist/index.d.cts

@@ -11,6 +11,18 @@ interface PageLike {
         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';
@@ -52,6 +64,11 @@ interface DetectedIssue {
 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.
@@ -111,11 +128,50 @@ interface ScanIssue {
         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,
@@ -160,11 +216,37 @@ interface ScanOptions {
     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;
 }
 
 declare function scan(target: string | PageLike, options?: ScanOptions): Promise<ScanResult>;
 
-declare function runDetectors(page: PageLike): Promise<DetectedIssue[]>;
+type TruncationEntry = {
+    detector: string;
+    cap: number;
+};
+/**
+ * `outTruncated` collects which detectors hit their per-page cap THIS call.
+ * `outWarnings` collects non-fatal engine subsystem failures (e.g. kernel
+ * 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[]>;
 declare function extractSiteTheme(page: PageLike): Promise<SiteTheme>;
 
 interface AxeViolation {

package/dist/index.d.ts

@@ -11,6 +11,18 @@ interface PageLike {
         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';
@@ -52,6 +64,11 @@ interface DetectedIssue {
 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.
@@ -111,11 +128,50 @@ interface ScanIssue {
         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,
@@ -160,11 +216,37 @@ interface ScanOptions {
     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;
 }
 
 declare function scan(target: string | PageLike, options?: ScanOptions): Promise<ScanResult>;
 
-declare function runDetectors(page: PageLike): Promise<DetectedIssue[]>;
+type TruncationEntry = {
+    detector: string;
+    cap: number;
+};
+/**
+ * `outTruncated` collects which detectors hit their per-page cap THIS call.
+ * `outWarnings` collects non-fatal engine subsystem failures (e.g. kernel
+ * 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[]>;
 declare function extractSiteTheme(page: PageLike): Promise<SiteTheme>;
 
 interface AxeViolation {