@diegovelasquezweb/a11y-engine 0.1.9 → 0.2.1

package/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **Programmatic API** — 7 exported functions accessible via `import { ... } from "@diegovelasquezweb/a11y-engine"`:
+  - `getEnrichedFindings(input, options?)` — normalizes raw findings, canonicalizes pa11y rules, enriches with fix intelligence, infers effort, sorts by severity. Accepts a full scan payload or a raw findings array. Supports `screenshotUrlBuilder` callback for consumer-specific screenshot URLs.
+  - `getAuditSummary(findings, payload?)` — computes severity totals, compliance score, grade label, WCAG pass/fail status, persona impact groups, quick wins, target URL, and detected stack from metadata.
+  - `getPDFReport(payload, options?)` — generates a formal A4 PDF compliance report via Playwright. Returns `{ buffer, contentType }`.
+  - `getChecklist(options?)` — generates a standalone manual accessibility testing checklist as HTML. Returns `{ html, contentType }`.
+  - `getHTMLReport(payload, options?)` — generates an interactive HTML audit dashboard with severity filters and fix guidance. Supports embedded base64 screenshots via `screenshotsDir`. Returns `{ html, contentType }`.
+  - `getRemediationGuide(payload, options?)` — generates a Markdown remediation guide optimized for AI agents. Supports optional `patternFindings` from source scanner. Returns `{ markdown, contentType }`.
+  - `getSourcePatterns(projectDir, options?)` — scans project source code for accessibility patterns not detectable by axe-core. Returns `{ findings, summary }`.
+- **TypeScript type declarations** shipped with the package (`scripts/index.d.mts`):
+  - `Finding` — raw finding with all snake_case fields
+  - `EnrichedFinding` — extends Finding with camelCase aliases and enriched fields
+  - `AuditSummary` — full audit summary including totals, score, personas, quick wins, detected stack
+  - `SeverityTotals`, `PersonaGroup`, `DetectedStack`, `ComplianceScore`
+  - `ScanPayload`, `EnrichmentOptions`, `ReportOptions`
+  - `PDFReport`, `HTMLReport`, `ChecklistReport`, `RemediationGuide`
+  - `SourcePatternFinding`, `SourcePatternResult`, `SourcePatternOptions`
+- `exports` and `main` fields in `package.json` pointing to `scripts/index.mjs`
+- `--axe-tags` CLI flag passthrough from `audit.mjs` to `dom-scanner.mjs`
+- `resolveScanDirs` exported from `source-scanner.mjs` for programmatic use
+
+### Changed
+
+- `getEnrichedFindings` always creates camelCase aliases (`fixDescription`, `fixCode`, `screenshotPath`, `wcagCriterionId`, `impactedUsers`, etc.) regardless of whether the finding already has fix data — fixes bug where camelCase fields were `undefined` when snake_case data existed
+- `getEnrichedFindings` infers `effort` field after intelligence enrichment: findings with `fixCode` default to `"low"`, others to `"high"` — unless an explicit effort value already exists
+- `getEnrichedFindings` normalizes raw findings internally — consumers no longer need to pre-process the findings array
+- `getEnrichedFindings` sorts findings by severity (Critical > Serious > Moderate > Minor) then by ID
+- `getAuditSummary` now includes `quickWins` (top 3 Critical/Serious findings with fix code), `targetUrl` (extracted from metadata with fallbacks), and `detectedStack` (framework/CMS/libraries from project context)
+- CLI (`audit.mjs`) continues to work standalone — the programmatic API is additive
+
 ---
 
 ## [0.1.3] — 2026-03-14

package/README.md

@@ -1,176 +1,218 @@
 # @diegovelasquezweb/a11y-engine
 
-Multi-engine WCAG 2.2 AA accessibility audit engine. Combines three scanning engines (axe-core, Chrome DevTools Protocol, and pa11y), merges and deduplicates their findings, enriches results with fix intelligence, and produces structured artifacts for developers, agents, and stakeholders.
+Multi-engine WCAG 2.2 accessibility audit engine. Combines three scanning engines (axe-core, Chrome DevTools Protocol, and pa11y), merges and deduplicates their findings, enriches results with fix intelligence, and produces structured artifacts for developers, agents, and stakeholders.
 
 ## What it is
 
-A Node.js CLI and programmatic engine that:
+A Node.js package that works two ways:
 
-1. Crawls a target URL and discovers routes automatically
-2. Runs three independent accessibility engines against each page:
-   - **axe-core** — industry-standard WCAG rule engine, injected into the live page via Playwright
-   - **CDP** (Chrome DevTools Protocol) — queries the browser's accessibility tree directly for issues axe may miss (missing accessible names, aria-hidden on focusable elements)
-   - **pa11y** (HTML CodeSniffer) — catches WCAG violations around heading hierarchy, link purpose, and form associations
-3. Merges and deduplicates findings across all three engines
-4. Optionally scans project source code for patterns no runtime engine can detect
-5. Enriches each finding with stack-aware fix guidance, selectors, and verification commands
-6. Produces a full artifact set: JSON data, Markdown remediation guide, HTML dashboard, PDF compliance report, and manual testing checklist
+1. **CLI** — run `npx a11y-audit --base-url <url>` to scan a site and generate reports
+2. **Programmatic API** — import functions directly to normalize findings, compute scores, and generate reports in your own application
 
-## Why use this engine
+## Programmatic API
 
-| Capability | With this engine | Without |
+```bash
+npm install @diegovelasquezweb/a11y-engine
+```
+
+```ts
+import {
+  getEnrichedFindings,
+  getAuditSummary,
+  getPDFReport,
+  getChecklist,
+  getHTMLReport,
+  getRemediationGuide,
+  getSourcePatterns,
+} from "@diegovelasquezweb/a11y-engine";
+```
+
+### getEnrichedFindings
+
+Normalizes raw scan findings, canonicalizes pa11y rules to axe equivalents, enriches with fix intelligence, infers effort, and sorts by severity.
+
+```ts
+const findings = getEnrichedFindings(scanPayload, {
+  screenshotUrlBuilder: (path) => `/api/screenshot?path=${encodeURIComponent(path)}`,
+});
+```
+
+| Parameter | Type | Description |
 | :--- | :--- | :--- |
