@webability/core 1.1.4 → 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';
@@ -116,9 +128,33 @@ 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
@@ -186,6 +222,16 @@ interface ScanOptions {
      * 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>;

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';
@@ -116,9 +128,33 @@ 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
@@ -186,6 +222,16 @@ interface ScanOptions {
      * 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>;