nfunc-mcp 0.2.0 → 0.4.0

package/dist/mappers/psiAggregator.js

@@ -0,0 +1,293 @@
+/**
+ * Cross-run arithmetic.
+ *
+ * This module owns every number that describes the audit as a whole, because
+ * that is precisely where reading JSON by hand goes wrong. The manual Five
+ * Below report got "TBT fails on 22/22 pages" right and the direction of the
+ * CrUX CLS disagreement backwards, in the same document — the first is a count
+ * and the second is a comparison, and a human doing 26 files will eventually
+ * miss one. Everything here is computed so the report can quote rather than
+ * derive.
+ *
+ * It also owns the two redundancy rules, because both need the page set in
+ * view. A single-URL audit should still report every failing metric; the
+ * repetition only exists across a set.
+ */
+import { classifyVital, formatVitalValue, vitalLabel } from "./webVitalsMapper.js";
+/** A vital failing on at least this share of runs is a candidate for collapse. */
+const SYSTEMIC_THRESHOLD = 0.8;
+/**
+ * ...but only if it also varies little between pages.
+ *
+ * Ubiquity alone is not enough, and the first implementation of this rule got
+ * it wrong: it collapsed CLS, which fails on 25 of 25 Five Below runs but
+ * ranges 0.18 to 0.85 — a 4.7x spread that is the single most page-specific
+ * signal in the dataset. Collapsing it would have deleted the finding the
+ * whole tool exists to surface.
+ *
+ * A shared-code characteristic looks the same everywhere: INP fails on every
+ * page within a 2.1x band. A per-page defect that happens to be widespread
+ * does not. So collapse requires both — fails nearly everywhere *and* barely
+ * moves between pages.
+ */
+const SYSTEMIC_MAX_SPREAD = 2.5;
+/** Lab-only metrics with no field counterpart, needed for the universal-failure counts. */
+const LAB_THRESHOLDS = {
+    tbtMs: { label: "Total Blocking Time", good: 200, unit: "ms" },
+};
+const PRIORITY_RANK = { P1: 0, P2: 1, P3: 2 };
+function median(values) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+}
+function mean(values) {
+    return values.length === 0 ? 0 : Math.round(values.reduce((a, b) => a + b, 0) / values.length);
+}
+/**
+ * Rule 2 — component suppression.
+ *
+ * FCP is a component of LCP: if the largest element paints late, the first one
+ * usually did too. Across the Five Below batch the two co-occurred on 17 of 25
+ * runs and FCP never once reached P1, so an FCP finding alongside an LCP
+ * finding is two tickets describing one defect. The FCP measurement is kept as
+ * evidence on the LCP finding rather than discarded.
+ *
+ * TTFB is deliberately *not* treated this way. It fired on one run out of 25,
+ * which is the signature of a metric carrying independent information.
+ */
+export function suppressComponentFindings(findings) {
+    const lcp = findings.find((f) => f.evidence.audit_id === "crux.lcp");
+    const fcp = findings.find((f) => f.evidence.audit_id === "crux.fcp");
+    if (!lcp || !fcp)
+        return findings;
+    lcp.evidence = {
+        ...lcp.evidence,
+        supporting_fcp: fcp.evidence.value,
+        note: "First Contentful Paint is also below target; it is a component of this metric, not a separate defect.",
+    };
+    return findings.filter((f) => f !== fcp);
+}
+/**
+ * Rule 1 — systemic collapse.
+ *
+ * A vital rated below "good" on 80%+ of runs is describing the site, not any
+ * one page. INP failed on 25 of 25 Five Below runs with a 2.1x spread and a
+ * 316 ms median: twenty-five findings that each say "fix this page" when the
+ * true statement is "this site's interaction handling is uniformly mediocre".
+ *
+ * The threshold is deliberately well above a simple majority — a vital failing
+ * on half the pages is discriminating between them, and that is information
+ * worth keeping per page.
+ *
+ * Priority is the worst observed, not an average: a vital that is poor
+ * everywhere is not less urgent for being ubiquitous.
+ */
+export function collapseSystemicFindings(runs) {
+    const findings = [];
+    const collapsedVitals = [];
+    if (runs.length < 3)
+        return { findings, collapsedVitals };
+    const vitals = ["lcp", "inp", "cls", "fcp", "ttfb"];
+    for (const vital of vitals) {
+        // Only URL-level measurements can support a site-wide conclusion.
+        //
+        // Origin-level CrUX is *the same number* repeated for every page that falls
+        // back to it, so both tests below are guaranteed to pass on it: the failure
+        // rate is 100% and the spread is exactly 1.0x. That manufactured a
+        // "fails everywhere and varies little between pages" finding from what was
+        // literally one measurement copied across three runs. The spread gate is
+        // only meaningful over independent per-page data.
+        const measured = runs.filter((r) => r.field?.metrics[vital]?.source === "url");
+        if (measured.length < 3)
+            continue;
+        // Count runs that still carry a finding for this vital, not runs whose raw
+        // metric is below target. The two rules have to compose: FCP is folded into
+        // LCP by component suppression, and counting raw metrics resurrected it as
+        // a site-wide finding that per-page reporting had deliberately dropped.
+        const failing = measured.filter((r) => r.findings.some((f) => f.evidence.audit_id === `crux.${vital}`));
+        if (failing.length / measured.length < SYSTEMIC_THRESHOLD)
+            continue;
+        const values = failing.map((r) => r.field?.metrics[vital]?.p75 ?? 0);
+        // Spread gate. Guard against a zero floor, which would make any spread
+        // infinite and suppress the collapse for the wrong reason.
+        const low = Math.min(...values);
+        const high = Math.max(...values);
+        if (low > 0 && high / low > SYSTEMIC_MAX_SPREAD)
+            continue;
+        const worst = failing
+            .flatMap((r) => r.findings.filter((f) => f.evidence.audit_id === `crux.${vital}`))
+            .reduce((acc, f) => (PRIORITY_RANK[f.priority] < PRIORITY_RANK[acc] ? f.priority : acc), "P3");
+        const med = median(values);
+        const min = low;
+        const max = high;
+        collapsedVitals.push(vital);
+        findings.push({
+            priority: worst,
+            title: `${vitalLabel(vital)} is below target site-wide (${failing.length}/${measured.length} runs)`,
+            description: `Real users are below Google's ${vitalLabel(vital)} target on ` +
+                `${failing.length} of ${measured.length} audited page/device runs, with a median of ` +
+                `${formatVitalValue(vital, med)} and a range of ${formatVitalValue(vital, min)} to ` +
+                `${formatVitalValue(vital, max)}. Because it fails almost everywhere and varies little ` +
+                `between pages, this is a characteristic of the site's shared code rather than a defect ` +
+                `on any one template — fixing individual pages will not move it. Investigate the common ` +
+                `layer: the shared bundle, the third-party tags loaded on every page, or the base template.`,
+            evidence: {
+                audit_id: `crux.${vital}.systemic`,
+                value: formatVitalValue(vital, med),
+                failing_runs: failing.length,
+                total_runs: measured.length,
+                range: `${formatVitalValue(vital, min)}–${formatVitalValue(vital, max)}`,
+            },
+        });
+    }
+    return { findings, collapsedVitals };
+}
+/** Core Web Vitals verdict per run, field-first, matching the manual report's tiers. */
+function cwvVerdict(run) {
+    const core = ["lcp", "inp", "cls"];
+    let failing = 0;
+    for (const vital of core) {
+        const fieldMetric = run.field?.metrics[vital];
+        if (fieldMetric) {
+            if (classifyVital(vital, fieldMetric.p75) !== "good")
+                failing++;
+            continue;
+        }
+        // INP has no lab fallback, so a run with no field INP is scored on what exists.
+        const labValue = vital === "lcp" ? run.lab.lcpMs : vital === "cls" ? run.lab.cls : null;
+        if (labValue !== null && classifyVital(vital, labValue) !== "good")
+            failing++;
+    }
+    if (failing === 0)
+        return "pass";
+    return failing === 1 ? "needs_improvement" : "fail";
+}
+export function aggregate(runs) {
+    const strategies = [...new Set(runs.map((r) => r.strategy))];
+    const by_strategy = {};
+    for (const strategy of strategies) {
+        const scores = runs
+            .filter((r) => r.strategy === strategy)
+            .map((r) => r.scores.performance)
+            .filter((n) => typeof n === "number");
+        if (scores.length === 0)
+            continue;
+        by_strategy[strategy] = {
+            performance: { mean: mean(scores), min: Math.min(...scores), max: Math.max(...scores) },
+        };
+    }
+    const templateIds = [...new Set(runs.map((r) => r.template))];
+    const by_template = templateIds.map((template) => {
+        const group = runs.filter((r) => r.template === template);
+        const performance_mean = {};
+        for (const strategy of strategies) {
+            const scores = group
+                .filter((r) => r.strategy === strategy)
+                .map((r) => r.scores.performance)
+                .filter((n) => typeof n === "number");
+            if (scores.length > 0)
+                performance_mean[strategy] = mean(scores);
+        }
+        const worst = [...group].sort((a, b) => (a.scores.performance ?? 100) - (b.scores.performance ?? 100))[0];
+        return {
+            template,
+            label: group[0].label,
+            sampled: new Set(group.map((r) => r.url)).size,
+            performance_mean,
+            worst_url: worst?.url ?? "",
+        };
+    });
+    // Lab metrics failing across the runs. At 100% this is the "22/22 fail TBT"
+    // line — the strongest sentence in the manual report, and the one most likely
+    // to be miscounted by hand. Below 80% it is not a headline; `universal` says
+    // which case a reader is looking at.
+    const lab_metric_failures = [];
+    for (const [key, spec] of Object.entries(LAB_THRESHOLDS)) {
+        const values = runs
+            .map((r) => r.lab[key])
+            .filter((v) => typeof v === "number");
+        if (values.length === 0)
+            continue;
+        const failing = values.filter((v) => v > spec.good);
+        if (failing.length === 0)
+            continue;
+        const pct = Math.round((failing.length / values.length) * 100);
+        lab_metric_failures.push({
+            metric: key,
+            label: spec.label,
+            failing: failing.length,
+            of: values.length,
+            pct,
+            universal: pct >= 80,
+            range: `${Math.round(Math.min(...failing))} ms–${Math.round(Math.max(...failing))} ms`,
+            threshold: `${spec.good} ms`,
+        });
+    }
+    const cwv_verdicts = { pass: 0, needs_improvement: 0, fail: 0 };
+    for (const run of runs)
+        cwv_verdicts[cwvVerdict(run)]++;
+    const tally = (verdict) => {
+        const counts = new Map();
+        for (const run of runs) {
+            for (const c of run.comparisons) {
+                if (c.verdict !== verdict)
+                    continue;
+                counts.set(c.metric, (counts.get(c.metric) ?? 0) + 1);
+            }
+        }
+        return [...counts.entries()]
+            .map(([metric, n]) => ({ metric, runs: n }))
+            .sort((a, b) => b.runs - a.runs);
+    };
+    // Outliers: a value far above the median for its own strategy. With
+    // runs_per_url = 1 there is nothing to check it against, so it is reported
+    // as unconfirmed rather than asserted — the manual report had to make this
+    // caveat in prose for its 9.97 s TBT reading.
+    const outliers = [];
+    for (const strategy of strategies) {
+        const group = runs.filter((r) => r.strategy === strategy);
+        for (const key of Object.keys(LAB_THRESHOLDS)) {
+            const values = group
+                .map((r) => r.lab[key])
+                .filter((v) => typeof v === "number");
+            if (values.length < 4)
+                continue;
+            const med = median(values);
+            if (med <= 0)
+                continue;
+            for (const run of group) {
+                const value = run.lab[key];
+                if (typeof value !== "number" || value / med < 3)
+                    continue;
+                outliers.push({
+                    url: run.url,
+                    strategy,
+                    metric: String(key),
+                    value: `${Math.round(value)} ms`,
+                    vs_median_multiple: Number((value / med).toFixed(1)),
+                    confidence: run.runs > 1 ? `median_of_${run.runs}` : "unconfirmed_single_run",
+                });
+            }
+        }
+    }
+    return {
+        run_count: runs.length,
+        pages: new Set(runs.map((r) => r.url)).size,
+        captured_at: new Date().toISOString(),
+        by_strategy,
+        by_template,
+        lab_metric_failures,
+        cwv_verdicts,
+        lab_vs_field_summary: {
+            worse_in_field: tally("worse_in_field"),
+            worse_in_lab: tally("worse_in_lab"),
+            confirmed: tally("confirmed"),
+            no_field_data: runs.filter((r) => !r.field).length,
+        },
+        outliers,
+    };
+}
+//# sourceMappingURL=psiAggregator.js.map