-| **Multi-engine scanning** | axe-core + CDP accessibility tree + pa11y (HTML CodeSniffer) with cross-engine deduplication | Single engine — higher false-negative rate |
-| **Full WCAG 2.2 Coverage** | Three runtime engines + source code pattern scanner | Runtime scan only — misses structural and 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 |
+| `input` | `ScanPayload \| Finding[] \| Record<string, unknown>[]` | Raw scan output or findings array |
+| `options.screenshotUrlBuilder` | `(rawPath: string) => string` | Transforms screenshot file paths into consumer-specific URLs |
 
-## How the scan pipeline works
+**Returns**: `EnrichedFinding[]` — normalized, enriched, sorted findings with both snake_case and camelCase fields.
+
+### getAuditSummary
+
+Computes a complete audit summary from enriched findings.
 
+```ts
+const summary = getAuditSummary(findings, scanPayload);
+// summary.score         → 72
+// summary.label         → "Good"
+// summary.wcagStatus    → "Fail"
+// summary.totals        → { Critical: 1, Serious: 3, Moderate: 5, Minor: 2 }
+// summary.personaGroups → { screenReader: {...}, keyboard: {...}, ... }
+// summary.quickWins     → [top 3 fixable Critical/Serious findings]
+// summary.targetUrl     → "https://example.com"
+// summary.detectedStack → { framework: "nextjs", cms: null, uiLibraries: [] }
 ```
-URL
- |
- v
-[1. Crawl & Discover]  sitemap.xml / BFS link crawl / explicit --routes
- |
- v
-[2. Navigate]           Playwright opens each route in Chromium
- |
- +---> [axe-core]       Injects axe into the page, runs WCAG tag checks
- |
- +---> [CDP]            Opens a CDP session, reads the full accessibility tree
- |
- +---> [pa11y]          Launches HTML CodeSniffer via Puppeteer Chrome
- |
- v
-[3. Merge & Dedup]      Combines findings, removes cross-engine duplicates
- |
- v
-[4. Analyze]            Enriches with WCAG mapping, severity, fix code, framework hints
- |
- v
-[5. Reports]            HTML dashboard, PDF, checklist, Markdown remediation
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `findings` | `EnrichedFinding[]` | Output from `getEnrichedFindings` |
+| `payload` | `ScanPayload \| null` | Original scan payload for metadata extraction |
+
+**Returns**: `AuditSummary`
+
+### getPDFReport
+
+Generates a formal A4 PDF compliance report using Playwright.
+
+```ts
+const { buffer, contentType } = await getPDFReport(scanPayload, {
+  baseUrl: "https://example.com",
+});
+fs.writeFileSync("report.pdf", buffer);
 ```
 
-## Installation
+**Returns**: `Promise<PDFReport>` — `{ buffer: Buffer, contentType: "application/pdf" }`
 
-```bash
-npm install @diegovelasquezweb/a11y-engine
-npx playwright install chromium
-npx puppeteer browsers install chrome
+### getHTMLReport
+
+Generates an interactive HTML audit dashboard with severity filters, persona impact, and fix guidance.
+
+```ts
+const { html, contentType } = await getHTMLReport(scanPayload, {
+  baseUrl: "https://example.com",
+  screenshotsDir: "/path/to/.audit/screenshots",
+});
 ```
 
-```bash
-pnpm add @diegovelasquezweb/a11y-engine
-pnpm exec playwright install chromium
-npx puppeteer browsers install chrome
+**Returns**: `Promise<HTMLReport>` — `{ html: string, contentType: "text/html" }`
+
+### getChecklist
+
+Generates a standalone manual accessibility testing checklist.
+
+```ts
+const { html, contentType } = await getChecklist({
+  baseUrl: "https://example.com",
+});
 ```
 
-> **Two browsers are required:**
-> - **Playwright Chromium** — used by axe-core and CDP checks
-> - **Puppeteer Chrome** — used by pa11y (HTML CodeSniffer)
->
-> These are separate browser installations. If Puppeteer Chrome is missing, pa11y checks fail silently (non-fatal) and the scan continues with axe + CDP only.
+**Returns**: `Promise<ChecklistReport>` — `{ html: string, contentType: "text/html" }`
+
+### getRemediationGuide
+
+Generates a Markdown remediation guide optimized for AI agents.
+
+```ts
+const { markdown, contentType } = await getRemediationGuide(scanPayload, {
+  baseUrl: "https://example.com",
+  patternFindings: sourcePatternResult,
+});
+```
+
+**Returns**: `Promise<RemediationGuide>` — `{ markdown: string, contentType: "text/markdown" }`
+
+### getSourcePatterns
+
+Scans project source code for accessibility patterns not detectable by axe-core at runtime.
+
+```ts
+const { findings, summary } = await getSourcePatterns("/path/to/project", {
+  framework: "nextjs",
+});
+// summary → { total: 12, confirmed: 10, potential: 2 }
+```
+
+**Returns**: `Promise<SourcePatternResult>` — `{ findings: SourcePatternFinding[], summary: { total, confirmed, potential } }`
+
+## CLI usage
 
-## Quick start
+The CLI runs the full scan pipeline: crawl, scan with 3 engines, merge, analyze, and generate reports.
 
 ```bash
-# Minimal scan — produces remediation.md in .audit/
+# Minimal scan
 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)
+# Scan with source code intelligence
 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
+### Targeting and 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. |
+| `--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 for stack-aware fixes and source pattern scanning |
 
 ### 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. |
