@testivai/witness-playwright 1.3.3 → 1.5.1

package/dist/capture/element-map.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Element-map capture — the layout + computed-style digest that powers
+ * element attribution, shift classification, and the style fingerprint
+ * on the comparison side (@testivai/witness).
+ *
+ * `collectElementMap` is a SELF-CONTAINED function (no imports, no
+ * closures) so it can be serialized into the page with
+ * `(${collectElementMap.toString()})(document, window, max)` — and unit
+ * tested in Node against a duck-typed DOM. Keep it dependency-free.
+ */
+export interface CollectedElement {
+    path: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    styleHash: string;
+}
+/**
+ * Walk the document and produce [{path, rect, styleHash}] in document
+ * coordinates (DPR-scaled to match full-page screenshot pixels).
+ *
+ * - `path` is deterministic: tag + first class + :nth-of-type when the
+ *   element has same-tag element siblings.
+ * - Elements smaller than 4×4 px and invisible elements are skipped.
+ * - The walk is depth-first and capped at `maxElements`.
+ * - `styleHash` digests a fixed, documented list of computed properties
+ *   (FNV-1a 32-bit, hex) — deterministic for identical rendering.
+ */
+export declare function collectElementMap(doc: Document, win: Window & typeof globalThis, maxElements: number): CollectedElement[];
+/** Default element cap — bounds capture time and elements.json size. */
+export declare const DEFAULT_MAX_ELEMENTS = 3000;
+/**
+ * The page-side expression evaluated by the adapter. Serializes the
+ * collector so page code and unit-tested code are the same function.
+ */
+export declare function buildElementMapExpression(maxElements?: number): string;

package/dist/capture/element-map.js

@@ -0,0 +1,123 @@
+"use strict";
+/**
+ * Element-map capture — the layout + computed-style digest that powers
+ * element attribution, shift classification, and the style fingerprint
+ * on the comparison side (@testivai/witness).
+ *
+ * `collectElementMap` is a SELF-CONTAINED function (no imports, no
+ * closures) so it can be serialized into the page with
+ * `(${collectElementMap.toString()})(document, window, max)` — and unit
+ * tested in Node against a duck-typed DOM. Keep it dependency-free.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MAX_ELEMENTS = void 0;
+exports.collectElementMap = collectElementMap;
+exports.buildElementMapExpression = buildElementMapExpression;
+/**
+ * Walk the document and produce [{path, rect, styleHash}] in document
+ * coordinates (DPR-scaled to match full-page screenshot pixels).
+ *
+ * - `path` is deterministic: tag + first class + :nth-of-type when the
+ *   element has same-tag element siblings.
+ * - Elements smaller than 4×4 px and invisible elements are skipped.
+ * - The walk is depth-first and capped at `maxElements`.
+ * - `styleHash` digests a fixed, documented list of computed properties
+ *   (FNV-1a 32-bit, hex) — deterministic for identical rendering.
+ */
+function collectElementMap(doc, win, maxElements) {
+    var STYLE_PROPS = [
+        'color', 'background-color', 'background-image',
+        'border-top-color', 'border-right-color', 'border-bottom-color', 'border-left-color',
+        'border-top-width', 'border-right-width', 'border-bottom-width', 'border-left-width',
+        'border-top-style', 'border-bottom-style', 'border-radius',
+        'font-family', 'font-size', 'font-weight', 'font-style', 'line-height',
+        'text-align', 'text-transform', 'letter-spacing',
+        'padding-top', 'padding-right', 'padding-bottom', 'padding-left',
+        'margin-top', 'margin-right', 'margin-bottom', 'margin-left',
+        'display', 'opacity', 'visibility', 'box-shadow',
+    ];
+    function fnv1a(str) {
+        var h = 0x811c9dc5;
+        for (var i = 0; i < str.length; i++) {
+            h ^= str.charCodeAt(i);
+            h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
+        }
+        return ('0000000' + h.toString(16)).slice(-8);
+    }
+    function segment(el) {
+        var tag = el.tagName.toLowerCase();
+        var cls = '';
+        if (el.classList && el.classList.length > 0) {
+            cls = '.' + el.classList[0];
+        }
+        var parent = el.parentElement;
+        if (!parent)
+            return tag + cls;
+        var sameTag = 0;
+        var index = 0;
+        for (var i = 0; i < parent.children.length; i++) {
+            var sib = parent.children[i];
+            if (sib.tagName === el.tagName) {
+                sameTag++;
+                if (sib === el)
+                    index = sameTag;
+            }
+        }
+        return sameTag > 1 ? tag + cls + ':nth-of-type(' + index + ')' : tag + cls;
+    }
+    function pathOf(el, stopAt) {
+        var parts = [];
+        var node = el;
+        while (node && node !== stopAt.parentElement) {
+            parts.unshift(segment(node));
+            node = node.parentElement;
+        }
+        return parts.join(' > ');
+    }
+    var dpr = win.devicePixelRatio || 1;
+    var scrollX = win.scrollX || 0;
+    var scrollY = win.scrollY || 0;
+    var out = [];
+    var body = doc.body;
+    if (!body)
+        return out;
+    var stack = [body];
+    while (stack.length > 0 && out.length < maxElements) {
+        var el = stack.pop();
+        var rect = el.getBoundingClientRect();
+        if (rect.width >= 4 && rect.height >= 4) {
+            var styleParts = [];
+            try {
+                var cs = win.getComputedStyle(el);
+                for (var p = 0; p < STYLE_PROPS.length; p++) {
+                    styleParts.push(STYLE_PROPS[p] + ':' + cs.getPropertyValue(STYLE_PROPS[p]));
+                }
+            }
+            catch (e) {
+                // styleHash stays a digest of the empty string — still deterministic
+            }
+            out.push({
+                path: pathOf(el, body),
+                x: Math.round((rect.x + scrollX) * dpr),
+                y: Math.round((rect.y + scrollY) * dpr),
+                width: Math.round(rect.width * dpr),
+                height: Math.round(rect.height * dpr),
+                styleHash: fnv1a(styleParts.join(';')),
+            });
+        }
+        // Push children in reverse so the walk stays document-ordered
+        for (var c = el.children.length - 1; c >= 0; c--) {
+            stack.push(el.children[c]);
+        }
+    }
+    return out;
+}
+/** Default element cap — bounds capture time and elements.json size. */
+exports.DEFAULT_MAX_ELEMENTS = 3000;
+/**
+ * The page-side expression evaluated by the adapter. Serializes the
+ * collector so page code and unit-tested code are the same function.
+ */
+function buildElementMapExpression(maxElements = exports.DEFAULT_MAX_ELEMENTS) {
+    return `(${collectElementMap.toString()})(document, window, ${maxElements})`;
+}

