@a11y-oracle/visual-engine 1.0.0

package/README.md

@@ -0,0 +1,156 @@
+# @a11y-oracle/visual-engine
+
+Visual pixel analysis engine for resolving incomplete color contrast warnings from axe-core. Provides CSS halo heuristic detection, CDP-based screenshot capture, and pixel-level luminance analysis using the WCAG Safe Assessment Matrix.
+
+## Installation
+
+```bash
+npm install @a11y-oracle/visual-engine
+```
+
+> **Note:** Most users should use [`@a11y-oracle/axe-bridge`](../axe-bridge/README.md) instead, which wraps this engine and integrates directly with axe-core results. Install the visual-engine directly only if you need fine-grained control over individual analysis steps or are building a custom integration.
+
+## Usage
+
+### VisualContrastAnalyzer (Recommended)
+
+The coordinator class runs the full pipeline for a single element:
+
+```typescript
+import { VisualContrastAnalyzer } from '@a11y-oracle/visual-engine';
+import type { CDPSessionLike } from '@a11y-oracle/cdp-types';
+
+const analyzer = new VisualContrastAnalyzer(cdpSession);
+
+const result = await analyzer.analyzeElement('#hero-text', 4.5);
+
+switch (result.category) {
+  case 'pass':       // Worst-case contrast passes threshold
+  case 'violation':  // Best-case contrast fails threshold
+  case 'incomplete': // Split decision, dynamic content, or unresolvable
+}
+```
+
+### Individual Pipeline Steps
+
+Each stage of the pipeline is also exported for advanced use:
+
+```typescript
+import {
+  getElementStyles,
+  captureElementBackground,
+  analyzeHalo,
+  extractPixelLuminance,
+} from '@a11y-oracle/visual-engine';
+
+// 1. Get computed styles via CDP
+const styles = await getElementStyles(cdp, '#my-element');
+
+// 2. CSS halo fast path (no screenshot needed)
+const halo = analyzeHalo(styles, 4.5);
+if (halo.hasValidHalo) {
+  // Element has a valid text stroke or shadow halo
+}
+
+// 3. Capture background with text hidden
+const capture = await captureElementBackground(cdp, '#my-element');
+
+// 4. Pixel-level luminance analysis
+const pixels = extractPixelLuminance(capture.pngBuffer, capture.textColor);
+```
+
+## Analysis Pipeline
+
+The `VisualContrastAnalyzer.analyzeElement()` method runs this pipeline:
+
+1. **Get Computed Styles** — Fetches `color`, `backgroundColor`, `textStrokeWidth`, `textStrokeColor`, `textShadow`, and `backgroundImage` via CDP `Runtime.evaluate`.
+
+2. **Dynamic Content Check** — Detects video/canvas ancestors, sub-1 opacity, and CSS blend modes. Dynamic content is left as `incomplete`.
+
+3. **CSS Halo Heuristic** (fast path) — Checks for:
+   - `-webkit-text-stroke` >= 1px with sufficient contrast against the background
+   - `text-shadow` with 4+ zero-blur directional shadows covering all quadrants
+
+   If a valid halo is found and its color passes the threshold against the background, the element passes without a screenshot.
+
+4. **Screenshot Capture** — Hides the element's text (sets `color: transparent`), captures a clipped screenshot via CDP `Page.captureScreenshot`, then restores the text.
+
+5. **Pixel Analysis** — Decodes the PNG, scans all opaque pixels for luminance extremes (lightest and darkest), and computes contrast ratios against the text color.
+
+6. **Safe Assessment Matrix**:
+   - **Pass**: Text contrast against the *lightest* AND *darkest* background pixels both meet the threshold (worst-case passes)
+   - **Violation**: Text contrast against the *lightest* AND *darkest* background pixels both fail the threshold (best-case fails)
+   - **Incomplete**: One passes and one fails (split decision) — cannot safely categorize
+
+## API Reference
+
+### VisualContrastAnalyzer
+
+#### `constructor(cdp: CDPSessionLike)`
+
+Create an analyzer bound to a CDP session.
+
+#### `analyzeElement(selector, threshold?): Promise<ContrastAnalysisResult>`
+
+Run the full pipeline on an element.
+
+- **selector** — CSS selector targeting the element
+- **threshold** — Minimum contrast ratio (default: 4.5)
+- **Returns** — `ContrastAnalysisResult` with `category`, `textColor`, `halo`, `pixels`, and `reason`
+
+### Halo Detection
+
+#### `analyzeHalo(styles, threshold?): HaloResult`
+
+Check if computed styles contain a valid CSS halo.
+
+- **styles** — `ElementComputedStyles` from `getElementStyles()`
+- **threshold** — Minimum contrast ratio (default: 4.5)
+- **Returns** — `HaloResult` with `hasValidHalo`, `haloContrast`, `method`, and `skipReason`
+
+#### `parseTextShadow(css): TextShadowPart[]`
+
+Parse a CSS `text-shadow` value into structured parts.
+
+### Pixel Analysis
+
+#### `extractPixelLuminance(pngBuffer, textColor): PixelAnalysisResult | null`
+
+Decode a PNG and compute contrast ratios against a text color.
+
+- **pngBuffer** — Raw PNG buffer from `captureElementBackground()`
+- **textColor** — `RGBColor` of the foreground text
+- **Returns** — Luminance extremes and contrast ratios, or `null` if no opaque pixels
+
+#### `decodePng(buffer): { width, height, data: Uint8Array }`
+
+Decode a PNG buffer into raw RGBA pixel data.
+
+### Screenshot Capture
+
+#### `getElementStyles(cdp, selector): Promise<ElementComputedStyles | null>`
+
+Fetch computed styles for an element via CDP.
+
+#### `captureElementBackground(cdp, selector): Promise<{ pngBuffer: Buffer; textColor: RGBColor | null } | null>`
+
+Capture a clipped screenshot of an element with its text hidden.
+
+## Types
+
+```typescript
+import type {
+  ContrastAnalysisResult,  // Full analysis result
+  ContrastCategory,        // 'pass' | 'violation' | 'incomplete'
+  HaloResult,              // CSS halo analysis result
+  PixelAnalysisResult,     // Luminance extremes + contrast ratios
+  TextShadowPart,          // Parsed text-shadow entry
+  ElementComputedStyles,   // Computed CSS properties for contrast analysis
+} from '@a11y-oracle/visual-engine';
+```
+
+## Dependencies
+
+- **`@a11y-oracle/focus-analyzer`** — Reuses `relativeLuminance()`, `contrastRatio()`, and `parseColor()` for WCAG-compliant color math
+- **`@a11y-oracle/cdp-types`** — `CDPSessionLike` interface for framework-agnostic CDP access
+- **`fast-png`** — Pure TypeScript PNG decoder/encoder (browser + Node.js compatible, no native dependencies)

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @module @a11y-oracle/visual-engine
+ *
+ * Visual pixel analysis engine for resolving incomplete color contrast
+ * warnings. Provides CSS halo heuristic detection, CDP-based screenshot
+ * capture, and pixel-level luminance analysis using the WCAG Safe
+ * Assessment Matrix.
+ *
+ * @packageDocumentation
+ */
+export { VisualContrastAnalyzer } from './lib/visual-analyzer.js';
+export { analyzeHalo, parseTextShadow } from './lib/halo-detector.js';
+export { extractPixelLuminance, decodePng } from './lib/pixel-analysis.js';
+export { captureElementBackground, getElementStyles } from './lib/screenshot.js';
+export type { ContrastAnalysisResult, ContrastCategory, HaloResult, PixelAnalysisResult, TextShadowPart, ElementComputedStyles, } from './lib/types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,EAAE,qBAAqB,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAC3E,OAAO,EAAE,wBAAwB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACjF,YAAY,EACV,sBAAsB,EACtB,gBAAgB,EAChB,UAAU,EACV,mBAAmB,EACnB,cAAc,EACd,qBAAqB,GACtB,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * @module @a11y-oracle/visual-engine
+ *
+ * Visual pixel analysis engine for resolving incomplete color contrast
+ * warnings. Provides CSS halo heuristic detection, CDP-based screenshot
+ * capture, and pixel-level luminance analysis using the WCAG Safe
+ * Assessment Matrix.
+ *
+ * @packageDocumentation
+ */
+export { VisualContrastAnalyzer } from './lib/visual-analyzer.js';
+export { analyzeHalo, parseTextShadow } from './lib/halo-detector.js';
+export { extractPixelLuminance, decodePng } from './lib/pixel-analysis.js';
+export { captureElementBackground, getElementStyles } from './lib/screenshot.js';

