@diegovelasquezweb/a11y-engine 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+---
+
+## [0.1.2] — 2026-03-13
+
+### Fixed
+
+- `bin` field in `package.json` — removed leading `./` from the entry path (`scripts/audit.mjs`) to satisfy npm bin resolution
+- `repository.url` normalized to `git+https://` prefix as required by npm registry validation
+- Missing shebang (`#!/usr/bin/env node`) added to `scripts/audit.mjs` so the `a11y-audit` binary executes correctly when installed globally or via `npx`
+
+---
+
+## [0.1.1] — 2026-03-13
+
+### Added
+
+- Engine scripts published as a standalone npm package:
+  - `scripts/audit.mjs` — orchestrator for the full audit pipeline
+  - `scripts/core/utils.mjs` — shared logging, path utilities, and defaults
+  - `scripts/core/toolchain.mjs` — dependency and Playwright browser verification
+  - `scripts/core/asset-loader.mjs` — JSON asset loading with error boundaries
+  - `scripts/engine/dom-scanner.mjs` — Playwright + axe-core WCAG 2.2 AA scanner
+  - `scripts/engine/analyzer.mjs` — finding enrichment with fix intelligence
+  - `scripts/engine/source-scanner.mjs` — static source code pattern scanner
+  - `scripts/reports/builders/` — orchestrators for each report format
+  - `scripts/reports/renderers/` — rendering logic for HTML, PDF, Markdown, and checklist
+- Asset files bundled under `assets/`:
+  - `assets/reporting/compliance-config.json` — scoring weights, grade thresholds, and legal regulation mapping
+  - `assets/reporting/wcag-reference.json` — WCAG criterion map, persona config, and persona–rule mapping
+  - `assets/reporting/manual-checks.json` — 41 manual WCAG checks for the interactive checklist
+  - `assets/discovery/crawler-config.json` — BFS crawl configuration defaults
+  - `assets/discovery/stack-detection.json` — framework and CMS fingerprint signatures
+  - `assets/remediation/intelligence.json` — per-rule fix intelligence (106 axe-core rules)
+  - `assets/remediation/code-patterns.json` — source code pattern definitions
+  - `assets/remediation/guardrails.json` — agent fix guardrails and scope rules
+  - `assets/remediation/axe-check-maps.json` — axe check-to-rule mapping
+  - `assets/remediation/source-boundaries.json` — framework-specific file location patterns
+- `a11y-audit` binary registered in `bin` field — invocable via `npx a11y-audit` after install
+- `LICENSE` (MIT)
+
+---
+
+## [0.1.0] — 2026-03-13
+
+### Added
+
+- Initial package scaffold: `package.json` for `@diegovelasquezweb/a11y-engine` with correct `name`, `version`, `type: module`, `engines`, `files`, and `scripts` fields
+- `devDependencies`: `vitest` for test runner
+- `dependencies`: `playwright`, `@axe-core/playwright`, `axe-core`, `pa11y`

package/README.md

@@ -1,20 +1,162 @@
 # @diegovelasquezweb/a11y-engine
 
-WCAG 2.2 AA accessibility audit engine. Scanner, analyzer, and report builders.
+WCAG 2.2 AA accessibility audit engine. Runs Playwright + axe-core scans, enriches findings with fix intelligence, and produces structured artifacts for developers, agents, and stakeholders.
 
-## Install
+## What it is
+
+A Node.js CLI and programmatic engine that:
+
+1. Crawls a target URL and discovers routes automatically
+2. Runs axe-core WCAG 2.2 AA checks across all discovered pages
+3. Optionally scans project source code for patterns axe cannot detect at runtime
+4. Enriches each finding with stack-aware fix guidance, selectors, and verification commands
+5. Produces a full artifact set: JSON data, Markdown remediation guide, HTML dashboard, PDF compliance report, and manual testing checklist
+
+## Why use this engine
+
+| Capability | With this engine | Without |
+| :--- | :--- | :--- |
+| **Full WCAG 2.2 Coverage** | axe-core runtime scan + source code pattern scanner | Runtime scan only — misses CSS/source-level issues |
+| **Fix Intelligence** | Stack-aware patches with code snippets tailored to detected framework | Raw rule violations with no remediation context |
+| **Structured Artifacts** | JSON + Markdown + HTML + PDF + Checklist — ready to consume or forward | Findings exist only in the terminal session |
+| **CI/Agent Integration** | Deterministic exit codes, stdout-parseable output paths, JSON schema | Requires wrapper scripting |
+
+## Installation
 
 ```bash
-npm i @diegovelasquezweb/a11y-engine
+npm install @diegovelasquezweb/a11y-engine
 npx playwright install chromium
 ```
 
