@webability/core 1.8.0 → 1.10.0

package/dist/engine.d.ts

@@ -0,0 +1,588 @@
+import { c as ScanIssue, m as JudgeOptions, I as InternalBug, q as JudgedEntry, P as PageLike } from './types-fjs6XhzQ.js';
+
+/**
+ * The one engine's contract: two injected drivers in, one result out.
+ *
+ * runEngine never launches a browser, calls a provider or touches storage on
+ * its own (the bundle carries scan()'s URL-string branch, which it never
+ * takes). A consumer passes a `Page` (Playwright, Puppeteer, a sandbox) and,
+ * for agent tasks, a `Model` (any OpenAI-compatible chat call). Everything the
+ * engine reads or writes goes through those two objects. No agent stage runs
+ * yet: the rubric agent for judgment criteria is its own step.
+ */
+
+/**
+ * Minimal browser page. A Playwright page needs a thin adapter
+ * (`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.
+ */
+interface Page {
+    /** A Response-like return (`status()`) is read for the main document's HTTP status. */
+    goto(url: string, opts?: {
+        waitUntil?: any;
+        timeout?: number;
+    }): Promise<unknown>;
+    evaluate<R>(pageFunction: string | ((...args: any[]) => R | Promise<R>), ...args: any[]): Promise<R>;
+    /** Must honour `clip`, `fullPage` and `animations`: pixel contrast crops by `clip`. */
+    screenshot(opts?: {
+        type?: 'png';
+        encoding?: 'base64';
+        clip?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        fullPage?: boolean;
+        animations?: 'disabled' | 'allow';
+    }): Promise<Uint8Array | string>;
+    /** focusVisible presses Tab to put the browser in keyboard modality. */
+    keyboard: {
+        press(key: string): Promise<void>;
+    };
+    /** Wait for the document's `load` event (render settle). Absent: settle waits on animations only, so late iframes/media may be missed. */
+    waitForLoadState?(state: 'load', opts?: {
+        timeout?: number;
+    }): Promise<void>;
+    /** Current URL. Absent: the input URL is used. */
+    url?(): string;
+    /**
+     * 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.
+     */
+    loadHtml?(html: string, url: string): Promise<void>;
+    /** Script injection (Playwright/Puppeteer). Absent: string `evaluate` is used. */
+    addScriptTag?(opts: {
+        content?: string;
+        url?: string;
+    }): Promise<unknown>;
+    /**
+     * The live Playwright Page. axe's frame-aware run (AxeBuilder) needs it to
+     * scan inside iframes. Absent: axe runs in the top document only.
+     */
+    playwrightPage?(): unknown;
+}
+/** One OpenAI-compatible chat call. `signal` aborts the HTTP request at the engine's deadline. */
+interface ModelRequest {
+    model?: string;
+    messages: any[];
+    tools?: any[];
+    max_tokens: number;
+    temperature?: number;
+    reasoning_effort?: 'low' | 'medium' | 'high';
+}
+interface ModelResponse {
+    message: {
+        content?: string | null;
+        tool_calls?: any[];
+    };
+    /** OpenAI usage; `cost` (USD) when the gateway reports it. */
+    usage?: {
+        prompt_tokens?: number;
+        completion_tokens?: number;
+        prompt_tokens_details?: {
+            cached_tokens?: number;
+        };
+        cost?: number;
+    };
+}
+interface Model {
+    chat(req: ModelRequest, opts?: {
+        signal?: AbortSignal;
+    }): 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.
+ */
+type EngineInput = {
+    url: string;
+    html?: undefined;
+} | {
+    html: string;
+    url?: string;
+};
+interface EngineOptions {
+    /** Highest WCAG level reported. Default 'AA'. */
+    level?: 'A' | 'AA' | 'AAA';
+    /** HTTP status of the main document when the caller navigated. */
+    mainStatus?: number;
+    /**
+     * Knobs of the deterministic layer (core scan()): scope to a subtree,
+     * dismiss cookie banners first (default false), the axe tags, the render
+     * settle, and core's in-scan AI judge for undecided findings. The judge
+     * makes its own HTTP calls (not through `Model`); leave it unset for a run
+     * with no model traffic.
+     */
+    scan?: {
+        rootSelector?: string;
+        dismissModals?: boolean;
+        judge?: JudgeOptions;
+        /** axe-core tags (default: core's WCAG A/AA set). */
+        wcagTags?: string[];
+        /** scan()'s render settle: false skips it (a DOM with no layout or animation). */
+        settle?: boolean;
+    };
+}
+/**
+ * One fix record. The first five keys are the served manifest's wire keys
+ * (widget reads `sel`/`attr`/`val`/`mode`/`p`); the rest are provenance the
+ * Worker and the safety lookups need.
+ */
+interface EngineFix {
+    sel: string;
+    /** The selector exactly as the producing engine emitted it, before any rewrite. Equal to `sel` when nothing rewrote it. */
+    originalSel: string;
+    attr: string;
+    val: string;
+    /** Served manifest mode. Engine fixes are plain attribute writes: 'attr'. */
+    mode: 'attr';
+    /** Page path the fix is scoped to (from the input URL), '/' when the input had none. */
+    p: string;
+    issueType: string;
+    wcag: string;
+    /** What the fix rests on: the finding's message and the element markup. */
+    evidence: string;
+    engineVersion: string;
+}
+/** One reported finding (scan()'s issue row). */
+type EngineIssue = ScanIssue;
+
+interface EngineStats {
+    engineVersion: string;
+    input: 'url' | 'snapshot';
+    ms: number;
+    deterministic: {
+        issues: number;
+        bySource: Record<string, number>;
+        engineWarnings: string[];
+    };
+    fixes: {
+        candidates: number;
+        emitted: number;
+        rejectedByValidator: number;
+        rejectedByHidingGuard: number;
+        rejected: Array<{
+            sel: string;
+            attr: string;
+            why: string;
+        }>;
+    };
+    /** No agent stage yet: always `ran: false`, and `skipped` says why. */
+    agent: {
+        ran: false;
+        skipped: string;
+    };
+    /** Storage operations the engine performed. Always 0: the package has no storage. */
+    io: {
+        dbRows: 0;
+        r2Gets: 0;
+        r2Puts: 0;
+        kvOps: 0;
+    };
+    /** Degraded stages (a failed load, a guard that could not run). A result with errors is partial. */
+    errors: string[];
+    /** Capabilities the injected Page lacked and what was skipped because of it. */
+    warnings: string[];
+}
+interface EngineResult {
+    url: string;
+    issues: EngineIssue[];
+    incomplete: EngineIssue[];
+    fixes: EngineFix[];
+    internal_bugs: InternalBug[];
+    stats: EngineStats;
+    /** 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. */
+    blocked?: {
+        reason: string;
+        signal?: string;
+        status?: number;
+        vendor?: string;
+    };
+}
+/** The served manifest wire keys, in order. */
+declare const SERVED_FIX_KEYS: readonly ["sel", "attr", "val", "mode", "p"];
+
+declare function runEngine(args: {
+    page: Page;
+    model?: Model;
+    input: EngineInput;
+    opts?: EngineOptions;
+}): Promise<EngineResult>;
+
+/**
+ * Driver adapters: the injected Page as core's PageLike, and a DOM snapshot
+ * loaded into it.
+ */
+
+/**
+ * core's scan() runs on a PageLike (evaluate + addScriptTag + url). A driver
+ * without addScriptTag gets script content through a string `evaluate`. A
+ * script by URL is refused; no scan() stage loads one, so nothing is lost.
+ */
+declare function toPageLike(page: Page, fallbackUrl: string): PageLike;
+/**
+ * Load a DOM snapshot as the page's document, with no network fetch of the
+ * page itself. The HTML is parsed by DOMParser on about:blank; `<script>`
+ * elements of any namespace (HTML or SVG) and `<meta http-equiv=refresh>`
+ * 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`.
+ *
+ * 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`.
+ */
+declare function loadSnapshot(page: Page, html: string, baseUrl?: string): Promise<void>;
+/** The Playwright page members the adapter reads (structural: no playwright import). */
+interface PlaywrightPageLike {
+    goto(url: string, opts?: any): Promise<any>;
+    evaluate(fn: any, arg?: any): Promise<any>;
+    screenshot(opts?: any): Promise<Uint8Array>;
+    keyboard: {
+        press(key: string): Promise<void>;
+    };
+    waitForLoadState?(state: 'load', opts?: {
+        timeout?: number;
+    }): Promise<void>;
+    url(): string;
+    addScriptTag?(opts: {
+        content?: string;
+        url?: string;
+    }): Promise<unknown>;
+    route?(url: (u: URL) => boolean, handler: (route: any) => unknown): Promise<void>;
+    unroute?(url: (u: URL) => boolean, handler?: (route: any) => unknown): Promise<void>;
+}
+/**
+ * A Playwright page as the engine's Page. Playwright's evaluate takes one
+ * argument. With `route`, a snapshot is served at its own URL (`loadHtml`),
+ * so `location` is the live page's.
+ */
+declare function fromPlaywright(p: PlaywrightPageLike): Page;
+
+/**
+ * Fix Manifest Validator — Three-Layer Safety Architecture
+ *
+ * Every fix passes through three layers before reaching the DB:
+ *
+ *   Layer 1: Structural validation (selector, attribute, value safety)
+ *   Layer 2: Protected element check (don't touch third-party/admin/consent UI)
+ *   Layer 3: Risk classification (additive vs modifier vs destructive)
+ *
+ * Layer 3 output feeds into the repository's status logic:
+ *   - additive   → normal confidence gate (>= 0.85 → approved)
+ *   - modifier   → always 'pending' (human review required)
+ *   - destructive → rejected (unless source is 'manual')
+ */
+interface ValidationResult {
+    ok: boolean;
+    reason?: string;
+}
+type FixRiskTier = 'additive' | 'modifier' | 'destructive';
+interface FixClassification {
+    tier: FixRiskTier;
+    reason: string;
+}
+/**
+ * Validate a `role` attribute value.
+ *   - case-sensitive: must be lowercase (rejects "Main", "Breadcrumb", "Navigation")
+ *   - every space-separated token must be a real concrete ARIA role
+ *   - empty / whitespace-only is invalid
+ */
+declare function validateRoleValue(value: string): ValidationResult;
+/**
+ * The one fix the `<html>` root takes: `lang` (WCAG 3.1.1 — the document
+ * language lives on `<html>` and nowhere else). afe1654ed rejected every bare
+ * `html` selector as structural hardening (its case: `html { style:
+ * filter:invert(1) }` repaints every page); `lang` writes no style, no markup
+ * and no behaviour, so it is the single exception. Every other attribute on
+ * `html` stays rejected. Exact attribute name, no case folding.
+ */
+declare function isHtmlLangFix(selector: string | null | undefined, attribute: string | null | undefined): boolean;
+/**
+ * Selector check for a fix whose attribute is known. `html` + `lang` passes
+ * (the root is one element, never protected UI); everything else takes
+ * validateSelector, where a bare `html` is still rejected.
+ */
+declare function validateSelectorForAttribute(selector: string, attribute: string, protectedScope?: ProtectedScope): ValidationResult;
+/**
+ * Would the browser's querySelectorAll parse this selector? (LEDGER row 78 —
+ * served selectors that throw are swallowed per fix by the widget and stay
+ * approved forever.) Two layers: the character/escape rules below refuse an
+ * unescaped `/`, `%`, `!` or a Tailwind `:variant` exactly as the browser
+ * does; then a real tokeniser (css-what) refuses unbalanced brackets, an
+ * unterminated string, an empty `:not()`, a dangling `#`, and `astParses`
+ * refuses what css-what tolerates but the browser does not (`#hero >`,
+ * `a||b`, `li:nth-child(2n+)`, `button::part()`).
+ */
+declare function selectorParses(selector: string): boolean;
+/** Which protected-element registry a writer consults. The scan path runs the
+ *  full registry against a DOM it rendered; the ingest path keeps the narrower
+ *  admin/overlay check because the full registry's SUBSTRING vendor patterns
+ *  (crisp-, hubspot-) false-match attribute VALUES in live approved fixes
+ *  (img[src=".../apple-cranberry-crisp-…jpg"], body.hubspot-disable-focus-styles). */
+type ProtectedScope = 'full' | 'dead-region';
+declare function validateSelector(selector: string, protectedScope?: ProtectedScope): ValidationResult;
+declare function validateAttribute(attr: string): ValidationResult;
+declare function validateTextValue(value: string, attribute?: string): ValidationResult;
+/**
+ * Classify a fix into a risk tier:
+ *   - additive: adds information that wasn't there (aria-label, alt, role, scope, etc.)
+ *   - modifier: changes visibility/interactivity (aria-hidden, tabindex, style)
+ *   - destructive: removes or empties functional attributes
+ */
+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;
+    value: string;
+    issueType?: string | null;
+    context?: string | null;
+}, protectedScope?: ProtectedScope): ValidationResult;
+
+/**
+ * Hiding-hazard guard
+ * ───────────────────
+ * A single, detector-agnostic guard that prevents the scan from EVER emitting a
+ * fix that would remove an interactive control from the accessibility tree.
+ *
+ * The hazard: `aria-hidden="true"`, `role="presentation"`, or `role="none"` on
+ * an element that is itself interactive (a real `<a href>`, button, form
+ * control, interactive ARIA role, or `tabindex >= 0`) — or that CONTAINS a
+ * focusable descendant. Applied to, say, a "Sign up" CTA link, this hides the
+ * button from screen-reader users AND leaves it keyboard-focusable-but-invisible
+ * (a WCAG 4.1.2 hidden-focusable). That is the exact "overlay makes it worse"
+ * failure — the worst thing an accessibility product can ship.
+ *
+ * Several detectors CAN produce this in edge cases (decorative-icon size/class
+ * heuristics, sr-only-container keyboard-trap heuristics, adjacent-identical-
+ * link dedup). Rather than patch each one, this guard runs once over the merged
+ * output against the LIVE DOM, so it covers every detector — present and future
+ * — from one place. Correctly-decorative targets (non-interactive, no focusable
+ * descendants) are untouched.
+ */
+
+/** The fields of a fix row the guard reads. */
+interface HidingCandidate {
+    selector: string;
+    attribute?: string;
+    fixValue?: string;
+}
+/** Does this fix remove its target (and subtree) from the accessibility tree? */
+declare function isHidingFix(attribute: string | undefined, fixValue: string | undefined): boolean;
+/**
+ * Minimal element view — satisfied by a real DOM Element in the browser and by
+ * a fake in tests. The browser pass mirrors this rule's LOGIC (page.evaluate
+ * can't reference this import), but the role list + focusable selector are
+ * passed IN as arguments, so those constants have a single source of truth.
+ */
+interface HazardElementView {
+    tagName: string;
+    getAttribute(name: string): string | null;
+    hasAttribute(name: string): boolean;
+    querySelector(sel: string): unknown | null;
+    querySelectorAll?(sel: string): ArrayLike<HazardElementView>;
+    textContent?: string | null;
+    isContentEditable?: boolean;
+}
+/**
+ * True when hiding this element would swallow a control: it is itself
+ * interactive/focusable, OR it contains a focusable descendant, OR it is or
+ * contains visually-hidden text (the sr-only pattern). That text exists only
+ * for screen-reader users, often as an icon's or link's only name; hiding it
+ * leaves them nothing (B13). `isVisuallyHidden` is the DOM fact (the live
+ * pass measures geometry and clipping); without it the third check is off.
+ */
+declare function isInteractiveOrContainsFocusable(el: HazardElementView, isVisuallyHidden?: (e: HazardElementView) => boolean): boolean;
+/**
+ * Drop every hiding fix whose live target is interactive or contains a
+ * focusable descendant. One page.evaluate over just the hiding candidates.
+ * Fails CLOSED for hiding fixes only: when the check cannot run, every hiding
+ * candidate is dropped (other fixes pass) and `onError` gets the reason.
+ */
+declare function dropHazardousHidingFixes<T extends HidingCandidate>(page: Pick<Page, 'evaluate'>, issues: T[], onError?: (err: Error) => void): Promise<T[]>;
+
+/**
+ * The subset of INTERACTIVE_ROLES that behave like a native form-control
+ * input (something a <fieldset> groups) — excludes navigational/structural
+ * roles (button, link, menuitem*, tab, option, treeitem, gridcell) that are
+ * interactive but not "controls" a fieldset legend would describe.
+ *
+ * fieldsetLegend.detector.ts's ARIA form-control count must inline an
+ * identical literal rather than import this — its detector function is
+ * serialized via page.evaluate/toString and cannot reference an imported
+ * binding at runtime (same constraint as the kernel). Only
+ * test/fieldsetLegend.formControlRoles.test.ts actually reads this export,
+ * to pin that inline literal against drift.
+ */
+declare const FORM_CONTROL_ROLES: Set<string>;
+/** Is the visible text a label the rule applies to? Shared with the vector. */
+declare const isLabelText: (text: string) => boolean;
+/** Does `value` contain `text` as a whole phrase (see labelContainsText in the kernel)? */
+declare const labelContainsText: (value: string, text: string) => boolean;
+/** Widget normalisation: trim, collapse whitespace. Case-folding happens at compare time. */
+declare const normalizeVisibleText: (text: string) => string;
+/**
+ * The same contract as browser-side JS for the scan detector, which runs under
+ * page.evaluate and cannot import (labelInName.detector.ts; injected by
+ * index.ts with the other helpers, declared in browser-globals.d.ts). Built
+ * from the very functions above, so there is one implementation, not a copy.
+ */
+declare const LABEL_IN_NAME_JS: string;
+interface LabelInNameInput {
+    attribute: string;
+    value: string;
+    issueType?: string | null;
+    /** The stored `fix_manifests.context` (JSON from the widget/Worker, or the
+     *  scan detectors' `visible: … | aria-label: …` pipe string). */
+    context?: string | null;
+}
+interface LabelInNameResult {
+    ok: boolean;
+    reason?: string;
+}
+/** Lowercase, strip diacritics, collapse everything that is not a letter or digit to one space. */
+declare function foldLabel(s: string): string;
+/** Does `haystack` contain `needle` as a whole phrase after folding? */
+declare function foldContains(haystack: string, needle: string): boolean;
+interface ParsedContext {
+    tag: string;
+    role: string;
+    text: string;
+    /** The element's CURRENT accessible name as the detector saw it (Worker `currentAriaLabel` / `attrs['aria-label']`, scan-detector `aria-label:`); '' when the context carries none. */
+    ariaLabel: string;
+}
+/**
+ * The stored `fix_manifests.context` in its three generations: Worker JSON
+ * (optionally wrapped as `{original: "<json>", validationFailure}` by the AI
+ * validator), and the scan detectors' `visible: … | aria-label: …` pipe string.
+ */
+declare function parseContext(context: string | null | undefined): ParsedContext;
+/**
+ * Does this aria-label fix satisfy Label in Name? `ok:true` also when the rule
+ * does not apply (other attribute, non-interactive element, no visible text or
+ * symbol-only text) — callers treat only `ok:false` as a reject.
+ */
+declare function labelInNameCheck(fix: LabelInNameInput): LabelInNameResult;
+
+/**
+ * Page language detection for the missing `<html lang>` fix (WCAG 3.1.1).
+ *
+ * One file, two byte-identical copies: fix-manifest-api src/detectors/pageLanguage.ts
+ * and platform api/services/fixDetectors/pageLanguage.ts. A pinned-sha256 test
+ * in each repo (pageLanguage-drift) fails on any edit to one copy alone: change
+ * both, then update both pins in the same pair of PRs.
+ *
+ * The fix value is the page's REAL language, or no fix at all. A wrong `lang`
+ * makes the screen reader read the whole page with the wrong voice, which is
+ * worse than no `lang`. Every `html[lang]` row in prod carried "en" (72/72,
+ * 15 of them on German, Dutch, Spanish, French, Danish, Chinese and Italian
+ * pages, 2026-10-09) because the AI fill only saw the page title and domain.
+ *
+ * Inputs are facts the pipeline already holds at scan/ingest time: the page
+ * URL, the page text, and (when the caller can read them) the language the
+ * page declares in xml:lang / content-language / og:locale / body[lang] /
+ * a self-referencing hreflang. Pure function: no network, no AI, no per-site
+ * data. Runs once per page at detection time; the widget only applies the
+ * stored value.
+ *
+ * Decision:
+ *   1. Text decides when it is confident (function-word frequency for Latin
+ *      script languages, the writing system for scripts only one language
+ *      uses). Any declared or URL signal that disagrees → null.
+ *   2. Text not confident: declared signals that all agree decide, unless
+ *      the text leans to another language or rules the declared one out.
+ *   3. A URL code (language subdomain or first path segment) decides only
+ *      when the text leans the same way and does not rule it out.
+ *   4. Otherwise null — the caller emits NO row.
+ *
+ * Function-word evidence is measured against ALL page tokens, not only the
+ * tokens we recognise. A language's words make up 15–30% of the tokens of a
+ * real page in that language (home pages, nav included: 0.157–0.321 on 18
+ * live pages, 2026-10-10). A page in a language with no list here (Romanian,
+ * Indonesian, Turkish, Finnish, Hungarian) shares a few short words with the
+ * listed ones but reaches ≈0.10 at most for any of them, so it is never confident —
+ * and it rules out every listed language, so a declared "en" on such a page
+ * is not trusted either. Languages close enough to a listed one to clear the
+ * floor on their own (Catalan ~ Spanish, Galician ~ Portuguese, Afrikaans ~
+ * Dutch) carry their own list, so the words that tell them apart decide.
+ */
+type LangSource = 'text' | 'declared' | 'url';
+interface PageLanguageInput {
+    /** Page URL (or the canonical page key). */
+    url?: string | null;
+    /** Visible page text (any length; only the first 20k chars are read). */
+    text?: string | null;
+    /** Languages the page declares outside `<html lang>`: xml:lang, content-language, meta language, og:locale, body[lang], self hreflang. */
+    declared?: Array<string | null | undefined>;
+}
+interface PageLanguageResult {
+    /** Primary BCP-47 subtag, lowercase ("de", "nl", "zh"). */
+    lang: string;
+    source: LangSource;
+}
+interface TextVerdict {
+    /** Language the text points to, if any. */
+    lean: string | null;
+    /** True when the lean is strong enough to decide alone. */
+    confident: boolean;
+    /** Listed languages the text rules out: enough tokens, and their function words stay under MIN_SHARE of them. */
+    ruledOut: Set<string>;
+}
+/** Primary subtag of a BCP-47-ish tag ("de-DE", "de_DE", "zh-Hans" → "de"/"zh"); '' when it is not a language code. */
+declare function primaryLanguage(tag: string | null | undefined): string;
+/** Language code carried by the URL: a language subdomain ("fr.shop.de") or first path segment ("/de/", "/zh-hans/"). */
+declare function languageFromUrl(url: string | null | undefined): string;
+/** What the page text says about its language. */
+declare function languageFromText(raw: string | null | undefined): TextVerdict;
+/** The page's language, or null when nothing settles it (→ emit no fix). */
+declare function detectPageLanguage(input: PageLanguageInput): PageLanguageResult | null;
+
+/**
+ * Selector Quality Scoring
+ *
+ * Scores CSS selectors on specificity and stability. Fixes with low-quality
+ * selectors are either rejected or forced to pending based on score.
+ *
+ * A selector that can match unintended elements is dangerous — it can hide
+ * content, strip functionality, or inject wrong labels on the wrong elements.
+ */
+interface SelectorQualityResult {
+    score: number;
+    reasons: string[];
+}
+/**
+ * Bare element tags that are too broad when used as the sole selector.
+ * `iframe` as a selector matches every iframe on the page.
+ *
+ * Exported so anything that judges a selector PART by this same universe
+ * (e.g. a comma-separated template row) imports this set instead of keeping
+ * a second hand-written copy that can silently drift (Pullfrog, #1025).
+ */
+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 };