@govtechsg/oobee 0.10.86 → 0.10.88

package/dist/crawlers/commonCrawlerFunc.js

@@ -2,7 +2,7 @@ import { Dataset, RequestQueue, log, playwrightUtils } from 'crawlee';
 import axe from 'axe-core';
 import { axeScript, disallowedListOfPatterns, guiInfoStatusTypes, RuleFlags, saflyIconSelector, } from '../constants/constants.js';
 import { consoleLogger, guiInfoLog } from '../logs.js';
-import { takeScreenshotForHTMLElements } from '../screenshotFunc/htmlScreenshotFunc.js';
+import { enrichColorContrastDOMContext, takeScreenshotForHTMLElements } from '../screenshotFunc/htmlScreenshotFunc.js';
 import { isFilePath } from '../constants/common.js';
 import { extractAndGradeText } from './custom/extractAndGradeText.js';
 import { evaluateAltText } from './custom/evaluateAltText.js';
@@ -35,6 +35,522 @@ const truncateHtml = (html, maxBytes = 1024, suffix = '…') => {
     }
     return result;
 };
+const formatContrastFontSize = (fontSize) => {
+    if (!fontSize)
+        return 'unknown size';
+    const pxMatch = fontSize.match(/\(([\d.]+px)\)/i);
+    return pxMatch ? pxMatch[1] : fontSize;
+};
+/**
+ * Parses a CSS color string into an [R, G, B] tuple (values 0–255).
+ *
+ * axe-core serialises colours via its internal `Color.toHexString()`, which
+ * always produces lowercase 6-digit hex (#rrggbb).  The parser also accepts
+ * 3-digit hex (#rgb) and functional rgb() notation for robustness.
+ *
+ * Returns null if the string does not match any supported format.
+ */
+const parseColor = (color) => {
+    const hex6 = color.match(/^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i);
+    if (hex6)
+        return [parseInt(hex6[1], 16), parseInt(hex6[2], 16), parseInt(hex6[3], 16)];
+    const hex3 = color.match(/^#([0-9a-f])([0-9a-f])([0-9a-f])$/i);
+    if (hex3)
+        return [
+            parseInt(hex3[1] + hex3[1], 16),
+            parseInt(hex3[2] + hex3[2], 16),
+            parseInt(hex3[3] + hex3[3], 16),
+        ];
+    const rgb = color.match(/^rgb\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*\)$/i);
+    if (rgb)
+        return [parseInt(rgb[1]), parseInt(rgb[2]), parseInt(rgb[3])];
+    return null;
+};
+/**
+ * Computes the WCAG 2.x relative luminance of an sRGB colour.
+ *
+ * Algorithm (WCAG 2.1 §1.4.3 / IEC 61966-2-1 sRGB standard):
+ *   1. Normalise each 8-bit channel to [0, 1] by dividing by 255.
+ *   2. Gamma-expand (linearise) each normalised channel:
+ *        if sRGB ≤ 0.04045  →  linear = sRGB / 12.92
+ *        else               →  linear = ((sRGB + 0.055) / 1.055) ^ 2.4
+ *      The threshold 0.04045 and the slope 1/12.92 describe the near-black
+ *      linear segment of the sRGB electro-optical transfer function (EOTF).
+ *      The power 2.4 (≈ gamma 2.2) and the offset 0.055 handle the rest.
+ *   3. Weight the linear channels by the CIE 1931 XYZ D65 Y-row coefficients
+ *      projected onto the sRGB primaries:
+ *        L = 0.2126 R_lin + 0.7152 G_lin + 0.0722 B_lin
+ *      These weights reflect human eye sensitivity: the eye is most sensitive
+ *      to green, moderately to red, and least to blue.
+ *
+ * Returns a value in [0, 1]: 0 = absolute black, 1 = perfect white.
+ */
+const relativeLuminance = (r, g, b) => {
+    const linearise = (c) => {
+        const s = c / 255;
+        return s <= 0.04045 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+    };
+    return 0.2126 * linearise(r) + 0.7152 * linearise(g) + 0.0722 * linearise(b);
+};
+/**
+ * Computes the WCAG 2.x contrast ratio between two relative luminances.
+ *
+ * Formula: (L_lighter + 0.05) / (L_darker + 0.05)
+ *
+ * The additive offset 0.05 models the luminance of ambient flare (reflected
+ * light) assumed in a reference viewing environment.  It prevents the ratio
+ * from reaching infinity for pure black and anchors the scale so that
+ * white-on-black yields exactly 21:1.  The lighter luminance is always placed
+ * in the numerator so the result is always ≥ 1.
+ *
+ * WCAG thresholds:
+ *   AA  normal text  ≥ 4.5:1   |  large text ≥ 3:1
+ *   AAA normal text  ≥ 7:1     |  large text ≥ 4.5:1
+ */
+const wcagContrastRatio = (l1, l2) => {
+    const lighter = Math.max(l1, l2);
+    const darker = Math.min(l1, l2);
+    return (lighter + 0.05) / (darker + 0.05);
+};
+/**
+ * Converts an sRGB colour to HSL cylindrical coordinates.
+ *   H (hue)        ∈ [0°, 360°)
+ *   S (saturation) ∈ [0, 1]
+ *   L (lightness)  ∈ [0, 1]
+ *
+ * We work in HSL because adjusting L alone changes perceived brightness while
+ * preserving the hue and saturation of the original brand colour — the
+ * smallest perceptible change needed to satisfy the contrast requirement.
+ * Achromatic colours (R = G = B) return H = 0, S = 0.
+ */
+const rgbToHsl = (r, g, b) => {
+    const R = r / 255, G = g / 255, B = b / 255;
+    const max = Math.max(R, G, B), min = Math.min(R, G, B);
+    const l = (max + min) / 2;
+    if (max === min)
+        return [0, 0, l];
+    const d = max - min;
+    const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+    let h;
+    if (max === R)
+        h = ((G - B) / d + (G < B ? 6 : 0)) / 6;
+    else if (max === G)
+        h = ((B - R) / d + 2) / 6;
+    else
+        h = ((R - G) / d + 4) / 6;
+    return [h * 360, s, l];
+};
+/**
+ * Converts HSL back to sRGB (inverse of rgbToHsl).
+ *
+ * Uses the standard two-step piecewise-linear hue reconstruction:
+ *   q = L < 0.5 ? L(1+S) : L+S−L·S   (upper chroma boundary)
+ *   p = 2L − q                         (lower chroma boundary)
+ * Each R, G, B channel is obtained by evaluating a piecewise hue function
+ * with offsets of +1/3 (120°) and −1/3 (−120°) for R and B respectively.
+ */
+const hslToRgb = (h, s, l) => {
+    h = h / 360;
+    if (s === 0) {
+        const v = Math.round(l * 255);
+        return [v, v, v];
+    }
+    const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+    const p = 2 * l - q;
+    const hue2rgb = (p, q, t) => {
+        if (t < 0)
+            t += 1;
+        if (t > 1)
+            t -= 1;
+        if (t < 1 / 6)
+            return p + (q - p) * 6 * t;
+        if (t < 1 / 2)
+            return q;
+        if (t < 2 / 3)
+            return p + (q - p) * (2 / 3 - t) * 6;
+        return p;
+    };
+    return [
+        Math.round(hue2rgb(p, q, h + 1 / 3) * 255),
+        Math.round(hue2rgb(p, q, h) * 255),
+        Math.round(hue2rgb(p, q, h - 1 / 3) * 255),
+    ];
+};
+/** Converts an [R, G, B] tuple (0–255) to a lowercase 6-digit hex string. */
+const rgbToHex = (r, g, b) => '#' +
+    [r, g, b].map(c => c.toString(16).padStart(2, '0')).join('');
+/**
+ * Finds the lightness-adjusted version of `adjustRgb` that is as close as
+ * possible to the original colour while achieving at least `requiredRatio`
+ * contrast against `fixedRgb`.
+ *
+ * Strategy — binary search on HSL lightness L ∈ [0, 1]:
+ *   direction = 'darker':  searches L ∈ [0, original_L] for the MAXIMUM L
+ *     (least dark, closest to original) at which contrast ≥ required.
+ *   direction = 'lighter': searches L ∈ [original_L, 1] for the MINIMUM L
+ *     (least light, closest to original) at which contrast ≥ required.
+ *
+ * Hue (H) and saturation (S) are held constant so the result stays as close
+ * to the original brand/design colour as possible.
+ *
+ * 30 iterations yield a lightness precision of 1/2^30 ≈ 10⁻⁹, well below
+ * the 1/255 ≈ 0.004 resolution of 8-bit channels, so the result is
+ * effectively exact at 8-bit depth.
+ *
+ * Returns null if even the extreme value for this direction (pure black at
+ * L = 0 or pure white at L = 1 for the given H and S) cannot achieve the
+ * required ratio — an edge case that only arises for very low required ratios
+ * or highly chromatic near-neutral colours.
+ */
+const findCompliantColorByLightness = (adjustRgb, fixedRgb, requiredRatio, direction) => {
+    const fixedLum = relativeLuminance(...fixedRgb);
+    const [h, s, origHslL] = rgbToHsl(...adjustRgb);
+    // Verify the extreme value in this direction is sufficient at all.
+    const extremeHslL = direction === 'darker' ? 0 : 1;
+    const extremeRgb = hslToRgb(h, s, extremeHslL);
+    if (wcagContrastRatio(fixedLum, relativeLuminance(...extremeRgb)) < requiredRatio) {
+        return null;
+    }
+    let lo = direction === 'darker' ? 0 : origHslL;
+    let hi = direction === 'darker' ? origHslL : 1;
+    let best = extremeHslL; // guaranteed-passing extreme
+    for (let i = 0; i < 30; i++) {
+        const mid = (lo + hi) / 2;
+        const midRgb = hslToRgb(h, s, mid);
+        const passes = wcagContrastRatio(fixedLum, relativeLuminance(...midRgb)) >= requiredRatio;
+        if (passes) {
+            best = mid; // This midpoint works; try to get even closer to the original.
+            if (direction === 'darker')
+                lo = mid; // Can we raise L further (less dark)?
+            else
+                hi = mid; // Can we lower L further (less light)?
+        }
+        else {
+            if (direction === 'darker')
+                hi = mid; // Too light; go darker.
+            else
+                lo = mid; // Too dark; go lighter.
+        }
+    }
+    return hslToRgb(h, s, best);
+};
+/**
+ * Builds a human-readable recommendation for a single failing contrast pair.
+ *
+ * WCAG 1.4.3 "Contrast (Minimum)" defines two situations based on font size
+ * and weight (1 pt = 1.333 px at 96 dpi):
+ *
+ *   Situation A — normal text (< 18 pt non-bold  /  < 14 pt bold,
+ *                               i.e. < ~24 px    /  < ~18.5 px):
+ *     Required contrast ≥ 4.5:1  (G18)
+ *
+ *   Situation B — large text  (≥ 18 pt non-bold  /  ≥ 14 pt bold,
+ *                               i.e. ≥ ~24 px    /  ≥ ~18.5 px):
+ *     Required contrast ≥ 3:1    (G145)
+ *
+ * axe-core applies this rule upstream using:
+ *   ptSize      = Math.ceil(fontSize_px × 72) / 96          // px → pt
+ *   isSmallFont = (bold && ptSize < boldTextPt)              // default 14 pt
+ *              || (!bold && ptSize < largeTextPt)            // default 18 pt
+ *   bold        = fontWeight ≥ 700 || fontWeight === 'bold'  // boldValue = 700
+ * and stores the result as `expectedContrastRatio: "4.5:1"` (Situation A) or
+ * `"3:1"` (Situation B).  The `required` value used here is derived from that
+ * field via `parseFloat("4.5:1") → 4.5` or `parseFloat("3:1") → 3`, so the
+ * binary search automatically targets the correct threshold for each
+ * combination's font size and weight — no re-classification is needed here.
+ *
+ * WCAG 1.4.3 exceptions (no contrast requirement — filtered by axe-core
+ * before the data ever reaches this function):
+ *   • Pure decoration (no informational purpose, rearrangeable/substitutable)
+ *   • Inactive / disabled user-interface components
+ *   • Logotypes and brand names
+ *   • Text inside photographs or images with significant other visual content
+ *
+ * Algorithm for each failing pair:
+ *   1. Parse both colours to [R, G, B] (axe-core supplies #rrggbb hex).
+ *   2. Convert each colour to HSL.  Search for the nearest compliant
+ *      foreground by binary-searching HSL lightness L in both the 'darker'
+ *      and 'lighter' directions while keeping H and S constant (preserves
+ *      hue/saturation of the original brand colour).
+ *   3. Repeat step 2 for the background (holding the foreground fixed).
+ *   4. For each colour role, pick whichever direction (darker/lighter)
+ *      requires the smaller change in L — i.e. the least visually
+ *      disruptive compliant alternative.
+ *   5. Report both the adjusted foreground and the adjusted background
+ *      (hex + rgb) so developers can choose whichever fits their design
+ *      system.  The target ratio is included so the output is unambiguous
+ *      when a page contains a mix of normal-text (4.5:1) and large-text
+ *      (3:1) failures.
+ *
+ * Returns null if the colours cannot be parsed or no compliant alternative
+ * can be found (extremely rare; only arises when the colour is already at
+ * the luminance extreme for its hue/saturation).
+ */
+const buildContrastRecommendation = (example) => {
+    const fgRgb = parseColor(example.fgColor);
+    const bgRgb = parseColor(example.bgColor);
+    if (!fgRgb || !bgRgb)
+        return null;
+    // parseFloat handles "4.5:1" → 4.5 because it stops at the non-numeric ':'.
+    // The value is either 4.5 (Situation A, normal text) or 3 (Situation B,
+    // large text), as determined by axe-core from the element's font metrics.
+    const CONTRAST_BUFFER = 1.05;
+    const required = parseFloat(example.expectedContrastRatio) * CONTRAST_BUFFER;
+    if (isNaN(required))
+        return null;
+    // Find the nearest compliant foreground (try both directions, pick closest).
+    const fgDarker = findCompliantColorByLightness(fgRgb, bgRgb, required, 'darker');
+    const fgLighter = findCompliantColorByLightness(fgRgb, bgRgb, required, 'lighter');
+    const [, , origFgHslL] = rgbToHsl(...fgRgb);
+    let recFg = null;
+    if (fgDarker && fgLighter) {
+        const [, , dL] = rgbToHsl(...fgDarker);
+        const [, , lL] = rgbToHsl(...fgLighter);
+        recFg = Math.abs(dL - origFgHslL) <= Math.abs(lL - origFgHslL) ? fgDarker : fgLighter;
+    }
+    else {
+        recFg = fgDarker ?? fgLighter;
+    }
+    // Find the nearest compliant background (try both directions, pick closest).
+    const bgDarker = findCompliantColorByLightness(bgRgb, fgRgb, required, 'darker');
+    const bgLighter = findCompliantColorByLightness(bgRgb, fgRgb, required, 'lighter');
+    const [, , origBgHslL] = rgbToHsl(...bgRgb);
+    let recBg = null;
+    if (bgDarker && bgLighter) {
+        const [, , dL] = rgbToHsl(...bgDarker);
+        const [, , lL] = rgbToHsl(...bgLighter);
+        recBg = Math.abs(dL - origBgHslL) <= Math.abs(lL - origBgHslL) ? bgDarker : bgLighter;
+    }
+    else {
+        recBg = bgDarker ?? bgLighter;
+    }
+    if (!recFg && !recBg)
+        return null;
+    const parts = [];
+    if (recFg) {
+        const [rr, gg, bb] = recFg;
+        parts.push(`foreground text color to ${rgbToHex(rr, gg, bb)} (rgb(${rr}, ${gg}, ${bb}))`);
+    }
+    if (recBg) {
+        const [rr, gg, bb] = recBg;
+        parts.push(`background to ${rgbToHex(rr, gg, bb)} (rgb(${rr}, ${gg}, ${bb}))`);
+    }
+    // Include the target ratio in the string so the message is unambiguous when
+    // a single element has a mix of normal-text (4.5:1) and large-text (3:1)
+    // failing combinations with different required thresholds.
+    return `${parts.join(' or ')}`;
+};
+/**
+ * Builds the augmented issue description for a single axe-core color-contrast
+ * violation node.
+ *
+ * ─── WCAG rules applied ──────────────────────────────────────────────────────
+ *
+ * WCAG 1.4.3 "Contrast (Minimum)" distinguishes two situations:
+ *
+ *   Situation A — normal text (< 18 pt non-bold / < 14 pt bold,
+ *                               i.e. < ~24 px   / < ~18.5 px at 96 dpi):
+ *     Required contrast ratio ≥ 4.5:1
+ *
+ *   Situation B — large text  (≥ 18 pt non-bold / ≥ 14 pt bold,
+ *                               i.e. ≥ ~24 px   / ≥ ~18.5 px at 96 dpi):
+ *     Required contrast ratio ≥ 3:1
+ *
+ * axe-core classifies each element before this function runs:
+ *   ptSize      = Math.ceil(fontSize_px × 72) / 96          // px → pt
+ *   isSmallFont = (bold  && ptSize < 14)                     // Situation A bold
+ *              || (!bold && ptSize < 18)                     // Situation A normal
+ *   bold        = fontWeight ≥ 700 || fontWeight === 'bold'
+ * …and stores the result in check.data.expectedContrastRatio as "4.5:1" or "3:1".
+ *
+ * Exceptions (no contrast requirement — already excluded by axe-core upstream):
+ *   • Pure decoration (no informational purpose)
+ *   • Inactive / disabled UI components
+ *   • Logotypes and brand names
+ *   • Text inside photographs with significant other visual content
+ *
+ * ─── Function flow ───────────────────────────────────────────────────────────
+ *
+ *  1. Collect checks — flatten node.any, node.all, node.none into one array.
+ *     Each entry may carry a ContrastCheckData payload with fgColor, bgColor,
+ *     contrastRatio, fontSize, fontWeight, and expectedContrastRatio.
+ *
+ *  2. Deduplicate — key each combination on
+ *     [fgColor, bgColor, fontSize, fontWeight, expectedContrastRatio].
+ *     A single DOM node can generate multiple identical checks; the Map ensures
+ *     each distinct failing pair is reported once.
+ *
+ *  3. Build the base message — lists every unique failing combination with its
+ *     current contrast ratio and the required ratio, and instructs the developer
+ *     to fix all failing text in the component, not just the first element.
+ *
+ *  4. Build per-combo recommendations (via buildContrastRecommendation) —
+ *     for each failing pair, binary-search HSL lightness to find the nearest
+ *     compliant foreground (background fixed) and the nearest compliant
+ *     background (foreground fixed), both expressed as hex + rgb().  The binary
+ *     search targets the combination's own expectedContrastRatio (4.5 or 3),
+ *     so large-text recommendations are correctly held to the 3:1 threshold
+ *     and normal-text recommendations to 4.5:1.
+ *
+ *  5. Concatenate — append "Recommendation: …" after the base message so the
+ *     existing description is never modified, only extended.
+ *
+ * Returns null when no check carries usable contrast data (axe-core may omit
+ * it for pseudo-element or out-of-viewport cases).
+ */
+const buildColorContrastMessage = (node) => {
+    const checks = [...(node.any || []), ...(node.all || []), ...(node.none || [])];
+    const uniqueCombos = new Map();
+    checks.forEach(check => {
+        const data = check.data || {};
+        const hasContrastData = data.fgColor ||
+            data.bgColor ||
+            data.contrastRatio !== undefined ||
+            data.expectedContrastRatio;
+        if (!hasContrastData)
+            return;
+        const fgColor = data.fgColor || 'unknown foreground';
+        const bgColor = data.bgColor || 'unknown background';
+        const contrastRatio = String(data.contrastRatio ?? 'unknown');
+        const fontSize = formatContrastFontSize(data.fontSize);
+        const fontWeight = data.fontWeight || 'normal';
+        const expectedContrastRatio = data.expectedContrastRatio || '4.5:1';
+        const key = [fgColor, bgColor, fontSize, fontWeight, expectedContrastRatio].join('|');
+        if (!uniqueCombos.has(key)) {
+            uniqueCombos.set(key, {
+                fgColor,
+                bgColor,
+                contrastRatio,
+                fontSize,
+                fontWeight,
+                expectedContrastRatio,
+            });
+        }
+    });
+    if (!uniqueCombos.size)
+        return null;
+    const combos = [...uniqueCombos.values()];
+    const examples = combos
+        .map(example => `foreground ${example.fgColor} on ${example.bgColor} at ${example.fontSize} ${example.fontWeight === 'bold' ? 'bold' : 'regular'} text`)
+        .join(', and ');
+    const targetRatio = combos[0]?.expectedContrastRatio || '4.5:1';
+    const currentRatio = combos[0]?.contrastRatio || 'unknown';
+    const base = `Multiple text elements in this component fail WCAG 1.4.3 Color Contrast Minimum.\n  Normal text should meet or exceed ${targetRatio} contrast ratio against its actual background.\n  The current text contrast ratio of ${currentRatio} does not meet requirements. Failing combinations in this snippet include ${examples}.`;
+    const recommendations = combos
+        .map(buildContrastRecommendation)
+        .filter((r) => r !== null);
+    const recSection = recommendations.length > 0
+        ? `\n  Recommendation: Adjust ${recommendations.join('; ')}.`
+        : '';
+    const ctx = node.contrastDOMContext;
+    if (!ctx)
+        return `${base}${recSection}`;
+    const notes = [];
+    if (ctx.hasGradient) {
+        notes.push(`gradient background detected (${ctx.backgroundImage}): the sampled background color represents a single point — verify contrast at every gradient stop and position where text appears, then adjust the gradient stops or add a solid color fallback behind the text`);
+    }
+    else if (ctx.ancestorHasGradient) {
+        notes.push(`an ancestor provides a gradient background: the sampled background color may not match what is visually beneath the text — verify contrast against the actual rendered gradient`);
+    }
+    if (ctx.hasBackgroundImage) {
+        notes.push(`background image detected: contrast cannot be fully determined from a sampled color alone — ensure text remains readable across all image content and states`);
+    }
+    else if (ctx.ancestorHasBackgroundImage) {
+        notes.push(`an ancestor has a background image: the effective background under this text may differ from the sampled value`);
+    }
+    if (ctx.hasReducedOpacity) {
+        notes.push(`opacity less than 1 detected on this element or an ancestor: the rendered contrast is lower than the computed color values indicate`);
+    }
+    if (ctx.mixBlendMode) {
+        notes.push(`mix-blend-mode: ${ctx.mixBlendMode} is applied: actual rendered colors depend on the underlying layers`);
+    }
+    if (ctx.backdropFilter) {
+        notes.push(`backdrop-filter: ${ctx.backdropFilter} is applied: the effective background appearance is modified`);
+    }
+    if (ctx.filter) {
+        notes.push(`CSS filter: ${ctx.filter} is applied to this element: rendered colors may differ from computed values`);
+    }
+    const ctxSection = notes.length > 0
+        ? `\n  Rendering complexity: ${notes.join('; ')}.\n  The color fix recommendations above may not be accurate for this element — manual verification of the actual rendered contrast is strongly advised.`
+        : '';
+    return `${base}${recSection}${ctxSection}`;
+};
+// Enriches axe violation failureSummaries with additional DOM context gathered via Playwright,
+// providing LLMs with the specific details they need to apply correct fixes.
+export const enrichViolationMessages = async (results, page) => {
+    for (const violation of results.violations) {
+        if (violation.id !== 'target-size' && violation.id !== 'valid-lang')
+            continue;
+        for (const node of violation.nodes) {
+            const cssSelector = node.target.length === 1 && typeof node.target[0] === 'string' ? node.target[0] : null;
+            if (!cssSelector)
+                continue;
+            if (violation.id === 'target-size') {
+                const ctx = await page
+                    .evaluate((sel) => {
+                    try {
+                        const el = document.querySelector(sel);
+                        if (!el)
+                            return null;
+                        const rect = el.getBoundingClientRect();
+                        const computed = window.getComputedStyle(el);
+                        return {
+                            renderedWidth: Math.round(rect.width),
+                            renderedHeight: Math.round(rect.height),
+                            boxSizing: computed.boxSizing,
+                            inlineWidth: el.style.width || null,
+                            inlineHeight: el.style.height || null,
+                            tagName: el.tagName.toLowerCase(),
+                        };
+                    }
+                    catch {
+                        return null;
+                    }
+                }, cssSelector)
+                    .catch(() => null);
+                if (ctx) {
+                    const spacingMatch = node.failureSummary?.match(/diameter of (\d+)px/);
+                    const spacing = spacingMatch ? spacingMatch[1] : null;
+                    let message = `Insufficient target size: ${ctx.renderedWidth}px by ${ctx.renderedHeight}px (box-sizing: ${ctx.boxSizing}).\n  Ensure it is at least 24px by 24px.`;
+                    if (spacing) {
+                        message += `\n  Target has insufficient space to its adjacent element of ${spacing}px. Ensure it has a safe clickable space of at least 24px.`;
+                    }
+                    if (ctx.boxSizing === 'border-box' &&
+                        (ctx.inlineWidth !== null || ctx.inlineHeight !== null)) {
+                        message += `\n  Current button style code snippet does not increase the hit area.\n  Remove the explicit width/height and use min-width: 24px; min-height: 24px instead.\n  Or place the visual content in a child <span> element.`;
+                    }
+                    node.failureSummary = message;
+                }
+            }
+            else if (violation.id === 'valid-lang') {
+                const ctx = await page
+                    .evaluate((sel) => {
+                    try {
+                        const el = document.querySelector(sel);
+                        if (!el)
+                            return null;
+                        return {
+                            langValue: el.getAttribute('lang') ?? '',
+                            textSnippet: (el.textContent ?? '').trim().slice(0, 120),
+                        };
+                    }
+                    catch {
+                        return null;
+                    }
+                }, cssSelector)
+                    .catch(() => null);
+                if (ctx) {
+                    let message = `Value of lang attribute is not a valid language.\n  Use a registered IANA language code instead of "${ctx.langValue}".`;
+                    if (ctx.langValue.startsWith('x-')) {
+                        message += `\n  Axe-core valid-lang rule also rejects private-use subtags.`;
+                    }
+                    message += `\n  Identify the actual language of this text and use its registered BCP 47 code (e.g., lang="it" Italian, "es" Spanish, "fr" French, "de" German, "zh" Chinese, "ja" Japanese, "ko" Korean, "pt" Portuguese, "ar" Arabic).`;
+                    node.failureSummary = message;
+                }
+            }
+        }
+    }
+};
 export const filterAxeResults = (results, pageTitle, customFlowDetails) => {
     const { violations, passes, incomplete, url } = results;
     let totalItems = 0;
@@ -72,9 +588,12 @@ export const filterAxeResults = (results, pageTitle, customFlowDetails) => {
                     items: [],
                 };
             }