package/dist/lib/halo-detector.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @module halo-detector
+ *
+ * CSS halo heuristic for WCAG color contrast. WCAG allows a text
+ * stroke or shadow to serve as the contrast boundary. This module
+ * evaluates computed CSS styles to determine if a valid halo exists
+ * before falling back to the more expensive pixel analysis pipeline.
+ */
+import type { ElementComputedStyles, HaloResult, TextShadowPart } from './types.js';
+/**
+ * Analyze an element's computed styles for a valid CSS halo.
+ *
+ * A halo is valid when:
+ * - `-webkit-text-stroke-width` >= 1px with a stroke color that passes
+ *   the contrast threshold against the background, OR
+ * - `text-shadow` has 0-blur, multi-directional coverage (4+ quadrants),
+ *   and a shadow color that passes the threshold.
+ *
+ * If the background is complex (transparent, gradient, or image),
+ * the halo check is skipped entirely.
+ *
+ * @param styles - Computed CSS styles from the element.
+ * @param threshold - Minimum contrast ratio. Default: 4.5 (WCAG AA).
+ */
+export declare function analyzeHalo(styles: ElementComputedStyles, threshold?: number): HaloResult;
+/**
+ * Parse a CSS `text-shadow` value into structured parts.
+ *
+ * Handles the standard CSS syntax where each shadow is:
+ *   `[color] <offset-x> <offset-y> [blur-radius]`
+ * or
+ *   `<offset-x> <offset-y> [blur-radius] [color]`
+ *
+ * Multiple shadows are comma-separated.
+ *
+ * @param css - The raw `text-shadow` CSS value.
+ * @returns Array of parsed shadow parts. Empty if `none` or unparseable.
+ */
+export declare function parseTextShadow(css: string): TextShadowPart[];
+//# sourceMappingURL=halo-detector.d.ts.map

package/dist/lib/halo-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"halo-detector.d.ts","sourceRoot":"","sources":["../../src/lib/halo-detector.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,qBAAqB,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAKpF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,qBAAqB,EAC7B,SAAS,GAAE,MAA0B,GACpC,UAAU,CA2BZ;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,EAAE,CAY7D"}

package/dist/lib/halo-detector.js

