@webability/core 1.6.0 → 1.8.0

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

@@ -1,3 +1,156 @@
+/**
+ * Rendered-pixel contrast judge for text on a gradient / image / overlapped
+ * background — the cases where axe reports `incomplete` and CSS cannot give a
+ * background colour.
+ *
+ * What the user actually sees behind the glyphs IS measurable: hide every
+ * glyph, screenshot the text's own boxes, and compare the text colour with
+ * the pixels that were behind it.
+ *
+ *   - every pixel fails the threshold  -> the text fails wherever it sits: VIOLATION
+ *   - any pixel passes                 -> the background is not uniformly bad: DROP
+ *     (a mixed gradient is not a confident failure, and never a pass we claim)
+ *
+ * Anything we cannot measure reliably (semi-transparent text, text over
+ * <video>/<canvas>/<iframe>, background-clip:text, transformed or clipped
+ * boxes, no screenshot support) is dropped, never judged.
+ */
+
+interface PixelVerdict {
+    selector: string;
+    fail: boolean;
+    /** Best (highest) contrast ratio found anywhere behind the text. */
+    bestRatio: number;
+    /** Worst (lowest) contrast ratio found anywhere behind the text. */
+    worstRatio: number;
+    /** The background pixel behind the text that gave `worstRatio`, as rgb(r,g,b). */
+    worstBg?: string;
+    /** The background pixel behind the text that gave `bestRatio`, as rgb(r,g,b). */
+    bestBg?: string;
+    threshold: number;
+    fg: string;
+}
+
+/**
+ * AI judge for the undecided set.
+ *
+ * The scanner never hands the user a "needs review" bucket. Findings the
+ * engines could not decide (axe `incomplete`, a detector's `needsReview`)
+ * first go through the deterministic resolvers (rendered-pixel contrast,
+ * captions). What is still undecided after that reaches this judge, which
+ * turns each item into one of:
+ *
+ *   - `violation` + a concrete fix  → promoted into `issues[]`
+ *   - `pass` + a one-line reason    → recorded in `judged[]`, not reported
+ *
+ * Anything the judge cannot settle — no model configured, malformed output,
+ * timeout, a contrast background that cannot be sampled — is DROPPED, exactly
+ * as before. The judge never invents a verdict.
+ *
+ * Deterministic pre-judges run before any model call (declared-decorative
+ * images, images named by their link text, CSS backgrounds outside any
+ * control or on a control that already has a name, motion that a
+ * `prefers-reduced-motion: reduce` rule stops on that element). Contrast items carry a real pixel measurement
+ * (best/worst ratio behind the glyphs, AA threshold for the font size) so the
+ * verdict states a ratio the scanner measured, not one the model guessed.
+ *
+ * Models (local, via an OpenAI-compatible chat endpoint — OpenRouter by
+ * default): vision `anthropic/claude-haiku-4.5`, text-only
+ * `deepseek/deepseek-v4-flash`. Hosted: POST `${apiUrl}/api/judge-incomplete`.
+ */
+
+declare const JUDGE_DEFAULT_TIMEOUT_MS = 20000;
+declare const DEFAULT_JUDGE_BASE_URL = "https://openrouter.ai/api/v1";
+declare const DEFAULT_JUDGE_VISION_MODEL = "anthropic/claude-haiku-4.5";
+declare const DEFAULT_JUDGE_TEXT_MODEL = "deepseek/deepseek-v4-flash";
+type JudgeVerdictKind = 'pass' | 'violation';
+/** One judged finding, as recorded on `ScanResult.judged`. Small on purpose. */
+interface JudgedEntry$1 {
+    id: string;
+    type: string;
+    verdict: JudgeVerdictKind;
+    reason: string;
+}
+/** One undecided finding as sent to the model / hosted endpoint. */
+interface JudgeItem {
+    id: string;
+    type: string;
+    wcag: string;
+    message: string;
+    selector: string;
+    /** outerHTML, ≤400 chars */
+    html: string;
+    /** Computed context: colours/threshold/ratios for contrast, src/alt/link text for images, … */
+    context: Record<string, unknown>;
+    /** PNG, base64 (no data: prefix). Present only on the vision path. */
+    screenshot?: string;
+}
+interface JudgeRequest {
+    url: string;
+    level: WcagLevel;
+    vision: boolean;
+    items: JudgeItem[];
+}
+interface JudgeVerdict {
+    id: string;
+    verdict: JudgeVerdictKind;
+    reason?: string;
+    fix?: {
+        attribute?: string;
+        value?: string;
+    };
+}
+/** Returns the raw model output (a JSON array string) or an already-parsed `{verdicts}` / array. */
+type JudgeTransport = (req: JudgeRequest, signal: AbortSignal) => Promise<unknown>;
+interface JudgeOptions {
+    /** OpenAI-compatible chat-completions key (OpenRouter). Enables the local path. */
+    apiKey?: string;
+    /** Base URL of the chat-completions API. Default https://openrouter.ai/api/v1 */
+    baseUrl?: string;
+    visionModel?: string;
+    textModel?: string;
+    /** Hosted path: WebAbility API origin; POST `${apiUrl}/api/judge-incomplete`. */
+    apiUrl?: string;
+    /** Bearer token for the hosted path. */
+    apiToken?: 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. */
+    level?: WcagLevel;
+    /** false = HTML/text only (scan_html, DOM path). Default: screenshots when the page can take them. */
+    vision?: boolean;
+    /** Test / custom model injection. Wins over apiKey/apiUrl. */
+    transport?: JudgeTransport;
+}
+interface JudgeRunOptions extends JudgeOptions {
+    url: string;
+    /** Pixel measurements already taken by the contrast resolver (by selector). */
+    measured?: Map<string, PixelVerdict>;
+}
+interface JudgeOutcome {
+    /** Verdict=violation, now confirmed findings with a fix. Not yet deduped against `issues`. */
+    promoted: ScanIssue[];
+    /** Every verdict reached (pass and violation), id = the original finding id. */
+    judged: JudgedEntry$1[];
+}
+declare function resetJudgeCache(): void;
+/** OpenAI-compatible chat completions (OpenRouter). Vision → image_url parts; text-only → text model. */
+declare function openAiCompatibleTransport(cfg: {
+    apiKey: string;
+    baseUrl?: string;
+    visionModel?: string;
+    textModel?: string;
+}): JudgeTransport;
+/**
+ * Hosted path: the platform judges on the server. Request body = JudgeRequest;
+ * response = `{ verdicts: JudgeVerdict[] }`. Any non-2xx → items stay dropped.
+ */
+declare function hostedJudgeTransport(cfg: {
+    apiUrl: string;
+    token?: string;
+}): JudgeTransport;
+declare function judgeUndecided(page: PageLike | null, undecided: readonly ScanIssue[], opts: JudgeRunOptions): Promise<JudgeOutcome>;
+
 /**
  * @webability/core — type definitions
  */
