@applitools/eyes-results 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.2.3](https://github.com/Applitools-Dev/sdk/compare/js/eyes-results@0.2.2...js/eyes-results@0.2.3) (2026-09-10)
+
+
+### Bug Fixes
+
+* replace overlapping match regions and refuse no-op or dynamic masks | AD-15903 ([#4163](https://github.com/Applitools-Dev/sdk/issues/4163)) ([78bdcf1](https://github.com/Applitools-Dev/sdk/commit/78bdcf10aa321252fcd613a685e9a8749a8215ce))
+
+## [0.2.2](https://github.com/Applitools-Dev/sdk/compare/js/eyes-results@0.2.1...js/eyes-results@0.2.2) (2026-08-25)
+
+
+### Bug Fixes
+
+* discover the project .env so the family read/write keys resolve | AD-15678 ([#4131](https://github.com/Applitools-Dev/sdk/issues/4131)) ([316f39f](https://github.com/Applitools-Dev/sdk/commit/316f39fd15fd516b3d266b8aa8deccddfabd0921))
+
 ## [0.2.1](https://github.com/Applitools-Dev/sdk/compare/js/eyes-results@0.2.0...js/eyes-results@0.2.1) (2026-08-24)
 
 

package/dist/api/url-parsing.js

@@ -49,8 +49,7 @@ export function parseApplitoolsUrl(url) {
 export function parseSessionUrl(url) {
     const parsed = parseApplitoolsUrl(url);
     if (!parsed.sessionId) {
-        throw new Error('The input URL is a batch URL while a session URL is expected. ' +
-            'Use the eyes_fetch_visual_results MCP tool to obtain URLs of sessions in this batch.');
+        throw new Error('The input URL is a batch URL while a session URL is expected.');
     }
     return parsed;
 }

package/dist/geometry/geometry.js

@@ -45,7 +45,42 @@ export function padRect(rect, padding, imageWidth = Infinity, imageHeight = Infi
     const bottom = Math.min(imageHeight, rect.top + rect.height + padding);
     return { left, top, width: right - left, height: bottom - top };
 }
-/** Merges pairs of rects that overlap by more than 10% of the smaller rect's area. */
+/** A region under this covers a diff artefact, not content, and as a search source it matches almost everywhere. */
+export const MIN_REGION_AREA_PX = 16;
+export function isTooSmallRegion(rect) {
+    return rect.width * rect.height < MIN_REGION_AREA_PX;
+}
+export function sameRect(a, b) {
+    return a.left === b.left && a.top === b.top && a.width === b.width && a.height === b.height;
+}
+/** Intersection area as a fraction of the smaller rect's area — IoU would punish a thin rect for a few px of drift. */
+export function overlapCoverage(a, b) {
+    const smaller = Math.min(a.width * a.height, b.width * b.height);
+    // A rect with no area covers nothing, and would divide by zero.
+    if (smaller === 0)
+        return 0;
+    return intersectionArea(a, b) / smaller;
+}
+/** Below this, two rects merely graze each other at the edges and are treated as unrelated. */
+export const SIGNIFICANT_OVERLAP_MIN_FRACTION = 0.1;
+/** Below this on either axis the two rects are different shapes, however much they overlap. */
+export const SIMILAR_SIZE_MIN_RATIO = 0.85;
+export const SIMILAR_COVERAGE_MIN_FRACTION = 0.7;
+export function isSignificantOverlap(a, b) {
+    return rectsIntersect(a, b) && overlapCoverage(a, b) > SIGNIFICANT_OVERLAP_MIN_FRACTION;
+}
+/**
+ * Similar size on both axes and mostly overlapping: one rect is the other after a drift of a few px.
+ * A rect that moved a whole row away shares no area with where it was, so it is not nearly the same.
+ */
+export function isNearlySameRect(a, b) {
+    if (!isSignificantOverlap(a, b))
+        return false;
+    const ratio = (x, y) => Math.min(x, y) / Math.max(x, y);
+    const sizeRatio = Math.min(ratio(a.width, b.width), ratio(a.height, b.height));
+    return sizeRatio >= SIMILAR_SIZE_MIN_RATIO && overlapCoverage(a, b) >= SIMILAR_COVERAGE_MIN_FRACTION;
+}
+/** Merges pairs of rects that overlap by more than `SIGNIFICANT_OVERLAP_MIN_FRACTION` of the smaller rect's area. */
 export function unifyRects(rects) {
     let result = [...rects];
     let merged = true;
@@ -53,9 +88,7 @@ export function unifyRects(rects) {
         merged = false;
         outer: for (let i = 0; i < result.length; i++) {
             for (let j = i + 1; j < result.length; j++) {
-                const overlap = intersectionArea(result[i], result[j]);
-                const smallerArea = Math.min(result[i].width * result[i].height, result[j].width * result[j].height);
-                if (overlap / smallerArea > 0.1) {
+                if (isSignificantOverlap(result[i], result[j])) {
                     result = [
                         ...result.slice(0, i),
                         ...result.slice(i + 1, j),

package/dist/lib/env.js

@@ -5,22 +5,20 @@ export const defaultLoadEnvDeps = {
     existsSync: fs.existsSync,
     configDotenv: dotenv.config,
 };
-/**
- * Walks up from `startDir` (default: the current working directory) looking for a `.env`
- * file, loading the first one found via `dotenv`. Mirrors the behavior every skill's own
- * `main.ts` used to inline directly.
- */
 export function loadEnvFromCwd(startDir = process.cwd(), deps = defaultLoadEnvDeps) {
     let dir = startDir;
     while (true) {
         const envPath = path.join(dir, '.env');
         if (deps.existsSync(envPath)) {
-            deps.configDotenv({ path: envPath });
-            return;
+            const preset = new Set(Object.keys(process.env));
+            const result = deps.configDotenv({ path: envPath });
+            const parsed = result?.parsed ?? {};
+            const applied = Object.keys(parsed).filter(name => !preset.has(name));
+            return { path: envPath, applied, parsed };
         }
         const parent = path.dirname(dir);
         if (parent === dir)
-            return;
+            return undefined;
         dir = parent;
     }
 }

package/dist/sessions/dom.js

@@ -1,4 +1,4 @@
-import { rectsIntersect, rectContains } from '../geometry/geometry.js';
+import { rectsIntersect, rectContains, isNearlySameRect } from '../geometry/geometry.js';
 /**
  * Extracts the bounding rect from an Applitools DOM snapshot node.
  * Returns null if the node has no rect or its values are not numbers.
@@ -295,17 +295,15 @@ export function resolveNodeIdsToNodes(root, nodeIds) {
     return result;
 }
 /**
- * Finds the element node in `root` whose rect most closely matches `targetRect` — within
- * `tolerancePx` on all four of left/top/width/height — returning the same {domSelector,
- * rect} shape as `findNodeById`. Lets a caller upgrade a raw pixel rect (e.g. one eyeballed off
- * a screenshot) into a domSelector-backed region when a matching element actually exists,
- * so the region tracks that element rather than a fixed set of pixels. Returns `null` if no
- * node is within tolerance. When multiple nodes qualify (e.g. a wrapper and its one child
- * share nearly the same rect), the one with the smallest total deviation wins.
+ * The element `targetRect` denotes: a match within `tolerancePx` on every edge, else the element
+ * whose box is nearly the same rect — a changed-area rect bounds the differing pixels, which rarely
+ * lands within a few px of the element's own box. Within a tier the smallest total deviation wins.
  */
 export function findNodeByRect(root, targetRect, tolerancePx = 5) {
-    let best = null;
-    let bestDelta = Infinity;
+    let exact = null;
+    let exactDelta = Infinity;
+    let shifted = null;
+    let shiftedDelta = Infinity;
     for (const { node } of flattenTree(root)) {
         const r = nodeRect(node);
         if (!r)
@@ -314,15 +312,20 @@ export function findNodeByRect(root, targetRect, tolerancePx = 5) {
         const dTop = Math.abs(r.top - targetRect.top);
         const dWidth = Math.abs(r.width - targetRect.width);
         const dHeight = Math.abs(r.height - targetRect.height);
-        if (dLeft > tolerancePx || dTop > tolerancePx || dWidth > tolerancePx || dHeight > tolerancePx)
-            continue;
         const delta = dLeft + dTop + dWidth + dHeight;
-        if (delta < bestDelta) {
-            bestDelta = delta;
-            best = node;
+        if (dLeft <= tolerancePx && dTop <= tolerancePx && dWidth <= tolerancePx && dHeight <= tolerancePx) {
+            if (delta < exactDelta) {
+                exactDelta = delta;
+                exact = node;
+            }
+        }
+        else if (isNearlySameRect(r, targetRect) && delta < shiftedDelta) {
+            shiftedDelta = delta;
+            shifted = node;
         }
     }
-    return best ? findNodeById(root, best.id) : null;
+    const found = exact ?? shifted;
+    return found ? findNodeById(root, found.id) : null;
 }
 // ---------------------------------------------------------------------------
 // Reading-order sort

package/dist/sessions/match.js

@@ -38,7 +38,9 @@ function pickCategories(bucket) {
  *   `appOutputResolution[stepIndex].annotations` if a resolution exists, else
  *   `expectedAppOutput[stepIndex].annotations` (the baseline's own regions) — since
  *   `imageMatchSettings`'s own arrays only reflect what was true when the test last ran, not any
- *   region a reviewer added since.
+ *   region a reviewer added since. The coded regions among them (`regionId`) stay in those arrays
+ *   ahead of the annotations: the compare endpoint applies the arrays and not `identifiedRegions`,
+ *   so leaving them out reports diffs inside regions the real match never checks.
  *
  * No baseline/checkpoint side-picking or healing happens here: the raw session already resolves
  * which side a region describes (see `regions.ts`'s `getEffectiveRegions`, used instead for a
@@ -48,9 +50,30 @@ function pickCategories(bucket) {
 export function getEffectiveMatchSettings(rawSession, stepIndex) {
     const imageMatchSettings = rawSession?.actualAppOutput?.[stepIndex]?.imageMatchSettings ?? {};
     const annotations = rawSession?.appOutputResolution?.[stepIndex]?.annotations ?? rawSession?.expectedAppOutput?.[stepIndex]?.annotations;
-    return {
-        ...imageMatchSettings,
-        ...pickCategories(annotations),
-        identifiedRegions: pickCategories(imageMatchSettings),
-    };
+    const coded = pickCategories(imageMatchSettings);
+    const annotated = pickCategories(annotations);
+    const regions = {};
+    for (const category of MATCH_SETTINGS_CATEGORIES) {
+        regions[category] = [...coded[category].filter(isCodedRegion), ...annotated[category]];
+    }
+    return { ...imageMatchSettings, ...regions, identifiedRegions: coded };
 }
+function isCodedRegion(region) {
+    return typeof region.regionId === 'string' && region.regionId !== '';
+}
+/**
+ * The five match levels a match region can name — a subset of `MATCH_SETTINGS_CATEGORIES`, ordered
+ * as the `regionOp` wire syntax and the MCP tool schemas list them.
+ */
+export const REGION_TYPES = ['ignore', 'strict', 'ignorecolors', 'dynamic', 'layout'];
+/**
+ * Higher masks less: `strict` checks almost everything, `ignore` checks nothing. Read to refuse a
+ * replacement that would leave a region weaker than it was.
+ */
+export const REGION_TYPE_STRENGTH = {
+    ignore: 0,
+    layout: 1,
+    dynamic: 2,
+    ignorecolors: 3,
+    strict: 4,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applitools/eyes-results",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Applitools Eyes REST plumbing, DOM diffing, and session/batch shaping",
   "keywords": [
     "applitools",

package/types/geometry/geometry.d.ts

@@ -20,5 +20,22 @@ export declare function boundingRect(a: Rect, b: Rect): Rect;
  * When `imageWidth`/`imageHeight` are provided the result is clipped to the image bounds.
  */
 export declare function padRect(rect: Rect, padding: number, imageWidth?: number, imageHeight?: number): Rect;
-/** Merges pairs of rects that overlap by more than 10% of the smaller rect's area. */
+/** A region under this covers a diff artefact, not content, and as a search source it matches almost everywhere. */
+export declare const MIN_REGION_AREA_PX = 16;
+export declare function isTooSmallRegion(rect: Rect): boolean;
+export declare function sameRect(a: Rect, b: Rect): boolean;
+/** Intersection area as a fraction of the smaller rect's area — IoU would punish a thin rect for a few px of drift. */
+export declare function overlapCoverage(a: Rect, b: Rect): number;
+/** Below this, two rects merely graze each other at the edges and are treated as unrelated. */
+export declare const SIGNIFICANT_OVERLAP_MIN_FRACTION = 0.1;
+/** Below this on either axis the two rects are different shapes, however much they overlap. */
+export declare const SIMILAR_SIZE_MIN_RATIO = 0.85;
+export declare const SIMILAR_COVERAGE_MIN_FRACTION = 0.7;
+export declare function isSignificantOverlap(a: Rect, b: Rect): boolean;
+/**
+ * Similar size on both axes and mostly overlapping: one rect is the other after a drift of a few px.
+ * A rect that moved a whole row away shares no area with where it was, so it is not nearly the same.
+ */
+export declare function isNearlySameRect(a: Rect, b: Rect): boolean;
+/** Merges pairs of rects that overlap by more than `SIGNIFICANT_OVERLAP_MIN_FRACTION` of the smaller rect's area. */
 export declare function unifyRects(rects: Rect[]): Rect[];

package/types/lib/env.d.ts

@@ -6,9 +6,9 @@ export interface LoadEnvDeps {
     }) => unknown;
 }
 export declare const defaultLoadEnvDeps: LoadEnvDeps;
-/**
- * Walks up from `startDir` (default: the current working directory) looking for a `.env`
- * file, loading the first one found via `dotenv`. Mirrors the behavior every skill's own
- * `main.ts` used to inline directly.
- */
-export declare function loadEnvFromCwd(startDir?: string, deps?: LoadEnvDeps): void;
+export interface LoadedEnv {
+    path: string;
+    applied: string[];
+    parsed: Record<string, string>;
+}
+export declare function loadEnvFromCwd(startDir?: string, deps?: LoadEnvDeps): LoadedEnv | undefined;

package/types/sessions/dom.d.ts

@@ -90,13 +90,9 @@ export declare function findNodeBySelector(root: PrunedDom, path: string): DomNo
  */
 export declare function resolveNodeIdsToNodes(root: PrunedDom, nodeIds: string[]): Map<string, DomNode>;
 /**
- * Finds the element node in `root` whose rect most closely matches `targetRect` — within
- * `tolerancePx` on all four of left/top/width/height — returning the same {domSelector,
- * rect} shape as `findNodeById`. Lets a caller upgrade a raw pixel rect (e.g. one eyeballed off
- * a screenshot) into a domSelector-backed region when a matching element actually exists,
- * so the region tracks that element rather than a fixed set of pixels. Returns `null` if no
- * node is within tolerance. When multiple nodes qualify (e.g. a wrapper and its one child
- * share nearly the same rect), the one with the smallest total deviation wins.
+ * The element `targetRect` denotes: a match within `tolerancePx` on every edge, else the element
+ * whose box is nearly the same rect — a changed-area rect bounds the differing pixels, which rarely
+ * lands within a few px of the element's own box. Within a tier the smallest total deviation wins.
  */
 export declare function findNodeByRect(root: PrunedDom, targetRect: Rect, tolerancePx?: number): DomNode | null;
 export interface FlatNode {

package/types/sessions/match.d.ts

@@ -62,7 +62,9 @@ export interface ImageMatchSettings {
  *   `appOutputResolution[stepIndex].annotations` if a resolution exists, else
  *   `expectedAppOutput[stepIndex].annotations` (the baseline's own regions) — since
  *   `imageMatchSettings`'s own arrays only reflect what was true when the test last ran, not any
- *   region a reviewer added since.
+ *   region a reviewer added since. The coded regions among them (`regionId`) stay in those arrays
+ *   ahead of the annotations: the compare endpoint applies the arrays and not `identifiedRegions`,
+ *   so leaving them out reports diffs inside regions the real match never checks.
  *
  * No baseline/checkpoint side-picking or healing happens here: the raw session already resolves
  * which side a region describes (see `regions.ts`'s `getEffectiveRegions`, used instead for a
@@ -70,3 +72,14 @@ export interface ImageMatchSettings {
  * effect, relayed as-is, by reference.
  */
 export declare function getEffectiveMatchSettings(rawSession: any, stepIndex: number): ImageMatchSettings;
+/**
+ * The five match levels a match region can name — a subset of `MATCH_SETTINGS_CATEGORIES`, ordered
+ * as the `regionOp` wire syntax and the MCP tool schemas list them.
+ */
+export declare const REGION_TYPES: readonly ["ignore", "strict", "ignorecolors", "dynamic", "layout"];
+export type RegionType = (typeof REGION_TYPES)[number];
+/**
+ * Higher masks less: `strict` checks almost everything, `ignore` checks nothing. Read to refuse a
+ * replacement that would leave a region weaker than it was.
+ */
+export declare const REGION_TYPE_STRENGTH: Record<RegionType, number>;