package/dist/mappers/psiAggregator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"psiAggregator.js","sourceRoot":"","sources":["../../src/mappers/psiAggregator.ts"],"names":[],"mappings":"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"}

package/dist/mappers/webVitalsMapper.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Core Web Vitals field data → priorities and defect prose.
+ *
+ * The lab side of a PSI response goes through the existing
+ * `formatLighthouseFinding` path unchanged. This module handles the CrUX half,
+ * where the inputs are 75th-percentile measurements from real users rather
+ * than audit scores, so neither the impact-weight mapping nor the WCAG
+ * technique table applies.
+ *
+ * Field findings are written to read differently from lab findings on purpose.
+ * A lab finding says the page did something under simulation; a field finding
+ * says a measurable share of real people already experienced it. That
+ * distinction is the whole reason to call PSI, and it should survive into the
+ * defect ticket.
+ */
+import type { Finding, Priority } from "../types.js";
+import type { CruxMetric, WebVital } from "../utils/psiParser.js";
+export type VitalRating = "good" | "needs-improvement" | "poor";
+export declare function vitalLabel(vital: WebVital): string;
+/**
+ * LCP, INP and CLS gate a release and affect ranking; FCP and TTFB explain
+ * them. Exported because the priority cap has to hold everywhere a priority is
+ * decided, not just where one is first assigned.
+ */
+export declare function isCoreVital(vital: WebVital): boolean;
+/**
+ * Rate a p75 value against Google's thresholds.
+ *
+ * PSI also returns its own FAST/AVERAGE/SLOW `category` per metric, and the two
+ * agree in practice. We classify from the published thresholds anyway, so that
+ * the boundary a finding was raised at is a documented number in this file
+ * rather than a verdict from an opaque field — and so origin-level and
+ * URL-level metrics are graded identically.
+ */
+export declare function classifyVital(vital: WebVital, p75: number): VitalRating;
+/**
+ * Poor → P1, needs improvement → P2, good → no finding (never report a passing
+ * check). Non-core diagnostics cap at P2.
+ */
+export declare function fieldVitalToPriority(vital: WebVital, p75: number): Priority | null;
+/** Human-readable measurement. CLS is unitless; everything else is milliseconds. */
+export declare function formatVitalValue(vital: WebVital, value: number): string;
+/**
+ * One field metric → a Finding, or null when real users are having a fine time.
+ *
+ * `source` reaches the evidence deliberately. An origin-level metric describes
+ * the whole site, not this page, and a reader deciding whether to act on the
+ * finding needs to know which they are looking at.
+ */
+export declare function formatFieldFinding(vital: WebVital, metric: CruxMetric): Finding | null;
+/** Every failing field metric in a parsed CrUX block, unsorted. */
+export declare function formatFieldFindings(metrics: Partial<Record<WebVital, CruxMetric>>): Finding[];