@@ -0,0 +1,238 @@
+/**
+ * @module halo-detector
+ *
+ * CSS halo heuristic for WCAG color contrast. WCAG allows a text
+ * stroke or shadow to serve as the contrast boundary. This module
+ * evaluates computed CSS styles to determine if a valid halo exists
+ * before falling back to the more expensive pixel analysis pipeline.
+ */
+import { parseColor, contrastRatio } from '@a11y-oracle/focus-analyzer';
+/** Default WCAG AA contrast threshold for normal text. */
+const DEFAULT_THRESHOLD = 4.5;
+/**
+ * Analyze an element's computed styles for a valid CSS halo.
+ *
+ * A halo is valid when:
+ * - `-webkit-text-stroke-width` >= 1px with a stroke color that passes
+ *   the contrast threshold against the background, OR
+ * - `text-shadow` has 0-blur, multi-directional coverage (4+ quadrants),
+ *   and a shadow color that passes the threshold.
+ *
+ * If the background is complex (transparent, gradient, or image),
+ * the halo check is skipped entirely.
+ *
+ * @param styles - Computed CSS styles from the element.
+ * @param threshold - Minimum contrast ratio. Default: 4.5 (WCAG AA).
+ */
+export function analyzeHalo(styles, threshold = DEFAULT_THRESHOLD) {
+    const noHalo = {
+        hasValidHalo: false,
+        haloContrast: null,
+        method: null,
+        skipReason: null,
+    };
+    // Check if background is complex (can't resolve halo via CSS alone)
+    if (isBackgroundComplex(styles)) {
+        return { ...noHalo, skipReason: 'complex-background' };
+    }
+    const bgColor = parseColor(styles.backgroundColor);
+    if (!bgColor) {
+        return { ...noHalo, skipReason: 'unparseable-background' };
+    }
+    // Check text-stroke first (simpler, more reliable)
+    const strokeResult = checkStroke(styles, bgColor, threshold);
+    if (strokeResult)
+        return strokeResult;
+    // Check text-shadow
+    const shadowResult = checkShadow(styles, bgColor, threshold);
+    if (shadowResult)
+        return shadowResult;
+    return noHalo;
+}
+/**
+ * Parse a CSS `text-shadow` value into structured parts.
+ *
+ * Handles the standard CSS syntax where each shadow is:
+ *   `[color] <offset-x> <offset-y> [blur-radius]`
+ * or
+ *   `<offset-x> <offset-y> [blur-radius] [color]`
+ *
+ * Multiple shadows are comma-separated.
+ *
+ * @param css - The raw `text-shadow` CSS value.
+ * @returns Array of parsed shadow parts. Empty if `none` or unparseable.
+ */
+export function parseTextShadow(css) {
+    if (!css || css.trim().toLowerCase() === 'none')
+        return [];
+    const shadows = splitShadows(css);
+    const parts = [];
+    for (const shadow of shadows) {
+        const parsed = parseSingleShadow(shadow.trim());
+        if (parsed)
+            parts.push(parsed);
+    }
+    return parts;
+}
+/**
+ * Check if the background is too complex for CSS-only halo analysis.
+ */
+function isBackgroundComplex(styles) {
+    // Background image present (gradient, url(), etc.)
+    if (styles.backgroundImage && styles.backgroundImage !== 'none') {
+        return true;
+    }
+    // Background color is transparent or semi-transparent
+    const bgColor = parseColor(styles.backgroundColor);
+    if (!bgColor || bgColor.a < 1) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Check if `-webkit-text-stroke` qualifies as a valid halo.
+ */
+function checkStroke(styles, bgColor, threshold) {
+    const width = parseFloat(styles.textStrokeWidth);
+    if (isNaN(width) || width < 1)
+        return null;
+    const strokeColor = parseColor(styles.textStrokeColor);
+    if (!strokeColor || strokeColor.a < 1)
+        return null;
+    const cr = contrastRatio(strokeColor, bgColor);
+    if (cr >= threshold) {
+        return {
+            hasValidHalo: true,
+            haloContrast: cr,
+            method: 'stroke',
+            skipReason: null,
+        };
+    }
+    return null;
+}
+/**
+ * Check if `text-shadow` qualifies as a valid halo.
+ *
+ * Requirements:
+ * 1. All shadows must have blur radius of 0.
+ * 2. Shadows must cover at least 4 directions (all quadrants).
+ * 3. All shadow colors must pass the contrast threshold.
+ */
+function checkShadow(styles, bgColor, threshold) {
+    const parts = parseTextShadow(styles.textShadow);
+    if (parts.length === 0)
+        return null;
+    // Any blur > 0 disqualifies the entire shadow as a halo
+    if (parts.some((p) => p.blur > 0))
+        return null;
+    // Must cover all 4 quadrants
+    if (!coversAllQuadrants(parts))
+        return null;
+    // All shadow colors must pass contrast
+    let minContrast = Infinity;
+    for (const part of parts) {
+        if (part.color.a < 1)
+            return null;
+        const cr = contrastRatio(part.color, bgColor);
+        minContrast = Math.min(minContrast, cr);
+    }
+    if (minContrast >= threshold) {
+        return {
+            hasValidHalo: true,
+            haloContrast: minContrast,
+            method: 'shadow',
+            skipReason: null,
+        };
+    }
+    return null;
+}
+/**
+ * Check if shadow parts cover all 4 directional quadrants
+ * (top-left, top-right, bottom-left, bottom-right).
+ */
+function coversAllQuadrants(parts) {
+    let hasTopLeft = false;
+    let hasTopRight = false;
+    let hasBottomLeft = false;
+    let hasBottomRight = false;
+    for (const p of parts) {
+        if (p.offsetX <= 0 && p.offsetY <= 0)
+            hasTopLeft = true;
+        if (p.offsetX >= 0 && p.offsetY <= 0)
+            hasTopRight = true;
+        if (p.offsetX <= 0 && p.offsetY >= 0)
+            hasBottomLeft = true;
+        if (p.offsetX >= 0 && p.offsetY >= 0)
+            hasBottomRight = true;
+    }
+    return hasTopLeft && hasTopRight && hasBottomLeft && hasBottomRight;
+}
+/**
+ * Split a CSS text-shadow value by commas, respecting parentheses.
+ * Commas inside `rgb()` / `rgba()` are not treated as separators.
+ */
+function splitShadows(css) {
+    const parts = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < css.length; i++) {
+        if (css[i] === '(')
+            depth++;
+        else if (css[i] === ')')
+            depth--;
+        else if (css[i] === ',' && depth === 0) {
+            parts.push(css.substring(start, i));
+            start = i + 1;
+        }
+    }
+    parts.push(css.substring(start));
+    return parts;
+}
+/**
+ * Parse a single text-shadow value (one of possibly many comma-separated).
+ *
+ * Format: `[color] <offset-x> <offset-y> [blur] [color]`
+ * The color can appear before or after the numeric values.
+ */
+function parseSingleShadow(raw) {
+    if (!raw)
+        return null;
+    let remaining = raw;
+    let color = null;
+    // Extract color first — it can be rgb()/rgba() or #hex
+    // Try rgb()/rgba() first
+    const rgbRegex = /rgba?\([^)]+\)/i;
+    const rgbMatch = remaining.match(rgbRegex);
+    if (rgbMatch) {
+        color = parseColor(rgbMatch[0]);
+        remaining = remaining.replace(rgbMatch[0], '');
+    }
+    else {
+        // Try hex color
+        const hexRegex = /#[0-9a-f]{3,8}/i;
+        const hexMatch = remaining.match(hexRegex);
+        if (hexMatch) {
+            color = parseColor(hexMatch[0]);
+            remaining = remaining.replace(hexMatch[0], '');
+        }
+    }
+    // Extract numeric values from the remainder (px values)
+    const numericRegex = /-?[\d.]+(?:px)?/g;
+    const numbers = [];
+    let numericMatch;
+    while ((numericMatch = numericRegex.exec(remaining)) !== null) {
+        numbers.push(parseFloat(numericMatch[0]));
+    }
+    // Need at least 2 numbers (offsetX, offsetY)
+    if (numbers.length < 2)
+        return null;
+    const offsetX = numbers[0];
+    const offsetY = numbers[1];
+    const blur = numbers.length >= 3 ? numbers[2] : 0;
+    // Default to black if no color found
+    if (!color)
+        color = parseColor('#000000');
+    if (!color)
+        return null;
+    return { offsetX, offsetY, blur, color };
+}

