@govtechsg/oobee 0.10.86 → 0.10.88

package/src/crawlers/custom/utils.ts

@@ -40,6 +40,7 @@ const RESTRICT_OVERLAY_TO_ENTRY_DOMAIN = parseBoolEnv(
   process.env.RESTRICT_OVERLAY_TO_ENTRY_DOMAIN,
   false,
 );
+const OVERLAY_OPERATION_TIMEOUT_MS = 5000;
 
 const isOverlayAllowed = (currentUrl: string, entryUrl: string) => {
   try {
@@ -306,7 +307,7 @@ export const addOverlayMenu = async (
     collapsed: false,
   },
 ) => {
-  await page.waitForLoadState('domcontentloaded');
+  await page.waitForLoadState('domcontentloaded', { timeout: OVERLAY_OPERATION_TIMEOUT_MS });
   consoleLogger.info(`Overlay menu: adding to ${menuPos}...`);
 
   // Add the overlay menu with initial styling
@@ -1143,6 +1144,7 @@ export const addOverlayMenu = async (
     })
     .catch(error => {
       consoleLogger.error('Overlay menu: failed to add', error);
+      throw error;
     });
 };
 
@@ -1165,6 +1167,8 @@ export const removeOverlayMenu = async page => {
 
 export const initNewPage = async (page, pageClosePromises, processPageParams, pagesDict) => {
   let menuPos = MENU_POSITION.right;
+  let overlayRefreshSeq = 0;
+  let overlayRefreshChain = Promise.resolve();
 
   // eslint-disable-next-line no-underscore-dangle
   const pageId = page._guid;
@@ -1194,6 +1198,83 @@ export const initNewPage = async (page, pageClosePromises, processPageParams, pa
     };
   }
 
+  const reconcileOverlayMenu = async (trigger: string) => {
+    // Mark this as the latest refresh so older ones can stop.
+    const refreshSeq = ++overlayRefreshSeq;
+
+    // Serialize overlay updates so multiple navigation events do not add/remove concurrently.
+    overlayRefreshChain = overlayRefreshChain
+      .catch(() => {})
+      .then(async () => {
+        if (refreshSeq !== overlayRefreshSeq || page.isClosed()) return;
+
+        try {
+          // `framenavigated` can fire before the new document is ready for DOM inspection/injection.
+          await page.waitForLoadState('domcontentloaded', { timeout: 5000 });
+        } catch {
+          // Best effort only. The page may still be mid-navigation.
+        }
+
+        try {
+          // Give fast redirect chains a brief chance to advance before we inject/remove the overlay.
+          await page.waitForTimeout(300);
+        } catch {
+          // Best effort only. The page may already be closing.
+        }
+
+        // Re-check staleness after waiting because a newer navigation may have happened meanwhile.
+        if (refreshSeq !== overlayRefreshSeq || page.isClosed()) return;
+
+        const allowed = isOverlayAllowed(page.url(), processPageParams.entryUrl);
+
+        if (!allowed) {
+          await Promise.race([
+            removeOverlayMenu(page),
+            new Promise((_, reject) => {
+              setTimeout(() => {
+                reject(
+                  new Error(
+                    `removeOverlayMenu timed out after ${OVERLAY_OPERATION_TIMEOUT_MS}ms`,
+                  ),
+                );
+              }, OVERLAY_OPERATION_TIMEOUT_MS);
+            }),
+          ]);
+          return;
+        }
+
+        const hasOverlay = await page.evaluate(() =>
+          Boolean(document.querySelector('#oobeeShadowHost')),
+        );
+
+        consoleLogger.info(`Overlay state (${trigger}): ${hasOverlay}`);
+
+        if (!hasOverlay) {
+          // Recreate the overlay after allowed redirects while preserving current UI state.
+          consoleLogger.info(`Adding overlay menu to page (${trigger}): ${page.url()}`);
+          await Promise.race([
+            addOverlayMenu(page, processPageParams.urlsCrawled, menuPos, {
+              inProgress: !!pagesDict[pageId]?.isScanning,
+              collapsed: !!pagesDict[pageId]?.collapsed,
+              hideStopInput: !!processPageParams.customFlowLabel,
+            }),
+            new Promise((_, reject) => {
+              setTimeout(() => {
+                reject(
+                  new Error(`addOverlayMenu timed out after ${OVERLAY_OPERATION_TIMEOUT_MS}ms`),
+                );
+              }, OVERLAY_OPERATION_TIMEOUT_MS);
+            }),
+          ]);
+        }
+      })
+      .catch(() => {
+        consoleLogger.info('Error in adding overlay menu to page');
+      });
+
+    await overlayRefreshChain;
+  };
+
   type handleOnScanClickFunction = () => void;
 
   // Window functions exposed in browser
@@ -1208,17 +1289,7 @@ export const initNewPage = async (page, pageClosePromises, processPageParams, pa
       pagesDict[pageId].isScanning = false;
 
       if (page.isClosed()) return;
-      const allowed = isOverlayAllowed(page.url(), processPageParams.entryUrl);
-
-      if (allowed) {
-        await addOverlayMenu(page, processPageParams.urlsCrawled, menuPos, {
-          inProgress: false,
-          collapsed: !!pagesDict[pageId]?.collapsed,
-          hideStopInput: !!processPageParams.customFlowLabel,
-        });
-      } else {
-        await removeOverlayMenu(page);
-      }
+      await reconcileOverlayMenu('scan-click');
     } catch (error) {
       log(`Scan failed ${error}`);
     }
@@ -1282,42 +1353,25 @@ export const initNewPage = async (page, pageClosePromises, processPageParams, pa
 
   page.on('domcontentloaded', async () => {
     if (page.isClosed()) return;
-    try {
-      const allowed = isOverlayAllowed(page.url(), processPageParams.entryUrl);
-
-      if (!allowed) {
-        await removeOverlayMenu(page);
-        return;
-      }
-
-      const existingOverlay = await page.evaluate(() => {
-        return document.querySelector('#oobeeShadowHost');
-      });
-
-      consoleLogger.info(`Overlay state: ${existingOverlay}`);
-
-      if (!existingOverlay) {
-        consoleLogger.info(`Adding overlay menu to page: ${page.url()}`);
-        await addOverlayMenu(page, processPageParams.urlsCrawled, menuPos, {
-          inProgress: !!pagesDict[pageId]?.isScanning,
-          collapsed: !!pagesDict[pageId]?.collapsed,
-          hideStopInput: !!processPageParams.customFlowLabel,
-        });
-      }
+    await reconcileOverlayMenu('domcontentloaded');
 
-      if (isCypressTest) {
-        try {
-          await handleOnScanClick();
-          page.close();
-        } catch {
-          consoleLogger.info(`Error in calling handleOnScanClick, isCypressTest: ${isCypressTest}`);
-        }
+    if (isCypressTest) {
+      try {
+        await handleOnScanClick();
+        page.close();
+      } catch {
+        consoleLogger.info(
+          `Error in calling handleOnScanClick, isCypressTest: ${isCypressTest}`,
+        );
       }
-    } catch {
-      consoleLogger.info('Error in adding overlay menu to page');
     }
   });
 
+  page.on('framenavigated', async (frame: any) => {
+    if (frame !== page.mainFrame() || page.isClosed()) return;
+    await reconcileOverlayMenu('framenavigated');
+  });
+
   try {
     if (page.isClosed()) return page;
     await page.exposeFunction('handleOnScanClick', handleOnScanClick);
@@ -1337,5 +1391,7 @@ export const initNewPage = async (page, pageClosePromises, processPageParams, pa
     log(`Error exposing functions on page: ${e}`);
   }
 
+  await reconcileOverlayMenu('init');
+
   return page;
 };

package/src/generateHtmlReport.ts

@@ -22,6 +22,7 @@ import constants, {
   a11yRuleShortDescriptionMap,
   disabilityBadgesMap,
   a11yRuleLongDescriptionMap,
+  a11yRuleStepByStepGuide,
 } from './constants/constants.js';
 
 import { consoleLogger } from './logs.js';
@@ -65,7 +66,12 @@ const ensureCategory = (
     if (typeof rule.totalItems !== 'number') {
       rule.totalItems = rule.pagesAffected.reduce(
         (accumulate: number, page: any) =>
-          accumulate + (Array.isArray(page.items) ? page.items.length : 0),
+          accumulate +
+          (Array.isArray(page.items)
+            ? page.items.length
+            : typeof page.itemsCount === 'number'
+              ? page.itemsCount
+              : 0),
         0,
       );
     }
@@ -87,7 +93,10 @@ const ensureCategory = (
   };
 };
 
-export const generateHtmlReport = async (resultDir: string): Promise<string> => {
+export const generateHtmlReport = async (
+  resultDir: string,
+  htmlFilename = 'report',
+): Promise<string> => {
   try {
     const storagePath = path.resolve(resultDir);
     const scanDataJsonPath = path.join(storagePath, 'scanData.json');
@@ -117,24 +126,22 @@ export const generateHtmlReport = async (resultDir: string): Promise<string> =>
     const scanData = JSON.parse(await fs.readFile(scanDataJsonPath, 'utf8'));
     const scanItemsAll = JSON.parse(await fs.readFile(scanItemsJsonPath, 'utf8'));
 
-    // Use convertItemsToReferences to normalize items structure to match scanItemsWithHtmlGroupRefs format
-    const scanItemsWithHtmlGroupRefs = convertItemsToReferences({
+    // Build the lighter scanItems payload used by the HTML report.
+    const lightScanItemsPayload = convertItemsToReferences({
       items: scanItemsAll,
-      ...scanData
     });
 
     const {
       mustFix = {},
       goodToFix = {},
       needsReview = {},
-      passed = {},
-    } = scanItemsWithHtmlGroupRefs;
+    } = lightScanItemsPayload;
 
     const items = {
       mustFix: ensureCategory(mustFix, 'mustFix'),
       goodToFix: ensureCategory(goodToFix, 'goodToFix'),
       needsReview: ensureCategory(needsReview, 'needsReview'),
-      passed: ensureCategory(passed, 'passed'),
+      passed: ensureCategory(scanItemsAll.passed || {}, 'passed'),
     };
 
     const pagesScanned = Array.isArray(scanData.pagesScanned) ? scanData.pagesScanned : [];
@@ -183,6 +190,8 @@ export const generateHtmlReport = async (resultDir: string): Promise<string> =>
       a11yRuleShortDescriptionMap,
       disabilityBadgesMap,
       a11yRuleLongDescriptionMap,
+      a11yRuleStepByStepGuide,
+      wcagCriteriaLabels: constants.wcagCriteriaLabels,
       advancedScanOptionsSummaryItems: {
         showIncludeScreenshots: !!scanData.advancedScanOptionsSummaryItems?.showIncludeScreenshots,
         showAllowSubdomains: !!scanData.advancedScanOptionsSummaryItems?.showAllowSubdomains,
@@ -217,10 +226,11 @@ export const generateHtmlReport = async (resultDir: string): Promise<string> =>
       (allIssues as any).advancedScanOptionsSummaryItems?.disableOobee,
     );
 
-    await writeHTML(allIssues, storagePath, 'report', scanDataB64Path, scanItemsB64Path);
+    await writeHTML(allIssues, storagePath, htmlFilename, scanDataB64Path, scanItemsB64Path);
 
-    consoleLogger.info(`Report generated at: ${path.join(storagePath, 'report.html')}`);
-    return path.join(storagePath, 'report.html');
+    const outputPath = path.join(storagePath, `${htmlFilename}.html`);
+    consoleLogger.info(`Report generated at: ${outputPath}`);
+    return outputPath;
   } catch (err: any) {
     consoleLogger.error(`generateHtmlReport failed: ${err?.message || err}`);
     throw err;

package/src/mergeAxeResults/itemReferences.ts

@@ -1,5 +1,9 @@
 import type { AllIssues, ItemsInfo, RuleInfo } from './types.js';
 
+type ScanItems = AllIssues['items'];
+type ScanCategory = ScanItems[keyof ScanItems];
+type ScanItemsLight = Pick<ScanItems, 'mustFix' | 'goodToFix' | 'needsReview' | 'passed'>;
+
 /**
  * Builds pre-computed HTML groups to optimize Group by HTML Element functionality.
  * Keys are composite "html\x00xpath" strings to ensure unique matching per element instance.
@@ -31,32 +35,72 @@ export const buildHtmlGroups = (rule: RuleInfo, items: ItemsInfo[], pageUrl: str
   });
 };
 
+/*
+// Commenting this out for now as we are not including htmlGroups in the embedded report payload to keep it lean.
+// We can revisit this if we want to include htmlGroups in the future and need a reference builder for it.
+const toHtmlGroupReference = (item: any) => {
+  if (typeof item === 'string') {
+    return item;
+  }
+
+  return `${item?.html || 'No HTML element'}\x00${item?.xpath || ''}`;
+};
+
+const cloneCategoryWithReferenceItems = (category: ScanCategory): ScanCategory =>
+  ({
+    ...category,
+    rules: category.rules.map(
+      rule =>
+        ({
+          ...rule,
+          pagesAffected: rule.pagesAffected.map(
+            page => {
+              const { items, ...pageWithoutItems } = page;
+
+              return {
+                ...pageWithoutItems,
+                itemsCount: page.itemsCount ?? (Array.isArray(items) ? items.length : 0),
+                items: Array.isArray(items) ? items.map(toHtmlGroupReference) : items,
+              } as any;
+            },
+          ),
+        }) as any,
+    ),
+  }) as ScanCategory;
+*/
+
+const cloneCategoryLight = (category: ScanCategory, includeHtmlGroups: boolean): ScanCategory =>
+  ({
+    ...category,
+    rules: category.rules.map(
+      rule =>
+        ({
+          rule: rule.rule,
+          description: rule.description,
+          helpUrl: rule.helpUrl,
+          conformance: rule.conformance,
+          totalItems: rule.totalItems,
+          axeImpact: rule.axeImpact,
+          ...(includeHtmlGroups && rule.htmlGroups ? { htmlGroups: rule.htmlGroups } : {}),
+          pagesAffected: rule.pagesAffected.map(page => ({
+            url: page.url,
+            pageTitle: page.pageTitle,
+            itemsCount: page.itemsCount ?? (Array.isArray((page as any).items) ? (page as any).items.length : 0),
+          })),
+        }) as any,
+    ),
+  }) as ScanCategory;
+
 /**
- * Converts items in pagesAffected to references (html\x00xpath composite keys) for embedding in HTML report.
- * Additionally, it deep-clones allIssues, replaces page.items objects with composite reference keys.
- * Those refs are specifically for htmlGroups lookup (html + xpath).
+ * Builds the embedded HTML-report payload from the full scan items.
+ * Includes htmlGroups for non-passed categories (Group by HTML Element),
+ * excludes them from passed to keep payload within browser memory limits.
  */
-export const convertItemsToReferences = (allIssues: AllIssues): AllIssues => {
-  const cloned = JSON.parse(JSON.stringify(allIssues));
-
-  ['mustFix', 'goodToFix', 'needsReview', 'passed'].forEach(category => {
-    if (!cloned.items[category]?.rules) return;
-
-    cloned.items[category].rules.forEach((rule: any) => {
-      if (!rule.pagesAffected || !rule.htmlGroups) return;
-
-      rule.pagesAffected.forEach((page: any) => {
-        if (!page.items) return;
-
-        page.items = page.items.map((item: any) => {
-          if (typeof item === 'string') return item; // Already a reference
-          // Use composite key matching buildHtmlGroups
-          const htmlKey = `${item.html || 'No HTML element'}\x00${item.xpath || ''}`;
-          return htmlKey;
-        });
-      });
-    });
-  });
-
-  return cloned;
+export const convertItemsToReferences = (source: Pick<AllIssues, 'items'>): ScanItemsLight => {
+  return {
+    mustFix: cloneCategoryLight(source.items.mustFix, true),
+    goodToFix: cloneCategoryLight(source.items.goodToFix, true),
+    needsReview: cloneCategoryLight(source.items.needsReview, true),
+    passed: cloneCategoryLight(source.items.passed, false),
+  };
 };

package/src/mergeAxeResults/sentryTelemetry.ts

@@ -140,7 +140,10 @@ const sendWcagBreakdownToSentry = async (
         event_type: 'accessibility_scan',
         scanType: scanInfo.scanType,
         browser: scanInfo.browser,
-        entryUrl: scanInfo.entryUrl,
+        entryUrl: process.env.OOBEE_SCAN_METADATA ?? scanInfo.entryUrl,
+        ...(process.env.OOBEE_SCAN_PRODUCT && {
+          scanProduct: process.env.OOBEE_SCAN_PRODUCT,
+        }),
       },
       user: {
         ...(scanInfo.email && scanInfo.name

package/src/mergeAxeResults.ts

@@ -185,15 +185,15 @@ const writeHTML = async (
     'utf-8',
   );
 
-  // Create lighter version with item references for embedding in HTML
-  const scanItemsWithHtmlGroupRefs = convertItemsToReferences(allIssues);
+  // Create the lighter scanItems payload for embedding in the HTML report.
+  const lightScanItemsPayload = convertItemsToReferences(allIssues);
 
   // Write the lighter items to a file and get the base64 path
   const {
-    jsonFilePath: scanItemsWithHtmlGroupRefsJsonFilePath,
-    base64FilePath: scanItemsWithHtmlGroupRefsBase64FilePath,
+    jsonFilePath: lightScanItemsPayloadJsonFilePath,
+    base64FilePath: lightScanItemsPayloadBase64FilePath,
   } = await writeJsonFileAndCompressedJsonFile(
-    scanItemsWithHtmlGroupRefs.items,
+    lightScanItemsPayload,
     storagePath,
     'scanItems-light',
   );
@@ -212,8 +212,8 @@ const writeHTML = async (
         await Promise.all([
           fs.promises.unlink(topFilePath),
           fs.promises.unlink(bottomFilePath),
-          fs.promises.unlink(scanItemsWithHtmlGroupRefsBase64FilePath),
-          fs.promises.unlink(scanItemsWithHtmlGroupRefsJsonFilePath),
+          fs.promises.unlink(lightScanItemsPayloadBase64FilePath),
+          fs.promises.unlink(lightScanItemsPayloadJsonFilePath),
         ]);
       } catch (err) {
         console.error('Error cleaning up temporary files:', err);
@@ -251,6 +251,9 @@ const writeHTML = async (
   } else {
     console.warn('Skipping fetch GenAI feature as it is local report');
   }
+
+  var scanData = null;
+  var scanItems = null;
   \n`);
 
     outputStream.write('</script>\n<script type="text/plain" id="scanDataRaw">');
@@ -259,22 +262,25 @@ const writeHTML = async (
     scanDetailsReadStream.on('end', async () => {
       outputStream.write('</script>\n<script>\n');
       outputStream.write(
-        "var scanDataPromise = (async () => { console.log('Loading scanData...'); scanData = await decodeUnzipParse(document.getElementById('scanDataRaw').textContent); })();\n",
+        "var scanDataPromise = (async () => { console.log('Loading scanData...'); scanData = await decodeUnzipParse(document.getElementById('scanDataRaw').textContent); console.log('[report] scanData loaded'); })();\n",
       );
       outputStream.write('</script>\n');
 
       // Write scanItems in 2MB chunks using a stream to avoid loading entire file into memory
       try {
         let chunkIndex = 1;
-        const scanItemsStream = fs.createReadStream(scanItemsWithHtmlGroupRefsBase64FilePath, {
+        const scanItemsStream = fs.createReadStream(lightScanItemsPayloadBase64FilePath, {
           encoding: 'utf8',
           highWaterMark: CHUNK_SIZE,
         });
 
         for await (const chunk of scanItemsStream) {
-          outputStream.write(
+          const ok = outputStream.write(
             `<script type="text/plain" id="scanItemsRaw${chunkIndex}">${chunk}</script>\n`,
           );
+          if (!ok) {
+            await new Promise<void>(resolve => outputStream.once('drain', resolve));
+          }
           chunkIndex++;
         }
 
@@ -291,6 +297,7 @@ var scanItemsPromise = (async () => {
     i++;
   }
   scanItems = await decodeUnzipParse(chunks);
+  console.log('[report] scanItems loaded');
 })();\n`);
         outputStream.write(suffixData);
         outputStream.end();
@@ -989,10 +996,13 @@ const generateArtifacts = async (
     1,
   );
 
+  // Brief delay to allow lingering async crawlee storage operations to flush
+  await new Promise(resolve => setTimeout(resolve, 3000));
+
   try {
     await fs.promises.rm(path.join(storagePath, 'crawlee'), { recursive: true, force: true });
   } catch (error) {
-    consoleLogger.warn(`Unable to force remove crawlee folder: ${error.message}`);
+    // Silently ignore — folder may already be gone or still locked
   }
 
   try {

package/src/npmIndex.ts

@@ -12,10 +12,10 @@ import {
   getPlaywrightLaunchOptions,
   submitForm,
 } from './constants/common.js';
-import { createCrawleeSubFolders, filterAxeResults } from './crawlers/commonCrawlerFunc.js';
+import { createCrawleeSubFolders, enrichViolationMessages, filterAxeResults } from './crawlers/commonCrawlerFunc.js';
 import { createAndUpdateResultsFolders, getVersion } from './utils.js';
 import generateArtifacts, { createBasicFormHTMLSnippet, sendWcagBreakdownToSentry } from './mergeAxeResults.js';
-import { takeScreenshotForHTMLElements } from './screenshotFunc/htmlScreenshotFunc.js';
+import { enrichColorContrastDOMContext, takeScreenshotForHTMLElements } from './screenshotFunc/htmlScreenshotFunc.js';
 import { consoleLogger, silentLogger } from './logs.js';
 import { alertMessageOptions } from './constants/cliFunctions.js';
 import { evaluateAltText } from './crawlers/custom/evaluateAltText.js';
@@ -86,6 +86,13 @@ const getOobeeFunctionsScript = (disableOobee: boolean, enableWcagAaa: boolean)
       window.xPathToCss = ${xPathToCss.toString()};
       window.extractText = ${extractText.toString()};
       
+      function getReadabilityInterpretation(score) {
+        const num = parseFloat(score);
+        if (Number.isNaN(num)) return '';
+        if (num > 30) return 'It is targeted for junior college (JC) level comprehension and above.';
+        return 'It is targeted for university graduate level comprehension and above.';
+      }
+
       function getAxeConfiguration({
         enableWcagAaa = false,
         gradingReadabilityFlag = '',
@@ -120,7 +127,7 @@ const getOobeeFunctionsScript = (disableOobee: boolean, enableWcagAaa: boolean)
                 return !node.dataset.flagged; // fail any element with a data-flagged attribute set to true
               },
             },
-            ...((enableWcagAaa && !disableOobee)
+            ...((enableWcagAaa && !disableOobee && gradingReadabilityFlag !== '')
               ? [
                   {
                     id: 'oobee-grading-text-contents',
@@ -128,16 +135,11 @@ const getOobeeFunctionsScript = (disableOobee: boolean, enableWcagAaa: boolean)
                       impact: 'moderate',
                       messages: {
                         pass: 'The text content is easy to understand.',
-                        fail: 'The text content is potentially difficult to understand.',
-                        incomplete: \`The text content is potentially difficult to read, with a Flesch-Kincaid Reading Ease score of \${gradingReadabilityFlag}.\nThe target passing score is above 50, indicating content readable by university students and lower grade levels.\nA higher score reflects better readability.\`,
+                        fail: \`Text content is potentially difficult to read.\n  It scored \${gradingReadabilityFlag} out of 50 on the Flesch-Kincaid Readability Test.\n  \${getReadabilityInterpretation(gradingReadabilityFlag)}\`,
+                        incomplete: \`Text content is potentially difficult to read.\n  It scored \${gradingReadabilityFlag} out of 50 on the Flesch-Kincaid Readability Test.\n  \${getReadabilityInterpretation(gradingReadabilityFlag)}\`,
                       },
                     },
-                    evaluate: (_node) => {
-                      if (gradingReadabilityFlag === '') {
-                        return true; // Pass if no readability issues
-                      }
-                      // Fail if readability issues are detected
-                    },
+                    evaluate: (_node) => false,
                   },
                 ]
               : []),
@@ -168,7 +170,7 @@ const getOobeeFunctionsScript = (disableOobee: boolean, enableWcagAaa: boolean)
                 helpUrl: 'https://www.deque.com/blog/accessible-aria-buttons',
               },
             },
-            ...((enableWcagAaa && !disableOobee)
+            ...((enableWcagAaa && !disableOobee && gradingReadabilityFlag !== '')
               ? [
                   {
                     id: 'oobee-grading-text-contents',
@@ -864,6 +866,9 @@ export const scanPage = async (
         return window.runA11yScan();
       });
 
+      await enrichViolationMessages(scanResult.axeScanResults, page);
+      await enrichColorContrastDOMContext(scanResult.axeScanResults.violations, page);
+
       scanData.push({
         axeScanResults: scanResult.axeScanResults,
         pageUrl: page.url(),

package/src/screenshotFunc/htmlScreenshotFunc.ts

@@ -5,10 +5,89 @@ import path from 'path';
 // import { silentLogger } from '../logs.js';
 import { Result } from 'axe-core';
 import { Page } from 'playwright';
-import { NodeResultWithScreenshot, ResultWithScreenshot } from '../crawlers/commonCrawlerFunc.js';
+import {
+  ContrastDOMContext,
+  NodeResultWithScreenshot,
+  ResultWithScreenshot,
+} from '../crawlers/commonCrawlerFunc.js';
 
 const screenshotMap: Record<string, string> = {}; // Map of screenshot hashkey to its buffer value and screenshot path
 
+export const enrichColorContrastDOMContext = async (
+  violations: Result[],
+  page: Page,
+): Promise<void> => {
+  for (const violation of violations) {
+    if (violation.id !== 'color-contrast' && violation.id !== 'color-contrast-enhanced') continue;
+
+    for (const node of violation.nodes) {
+      const { target } = node;
+      const selector = target.length === 1 && typeof target[0] === 'string' ? target[0] : null;
+      if (!selector) continue;
+
+      try {
+        const domContext = await page
+          .evaluate((sel: string): ContrastDOMContext | null => {
+            const el = document.querySelector(sel);
+            if (!el) return null;
+
+            const style = window.getComputedStyle(el);
+            const bgImage = style.backgroundImage;
+            const hasGradient = bgImage !== 'none' && bgImage.includes('gradient');
+            const hasBackgroundImage = bgImage !== 'none' && !hasGradient;
+
+            let hasReducedOpacity = parseFloat(style.opacity) < 1;
+            let ancestorHasGradient = false;
+            let ancestorHasBackgroundImage = false;
+
+            let ancestor = el.parentElement;
+            while (ancestor && ancestor.tagName !== 'HTML') {
+              const anStyle = window.getComputedStyle(ancestor);
+              if (!hasReducedOpacity && parseFloat(anStyle.opacity) < 1) {
+                hasReducedOpacity = true;
+              }
+              const anBgImg = anStyle.backgroundImage;
+              if (anBgImg !== 'none') {
+                if (!ancestorHasGradient && anBgImg.includes('gradient')) {
+                  ancestorHasGradient = true;
+                } else if (!ancestorHasBackgroundImage) {
+                  ancestorHasBackgroundImage = true;
+                }
+              }
+              ancestor = ancestor.parentElement;
+            }
+
+            const mixBlendMode = style.mixBlendMode !== 'normal' ? style.mixBlendMode : null;
+            const backdropFilter =
+              style.backdropFilter && style.backdropFilter !== 'none'
+                ? style.backdropFilter
+                : null;
+            const filter = style.filter && style.filter !== 'none' ? style.filter : null;
+
+            return {
+              backgroundImage: bgImage !== 'none' ? bgImage : '',
+              hasGradient,
+              hasBackgroundImage,
+              ancestorHasGradient,
+              ancestorHasBackgroundImage,
+              hasReducedOpacity,
+              mixBlendMode,
+              backdropFilter,
+              filter,
+            };
+          }, selector)
+          .catch(() => null);
+
+        if (domContext) {
+          (node as NodeResultWithScreenshot).contrastDOMContext = domContext;
+        }
+      } catch {
+        // Non-critical; proceed without DOM context
+      }
+    }
+  }
+};
+
 export const takeScreenshotForHTMLElements = async (
   violations: Result[],
   page: Page,
@@ -67,6 +146,7 @@ export const takeScreenshotForHTMLElements = async (
         } catch (e) {
           // consoleLogger.info(`Unable to take element screenshot at ${selector}`);
         }
+
       }
       newViolationNodes.push(nodeWithScreenshotPath);
     }