@webability/core 1.18.0 → 1.19.1

package/dist/index.d.cts

@@ -1,9 +1,144 @@
-import { P as PageLike, S as ScanOptions, a as ScanResult, W as WcagLevel, b as SiteTheme, F as FixDetector, I as InternalBug, D as DetectedIssue, c as ScanIssue } from './types-Bk-B2Y9X.cjs';
-export { B as BrowserDetector, d as DEFAULT_JUDGE_BASE_URL, e as DEFAULT_JUDGE_TEXT_MODEL, f as DEFAULT_JUDGE_VISION_MODEL, g as FixIssueType, h as IssueImpact, i as IssueSource, J as JUDGE_DEFAULT_TIMEOUT_MS, j as JUDGE_SYSTEM_PROMPT, k as JudgeChatBody, l as JudgeItem, m as JudgeOptions, n as JudgeRequest, o as JudgeTransport, p as JudgeVerdict, q as JudgedEntry, V as VIEWPORT_SIZES, r as ViewportPreset, s as WCAG_BY_ISSUE, t as buildJudgeChatBody, u as hostedJudgeTransport, v as judgeUndecided, w as openAiCompatibleTransport, x as resetJudgeCache } from './types-Bk-B2Y9X.cjs';
+import { P as PageLike, S as ScanOptions, a as ScanResult, W as WcagLevel, I as IssueImpact, b as ScanIssue, J as JudgeOptions, c as InternalBug, d as JudgeTransport, e as SiteTheme, F as FixDetector, D as DetectedIssue } from './types-B_q8lTmv.cjs';
+export { B as BrowserDetector, f as DEFAULT_JUDGE_BASE_URL, g as DEFAULT_JUDGE_TEXT_MODEL, h as DEFAULT_JUDGE_VISION_MODEL, i as FixIssueType, j as IssueSource, k as JUDGE_DEFAULT_TIMEOUT_MS, l as JUDGE_SYSTEM_PROMPT, m as JudgeChatBody, n as JudgeItem, o as JudgeRequest, p as JudgeVerdict, q as JudgedEntry, V as VIEWPORT_SIZES, r as ViewportPreset, s as WCAG_BY_ISSUE, t as buildJudgeChatBody, u as hostedJudgeTransport, v as judgeUndecided, w as openAiCompatibleTransport, x as resetJudgeCache } from './types-B_q8lTmv.cjs';
 export { F as FIX_JUDGE_MAX_FIXES, a as FixJudgeFix, b as FixJudgeHttpError, c as FixJudgeRequest, d as FixJudgeTransport, e as FixJudgeVerdict, f as FixJudgeVerdictKind, h as hostedFixJudgeTransport } from './hostedFixJudge-DXYes7X1.cjs';
 
 declare function scan(target: string | PageLike, options?: ScanOptions): Promise<ScanResult>;
 