package/dist/lib/pixel-analysis.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @module pixel-analysis
+ *
+ * PNG decoding and pixel-level WCAG luminance analysis. Scans a
+ * background screenshot to find the lightest and darkest pixels,
+ * then calculates contrast ratios against the foreground text color.
+ */
+import type { RGBColor } from '@a11y-oracle/focus-analyzer';
+import type { PixelAnalysisResult } from './types.js';
+/**
+ * Decode a PNG buffer into raw pixel data.
+ *
+ * @param buffer - A PNG-encoded buffer (e.g. from CDP screenshot).
+ * @returns Width, height, and RGBA pixel data (4 bytes per pixel).
+ */
+export declare function decodePng(input: Uint8Array): {
+    width: number;
+    height: number;
+    data: Uint8Array;
+};
+/**
+ * Scan an RGBA pixel buffer to find the lightest and darkest pixels
+ * by relative luminance.
+ *
+ * Skips pixels with alpha < 255 (semi-transparent or fully transparent).
+ *
+ * @param data - RGBA pixel data (4 bytes per pixel).
+ * @param width - Image width in pixels.
+ * @param height - Image height in pixels.
+ * @returns The extreme luminance values and their corresponding colors,
+ *          or null if no opaque pixels were found.
+ */
+export declare function findLuminanceExtremes(data: Uint8Array, width: number, height: number): {
+    lMax: number;
+    lMin: number;
+    lMaxColor: RGBColor;
+    lMinColor: RGBColor;
+    pixelCount: number;
+} | null;
+/**
+ * Decode a PNG screenshot and analyze pixel luminance against a text color.
+ *
+ * Computes contrast ratios of the text color against the lightest and
+ * darkest background pixels found in the image.
+ *
+ * @param pngBuffer - PNG-encoded screenshot of the element background.
+ * @param textColor - The foreground text color to check contrast against.
+ * @returns Pixel analysis result, or null if no opaque pixels were found.
+ */
+export declare function extractPixelLuminance(pngBuffer: Uint8Array, textColor: RGBColor): PixelAnalysisResult | null;
+//# sourceMappingURL=pixel-analysis.d.ts.map

package/dist/lib/pixel-analysis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pixel-analysis.d.ts","sourceRoot":"","sources":["../../src/lib/pixel-analysis.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,UAAU,CAAC;CAClB,CAuCA;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb;IACD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,QAAQ,CAAC;IACpB,SAAS,EAAE,QAAQ,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,IAAI,CAqCP;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,UAAU,EACrB,SAAS,EAAE,QAAQ,GAClB,mBAAmB,GAAG,IAAI,CAc5B"}

package/dist/lib/pixel-analysis.js

@@ -0,0 +1,121 @@
+/**
+ * @module pixel-analysis
+ *
+ * PNG decoding and pixel-level WCAG luminance analysis. Scans a
+ * background screenshot to find the lightest and darkest pixels,
+ * then calculates contrast ratios against the foreground text color.
+ */
+import { decode } from 'fast-png';
+import { relativeLuminance, contrastRatio, } from '@a11y-oracle/focus-analyzer';
+/**
+ * Decode a PNG buffer into raw pixel data.
+ *
+ * @param buffer - A PNG-encoded buffer (e.g. from CDP screenshot).
+ * @returns Width, height, and RGBA pixel data (4 bytes per pixel).
+ */
+export function decodePng(input) {
+    const png = decode(input);
+    const channels = png.channels ?? 4;
+    // fast-png returns data matching the PNG's channel count.
+    // Normalize to RGBA (4 bytes per pixel) for consistent downstream processing.
+    if (channels === 4) {
+        return {
+            width: png.width,
+            height: png.height,
+            data: new Uint8Array(png.data),
+        };
+    }
+    if (channels === 3) {
+        // RGB → RGBA: inject alpha = 255 for every pixel
+        const totalPixels = png.width * png.height;
+        const rgba = new Uint8Array(totalPixels * 4);
+        for (let i = 0; i < totalPixels; i++) {
+            rgba[i * 4] = png.data[i * 3];
+            rgba[i * 4 + 1] = png.data[i * 3 + 1];
+            rgba[i * 4 + 2] = png.data[i * 3 + 2];
+            rgba[i * 4 + 3] = 255;
+        }
+        return { width: png.width, height: png.height, data: rgba };
+    }
+    // Grayscale (1) or Grayscale+Alpha (2) — expand to RGBA
+    const totalPixels = png.width * png.height;
+    const rgba = new Uint8Array(totalPixels * 4);
+    for (let i = 0; i < totalPixels; i++) {
+        const gray = png.data[i * channels];
+        const alpha = channels === 2 ? png.data[i * channels + 1] : 255;
+        rgba[i * 4] = gray;
+        rgba[i * 4 + 1] = gray;
+        rgba[i * 4 + 2] = gray;
+        rgba[i * 4 + 3] = alpha;
+    }
+    return { width: png.width, height: png.height, data: rgba };
+}
+/**
+ * Scan an RGBA pixel buffer to find the lightest and darkest pixels
+ * by relative luminance.
+ *
+ * Skips pixels with alpha < 255 (semi-transparent or fully transparent).
+ *
+ * @param data - RGBA pixel data (4 bytes per pixel).
+ * @param width - Image width in pixels.
+ * @param height - Image height in pixels.
+ * @returns The extreme luminance values and their corresponding colors,
+ *          or null if no opaque pixels were found.
+ */
+export function findLuminanceExtremes(data, width, height) {
+    let lMax = -Infinity;
+    let lMin = Infinity;
+    let lMaxColor = { r: 0, g: 0, b: 0, a: 1 };
+    let lMinColor = { r: 0, g: 0, b: 0, a: 1 };
+    let pixelCount = 0;
+    const totalPixels = width * height;
+    for (let i = 0; i < totalPixels; i++) {
+        const offset = i * 4;
+        const a = data[offset + 3];
+        // Skip non-opaque pixels
+        if (a < 255)
+            continue;
+        const r = data[offset];
+        const g = data[offset + 1];
+        const b = data[offset + 2];
+        const color = { r, g, b, a: 1 };
+        const lum = relativeLuminance(color);
+        pixelCount++;
+        if (lum > lMax) {
+            lMax = lum;
+            lMaxColor = color;
+        }
+        if (lum < lMin) {
+            lMin = lum;
+            lMinColor = color;
+        }
+    }
+    if (pixelCount === 0)
+        return null;
+    return { lMax, lMin, lMaxColor, lMinColor, pixelCount };
+}
+/**
+ * Decode a PNG screenshot and analyze pixel luminance against a text color.
+ *
+ * Computes contrast ratios of the text color against the lightest and
+ * darkest background pixels found in the image.
+ *
+ * @param pngBuffer - PNG-encoded screenshot of the element background.
+ * @param textColor - The foreground text color to check contrast against.
+ * @returns Pixel analysis result, or null if no opaque pixels were found.
+ */
+export function extractPixelLuminance(pngBuffer, textColor) {
+    const { width, height, data } = decodePng(pngBuffer);
+    const extremes = findLuminanceExtremes(data, width, height);
+    if (!extremes)
+        return null;
+    return {
+        lMax: extremes.lMax,
+        lMin: extremes.lMin,
+        lMaxColor: extremes.lMaxColor,
+        lMinColor: extremes.lMinColor,
+        crAgainstLightest: contrastRatio(textColor, extremes.lMaxColor),
+        crAgainstDarkest: contrastRatio(textColor, extremes.lMinColor),
+        pixelCount: extremes.pixelCount,
+    };
+}