-| `--axe-tags` | `<csv>` | `wcag2a,wcag2aa,wcag21a,wcag21aa,wcag22a,wcag22aa` | axe-core WCAG tag filter. |
-| `--framework` | `<name>` | — | Override auto-detected stack. Supported: `nextjs`, `gatsby`, `react`, `nuxt`, `vue`, `angular`, `astro`, `svelte`, `shopify`, `wordpress`, `drupal`. |
+| `--target` | `<text>` | `WCAG 2.2 AA` | Compliance target label in reports |
+| `--axe-tags` | `<csv>` | `wcag2a,wcag2aa,wcag21a,wcag21aa,wcag22a,wcag22aa` | axe-core WCAG tag filter |
+| `--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 (`nextjs`, `react`, `vue`, `angular`, `svelte`, `shopify`, `wordpress`, etc.) |
 
-### Execution & emulation
+### Execution and 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/`. |
+| `--color-scheme` | `light\|dark` | `light` | Emulate `prefers-color-scheme` |
+| `--wait-until` | `domcontentloaded\|load\|networkidle` | `domcontentloaded` | Playwright page load strategy |
+| `--viewport` | `<WxH>` | — | Viewport size (e.g. `375x812`) |
+| `--wait-ms` | `<num>` | `2000` | Delay after page load before scanning (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 |
 
 ### 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
-# 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
+| `--with-reports` | — | `false` | Generate HTML + PDF + Checklist reports |
+| `--output` | `<path>` | — | Output path for `report.html` |
+| `--skip-patterns` | — | `false` | Disable source code pattern scanner |
 
-# 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
+## How the scan pipeline works
 
-# Ignore known false positives
-a11y-audit --base-url https://example.com --ignore-findings color-contrast,frame-title
 ```
-
-## Output artifacts
-
-All artifacts are written to `.audit/` relative to the package root.
-
-| File | Always generated | Description |
-| :--- | :--- | :--- |
-| `a11y-scan-results.json` | Yes | Raw merged results from axe-core + CDP + pa11y per route |
-| `a11y-findings.json` | Yes | Enriched findings with fix intelligence, WCAG mapping, and severity |
-| `progress.json` | Yes | Real-time scan progress with per-engine step status and finding counts |
-| `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.
+URL
+ |
+ v
+[1. Crawl & Discover]  sitemap.xml / BFS link crawl / explicit --routes
+ |
+ v
+[2. Navigate]           Playwright opens each route in Chromium
+ |
+ +---> [axe-core]       Injects axe into the page, runs WCAG tag checks
+ |
+ +---> [CDP]            Opens a CDP session, reads the full accessibility tree
+ |
+ +---> [pa11y]          Launches HTML CodeSniffer via Puppeteer Chrome
+ |
+ v
+[3. Merge & Dedup]      Combines findings, removes cross-engine duplicates
+ |
+ v
+[4. Analyze]            Enriches with WCAG mapping, severity, fix code, framework hints
+ |
+ v
+[5. Reports]            HTML dashboard, PDF, checklist, Markdown remediation
+```
 
 ## Scan engines
 
@@ -181,52 +223,48 @@ The primary engine. Runs Deque's axe-core rule set against the live DOM inside P
 ### CDP (Chrome DevTools Protocol)
 
 Queries the browser's full accessibility tree via a CDP session. Catches issues axe may miss:
-- Interactive elements (buttons, links, inputs) with no accessible name
+- Interactive elements with no accessible name
 - Focusable elements hidden with `aria-hidden`
 
 ### pa11y (HTML CodeSniffer)
 
-Runs Squiz's HTML CodeSniffer via Puppeteer Chrome. Catches WCAG violations around:
-- Heading hierarchy
-- Link purpose
-- Form label associations
+Runs Squiz's HTML CodeSniffer via Puppeteer Chrome. Catches WCAG violations around heading hierarchy, link purpose, and form label associations.
 
 Requires a separate Chrome installation (`npx puppeteer browsers install chrome`). If Chrome is missing, pa11y fails silently and the scan continues with axe + CDP.
 
-### Merge & deduplication
-
-After all three engines run, findings are merged and deduplicated:
-- axe findings are added first (baseline)
-- CDP findings are checked against axe equivalents (e.g. `cdp-missing-accessible-name` vs `button-name`) to avoid duplicates
-- pa11y findings are checked against existing selectors to avoid triple-reporting the same element
-
-## Troubleshooting
-
-**`Error: browserType.launch: Executable doesn't exist`**
-Run `npx playwright install chromium` (or `pnpm exec playwright install chromium`).
+## Output artifacts
 
-**`pa11y checks failed (non-fatal): Could not find Chrome`**
-pa11y requires Puppeteer's Chrome, which is separate from Playwright's Chromium. Install it with `npx puppeteer browsers install chrome`.
+All artifacts are written to `.audit/` relative to the package root.
 
-**`Missing required argument: --base-url`**
-The flag is required. Provide a full URL including protocol: `--base-url https://example.com`.
+| File | Always generated | Description |
+| :--- | :--- | :--- |
+| `a11y-scan-results.json` | Yes | Raw merged results from axe + CDP + pa11y per route |
+| `a11y-findings.json` | Yes | Enriched findings with fix intelligence |
+| `progress.json` | Yes | Real-time scan progress with per-engine step status |
+| `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 |
 
-**Scan returns 0 findings on an SPA**
-Use `--wait-until networkidle --wait-ms 3000` to let async content render before the engines run.
+## Installation
 
-**`--with-reports` exits without generating PDF**
-Ensure `--output` is also set and points to an `.html` file path: `--output ./audit/report.html`.
+```bash
+npm install @diegovelasquezweb/a11y-engine
+npx playwright install chromium
+npx puppeteer browsers install chrome
+```
 
-**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.
+> **Two browsers are required:**
+> - **Playwright Chromium** — used by axe-core and CDP checks
+> - **Puppeteer Chrome** — used by pa11y (HTML CodeSniffer)
 
 ## Documentation
 
 | Resource | Description |
 | :--- | :--- |
-| [Architecture](https://github.com/diegovelasquezweb/a11y-engine/blob/main/docs/architecture.md) | How the multi-engine scanner 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 |
+| [Architecture](docs/architecture.md) | How the multi-engine scanner pipeline works |
+| [CLI Handbook](docs/cli-handbook.md) | Full flag reference and usage patterns |
+| [Output Artifacts](docs/outputs.md) | Schema and structure of every generated file |
 
 ## License
 

package/docs/architecture.md

@@ -205,6 +205,28 @@ Assets are static JSON files bundled with the package under `assets/`. They are
 | `remediation/axe-check-maps.json` | axe check-to-rule mapping |
 | `remediation/source-boundaries.json` | Framework-specific source file locations |
 
+## Programmatic API
+
+In addition to the CLI pipeline, the engine exports 7 functions via `scripts/index.mjs` for direct consumption by Node.js applications (e.g. `a11y-scanner`). These functions reuse the same internal renderers, assets, and enrichment logic as the CLI — no duplication.
+
+```
+scripts/index.mjs (public API)
+  ├── getEnrichedFindings()   ← uses asset-loader, intelligence.json, pa11y-config.json
+  ├── getAuditSummary()       ← uses compliance-config.json, wcag-reference.json
+  ├── getPDFReport()          ← uses reports/renderers/pdf.mjs + Playwright
+  ├── getHTMLReport()         ← uses reports/renderers/html.mjs + findings.mjs
+  ├── getChecklist()          ← uses reports/renderers/html.mjs (manual checks)
+  ├── getRemediationGuide()   ← uses reports/renderers/md.mjs
+  └── getSourcePatterns()     ← uses engine/source-scanner.mjs
+```
+
+### Key design decisions
+
+- **No filesystem output** — all API functions return data in memory (strings, Buffers, arrays). The consumer decides where to write.
+- **Payload in, results out** — functions accept the raw `{ findings, metadata }` payload that `a11y-findings.json` contains. No need to resolve paths or read files.
+- **`screenshotUrlBuilder` callback** — `getEnrichedFindings` accepts an optional function to transform raw screenshot paths (e.g. `screenshots/0-color-contrast.png`) into consumer-specific URLs (e.g. `/api/scan/{id}/screenshot?path=...`). This keeps URL construction out of the engine.
+- **CLI unaffected** — the `audit.mjs` orchestrator and all CLI builders continue to work exactly as before. The API is additive.
+
 ## Execution model and timeouts
 
 `audit.mjs` spawns each stage as a child process via `node:child_process`. All child processes:

package/docs/cli-handbook.md

@@ -235,3 +235,7 @@ The engine never exits `1` just because findings were found. Exit `1` only indic
 REMEDIATION_PATH=<abs-path>   # always printed on success
 REPORT_PATH=<abs-path>        # only printed when --with-reports is set
 ```
+
+## Programmatic alternative
+
+For applications that embed the engine as a dependency (e.g. web dashboards, CI pipelines), the engine also exports a programmatic API that processes scan data in memory without filesystem operations. See the [README](../README.md#programmatic-api) for full documentation.

package/docs/outputs.md

@@ -257,40 +257,54 @@ 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"));
+### Using the programmatic API (recommended)
+
+The engine exports functions that process scan data directly in memory — no filesystem path resolution needed:
+
+```ts
+import {
+  getEnrichedFindings,
+  getAuditSummary,
+  getPDFReport,
+  getHTMLReport,
+  getChecklist,
+  getRemediationGuide,
+  getSourcePatterns,
+} from "@diegovelasquezweb/a11y-engine";
+
+// After running audit.mjs via CLI, read the findings file
+const payload = JSON.parse(fs.readFileSync(findingsPath, "utf-8"));
+
+// Enrich findings with fix intelligence
+const findings = getEnrichedFindings(payload, {
+  screenshotUrlBuilder: (path) => `/api/screenshot?path=${encodeURIComponent(path)}`,
+});
+
+// Get full audit summary
+const summary = getAuditSummary(findings, payload);
+
+// Generate reports
+const pdf = await getPDFReport(payload, { baseUrl: "https://example.com" });
+const html = await getHTMLReport(payload, { baseUrl: "https://example.com" });
+const checklist = await getChecklist({ baseUrl: "https://example.com" });
+const guide = await getRemediationGuide(payload, { baseUrl: "https://example.com" });
+
+// Scan source code patterns
+const patterns = await getSourcePatterns("/path/to/project", { framework: "nextjs" });
 ```
 
-> 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");
-```
+See the [README](../README.md#programmatic-api) for full API documentation and type signatures.
 
 ### Reading `progress.json` for live UI updates
 
+During CLI execution, `progress.json` is written to `.audit/` in real-time. This is relevant when using the CLI via `child_process` — the programmatic API does not write progress files.
+
 ```js
 const progressPath = path.join(engineRoot, ".audit", "progress.json");
 
-// Poll this file during scan execution
 if (fs.existsSync(progressPath)) {
   const progress = JSON.parse(fs.readFileSync(progressPath, "utf-8"));
   console.log(`Current step: ${progress.currentStep}`);
-  console.log(`axe found: ${progress.steps?.axe?.found ?? "pending"}`);
 }
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegovelasquezweb/a11y-engine",
-  "version": "0.1.9",
+  "version": "0.2.1",
   "description": "WCAG 2.2 AA accessibility audit engine — scanner, analyzer, and report builders",
   "type": "module",
   "license": "MIT",

package/scripts/engine/analyzer.mjs

@@ -949,17 +949,23 @@ export function collectIncompleteFindings(routes) {
 }
 
 /**
- * The main execution function for the analyzer script.
- * Reads scan results, processes findings, and writes the final findings JSON.
+ * Runs the analyzer programmatically on a scan payload.
+ * @param {Object} scanPayload - The raw scan output from dom-scanner ({ routes, base_url, projectContext, ... }).
+ * @param {{ ignoreFindings?: string[], framework?: string, output?: string }} [options={}]
+ * @returns {Object} The enriched findings payload { findings, incomplete_findings, metadata, ... }.
  */
-function main() {
-  const args = parseArgs(process.argv.slice(2));
-  const ignoredRules = new Set(args.ignoreFindings);
+export function runAnalyzer(scanPayload, options = {}) {
+  if (!scanPayload) throw new Error("Missing scan payload");
 
-  const payload = readJson(args.input);
-  if (!payload) throw new Error(`Input not found or invalid: ${args.input}`);
+  const args = {
+    input: null,
+    output: options.output || getInternalPath("a11y-findings.json"),
+    ignoreFindings: options.ignoreFindings || [],
+    framework: options.framework || null,
+  };
 
-  const result = buildFindings(payload, args);
+  const ignoredRules = new Set(args.ignoreFindings);
+  const result = buildFindings(scanPayload, args);
 
   if (ignoredRules.size > 0) {
     const knownIds = new Set(
@@ -989,15 +995,15 @@ function main() {
   if (deduplicatedCount > 0) log.info(`Deduplicated ${deduplicatedCount} cross-page finding group(s).`);
 
   const overallAssessment = computeOverallAssessment(dedupedFindings);
-  const passedCriteria = computePassedCriteria(payload.routes || [], WCAG_CRITERION_MAP, dedupedFindings);
-  const outOfScope = computeOutOfScope(payload.routes || []);
+  const passedCriteria = computePassedCriteria(scanPayload.routes || [], WCAG_CRITERION_MAP, dedupedFindings);
+  const outOfScope = computeOutOfScope(scanPayload.routes || []);
   const recommendations = computeRecommendations(dedupedFindings);
-  const testingMethodology = computeTestingMethodology(payload);
-  const incompleteFindings = collectIncompleteFindings(payload.routes || []);
+  const testingMethodology = computeTestingMethodology(scanPayload);
+  const incompleteFindings = collectIncompleteFindings(scanPayload.routes || []);
   if (incompleteFindings.length > 0)
     log.info(`${incompleteFindings.length} incomplete finding(s) require manual review.`);
 
-  writeJson(args.output, {
+  const outputPayload = {
     ...result,
     findings: dedupedFindings,
     incomplete_findings: incompleteFindings,
@@ -1011,12 +1017,32 @@ function main() {
       fpFiltered: fpRemovedCount,
       deduplicatedCount,
     },
-  });
+  };
+
+  // Write to disk for CLI compatibility
+  writeJson(args.output, outputPayload);
 
   if (dedupedFindings.length === 0) {
     log.info("Congratulations, no issues found.");
   }
   log.success(`Findings processed and saved to ${args.output}`);
+
+  return outputPayload;
+}
+
+/**
+ * CLI entry point — reads from disk, processes, writes to disk.
+ */
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const payload = readJson(args.input);
+  if (!payload) throw new Error(`Input not found or invalid: ${args.input}`);
+
+  runAnalyzer(payload, {
+    ignoreFindings: args.ignoreFindings,
+    framework: args.framework,
+    output: args.output,
+  });
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) {

package/scripts/engine/dom-scanner.mjs

@@ -489,7 +489,16 @@ async function analyzeRoute(
  * @param {"pending"|"running"|"done"|"error"} status - Step status.
  * @param {Object} [extra={}] - Additional metadata.
  */
+/** @type {((step: string, status: string, extra?: object) => void) | null} */
+let _onProgressCallback = null;
+
 function writeProgress(step, status, extra = {}) {
+  // Notify external callback if set (programmatic API)
+  if (_onProgressCallback) {
+    _onProgressCallback(step, status, extra);
+  }
+
+  // Always write to disk for CLI consumers
   const progressPath = getInternalPath("progress.json");
   let progress = {};
   try {
@@ -788,8 +797,45 @@ function mergeViolations(axeViolations, cdpViolations, pa11yViolations) {
  * Coordinates browser setup, crawling/discovery, parallel scanning, and result saving.
  * @throws {Error} If navigation to the base URL fails or browser setup issues occur.
  */
-async function main() {
-  const args = parseArgs(process.argv.slice(2));
+/**
+ * Runs the DOM scanner programmatically.
+ * @param {Object} options - Scanner configuration (same shape as CLI args object).
+ * @param {{ onProgress?: (step: string, status: string, extra?: object) => void }} [callbacks={}]
+ * @returns {Promise<Object>} The scan payload { generated_at, base_url, onlyRule, projectContext, routes }.
+ */
+export async function runDomScanner(options = {}, callbacks = {}) {
+  const args = {
+    baseUrl: options.baseUrl || "",
+    routes: options.routes || "",
+    output: options.output || getInternalPath("a11y-scan-results.json"),
+    maxRoutes: options.maxRoutes ?? DEFAULTS.maxRoutes,
+    waitMs: options.waitMs ?? DEFAULTS.waitMs,
+    timeoutMs: options.timeoutMs ?? DEFAULTS.timeoutMs,
+    headless: options.headless ?? DEFAULTS.headless,
+    waitUntil: options.waitUntil ?? DEFAULTS.waitUntil,
+    colorScheme: options.colorScheme || null,
+    screenshotsDir: options.screenshotsDir || getInternalPath("screenshots"),
+    excludeSelectors: options.excludeSelectors || [],
+    onlyRule: options.onlyRule || null,
+    crawlDepth: Math.min(Math.max(options.crawlDepth ?? DEFAULTS.crawlDepth, 1), 3),
+    viewport: options.viewport || null,
+    axeTags: options.axeTags || null,
+  };
+
+  if (!args.baseUrl) throw new Error("Missing required option: baseUrl");
+
+  if (callbacks.onProgress) {
+    _onProgressCallback = callbacks.onProgress;
+  }
+
+  try {
+    return await _runDomScannerInternal(args);
+  } finally {
+    _onProgressCallback = null;
+  }
+}
+
+async function _runDomScannerInternal(args) {
   const baseUrl = new URL(args.baseUrl).toString();
   const origin = new URL(baseUrl).origin;
 
@@ -850,7 +896,7 @@ async function main() {
   } catch (err) {
     log.error(`Fatal: Could not load base URL ${baseUrl}: ${err.message}`);
     await browser.close();
-    process.exit(1);
+    throw new Error(`Could not load base URL ${baseUrl}: ${err.message}`);
   }
 
   /**
@@ -1036,6 +1082,13 @@ async function main() {
 
   writeJson(args.output, payload);
   log.success(`Routes scan complete. Results saved to ${args.output}`);
+
+  return payload;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  await runDomScanner(args);
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) {

package/scripts/engine/source-scanner.mjs

@@ -113,7 +113,7 @@ function walkFiles(dir, extensions, results = []) {
  * @param {string} projectDir
  * @returns {string[]}
  */
-function resolveScanDirs(framework, projectDir) {
+export function resolveScanDirs(framework, projectDir) {
   const boundaries = framework ? SOURCE_BOUNDARIES?.[framework] : null;
   if (!boundaries) return [projectDir];
 

package/scripts/index.d.mts

@@ -137,11 +137,87 @@ export interface PDFReport {
   contentType: "application/pdf";
 }
 
+export interface HTMLReport {
+  html: string;
+  contentType: "text/html";
+}
+
 export interface ChecklistReport {
   html: string;
   contentType: "text/html";
 }
 
+export interface RemediationGuide {
+  markdown: string;
+  contentType: "text/markdown";
+}
+
+export interface SourcePatternFinding {
+  id: string;
+  pattern_id: string;
+  title: string;
+  severity: string;
+  wcag: string;
+  wcag_criterion: string;
+  wcag_level: string;
+  type: string;
+  fix_description: string | null;
+  status: "confirmed" | "potential";
+  file: string;
+  line: number;
+  match: string;
+  context: string;
+  source: "code-pattern";
+}
+
+export interface SourcePatternResult {
+  findings: SourcePatternFinding[];
+  summary: {
+    total: number;
+    confirmed: number;
+    potential: number;
+  };
+}
+
+export interface HTMLReportOptions extends ReportOptions {
+  screenshotsDir?: string;
+}
+
+export interface RemediationOptions extends ReportOptions {
+  patternFindings?: Record<string, unknown> | null;
+}
+
+export interface SourcePatternOptions {
+  framework?: string;
+  onlyPattern?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Audit options
+// ---------------------------------------------------------------------------
+
+export interface RunAuditOptions {
+  baseUrl: string;
+  maxRoutes?: number;
+  crawlDepth?: number;
+  routes?: string;
+  waitMs?: number;
+  timeoutMs?: number;
+  headless?: boolean;
+  waitUntil?: string;
+  colorScheme?: string;
+  viewport?: { width: number; height: number };
+  axeTags?: string[];
+  onlyRule?: string;
+  excludeSelectors?: string[];
+  ignoreFindings?: string[];
+  framework?: string;
+  projectDir?: string;
+  skipPatterns?: boolean;
+  screenshotsDir?: string;
+  onProgress?: (step: string, status: string, extra?: Record<string, unknown>) => void;
+}
+
 // ---------------------------------------------------------------------------
 // Enrichment options
 // ---------------------------------------------------------------------------
@@ -154,6 +230,8 @@ export interface EnrichmentOptions {
 // Public API
 // ---------------------------------------------------------------------------
 
+export function runAudit(options: RunAuditOptions): Promise<ScanPayload>;
+
 export function getEnrichedFindings(
   input: ScanPayload | Finding[] | Record<string, unknown>[],
   options?: EnrichmentOptions
@@ -172,3 +250,18 @@ export function getPDFReport(
 export function getChecklist(
   options?: Pick<ReportOptions, "baseUrl">
 ): Promise<ChecklistReport>;
+
+export function getHTMLReport(
+  payload: ScanPayload,
+  options?: HTMLReportOptions
+): Promise<HTMLReport>;
+
+export function getRemediationGuide(
+  payload: ScanPayload & { incomplete_findings?: unknown[] },
+  options?: RemediationOptions
+): Promise<RemediationGuide>;
+
+export function getSourcePatterns(
+  projectDir: string,
+  options?: SourcePatternOptions
+): Promise<SourcePatternResult>;

package/scripts/index.mjs

@@ -424,6 +424,118 @@ export function getAuditSummary(findings, payload = null) {
   };
 }
 
+// ---------------------------------------------------------------------------
+// Full audit pipeline
+// ---------------------------------------------------------------------------
+
+/**
+ * Runs a complete accessibility audit: crawl + scan (axe + CDP + pa11y) + analyze.
+ * Returns the enriched scan payload ready for getEnrichedFindings().
+ *
+ * @param {{
+ *   baseUrl: string,
+ *   maxRoutes?: number,
+ *   crawlDepth?: number,
+ *   routes?: string,
+ *   waitMs?: number,
+ *   timeoutMs?: number,
+ *   headless?: boolean,
+ *   waitUntil?: string,
+ *   colorScheme?: string,
+ *   viewport?: { width: number, height: number },
+ *   axeTags?: string[],
+ *   onlyRule?: string,
+ *   excludeSelectors?: string[],
+ *   ignoreFindings?: string[],
+ *   framework?: string,
+ *   projectDir?: string,
+ *   skipPatterns?: boolean,
+ *   onProgress?: (step: string, status: string, extra?: object) => void,
+ * }} options
+ * @returns {Promise<{ findings: object[], metadata: object, incomplete_findings?: object[] }>}
+ */
+export async function runAudit(options) {
+  if (!options.baseUrl) throw new Error("runAudit requires baseUrl");
+
+  const { runDomScanner } = await import("./engine/dom-scanner.mjs");
+  const { runAnalyzer } = await import("./engine/analyzer.mjs");
+
+  const onProgress = options.onProgress || null;
+
+  // Step 1: DOM scan (axe + CDP + pa11y)
+  if (onProgress) onProgress("page", "running");
+
+  const scanPayload = await runDomScanner(
+    {
+      baseUrl: options.baseUrl,
+      maxRoutes: options.maxRoutes,
+      crawlDepth: options.crawlDepth,
+      routes: options.routes,
+      waitMs: options.waitMs,
+      timeoutMs: options.timeoutMs,
+      headless: options.headless,
+      waitUntil: options.waitUntil,
+      colorScheme: options.colorScheme,
+      viewport: options.viewport,
+      axeTags: options.axeTags,
+      onlyRule: options.onlyRule,
+      excludeSelectors: options.excludeSelectors,
+      screenshotsDir: options.screenshotsDir,
+    },
+    { onProgress },
+  );
+
+  // Step 2: Analyze + enrich
+  if (onProgress) onProgress("intelligence", "running");
+
+  const findingsPayload = runAnalyzer(scanPayload, {
+    ignoreFindings: options.ignoreFindings,
+    framework: options.framework,
+  });
+
+  // Step 3: Source patterns (optional)
+  if (options.projectDir && !options.skipPatterns) {
+    try {
+      const { resolveScanDirs, scanPattern } = await import("./engine/source-scanner.mjs");
+      const { patterns } = loadAssetJson(ASSET_PATHS.remediation.codePatterns, "code-patterns.json");
+
+      let resolvedFramework = options.framework;
+      if (!resolvedFramework && findingsPayload.metadata?.projectContext?.framework) {
+        resolvedFramework = findingsPayload.metadata.projectContext.framework;
+      }
+
+      const scanDirs = resolveScanDirs(resolvedFramework || null, options.projectDir);
+      const allPatternFindings = [];
+      for (const pattern of patterns) {
+        for (const scanDir of scanDirs) {
+          allPatternFindings.push(...scanPattern(pattern, scanDir, options.projectDir));
+        }
+      }
+
+      if (allPatternFindings.length > 0) {
+        findingsPayload.patternFindings = {
+          generated_at: new Date().toISOString(),
+          project_dir: options.projectDir,
+          findings: allPatternFindings,
+          summary: {
+            total: allPatternFindings.length,
+            confirmed: allPatternFindings.filter((f) => f.status === "confirmed").length,
+            potential: allPatternFindings.filter((f) => f.status === "potential").length,
+          },
+        };
+      }
+    } catch (err) {
+      // Non-fatal: source scanning is optional
+      const msg = err instanceof Error ? err.message : String(err);
+      console.warn(`Source pattern scan failed (non-fatal): ${msg}`);
+    }
+  }
+
+  if (onProgress) onProgress("intelligence", "done");
+
+  return findingsPayload;
+}
+
 // ---------------------------------------------------------------------------
 // Report generation
 // ---------------------------------------------------------------------------
@@ -608,3 +720,204 @@ export async function getChecklist(options = {}) {
     contentType: "text/html",
   };
 }
+
+// ---------------------------------------------------------------------------
+// HTML Report
+// ---------------------------------------------------------------------------
+
+/**
+ * Generates an interactive HTML audit dashboard from raw scan findings.
+ * Embeds screenshots as base64 data URIs when available.
+ * @param {{ findings: object[], metadata?: object }} payload - Raw scan output.
+ * @param {{ baseUrl?: string, target?: string, screenshotsDir?: string }} [options={}]
+ * @returns {Promise<{ html: string, contentType: "text/html" }>}
+ */
+export async function getHTMLReport(payload, options = {}) {
+  const fs = await import("node:fs");
+  const path = await import("node:path");
+  const { buildIssueCard, buildPageGroupedSection } = await import("./reports/renderers/html.mjs");
+  const { escapeHtml } = await import("./reports/renderers/utils.mjs");
+
+  const args = { baseUrl: options.baseUrl || "", target: options.target || "WCAG 2.2 AA" };
+  const findings = normalizeForReports(payload).filter(
+    (f) => f.wcagClassification !== "AAA" && f.wcagClassification !== "Best Practice",
+  );
+
+  // Embed screenshots as base64 if screenshotsDir is provided
+  if (options.screenshotsDir) {
+    for (const finding of findings) {
+      if (finding.screenshotPath) {
+        const filename = path.basename(finding.screenshotPath);
+        const absolutePath = path.join(options.screenshotsDir, filename);
+        try {
+          if (fs.existsSync(absolutePath)) {
+            const data = fs.readFileSync(absolutePath);
+            finding.screenshotPath = `data:image/png;base64,${data.toString("base64")}`;
+          } else {
+            finding.screenshotPath = null;
+          }
+        } catch {
+          finding.screenshotPath = null;
+        }
+      }
+    }
+  }
+
+  // Dynamically import the html builder's buildHtml — it auto-executes main() on import,
+  // so we replicate its logic here using the renderers directly.
+  const {
+    buildSummary: buildSummaryLocal,
+    computeComplianceScore: computeScoreLocal,
+    scoreLabel: scoreLabelLocal,
+    buildPersonaSummary: buildPersonaSummaryLocal,
+    wcagOverallStatus: wcagOverallStatusLocal,
+  } = await import("./reports/renderers/findings.mjs");
+
+  // Use the builder's internal buildHtml by re-importing it
+  // Since html.mjs auto-runs main() on import, we cannot import it directly.
+  // Instead, we construct the HTML using the same renderers.
+  const totals = buildSummaryLocal(findings);
+  const score = computeScoreLocal(totals);
+  const label = scoreLabelLocal(score);
+  const wcagStatus = wcagOverallStatusLocal(totals);
+  const personaCounts = buildPersonaSummaryLocal(findings);
+
+  let siteHostname = args.baseUrl;
+  try {
+    siteHostname = new URL(args.baseUrl.startsWith("http") ? args.baseUrl : `https://${args.baseUrl}`).hostname;
+  } catch {}
+
+  const pageGroups = {};
+  for (const f of findings) {
+    const area = f.area || "Unknown";
+    if (!pageGroups[area]) pageGroups[area] = [];
+    pageGroups[area].push(f);
+  }
+
+  const issueCards = findings.map((f) => buildIssueCard(f)).join("\n");
+  const pageGroupedSections = Object.entries(pageGroups)
+    .map(([area, group]) => buildPageGroupedSection(area, group))
+    .join("\n");
+
+  const quickWins = findings
+    .filter((f) => (f.severity === "Critical" || f.severity === "Serious") && f.fixCode)
+    .slice(0, 3);
+
+  // Build a self-contained HTML report
+  const html = `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Accessibility Audit — ${escapeHtml(siteHostname)}</title>
+  <script src="https://cdn.tailwindcss.com"><\/script>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
+  <style>
+    body { font-family: 'Inter', sans-serif; background: #f8fafc; }
+  </style>
+</head>
+<body>
+  <main class="max-w-5xl mx-auto px-4 py-12">
+    <h1 class="text-3xl font-extrabold mb-2">Accessibility Audit Dashboard</h1>
+    <p class="text-slate-500 mb-8">${escapeHtml(siteHostname)} — ${new Date().toLocaleDateString("en-US", { year: "numeric", month: "long", day: "numeric" })}</p>
+    <div class="grid grid-cols-2 md:grid-cols-4 gap-4 mb-8">
+      <div class="bg-white rounded-xl p-4 border border-slate-200 shadow-sm">
+        <div class="text-3xl font-black">${score}</div>
+        <div class="text-xs font-bold text-slate-500 uppercase">${label}</div>
+      </div>
+      <div class="bg-white rounded-xl p-4 border border-slate-200 shadow-sm">
+        <div class="text-3xl font-black">${findings.length}</div>
+        <div class="text-xs font-bold text-slate-500 uppercase">Issues</div>
+      </div>
+      <div class="bg-white rounded-xl p-4 border border-slate-200 shadow-sm">
+        <div class="text-3xl font-black ${wcagStatus === 'Pass' ? 'text-emerald-600' : 'text-rose-600'}">${wcagStatus}</div>
+        <div class="text-xs font-bold text-slate-500 uppercase">WCAG 2.2 AA</div>
+      </div>
+      <div class="bg-white rounded-xl p-4 border border-slate-200 shadow-sm">
+        <div class="text-3xl font-black">${Object.keys(pageGroups).length}</div>
+        <div class="text-xs font-bold text-slate-500 uppercase">Pages</div>
+      </div>
+    </div>
+    <div class="space-y-4">
+      ${pageGroupedSections}
+    </div>
+  </main>
+</body>
+</html>`;
+
+  return {
+    html,
+    contentType: "text/html",
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Remediation Guide (Markdown)
+// ---------------------------------------------------------------------------
+
+/**
+ * Generates a Markdown remediation guide from raw scan findings.
+ * @param {{ findings: object[], metadata?: object, incomplete_findings?: object[] }} payload
+ * @param {{ baseUrl?: string, target?: string, patternFindings?: object }} [options={}]
+ * @returns {Promise<{ markdown: string, contentType: "text/markdown" }>}
+ */
+export async function getRemediationGuide(payload, options = {}) {
+  const { buildMarkdownSummary } = await import("./reports/renderers/md.mjs");
+
+  const args = { baseUrl: options.baseUrl || "", target: options.target || "WCAG 2.2 AA" };
+  const findings = normalizeForReports(payload);
+
+  const markdown = buildMarkdownSummary(args, findings, {
+    ...payload.metadata,
+    incomplete_findings: payload.incomplete_findings,
+    pattern_findings: options.patternFindings || null,
+  });
+
+  return {
+    markdown,
+    contentType: "text/markdown",
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Source Pattern Scanner
+// ---------------------------------------------------------------------------
+
+/**
+ * Scans a project's source code for accessibility patterns not detectable by axe-core.
+ * @param {string} projectDir - Absolute path to the project root.
+ * @param {{ framework?: string, onlyPattern?: string }} [options={}]
+ * @returns {Promise<{ findings: object[], summary: { total: number, confirmed: number, potential: number } }>}
+ */
+export async function getSourcePatterns(projectDir, options = {}) {
+  const { scanPattern, resolveScanDirs } = await import("./engine/source-scanner.mjs");
+
+  const { patterns } = loadAssetJson(ASSET_PATHS.remediation.codePatterns, "code-patterns.json");
+
+  const activePatterns = options.onlyPattern
+    ? patterns.filter((p) => p.id === options.onlyPattern)
+    : patterns;
+
+  if (activePatterns.length === 0) {
+    return { findings: [], summary: { total: 0, confirmed: 0, potential: 0 } };
+  }
+
+  const scanDirs = resolveScanDirs(options.framework || null, projectDir);
+  const allFindings = [];
+
+  for (const pattern of activePatterns) {
+    for (const scanDir of scanDirs) {
+      allFindings.push(...scanPattern(pattern, scanDir, projectDir));
+    }
+  }
+
+  const confirmed = allFindings.filter((f) => f.status === "confirmed").length;
+  const potential = allFindings.filter((f) => f.status === "potential").length;
+
+  return {
+    findings: allFindings,
+    summary: { total: allFindings.length, confirmed, potential },
+  };
+}