+/**
+ * Rubrics: one human-judgment WCAG aspect per Markdown file (core/rubrics/*.md).
+ *
+ * The files are data. Front matter names the aspect (id, ACT rule, SC, the
+ * evidence it needs, a deterministic applicability filter); the body is the
+ * rubric text the model reads. This module only parses them. Machine-
+ * verifiable rules never get a rubric: axe decides those.
+ */
+
+declare const EVIDENCE_KINDS: readonly ["image", "link", "heading", "formField", "control", "page", "langElement", "form", "iframeGroup", "textBlocks"];
+type EvidenceKind = (typeof EVIDENCE_KINDS)[number];
+interface Rubric {
+    id: string;
+    title: string;
+    /** W3C ACT rule ids this aspect is scored against. */
+    act: string[];
+    sc: string[];
+    level: WcagLevel;
+    issueType: string;
+    impact: IssueImpact;
+    /**
+     * 'none' = no collector yet: the rubric is written but never runs.
+     * 'finding' = it decides engine findings the measurements left open (the
+     * undecided set, with the engine's `evidence`), through the AI judge.
+     */
+    evidence: EvidenceKind | 'none' | 'finding';
+    /** Finding rubrics: the issue types they decide. */
+    routes: string[];
+    /** Finding rubrics: decide any finding whose evidence carries this key as true (wins over `routes`). */
+    routeEvidence?: string;
+    /** Deterministic applicability: every listed boolean field must equal its value. */
+    where: Array<{
+        field: string;
+        value: boolean;
+    }>;
+    vision: boolean;
+    /** below-bar: evaluated, but under the ACT precision bar; the runner skips it unless named in `aspects`. */
+    status: 'evaluated' | 'unevaluated' | 'below-bar';
+    note?: string;
+    /** The rubric text sent to the model (Markdown body). */
+    body: string;
+    file: string;
+}
+declare const RUBRICS: Rubric[];
+/** Rubrics that have a collector and can run (the rubric runner's page aspects). */
+declare const RUNNABLE_RUBRICS: Rubric[];
+
+/**
+ * The rubric prompt contract, shared by the rubric runner (page aspects) and
+ * the AI judge (finding rubrics). A leaf module: no engine imports, so the
+ * judge and the runner can both use it without a cycle.
+ */
+
+type RubricVerdict = 'passed' | 'failed' | 'inapplicable' | 'cantTell';
+/** The rubric's system prompt: shared verdict contract + the rubric text. */
+declare function rubricSystemPrompt(r: Rubric): string;
+/** Parse model output; null when malformed (fail closed: the whole batch is undecided). */
+interface RubricFix {
+    attribute: string;
+    value: string;
+}
+declare function parseRubricVerdicts(raw: unknown): Array<{
+    id: string;
+    verdict: RubricVerdict;
+    reason: string;
+    fix?: RubricFix;
+}> | null;
+/** FNV-1a 64-bit of the rubric prompt, hex. Pure JS so the platform computes the same value from the same core. */
+declare function rubricPromptHash(r: Rubric): string;
+
+/**
+ * Rubric agent: decides the human-judgment WCAG aspects (core/rubrics/*.md).
+ *
+ * Per page: collect typed evidence once (evidence.ts, read-only), apply each
+ * rubric's deterministic applicability (`where`), then send ONE bounded call
+ * per (aspect, candidate batch) through the AI judge's transport with the
+ * rubric as the system prompt. Outcomes:
+ *
+ *   failed        → a finding (ScanIssue) on the candidate element
+ *   passed        → recorded in `verdicts`, not reported
+ *   inapplicable  → recorded, not reported
+ *   cantTell, an id the model left out, malformed output, a timeout → dropped
+ *                   and counted in `undecided`. Never a "needs review" row.
+ *
+ * No verdict cache: every run asks again, so paired eval draws on one page
+ * are independent. Findings on our own tooling are dropped before return
+ * (provenance contract, engines/tooling.ts).
+ */
+
+interface RubricVerdictEntry {
+    aspect: string;
+    selector: string;
+    verdict: Exclude<RubricVerdict, 'cantTell'>;
+    reason: string;
+    /** 'rule' = decided deterministically before any model call. */
+    by: 'model' | 'rule';
+}
+interface RubricRunOptions {
+    url: string;
+    /** Model access, same shape as the AI judge's (key, transport or hosted apiUrl). */
+    judge: JudgeOptions;
+    /** Rubric ids to run; default every runnable rubric. */
+    /** Only these aspects. Without it every runnable aspect runs except those below the ACT precision bar. */
+    aspects?: string[];
+    level?: WcagLevel;
+    /** Candidates per call. Default 8. */
+    batchSize?: number;
+    /** Budget for the whole run. Default 45 s. */
+    timeoutMs?: number;
+    /** Aspects decided in parallel. Default 3. */
+    concurrency?: number;
+    bugs?: InternalBug[];
+    warnings?: string[];
+    /** Scoped scan (verify_fix): only candidates on this element or inside it are asked. */
+    rootSelector?: string;
+}
+interface RubricOutcome {
+    findings: ScanIssue[];
+    verdicts: RubricVerdictEntry[];
+    /** Aspects with no applicable candidate on the page (no call made). */
+    inapplicable: string[];
+    /** Candidates sent to the model that came back without a verdict (cantTell, missing, malformed, timeout). */
+    undecided: number;
+    /** WCAG criteria of the undecided candidates (the scan's `unsettled`). */
+    undecidedWcag: string[];
+    calls: number;
+    errors: string[];
+}
+/**
+ * The judge transport for rubric calls: an injected transport, the operator's
+ * own model key, or the hosted judge (the platform resolves the rubric by id).
+ */
+declare function rubricTransport(opts: JudgeOptions): JudgeTransport | null;
+declare function runRubrics(page: PageLike, opts: RubricRunOptions): Promise<RubricOutcome>;
+
 /**
  * Pure issue-shaping utilities shared by the Playwright scan path
  * (scanner.ts) and the in-DOM scan path (dom.ts). Moved verbatim from
@@ -110,7 +245,9 @@ interface VerifyFixRefusal {
  * criterion no engine can fail, and a selector that crosses a shadow root or
  * iframe. Returns null when verification may proceed.
  */
