@webability/core 1.11.0 → 1.13.0

package/dist/engine.d.cts

@@ -1,4 +1,40 @@
-import { c as ScanIssue, m as JudgeOptions, I as InternalBug, q as JudgedEntry, P as PageLike } from './types-jXnoW_NT.cjs';
+import { c as ScanIssue, m as JudgeOptions, I as InternalBug, q as JudgedEntry, P as PageLike } from './types-gjAJ8j0I.cjs';
+
+/**
+ * Visitor HTML (`input: { html, baseURL }`): what the page may fetch while the
+ * served document is scanned, and the wait for its styles.
+ *
+ * The html is answered AS the response for baseURL. Every other request goes
+ * through `htmlRequestPolicy`: only stylesheets, fonts and images load (what
+ * computed styles and pixel contrast need); iframes, media, fetches, beacons
+ * and any other document are aborted, and so is a URL whose query carries a
+ * token-like key (a signed or session URL captured from a visitor must not be
+ * replayed from our IP). The adapters run the policy in the same interception
+ * the caller's guard uses, so that guard still sees, and can abort, every
+ * request the policy lets through.
+ */
+/** One intercepted request, as the policy reads it. */
+interface HtmlRequest {
+    url: string;
+    /** Driver resource type ('document', 'stylesheet', 'image', 'xhr'…). */
+    resourceType: string;
+    /** A navigation (document) request. */
+    navigation: boolean;
+    /** Issued by the top frame (false for an iframe's document). */
+    mainFrame: boolean;
+}
+/** fulfill: answer with the html. continue: let it through (to the caller's guard, then the network). abort: refuse. */
+type HtmlDecision = 'fulfill' | 'continue' | 'abort';
+type HtmlRequestPolicy = (r: HtmlRequest) => HtmlDecision;
+/** Query keys of signed, session or nonce URLs. */
+declare const TOKEN_QUERY_KEY: RegExp;
+/**
+ * The request policy for html served at `target`. `scripts: true` (the html's
+ * scripts run) also lets script requests through.
+ */
+declare function htmlRequestPolicy(target: string, opts?: {
+    scripts?: boolean;
+}): HtmlRequestPolicy;
 
 /**
  * The one engine's contract: two injected drivers in, one result out.
@@ -16,10 +52,14 @@ import { c as ScanIssue, m as JudgeOptions, I as InternalBug, q as JudgedEntry,
  * (`fromPlaywright`: its `evaluate` takes one argument). Optional members widen what the engine can
  * do; each absent one is named in `stats.warnings`, never guessed around.
  *
- * Isolation is the driver's: for `html` input the engine removes `<script>`
- * (HTML and SVG) and meta refresh but keeps inline handler attributes (detectors read them),
- * so the driver must give the page no egress it would not give a scanned site
- * (the hosted MCP's SSRF route, a sandbox), or turn JavaScript off.
+ * Isolation is the driver's: for snapshot input (`{ html, url }`) the engine
+ * removes `<script>` (HTML and SVG) and meta refresh but keeps inline handler
+ * attributes (detectors read them), so the driver must give the page no egress
+ * it would not give a scanned site (the hosted MCP's SSRF route, a sandbox),
+ * or turn JavaScript off. Visitor HTML (`{ html, baseURL }`) also loses
+ * `<noscript>`, its `on*` handlers are commented out and its `javascript:` URLs
+ * become `javascript:void(0)`, and its requests go through
+ * `htmlRequestPolicy` (see `loadHtml`).
  */
 interface Page {
     /** A Response-like return (`status()`) is read for the main document's HTTP status. */
@@ -55,8 +95,21 @@ interface Page {
      * Serve `html` as the document at `url` and navigate there (no network fetch
      * of the page itself). Absent: a snapshot stays on about:blank with a
      * `<base href>`, and `location` is about:blank.
+     *
+     * `policy` decides every request the page makes until the returned release
+     * function runs (the engine calls it when the scan is done): 'fulfill' is
+     * answered with `html`, 'abort' is refused, 'continue' goes on to the
+     * caller's own interception (a private-target guard), which may still abort
+     * it. The policy must compose with that guard, never replace it: Puppeteer
+     * cooperative interception at the default priority, Playwright
+     * `route.fallback()`. Absent policy: only the document is answered.
      */
-    loadHtml?(html: string, url: string): Promise<void>;
+    loadHtml?(html: string, url: string, policy?: HtmlRequestPolicy): Promise<void | (() => Promise<void>)>;
+    /** Set the viewport (CSS px). Absent: an input viewport is not applied, named in `stats.warnings`. */
+    setViewport?(size: {
+        width: number;
+        height: number;
+    }): Promise<void>;
     /** Script injection (Playwright/Puppeteer). Absent: string `evaluate` is used. */
     addScriptTag?(opts: {
         content?: string;
@@ -98,20 +151,74 @@ interface Model {
     }): Promise<ModelResponse>;
 }
 /**
- * What to scan. `url` alone: the engine loads it on the page. `html`: a DOM
- * snapshot (the widget Worker's input) loaded into the page, with `url` as its
- * base and the source of the fix records' page path.
+ * What to scan. `url` alone: the engine loads it on the page. `url` with
+ * `loaded: true`: the caller already navigated the page there (its own
+ * interception, waits and status); the engine scans it as it is and reads the
+ * HTTP status from `opts.mainStatus`. `html`: a DOM snapshot (the widget
+ * Worker's input) loaded into the page, with `url` as its base and the source
+ * of the fix records' page path.
  */
 type EngineInput = {
     url: string;
     html?: undefined;
+    loaded?: boolean;
+    baseURL?: undefined;
 } | {
     html: string;
     url?: string;
+    loaded?: undefined;
+    baseURL?: undefined;
+}
+/**
+ * Visitor HTML (the widget's capture): served AS the response for `baseURL`
+ * through the driver's `loadHtml`, with no fetch of the main document, so
+ * relative stylesheets, images and fonts load from the site and computed
+ * styles are real. Before serving, `<script>`, `<noscript>` and meta
+ * refresh are removed, every `on*` handler keeps its attribute with its text
+ * inside a comment (it runs nothing; detectors still read it), every
+ * `javascript:` URL becomes `javascript:void(0)`, and a relative
+ * `<base href>` is made absolute against `baseURL` (unless `scripts: true`:
+ * served as captured). Only stylesheets, fonts and images load
+ * (`htmlRequestPolicy`). Stylesheets and fonts are waited for (8 s bound),
+ * then CSS animations are put at their end state (carousels excepted) and
+ * frozen, before the scan. `viewport` sets the page size first.
+ * A driver without `loadHtml` fails closed: nothing is loaded or scanned,
+ * `stats.input` is 'html-blank' and `stats.errors` says why.
+ */
+ | {
+    html: string;
+    baseURL: string;
+    scripts?: boolean;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    url?: undefined;
+    loaded?: undefined;
 };
 interface EngineOptions {
-    /** Highest WCAG level reported. Default 'AA'. */
+    /**
+     * Highest WCAG level reported. Default 'AA'. At 'A'/'AA' a fix is emitted
+     * only when its write remedies a WCAG 2.2 criterion at that level
+     * (guards/aaFixGate); findings are reported either way.
+     */
     level?: 'A' | 'AA' | 'AAA';
+    /**
+     * Also run core's experimental best-practice checks (default false):
+     * adjacent_redundant_link, missing_button_type, decorative_image_with_title,
+     * nested_landmark. They fail no WCAG 2.2 A/AA criterion, so the default run
+     * reports none of them. Passed to scan() as `experimental`.
+     */
+    includeBestPractice?: boolean;
+    /**
+     * Post-fix verification (default true): the structural fixers run, every
+     * fix is applied to the page, axe runs again and a fix that introduces a
+     * violation is dropped; the page is restored. false: never-harm only, no
+     * structural fixes, `verification` absent.
+     */
+    verify?: boolean;
+    /** Axe runs verification may spend isolating regressions. Default 40. */
+    verifyMaxAxeRuns?: number;
     /** HTTP status of the main document when the caller navigated. */
     mainStatus?: number;
     /**
@@ -151,30 +258,115 @@ interface EngineFix {
     /** What the fix rests on: the finding's message and the element markup. */
     evidence: string;
     engineVersion: string;
+    /**
+     * Post-fix verification: 'verified' (applied on the page, axe found no new
+     * violation on it, its ancestors or descendants); 'not_verifiable' (a
+     * manifest operation that is not an attribute write, or verification could
+     * not run: `stats.verify.error`). Rejected fixes are not emitted. Absent
+     * with `opts.verify: false`.
+     */
+    verification?: 'verified' | 'not_verifiable';
 }
 /** One reported finding (scan()'s issue row). */
 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.
+ */
+interface EngineFinding {
+    /** The issue row's id (`issues[k].id`). */
+    id: string;
+    selector: string;
+    /** Attribute the fix targets (alt, aria-label, role, style…). */
+    attribute: string;
+    /** What the element has now ('' when missing). */
+    currentValue: string;
+    issueType: string;
+    wcag: string;
+    /** The detector's context: visible text, nearby heading, parent tag, href. */
+    context: string;
+    /** The value must be written by a model (alt text, a label). */
+    needsAI: boolean;
+    /** The detector's known value, as the detector produced it (style values keep `!important`). Absent: no known value. */
+    fixValue?: string;
+    /** Image source, for alt text written from the image. */
+    imageSrc?: string;
+    /** The element's outer HTML, first 300 characters. */
+    outerHtml?: string;
+    /** Must not auto-apply: the detector marked the verdict uncertain (`needsReview`) or the fix not mechanical (`manualFix`). */
+    needsReview: boolean;
+    /** The detector's reason for review. */
+    reviewReason?: string;
+    /** State pseudo-class the detector's style fix applies in (`:focus-visible`); `selector` names the element at rest. */
+    pseudo?: string;
+}
 
 interface EngineStats {
     engineVersion: string;
-    input: 'url' | 'snapshot';
+    /**
+     * 'loaded': the caller's page was scanned as it was, with no navigation.
+     * 'html': visitor html served at its baseURL; 'html-blank': visitor html
+     * refused, unscanned, because the driver had no `loadHtml` to hold the
+     * request policy.
+     */
+    input: 'url' | 'loaded' | 'snapshot' | 'html' | 'html-blank';
     ms: number;
     deterministic: {
         issues: number;
         bySource: Record<string, number>;
         engineWarnings: string[];
     };
+    /**
+     * Fix bookkeeping. Every candidate is either emitted or in `rejected`:
+     * `candidates === emitted + rejected.length === emitted + sum(rejectedBy*)`.
+     * `candidates` includes the structural fixes (`structuralCandidates` of them).
+     * `rejectedBySelector`: the selector matched no element (or did not parse, or
+     * could not be checked) on the page at fix time, why `selector_unmatched...`.
+     * `rejectedByDuplicate`: a structural fix whose attribute another fix writes,
+     * or a detector candidate whose (selector, attribute) an earlier candidate of
+     * another issue type already writes (why `duplicate_candidate`). Only
+     * candidates that passed the validator and the A/AA gate take part, so a
+     * 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`.
+     */
     fixes: {
         candidates: number;
+        structuralCandidates: number;
         emitted: number;
         rejectedByValidator: number;
+        rejectedByGate: number;
         rejectedByHidingGuard: number;
+        rejectedBySelector: number;
+        rejectedByDuplicate: number;
+        rejectedByEmptyValue: number;
+        rejectedByNeverHarm: number;
+        rejectedByVerify: number;
         rejected: Array<{
             sel: string;
             attr: string;
             why: string;
         }>;
     };
+    /**
+     * Post-fix verification. `structural`: structural fixes that joined the
+     * batch. `verified` / `rejected` / `notVerifiable`: per-fix outcomes
+     * (rejected fixes are not emitted). `axeRuns` includes the pre-fix run.
+     */
+    verify: {
+        ran: boolean;
+        skipped?: string;
+        error?: string;
+        structural: number;
+        verified: number;
+        rejected: number;
+        notVerifiable: number;
+        axeRuns: number;
+        ms: number;
+    };
     /** No agent stage yet: always `ran: false`, and `skipped` says why. */
     agent: {
         ran: false;
@@ -197,6 +389,8 @@ interface EngineResult {
     issues: EngineIssue[];
     incomplete: EngineIssue[];
     fixes: EngineFix[];
+    /** The detector record of each WebAbility issue (see EngineFinding). */
+    findings: EngineFinding[];
     internal_bugs: InternalBug[];
     stats: EngineStats;
     /** Verdicts of core's in-scan judge (`opts.scan.judge`) on findings the engines could not decide. */
@@ -237,18 +431,39 @@ declare function toPageLike(page: Page, fallbackUrl: string): PageLike;
  * are removed, so the snapshot cannot run its scripts or navigate the page on
  * load.
  *
- * Inline event-handler attributes (`onclick`, `onerror`…) are KEPT: detectors
- * read their text (missingRoles, linkWarnings, targetSize, timingAndInput). An
- * `<img onerror>` can therefore still run when the snapshot loads; isolating
- * that (no egress, or JavaScript off) is the driver's job, as stated on
- * `Page`.
+ * Snapshot input keeps inline event-handler attributes (`onclick`,
+ * `onerror`…): detectors read their text (missingRoles, linkWarnings,
+ * targetSize, timingAndInput). An `<img onerror>` can therefore still run when
+ * the snapshot loads; isolating that (no egress, or JavaScript off) is the
+ * driver's job, as stated on `Page`.
+ *
+ * `visitor` (visitor HTML, `{ html, baseURL }`) also removes `<noscript>`
+ * (tag-manager and pixel fallbacks would fire fake pageviews), `srcdoc` and
+ * `data:` frames; comments out every `on*` handler (the attribute and its
+ * text stay for the detectors that read them); turns every `javascript:` URL
+ * into `javascript:void(0)`; and makes a `<base href>` absolute against
+ * `baseUrl` (a site's `<base href="/">` resolves against about:blank
+ * otherwise).
  *
  * With `baseUrl` and a driver `loadHtml`, the cleaned HTML is served at
- * `baseUrl`, so `location` is the live page's (detectors compare links with
- * `location.origin`/`pathname`). Without `loadHtml` the document stays on
- * about:blank with a `<base href>`; the engine names that in `stats.warnings`.
+ * `baseUrl` under `policy`, so `location` is the live page's (detectors
+ * compare links with `location.origin`/`pathname`); the returned `release`
+ * removes the policy and must run once the scan is done. A served document
+ * carries a one-off marker (a comment before the doctype, which keeps
+ * standards mode and touches no element), checked and removed after the load,
+ * on the sanitized and the `scripts` path alike: a caller's interception that
+ * answered the navigation itself (the live page from the network) is an
+ * error, never a silent scan of something else. Without `loadHtml` the
+ * document stays on about:blank with a `<base href>` (`served: false`).
  */
-declare function loadSnapshot(page: Page, html: string, baseUrl?: string): Promise<void>;
+declare function loadSnapshot(page: Page, html: string, baseUrl?: string, opts?: {
+    scripts?: boolean;
+    visitor?: boolean;
+    policy?: HtmlRequestPolicy;
+}): Promise<{
+    served: boolean;
+    release?: () => Promise<void>;
+}>;
 /** The Playwright page members the adapter reads (structural: no playwright import). */
 interface PlaywrightPageLike {
     goto(url: string, opts?: any): Promise<any>;
@@ -267,6 +482,10 @@ interface PlaywrightPageLike {
     }): Promise<unknown>;
     route?(url: (u: URL) => boolean, handler: (route: any) => unknown): Promise<void>;
     unroute?(url: (u: URL) => boolean, handler?: (route: any) => unknown): Promise<void>;
+    setViewportSize?(size: {
+        width: number;
+        height: number;
+    }): Promise<void>;
 }
 /**
  * A Playwright page as the engine's Page. Playwright's evaluate takes one
@@ -274,6 +493,50 @@ interface PlaywrightPageLike {
  * so `location` is the live page's.
  */
 declare function fromPlaywright(p: PlaywrightPageLike): Page;
+/** The puppeteer-core page members the adapter reads (structural: no puppeteer import). */
+interface PuppeteerPageLike {
+    goto(url: string, opts?: any): Promise<any>;
+    evaluate(fn: any, ...args: any[]): Promise<any>;
+    screenshot(opts?: any): Promise<Uint8Array | string>;
+    keyboard: {
+        press(key: string): Promise<void>;
+    };
+    url(): string;
+    waitForFunction?(fn: any, opts?: {
+        timeout?: number;
+    }, ...args: any[]): Promise<unknown>;
+    addScriptTag?(opts: {
+        content?: string;
+        url?: string;
+    }): Promise<unknown>;
+    setRequestInterception?(on: boolean): Promise<void>;
+    setViewport?(v: {
+        width: number;
+        height: number;
+    }): Promise<void>;
+    on?(event: 'request', handler: (req: any) => void): unknown;
+    off?(event: 'request', handler: (req: any) => void): unknown;
+}
+/**
+ * A puppeteer-core page as the engine's Page. Puppeteer's evaluate takes every
+ * argument; its screenshot has no `animations` option (dropped). It has no
+ * waitForLoadState: with `waitForFunction` the adapter waits for
+ * `document.readyState === 'complete'`.
+ *
+ * `loadHtml` only with `interceptDocument`. It joins the page's request
+ * interception as one more cooperative handler (default priority), so the
+ * caller's own guards (the platform's private-target, own-widget and bandwidth
+ * guards) still see every request and their aborts win. A caller handler in
+ * legacy mode (no priority) resolves requests before it can: the served-marker
+ * check then fails the load instead of scanning the live page. Release turns
+ * interception off again unless `page.__keepRequestInterception` is set (the
+ * platform's session-long owners set it). Without `interceptDocument` a
+ * snapshot stays on about:blank, named in `stats.warnings`.
+ * No `playwrightPage`: axe runs in the top document only.
+ */
+declare function fromPuppeteer(p: PuppeteerPageLike, opts?: {
+    interceptDocument?: boolean;
+}): Page;
 
 /**
  * Fix Manifest Validator — Three-Layer Safety Architecture
@@ -350,11 +613,6 @@ declare function classifyFixRisk(fix: {
     attribute: string;
     value: string;
 }): FixClassification;
-/**
- * `issueType` + `context` are optional: when the caller has the element's
- * stored context (visible text), the WCAG 2.5.3 Label-in-Name rule runs on
- * aria-label fixes (see labelInNameRule.ts). Without them the check is a no-op.
- */
 declare function validateFix(fix: {
     selector: string;
     attribute: string;
@@ -585,4 +843,4 @@ interface SelectorQualityResult {
 declare const BARE_TAGS: Set<string>;
 declare function scoreSelectorQuality(selector: string): SelectorQualityResult;
 
-export { BARE_TAGS, type EngineFix, type EngineInput, type EngineIssue, type EngineOptions, type EngineResult, type EngineStats, FORM_CONTROL_ROLES, type HazardElementView, InternalBug, LABEL_IN_NAME_JS, type Model, type ModelRequest, type ModelResponse, type Page, type PlaywrightPageLike, type ProtectedScope, SERVED_FIX_KEYS, classifyFixRisk, detectPageLanguage, dropHazardousHidingFixes, foldContains, foldLabel, fromPlaywright, isHidingFix, isHtmlLangFix, isInteractiveOrContainsFocusable, isLabelText, labelContainsText, labelInNameCheck, languageFromText, languageFromUrl, loadSnapshot, normalizeVisibleText, parseContext, primaryLanguage, runEngine, scoreSelectorQuality, selectorParses, toPageLike, validateAttribute, validateFix, validateRoleValue, validateSelector, validateSelectorForAttribute, validateTextValue };
+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 };