-## Usage
+```bash
+pnpm add @diegovelasquezweb/a11y-engine
+pnpm exec playwright install chromium
+```
+
+> Chromium must be installed separately. The engine uses Playwright's bundled browser — not a system Chrome.
+
+## Quick start
+
+```bash
+# Minimal scan — produces remediation.md in .audit/
+npx a11y-audit --base-url https://example.com
+
+# Full audit with all reports
+npx a11y-audit --base-url https://example.com --with-reports --output ./audit/report.html
+
+# Scan with source code intelligence (for stack-aware fix guidance)
+npx a11y-audit --base-url http://localhost:3000 --project-dir . --with-reports --output ./audit/report.html
+```
+
+## CLI usage
+
+```
+a11y-audit --base-url <url> [options]
+```
+
+### Targeting & scope
+
+| Flag | Argument | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--base-url` | `<url>` | (Required) | Starting URL for the audit. |
+| `--max-routes` | `<num>` | `10` | Max routes to discover and scan. |
+| `--crawl-depth` | `<num>` | `2` | BFS link-follow depth during discovery (1–3). |
+| `--routes` | `<csv>` | — | Explicit path list, bypasses auto-discovery. |
+| `--project-dir` | `<path>` | — | Path to project source. Enables source pattern scanner and framework auto-detection. |
+
+### Audit intelligence
+
+| Flag | Argument | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--target` | `<text>` | `WCAG 2.2 AA` | Compliance target label in reports. |
+| `--only-rule` | `<id>` | — | Run a single axe rule (e.g. `color-contrast`). |
+| `--ignore-findings` | `<csv>` | — | Rule IDs to exclude from output. |
+| `--exclude-selectors` | `<csv>` | — | CSS selectors to skip during DOM scan. |
+| `--framework` | `<name>` | — | Override auto-detected stack. Supported: `nextjs`, `gatsby`, `react`, `nuxt`, `vue`, `angular`, `astro`, `svelte`, `shopify`, `wordpress`, `drupal`. |
+
+### Execution & emulation
+
+| Flag | Argument | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--color-scheme` | `light\|dark` | `light` | Emulate `prefers-color-scheme`. |
+| `--wait-until` | `domcontentloaded\|load\|networkidle` | `domcontentloaded` | Playwright page load strategy. Use `networkidle` for SPAs. |
+| `--viewport` | `<WxH>` | — | Viewport size (e.g. `375x812`, `1440x900`). |
+| `--wait-ms` | `<num>` | `2000` | Delay after page load before running axe (ms). |
+| `--timeout-ms` | `<num>` | `30000` | Network timeout per page (ms). |
+| `--headed` | — | `false` | Run browser in visible mode. |
+| `--affected-only` | — | `false` | Re-scan only routes with previous violations. Requires a prior scan in `.audit/`. |
+
+### Output generation
+
+| Flag | Argument | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--with-reports` | — | `false` | Generate HTML + PDF + Checklist reports. Requires `--output`. |
+| `--skip-reports` | — | `true` | Skip visual report generation (default). |
+| `--output` | `<path>` | — | Output path for `report.html` (PDF and checklist derive from it). |
+| `--skip-patterns` | — | `false` | Disable source code pattern scanner even when `--project-dir` is set. |
+
+## Common command patterns
 
 ```bash
-npx a11y-audit --base-url https://example.com --max-routes 5
+# Focused audit — one rule, one route
+a11y-audit --base-url https://example.com --only-rule color-contrast --routes /checkout --max-routes 1
+
+# Dark mode audit
+a11y-audit --base-url https://example.com --color-scheme dark
+
+# SPA with deferred rendering
+a11y-audit --base-url https://example.com --wait-until networkidle --wait-ms 3000
+
+# Mobile viewport
+a11y-audit --base-url https://example.com --viewport 375x812
+
+# Fast re-audit after fixes (skips clean pages)
+a11y-audit --base-url https://example.com --affected-only
+
+# Ignore known false positives
+a11y-audit --base-url https://example.com --ignore-findings color-contrast,frame-title
 ```
 