package/dist/lib/screenshot.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @module screenshot
+ *
+ * CDP-based element screenshot capture with text hiding. Extracts
+ * computed styles and captures bounding-box screenshots of element
+ * backgrounds after temporarily making text invisible.
+ */
+import type { CDPSessionLike } from '@a11y-oracle/cdp-types';
+import type { RGBColor } from '@a11y-oracle/focus-analyzer';
+import type { ElementComputedStyles } from './types.js';
+/**
+ * Extract computed styles from an element for halo analysis.
+ *
+ * @param cdp - CDP session.
+ * @param selector - CSS selector targeting the element.
+ * @returns Computed styles, or null if element not found.
+ */
+export declare function getElementStyles(cdp: CDPSessionLike, selector: string): Promise<ElementComputedStyles | null>;
+/**
+ * Check if an element contains dynamic/temporal content that
+ * prevents reliable pixel analysis (video, canvas, opacity < 1, blend modes).
+ *
+ * @param cdp - CDP session.
+ * @param selector - CSS selector targeting the element.
+ * @returns true if the element has dynamic content.
+ */
+export declare function isDynamicContent(cdp: CDPSessionLike, selector: string): Promise<boolean>;
+/**
+ * Capture a bounding-box screenshot of an element's background
+ * after temporarily hiding its text content.
+ *
+ * The text is hidden via CSS injection (`color: transparent`) and
+ * restored in a `finally` block to ensure cleanup even on errors.
+ *
+ * @param cdp - CDP session.
+ * @param selector - CSS selector targeting the element.
+ * @returns PNG buffer of the background and the parsed text color,
+ *          or null if the element was not found.
+ */
+export declare function captureElementBackground(cdp: CDPSessionLike, selector: string): Promise<{
+    pngBuffer: Uint8Array;
+    textColor: RGBColor | null;
+} | null>;
+//# sourceMappingURL=screenshot.d.ts.map

package/dist/lib/screenshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"screenshot.d.ts","sourceRoot":"","sources":["../../src/lib/screenshot.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE7D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AA0GxD;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,cAAc,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAOvC;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,cAAc,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,OAAO,CAAC,CAOlB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,cAAc,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,SAAS,EAAE,UAAU,CAAC;IAAC,SAAS,EAAE,QAAQ,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,CAAC,CA4CvE"}

package/dist/lib/screenshot.js