package/dist/config/loader.js

@@ -138,7 +138,8 @@ function mergeTestConfig(projectConfig, testConfig) {
         // the selectors (masked for a long time by the diff engine's cumulated
         // threshold absorbing the tiny leaked pixels).
         ignoreSelectors: testConfig.ignoreSelectors,
-        stabilize: testConfig.stabilize
+        stabilize: testConfig.stabilize,
+        mask: testConfig.mask
     };
 }
 /**

package/dist/snapshot.js

@@ -44,6 +44,7 @@ const url_1 = require("url");
 const sharp_1 = __importDefault(require("sharp"));
 const loader_1 = require("./config/loader");
 const ignore_selectors_1 = require("./config/ignore-selectors");
+const element_map_1 = require("./capture/element-map");
 const stabilize_1 = require("./config/stabilize");
 /**
  * Generates a safe filename from a URL.
@@ -408,6 +409,74 @@ async function snapshot(page, testInfo, name, config) {
                 console.warn('[TestivAI] DOM capture failed (noise-hint will be unavailable):', err);
             }
         }
+        // Mask support: record per-call mask specs and capture geometry for
+        // every selector mask (config + per-call) via getBoundingClientRect.
+        // The DOM snapshot carries no layout, so comparison-time selector
+        // masks depend on these rects; when absent, the compare degrades to
+        // a visible warning. Best-effort — never breaks the capture.
+        try {
+            const perCallMasks = effectiveConfig.mask ?? [];
+            const configMaskEntries = readConfigMasks(process.cwd());
+            const selectorMasks = [
+                ...configMaskEntries.filter((m) => typeof m === 'string'),
+                ...perCallMasks.filter((m) => typeof m === 'string'),
+            ];
+            const uniqueSelectors = [...new Set(selectorMasks)];
+            let maskRects = [];
+            if (uniqueSelectors.length > 0) {
+                maskRects = await page.evaluate((selectors) => {
+                    const dpr = window.devicePixelRatio || 1;
+                    const out = [];
+                    for (const sel of selectors) {
+                        try {
+                            document.querySelectorAll(sel).forEach((el) => {
+                                const r = el.getBoundingClientRect();
+                                if (r.width > 0 && r.height > 0) {
+                                    out.push({
+                                        selector: sel,
+                                        x: Math.round((r.x + window.scrollX) * dpr),
+                                        y: Math.round((r.y + window.scrollY) * dpr),
+                                        width: Math.round(r.width * dpr),
+                                        height: Math.round(r.height * dpr),
+                                    });
+                                }
+                            });
+                        }
+                        catch {
+                            // invalid selector — the compare side will warn
+                        }
+                    }
+                    return out;
+                }, uniqueSelectors);
+            }
+            const geometricCallMasks = perCallMasks.filter((m) => typeof m !== 'string');
+            const callSelectorMasks = perCallMasks.filter((m) => typeof m === 'string');
+            if (geometricCallMasks.length > 0 || callSelectorMasks.length > 0 || maskRects.length > 0) {
+                await fs.writeJson(path.join(localSnapshotDir, 'metadata.json'), {
+                    name: snapshotName,
+                    timestamp: new Date(timestamp).toISOString(),
+                    ...(geometricCallMasks.length > 0 ? { masks: geometricCallMasks } : {}),
+                    ...(callSelectorMasks.length > 0 ? { maskSelectors: callSelectorMasks } : {}),
+                    ...(maskRects.length > 0 ? { maskRects } : {}),
+                });
+            }
+        }
+        catch {
+            // metadata is an enhancement; the screenshot path never depends on it
+        }
+        // Element map: layout + computed-style digest for every visible
+        // element, powering attribution ("WHICH element changed"), exact
+        // shift classification, and the style fingerprint on the compare
+        // side. Best-effort — the screenshot path never depends on it.
+        try {
+            const elementMap = await page.evaluate((0, element_map_1.buildElementMapExpression)());
+            if (Array.isArray(elementMap) && elementMap.length > 0) {
+                await fs.writeJson(path.join(localSnapshotDir, 'elements.json'), elementMap);
+            }
+        }
+        catch {
+            // missing elements.json only disables attribution for this capture
+        }
     }
     // 2. Dump page structure (HTML) - skip in local mode
     // @renamed: domPath → structurePath (IP protection)
@@ -709,3 +778,17 @@ async function snapshot(page, testInfo, name, config) {
         structureAnalysis
     });
 }
+/**
+ * Read the global `mask` list from .testivai/config.json (selector strings
+ * and geometric objects). Returns [] when absent or malformed.
+ */
+function readConfigMasks(projectRoot) {
+    try {
+        const raw = fs.readFileSync(path.join(projectRoot, '.testivai', 'config.json'), 'utf-8');
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed?.mask) ? parsed.mask : [];
+    }
+    catch {
+        return [];
+    }
+}