-## Options
+## Output artifacts
+
+All artifacts are written to `.audit/` relative to the package root.
+
+| File | Always generated | Description |
+| :--- | :--- | :--- |
+| `a11y-scan-results.json` | Yes | Raw axe-core results per route |
+| `a11y-findings.json` | Yes | Enriched findings with fix intelligence |
+| `remediation.md` | Yes | AI-agent-optimized remediation roadmap |
+| `report.html` | With `--with-reports` | Interactive HTML dashboard |
+| `report.pdf` | With `--with-reports` | Formal compliance PDF |
+| `checklist.html` | With `--with-reports` | Manual WCAG testing checklist |
+
+See [Output Artifacts](docs/outputs.md) for full schema reference.
+
+## Troubleshooting
+
+**`Error: browserType.launch: Executable doesn't exist`**
+Run `npx playwright install chromium` (or `pnpm exec playwright install chromium`).
+
+**`Missing required argument: --base-url`**
+The flag is required. Provide a full URL including protocol: `--base-url https://example.com`.
+
+**Scan returns 0 findings on an SPA**
+Use `--wait-until networkidle --wait-ms 3000` to let async content render before axe runs.
+
+**`--with-reports` exits without generating PDF**
+Ensure `--output` is also set and points to an `.html` file path: `--output ./audit/report.html`.
+
+**Chromium crashes in CI**
+Add `--no-sandbox` via the `PLAYWRIGHT_CHROMIUM_LAUNCH_OPTIONS` env var, or run Playwright with the `--with-deps` flag during browser installation.
+
+## Documentation
+
+| Resource | Description |
+| :--- | :--- |
+| [Architecture](https://github.com/diegovelasquezweb/a11y-engine/blob/main/docs/architecture.md) | How the scanner → analyzer → report pipeline works |
+| [CLI Handbook](https://github.com/diegovelasquezweb/a11y-engine/blob/main/docs/cli-handbook.md) | Full flag reference and usage patterns |
+| [Output Artifacts](https://github.com/diegovelasquezweb/a11y-engine/blob/main/docs/outputs.md) | Schema and structure of every generated file |
+
+## License
 
-See `a11y-audit --help` for full CLI reference.
+MIT

package/docs/architecture.md

@@ -0,0 +1,139 @@
+# Engine Architecture
+
+**Navigation**: [Home](../README.md) • [Architecture](architecture.md) • [CLI Handbook](cli-handbook.md) • [Output Artifacts](outputs.md)
+
+---
+
+## Table of Contents
+
+- [Pipeline overview](#pipeline-overview)
+- [Stage 1: DOM scanner](#stage-1-dom-scanner)
+- [Stage 2: Analyzer](#stage-2-analyzer)
+- [Stage 3: Report builders](#stage-3-report-builders)
+- [Assets and rule intelligence](#assets-and-rule-intelligence)
+- [Execution model and timeouts](#execution-model-and-timeouts)
+
+---
+
+The engine operates as a three-stage pipeline. Each stage is an independent Node.js process spawned by `audit.mjs`. Stages communicate through JSON files written to `.audit/`.
+
+## Pipeline overview
+
+```
+Target URL
+    │
+    ▼
+┌─────────────────────────────┐
+│  Stage 1: DOM Scanner       │  Playwright + axe-core
+│  dom-scanner.mjs            │  Route discovery + WCAG scan
+└──────────────┬──────────────┘
+               │ a11y-scan-results.json
+               ▼
+┌─────────────────────────────┐
+│  Stage 1b: Source Scanner   │  Static regex analysis
+│  source-scanner.mjs         │  (optional — requires --project-dir)
+└──────────────┬──────────────┘
+               │ merges into a11y-findings.json
+               ▼
+┌─────────────────────────────┐
+│  Stage 2: Analyzer          │  Fix intelligence enrichment
+│  analyzer.mjs               │  intelligence.json + guardrails
+└──────────────┬──────────────┘
+               │ a11y-findings.json
+               ▼
+┌─────────────────────────────┐
+│  Stage 3: Report Builders   │  Parallel rendering
+│  md / html / pdf / checklist│
+└──────────────┬──────────────┘
+               │
+    ┌──────────┼──────────┬──────────────┐
+    ▼          ▼          ▼              ▼
+remediation  report    report         checklist
+   .md       .html      .pdf            .html
+```
+
+## Stage 1: DOM scanner
+
+**Script**: `scripts/engine/dom-scanner.mjs`
+
+Launches a Playwright-controlled Chromium browser and runs axe-core against each discovered route.
+
+**Route discovery**:
+- If the site exposes a `sitemap.xml`, all listed URLs are scanned (up to `--max-routes`).
+- Otherwise, BFS crawl starting from `--base-url`, following same-origin `<a href>` links up to `--crawl-depth` levels deep.
+- Routes are deduplicated and normalized before scanning.
+
+**Scanning**:
+- 3 parallel browser tabs scan routes concurrently (~2–3× faster than sequential).
+- axe-core 4.11+ runs WCAG 2.2 A, AA, and best-practice tag sets.
+- Screenshots of affected elements are captured for each violation.
+- `--color-scheme`, `--viewport`, `--wait-until`, and `--wait-ms` control the browser environment.
+
+**Output**: `a11y-scan-results.json` — raw axe results per route with DOM snapshots.
+
+### Optional: Source scanner
+
+**Script**: `scripts/engine/source-scanner.mjs` — runs when `--project-dir` is set and `--skip-patterns` is not.
+
+Performs static analysis of source files for accessibility issues axe cannot detect at runtime (e.g. focus outline suppression, missing alt text in templates). Uses regex patterns from `assets/remediation/code-patterns.json` scoped to framework-specific file boundaries from `assets/remediation/source-boundaries.json`.
+
+Findings are classified as `confirmed` (pattern unambiguously matches) or `potential` (requires human verification).
+
+## Stage 2: Analyzer
+
+**Script**: `scripts/engine/analyzer.mjs`
+
+Reads `a11y-scan-results.json` and enriches each violation with:
+
+- **Fix intelligence** from `assets/remediation/intelligence.json` — 106 axe-core rules with code snippets, MDN links, framework-specific notes, and WCAG criterion mapping.
+- **Selector scoring** — picks the most stable selector from axe's `nodes` list. Priority: `#id` > `[data-*]` > `[aria-*]` > `[type=]`, with penalty for Tailwind utility classes.
+- **Framework context** — `assets/discovery/stack-detection.json` fingerprints the DOM to detect framework and CMS. Per-finding `framework_notes` and `cms_notes` are filtered to the detected stack.
+- **Guardrails** — `assets/remediation/guardrails.json` defines scope rules that prevent agents from touching backend code, third-party scripts, or minified files.
+- **Compliance scoring** — `assets/reporting/compliance-config.json` weights findings by severity to produce a 0–100 score with grade thresholds.
+- **Persona impact groups** — `assets/reporting/wcag-reference.json` maps findings to disability personas (visual, motor, cognitive, etc.).
+
+**Output**: `a11y-findings.json` — enriched findings array with all intelligence fields.
+
+## Stage 3: Report builders
+
+All builders run in parallel when `--with-reports` is set. Each reads `a11y-findings.json` independently.
+
+| Builder | Script | Output | Audience |
+| :--- | :--- | :--- | :--- |
+| Markdown | `reports/builders/md.mjs` | `remediation.md` | AI agents |
+| HTML | `reports/builders/html.mjs` | `report.html` | Developers |
+| PDF | `reports/builders/pdf.mjs` | `report.pdf` | Stakeholders |
+| Checklist | `reports/builders/checklist.mjs` | `checklist.html` | QA / Developers |
+
+The `remediation.md` builder always runs (even without `--with-reports`) since it is the primary output for AI agent consumption.
+
+Renderers in `scripts/reports/renderers/` contain the actual rendering logic — builders are thin orchestrators that call renderers and write output files.
+
+## Assets and rule intelligence
+
+Assets are static JSON files bundled with the package under `assets/`. They are read at runtime by the analyzer and report builders.
+
+| Asset | Purpose |
+| :--- | :--- |
+| `reporting/compliance-config.json` | Score weights, grade thresholds, legal regulation list |
+| `reporting/wcag-reference.json` | WCAG criterion map, persona config, persona–rule mapping |
+| `reporting/manual-checks.json` | 41 manual checks for the WCAG checklist |
+| `discovery/crawler-config.json` | BFS crawl defaults (timeouts, concurrency) |
+| `discovery/stack-detection.json` | Framework/CMS DOM fingerprints |
+| `remediation/intelligence.json` | Per-rule fix intelligence for 106 axe-core rules |
+| `remediation/code-patterns.json` | Source code pattern definitions |
+| `remediation/guardrails.json` | Agent fix scope guardrails |
+| `remediation/axe-check-maps.json` | axe check-to-rule mapping |
+| `remediation/source-boundaries.json` | Framework-specific source file locations |
+
+## Execution model and timeouts
+
+`audit.mjs` spawns each stage as a child process via `node:child_process`. All child processes:
+
+- Inherit the parent's environment
+- Run with `cwd` set to the package root (`SKILL_ROOT`)
+- Have a hard timeout of **15 minutes** (configurable via the `SCRIPT_TIMEOUT_MS` constant)
+
+The orchestrator exits with code `1` if any stage fails. Individual stage timeouts are also enforced per page via `--timeout-ms` (default: 30s).
+
+If `node_modules/` is absent on first run, the orchestrator automatically installs dependencies via `pnpm install` (falls back to `npm install`).

package/docs/cli-handbook.md

@@ -0,0 +1,209 @@
+# CLI Handbook
+
+**Navigation**: [Home](../README.md) • [Architecture](architecture.md) • [CLI Handbook](cli-handbook.md) • [Output Artifacts](outputs.md)
+
+---
+
+## Table of Contents
+
+- [Basic usage](#basic-usage)
+- [Flag groups](#flag-groups)
+  - [Targeting & scope](#targeting--scope)
+  - [Audit intelligence](#audit-intelligence)
+  - [Execution & emulation](#execution--emulation)
+  - [Output generation](#output-generation)
+- [Examples](#examples)
+- [Exit codes](#exit-codes)
+
+---
+
+## Basic usage
+
+```bash
+npx a11y-audit --base-url <url> [options]
+```
+
+Or if installed locally:
+
+```bash
+node node_modules/@diegovelasquezweb/a11y-engine/scripts/audit.mjs --base-url <url> [options]
+```
+
+The only required flag is `--base-url`. All other flags are optional.
+
+---
+
+## Flag groups
+
+### Targeting & scope
+
+Controls what gets scanned.
+
+| Flag | Argument | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--base-url` | `<url>` | (Required) | Starting URL. Must include protocol (`https://` or `http://`). |
+| `--max-routes` | `<num>` | `10` | Maximum unique same-origin paths to discover and scan. |
+| `--crawl-depth` | `<num>` | `2` | How deep to follow links during BFS discovery (1–3). Has no effect when `--routes` is set. |
+| `--routes` | `<csv>` | — | Explicit paths to scan (e.g. `/,/about,/contact`). Overrides auto-discovery entirely. |
+| `--project-dir` | `<path>` | — | Path to the audited project source. Enables the source code pattern scanner and framework auto-detection from `package.json`. |
+
+**Route discovery logic**:
+1. If the target has a `sitemap.xml`, all listed URLs are used (up to `--max-routes`).
+2. Otherwise, BFS crawl from `--base-url`, following same-origin `<a href>` links.
+3. `--routes` always takes precedence over both.
+
+---
+
+### Audit intelligence
+
+Controls how findings are interpreted and filtered.
+
+| Flag | Argument | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--target` | `<text>` | `WCAG 2.2 AA` | Compliance target label rendered in reports. Does not change which rules run. |
+| `--only-rule` | `<id>` | — | Run a single axe rule ID only. Useful for focused re-audits after fixing a specific issue. |
+| `--ignore-findings` | `<csv>` | — | Comma-separated list of axe rule IDs to suppress from output entirely. |
+| `--exclude-selectors` | `<csv>` | — | CSS selectors to skip. Elements matching these selectors are excluded from axe scanning. |
+| `--framework` | `<name>` | — | Override auto-detected framework. Affects which fix notes and source boundaries are applied. |
+
+**Supported `--framework` values**: `nextjs`, `gatsby`, `react`, `nuxt`, `vue`, `angular`, `astro`, `svelte`, `shopify`, `wordpress`, `drupal`.
+
+---
+
+### Execution & emulation
+
+Controls browser behavior during scanning.
+
+| Flag | Argument | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--color-scheme` | `light\|dark` | `light` | Emulates `prefers-color-scheme` media query. |
+| `--wait-until` | `domcontentloaded\|load\|networkidle` | `domcontentloaded` | Playwright page load strategy. Use `networkidle` for SPAs with async rendering. |
+| `--viewport` | `<WxH>` | `1280x800` | Browser viewport in pixels (e.g. `375x812` for mobile, `1440x900` for desktop). |
+| `--wait-ms` | `<num>` | `2000` | Fixed delay (ms) after page load before axe runs. Useful when JS renders content after `DOMContentLoaded`. |
+| `--timeout-ms` | `<num>` | `30000` | Network timeout per page load (ms). |
+| `--headed` | — | `false` | Launch browser in visible mode. Useful for debugging page rendering issues. |
+| `--affected-only` | — | `false` | Re-scan only routes that had violations in the previous scan. Reads `.audit/a11y-scan-results.json` to determine affected routes. Falls back to full scan if no prior results exist. |
+
+---
+
+### Output generation
+
+Controls what artifacts are written.
+
+| Flag | Argument | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--with-reports` | — | `false` | Generate full artifact set: `report.html`, `report.pdf`, `checklist.html`, and `remediation.md`. Requires `--output`. |
+| `--skip-reports` | — | `true` | Default behavior. Only `remediation.md` is generated. |
+| `--output` | `<path>` | — | Absolute or relative path for `report.html`. PDF and checklist are derived from the same directory. |
+| `--skip-patterns` | — | `false` | Disable source code pattern scanner even when `--project-dir` is set. Use this for DOM-only results without static analysis. |
+
+---
+
+## Examples
+
+### Minimal scan
+
+```bash
+# Produces only remediation.md in .audit/
+a11y-audit --base-url https://example.com
+```
+
+### Full audit with all reports
+
+```bash
+a11y-audit \
+  --base-url https://example.com \
+  --with-reports \
+  --output ./audit/report.html
+```
+
+### Include source code intelligence
+
+```bash
+a11y-audit \
+  --base-url http://localhost:3000 \
+  --project-dir . \
+  --with-reports \
+  --output ./audit/report.html
+```
+
+### Focused re-audit — single rule, single route
+
+```bash
+a11y-audit \
+  --base-url https://example.com \
+  --only-rule color-contrast \
+  --routes /checkout \
+  --max-routes 1
+```
+
+### Fast re-audit after applying fixes
+
+```bash
+# Only re-scans routes that had violations in the last run
+a11y-audit --base-url https://example.com --affected-only
+```
+
+### SPA with deferred rendering
+
+```bash
+a11y-audit \
+  --base-url https://example.com \
+  --wait-until networkidle \
+  --wait-ms 3000
+```
+
+### Dark mode audit
+
+```bash
+a11y-audit --base-url https://example.com --color-scheme dark
+```
+
+### Mobile viewport
+
+```bash
+a11y-audit --base-url https://example.com --viewport 375x812
+```
+
+### Suppress known false positives
+
+```bash
+a11y-audit \
+  --base-url https://example.com \
+  --ignore-findings color-contrast,frame-title
+```
+
+### Explicit route list
+
+```bash
+a11y-audit \
+  --base-url https://example.com \
+  --routes /,/pricing,/blog,/contact
+```
+
+### Override framework detection
+
+```bash
+a11y-audit \
+  --base-url http://localhost:3000 \
+  --framework nextjs \
+  --project-dir .
+```
+
+---
+
+## Exit codes
+
+| Code | Meaning |
+| :--- | :--- |
+| `0` | Audit completed successfully (regardless of findings count) |
+| `1` | Runtime error — invalid URL, missing required flag, stage failure, or timeout |
+
+The engine never exits `1` just because findings were found. Exit `1` only indicates a pipeline or configuration error.
+
+**Stdout markers** (parseable by scripts and CI):
+
+```
+REMEDIATION_PATH=<abs-path>   # always printed on success
+REPORT_PATH=<abs-path>        # only printed when --with-reports is set
+```

package/docs/outputs.md

@@ -0,0 +1,245 @@
+# Output Artifacts
+
+**Navigation**: [Home](../README.md) • [Architecture](architecture.md) • [CLI Handbook](cli-handbook.md) • [Output Artifacts](outputs.md)
+
+---
+
+## Table of Contents
+
+- [Default output directory](#default-output-directory)
+- [a11y-scan-results.json](#a11y-scan-resultsjson)
+- [a11y-findings.json](#a11y-findingsjson)
+- [remediation.md](#remediationmd)
+- [report.html](#reporthtml)
+- [report.pdf](#reportpdf)
+- [checklist.html](#checklisthtml)
+- [Consuming outputs programmatically](#consuming-outputs-programmatically)
+
+---
+
+## Default output directory
+
+All artifacts are written to `.audit/` relative to the package root (`SKILL_ROOT`). When consumed as an npm package, this resolves to the real package path inside `node_modules/`.
+
+```
+.audit/
+├── a11y-scan-results.json   # raw axe-core scan data
+├── a11y-findings.json       # enriched findings (primary data artifact)
+├── remediation.md           # AI agent remediation guide
+├── report.html              # interactive dashboard (--with-reports)
+├── report.pdf               # compliance report (--with-reports)
+├── checklist.html           # manual testing checklist (--with-reports)
+└── screenshots/             # element screenshots per violation
+```
+
+> When integrating the engine as a dependency (e.g. in `a11y-scanner`), use `fs.realpathSync` on the symlink path to resolve the real `.audit/` location — pnpm uses a deep `.pnpm/` directory structure, not the `node_modules/@scope/pkg` symlink.
+
+---
+
+## a11y-scan-results.json
+
+Raw axe-core output per route. Written by `scripts/engine/dom-scanner.mjs`.
+
+```json
+{
+  "routes": [
+    {
+      "path": "/",
+      "url": "https://example.com/",
+      "violations": [...],
+      "incomplete": [...],
+      "passes": [...],
+      "inapplicable": [...]
+    }
+  ]
+}
+```
+
+This file is consumed by `analyzer.mjs` and also used by `--affected-only` to determine which routes to re-scan on subsequent runs.
+
+---
+
+## a11y-findings.json
+
+The primary enriched data artifact. Written by `scripts/engine/analyzer.mjs`. This is the file consumed by all report builders.
+
+### Top-level structure
+
+```json
+{
+  "metadata": { ... },
+  "findings": [ ... ]
+}
+```
+
+### `metadata` fields
+
+| Field | Type | Description |
+| :--- | :--- | :--- |
+| `scanDate` | `string` (ISO 8601) | Timestamp of when the scan ran |
+| `checklist` | `object` | Manual check results if checklist was run |
+| `projectContext` | `object` | Auto-detected framework, CMS, and UI libraries |
+| `overallAssessment` | `string` | `"Pass"`, `"Conditional Pass"`, or `"Fail"` |
+| `passedCriteria` | `string[]` | WCAG criterion IDs with no active violations |
+| `outOfScope` | `object[]` | Findings excluded due to guardrails |
+| `recommendations` | `object[]` | Grouped fix recommendations by component |
+| `testingMethodology` | `object` | Scan scope and methodology summary |
+| `fpFiltered` | `number` | Count of findings filtered as likely false positives |
+| `deduplicatedCount` | `number` | Count of duplicate findings removed |
+
+### `findings` — per-finding fields
+
+| Field | Type | Description |
+| :--- | :--- | :--- |
+| `id` | `string` | Deterministic finding ID (e.g. `A11Y-001`) |
+| `rule_id` | `string` | axe-core rule ID (e.g. `color-contrast`) |
+| `title` | `string` | Human-readable finding title |
+| `severity` | `string` | `Critical`, `Serious`, `Moderate`, or `Minor` |
+| `wcag` | `string` | WCAG success criterion (e.g. `1.4.3`) |
+| `wcag_criterion_id` | `string` | Full WCAG criterion ID (e.g. `1.4.3`) |
+| `wcag_classification` | `string` | `A`, `AA`, `AAA`, or `Best Practice` |
+| `area` | `string` | Affected page area (e.g. `Navigation`, `Forms`) |
+| `url` | `string` | URL where the violation was found |
+| `selector` | `string` | CSS selector for the affected element |
+| `primary_selector` | `string` | Most stable selector chosen by the analyzer |
+| `impacted_users` | `string` | Disability groups affected |
+| `actual` | `string` | Observed violation description |
+| `expected` | `string` | What the correct behavior should be |
+| `category` | `string` | Violation category (e.g. `Color & Contrast`) |
+| `primary_failure_mode` | `string\|null` | Root cause classification |
+| `relationship_hint` | `string\|null` | Label/input relationship context |
+| `failure_checks` | `object[]` | axe check-level failure details |
+| `related_context` | `object[]` | Surrounding DOM context |
+| `fix_description` | `string\|null` | Plain-language fix explanation |
+| `fix_code` | `string\|null` | Ready-to-apply code snippet |
+| `fix_code_lang` | `string` | Language for code block (e.g. `html`, `jsx`) |
+| `recommended_fix` | `string` | Link to canonical fix reference (APG, MDN) |
+| `mdn` | `string\|null` | MDN documentation URL |
+| `effort` | `string\|null` | Fix effort estimate (`low`, `medium`, `high`) |
+| `related_rules` | `string[]` | Related axe rule IDs |
+| `guardrails` | `object\|null` | Agent scope guardrails for this finding |
+| `false_positive_risk` | `string\|null` | Known false positive patterns |
+| `fix_difficulty_notes` | `string\|null` | Edge cases and pitfalls for this fix |
+| `framework_notes` | `string\|null` | Framework-specific fix guidance |
+| `cms_notes` | `string\|null` | CMS-specific fix guidance |
+| `check_data` | `object\|null` | Raw axe check data |
+| `total_instances` | `number` | Count of affected elements across all pages |
+| `evidence` | `object[]` | DOM HTML snippets for each affected element |
+| `screenshot_path` | `string\|null` | Path to element screenshot |
+| `file_search_pattern` | `string\|null` | Regex/glob pattern to find the source file |
+| `managed_by_library` | `string\|null` | UI library managing this element (if any) |
+| `ownership_status` | `string` | `confirmed`, `potential`, or `unknown` |
+| `ownership_reason` | `string\|null` | Why this ownership status was assigned |
+| `primary_source_scope` | `string[]` | Source file paths likely containing the issue |
+| `search_strategy` | `string` | Agent search strategy recommendation |
+| `component_hint` | `string\|null` | Component name hint for source search |
+| `verification_command` | `string\|null` | CLI command to verify fix was applied |
+| `verification_command_fallback` | `string\|null` | Fallback verify command |
+| `pages_affected` | `number\|null` | Number of pages with this violation |
+| `affected_urls` | `string[]\|null` | All URLs where this violation appears |
+
+---
+
+## remediation.md
+
+AI agent-optimized remediation guide. Always generated (even without `--with-reports`). Written to `.audit/remediation.md`.
+
+Content:
+
+- Audit summary header with score, URL, and date
+- Per-finding sections with: violation description, DOM evidence, fix description, code snippet, verify command, and WCAG criterion
+- "Passed WCAG 2.2 Criteria" section listing clean criteria
+- "Source Code Patterns" section (if source scanner ran)
+- Component grouping table for batching fixes
+
+The path is printed to stdout on completion as `REMEDIATION_PATH=<path>`.
+
+---
+
+## report.html
+
+Interactive HTML dashboard. Generated only with `--with-reports --output <path>`.
+
+Features:
+
+- Severity-grouped findings with expandable detail cards
+- DOM evidence with syntax-highlighted code
+- Screenshot thumbnails per finding
+- Search and filter by severity, category, and page
+- Compliance score gauge with grade label
+- Persona impact breakdown (visual, motor, cognitive, etc.)
+- Quick wins section (Critical/Serious findings with ready code)
+
+Written to the path specified by `--output`. The path is printed to stdout as `REPORT_PATH=<path>`.
+
+---
+
+## report.pdf
+
+Formal PDF compliance report for stakeholders. Generated alongside `report.html` when `--with-reports` is set.
+
+Sections:
+
+1. Cover page with score, date, and target URL
+2. Table of Contents
+3. Executive Summary — score, overall assessment, finding counts by severity
+4. Legal Risk Summary — applicable regulations based on score tier
+5. Methodology — scan scope, tools, and WCAG version
+6. Findings Breakdown — severity table and issue summary
+7. Recommended Next Steps — dynamically generated from findings
+
+Written to the same directory as `--output` with `.pdf` extension.
+
+---
+
+## checklist.html
+
+Interactive manual testing checklist. Generated alongside `report.html` when `--with-reports` is set.
+
+Contains the 41 WCAG 2.2 AA manual checks that automated tools cannot detect, including:
+
+- Keyboard navigation and focus order
+- Screen reader announcements
+- Motion and animation
+- Zoom and reflow (400%)
+- Cognitive load and reading level
+
+Each item is checkable and includes testing instructions. State is not persisted between sessions.
+
+Written to the same directory as `--output` as `checklist.html`.
+
+---
+
+## Consuming outputs programmatically
+
+### Reading `a11y-findings.json` from an integration
+
+```js
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+
+// Resolve real path (handles pnpm symlinks)
+const req = createRequire(import.meta.url);
+const auditScript = req.resolve("@diegovelasquezweb/a11y-engine/scripts/audit.mjs");
+const engineRoot = path.dirname(path.dirname(auditScript));
+const findingsPath = path.join(engineRoot, ".audit", "a11y-findings.json");
+
+const { findings, metadata } = JSON.parse(fs.readFileSync(findingsPath, "utf-8"));
+```
+
+> Note: `import.meta.url` may be mangled by bundlers (e.g. Next.js). In that case, use `fs.realpathSync` on the known symlink instead:
+
+```js
+const symlinkBase = path.join(process.cwd(), "node_modules", "@diegovelasquezweb", "a11y-engine");
+const engineRoot = fs.realpathSync(symlinkBase);
+const findingsPath = path.join(engineRoot, ".audit", "a11y-findings.json");
+```
+
+### Parsing stdout markers
+
+```bash
+OUTPUT=$(node scripts/audit.mjs --base-url https://example.com --with-reports --output ./audit/report.html)
+REMEDIATION_PATH=$(echo "$OUTPUT" | grep REMEDIATION_PATH | cut -d= -f2)
+REPORT_PATH=$(echo "$OUTPUT" | grep REPORT_PATH | cut -d= -f2)
+```

package/package.json

@@ -1,24 +1,26 @@
 {
   "name": "@diegovelasquezweb/a11y-engine",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "WCAG 2.2 AA accessibility audit engine — scanner, analyzer, and report builders",
   "type": "module",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/diegovelasquezweb/a11y-engine.git"
+    "url": "git+https://github.com/diegovelasquezweb/a11y-engine.git"
   },
   "homepage": "https://github.com/diegovelasquezweb/a11y-engine#readme",
   "engines": {
     "node": ">=18"
   },
   "bin": {
-    "a11y-audit": "./scripts/audit.mjs"
+    "a11y-audit": "scripts/audit.mjs"
   },
   "files": [
     "scripts/**",
     "assets/**",
+    "docs/**",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {
@@ -33,5 +35,6 @@
   },
   "devDependencies": {
     "vitest": "^4.0.18"
-  }
+  },
+  "packageManager": "pnpm@10.22.0+sha512.bf049efe995b28f527fd2b41ae0474ce29186f7edcb3bf545087bd61fbbebb2bf75362d1307fda09c2d288e1e499787ac12d4fcb617a974718a6051f2eee741c"
 }

package/scripts/engine/dom-scanner.mjs

@@ -8,6 +8,7 @@
 
 import { chromium } from "playwright";
 import AxeBuilder from "@axe-core/playwright";
+import pa11y from "pa11y";
 import { log, DEFAULTS, writeJson, getInternalPath } from "../core/utils.mjs";
 import { ASSET_PATHS, loadAssetJson } from "../core/asset-loader.mjs";
 import path from "node:path";
@@ -85,6 +86,7 @@ function parseArgs(argv) {
     onlyRule: null,
     crawlDepth: DEFAULTS.crawlDepth,
     viewport: null,
+    axeTags: null,
   };
 
   for (let i = 0; i < argv.length; i += 1) {
@@ -110,6 +112,7 @@ function parseArgs(argv) {
       args.excludeSelectors = value.split(",").map((s) => s.trim());
     if (key === "--color-scheme") args.colorScheme = value;
     if (key === "--screenshots-dir") args.screenshotsDir = value;
+    if (key === "--axe-tags") args.axeTags = value.split(",").map((s) => s.trim());
     if (key === "--viewport") {
       const [w, h] = value.split("x").map(Number);
       if (w && h) args.viewport = { width: w, height: h };
@@ -398,6 +401,7 @@ async function analyzeRoute(
   timeoutMs = 30000,
   maxRetries = 2,
   waitUntil = "domcontentloaded",
+  axeTags = null,
 ) {
   let lastError;
 
@@ -417,7 +421,8 @@ async function analyzeRoute(
         log.info(`Targeted Audit: Only checking rule "${onlyRule}"`);
         builder.withRules([onlyRule]);
       } else {
-        builder.withTags(AXE_TAGS);
+        const tagsToUse = axeTags || AXE_TAGS;
+        builder.withTags(tagsToUse);
       }
 
       if (Array.isArray(excludeSelectors)) {
@@ -470,6 +475,262 @@ async function analyzeRoute(
   };
 }
 
+/**
+ * Writes scan progress to a JSON file for real-time UI updates.
+ * @param {string} step - Current step identifier.
+ * @param {"pending"|"running"|"done"|"error"} status - Step status.
+ * @param {Object} [extra={}] - Additional metadata.
+ */
+function writeProgress(step, status, extra = {}) {
+  const progressPath = getInternalPath("progress.json");
+  let progress = {};
+  try {
+    if (fs.existsSync(progressPath)) {
+      progress = JSON.parse(fs.readFileSync(progressPath, "utf-8"));
+    }
+  } catch { /* ignore */ }
+  progress.steps = progress.steps || {};
+  progress.steps[step] = { status, updatedAt: new Date().toISOString(), ...extra };
+  progress.currentStep = step;
+  fs.mkdirSync(path.dirname(progressPath), { recursive: true });
+  fs.writeFileSync(progressPath, JSON.stringify(progress, null, 2));
+}
+
+/**
+ * Runs CDP (Chrome DevTools Protocol) accessibility checks using Playwright's CDP session.
+ * Catches issues axe-core may miss: missing accessible names, broken focus order,
+ * aria-hidden on focusable elements, and missing form labels.
+ * @param {import("playwright").Page} page - The Playwright page object.
+ * @returns {Promise<Object[]>} Array of CDP-sourced violations in axe-compatible format.
+ */
+async function runCdpChecks(page) {
+  const violations = [];
+  try {
+    const cdp = await page.context().newCDPSession(page);
+
+    const { nodes } = await cdp.send("Accessibility.getFullAXTree");
+
+    for (const node of nodes) {
+      const role = node.role?.value || "";
+      const name = node.name?.value || "";
+      const properties = node.properties || [];
+      const ignored = node.ignored || false;
+
+      if (ignored) continue;
+
+      const focusable = properties.find((p) => p.name === "focusable")?.value?.value === true;
+      const hidden = properties.find((p) => p.name === "hidden")?.value?.value === true;
+
+      const interactiveRoles = ["button", "link", "textbox", "combobox", "listbox", "menuitem", "tab", "checkbox", "radio", "switch", "slider"];
+      if (interactiveRoles.includes(role) && !name.trim()) {
+        const backendId = node.backendDOMNodeId;
+        let selector = "";
+        try {
+          if (backendId) {
+            const { object } = await cdp.send("DOM.resolveNode", { backendNodeId: backendId });
+            if (object?.objectId) {
+              const result = await cdp.send("Runtime.callFunctionOn", {
+                objectId: object.objectId,
+                functionDeclaration: `function() {
+                  if (this.id) return '#' + this.id;
+                  if (this.className && typeof this.className === 'string') return this.tagName.toLowerCase() + '.' + this.className.trim().split(/\\s+/).join('.');
+                  return this.tagName.toLowerCase();
+                }`,
+                returnByValue: true,
+              });
+              selector = result.result?.value || "";
+            }
+          }
+        } catch { /* fallback: no selector */ }
+
+        violations.push({
+          id: "cdp-missing-accessible-name",
+          impact: "serious",
+          tags: ["wcag2a", "wcag412", "cdp-check"],
+          description: `Interactive element with role "${role}" has no accessible name`,
+          help: "Interactive elements must have an accessible name",
+          helpUrl: "https://dequeuniversity.com/rules/axe/4.11/button-name",
+          source: "cdp",
+          nodes: [{
+            any: [],
+            all: [{
+              id: "cdp-accessible-name",
+              data: { role, name: "(empty)" },
+              relatedNodes: [],
+              impact: "serious",
+              message: `Element with role "${role}" has no accessible name in the accessibility tree`,
+            }],
+            none: [],
+            impact: "serious",
+            html: `<${role} aria-role="${role}">`,
+            target: selector ? [selector] : [`[role="${role}"]`],
+            failureSummary: `Fix all of the following:\n  Element with role "${role}" has no accessible name`,
+          }],
+        });
+      }
+
+      if (hidden && focusable) {
+        violations.push({
+          id: "cdp-aria-hidden-focusable",
+          impact: "serious",
+          tags: ["wcag2a", "wcag412", "cdp-check"],
+          description: `Focusable element with role "${role}" is aria-hidden`,
+          help: "aria-hidden elements must not be focusable",
+          helpUrl: "https://dequeuniversity.com/rules/axe/4.11/aria-hidden-focus",
+          source: "cdp",
+          nodes: [{
+            any: [],
+            all: [{
+              id: "cdp-hidden-focusable",
+              data: { role },
+              relatedNodes: [],
+              impact: "serious",
+              message: `Focusable element with role "${role}" is hidden from the accessibility tree`,
+            }],
+            none: [],
+            impact: "serious",
+            html: `<element role="${role}" aria-hidden="true">`,
+            target: [`[role="${role}"]`],
+            failureSummary: `Fix all of the following:\n  Focusable element is hidden from the accessibility tree`,
+          }],
+        });
+      }
+    }
+
+    await cdp.detach();
+  } catch (err) {
+    log.warn(`CDP checks failed (non-fatal): ${err.message}`);
+  }
+  return violations;
+}
+
+/**
+ * Runs pa11y (HTML CodeSniffer) against the already-loaded page URL.
+ * Catches WCAG violations that axe-core may miss, particularly around
+ * heading hierarchy, link purpose, and form associations.
+ * @param {string} routeUrl - The URL to scan.
+ * @param {string[]} [axeTags] - WCAG level tags for standard filtering.
+ * @returns {Promise<Object[]>} Array of pa11y-sourced violations in axe-compatible format.
+ */
+async function runPa11yChecks(routeUrl, axeTags) {
+  const violations = [];
+  try {
+    let standard = "WCAG2AA";
+    if (axeTags) {
+      if (axeTags.includes("wcag2aaa")) standard = "WCAG2AAA";
+      else if (axeTags.includes("wcag2aa") || axeTags.includes("wcag21aa") || axeTags.includes("wcag22aa")) standard = "WCAG2AA";
+      else if (axeTags.includes("wcag2a")) standard = "WCAG2A";
+    }
+
+    const results = await pa11y(routeUrl, {
+      standard,
+      timeout: 30000,
+      wait: 2000,
+      chromeLaunchConfig: {
+        args: ["--no-sandbox", "--disable-setuid-sandbox"],
+      },
+      ignore: [
+        "WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail",
+        "WCAG2AA.Principle4.Guideline4_1.4_1_2.H91.A.NoContent",
+      ],
+    });
+
+    const impactMap = { 1: "serious", 2: "moderate", 3: "minor" };
+
+    for (const issue of results.issues || []) {
+      if (issue.type === "notice") continue;
+
+      const impact = impactMap[issue.typeCode] || "moderate";
+
+      let wcagCriterion = "";
+      const wcagMatch = issue.code?.match(/Guideline(\d+)_(\d+)\.(\d+)_(\d+)_(\d+)/);
+      if (wcagMatch) {
+        wcagCriterion = `${wcagMatch[3]}.${wcagMatch[4]}.${wcagMatch[5]}`;
+      }
+
+      const ruleId = `pa11y-${(issue.code || "unknown").replace(/\./g, "-").toLowerCase().slice(0, 60)}`;
+
+      violations.push({
+        id: ruleId,
+        impact,
+        tags: ["pa11y-check", ...(wcagCriterion ? [`wcag${wcagCriterion.replace(/\./g, "")}`] : [])],
+        description: issue.message || "pa11y detected an accessibility issue",
+        help: issue.message?.split(".")[0] || "Accessibility issue detected by HTML CodeSniffer",
+        helpUrl: wcagCriterion
+          ? `https://www.w3.org/WAI/WCAG21/Understanding/${wcagCriterion.replace(/\./g, "")}`
+          : "https://squizlabs.github.io/HTML_CodeSniffer/",
+        source: "pa11y",
+        nodes: [{
+          any: [],
+          all: [{
+            id: "pa11y-check",
+            data: { code: issue.code, context: issue.context?.slice(0, 200) },
+            relatedNodes: [],
+            impact,
+            message: issue.message || "",
+          }],
+          none: [],
+          impact,
+          html: issue.context || "",
+          target: issue.selector ? [issue.selector] : [],
+          failureSummary: `Fix all of the following:\n  ${issue.message || "Accessibility issue"}`,
+        }],
+      });
+    }
+  } catch (err) {
+    log.warn(`pa11y checks failed (non-fatal): ${err.message}`);
+  }
+  return violations;
+}
+
+/**
+ * Merges violations from multiple sources (axe-core, CDP, pa11y) and deduplicates.
+ * Deduplication is based on rule ID + first target selector combination.
+ * @param {Object[]} axeViolations - Violations from axe-core.
+ * @param {Object[]} cdpViolations - Violations from CDP checks.
+ * @param {Object[]} pa11yViolations - Violations from pa11y.
+ * @returns {Object[]} Merged and deduplicated violations array.
+ */
+function mergeViolations(axeViolations, cdpViolations, pa11yViolations) {
+  const seen = new Set();
+  const merged = [];
+
+  for (const v of axeViolations) {
+    const key = `${v.id}::${v.nodes?.[0]?.target?.[0] || ""}`;
+    seen.add(key);
+    merged.push(v);
+  }
+
+  for (const v of cdpViolations) {
+    const axeEquiv = {
+      "cdp-missing-accessible-name": ["button-name", "link-name", "input-name", "aria-command-name"],
+      "cdp-aria-hidden-focusable": ["aria-hidden-focus"],
+    };
+    const equivRules = axeEquiv[v.id] || [];
+    const target = v.nodes?.[0]?.target?.[0] || "";
+    const isDuplicate = equivRules.some((r) => seen.has(`${r}::${target}`));
+    if (!isDuplicate) {
+      const key = `${v.id}::${target}`;
+      if (!seen.has(key)) {
+        seen.add(key);
+        merged.push(v);
+      }
+    }
+  }
+
+  for (const v of pa11yViolations) {
+    const target = v.nodes?.[0]?.target?.[0] || "";
+    const key = `${v.id}::${target}`;
+    const selectorCovered = [...seen].some((k) => k.endsWith(`::${target}`) && target);
+    if (!seen.has(key) && (!selectorCovered || !target)) {
+      seen.add(key);
+      merged.push(v);
+    }
+  }
+
+  return merged;
+}
+
 /**
  * The main execution function for the accessibility scanner.
  * Coordinates browser setup, crawling/discovery, parallel scanning, and result saving.
@@ -630,6 +891,8 @@ async function main() {
       tabPages.push(await context.newPage());
     }
 
+    writeProgress("page", "running");
+
     for (let i = 0; i < routes.length; i += tabPages.length) {
       const batch = [];
       for (let j = 0; j < tabPages.length && i + j < routes.length; j++) {
@@ -640,6 +903,11 @@ async function main() {
             const routePath = routes[idx];
             log.info(`[${idx + 1}/${total}] Scanning: ${routePath}`);
             const targetUrl = new URL(routePath, baseUrl).toString();
+
+            writeProgress("page", "done");
+
+            // Step 1: axe-core
+            writeProgress("axe", "running");
             const result = await analyzeRoute(
               tabPage,
               targetUrl,
@@ -649,13 +917,51 @@ async function main() {
               args.timeoutMs,
               2,
               args.waitUntil,
+              args.axeTags,
+            );
+            const axeViolationCount = result.violations?.length || 0;
+            writeProgress("axe", "done", { found: axeViolationCount });
+            log.info(`axe-core: ${axeViolationCount} violation(s) found`);
+
+            // Step 2: CDP checks
+            writeProgress("cdp", "running");
+            const cdpViolations = await runCdpChecks(tabPage);
+            writeProgress("cdp", "done", { found: cdpViolations.length });
+            log.info(`CDP checks: ${cdpViolations.length} issue(s) found`);
+
+            // Step 3: pa11y
+            writeProgress("pa11y", "running");
+            const pa11yViolations = await runPa11yChecks(targetUrl, args.axeTags);
+            writeProgress("pa11y", "done", { found: pa11yViolations.length });
+            log.info(`pa11y: ${pa11yViolations.length} issue(s) found`);
+
+            // Step 4: Merge results
+            writeProgress("merge", "running");
+            const mergedViolations = mergeViolations(
+              result.violations || [],
+              cdpViolations,
+              pa11yViolations,
             );
-            if (args.screenshotsDir && result.violations) {
-              for (const violation of result.violations) {
+            writeProgress("merge", "done", {
+              axe: axeViolationCount,
+              cdp: cdpViolations.length,
+              pa11y: pa11yViolations.length,
+              merged: mergedViolations.length,
+            });
+            log.info(`Merged: ${mergedViolations.length} total unique violations (axe: ${axeViolationCount}, cdp: ${cdpViolations.length}, pa11y: ${pa11yViolations.length})`);
+
+            // Screenshots for merged violations
+            if (args.screenshotsDir && mergedViolations) {
+              for (const violation of mergedViolations) {
                 await captureElementScreenshot(tabPage, violation, idx);
               }
             }
-            results[idx] = { path: routePath, ...result };
+            results[idx] = {
+              path: routePath,
+              ...result,
+              violations: mergedViolations,
+              incomplete: result.incomplete || [],
+            };
           })(),
         );
       }