package/dist/mappers/webVitalsMapper.js

@@ -0,0 +1,131 @@
+/**
+ * Core Web Vitals field data → priorities and defect prose.
+ *
+ * The lab side of a PSI response goes through the existing
+ * `formatLighthouseFinding` path unchanged. This module handles the CrUX half,
+ * where the inputs are 75th-percentile measurements from real users rather
+ * than audit scores, so neither the impact-weight mapping nor the WCAG
+ * technique table applies.
+ *
+ * Field findings are written to read differently from lab findings on purpose.
+ * A lab finding says the page did something under simulation; a field finding
+ * says a measurable share of real people already experienced it. That
+ * distinction is the whole reason to call PSI, and it should survive into the
+ * defect ticket.
+ */
+/** Google's official p75 boundaries. */
+const VITALS = {
+    lcp: { label: "Largest Contentful Paint", good: 2500, needsImprovement: 4000, isCoreVital: true },
+    inp: { label: "Interaction to Next Paint", good: 200, needsImprovement: 500, isCoreVital: true },
+    cls: { label: "Cumulative Layout Shift", good: 0.1, needsImprovement: 0.25, isCoreVital: true },
+    fcp: { label: "First Contentful Paint", good: 1800, needsImprovement: 3000, isCoreVital: false },
+    ttfb: { label: "Time to First Byte", good: 800, needsImprovement: 1800, isCoreVital: false },
+};
+export function vitalLabel(vital) {
+    return VITALS[vital].label;
+}
+/**
+ * LCP, INP and CLS gate a release and affect ranking; FCP and TTFB explain
+ * them. Exported because the priority cap has to hold everywhere a priority is
+ * decided, not just where one is first assigned.
+ */
+export function isCoreVital(vital) {
+    return VITALS[vital].isCoreVital;
+}
+/**
+ * Rate a p75 value against Google's thresholds.
+ *
+ * PSI also returns its own FAST/AVERAGE/SLOW `category` per metric, and the two
+ * agree in practice. We classify from the published thresholds anyway, so that
+ * the boundary a finding was raised at is a documented number in this file
+ * rather than a verdict from an opaque field — and so origin-level and
+ * URL-level metrics are graded identically.
+ */
+export function classifyVital(vital, p75) {
+    const spec = VITALS[vital];
+    if (p75 <= spec.good)
+        return "good";
+    if (p75 <= spec.needsImprovement)
+        return "needs-improvement";
+    return "poor";
+}
+/**
+ * Poor → P1, needs improvement → P2, good → no finding (never report a passing
+ * check). Non-core diagnostics cap at P2.
+ */
+export function fieldVitalToPriority(vital, p75) {
+    const rating = classifyVital(vital, p75);
+    if (rating === "good")
+        return null;
+    if (rating === "needs-improvement")
+        return "P2";
+    return VITALS[vital].isCoreVital ? "P1" : "P2";
+}
+/** Human-readable measurement. CLS is unitless; everything else is milliseconds. */
+export function formatVitalValue(vital, value) {
+    if (vital === "cls")
+        return value.toFixed(3).replace(/0+$/, "").replace(/\.$/, "");
+    return value >= 1000 ? `${(value / 1000).toFixed(1)} s` : `${Math.round(value)} ms`;
+}
+/** "7 in 10 users" reads more concretely in a ticket than "0.7019". */
+function shareOfUsers(proportion) {
+    const pct = Math.round(proportion * 100);
+    return `${pct}% of real users`;
+}
+/**
+ * Defect prose for each vital, in the register `defectFormatter.ts` established:
+ * what the user experiences, not what the metric is called.
+ *
+ * Every template states the share of real users in the poor bucket. A p75 alone
+ * invites the reply "that's just the tail" — naming the proportion answers it
+ * before it is asked, and the number is already in the response.
+ */
+const FIELD_DESCRIPTIONS = {
+    lcp: (_m, value, poor) => `Real users wait ${value} for the main page content to appear (75th percentile, trailing 28 days). ${poor} experience a load slow enough to be rated poor, well past the point where visitors begin abandoning the page.`,
+    inp: (_m, value, poor) => `The page takes ${value} to respond visibly after a real user taps or clicks (75th percentile, trailing 28 days). ${poor} experience responsiveness rated poor — taps appear to do nothing, so users tap again and trigger duplicate actions.`,
+    cls: (_m, value, poor) => `Real users see the layout shift by ${value} while the page loads (75th percentile, trailing 28 days). ${poor} experience shifting rated poor, which causes mis-taps on the wrong control and loss of reading position.`,
+    fcp: (_m, value, poor) => `Real users stare at a blank screen for ${value} before anything paints (75th percentile, trailing 28 days). ${poor} experience a first paint rated poor. This is a diagnostic for the slow Largest Contentful Paint rather than a defect to fix on its own.`,
+    ttfb: (_m, value, poor) => `The server takes ${value} to return the first byte for real users (75th percentile, trailing 28 days). ${poor} experience a response rated poor; every downstream resource waits on this, so it caps how fast the rest of the page can possibly be.`,
+};
+/**
+ * One field metric → a Finding, or null when real users are having a fine time.
+ *
+ * `source` reaches the evidence deliberately. An origin-level metric describes
+ * the whole site, not this page, and a reader deciding whether to act on the
+ * finding needs to know which they are looking at.
+ */
+export function formatFieldFinding(vital, metric) {
+    const priority = fieldVitalToPriority(vital, metric.p75);
+    if (!priority)
+        return null;
+    const value = formatVitalValue(vital, metric.p75);
+    const poor = shareOfUsers(metric.distribution.poor);
+    const spec = VITALS[vital];
+    const scope = metric.source === "origin" ? " (site-wide data)" : "";
+    return {
+        priority,
+        title: `${spec.label} is ${classifyVital(vital, metric.p75) === "poor" ? "poor" : "below target"} for real users${scope}`,
+        description: FIELD_DESCRIPTIONS[vital](metric, value, poor) +
+            (metric.source === "origin"
+                ? " This URL has too little traffic for its own field data, so these figures describe the whole origin and may not reflect this page."
+                : ""),
+        evidence: {
+            audit_id: `crux.${vital}`,
+            value,
+            threshold: formatVitalValue(vital, spec.good),
+            field_source: metric.source,
+            users_affected_pct: Math.round(metric.distribution.poor * 100),
+        },
+    };
+}
+/** Every failing field metric in a parsed CrUX block, unsorted. */
+export function formatFieldFindings(metrics) {
+    const findings = [];
+    for (const [vital, metric] of Object.entries(metrics)) {
+        const finding = formatFieldFinding(vital, metric);
+        if (finding)
+            findings.push(finding);
+    }
+    return findings;
+}
+//# sourceMappingURL=webVitalsMapper.js.map