@@ -0,0 +1,181 @@
+/**
+ * @module screenshot
+ *
+ * CDP-based element screenshot capture with text hiding. Extracts
+ * computed styles and captures bounding-box screenshots of element
+ * backgrounds after temporarily making text invisible.
+ */
+import { parseColor } from '@a11y-oracle/focus-analyzer';
+/**
+ * Decode a base64 string to Uint8Array.
+ * Cross-platform: works in both Node.js (≥16) and browsers.
+ */
+function base64ToUint8Array(base64) {
+    const binaryString = atob(base64);
+    const bytes = new Uint8Array(binaryString.length);
+    for (let i = 0; i < binaryString.length; i++) {
+        bytes[i] = binaryString.charCodeAt(i);
+    }
+    return bytes;
+}
+/**
+ * JavaScript expression to extract computed styles relevant to
+ * visual contrast analysis from a target element.
+ *
+ * @param selector - CSS selector string (will be JSON.stringify'd).
+ */
+function getStylesScript(selector) {
+    return `
+(() => {
+  const el = document.querySelector(${JSON.stringify(selector)});
+  if (!el) return null;
+  const cs = window.getComputedStyle(el);
+  return {
+    color: cs.color || '',
+    backgroundColor: cs.backgroundColor || '',
+    textStrokeWidth: cs.webkitTextStrokeWidth || cs.getPropertyValue('-webkit-text-stroke-width') || '0px',
+    textStrokeColor: cs.webkitTextStrokeColor || cs.getPropertyValue('-webkit-text-stroke-color') || '',
+    textShadow: cs.textShadow || 'none',
+    backgroundImage: cs.backgroundImage || 'none',
+  };
+})()
+`;
+}
+/**
+ * JavaScript expression to get the bounding rect and foreground color
+ * of a target element, then hide its text content.
+ *
+ * Returns the bounding rect and text color before hiding.
+ */
+function getCaptureInfoAndHideScript(selector) {
+    return `
+(() => {
+  const el = document.querySelector(${JSON.stringify(selector)});
+  if (!el) return null;
+  const cs = window.getComputedStyle(el);
+  const color = cs.color || '';
+  const rect = el.getBoundingClientRect();
+  const info = {
+    color,
+    x: rect.x,
+    y: rect.y,
+    width: rect.width,
+    height: rect.height,
+  };
+  // Hide text content to expose background
+  el.style.setProperty('color', 'transparent', 'important');
+  el.style.setProperty('text-shadow', 'none', 'important');
+  el.style.setProperty('caret-color', 'transparent', 'important');
+  return info;
+})()
+`;
+}
+/**
+ * JavaScript expression to restore text visibility on a target element.
+ */
+function restoreTextScript(selector) {
+    return `
+(() => {
+  const el = document.querySelector(${JSON.stringify(selector)});
+  if (!el) return null;
+  el.style.removeProperty('color');
+  el.style.removeProperty('text-shadow');
+  el.style.removeProperty('caret-color');
+  return true;
+})()
+`;
+}
+/**
+ * JavaScript expression to detect dynamic/temporal content that
+ * prevents reliable pixel analysis.
+ */
+function isDynamicContentScript(selector) {
+    return `
+(() => {
+  const el = document.querySelector(${JSON.stringify(selector)});
+  if (!el) return false;
+  // Check if element is or is inside a video/canvas
+  if (el.tagName === 'VIDEO' || el.tagName === 'CANVAS') return true;
+  if (el.closest('video, canvas')) return true;
+  // Check for semi-transparent element or blend modes
+  const cs = window.getComputedStyle(el);
+  if (parseFloat(cs.opacity) < 1) return true;
+  if (cs.mixBlendMode && cs.mixBlendMode !== 'normal') return true;
+  return false;
+})()
+`;
+}
+/**
+ * Extract computed styles from an element for halo analysis.
+ *
+ * @param cdp - CDP session.
+ * @param selector - CSS selector targeting the element.
+ * @returns Computed styles, or null if element not found.
+ */
+export async function getElementStyles(cdp, selector) {
+    const result = (await cdp.send('Runtime.evaluate', {
+        expression: getStylesScript(selector),
+        returnByValue: true,
+    }));
+    return result.result.value;
+}
+/**
+ * Check if an element contains dynamic/temporal content that
+ * prevents reliable pixel analysis (video, canvas, opacity < 1, blend modes).
+ *
+ * @param cdp - CDP session.
+ * @param selector - CSS selector targeting the element.
+ * @returns true if the element has dynamic content.
+ */
+export async function isDynamicContent(cdp, selector) {
+    const result = (await cdp.send('Runtime.evaluate', {
+        expression: isDynamicContentScript(selector),
+        returnByValue: true,
+    }));
+    return result.result.value;
+}
+/**
+ * Capture a bounding-box screenshot of an element's background
+ * after temporarily hiding its text content.
+ *
+ * The text is hidden via CSS injection (`color: transparent`) and
+ * restored in a `finally` block to ensure cleanup even on errors.
+ *
+ * @param cdp - CDP session.
+ * @param selector - CSS selector targeting the element.
+ * @returns PNG buffer of the background and the parsed text color,
+ *          or null if the element was not found.
+ */
+export async function captureElementBackground(cdp, selector) {
+    // Get info and hide text in one atomic operation
+    const infoResult = (await cdp.send('Runtime.evaluate', {
+        expression: getCaptureInfoAndHideScript(selector),
+        returnByValue: true,
+    }));
+    const info = infoResult.result.value;
+    if (!info || info.width <= 0 || info.height <= 0)
+        return null;
+    try {
+        // Capture screenshot of the background-only region
+        const screenshotResult = (await cdp.send('Page.captureScreenshot', {
+            format: 'png',
+            clip: {
+                x: info.x,
+                y: info.y,
+                width: info.width,
+                height: info.height,
+                scale: 1,
+            },
+        }));
+        const pngBuffer = base64ToUint8Array(screenshotResult.data);
+        const textColor = parseColor(info.color);
+        return { pngBuffer, textColor };
+    }
+    finally {
+        // Always restore text visibility
+        await cdp.send('Runtime.evaluate', {
+            expression: restoreTextScript(selector),
+            returnByValue: true,
+        });
+    }
+}

