@testivai/witness-playwright 1.5.1 → 1.6.0

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

@@ -27,11 +27,11 @@ export interface CollectedElement {
  * - `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[];
+export declare function collectElementMap(doc: Document, win: Window & typeof globalThis, maxElements: number, ignoreSelectors?: string[]): 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;
+export declare function buildElementMapExpression(maxElements?: number, ignoreSelectors?: string[]): string;

package/dist/capture/element-map.js

@@ -24,7 +24,7 @@ exports.buildElementMapExpression = buildElementMapExpression;
  * - `styleHash` digests a fixed, documented list of computed properties
  *   (FNV-1a 32-bit, hex) — deterministic for identical rendering.
  */
-function collectElementMap(doc, win, maxElements) {
+function collectElementMap(doc, win, maxElements, ignoreSelectors = []) {
     var STYLE_PROPS = [
         'color', 'background-color', 'background-image',
         'border-top-color', 'border-right-color', 'border-bottom-color', 'border-left-color',
@@ -84,26 +84,55 @@ function collectElementMap(doc, win, maxElements) {
     var stack = [body];
     while (stack.length > 0 && out.length < maxElements) {
         var el = stack.pop();
+        // The consistency rule: elements covered by ignoreSelectors are
+        // excluded from pixels and the DOM snapshot — they must be excluded
+        // from the element map too (subtree included), or their dynamic
+        // styles would trip the style fingerprint they were meant to escape.
+        var ignored = false;
+        if (ignoreSelectors.length > 0 && typeof el.matches === 'function') {
+            for (var g = 0; g < ignoreSelectors.length; g++) {
+                try {
+                    if (el.matches(ignoreSelectors[g])) {
+                        ignored = true;
+                        break;
+                    }
+                }
+                catch (e) {
+                    // invalid selector — never breaks the walk
+                }
+            }
+        }
+        if (ignored)
+            continue; // skip element AND subtree
         var rect = el.getBoundingClientRect();
         if (rect.width >= 4 && rect.height >= 4) {
             var styleParts = [];
+            var hidden = false;
             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]));
+                    var value = cs.getPropertyValue(STYLE_PROPS[p]);
+                    if (STYLE_PROPS[p] === 'visibility' && value === 'hidden')
+                        hidden = true;
+                    styleParts.push(STYLE_PROPS[p] + ':' + value);
                 }
             }
             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(';')),
-            });
+            // visibility:hidden elements paint no pixels, so their style changes
+            // can never explain a pixel diff — keep them out of the map. Their
+            // CHILDREN may override visibility, so the subtree still walks.
+            if (!hidden) {
+                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--) {
@@ -118,6 +147,6 @@ 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})`;
+function buildElementMapExpression(maxElements = exports.DEFAULT_MAX_ELEMENTS, ignoreSelectors = []) {
+    return `(${collectElementMap.toString()})(document, window, ${maxElements}, ${JSON.stringify(ignoreSelectors)})`;
 }

package/dist/config/ignore-selectors.d.ts

@@ -1,38 +1,57 @@
 /**
  * Helpers for the ignoreSelectors feature.
  *
- * Three sources, merged with deduplication (last-write-wins dedup via Set):
+ * Three sources, merged with deduplication (first-write-wins via selector key):
  *   1. .testivai/config.json     — global OSS config (`ignoreSelectors` array)
  *   2. testivai.config.ts/js     — power-user project config (`ignoreSelectors`)
  *   3. testivai.witness() call   — per-snapshot override (`ignoreSelectors`)
  *
+ * Each entry is a bare CSS selector string (defaults to `mask` mode) or an
+ * object `{ selector, mode }` where mode is:
+ *   - `mask`     (default) → visibility:hidden — blank the box, keep layout
+ *   - `collapse`           → display:none      — remove layout influence
+ *
  * These functions are pure (no Playwright dependency) so they can be
  * exercised in plain Jest unit tests without a browser.
  */
-import { TestivAIConfig, TestivAIProjectConfig } from '../types';
+import { TestivAIConfig, TestivAIProjectConfig, IgnoreMode, IgnoreSelectorInput } from '../types';
+/** A fully-resolved ignore entry with an explicit mode. */
+export interface IgnoreRule {
+    selector: string;
+    mode: IgnoreMode;
+}
 /**
- * Read ignoreSelectors from `.testivai/config.json`.
- * Returns `[]` when the file doesn't exist or is malformed.
+ * Read raw ignoreSelectors from `.testivai/config.json`.
+ * Returns `[]` when the file doesn't exist, is malformed, or the field is not
+ * an array. Entries are returned as-authored (strings and/or objects).
  *
  * @param projectRoot  Directory that contains the `.testivai/` folder
  */
-export declare function readWitnessConfigSelectors(projectRoot: string): string[];
+export declare function readWitnessConfigSelectors(projectRoot: string): IgnoreSelectorInput[];
 /**
- * Collect and deduplicate ignoreSelectors from all three sources.
- *
- * Order of precedence for deduplication: earlier sources win (Set preserves
- * insertion order, so the first occurrence of any selector survives).
+ * Collect and deduplicate ignore rules (with modes) from all three sources.
+ * Earlier sources win on duplicate selectors (insertion order preserved).
  *
  * @param projectRoot    Path to the project root (where `.testivai/` lives)
  * @param projectConfig  Loaded `testivai.config.ts` project config
  * @param effectiveConfig  Merged per-snapshot TestivAIConfig
  */
+export declare function collectIgnoreRules(projectRoot: string, projectConfig: TestivAIProjectConfig, effectiveConfig: TestivAIConfig): IgnoreRule[];
+/**
+ * Collect and deduplicate ignore selector strings from all three sources.
+ *
+ * Mode-agnostic: returns just the selectors, used where only the "which
+ * elements" question matters (DOM/text signal and the element map exclude
+ * ignored elements regardless of mask vs collapse).
+ */
 export declare function collectIgnoreSelectors(projectRoot: string, projectConfig: TestivAIProjectConfig, effectiveConfig: TestivAIConfig): string[];
 /**
- * Build a `<style>` tag content that hides every given selector via
- * `visibility: hidden !important`.
+ * Build `<style>` content that neutralizes every entry before capture.
+ * `mask` → `visibility: hidden !important` (layout preserved);
+ * `collapse` → `display: none !important` (layout removed).
  *
- * Returns an empty string when the selectors list is empty so callers can
- * guard with `if (css)` before calling `page.addStyleTag`.
+ * Accepts bare strings (treated as `mask`) or resolved rules, so both the raw
+ * config shape and `collectIgnoreRules()` output work. Returns an empty string
+ * for an empty list so callers can guard with `if (css)`.
  */
-export declare function buildIgnoreSelectorsCSS(selectors: string[]): string;
+export declare function buildIgnoreSelectorsCSS(items: Array<IgnoreSelectorInput | IgnoreRule>): string;

package/dist/config/ignore-selectors.js

@@ -2,11 +2,16 @@
 /**
  * Helpers for the ignoreSelectors feature.
  *
- * Three sources, merged with deduplication (last-write-wins dedup via Set):
+ * Three sources, merged with deduplication (first-write-wins via selector key):
  *   1. .testivai/config.json     — global OSS config (`ignoreSelectors` array)
  *   2. testivai.config.ts/js     — power-user project config (`ignoreSelectors`)
  *   3. testivai.witness() call   — per-snapshot override (`ignoreSelectors`)
  *
+ * Each entry is a bare CSS selector string (defaults to `mask` mode) or an
+ * object `{ selector, mode }` where mode is:
+ *   - `mask`     (default) → visibility:hidden — blank the box, keep layout
+ *   - `collapse`           → display:none      — remove layout influence
+ *
  * These functions are pure (no Playwright dependency) so they can be
  * exercised in plain Jest unit tests without a browser.
  */
@@ -45,13 +50,28 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.readWitnessConfigSelectors = readWitnessConfigSelectors;
+exports.collectIgnoreRules = collectIgnoreRules;
 exports.collectIgnoreSelectors = collectIgnoreSelectors;
 exports.buildIgnoreSelectorsCSS = buildIgnoreSelectorsCSS;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+/** Normalize one raw entry to a rule, or null when it's unusable. */
+function toRule(input) {
+    if (typeof input === 'string') {
+        return input ? { selector: input, mode: 'mask' } : null;
+    }
+    if (input && typeof input.selector === 'string' && input.selector) {
+        return {
+            selector: input.selector,
+            mode: input.mode === 'collapse' ? 'collapse' : 'mask',
+        };
+    }
+    return null;
+}
 /**
- * Read ignoreSelectors from `.testivai/config.json`.
- * Returns `[]` when the file doesn't exist or is malformed.
+ * Read raw ignoreSelectors from `.testivai/config.json`.
+ * Returns `[]` when the file doesn't exist, is malformed, or the field is not
+ * an array. Entries are returned as-authored (strings and/or objects).
  *
  * @param projectRoot  Directory that contains the `.testivai/` folder
  */
@@ -68,30 +88,59 @@ function readWitnessConfigSelectors(projectRoot) {
     }
 }
 /**
- * Collect and deduplicate ignoreSelectors from all three sources.
- *
- * Order of precedence for deduplication: earlier sources win (Set preserves
- * insertion order, so the first occurrence of any selector survives).
+ * Collect and deduplicate ignore rules (with modes) from all three sources.
+ * Earlier sources win on duplicate selectors (insertion order preserved).
  *
  * @param projectRoot    Path to the project root (where `.testivai/` lives)
  * @param projectConfig  Loaded `testivai.config.ts` project config
  * @param effectiveConfig  Merged per-snapshot TestivAIConfig
  */