-declare function verifyFixRefusal(wcag: string | undefined, selector: string, sources?: CoverageSources): Promise<VerifyFixRefusal | null>;
+declare function verifyFixRefusal(wcag: string | undefined, selector: string, sources?: CoverageSources, opts?: {
+    judge?: boolean;
+}): Promise<VerifyFixRefusal | null>;
 
 interface AxeViolation {
     id: string;
@@ -139,6 +276,8 @@ interface AxeViolation {
                 target?: unknown;
             }>;
         }>;
+        /** Set by routeThirdPartyFrameNodes: the node sits in another site's frame. Judge context. */
+        waEvidence?: Record<string, unknown>;
     }>;
 }
 interface AxeRunResult {
@@ -227,4 +366,4 @@ interface DevSuggestion {
 }
 declare function generateDevSuggestion(issue: ScanIssue, framework: Framework, elementClasses?: string, fgColor?: string, bgColor?: string): DevSuggestion;
 
-export { type ContrastSuggestion, type CoverageSources, DetectedIssue, type DevSuggestion, FixDetector, type Framework, type FrameworkInfo, InternalBug, PageLike, REASON_TEXT, ScanIssue, ScanOptions, ScanResult, SiteTheme, type TailwindSuggestion, type Verifiability, WCAG_LEVEL_MAP, WcagLevel, coveredCriteria, criterionVerifiability, detectFramework, dismissModals, extractSiteTheme, generateDevSuggestion, getContrastRatio, getWcagLevel, isPiercingSelector, issueLevel, runAxe, runDetectors, scan, solveContrast, suggestTailwindFix, toHtmlReport, verifyFixRefusal, withinLevel };
+export { type ContrastSuggestion, type CoverageSources, DetectedIssue, type DevSuggestion, type EvidenceKind, FixDetector, type Framework, type FrameworkInfo, InternalBug, IssueImpact, JudgeOptions, JudgeTransport, PageLike, REASON_TEXT, RUBRICS, RUNNABLE_RUBRICS, type Rubric, type RubricOutcome, type RubricRunOptions, type RubricVerdictEntry, ScanIssue, ScanOptions, ScanResult, SiteTheme, type TailwindSuggestion, type Verifiability, WCAG_LEVEL_MAP, WcagLevel, coveredCriteria, criterionVerifiability, detectFramework, dismissModals, extractSiteTheme, generateDevSuggestion, getContrastRatio, getWcagLevel, isPiercingSelector, issueLevel, parseRubricVerdicts, rubricPromptHash, rubricSystemPrompt, rubricTransport, runAxe, runDetectors, runRubrics, scan, solveContrast, suggestTailwindFix, toHtmlReport, verifyFixRefusal, withinLevel };

package/dist/index.d.ts

@@ -1,9 +1,144 @@
-import { P as PageLike, S as ScanOptions, a as ScanResult, W as WcagLevel, b as SiteTheme, F as FixDetector, I as InternalBug, D as DetectedIssue, c as ScanIssue } from './types-Bk-B2Y9X.js';
-export { B as BrowserDetector, d as DEFAULT_JUDGE_BASE_URL, e as DEFAULT_JUDGE_TEXT_MODEL, f as DEFAULT_JUDGE_VISION_MODEL, g as FixIssueType, h as IssueImpact, i as IssueSource, J as JUDGE_DEFAULT_TIMEOUT_MS, j as JUDGE_SYSTEM_PROMPT, k as JudgeChatBody, l as JudgeItem, m as JudgeOptions, n as JudgeRequest, o as JudgeTransport, p as JudgeVerdict, q as JudgedEntry, V as VIEWPORT_SIZES, r as ViewportPreset, s as WCAG_BY_ISSUE, t as buildJudgeChatBody, u as hostedJudgeTransport, v as judgeUndecided, w as openAiCompatibleTransport, x as resetJudgeCache } from './types-Bk-B2Y9X.js';
+import { P as PageLike, S as ScanOptions, a as ScanResult, W as WcagLevel, I as IssueImpact, b as ScanIssue, J as JudgeOptions, c as InternalBug, d as JudgeTransport, e as SiteTheme, F as FixDetector, D as DetectedIssue } from './types-B_q8lTmv.js';
+export { B as BrowserDetector, f as DEFAULT_JUDGE_BASE_URL, g as DEFAULT_JUDGE_TEXT_MODEL, h as DEFAULT_JUDGE_VISION_MODEL, i as FixIssueType, j as IssueSource, k as JUDGE_DEFAULT_TIMEOUT_MS, l as JUDGE_SYSTEM_PROMPT, m as JudgeChatBody, n as JudgeItem, o as JudgeRequest, p as JudgeVerdict, q as JudgedEntry, V as VIEWPORT_SIZES, r as ViewportPreset, s as WCAG_BY_ISSUE, t as buildJudgeChatBody, u as hostedJudgeTransport, v as judgeUndecided, w as openAiCompatibleTransport, x as resetJudgeCache } from './types-B_q8lTmv.js';
 export { F as FIX_JUDGE_MAX_FIXES, a as FixJudgeFix, b as FixJudgeHttpError, c as FixJudgeRequest, d as FixJudgeTransport, e as FixJudgeVerdict, f as FixJudgeVerdictKind, h as hostedFixJudgeTransport } from './hostedFixJudge-DXYes7X1.js';
 
 declare function scan(target: string | PageLike, options?: ScanOptions): Promise<ScanResult>;
 
+/**
+ * Rubrics: one human-judgment WCAG aspect per Markdown file (core/rubrics/*.md).
+ *
+ * The files are data. Front matter names the aspect (id, ACT rule, SC, the
+ * evidence it needs, a deterministic applicability filter); the body is the
+ * rubric text the model reads. This module only parses them. Machine-
+ * verifiable rules never get a rubric: axe decides those.
+ */
+
+declare const EVIDENCE_KINDS: readonly ["image", "link", "heading", "formField", "control", "page", "langElement", "form", "iframeGroup", "textBlocks"];
+type EvidenceKind = (typeof EVIDENCE_KINDS)[number];
+interface Rubric {
+    id: string;
+    title: string;
+    /** W3C ACT rule ids this aspect is scored against. */
+    act: string[];
+    sc: string[];
+    level: WcagLevel;
+    issueType: string;
+    impact: IssueImpact;
+    /**
+     * 'none' = no collector yet: the rubric is written but never runs.
+     * 'finding' = it decides engine findings the measurements left open (the
+     * undecided set, with the engine's `evidence`), through the AI judge.
+     */
+    evidence: EvidenceKind | 'none' | 'finding';
+    /** Finding rubrics: the issue types they decide. */
+    routes: string[];
+    /** Finding rubrics: decide any finding whose evidence carries this key as true (wins over `routes`). */
+    routeEvidence?: string;
+    /** Deterministic applicability: every listed boolean field must equal its value. */
+    where: Array<{
+        field: string;
+        value: boolean;
+    }>;
+    vision: boolean;
+    /** below-bar: evaluated, but under the ACT precision bar; the runner skips it unless named in `aspects`. */
+    status: 'evaluated' | 'unevaluated' | 'below-bar';
+    note?: string;
+    /** The rubric text sent to the model (Markdown body). */
+    body: string;
+    file: string;
+}
+declare const RUBRICS: Rubric[];
+/** Rubrics that have a collector and can run (the rubric runner's page aspects). */
+declare const RUNNABLE_RUBRICS: Rubric[];
+
+/**
+ * The rubric prompt contract, shared by the rubric runner (page aspects) and
+ * the AI judge (finding rubrics). A leaf module: no engine imports, so the
+ * judge and the runner can both use it without a cycle.
+ */
+
+type RubricVerdict = 'passed' | 'failed' | 'inapplicable' | 'cantTell';
+/** The rubric's system prompt: shared verdict contract + the rubric text. */
+declare function rubricSystemPrompt(r: Rubric): string;
+/** Parse model output; null when malformed (fail closed: the whole batch is undecided). */
+interface RubricFix {
+    attribute: string;
+    value: string;
+}
+declare function parseRubricVerdicts(raw: unknown): Array<{
+    id: string;
+    verdict: RubricVerdict;
+    reason: string;
+    fix?: RubricFix;
+}> | null;
+/** FNV-1a 64-bit of the rubric prompt, hex. Pure JS so the platform computes the same value from the same core. */
+declare function rubricPromptHash(r: Rubric): string;
+
+/**
+ * Rubric agent: decides the human-judgment WCAG aspects (core/rubrics/*.md).
+ *
+ * Per page: collect typed evidence once (evidence.ts, read-only), apply each
+ * rubric's deterministic applicability (`where`), then send ONE bounded call
+ * per (aspect, candidate batch) through the AI judge's transport with the
+ * rubric as the system prompt. Outcomes:
+ *
+ *   failed        → a finding (ScanIssue) on the candidate element
+ *   passed        → recorded in `verdicts`, not reported
+ *   inapplicable  → recorded, not reported
+ *   cantTell, an id the model left out, malformed output, a timeout → dropped
+ *                   and counted in `undecided`. Never a "needs review" row.
+ *
+ * No verdict cache: every run asks again, so paired eval draws on one page
+ * are independent. Findings on our own tooling are dropped before return
+ * (provenance contract, engines/tooling.ts).
+ */
+
+interface RubricVerdictEntry {
+    aspect: string;
+    selector: string;
+    verdict: Exclude<RubricVerdict, 'cantTell'>;
+    reason: string;
+    /** 'rule' = decided deterministically before any model call. */
+    by: 'model' | 'rule';
+}
+interface RubricRunOptions {
+    url: string;
+    /** Model access, same shape as the AI judge's (key, transport or hosted apiUrl). */
+    judge: JudgeOptions;
+    /** Rubric ids to run; default every runnable rubric. */
+    /** Only these aspects. Without it every runnable aspect runs except those below the ACT precision bar. */
+    aspects?: string[];
+    level?: WcagLevel;
+    /** Candidates per call. Default 8. */
+    batchSize?: number;
+    /** Budget for the whole run. Default 45 s. */
+    timeoutMs?: number;
+    /** Aspects decided in parallel. Default 3. */
+    concurrency?: number;
+    bugs?: InternalBug[];
+    warnings?: string[];
+    /** Scoped scan (verify_fix): only candidates on this element or inside it are asked. */
+    rootSelector?: string;
+}
+interface RubricOutcome {
+    findings: ScanIssue[];
+    verdicts: RubricVerdictEntry[];
+    /** Aspects with no applicable candidate on the page (no call made). */
+    inapplicable: string[];
+    /** Candidates sent to the model that came back without a verdict (cantTell, missing, malformed, timeout). */
+    undecided: number;
+    /** WCAG criteria of the undecided candidates (the scan's `unsettled`). */
+    undecidedWcag: string[];
+    calls: number;
+    errors: string[];
+}
+/**
+ * The judge transport for rubric calls: an injected transport, the operator's
+ * own model key, or the hosted judge (the platform resolves the rubric by id).
+ */
+declare function rubricTransport(opts: JudgeOptions): JudgeTransport | null;
+declare function runRubrics(page: PageLike, opts: RubricRunOptions): Promise<RubricOutcome>;
+
 /**
  * Pure issue-shaping utilities shared by the Playwright scan path
  * (scanner.ts) and the in-DOM scan path (dom.ts). Moved verbatim from
@@ -110,7 +245,9 @@ interface VerifyFixRefusal {
  * criterion no engine can fail, and a selector that crosses a shadow root or
  * iframe. Returns null when verification may proceed.
  */
-declare function verifyFixRefusal(wcag: string | undefined, selector: string, sources?: CoverageSources): Promise<VerifyFixRefusal | null>;
+declare function verifyFixRefusal(wcag: string | undefined, selector: string, sources?: CoverageSources, opts?: {
+    judge?: boolean;
+}): Promise<VerifyFixRefusal | null>;
 
 interface AxeViolation {
     id: string;
@@ -139,6 +276,8 @@ interface AxeViolation {
                 target?: unknown;
             }>;
         }>;
+        /** Set by routeThirdPartyFrameNodes: the node sits in another site's frame. Judge context. */
+        waEvidence?: Record<string, unknown>;
     }>;
 }
 interface AxeRunResult {
@@ -227,4 +366,4 @@ interface DevSuggestion {
 }
 declare function generateDevSuggestion(issue: ScanIssue, framework: Framework, elementClasses?: string, fgColor?: string, bgColor?: string): DevSuggestion;
 
-export { type ContrastSuggestion, type CoverageSources, DetectedIssue, type DevSuggestion, FixDetector, type Framework, type FrameworkInfo, InternalBug, PageLike, REASON_TEXT, ScanIssue, ScanOptions, ScanResult, SiteTheme, type TailwindSuggestion, type Verifiability, WCAG_LEVEL_MAP, WcagLevel, coveredCriteria, criterionVerifiability, detectFramework, dismissModals, extractSiteTheme, generateDevSuggestion, getContrastRatio, getWcagLevel, isPiercingSelector, issueLevel, runAxe, runDetectors, scan, solveContrast, suggestTailwindFix, toHtmlReport, verifyFixRefusal, withinLevel };
+export { type ContrastSuggestion, type CoverageSources, DetectedIssue, type DevSuggestion, type EvidenceKind, FixDetector, type Framework, type FrameworkInfo, InternalBug, IssueImpact, JudgeOptions, JudgeTransport, PageLike, REASON_TEXT, RUBRICS, RUNNABLE_RUBRICS, type Rubric, type RubricOutcome, type RubricRunOptions, type RubricVerdictEntry, ScanIssue, ScanOptions, ScanResult, SiteTheme, type TailwindSuggestion, type Verifiability, WCAG_LEVEL_MAP, WcagLevel, coveredCriteria, criterionVerifiability, detectFramework, dismissModals, extractSiteTheme, generateDevSuggestion, getContrastRatio, getWcagLevel, isPiercingSelector, issueLevel, parseRubricVerdicts, rubricPromptHash, rubricSystemPrompt, rubricTransport, runAxe, runDetectors, runRubrics, scan, solveContrast, suggestTailwindFix, toHtmlReport, verifyFixRefusal, withinLevel };