package/dist/lib/types.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @module types
+ *
+ * Type definitions for visual contrast analysis, including halo
+ * detection, pixel luminance analysis, and the Safe Assessment Matrix.
+ */
+import type { RGBColor } from '@a11y-oracle/focus-analyzer';
+/** Classification of a contrast analysis result per the Safe Assessment Matrix. */
+export type ContrastCategory = 'pass' | 'violation' | 'incomplete';
+/** Parsed representation of a single CSS `text-shadow` declaration. */
+export interface TextShadowPart {
+    /** Horizontal offset in pixels. */
+    offsetX: number;
+    /** Vertical offset in pixels. */
+    offsetY: number;
+    /** Blur radius in pixels. 0 = sharp edge (valid for halo). */
+    blur: number;
+    /** Parsed shadow color. */
+    color: RGBColor;
+}
+/** Result of CSS halo heuristic analysis. */
+export interface HaloResult {
+    /** Whether a valid halo (stroke or shadow) was detected. */
+    hasValidHalo: boolean;
+    /** Contrast ratio of the halo color against the background, or null. */
+    haloContrast: number | null;
+    /** The halo method that passed: 'stroke', 'shadow', or null. */
+    method: 'stroke' | 'shadow' | null;
+    /** Reason the halo check was skipped, if applicable. */
+    skipReason: string | null;
+}
+/** Result of pixel-level luminance analysis on a background screenshot. */
+export interface PixelAnalysisResult {
+    /** Relative luminance of the lightest pixel (0–1). */
+    lMax: number;
+    /** Relative luminance of the darkest pixel (0–1). */
+    lMin: number;
+    /** RGB color of the lightest pixel. */
+    lMaxColor: RGBColor;
+    /** RGB color of the darkest pixel. */
+    lMinColor: RGBColor;
+    /** Contrast ratio of text color against the lightest background pixel. */
+    crAgainstLightest: number;
+    /** Contrast ratio of text color against the darkest background pixel. */
+    crAgainstDarkest: number;
+    /** Total opaque pixels analyzed. */
+    pixelCount: number;
+}
+/** Computed CSS styles extracted from an element for halo analysis. */
+export interface ElementComputedStyles {
+    /** Foreground text `color`. */
+    color: string;
+    /** Computed `background-color`. */
+    backgroundColor: string;
+    /** `-webkit-text-stroke-width` value. */
+    textStrokeWidth: string;
+    /** `-webkit-text-stroke-color` value. */
+    textStrokeColor: string;
+    /** `text-shadow` value. */
+    textShadow: string;
+    /** `background-image` value (e.g. `'none'` or `'linear-gradient(...)'`). */
+    backgroundImage: string;
+}
+/** Full result of the visual contrast analysis for a single element. */
+export interface ContrastAnalysisResult {
+    /** CSS selector of the analyzed element. */
+    selector: string;
+    /** The Safe Assessment Matrix category outcome. */
+    category: ContrastCategory;
+    /** Foreground text color, or null if it could not be determined. */
+    textColor: RGBColor | null;
+    /** The halo analysis result (fast path). */
+    halo: HaloResult;
+    /** The pixel analysis result (slow path), or null if halo resolved it. */
+    pixels: PixelAnalysisResult | null;
+    /** Human-readable explanation of the decision. */
+    reason: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lib/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAE5D,mFAAmF;AACnF,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,WAAW,GAAG,YAAY,CAAC;AAEnE,uEAAuE;AACvE,MAAM,WAAW,cAAc;IAC7B,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,2BAA2B;IAC3B,KAAK,EAAE,QAAQ,CAAC;CACjB;AAED,6CAA6C;AAC7C,MAAM,WAAW,UAAU;IACzB,4DAA4D;IAC5D,YAAY,EAAE,OAAO,CAAC;IACtB,wEAAwE;IACxE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,gEAAgE;IAChE,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,IAAI,CAAC;IACnC,wDAAwD;IACxD,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,2EAA2E;AAC3E,MAAM,WAAW,mBAAmB;IAClC,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,SAAS,EAAE,QAAQ,CAAC;IACpB,sCAAsC;IACtC,SAAS,EAAE,QAAQ,CAAC;IACpB,0EAA0E;IAC1E,iBAAiB,EAAE,MAAM,CAAC;IAC1B,yEAAyE;IACzE,gBAAgB,EAAE,MAAM,CAAC;IACzB,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,uEAAuE;AACvE,MAAM,WAAW,qBAAqB;IACpC,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,eAAe,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,eAAe,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,eAAe,EAAE,MAAM,CAAC;IACxB,2BAA2B;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,wEAAwE;AACxE,MAAM,WAAW,sBAAsB;IACrC,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,oEAAoE;IACpE,SAAS,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC3B,4CAA4C;IAC5C,IAAI,EAAE,UAAU,CAAC;IACjB,0EAA0E;IAC1E,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACnC,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;CAChB"}

package/dist/lib/types.js

@@ -0,0 +1,7 @@
+/**
+ * @module types
+ *
+ * Type definitions for visual contrast analysis, including halo
+ * detection, pixel luminance analysis, and the Safe Assessment Matrix.
+ */
+export {};

package/dist/lib/visual-analyzer.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @module visual-analyzer
+ *
+ * Coordinator class that runs the full visual contrast analysis pipeline:
+ * halo heuristic → dynamic content check → pixel analysis → Safe Assessment Matrix.
+ */
+import type { CDPSessionLike } from '@a11y-oracle/cdp-types';
+import type { ContrastAnalysisResult } from './types.js';
+/**
+ * Visual contrast analyzer that coordinates the halo-then-pixel pipeline
+ * for resolving incomplete color contrast warnings.
+ *
+ * @example
+ * ```typescript
+ * const analyzer = new VisualContrastAnalyzer(cdpSession);
+ * const result = await analyzer.analyzeElement('#my-text', 4.5);
+ * if (result.category === 'pass') {
+ *   // Safe to filter out
+ * }
+ * ```
+ */
+export declare class VisualContrastAnalyzer {
+    private cdp;
+    constructor(cdp: CDPSessionLike);
+    /**
+     * Analyze a single element's color contrast using the full pipeline.
+     *
+     * Pipeline order:
+     * 1. Get computed styles
+     * 2. Check for dynamic/temporal content (video, canvas, opacity)
+     * 3. Try CSS halo heuristic (fast path)
+     * 4. Capture background screenshot with text hidden
+     * 5. Pixel-level luminance analysis
+     * 6. Apply Safe Assessment Matrix
+     *
+     * @param selector - CSS selector targeting the element.
+     * @param threshold - Minimum contrast ratio. Default: 4.5 (WCAG AA).
+     * @returns The analysis result with category, metrics, and explanation.
+     */
+    analyzeElement(selector: string, threshold?: number): Promise<ContrastAnalysisResult>;
+}
+//# sourceMappingURL=visual-analyzer.d.ts.map

package/dist/lib/visual-analyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visual-analyzer.d.ts","sourceRoot":"","sources":["../../src/lib/visual-analyzer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,KAAK,EAAE,sBAAsB,EAAc,MAAM,YAAY,CAAC;AAmBrE;;;;;;;;;;;;GAYG;AACH,qBAAa,sBAAsB;IACrB,OAAO,CAAC,GAAG;gBAAH,GAAG,EAAE,cAAc;IAEvC;;;;;;;;;;;;;;OAcG;IACG,cAAc,CAClB,QAAQ,EAAE,MAAM,EAChB,SAAS,GAAE,MAA0B,GACpC,OAAO,CAAC,sBAAsB,CAAC;CAgHnC"}

package/dist/lib/visual-analyzer.js

@@ -0,0 +1,154 @@
+/**
+ * @module visual-analyzer
+ *
+ * Coordinator class that runs the full visual contrast analysis pipeline:
+ * halo heuristic → dynamic content check → pixel analysis → Safe Assessment Matrix.
+ */
+import { analyzeHalo } from './halo-detector.js';
+import { extractPixelLuminance } from './pixel-analysis.js';
+import { getElementStyles, captureElementBackground, isDynamicContent, } from './screenshot.js';
+/** Default WCAG AA contrast threshold for normal text. */
+const DEFAULT_THRESHOLD = 4.5;
+const NO_HALO = {
+    hasValidHalo: false,
+    haloContrast: null,
+    method: null,
+    skipReason: null,
+};
+/**
+ * Visual contrast analyzer that coordinates the halo-then-pixel pipeline
+ * for resolving incomplete color contrast warnings.
+ *
+ * @example
+ * ```typescript
+ * const analyzer = new VisualContrastAnalyzer(cdpSession);
+ * const result = await analyzer.analyzeElement('#my-text', 4.5);
+ * if (result.category === 'pass') {
+ *   // Safe to filter out
+ * }
+ * ```
+ */
+export class VisualContrastAnalyzer {
+    cdp;
+    constructor(cdp) {
+        this.cdp = cdp;
+    }
+    /**
+     * Analyze a single element's color contrast using the full pipeline.
+     *
+     * Pipeline order:
+     * 1. Get computed styles
+     * 2. Check for dynamic/temporal content (video, canvas, opacity)
+     * 3. Try CSS halo heuristic (fast path)
+     * 4. Capture background screenshot with text hidden
+     * 5. Pixel-level luminance analysis
+     * 6. Apply Safe Assessment Matrix
+     *
+     * @param selector - CSS selector targeting the element.
+     * @param threshold - Minimum contrast ratio. Default: 4.5 (WCAG AA).
+     * @returns The analysis result with category, metrics, and explanation.
+     */
+    async analyzeElement(selector, threshold = DEFAULT_THRESHOLD) {
+        // Step 1: Get computed styles
+        const styles = await getElementStyles(this.cdp, selector);
+        if (!styles) {
+            return {
+                selector,
+                category: 'incomplete',
+                textColor: null,
+                halo: NO_HALO,
+                pixels: null,
+                reason: 'Element not found',
+            };
+        }
+        // Step 2: Check for dynamic/temporal content
+        const dynamic = await isDynamicContent(this.cdp, selector);
+        if (dynamic) {
+            return {
+                selector,
+                category: 'incomplete',
+                textColor: null,
+                halo: NO_HALO,
+                pixels: null,
+                reason: 'Dynamic or temporal content detected (video, canvas, opacity, or blend mode)',
+            };
+        }
+        // Step 3: Try halo heuristic (CSS-only fast path)
+        const halo = analyzeHalo(styles, threshold);
+        if (halo.hasValidHalo) {
+            return {
+                selector,
+                category: 'pass',
+                textColor: null,
+                halo,
+                pixels: null,
+                reason: `Valid CSS halo detected via ${halo.method} (contrast: ${halo.haloContrast?.toFixed(2)})`,
+            };
+        }
+        // Step 4: Capture background screenshot
+        const capture = await captureElementBackground(this.cdp, selector);
+        if (!capture) {
+            return {
+                selector,
+                category: 'incomplete',
+                textColor: null,
+                halo,
+                pixels: null,
+                reason: 'Could not capture element background',
+            };
+        }
+        if (!capture.textColor) {
+            return {
+                selector,
+                category: 'incomplete',
+                textColor: null,
+                halo,
+                pixels: null,
+                reason: 'Could not determine foreground text color',
+            };
+        }
+        // Step 5: Pixel-level luminance analysis
+        const pixels = extractPixelLuminance(capture.pngBuffer, capture.textColor);
+        if (!pixels) {
+            return {
+                selector,
+                category: 'incomplete',
+                textColor: capture.textColor,
+                halo,
+                pixels: null,
+                reason: 'No opaque pixels found in background screenshot',
+            };
+        }
+        // Step 6: Safe Assessment Matrix
+        const passesLightest = pixels.crAgainstLightest >= threshold;
+        const passesDarkest = pixels.crAgainstDarkest >= threshold;
+        if (passesLightest && passesDarkest) {
+            return {
+                selector,
+                category: 'pass',
+                textColor: capture.textColor,
+                halo,
+                pixels,
+                reason: `Passes worst-case contrast (lightest: ${pixels.crAgainstLightest.toFixed(2)}, darkest: ${pixels.crAgainstDarkest.toFixed(2)})`,
+            };
+        }
+        if (!passesLightest && !passesDarkest) {
+            return {
+                selector,
+                category: 'violation',
+                textColor: capture.textColor,
+                halo,
+                pixels,
+                reason: `Fails best-case contrast (lightest: ${pixels.crAgainstLightest.toFixed(2)}, darkest: ${pixels.crAgainstDarkest.toFixed(2)})`,
+            };
+        }
+        return {
+            selector,
+            category: 'incomplete',
+            textColor: capture.textColor,
+            halo,
+            pixels,
+            reason: `Split decision — passes one extreme but fails the other (lightest: ${pixels.crAgainstLightest.toFixed(2)}, darkest: ${pixels.crAgainstDarkest.toFixed(2)})`,
+        };
+    }
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@a11y-oracle/visual-engine",
+  "version": "1.0.0",
+  "description": "Visual pixel analysis engine for color contrast resolution using CDP screenshot capture and luminance analysis",
+  "license": "MIT",
+  "author": "a11y-oracle",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/a11y-oracle/a11y-oracle.git",
+    "directory": "libs/visual-engine"
+  },
+  "bugs": {
+    "url": "https://github.com/a11y-oracle/a11y-oracle/issues"
+  },
+  "homepage": "https://github.com/a11y-oracle/a11y-oracle/tree/main/libs/visual-engine",
+  "keywords": [
+    "accessibility",
+    "a11y",
+    "color-contrast",
+    "wcag",
+    "visual",
+    "pixel-analysis",
+    "cdp",
+    "testing"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!**/*.tsbuildinfo"
+  ],
+  "dependencies": {
+    "@a11y-oracle/cdp-types": "1.0.0",
+    "@a11y-oracle/focus-analyzer": "1.0.0",
+    "fast-png": "^8.0.0",
+    "tslib": "^2.3.0"
+  }
+}