package/dist/types.d.ts

@@ -239,6 +239,18 @@ export interface TestivAIConfig {
      * or in `testivai.config.ts`. Per-snapshot values win.
      */
     stabilize?: boolean;
+    /**
+     * Masks for this snapshot: areas excluded from the pixel diff and
+     * hatched in the report (auditable — never silent). Each entry is a
+     * CSS selector string (geometry recorded at capture time) or a
+     * geometric region — px numbers, 0–1 ratios, "NN%" strings, or a
+     * single-edge shorthand like { top: 24 }.
+     *
+     * Merged with the global `mask` list from `.testivai/config.json`.
+     * Unlike `ignoreSelectors` (which hides elements during capture),
+     * masks act at comparison time and stay visible in the diff output.
+     */
+    mask?: Array<string | Record<string, number | string>>;
 }
 /**
  * Layout/Bounding box data for an element

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testivai/witness-playwright",
-  "version": "1.3.3",
+  "version": "1.5.1",
   "description": "Playwright sensor for Testivai Visual Regression Test system",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -48,7 +48,7 @@
     "sharp": "^0.34.5",
     "simple-git": "^3.21.0",
     "@testivai/common": "0.2.2",
-    "@testivai/witness": "1.3.1"
+    "@testivai/witness": "1.6.0"
   },
   "devDependencies": {
     "@playwright/test": "^1.60.0",