@webability/core 1.15.0 → 1.17.0

package/dist/engine.d.cts

@@ -1,4 +1,4 @@
-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';
 
 /**
@@ -293,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`). */
@@ -352,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;
@@ -365,6 +370,7 @@ interface EngineStats {
         rejectedByEmptyValue: number;
         rejectedByNeverHarm: number;
         rejectedByVerify: number;
+        targetSizeSkipped: Record<string, number>;
         rejected: Array<{
             sel: string;
             attr: string;
@@ -877,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, type JudgedFix, 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,4 @@
-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';
 
 /**
@@ -293,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`). */
@@ -352,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;
@@ -365,6 +370,7 @@ interface EngineStats {
         rejectedByEmptyValue: number;
         rejectedByNeverHarm: number;
         rejectedByVerify: number;
+        targetSizeSkipped: Record<string, number>;
         rejected: Array<{
             sel: string;
             attr: string;
@@ -877,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, type JudgedFix, 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 };