@webability/core 1.10.0 → 1.12.0

package/dist/{types-fjs6XhzQ.d.cts → types-gjAJ8j0I.d.cts}

@@ -219,7 +219,7 @@ interface PageLike {
     axePage?(): unknown;
 }
 /** 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';
+type FixIssueType = 'weak_link_name' | 'weak_heading' | 'weak_iframe_title' | 'weak_page_title' | 'weak_svg_name' | 'missing_button_role' | 'missing_semantic_role' | 'missing_document_language' | 'svg_missing_name' | 'aria_hidden_focusable' | 'contrast_insufficient' | 'non_text_contrast_insufficient' | 'focus_not_visible' | 'empty_link' | 'unlabeled_button' | 'missing_label' | 'skip_link' | 'aria_live' | 'missing_alt' | 'identify_input_purpose' | 'redundant_role' | 'new_window_link' | 'missing_fieldset_legend' | 'missing_table_header' | 'missing_table_caption' | 'missing_table_scope' | 'external_link_warning' | 'download_link_warning' | 'form_missing_submit' | 'placeholder_link' | 'missing_autocomplete' | 'missing_media_controls' | 'unsafe_autoplay' | 'zoom_restriction' | 'resize_text_clipped' | 'link_consistency' | 'keyboard_trap' | 'keyboard_trap_self_focus' | 'focus_order_disruption' | 'missing_captions' | 'color_only_link' | 'label_in_name' | 'onfocus_context_change' | 'focus_obscured_by_sticky' | 'text_spacing_blocked' | 'motion_uncontrollable' | 'auto_refresh' | 'motion_without_reduced_motion' | 'flashing_content' | 'animated_gif_no_pause' | 'carousel_autoplay_no_pause' | 'missing_required_indicator' | 'background_image_unlabeled' | 'broken_aria_reference' | 'main_content_hidden' | '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' | 'adjacent_redundant_link' | 'missing_button_type' | 'decorative_image_with_title' | 'nested_landmark';
 /** WCAG criterion for each issue type. */
 declare const WCAG_BY_ISSUE: Record<FixIssueType, string>;
 /** A single accessibility issue detected on the page. */
