@diegovelasquezweb/a11y-engine 0.8.3 → 0.8.5

package/README.md

@@ -1,4 +1,6 @@
-# @diegovelasquezweb/a11y-engine
+# a11y Engine
+
+[![npm](https://img.shields.io/npm/v/@diegovelasquezweb/a11y-engine)](https://www.npmjs.com/package/@diegovelasquezweb/a11y-engine)
 
 Accessibility automation engine for web applications. It orchestrates multi engine scanning, stack aware enrichment, and report generation for apps and services through a stable API.
 
@@ -12,7 +14,8 @@ Accessibility automation engine for web applications. It orchestrates multi engi
 | **Fix intelligence** | Enriches each finding with WCAG mapping, fix code snippets, framework and CMS specific notes, UI library ownership hints, effort estimates, and persona impact |
 | **AI enrichment** | Optional Claude-powered analysis that adds contextual fix suggestions based on detected stack, repo structure, and finding patterns |
 | **Report generation** | Produces HTML dashboard, PDF compliance report, manual testing checklist, and Markdown remediation guide |
-| **Source code scanning** | Static regex analysis of project source for accessibility patterns that runtime engines cannot detect — works with local paths or remote GitHub repos |
+| **Source code scanning** | Static regex analysis of project source for accessibility patterns that runtime engines cannot detect. Works with local paths or remote GitHub repos |
+| **Knowledge API** | Exposes WCAG conformance levels, severity definitions, persona profiles, glossary, scanner help, and documentation so frontends and agents can render guidance from engine-owned data |
 
 ## Installation
 
@@ -58,13 +61,13 @@ const payload = await runAudit({
   maxRoutes: 5,
   axeTags: ["wcag2a", "wcag2aa", "best-practice"],
   engines: { axe: true, cdp: true, pa11y: true },
-  repoUrl: "https://github.com/owner/repo", // optional — enables source pattern scan and stack detection from package.json
-  githubToken: process.env.GH_TOKEN,        // optional — for private repos and higher GitHub API rate limits
+  repoUrl: "https://github.com/owner/repo", // optional, enables source pattern scan and stack detection
+  githubToken: process.env.GH_TOKEN,        // optional, required for private repos
   ai: {
     enabled: true,
     apiKey: process.env.ANTHROPIC_API_KEY,
     githubToken: process.env.GH_TOKEN,
-    systemPrompt: "Custom prompt...",        // optional — overrides default Claude system prompt
+    systemPrompt: "Custom prompt...",        // optional, overrides default Claude system prompt
   },
   onProgress: (step, status, extra) => console.log(`${step}: ${status}`, extra),
 });
@@ -135,25 +138,7 @@ See [API Reference](docs/api-reference.md) for exact options and return types.
 
 ## CLI
 
-The package exposes an `a11y-audit` binary for terminal execution.
-
-```bash
-# Basic scan
-pnpm exec a11y-audit --base-url https://example.com
-
-# With source code pattern scanning via GitHub API (no clone)
-pnpm exec a11y-audit --base-url https://example.com \
-  --repo-url https://github.com/owner/repo \
-  --github-token ghp_...
-
-# With AI enrichment (set ANTHROPIC_API_KEY env var)
-ANTHROPIC_API_KEY=sk-ant-... pnpm exec a11y-audit --base-url https://example.com
-
-# With custom AI system prompt
-AI_SYSTEM_PROMPT="You are..." ANTHROPIC_API_KEY=sk-ant-... pnpm exec a11y-audit --base-url https://example.com
-```
-
-See the [CLI Handbook](docs/cli-handbook.md) for all flags and examples.
+The package exposes an `a11y-audit` binary for terminal execution. See the [CLI Handbook](docs/cli-handbook.md) for all flags, env vars, and examples.
 
 ## AI enrichment
 
@@ -163,7 +148,7 @@ When `ANTHROPIC_API_KEY` is set, the engine runs a post-scan enrichment step tha
 - A production-quality code snippet in the correct framework syntax
 - Context-aware suggestions when repo source files are available
 
-AI output is stored in separate fields (`ai_fix_description`, `ai_fix_code`) — the original engine fixes are always preserved. Findings improved by AI are flagged with `aiEnhanced: true`.
+AI output is stored in separate fields (`ai_fix_description`, `ai_fix_code`). The original engine fixes are always preserved. Findings improved by AI are flagged with `aiEnhanced: true`.
 
 The system prompt is fully customizable via `options.ai.systemPrompt` (programmatic API) or the `AI_SYSTEM_PROMPT` env var (CLI).
 

package/docs/api-reference.md

@@ -4,174 +4,444 @@
 
 ---
 
-## Core API
+## Table of Contents
+
+- [Installation](#installation)
+- [Import](#import)
+- [End-to-end example](#end-to-end-example)
+- [Core API](#core-api)
+  - [runAudit](#runauditoptions)
+  - [getFindings](#getfindingsinput-options)
+  - [getOverview](#getoverviewfindings-payload)
+- [Output API](#output-api)
+  - [getPDFReport](#getpdfreportpayload-options)
+  - [getHTMLReport](#gethtmlreportpayload-options)
+  - [getChecklist](#getchecklistoptions)
+  - [getRemediationGuide](#getremediationguidepayload-options)
+  - [getSourcePatterns](#getsourcepatternsprojdir-options)
+- [Knowledge API](#knowledge-api)
+  - [getKnowledge](#getknowledgeoptions)
+  - [getScannerHelp](#getscannerhelpoptions)
+  - [getPersonaReference](#getpersonareferenceoptions)
+  - [getUiHelp](#getuihelpoptions)
+  - [getConformanceLevels](#getconformancelevelsoptions)
+  - [getWcagPrinciples](#getwcagprinciplesoptions)
+  - [getSeverityLevels](#getseveritylevelsoptions)
 
-### `runAudit(options)`
+---
 
-Runs route discovery, runtime scan, merge, analyzer enrichment, and optional AI enrichment. Supports local project paths or remote GitHub repos for stack detection and source pattern scanning.
+## Installation
+
+```bash
+npm install @diegovelasquezweb/a11y-engine
+npx playwright install chromium
+npx puppeteer browsers install chrome
+```
+
+## Import
+
+All functions are named exports from the package root:
+
+```ts
+import {
+  runAudit,
+  getFindings,
+  getOverview,
+  getPDFReport,
+  getHTMLReport,
+  getChecklist,
+  getRemediationGuide,
+  getSourcePatterns,
+  getKnowledge,
+  getScannerHelp,
+  getPersonaReference,
+  getUiHelp,
+  getConformanceLevels,
+  getWcagPrinciples,
+  getSeverityLevels,
+} from "@diegovelasquezweb/a11y-engine";
+```
 
-`options` (`RunAuditOptions`):
+---
 
-| Option | Type |
-| :--- | :--- |
-| `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` |
-| `repoUrl` | `string` |
-| `githubToken` | `string` |
-| `skipPatterns` | `boolean` |
-| `screenshotsDir` | `string` |
-| `engines` | `{ axe?: boolean; cdp?: boolean; pa11y?: boolean }` |
-| `ai` | `{ enabled?: boolean; apiKey?: string; githubToken?: string; model?: string; systemPrompt?: string }` — `systemPrompt` overrides the default Claude prompt when set |
-| `onProgress` | `(step: string, status: string, extra?: Record<string, unknown>) => void` |
-
-Progress steps emitted via `onProgress`:
-
-| Step | When |
+## End-to-end example
+
+```ts
+import { runAudit, getFindings, getOverview } from "@diegovelasquezweb/a11y-engine";
+
+// 1. Run the scan
+const payload = await runAudit({
+  baseUrl: "https://example.com",
+  maxRoutes: 5,
+  engines: { axe: true, cdp: true, pa11y: true },
+  onProgress: (step, status) => console.log(`[${step}] ${status}`),
+});
+
+// 2. Get enriched findings
+const findings = getFindings(payload);
+
+// 3. Get compliance summary
+const { score, scoreLabel, wcagStatus, totals, quickWins } = getOverview(findings, payload);
+
+console.log(`Score: ${score}/100 (${scoreLabel})`);
+console.log(`WCAG Status: ${wcagStatus}`);
+console.log(`Critical: ${totals.Critical}, Serious: ${totals.Serious}`);
+```
+
+---
+
+## Core API
+
+### `runAudit(options)`
+
+Runs the full audit pipeline: route discovery → axe/CDP/pa11y scan → merge/dedup → analyzer enrichment → optional source pattern scanning → optional AI enrichment.
+
+Returns a `ScanPayload` object consumed by all other functions.
+
+**Options:**
+
+| Option | Type | Default | Range / Values | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `baseUrl` | `string` | — | Required | Starting URL including protocol (`https://` or `http://`) |
+| `maxRoutes` | `number` | `10` | 1 – 50 | Maximum unique pages to discover and scan |
+| `crawlDepth` | `number` | `2` | 1 – 3 | BFS link-follow depth from `baseUrl`. Has no effect when `routes` is set |
+| `routes` | `string` | — | CSV paths | Explicit paths to scan (e.g. `"/,/about,/contact"`). Overrides auto-discovery entirely |
+| `waitUntil` | `string` | `"domcontentloaded"` | `"domcontentloaded"` \| `"load"` \| `"networkidle"` | Page load strategy. Use `"networkidle"` for SPAs that render after `DOMContentLoaded` |
+| `waitMs` | `number` | `2000` | 0 – 10000 | Fixed delay (ms) after page load before engines run |
+| `timeoutMs` | `number` | `30000` | 5000 – 120000 | Network timeout per page (ms) |
+| `headless` | `boolean` | `true` | — | Set `false` to open a visible browser for debugging |
+| `viewport` | `object` | `{ width: 1280, height: 800 }` | width: 320–2560, height: 320–2560 | Browser viewport dimensions in pixels |
+| `colorScheme` | `string` | `"light"` | `"light"` \| `"dark"` | Emulates `prefers-color-scheme` media query |
+| `engines` | `object` | all `true` | `{ axe?, cdp?, pa11y? }` | Which engines to run. At least one must be enabled |
+| `axeTags` | `string[]` | WCAG 2.x A+AA | See below | axe-core rule tag filter. Also determines pa11y standard |
+| `onlyRule` | `string` | — | axe rule ID | Run a single axe rule only (e.g. `"color-contrast"`) |
+| `ignoreFindings` | `string[]` | — | axe rule IDs | Suppress specific rules from output entirely |
+| `excludeSelectors` | `string[]` | — | CSS selectors | Skip elements matching these selectors during axe scan |
+| `framework` | `string` | auto-detected | See below | Override framework detection for fix notes and source boundaries |
+| `projectDir` | `string` | — | local path | Local project source directory. Enables source pattern scanning and package.json stack detection |
+| `repoUrl` | `string` | — | GitHub URL | Remote repo URL. Enables source pattern scanning via GitHub API — no clone required |
+| `githubToken` | `string` | — | GitHub PAT | Increases GitHub API rate limit from 60 to 5,000 req/hr. Required for private repos |
+| `skipPatterns` | `boolean` | `false` | — | Disable source pattern scanning even when `projectDir` or `repoUrl` is set |
+| `screenshotsDir` | `string` | `.audit/screenshots` | dir path | Directory where element screenshots are saved |
+| `ai.enabled` | `boolean` | `false` | — | Enable Claude AI enrichment for Critical and Serious findings |
+| `ai.apiKey` | `string` | — | Anthropic API key | Required when `ai.enabled` is `true` |
+| `ai.githubToken` | `string` | — | GitHub PAT | Used to fetch source files from the repo for AI context |
+| `ai.model` | `string` | `"claude-haiku-4-5-20251001"` | Anthropic model ID | Claude model to use |
+| `ai.systemPrompt` | `string` | Built-in prompt | — | Overrides the default Claude system prompt for the entire scan |
+| `onProgress` | `function` | — | — | Callback fired at each pipeline step |
+
+**`axeTags` common values:**
+
+| Tag | Covers |
 | :--- | :--- |
-| `page` | Always — page load |
-| `axe` | Always — axe-core scan |
-| `cdp` | Always — CDP accessibility tree check |
-| `pa11y` | Always — pa11y HTML CodeSniffer scan |
-| `merge` | Always — finding deduplication |
-| `intelligence` | Always — enrichment and WCAG mapping |
-| `repo` | When `repoUrl` is set |
-| `patterns` | When source scanning is active |
-| `ai` | When AI enrichment is configured |
+| `wcag2a` | WCAG 2.0 Level A |
+| `wcag2aa` | WCAG 2.0 Level AA |
+| `wcag21a` | WCAG 2.1 Level A additions |
+| `wcag21aa` | WCAG 2.1 Level AA additions |
+| `wcag22a` | WCAG 2.2 Level A additions |
+| `wcag22aa` | WCAG 2.2 Level AA additions |
+| `wcag2aaa` | WCAG 2.0 Level AAA |
+| `best-practice` | Non-WCAG best practices |
+
+**Supported `framework` values:** `nextjs`, `gatsby`, `react`, `nuxt`, `vue`, `angular`, `astro`, `svelte`, `remix`, `shopify`, `wordpress`, `drupal`
+
+**`onProgress` callback:**
+
+```ts
+onProgress: (step, status, extra) => {
+  // step:   "page" | "axe" | "cdp" | "pa11y" | "merge" | "intelligence" | "repo" | "patterns" | "ai"
+  // status: "running" | "done" | "error" | "skipped"
+  // extra:  { found?: number, merged?: number, ... } — step-specific data
+}
+```
+
+```ts
+const payload = await runAudit({
+  baseUrl: "https://example.com",
+  maxRoutes: 5,
+  engines: { axe: true, cdp: true, pa11y: true },
+  repoUrl: "https://github.com/owner/repo",
+  githubToken: process.env.GH_TOKEN,
+  ai: { enabled: true, apiKey: process.env.ANTHROPIC_API_KEY },
+  onProgress: (step, status) => console.log(`[${step}] ${status}`),
+});
+```
 
 Returns: `Promise<ScanPayload>`
 
-> **`ai_enriched_findings` fast path**: When AI enrichment runs, the engine appends `ai_enriched_findings` to the payload. `getFindings()` checks for this field first — if present, it returns the already-enriched findings directly without re-normalizing the raw `findings` array.
+> **`ai_enriched_findings` fast path**: When AI enrichment runs, `getFindings()` uses `payload.ai_enriched_findings` directly instead of re-normalizing the raw findings array.
 
-### `getFindings(input, options?)`
+---
 
-Normalizes and enriches findings and returns sorted enriched findings.
+### `getFindings(input, options?)`
 
-- `input`: `ScanPayload` from `runAudit`
-- `options` (`EnrichmentOptions`):
-  - `screenshotUrlBuilder?: (rawPath: string) => string`
+Normalizes raw scan results into enriched, UI-ready findings sorted by severity.
+
+```ts
+import { getFindings } from "@diegovelasquezweb/a11y-engine";
+
+const findings = getFindings(payload, {
+  // Optional: rewrite internal screenshot paths to app URLs
+  screenshotUrlBuilder: (rawPath) =>
+    `/api/scan/${scanId}/screenshot?path=${encodeURIComponent(rawPath)}`,
+});
+
+// findings[0] example:
+// {
+//   id: "A11Y-001",
+//   ruleId: "color-contrast",
+//   title: "Elements must meet minimum color contrast ratio thresholds",
+//   severity: "Serious",
+//   wcag: "1.4.3",
+//   selector: ".hero-text",
+//   actual: "Element has insufficient color contrast of 2.5:1 ...",
+//   expected: "Text contrast ratio must be at least 4.5:1 ...",
+//   fixDescription: "Increase the foreground color contrast ...",
+//   fixCode: "/* Change #aaa to #767676 */",
+//   effort: "low",
+//   aiEnhanced: true,            // present when AI ran
+//   aiFixDescription: "...",     // Claude-generated (more specific)
+//   aiFixCode: "...",            // Claude-generated code snippet
+// }
+```
 
 Returns: `EnrichedFinding[]`
 
-### `getOverview(findings, payload?)`
+---
 
-Computes totals, score, WCAG status, persona groups, quick wins, target URL, and detected stack.
+### `getOverview(findings, payload?)`
 
-- `findings`: `EnrichedFinding[]`
-- `payload`: `ScanPayload | null`
+Computes the compliance score, WCAG status, severity totals, persona groups, and quick wins from enriched findings.
+
+```ts
+import { getFindings, getOverview } from "@diegovelasquezweb/a11y-engine";
+
+const findings = getFindings(payload);
+const overview = getOverview(findings, payload);
+
+// overview example:
+// {
+//   score: 72,              // 0–100. Formula: 100 - (Critical×15) - (Serious×5) - (Moderate×2) - (Minor×0.5)
+//   label: "Fair",          // "Excellent" (90–100) | "Good" (75–89) | "Fair" (55–74) | "Poor" (35–54) | "Critical" (0–34)
+//   wcagStatus: "Fail",     // "Pass" | "Conditional Pass" | "Fail"
+//   totals: { Critical: 1, Serious: 3, Moderate: 5, Minor: 2 },
+//   personaGroups: {
+//     screenReader: { count: 4, findings: [...] },
+//     keyboard:     { count: 2, findings: [...] },
+//     vision:       { count: 3, findings: [...] },
+//     cognitive:    { count: 1, findings: [...] },
+//   },
+//   quickWins: [...],       // top Critical/Serious findings with fix code ready
+//   targetUrl: "https://example.com",
+//   detectedStack: { framework: "nextjs", cms: null, uiLibraries: ["radix-ui"] },
+// }
+```
 
 Returns: `AuditSummary`
 
+---
+
 ## Output API
 
 ### `getPDFReport(payload, options?)`
 
-- `payload`: `ScanPayload`
-- `options`: `ReportOptions`
-  - `baseUrl?: string`
-  - `target?: string`
+Generates a formal A4 PDF compliance report.
+
+```ts
+import { getPDFReport } from "@diegovelasquezweb/a11y-engine";
+
+const { buffer, contentType } = await getPDFReport(payload, {
+  baseUrl: "https://example.com",
+  target: "WCAG 2.2 AA",
+});
 
-Returns: `Promise<PDFReport>` (`{ buffer, contentType }`)
+// In a Next.js API route:
+return new Response(buffer, { headers: { "Content-Type": contentType } });
+```
+
+Returns: `Promise<{ buffer: Buffer, contentType: string }>`
+
+---
 
 ### `getHTMLReport(payload, options?)`
 
-- `payload`: `ScanPayload`
-- `options`: `HTMLReportOptions`
-  - `baseUrl?: string`
-  - `target?: string`
-  - `screenshotsDir?: string`
+Generates an interactive HTML audit dashboard with finding cards, score gauge, and persona breakdown.
+
+```ts
+import { getHTMLReport } from "@diegovelasquezweb/a11y-engine";
 
-Returns: `Promise<HTMLReport>` (`{ html, contentType }`)
+const { html, contentType } = await getHTMLReport(payload, {
+  baseUrl: "https://example.com",
+  screenshotsDir: "/path/to/screenshots",
+});
+```
+
+Returns: `Promise<{ html: string, contentType: string }>`
+
+---
 
 ### `getChecklist(options?)`
 
-- `options`: `Pick<ReportOptions, "baseUrl">`
-  - `baseUrl?: string`
+Generates an interactive HTML manual testing checklist with 41 WCAG checks.
+
+```ts
+import { getChecklist } from "@diegovelasquezweb/a11y-engine";
 
-Returns: `Promise<ChecklistReport>` (`{ html, contentType }`)
+const { html, contentType } = await getChecklist({
+  baseUrl: "https://example.com",
+});
+```
+
+Returns: `Promise<{ html: string, contentType: string }>`
+
+---
 
 ### `getRemediationGuide(payload, options?)`
 
-- `payload`: `ScanPayload & { incomplete_findings?: unknown[] }`
-- `options`: `RemediationOptions`
-  - `baseUrl?: string`
-  - `target?: string`
-  - `patternFindings?: Record<string, unknown> | null`
+Generates a Markdown remediation guide optimized for AI agents and developers. Includes finding details, fix code, verify commands, and source pattern findings.
+
+```ts
+import { getRemediationGuide } from "@diegovelasquezweb/a11y-engine";
+
+const { markdown, contentType } = await getRemediationGuide(payload, {
+  baseUrl: "https://example.com",
+  patternFindings: payload.patternFindings ?? null,
+});
 
-Returns: `Promise<RemediationGuide>` (`{ markdown, contentType }`)
+// Write to disk or return as download
+```
+
+Returns: `Promise<{ markdown: string, contentType: string }>`
+
+---
 
 ### `getSourcePatterns(projectDir, options?)`
 
-- `projectDir`: `string`
-- `options`: `SourcePatternOptions`
-  - `framework?: string`
-  - `onlyPattern?: string`
+Scans a local project directory for source code accessibility patterns that runtime engines cannot detect.
+
+```ts
+import { getSourcePatterns } from "@diegovelasquezweb/a11y-engine";
+
+const result = await getSourcePatterns("./", {
+  framework: "nextjs",   // optional — scopes scan to framework source dirs
+  onlyPattern: "placeholder-only-label", // optional — run a single pattern
+});
+
+// result example:
+// {
+//   findings: [
+//     {
+//       id: "PAT-a1b2c3",
+//       pattern_id: "placeholder-only-label",
+//       title: "Input uses placeholder as its only label",
+//       severity: "Critical",
+//       status: "confirmed",
+//       file: "src/components/SearchBar.tsx",
+//       line: 12,
+//       match: '  <input placeholder="Search..." />',
+//       context: "...",
+//       fix_description: "Add an aria-label or visible <label> element",
+//     }
+//   ],
+//   summary: { total: 3, confirmed: 2, potential: 1 }
+// }
+```
 
 Returns: `Promise<SourcePatternResult>`
 
+---
+
 ## Knowledge API
 
+These functions expose engine-owned content for UIs and agents to render. All accept an optional `{ locale?: string }` option (default: `"en"`).
+
+### `getKnowledge(options?)`
+
+Returns the full knowledge pack — combines all knowledge functions into one call. Useful for pre-loading UI help content.
+
+```ts
+import { getKnowledge } from "@diegovelasquezweb/a11y-engine";
+
+const knowledge = getKnowledge({ locale: "en" });
+
+// knowledge.scanner         → scan options help and engine descriptions
+// knowledge.personas        → persona labels, icons, descriptions
+// knowledge.concepts        → UI concept definitions
+// knowledge.glossary        → accessibility glossary
+// knowledge.conformanceLevels → WCAG A/AA/AAA definitions with axe tags
+// knowledge.wcagPrinciples  → the 4 WCAG principles
+// knowledge.severityLevels  → Critical/Serious/Moderate/Minor definitions
+```
+
+Returns: `EngineKnowledge`
+
+---
+
 ### `getScannerHelp(options?)`
 
-- `options`: `KnowledgeOptions`
-  - `locale?: string`
+Returns scan option descriptions, allowed values, and engine metadata — used to render Advanced Settings UI.
 
-Returns: `ScannerHelp` (`{ locale, version, title, engines, options }`)
+```ts
+const help = getScannerHelp();
+// help.engines → [{ id: "axe", label: "axe-core", description: "..." }, ...]
+// help.options → [{ id: "maxRoutes", label: "Max Routes", type: "number", ... }, ...]
+```
+
+---
 
 ### `getPersonaReference(options?)`
 
-- `options`: `KnowledgeOptions`
-  - `locale?: string`
+Returns persona labels, descriptions, and disability group definitions.
 
-Returns: `PersonaReference` (`{ locale, version, personas }`)
+```ts
+const ref = getPersonaReference();
+// ref.personas → [{ id: "screenReader", label: "Screen Readers", icon: "...", description: "..." }, ...]
+```
+
+---
 
 ### `getUiHelp(options?)`
 
-- `options`: `KnowledgeOptions`
-  - `locale?: string`
+Returns shared concept definitions and a glossary of accessibility terms.
 
-Returns: `UiHelp` (`{ locale, version, concepts, glossary }`)
+```ts
+const ui = getUiHelp();
+// ui.concepts  → { wcag: "...", aria: "...", ... }
+// ui.glossary  → [{ term: "ARIA", definition: "..." }, ...]
+```
 
-### `getConformanceLevels(options?)`
+---
 
-- `options`: `KnowledgeOptions`
-  - `locale?: string`
+### `getConformanceLevels(options?)`
 
-Returns: `ConformanceLevelsResult` (`{ locale, version, conformanceLevels }`)
+Returns WCAG conformance level definitions with their corresponding axe-core tag sets.
 
-### `getWcagPrinciples(options?)`
+```ts
+const { conformanceLevels } = getConformanceLevels();
+// conformanceLevels[0] → { id: "AA", label: "WCAG 2.2 AA", axeTags: ["wcag2a", "wcag2aa", ...] }
+```
 
-- `options`: `KnowledgeOptions`
-  - `locale?: string`
+---
 
-Returns: `WcagPrinciplesResult` (`{ locale, version, wcagPrinciples }`)
+### `getWcagPrinciples(options?)`
 
-### `getSeverityLevels(options?)`
+Returns the four WCAG principles (Perceivable, Operable, Understandable, Robust) with criterion prefix patterns.
 
-- `options`: `KnowledgeOptions`
-  - `locale?: string`
+```ts
+const { wcagPrinciples } = getWcagPrinciples();
+// wcagPrinciples[0] → { id: "perceivable", label: "Perceivable", prefix: "1.", description: "..." }
+```
 
-Returns: `SeverityLevelsResult` (`{ locale, version, severityLevels }`)
+---
 
-### `getKnowledge(options?)`
+### `getSeverityLevels(options?)`
 
-- `options`: `KnowledgeOptions`
-  - `locale?: string`
+Returns severity level definitions with labels, descriptions, and ordering.
 
-Returns: `EngineKnowledge` (`{ locale, version, scanner, personas, concepts, glossary, docs, conformanceLevels, wcagPrinciples, severityLevels }`)
+```ts
+const { severityLevels } = getSeverityLevels();
+// severityLevels[0] → { id: "Critical", label: "Critical", order: 0, description: "..." }
+```
 
 ---
 

package/docs/engine-manifest.md

@@ -4,6 +4,14 @@
 
 ---
 
+## Table of Contents
+
+- [Source Modules](#1-source-modules)
+- [Asset Modules](#2-asset-modules)
+- [Test Suite](#3-test-suite)
+
+---
+
 This document is the current technical inventory of the engine package.
 
 ## 1) Source Modules

package/package.json

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

package/src/ai/claude.mjs

@@ -25,18 +25,10 @@ const MAX_AI_FINDINGS = 20; // cap to control cost
  * @param {object} context
  * @returns {string}
  */
-function buildSystemPrompt(context) {
-  const { framework, cms, uiLibraries } = context.stack || {};
-
-  let stackInfo = "";
-  if (framework) stackInfo += `Framework: ${framework}\n`;
-  if (cms) stackInfo += `CMS: ${cms}\n`;
-  if (uiLibraries?.length) stackInfo += `UI Libraries: ${uiLibraries.join(", ")}\n`;
-
-  return `You are an expert web accessibility engineer specializing in WCAG 2.2 AA remediation.
+export const DEFAULT_AI_SYSTEM_PROMPT = `You are an expert web accessibility engineer specializing in WCAG 2.2 AA remediation.
 
 Your task is to provide a developer-friendly AI hint for each accessibility finding — something MORE USEFUL than the generic automated fix already provided.
-${stackInfo ? `\nProject context:\n${stackInfo}` : ""}
+
 For each finding, provide:
 1. fixDescription: A 2-3 sentence explanation that goes BEYOND the generic fix. Explain WHY this matters for real users, WHAT specifically to look for in the codebase, and HOW to verify the fix works. Be specific to the selector and actual violation data provided.
 2. fixCode: A ready-to-use, production-quality code snippet in the correct syntax for the stack. Do NOT copy the existing fix code — write a BETTER, more complete example that a developer can use directly.
@@ -48,6 +40,20 @@ Rules:
 - Reference the actual selector or element from the finding when possible
 - If the violation data contains specific values (colors, ratios, labels), use them in your response
 - Respond in JSON only — no markdown, no explanation outside the JSON structure`;
+
+function buildSystemPrompt(context) {
+  const { framework, cms, uiLibraries } = context.stack || {};
+
+  let stackInfo = "";
+  if (framework) stackInfo += `Framework: ${framework}\n`;
+  if (cms) stackInfo += `CMS: ${cms}\n`;
+  if (uiLibraries?.length) stackInfo += `UI Libraries: ${uiLibraries.join(", ")}\n`;
+
+  const base = DEFAULT_AI_SYSTEM_PROMPT;
+  return stackInfo ? base.replace(
+    "For each finding, provide:",
+    `Project context:\n${stackInfo}\nFor each finding, provide:`
+  ) : base;
 }
 
 /**
@@ -230,7 +236,7 @@ async function fetchSourceFilesForFindings(findings, repoUrl, githubToken) {
       try {
         const content = await fetchRepoFile(repoUrl, filePath, githubToken);
         if (content) sourceFiles[filePath] = content;
-      } catch { /* non-fatal */ }
+      } catch { }
     }
   }
 

package/src/ai/enrich.mjs

@@ -74,6 +74,6 @@ async function main() {
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
   main().catch((err) => {
     log.warn(`AI enrichment failed (non-fatal): ${err.message}`);
-    process.exit(0); // non-fatal — never block the pipeline
+    process.exit(0);
   });
 }

package/src/index.d.mts

@@ -403,15 +403,6 @@ export interface RunAuditOptions {
   onProgress?: (step: string, status: string, extra?: Record<string, unknown>) => void;
 }
 
-export interface AiOptions {
-  enabled?: boolean;
-  apiKey?: string;
-  githubToken?: string;
-  model?: string;
-}
-
-
-
 
 
 export interface EnrichmentOptions {
@@ -471,3 +462,21 @@ export function getWcagPrinciples(options?: KnowledgeOptions): WcagPrinciplesRes
 export function getSeverityLevels(options?: KnowledgeOptions): SeverityLevelsResult;
 
 export function getKnowledge(options?: KnowledgeOptions): EngineKnowledge;
+
+export const DEFAULT_AI_SYSTEM_PROMPT: string;
+
+export interface ViewportPreset {
+  label: string;
+  width: number;
+  height: number;
+}
+
+export const VIEWPORT_PRESETS: ViewportPreset[];
+
+export interface AiOptions {
+  enabled?: boolean;
+  apiKey?: string;
+  githubToken?: string;
+  model?: string;
+  systemPrompt?: string;
+}

package/src/index.mjs

@@ -5,10 +5,9 @@
  */
 
 import { ASSET_PATHS, loadAssetJson } from "./core/asset-loader.mjs";
+export { DEFAULT_AI_SYSTEM_PROMPT } from "./ai/claude.mjs";
 
-// ---------------------------------------------------------------------------
 // Lazy-loaded asset cache
-// ---------------------------------------------------------------------------
 
 let _intelligence = null;
 let _pa11yConfig = null;
@@ -58,9 +57,7 @@ function resolveKnowledgeLocale(locale = "en") {
   return "en";
 }
 
-// ---------------------------------------------------------------------------
 // Pa11y rule canonicalization (internal)
-// ---------------------------------------------------------------------------
 
 function normalizePa11yToken(value) {
   return value
@@ -97,9 +94,7 @@ function mapPa11yRuleToCanonical(ruleId, sourceRuleId = null, checkData = null)
   return ruleId;
 }
 
-// ---------------------------------------------------------------------------
 // Raw finding normalization (internal)
-// ---------------------------------------------------------------------------
 
 const SEVERITY_ORDER = { Critical: 1, Serious: 2, Moderate: 3, Minor: 4 };
 
@@ -169,9 +164,7 @@ function normalizeSingleFinding(item, index, screenshotUrlBuilder) {
   };
 }
 
-// ---------------------------------------------------------------------------
 // Finding enrichment
-// ---------------------------------------------------------------------------
 
 /**
  * Normalizes and enriches raw findings with intelligence data.
@@ -188,19 +181,16 @@ export function getFindings(input, options = {}) {
   const { screenshotUrlBuilder = null } = options;
   const rules = getIntelligence().rules || {};
 
-  // If AI enrichment ran, return those findings directly (already normalized + enriched)
   if (input?.ai_enriched_findings?.length > 0 && !screenshotUrlBuilder) {
     return input.ai_enriched_findings;
   }
 
   const rawFindings = input?.findings || [];
 
-  // Normalize raw findings
   const normalized = rawFindings.map((item, index) =>
     normalizeSingleFinding(item, index, screenshotUrlBuilder)
   );
 
-  // Enrich with intelligence and output camelCase-only findings
   const enriched = normalized.map((finding) => {
     const canonical = mapPa11yRuleToCanonical(
       finding.rule_id,
@@ -208,7 +198,6 @@ export function getFindings(input, options = {}) {
       finding.check_data,
     );
 
-    // Build camelCase-only enriched finding
     const enrichedFinding = {
       id: finding.id,
       ruleId: canonical,
@@ -238,7 +227,7 @@ export function getFindings(input, options = {}) {
       recommendedFix: finding.recommended_fix,
       evidence: finding.evidence,
       totalInstances: finding.total_instances,
-      effort: finding.effort,
+      effort: finding.effort ?? (finding.fix_code ? "low" : "high"),
       relatedRules: finding.related_rules,
       screenshotPath: finding.screenshot_path,
       falsePositiveRisk: finding.false_positive_risk,
@@ -280,7 +269,6 @@ export function getFindings(input, options = {}) {
     return enrichedFinding;
   });
 
-  // Sort by severity then by ID
   enriched.sort((a, b) => {
     const sa = SEVERITY_ORDER[a.severity] ?? 99;
     const sb = SEVERITY_ORDER[b.severity] ?? 99;
@@ -291,9 +279,7 @@ export function getFindings(input, options = {}) {
   return enriched;
 }
 
-// ---------------------------------------------------------------------------
 // Score computation (internal)
-// ---------------------------------------------------------------------------
 
 function getComplianceScore(totals) {
   const config = getComplianceConfig();
@@ -324,9 +310,7 @@ function getComplianceScore(totals) {
   return { score, label, wcagStatus };
 }
 
-// ---------------------------------------------------------------------------
 // Persona grouping (internal)
-// ---------------------------------------------------------------------------
 
 function getPersonaGroups(findings) {
   const ref = getWcagReference();
@@ -383,9 +367,7 @@ function getPersonaGroups(findings) {
   return groups;
 }
 
-// ---------------------------------------------------------------------------
 // Audit summary
-// ---------------------------------------------------------------------------
 
 /**
  * Computes a complete audit summary from enriched findings: severity totals,
@@ -443,9 +425,7 @@ export function getOverview(findings, payload = null) {
   };
 }
 
-// ---------------------------------------------------------------------------
 // Knowledge APIs
-// ---------------------------------------------------------------------------
 
 /**
  * Returns scanner-facing help metadata including engine descriptions,
@@ -583,6 +563,13 @@ export function getSeverityLevels(options = {}) {
   };
 }
 
+export const VIEWPORT_PRESETS = [
+  { label: "Desktop", width: 1280, height: 800 },
+  { label: "Laptop",  width: 1440, height: 900 },
+  { label: "Tablet",  width: 768,  height: 1024 },
+  { label: "Mobile",  width: 375,  height: 812 },
+];
+
 export function getKnowledge(options = {}) {
   const scanner = getScannerHelp(options);
   const personas = getPersonaReference(options);
@@ -611,9 +598,7 @@ export function getKnowledge(options = {}) {
   };
 }
 
-// ---------------------------------------------------------------------------
 // Full audit pipeline
-// ---------------------------------------------------------------------------
 
 /**
  * Runs a complete accessibility audit: crawl + scan (axe + CDP + pa11y) + analyze.
@@ -818,9 +803,7 @@ export async function runAudit(options) {
   return findingsPayload;
 }
 
-// ---------------------------------------------------------------------------
 // Report generation
-// ---------------------------------------------------------------------------
 
 import {
   normalizeFindings as normalizeForReports,
@@ -1003,9 +986,7 @@ export async function getChecklist(options = {}) {
   };
 }
 
-// ---------------------------------------------------------------------------
 // HTML Report
-// ---------------------------------------------------------------------------
 
 /**
  * Generates an interactive HTML audit dashboard from raw scan findings.
@@ -1135,9 +1116,7 @@ export async function getHTMLReport(payload, options = {}) {
   };
 }
 
-// ---------------------------------------------------------------------------
 // Remediation Guide (Markdown)
-// ---------------------------------------------------------------------------
 
 /**
  * Generates a Markdown remediation guide from raw scan findings.
@@ -1163,9 +1142,7 @@ export async function getRemediationGuide(payload, options = {}) {
   };
 }
 
-// ---------------------------------------------------------------------------
 // Source Pattern Scanner
-// ---------------------------------------------------------------------------
 
 /**
  * Scans a project's source code for accessibility patterns not detectable by axe-core.

package/src/pipeline/dom-scanner.mjs

@@ -935,17 +935,12 @@ function mergeViolations(axeViolations, cdpViolations, pa11yViolations) {
     }
   }
 
-  // Step 3: pa11y findings — check via canonical rule ID (axe-equivalent) + selector
+  // Step 3: pa11y findings — only skip if same rule + same target already exists
   for (const v of pa11yViolations) {
     const target = v.nodes?.[0]?.target?.[0] || "";
     const key = `${v.id}::${target}`;
 
-    // If pa11y was mapped to an axe rule ID, check if that rule already covers this target
-    const isAxeEquivDuplicate = v.id && seenRuleTargets.has(v.id) && target && seenRuleTargets.get(v.id).has(target);
-    // Also check if any existing finding covers this exact target (broader dedup)
-    const selectorCovered = target && [...seen].some((k) => k.endsWith(`::${target}`));
-
-    if (!seen.has(key) && !isAxeEquivDuplicate && (!selectorCovered || !target)) {
+    if (!seen.has(key)) {
       seen.add(key);
       if (!seenRuleTargets.has(v.id)) seenRuleTargets.set(v.id, new Set());
       seenRuleTargets.get(v.id).add(target);