@@ -113,12 +266,10 @@ type IssueSource = 'webability' | 'axe-core' | 'deep-analysis';
 type IssueImpact = 'critical' | 'serious' | 'moderate' | 'minor';
 type WcagLevel = 'A' | 'AA' | 'AAA';
 /**
- * Confidence tier for a scan finding. Mirrors axe-core's three-tier output —
- * `high` is a confirmed violation safe to act on; `needs_review` is ambiguous
- * (e.g. text on a gradient background, mid-animation opacity, marketing imagery
- * that may legitimately contain text). Consumers should never auto-apply fixes
- * to `needs_review` findings — they belong in the `incomplete[]` bucket and
- * require human judgment.
+ * Internal confidence marker. `needs_review` means an engine could not decide
+ * (text on a gradient, marketing imagery that may be a logo, …). Such findings
+ * never reach the result: the pixel/caption resolvers and the AI judge turn
+ * them into a verdict, or they are dropped. No reported issue carries it.
  */
 type IssueConfidence = 'high' | 'needs_review';
 interface ScanIssue {
@@ -131,9 +282,9 @@ interface ScanIssue {
     message: string;
     selector: string;
     html?: string;
-    /** When set, this issue is ambiguous and lives in `ScanResult.incomplete[]`. */
+    /** Internal: set by an engine that could not decide; stripped before the result. */
     confidence?: IssueConfidence;
-    /** Why the classifier demoted this issue. Surfaced to MCP/SDK consumers. */
+    /** Internal: why the engine could not decide; handed to the judge as context, never reported. */
     reviewReason?: string;
     fix?: {
         attribute: string;
@@ -160,6 +311,13 @@ interface BlockedInfo {
     /** The specific signal that matched (page title, marker selector, or status). */
     signal?: string;
 }
+/** One judged finding — see `ScanResult.judged`. */
+interface JudgedEntry {
+    id: string;
+    type: string;
+    verdict: 'pass' | 'violation';
+    reason: string;
+}
 interface ScanResult {
     url: string;
     timestamp: string;
@@ -192,6 +350,12 @@ interface ScanResult {
      * existing consumers that read it keep compiling.
      */
     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.
+     */
+    judged?: JudgedEntry[];
     summary: {
         total: number;
         critical: number;
@@ -252,6 +416,13 @@ interface ScanOptions {
      * uniformly across both entrypoints. Ignored on the URL-string path.
      */
     mainStatus?: number;
+    /**
+     * 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.
+     */
+    judge?: JudgeOptions;
 }
 
-export { type BrowserDetector as B, type DetectedIssue as D, type FixDetector as F, type IssueImpact as I, 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, type FixIssueType as d, type IssueSource as e, type ViewportPreset as f, WCAG_BY_ISSUE as g };
+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 };

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

@@ -1,3 +1,156 @@
+/**
+ * Rendered-pixel contrast judge for text on a gradient / image / overlapped
+ * background — the cases where axe reports `incomplete` and CSS cannot give a
+ * background colour.
+ *
+ * What the user actually sees behind the glyphs IS measurable: hide every
+ * glyph, screenshot the text's own boxes, and compare the text colour with
+ * the pixels that were behind it.
+ *
+ *   - every pixel fails the threshold  -> the text fails wherever it sits: VIOLATION
+ *   - any pixel passes                 -> the background is not uniformly bad: DROP
+ *     (a mixed gradient is not a confident failure, and never a pass we claim)
+ *
+ * Anything we cannot measure reliably (semi-transparent text, text over
+ * <video>/<canvas>/<iframe>, background-clip:text, transformed or clipped
+ * boxes, no screenshot support) is dropped, never judged.
+ */
+
+interface PixelVerdict {
+    selector: string;
+    fail: boolean;
+    /** Best (highest) contrast ratio found anywhere behind the text. */
+    bestRatio: number;
+    /** Worst (lowest) contrast ratio found anywhere behind the text. */
+    worstRatio: number;
+    /** The background pixel behind the text that gave `worstRatio`, as rgb(r,g,b). */
+    worstBg?: string;
+    /** The background pixel behind the text that gave `bestRatio`, as rgb(r,g,b). */
+    bestBg?: string;
+    threshold: number;
+    fg: string;
+}
+
+/**
+ * AI judge for the undecided set.
+ *
+ * The scanner never hands the user a "needs review" bucket. Findings the
+ * engines could not decide (axe `incomplete`, a detector's `needsReview`)
+ * first go through the deterministic resolvers (rendered-pixel contrast,
+ * captions). What is still undecided after that reaches this judge, which
+ * turns each item into one of:
+ *
+ *   - `violation` + a concrete fix  → promoted into `issues[]`
+ *   - `pass` + a one-line reason    → recorded in `judged[]`, not reported
+ *
+ * Anything the judge cannot settle — no model configured, malformed output,
+ * timeout, a contrast background that cannot be sampled — is DROPPED, exactly
+ * as before. The judge never invents a verdict.
+ *
+ * Deterministic pre-judges run before any model call (declared-decorative
+ * images, images named by their link text, CSS backgrounds outside any
+ * control or on a control that already has a name, motion that a
+ * `prefers-reduced-motion: reduce` rule stops on that element). Contrast items carry a real pixel measurement
+ * (best/worst ratio behind the glyphs, AA threshold for the font size) so the
+ * verdict states a ratio the scanner measured, not one the model guessed.
+ *
+ * Models (local, via an OpenAI-compatible chat endpoint — OpenRouter by
+ * default): vision `anthropic/claude-haiku-4.5`, text-only
+ * `deepseek/deepseek-v4-flash`. Hosted: POST `${apiUrl}/api/judge-incomplete`.
+ */
+
+declare const JUDGE_DEFAULT_TIMEOUT_MS = 20000;
+declare const DEFAULT_JUDGE_BASE_URL = "https://openrouter.ai/api/v1";
+declare const DEFAULT_JUDGE_VISION_MODEL = "anthropic/claude-haiku-4.5";
+declare const DEFAULT_JUDGE_TEXT_MODEL = "deepseek/deepseek-v4-flash";
+type JudgeVerdictKind = 'pass' | 'violation';
+/** One judged finding, as recorded on `ScanResult.judged`. Small on purpose. */
+interface JudgedEntry$1 {
+    id: string;
+    type: string;
+    verdict: JudgeVerdictKind;
+    reason: string;
+}
+/** One undecided finding as sent to the model / hosted endpoint. */
+interface JudgeItem {
+    id: string;
+    type: string;
+    wcag: string;
+    message: string;
+    selector: string;
+    /** outerHTML, ≤400 chars */
+    html: string;
+    /** Computed context: colours/threshold/ratios for contrast, src/alt/link text for images, … */
+    context: Record<string, unknown>;
+    /** PNG, base64 (no data: prefix). Present only on the vision path. */
+    screenshot?: string;
+}
+interface JudgeRequest {
+    url: string;
+    level: WcagLevel;
+    vision: boolean;
+    items: JudgeItem[];
+}
+interface JudgeVerdict {
+    id: string;
+    verdict: JudgeVerdictKind;
+    reason?: string;
+    fix?: {
+        attribute?: string;
+        value?: string;
+    };
+}
+/** Returns the raw model output (a JSON array string) or an already-parsed `{verdicts}` / array. */
+type JudgeTransport = (req: JudgeRequest, signal: AbortSignal) => Promise<unknown>;
+interface JudgeOptions {
+    /** OpenAI-compatible chat-completions key (OpenRouter). Enables the local path. */
+    apiKey?: string;
+    /** Base URL of the chat-completions API. Default https://openrouter.ai/api/v1 */
+    baseUrl?: string;
+    visionModel?: string;
+    textModel?: string;
+    /** Hosted path: WebAbility API origin; POST `${apiUrl}/api/judge-incomplete`. */
+    apiUrl?: string;
+    /** Bearer token for the hosted path. */
+    apiToken?: 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. */
+    level?: WcagLevel;
+    /** false = HTML/text only (scan_html, DOM path). Default: screenshots when the page can take them. */
+    vision?: boolean;
+    /** Test / custom model injection. Wins over apiKey/apiUrl. */
+    transport?: JudgeTransport;
+}
+interface JudgeRunOptions extends JudgeOptions {
+    url: string;
+    /** Pixel measurements already taken by the contrast resolver (by selector). */
+    measured?: Map<string, PixelVerdict>;
+}
+interface JudgeOutcome {
+    /** Verdict=violation, now confirmed findings with a fix. Not yet deduped against `issues`. */
+    promoted: ScanIssue[];
+    /** Every verdict reached (pass and violation), id = the original finding id. */
+    judged: JudgedEntry$1[];
+}
+declare function resetJudgeCache(): void;
+/** OpenAI-compatible chat completions (OpenRouter). Vision → image_url parts; text-only → text model. */
+declare function openAiCompatibleTransport(cfg: {
+    apiKey: string;
+    baseUrl?: string;
+    visionModel?: string;
+    textModel?: string;
+}): JudgeTransport;
+/**
+ * Hosted path: the platform judges on the server. Request body = JudgeRequest;
+ * response = `{ verdicts: JudgeVerdict[] }`. Any non-2xx → items stay dropped.
+ */
+declare function hostedJudgeTransport(cfg: {
+    apiUrl: string;
+    token?: string;
+}): JudgeTransport;
+declare function judgeUndecided(page: PageLike | null, undecided: readonly ScanIssue[], opts: JudgeRunOptions): Promise<JudgeOutcome>;
+
 /**
  * @webability/core — type definitions
  */
@@ -113,12 +266,10 @@ type IssueSource = 'webability' | 'axe-core' | 'deep-analysis';
 type IssueImpact = 'critical' | 'serious' | 'moderate' | 'minor';
 type WcagLevel = 'A' | 'AA' | 'AAA';
 /**
- * Confidence tier for a scan finding. Mirrors axe-core's three-tier output —
- * `high` is a confirmed violation safe to act on; `needs_review` is ambiguous
- * (e.g. text on a gradient background, mid-animation opacity, marketing imagery
- * that may legitimately contain text). Consumers should never auto-apply fixes
- * to `needs_review` findings — they belong in the `incomplete[]` bucket and
- * require human judgment.
+ * Internal confidence marker. `needs_review` means an engine could not decide
+ * (text on a gradient, marketing imagery that may be a logo, …). Such findings
+ * never reach the result: the pixel/caption resolvers and the AI judge turn
+ * them into a verdict, or they are dropped. No reported issue carries it.
  */
 type IssueConfidence = 'high' | 'needs_review';
 interface ScanIssue {
@@ -131,9 +282,9 @@ interface ScanIssue {
     message: string;
     selector: string;
     html?: string;
-    /** When set, this issue is ambiguous and lives in `ScanResult.incomplete[]`. */
+    /** Internal: set by an engine that could not decide; stripped before the result. */
     confidence?: IssueConfidence;
-    /** Why the classifier demoted this issue. Surfaced to MCP/SDK consumers. */
+    /** Internal: why the engine could not decide; handed to the judge as context, never reported. */
     reviewReason?: string;
     fix?: {
         attribute: string;
@@ -160,6 +311,13 @@ interface BlockedInfo {
     /** The specific signal that matched (page title, marker selector, or status). */
     signal?: string;
 }
+/** One judged finding — see `ScanResult.judged`. */
+interface JudgedEntry {
+    id: string;
+    type: string;
+    verdict: 'pass' | 'violation';
+    reason: string;
+}
 interface ScanResult {
     url: string;
     timestamp: string;
@@ -192,6 +350,12 @@ interface ScanResult {
      * existing consumers that read it keep compiling.
      */
     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.
+     */
+    judged?: JudgedEntry[];
     summary: {
         total: number;
         critical: number;
@@ -252,6 +416,13 @@ interface ScanOptions {
      * uniformly across both entrypoints. Ignored on the URL-string path.
      */
     mainStatus?: number;
+    /**
+     * 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.
+     */
+    judge?: JudgeOptions;
 }
 
-export { type BrowserDetector as B, type DetectedIssue as D, type FixDetector as F, type IssueImpact as I, 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, type FixIssueType as d, type IssueSource as e, type ViewportPreset as f, WCAG_BY_ISSUE as g };
+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 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@webability/core",
-  "version": "1.6.0",
-  "description": "Accessibility scanner engine \u2014 WCAG 2.2 AA compliance testing with 200+ rules",
+  "version": "1.8.0",
+  "description": "Accessibility scanner engine — WCAG 2.2 AA compliance testing with 200+ rules",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",