-            const message = displayNeedsReview
+            const defaultMessage = displayNeedsReview
                 ? failureSummary.slice(failureSummary.indexOf('\n') + 1).trim()
                 : failureSummary;
+            const message = rule === 'color-contrast' || rule === 'color-contrast-enhanced'
+                ? buildColorContrastMessage(node) || defaultMessage
+                : defaultMessage;
             let finalHtml = html;
             if (html.includes('</script>')) {
                 finalHtml = html.replaceAll('</script>', '&lt;/script>');
@@ -320,6 +839,8 @@ export const runAxeScript = async ({ includeScreenshots, page, randomToken, cust
         flagUnlabelledClickableElementsFunctionString: flagUnlabelledClickableElements.toString(),
         xPathToCssFunctionString: xPathToCss.toString(),
     });
+    await enrichViolationMessages(results, page);
+    await enrichColorContrastDOMContext(results.violations, page);
     if (includeScreenshots) {
         results.violations = await takeScreenshotForHTMLElements(results.violations, page, randomToken);
         results.incomplete = await takeScreenshotForHTMLElements(results.incomplete, page, randomToken);

package/dist/crawlers/crawlDomain.js

@@ -4,7 +4,7 @@ import fsp from 'fs/promises';
 import { createCrawleeSubFolders, runAxeScript, isUrlPdf, shouldSkipClickDueToDisallowedHref, shouldSkipDueToUnsupportedContent, } from './commonCrawlerFunc.js';
 import constants, { blackListedFileExtensions, guiInfoStatusTypes, cssQuerySelectors, STATUS_CODE_METADATA, disallowedListOfPatterns, disallowedSelectorPatterns, FileTypes, } from '../constants/constants.js';
 import { getPlaywrightLaunchOptions, isBlacklistedFileExtensions, isSkippedUrl, isDisallowedInRobotsTxt, getUrlsFromRobotsTxt, waitForPageLoaded, } from '../constants/common.js';
-import { areLinksEqual, isFollowStrategy, register } from '../utils.js';
+import { areLinksEqual, isFollowStrategy, normUrl, register } from '../utils.js';
 import { handlePdfDownload, runPdfScan, mapPdfScanResults, doPdfScreenshots, } from './pdfScanFunc.js';
 import { consoleLogger, guiInfoLog } from '../logs.js';
 const isBlacklisted = (url, blacklistedPatterns) => {
@@ -37,8 +37,8 @@ const crawlDomain = async ({ url, randomToken, host: _host, viewportSettings, ma
     const pdfDownloads = [];
     const uuidToPdfMapping = {};
     const queuedUrlSet = new Set();
-    const scannedUrlSet = new Set(urlsCrawled.scanned.map(item => item.url));
-    const scannedResolvedUrlSet = new Set(urlsCrawled.scanned.map(item => item.actualUrl || item.url));
+    const scannedUrlSet = new Set(urlsCrawled.scanned.map(item => normUrl(item.url)));
+    const scannedResolvedUrlSet = new Set(urlsCrawled.scanned.map(item => normUrl(item.actualUrl || item.url)));
     const isScanHtml = [FileTypes.All, FileTypes.HtmlOnly].includes(fileTypes);
     const isScanPdfs = [FileTypes.All, FileTypes.PdfOnly].includes(fileTypes);
     const { maxConcurrency } = constants;
@@ -70,11 +70,12 @@ const crawlDomain = async ({ url, randomToken, host: _host, viewportSettings, ma
         const initialPageUrl = workingPage.url().toString();
         const selectedElementsString = cssQuerySelectors.join(', ');
         const isExcluded = (newPageUrl) => {
-            const isAlreadyScanned = urlsCrawled.scanned.some(item => item.url === newPageUrl);
+            const isAlreadyScanned = scannedUrlSet.has(normUrl(newPageUrl));
             const isBlacklistedUrl = isBlacklisted(newPageUrl, blacklistedPatterns);
             const isNotFollowStrategy = !isFollowStrategy(newPageUrl, initialPageUrl, strategy);
             const isNotSupportedDocument = disallowedListOfPatterns.some(pattern => newPageUrl.toLowerCase().startsWith(pattern));
-            return isNotSupportedDocument || isAlreadyScanned || isBlacklistedUrl || isNotFollowStrategy;
+            const isRobotsDisallowed = isDisallowedInRobotsTxt(newPageUrl);
+            return isNotSupportedDocument || isAlreadyScanned || isBlacklistedUrl || isNotFollowStrategy || isRobotsDisallowed;
         };
         const setPageListeners = (pageListener) => {
             // event listener to handle new page popups upon button click
@@ -235,7 +236,7 @@ const crawlDomain = async ({ url, randomToken, host: _host, viewportSettings, ma
                     catch (e) {
                         consoleLogger.error(e);
                     }
-                    if (scannedUrlSet.has(req.url)) {
+                    if (scannedUrlSet.has(normUrl(req.url))) {
                         req.skipNavigation = true;
                     }
                     if (isDisallowedInRobotsTxt(req.url))
@@ -358,7 +359,7 @@ const crawlDomain = async ({ url, randomToken, host: _host, viewportSettings, ma
                     finalUrl = requestLabelUrl;
                 }
                 const isRedirected = !areLinksEqual(finalUrl, requestLabelUrl);
-                if (isRedirected) {
+                if (isRedirected && !isDisallowedInRobotsTxt(finalUrl)) {
                     await enqueueUniqueRequest({ url: finalUrl, label: finalUrl });
                 }
                 else {
@@ -399,7 +400,7 @@ const crawlDomain = async ({ url, randomToken, host: _host, viewportSettings, ma
                     return;
                 }
                 // if URL has already been scanned
-                if (scannedUrlSet.has(request.url)) {
+                if (scannedUrlSet.has(normUrl(request.url))) {
                     await enqueueProcess(page, enqueueLinks, browserContext);
                     return;
                 }
@@ -493,8 +494,32 @@ const crawlDomain = async ({ url, randomToken, host: _host, viewportSettings, ma
                         return;
                     }
                     const results = await runAxeScript({ includeScreenshots, page, randomToken, ruleset });
+                    // Detect JS redirects that fire during/after axe scan.
+                    // Listen for navigation, then give a brief window for pending redirects to complete.
+                    try {
+                        let navigatedToUrl = null;
+                        const onFrameNavigated = (frame) => {
+                            if (frame === page.mainFrame()) {
+                                navigatedToUrl = frame.url();
+                            }
+                        };
+                        page.on('framenavigated', onFrameNavigated);
+                        await page.waitForTimeout(1000);
+                        page.off('framenavigated', onFrameNavigated);
+                        const postScanUrl = navigatedToUrl || page.url();
+                        if (postScanUrl && postScanUrl !== 'about:blank' && !isFollowStrategy(postScanUrl, request.url, 'same-hostname')) {
+                            urlsCrawled.notScannedRedirects.push({
+                                fromUrl: request.url,
+                                toUrl: postScanUrl,
+                            });
+                            return;
+                        }
+                    }
+                    catch (_) {
+                        // Page/context was destroyed during navigation — handled by outer catch
+                    }
                     if (isRedirected) {
-                        const isLoadedUrlInCrawledUrls = scannedResolvedUrlSet.has(actualUrl);
+                        const isLoadedUrlInCrawledUrls = scannedResolvedUrlSet.has(normUrl(actualUrl));
                         if (isLoadedUrlInCrawledUrls) {
                             urlsCrawled.notScannedRedirects.push({
                                 fromUrl: request.url,
@@ -513,8 +538,8 @@ const crawlDomain = async ({ url, randomToken, host: _host, viewportSettings, ma
                                 pageTitle: results.pageTitle,
                                 actualUrl, // i.e. actualUrl
                             });
-                            scannedUrlSet.add(request.url);
-                            scannedResolvedUrlSet.add(actualUrl);
+                            scannedUrlSet.add(normUrl(request.url));
+                            scannedResolvedUrlSet.add(normUrl(actualUrl));
                             urlsCrawled.scannedRedirects.push({
                                 fromUrl: request.url,
                                 toUrl: actualUrl, // i.e. actualUrl
@@ -535,8 +560,8 @@ const crawlDomain = async ({ url, randomToken, host: _host, viewportSettings, ma
                             actualUrl: request.url,
                             pageTitle: results.pageTitle,
                         });
-                        scannedUrlSet.add(request.url);
-                        scannedResolvedUrlSet.add(request.url);
+                        scannedUrlSet.add(normUrl(request.url));
+                        scannedResolvedUrlSet.add(normUrl(request.url));
                         await dataset.pushData(results);
                     }
                 }