+function collectIgnoreRules(projectRoot, projectConfig, effectiveConfig) {
+    const merged = [
+        ...readWitnessConfigSelectors(projectRoot),
+        ...(projectConfig.ignoreSelectors ?? []),
+        ...(effectiveConfig.ignoreSelectors ?? []),
+    ];
+    const seen = new Set();
+    const rules = [];
+    for (const item of merged) {
+        const rule = toRule(item);
+        if (rule && !seen.has(rule.selector)) {
+            seen.add(rule.selector);
+            rules.push(rule);
+        }
+    }
+    return rules;
+}
+/**
+ * Collect and deduplicate ignore selector strings from all three sources.
+ *
+ * Mode-agnostic: returns just the selectors, used where only the "which
+ * elements" question matters (DOM/text signal and the element map exclude
+ * ignored elements regardless of mask vs collapse).
+ */
 function collectIgnoreSelectors(projectRoot, projectConfig, effectiveConfig) {
-    const fromWitnessConfig = readWitnessConfigSelectors(projectRoot);
-    const fromProjectConfig = projectConfig.ignoreSelectors ?? [];
-    const fromSnapshot = effectiveConfig.ignoreSelectors ?? [];
-    return [...new Set([...fromWitnessConfig, ...fromProjectConfig, ...fromSnapshot])];
+    return collectIgnoreRules(projectRoot, projectConfig, effectiveConfig).map((r) => r.selector);
 }
 /**
- * Build a `<style>` tag content that hides every given selector via
- * `visibility: hidden !important`.
+ * Build `<style>` content that neutralizes every entry before capture.
+ * `mask` → `visibility: hidden !important` (layout preserved);
+ * `collapse` → `display: none !important` (layout removed).
  *
- * Returns an empty string when the selectors list is empty so callers can
- * guard with `if (css)` before calling `page.addStyleTag`.
+ * Accepts bare strings (treated as `mask`) or resolved rules, so both the raw
+ * config shape and `collectIgnoreRules()` output work. Returns an empty string
+ * for an empty list so callers can guard with `if (css)`.
  */