package/dist/mappers/webVitalsMapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webVitalsMapper.js","sourceRoot":"","sources":["../../src/mappers/webVitalsMapper.ts"],"names":[],"mappings":"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"}

package/dist/tools/accessibility.js

@@ -3,56 +3,97 @@ import { runShell } from "../utils/shellRunner.js";
 import { parsePa11yJSON } from "../utils/outputParsers.js";
 import { shellErrorResponse, parseErrorResponse, } from "../utils/toolResponse.js";
 import { formatA11yFinding } from "../mappers/defectFormatter.js";
+import { dedupeA11yFindings } from "../mappers/a11yDedupe.js";
 import { sortFindingsByPriority } from "../mappers/priorityMapper.js";
 const inputShape = {
     url: z.string().url(),
     standard: z.enum(["WCAG2A", "WCAG2AA", "WCAG2AAA"]).optional(),
     ignore: z.array(z.string()).optional(),
+    runner: z
+        .enum(["htmlcs", "axe", "both"])
+        .optional()
+        .describe("Which accessibility engine to run. 'htmlcs' (default) checks WCAG " +
+        "techniques and is strong on document structure, labels, and forms. " +
+        "'axe' is Deque's engine and is materially stronger on ARIA — roles, " +
+        "required parent/child relationships, prohibited and unsupported " +
+        "attributes — and on computed colour contrast, so prefer it when the " +
+        "work under test involves ARIA or a component library. 'both' runs " +
+        "the two and merges the results, which is the most thorough option " +
+        "and roughly doubles runtime."),
 };
 export function registerAccessibilityTool(server) {
     server.registerTool("run_accessibility_check", {
-        description: "Runs pa11y against a URL and returns a QA-style report with WCAG " +
-            "violations mapped to priorities (Level A → P1, AA → P2, AAA → P3; " +
-            "notices are filtered out). Requires the pa11y CLI to be installed " +
-            "globally on PATH (`npm install -g pa11y`).",
+        description: "Runs pa11y against a URL and returns a QA-style report of WCAG " +
+            "violations prioritised P1/P2/P3 (notices are filtered out). " +
+            "\n\n" +
+            "Two engines are available via `runner`. htmlcs (default) checks WCAG " +
+            "techniques and is strong on document structure, labels, and forms. " +
+            "axe is Deque's engine and is materially stronger on ARIA — invalid " +
+            "roles, missing required parent/child relationships, prohibited and " +
+            "unsupported attributes — and on computed colour contrast. " +
+            "**Prefer runner='axe' whenever the work under test involves ARIA, a " +
+            "component library, or a design system**, and runner='both' for the " +
+            "most thorough sweep. The two engines overlap only partly: on a real " +
+            "commerce page htmlcs found unlabelled inputs and duplicate ids that " +
+            "axe did not, while axe found aria-allowed-attr, aria-required-parent " +
+            "and image-alt failures htmlcs missed entirely. " +
+            "\n\n" +
+            "Requires the pa11y CLI on PATH (`npm install -g pa11y`).",
         inputSchema: inputShape,
-    }, async ({ url, standard, ignore }) => {
+    }, async ({ url, standard, ignore, runner }) => {
         const resolvedStandard = standard ?? "WCAG2AA";
-        const args = [
-            url,
-            "--reporter",
-            "json",
-            "--standard",
-            resolvedStandard,
-        ];
-        if (ignore && ignore.length > 0) {
-            args.push("--ignore", ignore.join(";"));
-        }
-        const result = await runShell("pa11y", args, { timeoutMs: 120_000 });
+        const resolvedRunner = runner ?? "htmlcs";
+        const engines = resolvedRunner === "both" ? ["htmlcs", "axe"] : [resolvedRunner];
+        const buildArgs = (engine) => {
+            const args = [url, "--reporter", "json", "--standard", resolvedStandard,
+                "--runner", engine];
+            if (ignore && ignore.length > 0)
+                args.push("--ignore", ignore.join(";"));
+            return args;
+        };
+        // Engines run concurrently so "both" costs little more wall time than one.
+        const results = await Promise.all(engines.map((e) => runShell("pa11y", buildArgs(e), { timeoutMs: 120_000 })));
         // pa11y exits 2 when issues are found — that's a successful run with data.
         // Exit 1 means pa11y itself failed (browser launch, bad URL, etc.).
-        const ranSuccessfully = result.exitCode === 0 || result.exitCode === 2;
-        if (!ranSuccessfully || !result.stdout) {
-            return shellErrorResponse("pa11y did not produce a usable report", result);
-        }
-        let parsed;
-        try {
-            parsed = parsePa11yJSON(result.stdout);
-        }
-        catch (err) {
-            return parseErrorResponse("Failed to parse pa11y JSON", err, result);
+        const usable = results.filter((r) => (r.exitCode === 0 || r.exitCode === 2) && r.stdout);
+        if (usable.length === 0) {
+            return shellErrorResponse("pa11y did not produce a usable report", results[0]);
         }
-        const findings = [];
-        for (const violation of parsed.violations) {
-            const finding = formatA11yFinding(violation);
-            if (finding)
-                findings.push(finding);
+        const rawFindings = [];
+        for (const result of usable) {
+            let parsed;
+            try {
+                parsed = parsePa11yJSON(result.stdout);
+            }
+            catch (err) {
+                return parseErrorResponse("Failed to parse pa11y JSON", err, result);
+            }
+            for (const violation of parsed.violations) {
+                const finding = formatA11yFinding(violation);
+                if (finding)
+                    rawFindings.push(finding);
+            }
         }
+        // Collapse repeats of the same defect before counting or sorting — see
+        // a11yDedupe for why pa11y produces them. Note this dedupes *within* an
+        // engine only: the key is (rule_code, selector), and the two engines emit
+        // different code shapes for the same defect ("...1_1_1.H37" vs
+        // "image-alt"), so an element both engines flag appears twice. That is
+        // deliberate for now — two independent engines agreeing is corroboration
+        // worth seeing, the same signal the Lighthouse/pa11y correlator promotes.
+        const { findings, rawCount } = dedupeA11yFindings(rawFindings);
         sortFindingsByPriority(findings);
         const report = {
             url,
             standard: resolvedStandard,
+            runners: engines,
+            ...(usable.length < engines.length
+                ? { warnings: [`Only ${usable.length} of ${engines.length} runners produced output.`] }
+                : {}),
             violation_count: findings.length,
+            // Pre-dedup total, so a large drop between the two is explainable
+            // rather than looking like dropped findings.
+            raw_violation_count: rawCount,
             findings,
         };
         return {