@webability/core 1.14.0 → 1.16.0

package/dist/engine.d.cts

@@ -1,4 +1,5 @@
-import { c as ScanIssue, m as JudgeOptions, I as InternalBug, q as JudgedEntry, P as PageLike } from './types-gjAJ8j0I.cjs';
+import { c as ScanIssue, m as JudgeOptions, I as InternalBug, q as JudgedEntry, P as PageLike } from './types-Bk-B2Y9X.cjs';
+import { d as FixJudgeTransport, f as FixJudgeVerdictKind } from './hostedFixJudge-DXYes7X1.cjs';
 
 /**
  * Visitor HTML (`input: { html, baseURL }`): what the page may fetch while the
@@ -217,6 +218,25 @@ interface EngineOptions {
      * structural fixes, `verification` absent.
      */
     verify?: boolean;
+    /**
+     * Hosted fix judge: the fixes the engine emits are sent to this injected
+     * transport (see `hostedFixJudgeTransport`) and come back as
+     * `EngineResult.judgedFixes`, one verdict per fix. The judge runs behind the
+     * transport, never in core. `fixes` itself is unchanged: the caller decides
+     * what an `apply: false` verdict means. Only for a page the engine loaded by
+     * URL (`{ url }` or `{ loaded: true }`): the judge loads that public URL
+     * itself, so html/snapshot input is skipped with a warning. `timeoutMs` bounds
+     * each call (up to ceil(fixes / 20) sequential calls), not the whole stage;
+     * default 160 s.
+     */
+    fixJudge?: {
+        transport: FixJudgeTransport;
+        viewport?: {
+            width: number;
+            height: number;
+        };
+        timeoutMs?: number;
+    };
     /** Axe runs verification may spend isolating regressions. Default 40. */
     verifyMaxAxeRuns?: number;
     /** HTTP status of the main document when the caller navigated. */
@@ -273,8 +293,11 @@ type EngineIssue = ScanIssue;
  * A WebAbility detector's own record of a reported issue: the fields scan()'s
  * issue row drops, for a consumer that writes values itself (the platform's
  * DetectedIssue). One per `source: 'webability'` issue in `issues[]`, same