-function buildIgnoreSelectorsCSS(selectors) {
-    if (selectors.length === 0)
-        return '';
-    return selectors.map(s => `${s} { visibility: hidden !important; }`).join('\n');
+function buildIgnoreSelectorsCSS(items) {
+    const lines = [];
+    for (const item of items) {
+        const rule = toRule(item);
+        if (!rule)
+            continue;
+        const decl = rule.mode === 'collapse'
+            ? 'display: none !important;'
+            : 'visibility: hidden !important;';
+        lines.push(`${rule.selector} { ${decl} }`);
+    }
+    return lines.join('\n');
 }

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { snapshot } from './snapshot';
 import { getCiRunId } from './ci';
+export { snapshot };
 export declare const testivai: {
     witness: typeof snapshot;
     ci: typeof getCiRunId;

package/dist/index.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.testivai = void 0;
+exports.testivai = exports.snapshot = void 0;
 const snapshot_1 = require("./snapshot");
+Object.defineProperty(exports, "snapshot", { enumerable: true, get: function () { return snapshot_1.snapshot; } });
 const ci_1 = require("./ci");
 exports.testivai = {
     witness: snapshot_1.snapshot,

package/dist/mode.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Resolve whether the adapter should run in local mode.
+ *
+ * Local-first is the zero-config default: with no API key, the adapter
+ * captures to `.testivai/temp/<name>/` and writes an HTML report — no cloud,
+ * no account, nothing scary. Cloud mode activates only when a key is present.
+ *
+ * Precedence (first match wins):
+ *   1. TESTIVAI_MODE env — explicit override ('local' | 'cloud')
+ *   2. .testivai/config.json `mode` — project default
+ *   3. TESTIVAI_API_KEY presence — key ⇒ cloud, no key ⇒ local
+ *
+ * This is deliberately derivable from the shell environment and the config
+ * file alone, so it resolves identically in the Playwright main process (the
+ * reporter) and in worker processes (the `snapshot()` capture) — env vars set
+ * at runtime by the reporter never propagate to already-spawned workers.
+ */
+export declare function resolveLocalMode(opts?: {
+    apiKey?: string;
+    projectRoot?: string;
+}): boolean;

package/dist/mode.js

@@ -0,0 +1,84 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveLocalMode = resolveLocalMode;
+const fs = __importStar(require("fs-extra"));
+const path = __importStar(require("path"));
+/**
+ * Read `mode` from .testivai/config.json. Returns null when the file is
+ * absent, malformed, or has no recognized mode field.
+ */
+function configMode(projectRoot) {
+    try {
+        const cfg = fs.readJsonSync(path.join(projectRoot, '.testivai', 'config.json'));
+        if (cfg?.mode === 'local')
+            return 'local';
+        if (cfg?.mode === 'cloud')
+            return 'cloud';
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve whether the adapter should run in local mode.
+ *
+ * Local-first is the zero-config default: with no API key, the adapter
+ * captures to `.testivai/temp/<name>/` and writes an HTML report — no cloud,
+ * no account, nothing scary. Cloud mode activates only when a key is present.
+ *
+ * Precedence (first match wins):
+ *   1. TESTIVAI_MODE env — explicit override ('local' | 'cloud')
+ *   2. .testivai/config.json `mode` — project default
+ *   3. TESTIVAI_API_KEY presence — key ⇒ cloud, no key ⇒ local
+ *
+ * This is deliberately derivable from the shell environment and the config
+ * file alone, so it resolves identically in the Playwright main process (the
+ * reporter) and in worker processes (the `snapshot()` capture) — env vars set
+ * at runtime by the reporter never propagate to already-spawned workers.
+ */
+function resolveLocalMode(opts = {}) {
+    const envMode = process.env.TESTIVAI_MODE;
+    if (envMode === 'local')
+        return true;
+    if (envMode === 'cloud')
+        return false;
+    const cfg = configMode(opts.projectRoot ?? process.cwd());
+    if (cfg)
+        return cfg === 'local';
+    const apiKey = opts.apiKey ?? process.env.TESTIVAI_API_KEY;
+    return !apiKey;
+}

package/dist/reporter.js

@@ -43,22 +43,7 @@ const simple_git_1 = __importDefault(require("simple-git"));
 const axios_1 = __importDefault(require("axios"));
 const ci_1 = require("./ci");
 const common_1 = require("@testivai/common");
-/**
- * Check if local mode is configured by looking for .testivai/config.json with mode: 'local'
- */
-function isLocalMode() {
-    try {
-        const configPath = path.join(process.cwd(), '.testivai', 'config.json');
-        if (!fs.existsSync(configPath)) {
-            return false;
-        }
-        const config = fs.readJsonSync(configPath);
-        return config.mode === 'local';
-    }
-    catch {
-        return false;
-    }
-}
+const mode_1 = require("./mode");
 class TestivAIPlaywrightReporter {
     constructor(options = {}) {
         this.gitInfo = null;
@@ -77,21 +62,18 @@ class TestivAIPlaywrightReporter {
         this.compressionHelper = new common_1.CompressionHelper(this.options.compression);
     }
     async onBegin(config, suite) {
-        // Check for local mode first
-        this.localMode = isLocalMode();
+        // Resolve mode. Local-first is the default: with no API key we capture
+        // and report locally rather than disabling the reporter. Cloud mode
+        // activates only when a key is present (or config/env force it).
+        this.localMode = (0, mode_1.resolveLocalMode)({ apiKey: this.options.apiKey });
         if (this.localMode) {
             process.env.TESTIVAI_MODE = 'local';
-            if (this.options.debug) {
-                console.log('Testivai Reporter: [DEBUG] Local mode detected, skipping API key validation');
+            // One quiet, friendly line — not a scary "disabling reporter" error.
+            if (!this.options.apiKey && !process.env.TESTIVAI_MODE_ANNOUNCED) {
+                console.log('TestivAI: no API key set — running in local mode (report → visual-report/index.html).');
+                process.env.TESTIVAI_MODE_ANNOUNCED = '1';
             }
         }
-        // API key is only required in cloud mode
-        if (!this.localMode && !this.options.apiKey) {
-            console.error('Testivai Reporter: API Key is not configured. Disabling reporter.');
-            console.error('Set TESTIVAI_API_KEY environment variable or pass apiKey in reporter options.');
-            this.options.apiUrl = undefined; // Disable reporter
-            return;
-        }
         // 1. Clean temp directory
         await fs.emptyDir(this.tempDir);
         // 2. Capture Git metadata

package/dist/snapshot.js

@@ -46,6 +46,7 @@ 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");
+const mode_1 = require("./mode");
 /**
  * Generates a safe filename from a URL.
  * @param pageUrl The URL of the page.
@@ -97,8 +98,11 @@ function effectiveSnapshotName(baseName, testInfo) {
  * @param config Optional TestivAI configuration for this snapshot (overrides project defaults).
  */
 async function snapshot(page, testInfo, name, config) {
-    // Check for local mode - only capture screenshots, skip heavy data
-    const isLocalMode = process.env.TESTIVAI_MODE === 'local';
+    // Check for local mode - only capture screenshots, skip heavy data.
+    // Resolved from the shell env + config so it agrees with the reporter even
+    // though this runs in a Playwright worker (the reporter's runtime env writes
+    // never reach workers). Default: local unless a TESTIVAI_API_KEY is present.
+    const isLocalMode = (0, mode_1.resolveLocalMode)();
     // Load project configuration and merge with test-specific overrides
     const projectConfig = await (0, loader_1.loadConfig)();
     const effectiveConfig = (0, loader_1.mergeTestConfig)(projectConfig, config);
@@ -127,8 +131,10 @@ async function snapshot(page, testInfo, name, config) {
     //   3. testivai.witness(...)  → { ignoreSelectors } (per-snapshot override)
     let ignoreStyleEl = null;
     if (isLocalMode) {
-        const allSelectors = (0, ignore_selectors_1.collectIgnoreSelectors)(process.cwd(), projectConfig, effectiveConfig);
-        const css = (0, ignore_selectors_1.buildIgnoreSelectorsCSS)(allSelectors);
+        // Rules carry per-selector mode: mask (visibility:hidden, layout kept) or
+        // collapse (display:none, layout removed — fixes variable-height shift).
+        const ignoreRules = (0, ignore_selectors_1.collectIgnoreRules)(process.cwd(), projectConfig, effectiveConfig);
+        const css = (0, ignore_selectors_1.buildIgnoreSelectorsCSS)(ignoreRules);
         if (css) {
             ignoreStyleEl = await page.addStyleTag({ content: css });
         }
@@ -385,7 +391,12 @@ async function snapshot(page, testInfo, name, config) {
     if (isLocalMode) {
         const localSnapshotDir = path.join(outputDir, snapshotName);
         await fs.ensureDir(localSnapshotDir);
-        await fs.copyFile(screenshotPath, path.join(localSnapshotDir, 'screenshot.png'));
+        // Move (not copy) the flat capture into the canonical <name>/ layout so
+        // local mode leaves exactly one on-disk representation — no stray
+        // <timestamp>_<name>.png alongside it. The flat metadata .json is also
+        // skipped in local mode (see below); the local report reads the <name>/
+        // directory, not the flat files.
+        await fs.move(screenshotPath, path.join(localSnapshotDir, 'screenshot.png'), { overwrite: true });
         try {
             const domIgnoreSelectors = (0, ignore_selectors_1.collectIgnoreSelectors)(process.cwd(), projectConfig, effectiveConfig);
             const domHtml = await page.evaluate((selectors) => {
@@ -469,7 +480,8 @@ async function snapshot(page, testInfo, name, config) {
         // 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)());
+            const mapIgnores = (0, ignore_selectors_1.collectIgnoreSelectors)(process.cwd(), projectConfig, effectiveConfig);
+            const elementMap = await page.evaluate((0, element_map_1.buildElementMapExpression)(undefined, mapIgnores));
             if (Array.isArray(elementMap) && elementMap.length > 0) {
                 await fs.writeJson(path.join(localSnapshotDir, 'elements.json'), elementMap);
             }
@@ -751,32 +763,37 @@ async function snapshot(page, testInfo, name, config) {
     // The SDK just captures the HTML and sends it with the configuration
     // @renamed: domAnalysis → structureAnalysis (IP protection)
     const structureAnalysis = isLocalMode ? undefined : undefined; // Will be populated by backend
-    // 6. Save metadata with configuration and performance data
-    const metadataPath = path.join(outputDir, `${baseFilename}.json`);
-    const metadata = {
-        snapshotName,
-        testName: testInfo.title,
-        timestamp,
-        url: page.url(),
-        viewport: page.viewportSize() || undefined,
-    };
-    await fs.writeJson(metadataPath, {
-        ...metadata,
-        files: {
-            screenshot: screenshotPath,
-            // @renamed: dom → structure, css → styles (IP protection)
-            structure: structurePath,
-            styles: stylesPath,
-        },
-        layout,
-        // Store the effective configuration for the reporter
-        testivaiConfig: effectiveConfig,
-        // Store unified performance metrics if captured
-        performanceMetrics,
-        // Store structure analysis if captured
-        // @renamed: domAnalysis → structureAnalysis (IP protection)
-        structureAnalysis
-    });
+    // 6. Save metadata with configuration and performance data.
+    //    Cloud mode only: the flat <timestamp>_<name>.json is the upload
+    //    manifest the reporter reads. Local mode has no flat files — its report
+    //    is generated from the canonical .testivai/temp/<name>/ directory.
+    if (!isLocalMode) {
+        const metadataPath = path.join(outputDir, `${baseFilename}.json`);
+        const metadata = {
+            snapshotName,
+            testName: testInfo.title,
+            timestamp,
+            url: page.url(),
+            viewport: page.viewportSize() || undefined,
+        };
+        await fs.writeJson(metadataPath, {
+            ...metadata,
+            files: {
+                screenshot: screenshotPath,
+                // @renamed: dom → structure, css → styles (IP protection)
+                structure: structurePath,
+                styles: stylesPath,
+            },
+            layout,
+            // Store the effective configuration for the reporter
+            testivaiConfig: effectiveConfig,
+            // Store unified performance metrics if captured
+            performanceMetrics,
+            // Store structure analysis if captured
+            // @renamed: domAnalysis → structureAnalysis (IP protection)
+            structureAnalysis
+        });
+    }
 }
 /**
  * Read the global `mask` list from .testivai/config.json (selector strings

package/dist/types.d.ts

@@ -6,6 +6,23 @@
  * - BatchPayload: Git + Browser info + collection of snapshots
  * - TestivAIConfig: Configuration for visual analysis behavior
  */
+/**
+ * How an ignored selector is neutralized before capture:
+ * - `mask`     — `visibility: hidden` (default): the box is blanked but keeps
+ *                its layout, so surrounding elements don't shift.
+ * - `collapse` — `display: none`: the element is removed from layout entirely,
+ *                so variable-height ignored content (e.g. a dynamic footer)
+ *                stops shifting everything below it.
+ */
+export type IgnoreMode = 'mask' | 'collapse';
+/**
+ * An ignoreSelectors entry: a plain CSS selector string (defaults to `mask`
+ * mode), or an object choosing the mode per selector.
+ */
+export type IgnoreSelectorInput = string | {
+    selector: string;
+    mode?: IgnoreMode;
+};
 /**
  * Layout configuration for visual analysis
  */
@@ -228,8 +245,12 @@ export interface TestivAIConfig {
      * Per-snapshot values are merged with (not replaced by) the global list.
      *
      * Example: ["[data-testivai-ignore]", ".version-badge", "#live-chat-widget"]
+     *
+     * Entries may also be objects to choose a per-selector mode, e.g.
+     * [{ selector: "#footer", mode: "collapse" }] to remove layout influence.
+     * A bare string defaults to "mask" (visibility:hidden, layout preserved).
      */
-    ignoreSelectors?: string[];
+    ignoreSelectors?: IgnoreSelectorInput[];
     /**
      * Stabilize the page before capture: disable CSS animations/transitions,
      * hide the text caret, and wait for web fonts to finish loading — the top

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testivai/witness-playwright",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "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.6.0"
+    "@testivai/witness": "1.7.0"
   },
   "devDependencies": {
     "@playwright/test": "^1.60.0",