@webability/core 1.8.0 → 1.9.0

package/dist/{types-BgiJ7PGs.d.cts → types-g-bI_MhR.d.cts}

@@ -113,6 +113,12 @@ interface JudgeOptions {
     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. */
@@ -121,6 +127,11 @@ interface JudgeOptions {
     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;
@@ -134,6 +145,32 @@ interface JudgeOutcome {
     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;
@@ -144,10 +181,12 @@ declare function openAiCompatibleTransport(cfg: {
 /**
  * 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>;
 
@@ -178,7 +217,7 @@ interface PageLike {
     };
 }
 /** 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_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';
+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. */
@@ -318,6 +357,31 @@ interface JudgedEntry {
     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;
@@ -342,6 +406,18 @@ interface ScanResult {
      * 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;
     /**
@@ -351,9 +427,10 @@ interface ScanResult {
      */
     incomplete: ScanIssue[];
     /**
-     * What the AI judge decided about findings the engines could not: every
-     * verdict (`pass` = cleared with a reason, `violation` = promoted into
-     * `issues`). Absent when the judge ran on nothing or is not configured.
+     * 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: {
@@ -374,12 +451,20 @@ declare const VIEWPORT_SIZES: Record<ViewportPreset, {
 }>;
 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;
@@ -420,9 +505,10 @@ interface ScanOptions {
      * 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 = judge skipped; undecided findings are dropped.
+     * 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 IssueImpact as I, type JudgeOptions as J, type PageLike as P, type ScanResult as S, VIEWPORT_SIZES as V, type WcagLevel as W, type ScanOptions 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 IssueSource as h, JUDGE_DEFAULT_TIMEOUT_MS as i, type JudgeItem as j, type JudgeRequest as k, type JudgeTransport as l, type JudgeVerdict as m, type JudgedEntry as n, type ViewportPreset as o, WCAG_BY_ISSUE as p, hostedJudgeTransport as q, judgeUndecided as r, openAiCompatibleTransport as s, resetJudgeCache as t };
+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 };

package/dist/{types-BgiJ7PGs.d.ts → types-g-bI_MhR.d.ts}

@@ -113,6 +113,12 @@ interface JudgeOptions {
     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. */
@@ -121,6 +127,11 @@ interface JudgeOptions {
     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;
@@ -134,6 +145,32 @@ interface JudgeOutcome {
     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;
@@ -144,10 +181,12 @@ declare function openAiCompatibleTransport(cfg: {
 /**
  * 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>;
 
@@ -178,7 +217,7 @@ interface PageLike {
     };
 }
 /** 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_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';
+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. */
@@ -318,6 +357,31 @@ interface JudgedEntry {
     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;
@@ -342,6 +406,18 @@ interface ScanResult {
      * 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;
     /**
@@ -351,9 +427,10 @@ interface ScanResult {
      */
     incomplete: ScanIssue[];
     /**
-     * What the AI judge decided about findings the engines could not: every
-     * verdict (`pass` = cleared with a reason, `violation` = promoted into
-     * `issues`). Absent when the judge ran on nothing or is not configured.
+     * 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: {
@@ -374,12 +451,20 @@ declare const VIEWPORT_SIZES: Record<ViewportPreset, {
 }>;
 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;
@@ -420,9 +505,10 @@ interface ScanOptions {
      * 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 = judge skipped; undecided findings are dropped.
+     * 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 IssueImpact as I, type JudgeOptions as J, type PageLike as P, type ScanResult as S, VIEWPORT_SIZES as V, type WcagLevel as W, type ScanOptions 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 IssueSource as h, JUDGE_DEFAULT_TIMEOUT_MS as i, type JudgeItem as j, type JudgeRequest as k, type JudgeTransport as l, type JudgeVerdict as m, type JudgedEntry as n, type ViewportPreset as o, WCAG_BY_ISSUE as p, hostedJudgeTransport as q, judgeUndecided as r, openAiCompatibleTransport as s, resetJudgeCache as t };
+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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webability/core",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Accessibility scanner engine — WCAG 2.2 AA compliance testing with 200+ rules",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -21,6 +21,18 @@
       "import": "./dist/playwright.js",
       "require": "./dist/playwright.cjs",
       "types": "./dist/playwright.d.ts"
+    },
+    "./engine": {
+      "import": "./dist/engine.js",
+      "require": "./dist/engine.cjs",
+      "types": "./dist/engine.d.ts"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "engine": [
+        "dist/engine.d.ts"
+      ]
     }
   },
   "files": [
@@ -30,7 +42,7 @@
   "scripts": {
     "build": "npm run gen:dom-kernel && tsup",
     "dev": "tsup --watch",
-    "test": "vitest run",
+    "test": "WA_STRICT_STATE=1 vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf dist",
@@ -56,7 +68,8 @@
     "directory": "core"
   },
   "dependencies": {
-    "@axe-core/playwright": "^4.11.3"
+    "@axe-core/playwright": "^4.11.3",
+    "css-what": "^6.2.2"
   },
   "peerDependencies": {
     "playwright": "^1.40.0"
@@ -68,6 +81,7 @@
   },
   "devDependencies": {
     "axe-core": "^4.11.3",
+    "esbuild": "0.27.7",
     "playwright": "1.59.1",
     "tsup": "^8.3.0",
     "typescript": "^5.6.0",