- * `id`; axe-core rows have none. Only issues that survived scan()'s judging,
- * dedup and level gate get one.
+ * `id`; axe-core rows have none, except `target-size` (WCAG 2.5.8): an axe row
+ * with a checked min-size fix gets a synthetic record (issueType
+ * `target_too_small`, attribute `style`, fixValue the write, same `id` as the axe
+ * row) so a consumer that joins fixes through findings[] sees it. Only issues
+ * that survived scan()'s judging, dedup and level gate get one.
  */
 interface EngineFinding {
     /** The issue row's id (`issues[k].id`). */
@@ -332,6 +355,8 @@ interface EngineStats {
      * rejected candidate never blocks a valid one.
      * `rejectedByEmptyValue`: a detector fix with an empty value on an attribute
      * other than alt (a boolean attribute such as controls=""), why `empty_value`.
+     * `targetSizeSkipped`: axe target-size findings with no safe min-size fix, by skip reason
+     * (informational: the findings stay; not a degraded stage and not part of the identity above).
      */
     fixes: {
         candidates: number;
@@ -345,6 +370,7 @@ interface EngineStats {
         rejectedByEmptyValue: number;
         rejectedByNeverHarm: number;
         rejectedByVerify: number;
+        targetSizeSkipped: Record<string, number>;
         rejected: Array<{
             sel: string;
             attr: string;
@@ -384,6 +410,18 @@ interface EngineStats {
     /** Capabilities the injected Page lacked and what was skipped because of it. */
     warnings: string[];
 }
+/** One emitted fix with the hosted judge's verdict. `apply` is true only for `correct_needed`; every failure is `unclear` + `apply: false`. */
+interface JudgedFix {
+    sel: string;
+    attr: string;
+    val: string;
+    issueType: string;
+    verdict: FixJudgeVerdictKind;
+    apply: boolean;
+    /** wrong_value only: the value the judge says would be right. */
+    suggestedValue?: string;
+    reason: string;
+}
 interface EngineResult {
     url: string;
     issues: EngineIssue[];
@@ -393,6 +431,8 @@ interface EngineResult {
     findings: EngineFinding[];
     internal_bugs: InternalBug[];
     stats: EngineStats;
+    /** The hosted fix judge's verdict on each emitted fix, in `fixes` order (`opts.fixJudge`). Absent when no judge was set or it was skipped (see `stats.warnings`). */
+    judgedFixes?: JudgedFix[];
     /** Verdicts of core's in-scan judge (`opts.scan.judge`) on findings the engines could not decide. */
     judged?: JudgedEntry[];
     /** Set when the target was a bot challenge, auth wall or HTTP error: nothing real was scanned. */
@@ -843,4 +883,80 @@ interface SelectorQualityResult {
 declare const BARE_TAGS: Set<string>;
 declare function scoreSelectorQuality(selector: string): SelectorQualityResult;
 
-export { BARE_TAGS, type EngineFinding, type EngineFix, type EngineInput, type EngineIssue, type EngineOptions, type EngineResult, type EngineStats, FORM_CONTROL_ROLES, type HazardElementView, type HtmlDecision, type HtmlRequest, type HtmlRequestPolicy, InternalBug, LABEL_IN_NAME_JS, type Model, type ModelRequest, type ModelResponse, type Page, type PlaywrightPageLike, type ProtectedScope, type PuppeteerPageLike, SERVED_FIX_KEYS, TOKEN_QUERY_KEY, classifyFixRisk, detectPageLanguage, dropHazardousHidingFixes, foldContains, foldLabel, fromPlaywright, fromPuppeteer, htmlRequestPolicy, isHidingFix, isHtmlLangFix, isInteractiveOrContainsFocusable, isLabelText, labelContainsText, labelInNameCheck, languageFromText, languageFromUrl, loadSnapshot, normalizeVisibleText, parseContext, primaryLanguage, runEngine, scoreSelectorQuality, selectorParses, toPageLike, validateAttribute, validateFix, validateRoleValue, validateSelector, validateSelectorForAttribute, validateTextValue };
+/**
+ * Hidden-at-rest text, listed as facts.
+ *
+ * Read-only and mechanical: this never clicks, hovers, scrolls, focuses or screenshots, and it decides nothing
+ * about whether a user can reach the content or whether it passes. It reports what the page says about itself:
+ * why a text group is not painted at rest, what the CSS backdrop is, and which interactive elements sit near it.
+ * A caller that has a browser and a judge (the platform lane) decides how to reveal a candidate and what it measures.
+ */
+
+type HiddenKind = 'display' | 'visibility' | 'opacity' | 'offscreen' | 'overflow-clip' | 'zero-size';
+type BackdropKind = 'plain' | 'image' | 'gradient' | 'sibling-layer' | 'unknown';
+interface HiddenCause {
+    kind: HiddenKind;
+    /** The element that causes it (may be the text element itself). */
+    selector: string;
+    /** True when the element is moved out of view by a transform. */
+    transformed?: boolean;
+}
+interface HiddenText {
+    selector: string;
+    text: string;
+    fg: string | null;
+    /** Plain CSS backdrop colour when one is known from the cascade. */
+    bg: string | null;
+    backdropKind: BackdropKind;
+    /** Contrast of fg on bg ignoring the hiding (opacity treated as 1). Null unless the backdrop is plain. */
+    staticRatio: number | null;
+    threshold: number;
+    rect: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    } | null;
+}
+interface NearbyInteractive {
+    selector: string;
+    tag: string;
+    role: string | null;
+    name: string;
+    hrefKind: 'none' | 'hash' | 'javascript' | 'same-page' | 'external';
+    inForm: boolean;
+    expanded: string | null;
+    selected: string | null;
+    current: string | null;
+    pressed: string | null;
+    /** Levels above the group root at which it was found (1 = a child of the root's parent). */
+    distance: number;
+    relation: 'ancestor' | 'in-ancestor';
+}
+interface HiddenCandidate {
+    id: number;
+    /** The topmost hidden ancestor-or-self of the texts. */
+    root: string;
+    hiddenBy: HiddenCause[];
+    ariaHidden: boolean;
+    inert: boolean;
+    texts: HiddenText[];
+    interactiveNearby: NearbyInteractive[];
+}
+interface HiddenCandidateList {
+    candidates: HiddenCandidate[];
+    /** Hidden groups found on the page, before the cap. */
+    found: number;
+    truncated?: {
+        found: number;
+        kept: number;
+        cap: number;
+    };
+}
+declare const DEFAULT_MAX_CANDIDATES = 200;
+/** List hidden-at-rest text groups with facts. Read-only. */
+declare function listHiddenCandidates(page: PageLike, opts?: {
+    max?: number;
+}): Promise<HiddenCandidateList>;
+
+export { BARE_TAGS, type BackdropKind, DEFAULT_MAX_CANDIDATES, type EngineFinding, type EngineFix, type EngineInput, type EngineIssue, type EngineOptions, type EngineResult, type EngineStats, FORM_CONTROL_ROLES, type HazardElementView, type HiddenCandidate, type HiddenCandidateList, type HiddenCause, type HiddenKind, type HiddenText, type HtmlDecision, type HtmlRequest, type HtmlRequestPolicy, InternalBug, type JudgedFix, LABEL_IN_NAME_JS, type Model, type ModelRequest, type ModelResponse, type NearbyInteractive, type Page, type PlaywrightPageLike, type ProtectedScope, type PuppeteerPageLike, SERVED_FIX_KEYS, TOKEN_QUERY_KEY, classifyFixRisk, detectPageLanguage, dropHazardousHidingFixes, foldContains, foldLabel, fromPlaywright, fromPuppeteer, htmlRequestPolicy, isHidingFix, isHtmlLangFix, isInteractiveOrContainsFocusable, isLabelText, labelContainsText, labelInNameCheck, languageFromText, languageFromUrl, listHiddenCandidates, loadSnapshot, normalizeVisibleText, parseContext, primaryLanguage, runEngine, scoreSelectorQuality, selectorParses, toPageLike, validateAttribute, validateFix, validateRoleValue, validateSelector, validateSelectorForAttribute, validateTextValue };

package/dist/engine.d.ts

@@ -1,4 +1,5 @@
-import { c as ScanIssue, m as JudgeOptions, I as InternalBug, q as JudgedEntry, P as PageLike } from './types-gjAJ8j0I.js';
+import { c as ScanIssue, m as JudgeOptions, I as InternalBug, q as JudgedEntry, P as PageLike } from './types-Bk-B2Y9X.js';
+import { d as FixJudgeTransport, f as FixJudgeVerdictKind } from './hostedFixJudge-DXYes7X1.js';
 
 /**
  * Visitor HTML (`input: { html, baseURL }`): what the page may fetch while the
@@ -217,6 +218,25 @@ interface EngineOptions {
      * structural fixes, `verification` absent.
      */
     verify?: boolean;
+    /**
+     * Hosted fix judge: the fixes the engine emits are sent to this injected
+     * transport (see `hostedFixJudgeTransport`) and come back as
+     * `EngineResult.judgedFixes`, one verdict per fix. The judge runs behind the
+     * transport, never in core. `fixes` itself is unchanged: the caller decides
+     * what an `apply: false` verdict means. Only for a page the engine loaded by
+     * URL (`{ url }` or `{ loaded: true }`): the judge loads that public URL
+     * itself, so html/snapshot input is skipped with a warning. `timeoutMs` bounds
+     * each call (up to ceil(fixes / 20) sequential calls), not the whole stage;
+     * default 160 s.
+     */
+    fixJudge?: {
+        transport: FixJudgeTransport;
+        viewport?: {
+            width: number;
+            height: number;
+        };
+        timeoutMs?: number;
+    };
     /** Axe runs verification may spend isolating regressions. Default 40. */
     verifyMaxAxeRuns?: number;
     /** HTTP status of the main document when the caller navigated. */
@@ -273,8 +293,11 @@ type EngineIssue = ScanIssue;
  * A WebAbility detector's own record of a reported issue: the fields scan()'s
  * issue row drops, for a consumer that writes values itself (the platform's
  * DetectedIssue). One per `source: 'webability'` issue in `issues[]`, same
- * `id`; axe-core rows have none. Only issues that survived scan()'s judging,
- * dedup and level gate get one.
+ * `id`; axe-core rows have none, except `target-size` (WCAG 2.5.8): an axe row
+ * with a checked min-size fix gets a synthetic record (issueType
+ * `target_too_small`, attribute `style`, fixValue the write, same `id` as the axe
+ * row) so a consumer that joins fixes through findings[] sees it. Only issues
+ * that survived scan()'s judging, dedup and level gate get one.
  */
 interface EngineFinding {
     /** The issue row's id (`issues[k].id`). */
@@ -332,6 +355,8 @@ interface EngineStats {
      * rejected candidate never blocks a valid one.
      * `rejectedByEmptyValue`: a detector fix with an empty value on an attribute
      * other than alt (a boolean attribute such as controls=""), why `empty_value`.
+     * `targetSizeSkipped`: axe target-size findings with no safe min-size fix, by skip reason
+     * (informational: the findings stay; not a degraded stage and not part of the identity above).
      */
     fixes: {
         candidates: number;
@@ -345,6 +370,7 @@ interface EngineStats {
         rejectedByEmptyValue: number;
         rejectedByNeverHarm: number;
         rejectedByVerify: number;
+        targetSizeSkipped: Record<string, number>;
         rejected: Array<{
             sel: string;
             attr: string;
@@ -384,6 +410,18 @@ interface EngineStats {
     /** Capabilities the injected Page lacked and what was skipped because of it. */
     warnings: string[];
 }
+/** One emitted fix with the hosted judge's verdict. `apply` is true only for `correct_needed`; every failure is `unclear` + `apply: false`. */
+interface JudgedFix {
+    sel: string;
+    attr: string;
+    val: string;
+    issueType: string;
+    verdict: FixJudgeVerdictKind;
+    apply: boolean;
+    /** wrong_value only: the value the judge says would be right. */
+    suggestedValue?: string;
+    reason: string;
+}
 interface EngineResult {
     url: string;
     issues: EngineIssue[];
@@ -393,6 +431,8 @@ interface EngineResult {
     findings: EngineFinding[];
     internal_bugs: InternalBug[];
     stats: EngineStats;
+    /** The hosted fix judge's verdict on each emitted fix, in `fixes` order (`opts.fixJudge`). Absent when no judge was set or it was skipped (see `stats.warnings`). */
+    judgedFixes?: JudgedFix[];
     /** Verdicts of core's in-scan judge (`opts.scan.judge`) on findings the engines could not decide. */
     judged?: JudgedEntry[];
     /** Set when the target was a bot challenge, auth wall or HTTP error: nothing real was scanned. */
@@ -843,4 +883,80 @@ interface SelectorQualityResult {
 declare const BARE_TAGS: Set<string>;
 declare function scoreSelectorQuality(selector: string): SelectorQualityResult;
 
-export { BARE_TAGS, type EngineFinding, type EngineFix, type EngineInput, type EngineIssue, type EngineOptions, type EngineResult, type EngineStats, FORM_CONTROL_ROLES, type HazardElementView, type HtmlDecision, type HtmlRequest, type HtmlRequestPolicy, InternalBug, LABEL_IN_NAME_JS, type Model, type ModelRequest, type ModelResponse, type Page, type PlaywrightPageLike, type ProtectedScope, type PuppeteerPageLike, SERVED_FIX_KEYS, TOKEN_QUERY_KEY, classifyFixRisk, detectPageLanguage, dropHazardousHidingFixes, foldContains, foldLabel, fromPlaywright, fromPuppeteer, htmlRequestPolicy, isHidingFix, isHtmlLangFix, isInteractiveOrContainsFocusable, isLabelText, labelContainsText, labelInNameCheck, languageFromText, languageFromUrl, loadSnapshot, normalizeVisibleText, parseContext, primaryLanguage, runEngine, scoreSelectorQuality, selectorParses, toPageLike, validateAttribute, validateFix, validateRoleValue, validateSelector, validateSelectorForAttribute, validateTextValue };
+/**
+ * Hidden-at-rest text, listed as facts.
+ *
+ * Read-only and mechanical: this never clicks, hovers, scrolls, focuses or screenshots, and it decides nothing
+ * about whether a user can reach the content or whether it passes. It reports what the page says about itself:
+ * why a text group is not painted at rest, what the CSS backdrop is, and which interactive elements sit near it.
+ * A caller that has a browser and a judge (the platform lane) decides how to reveal a candidate and what it measures.
+ */
+
+type HiddenKind = 'display' | 'visibility' | 'opacity' | 'offscreen' | 'overflow-clip' | 'zero-size';
+type BackdropKind = 'plain' | 'image' | 'gradient' | 'sibling-layer' | 'unknown';
+interface HiddenCause {
+    kind: HiddenKind;
+    /** The element that causes it (may be the text element itself). */
+    selector: string;
+    /** True when the element is moved out of view by a transform. */
+    transformed?: boolean;
+}
+interface HiddenText {
+    selector: string;
+    text: string;
+    fg: string | null;
+    /** Plain CSS backdrop colour when one is known from the cascade. */
+    bg: string | null;
+    backdropKind: BackdropKind;
+    /** Contrast of fg on bg ignoring the hiding (opacity treated as 1). Null unless the backdrop is plain. */
+    staticRatio: number | null;
+    threshold: number;
+    rect: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    } | null;
+}
+interface NearbyInteractive {
+    selector: string;
+    tag: string;
+    role: string | null;
+    name: string;
+    hrefKind: 'none' | 'hash' | 'javascript' | 'same-page' | 'external';
+    inForm: boolean;
+    expanded: string | null;
+    selected: string | null;
+    current: string | null;
+    pressed: string | null;
+    /** Levels above the group root at which it was found (1 = a child of the root's parent). */
+    distance: number;
+    relation: 'ancestor' | 'in-ancestor';
+}
+interface HiddenCandidate {
+    id: number;
+    /** The topmost hidden ancestor-or-self of the texts. */
+    root: string;
+    hiddenBy: HiddenCause[];
+    ariaHidden: boolean;
+    inert: boolean;
+    texts: HiddenText[];
+    interactiveNearby: NearbyInteractive[];
+}
+interface HiddenCandidateList {
+    candidates: HiddenCandidate[];
+    /** Hidden groups found on the page, before the cap. */
+    found: number;
+    truncated?: {
+        found: number;
+        kept: number;
+        cap: number;
+    };
+}
+declare const DEFAULT_MAX_CANDIDATES = 200;
+/** List hidden-at-rest text groups with facts. Read-only. */
+declare function listHiddenCandidates(page: PageLike, opts?: {
+    max?: number;
+}): Promise<HiddenCandidateList>;
+
+export { BARE_TAGS, type BackdropKind, DEFAULT_MAX_CANDIDATES, type EngineFinding, type EngineFix, type EngineInput, type EngineIssue, type EngineOptions, type EngineResult, type EngineStats, FORM_CONTROL_ROLES, type HazardElementView, type HiddenCandidate, type HiddenCandidateList, type HiddenCause, type HiddenKind, type HiddenText, type HtmlDecision, type HtmlRequest, type HtmlRequestPolicy, InternalBug, type JudgedFix, LABEL_IN_NAME_JS, type Model, type ModelRequest, type ModelResponse, type NearbyInteractive, type Page, type PlaywrightPageLike, type ProtectedScope, type PuppeteerPageLike, SERVED_FIX_KEYS, TOKEN_QUERY_KEY, classifyFixRisk, detectPageLanguage, dropHazardousHidingFixes, foldContains, foldLabel, fromPlaywright, fromPuppeteer, htmlRequestPolicy, isHidingFix, isHtmlLangFix, isInteractiveOrContainsFocusable, isLabelText, labelContainsText, labelInNameCheck, languageFromText, languageFromUrl, listHiddenCandidates, loadSnapshot, normalizeVisibleText, parseContext, primaryLanguage, runEngine, scoreSelectorQuality, selectorParses, toPageLike, validateAttribute, validateFix, validateRoleValue, validateSelector, validateSelectorForAttribute, validateTextValue };