@@ -258,6 +258,12 @@ interface DetectedIssue {
     manualFix?: boolean;
     /** Why this finding needs review — surfaced to MCP/SDK consumers. */
     reviewReason?: string;
+    /**
+     * State pseudo-class the fix applies in (`:focus-visible` for
+     * focus_not_visible). `selector` always names the element at rest; a
+     * consumer that writes CSS appends this to the selector.
+     */
+    pseudo?: string;
     /**
      * Optional exact user-facing message. Use when the generic
      * attribute/currentValue template ("missing X", "X is \"Y\"") would state
@@ -366,10 +372,13 @@ interface JudgedEntry {
  *   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
+ * - engine-failed: an engine could not read the page (a detector, axe, or the
+ *   page itself was lost mid-scan) and threw. The findings it would have
+ *   produced are absent, so the result must not be read as clean for them.
  */
 interface InternalBug {
     tool: string;
-    kind: 'state-not-restored' | 'finding-dropped';
+    kind: 'state-not-restored' | 'finding-dropped' | 'engine-failed';
     detail: string;
     selector?: string;
     /**
@@ -422,6 +431,12 @@ interface ScanResult {
     internal_bugs?: InternalBug[];
     /** Engine (core package) version that produced this result — provenance */
     engine?: string;
+    /**
+     * @internal The WebAbility detectors' raw rows, before conversion, judging,
+     * dedup and level gating. Present only with `keepDetected`. Not findings: a
+     * row here may have been dropped from `issues`.
+     */
+    detected?: DetectedIssue[];
     /**
      * @deprecated Always `[]`. The scanner judges uncertain findings itself:
      * each becomes a verdict in `issues` or is dropped. The field stays only so
@@ -455,12 +470,25 @@ interface ScanOptions {
     wcagTags?: string[];
     /** @internal test seam: extra detectors run serially, each in its own state guard. */
     extraSerialDetectors?: FixDetector[];
+    /**
+     * @internal Return the WebAbility detectors' raw rows as `ScanResult.detected`
+     * (runEngine joins them to the reported issues for the platform). Default off:
+     * the result carries no `detected` key.
+     */
+    keepDetected?: boolean;
     /**
      * 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;
+    /**
+     * Also run the experimental best-practice checks (default false). They are
+     * not WCAG 2.2 A/AA requirements, so the default scan never runs them:
+     * adjacent_redundant_link, missing_button_type, decorative_image_with_title,
+     * nested_landmark.
+     */
+    experimental?: boolean;
     /**
      * 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

package/dist/{types-fjs6XhzQ.d.ts → types-gjAJ8j0I.d.ts}

@@ -219,7 +219,7 @@ interface PageLike {
     axePage?(): unknown;
 }
 /** 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';
+type FixIssueType = 'weak_link_name' | 'weak_heading' | 'weak_iframe_title' | 'weak_page_title' | 'weak_svg_name' | 'missing_button_role' | 'missing_semantic_role' | 'missing_document_language' | 'svg_missing_name' | 'aria_hidden_focusable' | 'contrast_insufficient' | 'non_text_contrast_insufficient' | 'focus_not_visible' | 'empty_link' | 'unlabeled_button' | 'missing_label' | 'skip_link' | 'aria_live' | 'missing_alt' | 'identify_input_purpose' | 'redundant_role' | 'new_window_link' | 'missing_fieldset_legend' | 'missing_table_header' | 'missing_table_caption' | 'missing_table_scope' | 'external_link_warning' | 'download_link_warning' | 'form_missing_submit' | 'placeholder_link' | 'missing_autocomplete' | 'missing_media_controls' | 'unsafe_autoplay' | 'zoom_restriction' | 'resize_text_clipped' | 'link_consistency' | 'keyboard_trap' | 'keyboard_trap_self_focus' | 'focus_order_disruption' | 'missing_captions' | 'color_only_link' | 'label_in_name' | 'onfocus_context_change' | 'focus_obscured_by_sticky' | 'text_spacing_blocked' | 'motion_uncontrollable' | 'auto_refresh' | 'motion_without_reduced_motion' | 'flashing_content' | 'animated_gif_no_pause' | 'carousel_autoplay_no_pause' | 'missing_required_indicator' | 'background_image_unlabeled' | 'broken_aria_reference' | 'main_content_hidden' | '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' | 'adjacent_redundant_link' | 'missing_button_type' | 'decorative_image_with_title' | 'nested_landmark';
 /** WCAG criterion for each issue type. */
 declare const WCAG_BY_ISSUE: Record<FixIssueType, string>;
 /** A single accessibility issue detected on the page. */
@@ -258,6 +258,12 @@ interface DetectedIssue {
     manualFix?: boolean;
     /** Why this finding needs review — surfaced to MCP/SDK consumers. */
     reviewReason?: string;
+    /**
+     * State pseudo-class the fix applies in (`:focus-visible` for
+     * focus_not_visible). `selector` always names the element at rest; a
+     * consumer that writes CSS appends this to the selector.
+     */
+    pseudo?: string;
     /**
      * Optional exact user-facing message. Use when the generic
      * attribute/currentValue template ("missing X", "X is \"Y\"") would state
@@ -366,10 +372,13 @@ interface JudgedEntry {
  *   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
+ * - engine-failed: an engine could not read the page (a detector, axe, or the
+ *   page itself was lost mid-scan) and threw. The findings it would have
+ *   produced are absent, so the result must not be read as clean for them.
  */
 interface InternalBug {
     tool: string;
-    kind: 'state-not-restored' | 'finding-dropped';
+    kind: 'state-not-restored' | 'finding-dropped' | 'engine-failed';
     detail: string;
     selector?: string;
     /**
@@ -422,6 +431,12 @@ interface ScanResult {
     internal_bugs?: InternalBug[];
     /** Engine (core package) version that produced this result — provenance */
     engine?: string;
+    /**
+     * @internal The WebAbility detectors' raw rows, before conversion, judging,
+     * dedup and level gating. Present only with `keepDetected`. Not findings: a
+     * row here may have been dropped from `issues`.
+     */
+    detected?: DetectedIssue[];
     /**
      * @deprecated Always `[]`. The scanner judges uncertain findings itself:
      * each becomes a verdict in `issues` or is dropped. The field stays only so
@@ -455,12 +470,25 @@ interface ScanOptions {
     wcagTags?: string[];
     /** @internal test seam: extra detectors run serially, each in its own state guard. */
     extraSerialDetectors?: FixDetector[];
+    /**
+     * @internal Return the WebAbility detectors' raw rows as `ScanResult.detected`
+     * (runEngine joins them to the reported issues for the platform). Default off:
+     * the result carries no `detected` key.
+     */
+    keepDetected?: boolean;
     /**
      * 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;
+    /**
+     * Also run the experimental best-practice checks (default false). They are
+     * not WCAG 2.2 A/AA requirements, so the default scan never runs them:
+     * adjacent_redundant_link, missing_button_type, decorative_image_with_title,
+     * nested_landmark.
+     */
+    experimental?: boolean;
     /**
      * 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webability/core",
-  "version": "1.10.0",
+  "version": "1.12.0",
   "description": "Accessibility scanner engine — WCAG 2.2 AA compliance testing with 200+ rules",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -82,7 +82,9 @@
   "devDependencies": {
     "axe-core": "^4.11.3",
     "esbuild": "0.27.7",
+    "jsdom": "29.0.2",
     "playwright": "1.59.1",
+    "puppeteer-core": "24",
     "tsup": "^8.3.0",
     "typescript": "^5.6.0",
     "vitest": "^2.0.0"