snap-ally 1.0.1 → 1.0.2

package/README.md

@@ -164,6 +164,10 @@ Automated accessibility testing with Axe-core detects approximately **30–40% o
 
 snap-ally automates the "easy wins" in your CI/CD pipeline so your team can focus manual effort on the complex interactions that tools cannot evaluate.
 
+### Video missing in the VS Code Playwright extension
+
+If the report has no video when you run a test from the **VS Code Playwright extension**, uncheck **Show browser** in the Testing sidebar and run again. Playwright saves the video only when the browser context closes, and the extension's "Show browser" mode keeps a persistent context alive, so no video is produced (a [known Playwright behavior](https://github.com/microsoft/playwright/issues/33155), not a snap-ally bug). Running from the terminal (`npx playwright test`) and CI are unaffected.
+
 ---
 
 ## <span aria-hidden="true">🤝</span> Contributing

package/dist/SnapAllyReporter.js

@@ -158,7 +158,7 @@ class SnapAllyReporter {
         const violations = (actualData === null || actualData === void 0 ? void 0 : actualData.a11yErrors) || (actualData === null || actualData === void 0 ? void 0 : actualData.violations) || [];
         const a11yErrorCount = violations.reduce((acc, curr) => { var _a, _b; return acc + (curr.total || ((_a = curr.target) === null || _a === void 0 ? void 0 : _a.length) || ((_b = curr.nodes) === null || _b === void 0 ? void 0 : _b.length) || 0); }, 0);
         const filteredSteps = (() => {
-            const blocklist = ['Evaluate', 'Create page', 'Close page', 'Before Hooks', 'After Hooks', 'Worker Teardown', 'Worker Cleanup', 'Attach', 'Wait for timeout', 'Capture A11y screenshot'];
+            const blocklist = ['Evaluate', 'Create page', 'Close page', 'Before Hooks', 'After Hooks', 'Worker Teardown', 'Worker Cleanup', 'Attach', 'Wait for timeout', 'Capture A11y screenshot', 'Scroll into view', 'Bounding box'];
             const filtered = result.steps
                 .filter((s) => !blocklist.some(b => s.title.includes(b)))
                 .map((s) => s.title);

package/dist/core/HtmlRenderer.js

@@ -54,20 +54,24 @@ class HtmlRenderer {
             throw new Error(`[HtmlRenderer] Template not found: ${templatePath}`);
         }
         let html = fs.readFileSync(templatePath, 'utf8');
-        // Inline CSS
+        // Inline CSS. Use a replacement function so any `$` sequences in the
+        // injected content are inserted literally (a replacement *string* would
+        // interpret `$$`, `$&`, `` $` ``, `$'`, `$n` as special patterns).
         if (fs.existsSync(cssPath)) {
             const css = fs.readFileSync(cssPath, 'utf8');
-            html = html.replace('</head>', `<style>\n${css}\n</style>\n</head>`);
+            html = html.replace('</head>', () => `<style>\n${css}\n</style>\n</head>`);
             // Remove the link tag if it exists
             html = html.replace(/<link[^>]*global-report-styles\.css[^>]*>/, '');
         }
-        // Inline Data
-        const jsData = `window.snapAllyData = ${JSON.stringify(data)};`;
-        html = html.replace('<script src="data.js"></script>', `<script>\n${jsData}\n</script>`);
+        // Inline Data. Escape `</script` so violation HTML/text containing that
+        // sequence can't prematurely close the inlined <script> tag.
+        const jsonData = JSON.stringify(data).replace(/<\/script/gi, '<\\/script');
+        const jsData = `window.snapAllyData = ${jsonData};`;
+        html = html.replace('<script src="data.js"></script>', () => `<script>\n${jsData}\n</script>`);
         // Inline main logic
         if (fs.existsSync(jsPath)) {
             const js = fs.readFileSync(jsPath, 'utf8');
-            html = html.replace('<script src="report-app.js"></script>', `<script>\n${js}\n</script>`);
+            html = html.replace('<script src="report-app.js"></script>', () => `<script>\n${js}\n</script>`);
         }
         // Final cleanup of any potential remaining dummy scripts
         html = html.replace(/<script src="data-[^>]*\.js"><\/script>/, '');

package/dist/core/Scanner.d.ts

@@ -1,7 +1,8 @@
 import type { Page, TestInfo } from '@playwright/test';
 import { ScannerOptions } from '../models';
 /**
- * Performs an accessibility audit using Axe and Lighthouse.
+ * Performs an accessibility audit using Axe and attaches the results as the
+ * 'A11y' attachment consumed by SnapAllyReporter.
  */
 export declare function scanA11y(page: Page, testInfo: TestInfo, options?: ScannerOptions): Promise<void>;
 export declare const checkAccessibility: typeof scanA11y;

package/dist/core/Scanner.js

@@ -10,6 +10,14 @@ const test_1 = require("@playwright/test");
 const VisualReporter_1 = require("./VisualReporter");
 const models_1 = require("../models");
 const TimeUtils_1 = require("../utils/TimeUtils");
+/** Annotation types rendered separately in the report, so they must not repeat as context steps. */
+const EXCLUDED_ANNOTATION_TYPES = new Set(['Pre Condition', 'Post Condition', 'Description', 'A11y']);
+/**
+ * Matches reporter ids that refer to SnapAllyReporter: the file path used
+ * inside this repo (e.g. './src/SnapAllyReporter.ts') or the published
+ * package name ('snap-ally').
+ */
+const REPORTER_ID_PATTERN = /snap-?ally/i;
 /**
  * Sanitizes a string to be safe for use in file paths and prevents path traversal attacks.
  */
@@ -24,141 +32,172 @@ function sanitizePageKey(input) {
         .substring(0, 200));
 }
 /**
- * Performs an accessibility audit using Axe and Lighthouse.
+ * Reads the SnapAllyReporter options from the Playwright config so scans can
+ * fall back to the globally configured defaults.
  */
-async function scanA11y(page, testInfo, options = {}) {
-    var _a, _b, _c, _d, _e, _f, _g, _h;
-    // 1. Find reporter config for global defaults
-    const reporterConfig = testInfo.config.reporter.find((r) => Array.isArray(r) &&
-        (typeof r[0] === 'string' &&
-            (r[0].includes('SnapAllyReporter') || r[0].endsWith('SnapAllyReporter.ts'))));
-    const globalOptions = (Array.isArray(reporterConfig) ? ((_a = reporterConfig[1]) !== null && _a !== void 0 ? _a : {}) : {});
-    // 2. Resolve final options (local > global > default)
-    const showTerminal = (_c = (_b = options.verbose) !== null && _b !== void 0 ? _b : globalOptions.verbose) !== null && _c !== void 0 ? _c : true;
-    const showBrowser = (_e = (_d = options.consoleLog) !== null && _d !== void 0 ? _d : globalOptions.consoleLog) !== null && _e !== void 0 ? _e : true;
-    const rawPageKey = options.pageKey || page.url();
-    const pageKey = sanitizePageKey(rawPageKey);
-    const overlay = new VisualReporter_1.VisualReporter(page);
-    let axeBuilder = new playwright_1.default({ page });
+function getReporterOptions(testInfo) {
+    var _a;
+    // A reporter entry is normally a [name, options?] tuple, but Playwright also
+    // accepts a bare string (e.g. reporter: 'snap-ally'), so handle both shapes.
+    const reporters = testInfo.config.reporter;
+    const entry = reporters.find((descriptor) => {
+        const name = typeof descriptor === 'string' ? descriptor : descriptor[0];
+        return REPORTER_ID_PATTERN.test(name);
+    });
+    if (!entry || typeof entry === 'string') {
+        return {};
+    }
+    return ((_a = entry[1]) !== null && _a !== void 0 ? _a : {});
+}
+function buildAxe(page, options) {
+    let builder = new playwright_1.default({ page });
     const target = options.include || options.box;
     if (target) {
-        if (typeof target === 'string') {
-            axeBuilder = axeBuilder.include(target);
-        }
-        else {
-            axeBuilder = axeBuilder.include(target);
+        // AxeBuilder.include only accepts selector strings (axe-core SerialFrameSelector),
+        // never a Playwright Locator. Guard JS callers that bypass the type with a clear error.
+        if (typeof target !== 'string') {
+            throw new Error('[SnapAlly] "include"/"box" must be a CSS selector string; ' +
+                'Playwright Locators are not supported by AxeBuilder.');
         }
+        builder = builder.include(target);
     }
     if (options.rules) {
-        axeBuilder = axeBuilder.options({ rules: options.rules });
+        builder = builder.options({ rules: options.rules });
     }
     if (options.tags) {
-        axeBuilder = axeBuilder.withTags(options.tags);
+        builder = builder.withTags(options.tags);
     }
     if (options.axeOptions) {
-        axeBuilder = axeBuilder.options(options.axeOptions);
+        builder = builder.options(options.axeOptions);
     }
-    let axeResults;
+    return builder;
+}
+/**
+ * Runs the Axe analysis, returning null when the page closed before the scan
+ * could finish (e.g. the test already ended).
+ */
+async function runAxe(builder) {
     try {
-        axeResults = await axeBuilder.analyze();
+        return await builder.analyze();
     }
     catch (error) {
         if (error instanceof Error &&
             (error.message.includes('Test ended') ||
                 error.message.includes('Target page, context or browser has been closed'))) {
             console.warn(`[SnapAlly] Accessibility scan skipped: ${error.message}`);
-            return;
+            return null;
         }
         throw error;
     }
-    const violationCount = axeResults.violations.length;
-    if ((showTerminal || showBrowser) && violationCount > 0) {
-        const mainMsg = `[A11yScanner] Violations found: ${violationCount}`;
-        const detailMessages = axeResults.violations.map(
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        (v, i) => `  ${i + 1}. ${v.id} [${v.impact}] - ${v.help}`);
-        if (showTerminal) {
-            console.log(`\n${mainMsg}`);
-            detailMessages.forEach((msg) => console.log(msg));
-        }
-        if (showBrowser) {
-            await page.evaluate(([mainMsg, details, color]) => {
-                console.log(`%c ${mainMsg}`, `color: ${color}; font-weight: bold; font-size: 12px;`);
-                details.forEach((msg) => console.log(msg));
-            }, [mainMsg, detailMessages, models_1.DEFAULT_COLORS.serious]);
+}
+async function logViolations(page, violations, showTerminal, showBrowser) {
+    if (violations.length === 0 || (!showTerminal && !showBrowser)) {
+        return;
+    }
+    const mainMsg = `[A11yScanner] Violations found: ${violations.length}`;
+    const detailMessages = violations.map((violation, index) => `  ${index + 1}. ${violation.id} [${violation.impact}] - ${violation.help}`);
+    if (showTerminal) {
+        console.log(`\n${mainMsg}`);
+        detailMessages.forEach((msg) => console.log(msg));
+    }
+    if (showBrowser) {
+        await page.evaluate(([msg, details, color]) => {
+            console.log(`%c ${msg}`, `color: ${color}; font-weight: bold; font-size: 12px;`);
+            details.forEach((line) => console.log(line));
+        }, [mainMsg, detailMessages, models_1.DEFAULT_COLORS.serious]);
+    }
+}
+/**
+ * Highlights each visible violating element, captures a screenshot per element,
+ * and returns the violation enriched with that visual evidence.
+ */
+async function collectViolationEvidence(page, testInfo, visualReporter, violation, severityColor, contextSteps) {
+    const targets = [];
+    let screenshotIndex = 0;
+    await visualReporter.showBanner({ id: violation.id, help: violation.help, color: severityColor });
+    for (const node of violation.nodes) {
+        for (const selector of node.target) {
+            const elementSelector = selector.toString();
+            if (!(await page.locator(elementSelector).isVisible())) {
+                continue;
+            }
+            await visualReporter.highlightElement(elementSelector, severityColor);
+            // Let the highlight transition settle before the screenshot.
+            // eslint-disable-next-line playwright/no-wait-for-timeout
+            await page.waitForTimeout(100);
+            const screenshotName = `a11y-${violation.id}-${screenshotIndex++}.png`;
+            const buffer = await visualReporter.captureScreenshot(testInfo, screenshotName);
+            targets.push({
+                element: elementSelector,
+                snippet: elementSelector,
+                html: node.html || '',
+                screenshot: screenshotName,
+                steps: contextSteps,
+                stepsJson: JSON.stringify(contextSteps),
+                screenshotBase64: buffer.toString('base64'),
+            });
+            await visualReporter.removeHighlight();
         }
     }
+    // Remove this violation's banner so banners don't stack across violations.
+    await visualReporter.cleanupOverlay();
+    return {
+        id: violation.id,
+        description: violation.description,
+        severity: violation.impact || 'unknown',
+        helpUrl: violation.helpUrl,
+        help: violation.help,
+        guideline: violation.tags[1] || 'N/A',
+        wcagRule: violation.tags.find((tag) => tag.startsWith('wcag')) || violation.tags[1] || 'N/A',
+        total: targets.length || violation.nodes.length,
+        target: targets,
+    };
+}
+/**
+ * Performs an accessibility audit using Axe and attaches the results as the
+ * 'A11y' attachment consumed by SnapAllyReporter.
+ */
+async function scanA11y(page, testInfo, options = {}) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+    const globalOptions = getReporterOptions(testInfo);
+    // Resolve final options (local > global > default)
+    const showTerminal = (_b = (_a = options.verbose) !== null && _a !== void 0 ? _a : globalOptions.verbose) !== null && _b !== void 0 ? _b : true;
+    const showBrowser = (_d = (_c = options.consoleLog) !== null && _c !== void 0 ? _c : globalOptions.consoleLog) !== null && _d !== void 0 ? _d : true;
+    const pageKey = sanitizePageKey(options.pageKey || page.url());
+    const customColors = globalOptions.colors;
+    const axeResults = await runAxe(buildAxe(page, options));
+    if (!axeResults) {
+        return;
+    }
+    await logViolations(page, axeResults.violations, showTerminal, showBrowser);
+    const violationCount = axeResults.violations.length;
     await test_1.test.step('Check Accessibility', async () => {
         test_1.expect.soft(violationCount).toBe(0);
     });
-    const customColors = globalOptions === null || globalOptions === void 0 ? void 0 : globalOptions.colors;
-    const errors = [];
+    const visualReporter = new VisualReporter_1.VisualReporter(page);
+    const contextSteps = (testInfo.annotations || [])
+        .filter((annotation) => !EXCLUDED_ANNOTATION_TYPES.has(annotation.type))
+        .map((annotation) => annotation.description || '');
+    const violations = [];
     for (const violation of axeResults.violations) {
-        let errorIdx = 0;
-        const targets = [];
         const severityColor = (0, models_1.getSeverityColor)(violation.impact, customColors);
-        for (const node of violation.nodes) {
-            for (const selector of node.target) {
-                const elementSelector = selector.toString();
-                const locator = page.locator(elementSelector);
-                await overlay.showBanner({ id: violation.id, help: violation.help }, severityColor);
-                if (await locator.isVisible()) {
-                    await overlay.highlightElement(elementSelector, severityColor);
-                    // eslint-disable-next-line playwright/no-wait-for-timeout
-                    await page.waitForTimeout(100);
-                    const screenshotName = `a11y-${violation.id}-${errorIdx++}.png`;
-                    const buffer = await overlay.captureScreenshot(testInfo, screenshotName);
-                    const excluded = new Set([
-                        'Pre Condition',
-                        'Post Condition',
-                        'Description',
-                        'A11y',
-                    ]);
-                    const contextSteps = (testInfo.annotations || [])
-                        .filter((a) => !excluded.has(a.type))
-                        .map((a) => a.description || '');
-                    const nodeHtml = node.html || '';
-                    const friendlySnippet = elementSelector;
-                    targets.push({
-                        element: elementSelector,
-                        snippet: friendlySnippet,
-                        html: nodeHtml,
-                        screenshot: screenshotName,
-                        steps: contextSteps,
-                        stepsJson: JSON.stringify(contextSteps),
-                        screenshotBase64: buffer.toString('base64'),
-                    });
-                    await overlay.removeHighlight();
-                }
-            }
-        }
-        errors.push({
-            id: violation.id,
-            description: violation.description,
-            severity: violation.impact || 'unknown',
-            helpUrl: violation.helpUrl,
-            help: violation.help,
-            guideline: violation.tags[1] || 'N/A',
-            wcagRule: violation.tags.find((t) => t.startsWith('wcag')) || violation.tags[1] || 'N/A',
-            total: targets.length || violation.nodes.length,
-            target: targets,
-        });
+        violations.push(await collectViolationEvidence(page, testInfo, visualReporter, violation, severityColor, contextSteps));
     }
     const reportData = {
         pageKey,
         pageUrl: page.url(),
         accessibilityScore: 0,
-        a11yErrors: errors,
+        a11yErrors: violations,
         criticalColor: (customColors === null || customColors === void 0 ? void 0 : customColors.critical) || models_1.DEFAULT_COLORS.critical,
         seriousColor: (customColors === null || customColors === void 0 ? void 0 : customColors.serious) || models_1.DEFAULT_COLORS.serious,
         moderateColor: (customColors === null || customColors === void 0 ? void 0 : customColors.moderate) || models_1.DEFAULT_COLORS.moderate,
         minorColor: (customColors === null || customColors === void 0 ? void 0 : customColors.minor) || models_1.DEFAULT_COLORS.minor,
-        adoOrganization: ((_f = options.ado) === null || _f === void 0 ? void 0 : _f.organization) || process.env.ADO_ORGANIZATION || '',
-        adoProject: ((_g = options.ado) === null || _g === void 0 ? void 0 : _g.project) || process.env.ADO_PROJECT || '',
-        adoAreaPath: ((_h = options.ado) === null || _h === void 0 ? void 0 : _h.areaPath) || process.env.ADO_AREA_PATH || '',
+        adoOrganization: ((_e = options.ado) === null || _e === void 0 ? void 0 : _e.organization) || ((_f = globalOptions.ado) === null || _f === void 0 ? void 0 : _f.organization) || process.env.ADO_ORGANIZATION || '',
+        adoProject: ((_g = options.ado) === null || _g === void 0 ? void 0 : _g.project) || ((_h = globalOptions.ado) === null || _h === void 0 ? void 0 : _h.project) || process.env.ADO_PROJECT || '',
+        adoAreaPath: ((_j = options.ado) === null || _j === void 0 ? void 0 : _j.areaPath) || ((_k = globalOptions.ado) === null || _k === void 0 ? void 0 : _k.areaPath) || process.env.ADO_AREA_PATH || '',
         timestamp: TimeUtils_1.TimeUtils.formatDate(new Date()),
     };
-    await overlay.attachJsonData(testInfo, 'A11y', JSON.stringify(reportData));
-    await overlay.cleanupOverlay();
+    await visualReporter.attachJsonData(testInfo, 'A11y', JSON.stringify(reportData));
+    await visualReporter.cleanupOverlay();
 }
 exports.checkAccessibility = scanA11y;

package/dist/core/VisualReporter.d.ts

@@ -1,54 +1,28 @@
 import { type Page, type TestInfo } from '@playwright/test';
-/**
- * Information about an accessibility violation to display.
- */
-interface ViolationInfo {
-    id: string;
-    help: string;
-}
+import { BannerInfo } from '../models';
 /**
  * Manages visual feedback on the page during an accessibility scan.
  * Handles element highlights, violation banners, and report attachments.
  */
 export declare class VisualReporter {
     private readonly page;
-    private readonly overlayHostId;
-    private static readonly BANNER_ID;
-    private static readonly HIGHLIGHT_ID;
-    private static readonly HIGHLIGHT_PADDING;
-    private static readonly BANNER_ALPHA;
-    private static readonly HIGHLIGHT_SHADOW_ALPHA;
-    private static readonly PAGE_LIFECYCLE_ERROR_PATTERNS;
+    private readonly HIGHLIGHT_PADDING;
+    private readonly BANNER_ALPHA;
+    private static readonly BANNER_STYLE;
+    private static readonly BADGE_STYLE;
+    private static readonly HIGHLIGHT_STYLE;
+    private bannerOverlay;
+    private actionsOverlay;
+    private highlightOverlay;
     constructor(page: Page);
-    showBanner(violation: ViolationInfo, color: string): Promise<void>;
+    /**
+     * Applies alpha transparency to a CSS color string (hex, rgb, hsl, or named color).
+     */
+    private addAlphaToColor;
+    showBanner(violation: BannerInfo): Promise<void>;
     highlightElement(selector: string, color: string): Promise<void>;
     cleanupOverlay(): Promise<void>;
     removeHighlight(): Promise<void>;
     attachJsonData(testInfo: TestInfo, name: string, data: string): Promise<void>;
     captureScreenshot(testInfo: TestInfo, name: string): Promise<Buffer>;
-    /**
-     * Injects helper functions into the page context for overlay management.
-     * These helpers are used by visual feedback operations (banner, highlight).
-     */
-    private ensurePageHelpers;
-    /**
-     * Checks if an error message indicates a page lifecycle issue.
-     */
-    private isPageLifecycleError;
-    /**
-     * Executes a function in the page context with safety guarantees:
-     * 1. Ensures overlay helper functions are injected before execution
-     * 2. Gracefully handles page lifecycle errors (closed/destroyed pages)
-     *
-     * @param fn - Function to execute in the page context
-     * @param arg - Optional argument to pass to the function
-     */
-    private safeEvaluate;
-}
-declare global {
-    interface Window {
-        getOrCreateOverlayShadowRoot: (id: string) => ShadowRoot;
-        addAlphaToColor: (color: string, alpha: number) => string;
-    }
 }
-export {};

package/dist/core/VisualReporter.js

@@ -9,105 +9,62 @@ const test_1 = require("@playwright/test");
 class VisualReporter {
     constructor(page) {
         this.page = page;
-        this.overlayHostId = 'snap-ally-visual-root';
+        this.HIGHLIGHT_PADDING = 4;
+        this.BANNER_ALPHA = 0.85;
+        this.bannerOverlay = null;
+        this.actionsOverlay = null;
+        this.highlightOverlay = null;
     }
-    async showBanner(violation, color) {
-        await this.safeEvaluate(([v, rawColor, rootId, bannerId, bannerAlpha]) => {
-            const shadow = window.getOrCreateOverlayShadowRoot(rootId);
-            let container = shadow.getElementById(bannerId);
-            if (!container) {
-                const style = document.createElement('style');
-                style.textContent = `
-                        #${bannerId} {
-                            position: fixed;
-                            left: 50%;
-                            top: 24px;
-                            transform: translateX(-50%);
-                            width: calc(100% - 40px);
-                            max-width: 600px;
-                            padding: 12px 18px;
-                            border-radius: 12px;
-                            color: white;
-                            font-family: system-ui, -apple-system, sans-serif;
-                            font-size: 14px;
-                            display: flex;
-                            align-items: center;
-                            gap: 12px;
-                            box-shadow: 0 12px 40px rgba(0,0,0,0.3);
-                            backdrop-filter: blur(16px) saturate(180%);
-                            -webkit-backdrop-filter: blur(16px) saturate(180%);
-                            border: 1px solid rgba(255,255,255,0.15);
-                            z-index: 10000;
-                            transition: all 0.3s ease;
-                        }
-                        .badge {
-                            background: rgba(255,255,255,0.2);
-                            padding: 2px 8px;
-                            border-radius: 6px;
-                            font-size: 11px;
-                            font-weight: 700;
-                            text-transform: uppercase;
-                            border: 1px solid rgba(255,255,255,0.2);
-                        }
-                        .content { flex: 1; line-height: 1.4; font-weight: 500; }
-                    `;
-                shadow.appendChild(style);
-                container = document.createElement('div');
-                container.id = bannerId;
-                shadow.appendChild(container);
-            }
-            container.style.backgroundColor = window.addAlphaToColor(rawColor, bannerAlpha);
-            container.innerHTML = `
-                    <div style="font-size: 20px;">⚠️</div>
-                    <div class="content">
-                        <div style="margin-bottom:4px; display:flex; align-items:center; gap:8px;">
-                            <span class="badge">${v.id}</span>
-                            <span style="opacity: 0.9;">${v.help}</span>
-                        </div>
-                    </div>
-                `;
-        }, [violation, color, this.overlayHostId, VisualReporter.BANNER_ID, VisualReporter.BANNER_ALPHA]);
+    /**
+     * Applies alpha transparency to a CSS color string (hex, rgb, hsl, or named color).
+     */
+    addAlphaToColor(color, alpha) {
+        return `color-mix(in srgb, ${color} ${alpha * 100}%, transparent)`;
+    }
+    async showBanner(violation) {
+        this.actionsOverlay = await this.page.screencast.showActions({ position: 'top' });
+        const backgroundColor = this.addAlphaToColor(violation.color, this.BANNER_ALPHA);
+        const bannerHtml = `
+            <div style="${VisualReporter.BANNER_STYLE} background-color: ${backgroundColor};">
+                <div style="flex: 1; line-height: 1.4; font-weight: 500; display: flex; align-items: center; gap: 8px;">
+                    <span style="${VisualReporter.BADGE_STYLE}">${violation.id}</span>
+                    <span style="opacity: 0.9;">${violation.help}</span>
+                </div>
+            </div>
+        `;
+        this.bannerOverlay = await this.page.screencast.showOverlay(bannerHtml);
     }
     async highlightElement(selector, color) {
-        await this.safeEvaluate(([sel, rawColor, rootId, highlightId, padding, shadowAlpha]) => {
-            const target = document.querySelector(sel);
-            if (!target)
-                return;
-            target.scrollIntoView({ behavior: 'auto', block: 'center' });
-            const shadow = window.getOrCreateOverlayShadowRoot(rootId);
-            let highlight = shadow.getElementById(highlightId);
-            if (!highlight) {
-                const style = document.createElement('style');
-                style.textContent = `
-                        #${highlightId} {
-                            position: absolute;
-                            pointer-events: none;
-                            border-radius: 8px;
-                            box-sizing: border-box;
-                            z-index: 9999;
-                            transition: all 0.2s ease;
-                            box-shadow: 0 0 0 4px var(--c-alpha), 0 0 20px var(--c-alpha);
-                        }
-                    `;
-                shadow.appendChild(style);
-                highlight = document.createElement('div');
-                highlight.id = highlightId;
-                shadow.appendChild(highlight);
-            }
-            const rect = target.getBoundingClientRect();
-            highlight.style.left = `${rect.left + window.scrollX - padding}px`;
-            highlight.style.top = `${rect.top + window.scrollY - padding}px`;
-            highlight.style.width = `${rect.width + padding * 2}px`;
-            highlight.style.height = `${rect.height + padding * 2}px`;
-            highlight.style.border = `3px solid ${rawColor}`;
-            highlight.style.setProperty('--c-alpha', window.addAlphaToColor(rawColor, shadowAlpha));
-        }, [selector, color, this.overlayHostId, VisualReporter.HIGHLIGHT_ID, VisualReporter.HIGHLIGHT_PADDING, VisualReporter.HIGHLIGHT_SHADOW_ALPHA]);
+        const locator = this.page.locator(selector);
+        await locator.scrollIntoViewIfNeeded();
+        const box = await locator.boundingBox();
+        if (!box)
+            return;
+        const padding = this.HIGHLIGHT_PADDING;
+        const highlightHtml = `
+            <div style="
+                position: fixed;
+                left: ${box.x - padding}px;
+                top: ${box.y - padding}px;
+                width: ${box.width + padding * 2}px;
+                height: ${box.height + padding * 2}px;
+                border: 3px solid ${color};
+                ${VisualReporter.HIGHLIGHT_STYLE}
+            "></div>
+        `;
+        this.highlightOverlay = await this.page.screencast.showOverlay(highlightHtml);
     }
     async cleanupOverlay() {
-        await this.safeEvaluate((id) => { var _a; return (_a = document.getElementById(id)) === null || _a === void 0 ? void 0 : _a.remove(); }, this.overlayHostId);
+        var _a, _b;
+        await ((_a = this.bannerOverlay) === null || _a === void 0 ? void 0 : _a.dispose());
+        await ((_b = this.actionsOverlay) === null || _b === void 0 ? void 0 : _b.dispose());
+        this.bannerOverlay = null;
+        this.actionsOverlay = null;
     }
     async removeHighlight() {
-        await this.safeEvaluate(([rootId, hId]) => { var _a, _b, _c; return (_c = (_b = (_a = document.getElementById(rootId)) === null || _a === void 0 ? void 0 : _a.shadowRoot) === null || _b === void 0 ? void 0 : _b.getElementById(hId)) === null || _c === void 0 ? void 0 : _c.remove(); }, [this.overlayHostId, VisualReporter.HIGHLIGHT_ID]);
+        var _a;
+        await ((_a = this.highlightOverlay) === null || _a === void 0 ? void 0 : _a.dispose());
+        this.highlightOverlay = null;
     }
     async attachJsonData(testInfo, name, data) {
         await testInfo.attach(name, {
@@ -122,71 +79,33 @@ class VisualReporter {
             return screenshot;
         });
     }
-    /**
-     * Injects helper functions into the page context for overlay management.
-     * These helpers are used by visual feedback operations (banner, highlight).
-     */
-    async ensurePageHelpers() {
-        await this.page.evaluate(() => {
-            const w = window;
-            // Check if both helpers are already defined
-            if (typeof w.getOrCreateOverlayShadowRoot === 'function' && typeof w.addAlphaToColor === 'function') {
-                return;
-            }
-            w.getOrCreateOverlayShadowRoot = (id) => {
-                let root = document.getElementById(id);
-                if (!root) {
-                    root = document.createElement('div');
-                    root.id = id;
-                    root.style.cssText = 'position:absolute;top:0;left:0;width:0;height:0;z-index:2147483647;';
-                    document.body.appendChild(root);
-                    root.attachShadow({ mode: 'open' });
-                }
-                return root.shadowRoot;
-            };
-            w.addAlphaToColor = (color, alpha) => {
-                if (color.startsWith('rgba'))
-                    return color.replace(/[\d.]+\)$/, `${alpha})`);
-                if (color.startsWith('rgb'))
-                    return color.replace('rgb', 'rgba').replace(')', `, ${alpha})`);
-                const hex = Math.round(alpha * 255).toString(16).padStart(2, '0');
-                return `${color}${hex}`;
-            };
-        });
-    }
-    /**
-     * Checks if an error message indicates a page lifecycle issue.
-     */
-    isPageLifecycleError(message) {
-        const lowerMsg = message.toLowerCase();
-        return VisualReporter.PAGE_LIFECYCLE_ERROR_PATTERNS.some(pattern => lowerMsg.includes(pattern));
-    }
-    /**
-     * Executes a function in the page context with safety guarantees:
-     * 1. Ensures overlay helper functions are injected before execution
-     * 2. Gracefully handles page lifecycle errors (closed/destroyed pages)
-     *
-     * @param fn - Function to execute in the page context
-     * @param arg - Optional argument to pass to the function
-     */
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    async safeEvaluate(fn, arg) {
-        try {
-            await this.ensurePageHelpers();
-            await (arg !== undefined ? this.page.evaluate(fn, arg) : this.page.evaluate(fn));
-        }
-        catch (e) {
-            const msg = e instanceof Error ? e.message : String(e);
-            if (this.isPageLifecycleError(msg))
-                return;
-            throw e;
-        }
-    }
 }
 exports.VisualReporter = VisualReporter;
-VisualReporter.BANNER_ID = 'snap-ally-banner';
-VisualReporter.HIGHLIGHT_ID = 'snap-ally-highlight';
-VisualReporter.HIGHLIGHT_PADDING = 4;
-VisualReporter.BANNER_ALPHA = 0.85;
-VisualReporter.HIGHLIGHT_SHADOW_ALPHA = 0.3;
-VisualReporter.PAGE_LIFECYCLE_ERROR_PATTERNS = ['closed', 'destroyed', 'ended'];
+VisualReporter.BANNER_STYLE = `
+        position: absolute;
+        top: 16px;
+        left: 50%;
+        transform: translateX(-50%);
+        width: fit-content;
+        max-width: 600px;
+        padding: 12px 18px;
+        border-radius: 12px;
+        color: white;
+        font-family: system-ui, -apple-system, sans-serif;
+        font-size: 14px;
+        z-index: 10000;
+    `;
+VisualReporter.BADGE_STYLE = `
+        background: rgba(255,255,255,0.2);
+        padding: 2px 8px;
+        border-radius: 6px;
+        font-size: 11px;
+        font-weight: 700;
+        text-transform: uppercase;
+    `;
+VisualReporter.HIGHLIGHT_STYLE = `
+        border-radius: 8px;
+        box-sizing: border-box;
+        pointer-events: none;
+        z-index: 9999;
+    `;

package/dist/models/BannerInfo.d.ts

@@ -0,0 +1,6 @@
+/** Data needed to render a violation banner overlay on the page. */
+export interface BannerInfo {
+    id: string;
+    help: string;
+    color: string;
+}

package/dist/models/BannerInfo.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/models/ScannerOptions.d.ts

@@ -1,12 +1,14 @@
-import type { Locator } from '@playwright/test';
 /**
  * Options for the accessibility scanner.
  */
 export interface ScannerOptions {
-    /** Specific selector or locator to include in the scan. */
-    include?: string | Locator;
+    /**
+     * CSS selector to limit the scan to. Must be a string: AxeBuilder only
+     * accepts selector strings, not Playwright Locators.
+     */
+    include?: string;
     /** Alias for include. */
-    box?: string | Locator;
+    box?: string;
     /** Whether to log violations to the console. @default true */
     verbose?: boolean;
     /** Alias for verbose. */

package/dist/models/index.d.ts

@@ -1,4 +1,5 @@
 export * from './Violation';
+export * from './BannerInfo';
 export * from './ReportData';
 export * from './TestResults';
 export * from './ScannerOptions';

package/dist/models/index.js

@@ -15,6 +15,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./Violation"), exports);
+__exportStar(require("./BannerInfo"), exports);
 __exportStar(require("./ReportData"), exports);
 __exportStar(require("./TestResults"), exports);
 __exportStar(require("./ScannerOptions"), exports);

package/dist/templates/global-report-styles.css

@@ -186,8 +186,8 @@ header {
     right: 0;
     z-index: 1000;
     background: rgba(255, 255, 255, 0.8);
-    backdrop-filter: blur(20px) saturate(180%);
     -webkit-backdrop-filter: blur(20px) saturate(180%);
+    backdrop-filter: blur(20px) saturate(180%);
     border-bottom: 1px solid var(--glass-border);
     padding: 14px 40px;
     display: flex;
@@ -230,8 +230,8 @@ header {
 /* Footer */
 footer {
     background: rgba(255, 255, 255, 0.7);
-    backdrop-filter: blur(12px);
     -webkit-backdrop-filter: blur(12px);
+    backdrop-filter: blur(12px);
     border-top: 1px solid var(--glass-border);
     padding: 24px 40px;
     margin-top: auto;
@@ -485,6 +485,7 @@ footer {
     justify-content: center;
     background: rgba(255, 255, 255, 0.2);
     border-radius: 30px;
+    -webkit-backdrop-filter: blur(10px);
     backdrop-filter: blur(10px);
 }
 
@@ -550,6 +551,7 @@ footer {
     border-radius: 12px;
     font-size: 0.85rem;
     font-weight: 700;
+    -webkit-backdrop-filter: blur(5px);
     backdrop-filter: blur(5px);
     color: white;
 }
@@ -1293,6 +1295,7 @@ video {
 /* Charts */
 .chart-box {
     background: var(--card-bg);
+    -webkit-backdrop-filter: blur(12px);
     backdrop-filter: blur(12px);
     border: 1px solid var(--glass-border);
     border-radius: 24px;
@@ -1424,6 +1427,7 @@ video {
 /* Violation Cards */
 .violation-card {
     background: var(--glass-bg);
+    -webkit-backdrop-filter: blur(8px);
     backdrop-filter: blur(8px);
     border-radius: var(--card-radius);
     border: 1px solid var(--glass-border);
@@ -1757,6 +1761,7 @@ video {
     border: 1px solid var(--glass-border);
     box-shadow: 0 25px 50px rgba(0, 0, 0, 0.15);
     background: rgba(255, 255, 255, 0.98);
+    -webkit-backdrop-filter: blur(10px);
     backdrop-filter: blur(10px);
     overflow: hidden;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "snap-ally",
-    "version": "1.0.1",
+    "version": "1.0.2",
     "description": "A custom Playwright reporter for Accessibility testing using Axe, with HTML reporting and Azure DevOps integration.",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
@@ -33,19 +33,19 @@
         "@axe-core/playwright": "^4.11.1"
     },
     "peerDependencies": {
-        "@playwright/test": "^1.58.2",
-        "playwright": "^1.58.2"
+        "@playwright/test": "^1.60.0",
+        "playwright": "^1.60.0"
     },
     "devDependencies": {
-        "@playwright/test": "^1.58.2",
-        "@types/node": "^20.0.0",
-        "@typescript-eslint/eslint-plugin": "^8.56.1",
-        "@typescript-eslint/parser": "^8.56.1",
-        "eslint": "^10.0.2",
+        "@playwright/test": "^1.60.0",
+        "@types/node": "^25.9.3",
+        "@typescript-eslint/eslint-plugin": "^8.61.0",
+        "@typescript-eslint/parser": "^8.61.0",
+        "eslint": "^10.4.1",
         "eslint-config-prettier": "^10.1.8",
-        "eslint-plugin-playwright": "^2.9.0",
-        "jsdom": "^28.1.0",
-        "prettier": "^3.8.1",
-        "typescript": "^5.0.0"
+        "eslint-plugin-playwright": "^2.10.4",
+        "jsdom": "^29.1.1",
+        "prettier": "^3.8.4",
+        "typescript": "^6.0.3"
     }
-}
+}