@applitools/eyes-results 0.2.0

package/dist/sessions/dom.js

@@ -0,0 +1,513 @@
+import { rectsIntersect, rectContains } 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.
+ */
+export function nodeRect(node) {
+    const r = node?.rect;
+    if (!r)
+        return null;
+    const { left, top, width, height } = r;
+    if (typeof left !== 'number' || typeof top !== 'number' || typeof width !== 'number' || typeof height !== 'number')
+        return null;
+    return { left, top, width, height };
+}
+/**
+ * How many times larger than the tightest container an ancestor's area may be
+ * before it is reduced to a summary node (tagName + attributes only).
+ * Ancestors within this factor are kept in full because they are likely part of
+ * the direct component structure immediately surrounding the diff.
+ */
+const ANCESTOR_SIMILARITY_FACTOR = 5;
+/**
+ * Internal recursive implementation. Returns the pruned node alongside the pixel area
+ * of the tightest container found in the subtree, so ancestors can decide whether they
+ * are "similar in size" and should be kept in full, or are distant and should be summarised.
+ */
+function getDomAreaInternal(node, area) {
+    if (!node)
+        return { nodes: [], tightestContainerArea: 0 };
+    // Non-element nodes (text "#text", comment "#comment", etc.) have no rect.
+    // Pass them through — they survive only if their parent element is retained.
+    if (!node.tagName || node.tagName.startsWith('#'))
+        return { nodes: [node], tightestContainerArea: 0 };
+    // Process children. Only retained element children vote on retention; text nodes
+    // ride along. Track the largest tightestContainerArea reported by any child.
+    let retainedElementCount = 0;
+    const prunedChildren = [];
+    let childTightestArea = 0;
+    for (const child of node.childNodes ?? []) {
+        if (child?.tagName && !child.tagName.startsWith('#')) {
+            const result = getDomAreaInternal(child, area);
+            if (result.nodes.length > 0) {
+                prunedChildren.push(...result.nodes);
+                retainedElementCount++;
+                if (result.tightestContainerArea > childTightestArea) {
+                    childTightestArea = result.tightestContainerArea;
+                }
+            }
+        }
+        else {
+            if (child != null)
+                prunedChildren.push(child);
+        }
+    }
+    const r = nodeRect(node);
+    const selfIntersects = r !== null && rectsIntersect(r, area);
+    if (!selfIntersects && retainedElementCount === 0)
+        return { nodes: [], tightestContainerArea: 0 };
+    const nodeArea = r !== null ? r.width * r.height : 0;
+    const diffArea = area.width * area.height;
+    // A "container" strictly contains the area and is larger (equal-size nodes are
+    // treated as directly intersecting via selfIntersects above).
+    const isContainer = r !== null && rectContains(r, area) && nodeArea > diffArea;
+    // The "tightest container" is the innermost one: it contains the area but no
+    // retained child does. This is the most useful ancestor for source code correlation.
+    const isTightestContainer = isContainer && childTightestArea === 0;
+    const tightestContainerArea = isTightestContainer ? nodeArea : childTightestArea;
+    // Nodes that overlap the diff area without fully containing it are treated as direct
+    // neighbours of the change and always kept in full (rule 1).
+    // Nodes that contain the diff area may still be summarised if they are large enough.
+    const overlapsWithoutContaining = selfIntersects && !isContainer;
+    // A node is a distant ancestor when:
+    //   - not a direct neighbour (overlaps without containing)
+    //   - not the tightest container
+    //   - either has no meaningful pixel area, or is much larger than the tightest container
+    // Distant ancestors are skipped entirely; their retained children are promoted up.
+    const isDistantAncestor = !overlapsWithoutContaining &&
+        !isTightestContainer &&
+        (nodeArea === 0 || (tightestContainerArea > 0 && nodeArea > ANCESTOR_SIMILARITY_FACTOR * tightestContainerArea));
+    if (isDistantAncestor) {
+        return { nodes: prunedChildren, tightestContainerArea };
+    }
+    return { nodes: [{ ...node, childNodes: prunedChildren }], tightestContainerArea };
+}
+/**
+ * Recursively crops a PrunedDom tree to only the branches relevant to the given area.
+ *
+ * Retention rules:
+ *   1. Nodes that overlap the area without fully containing it get full detail — they are
+ *      direct neighbours of the change.
+ *   2. The tightest container (innermost ancestor whose rect strictly contains the area,
+ *      with no retained child also containing it) gets full detail.
+ *   3. Ancestors within ANCESTOR_SIMILARITY_FACTOR× the tightest container's pixel area
+ *      get full detail — they are likely part of the immediate component structure.
+ *   4. All other (distant) ancestors are skipped entirely; their retained children are
+ *      promoted up, so the output starts at the innermost relevant node.
+ *   - Text/comment nodes ("#text", "#comment") are passed through with their parent.
+ *   - Returns null if no node in the tree intersects the area.
+ */
+export function getDomArea(node, area) {
+    const { nodes } = getDomAreaInternal(node, area);
+    if (nodes.length === 0)
+        return null;
+    if (nodes.length === 1)
+        return nodes[0];
+    return nodes;
+}
+/**
+ * Validates that a domId is usable. Returns an error string if not, null if valid.
+ * Guards against passing the literal string "null" copied from `info` JSON output.
+ */
+export function validateDomId(domId) {
+    if (!domId || domId === 'null') {
+        return 'This step has no DOM capture (domId is null). DOM snapshots are only available for steps captured with the Applitools SDK DOM capture feature enabled.';
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Node ids
+// ---------------------------------------------------------------------------
+//
+// A short, LLM-safe id embedded on every element node's top-level `id` field (a sibling of
+// `tagName`/`rect`/`attributes`) so the model can reference a specific node unambiguously
+// (e.g. "node 14") instead of guessing a locator. Assignment happens once, upstream of this
+// package (server-side, see api's fetchPrunedDom), against the full unpruned tree — dom itself only
+// provides the assignment function and the lookup. See atoms/README.md's "Node ids" section for the full rationale.
+/**
+ * Assigns a sequential, 1-based id to every element node as a top-level `id` field, via a
+ * pre-order DFS over `root`. Mutates nodes in place.
+ *
+ * Must be called against the full, unpruned tree so a node's id is stable no matter
+ * what area a later `dom`/`dom-diff` call happens to crop to.
+ */
+export function assignNodeIds(root) {
+    let counter = 0;
+    function visit(node) {
+        if (!node)
+            return;
+        if (Array.isArray(node)) {
+            for (const n of node)
+                visit(n);
+            return;
+        }
+        if (!node.tagName || node.tagName.startsWith('#'))
+            return;
+        counter++;
+        node.id = String(counter);
+        for (const child of node.childNodes ?? [])
+            visit(child);
+    }
+    visit(root);
+}
+// The DOM API uppercases `tagName` for HTML-namespace elements regardless of source
+// casing, but preserves the as-authored case for everything else (SVG, MathML, custom
+// elements) — so an all-uppercase `tagName` is always an HTML-namespace normalization,
+// never a real name, and should be lowercased back to what's actually in the markup.
+// Live-verified: a `domSelector` built with the raw (uppercased) HTML tag name produced a
+// region that was visually positioned correctly (rect-only match) but showed as "unlinked"
+// to any DOM node until manually relinked, at which point the server rewrote it to
+// lowercase — confirming the server's own matching is case-sensitive against source case.
+const ALL_UPPERCASE_TAGNAME = /^[A-Z][A-Z0-9]*$/;
+function toDomSelectorTagName(tagName) {
+    return ALL_UPPERCASE_TAGNAME.test(tagName) ? tagName.toLowerCase() : tagName;
+}
+/**
+ * The shared id-range-skipping walk behind both `findNodeById` and `findNodeObjectById`:
+ * resolves a single node id against the full, unpruned, already-id-assigned tree, returning
+ * both the node itself and its `domSelector` (a `/tagName[i]` path from the root, `i` being
+ * the 0-based index among siblings sharing that tag name). Returns `null` if the id isn't
+ * present in the tree.
+ *
+ * Because `assignNodeIds` numbers nodes in pre-order with a single counter, every node's
+ * subtree occupies a contiguous, gapless id range starting at its own id, and sibling
+ * subtrees' ranges are strictly ordered left-to-right with no overlap — a sibling's own
+ * id is exactly the exclusive upper bound of the *previous* sibling's subtree range. This
+ * lets the search skip an entire sibling subtree without visiting a single node in it,
+ * whenever the target id clearly falls outside that subtree's range, rather than only
+ * stopping once it happens to reach the target by a plain linear walk.
+ */
+function searchNodeById(root, domId) {
+    const target = Number(domId);
+    function search(node, path, upperBoundExclusive) {
+        if (!node || !node.tagName || node.tagName.startsWith('#'))
+            return null;
+        const nodeId = Number(node.id);
+        if (!Number.isFinite(nodeId) || target < nodeId || target >= upperBoundExclusive)
+            return null;
+        if (target === nodeId)
+            return { node, path };
+        const elementChildren = (node.childNodes ?? []).filter((c) => c?.tagName && !c.tagName.startsWith('#'));
+        const tagCounts = new Map();
+        for (let i = 0; i < elementChildren.length; i++) {
+            const child = elementChildren[i];
+            // Siblings' id ranges are contiguous and strictly ascending (see the class doc above), so
+            // once target is smaller than this child's own id, it can't be in this or any later
+            // sibling either — nothing left to find. Safe to stop here without finishing tagCounts:
+            // nothing downstream will read it once we're about to return null from this node.
+            if (target < Number(child.id))
+                break;
+            // tagCounts must be updated for every sibling in order, even ones we skip below without
+            // recursing into — it's this child's index among same-tag siblings, needed to number any
+            // later sibling sharing its tag correctly, independent of whether target turns out to be
+            // in this particular child's subtree.
+            const index = tagCounts.get(child.tagName) ?? 0;
+            tagCounts.set(child.tagName, index + 1);
+            // This child's subtree ends where the next sibling's own id begins; the last
+            // child inherits the bound passed down from this node's own caller.
+            const next = elementChildren[i + 1];
+            const childUpperBound = next ? Number(next.id) : upperBoundExclusive;
+            // target lies past this child's entire subtree — skip recursing into it, but its
+            // tagCounts increment above must still happen (see comment there).
+            if (target >= childUpperBound)
+                continue;
+            const found = search(child, `${path}/${toDomSelectorTagName(child.tagName)}[${index}]`, childUpperBound);
+            if (found)
+                return found;
+        }
+        return null;
+    }
+    return search(root, `/${toDomSelectorTagName(root?.tagName ?? '')}`, Infinity);
+}
+/**
+ * Resolves a single node id to its `domSelector` and `rect`. Returns `null` if the id isn't
+ * present in the tree, or if the node found has no usable rect.
+ */
+export function findNodeById(root, domId) {
+    const found = searchNodeById(root, domId);
+    if (!found)
+        return null;
+    const rect = nodeRect(found.node);
+    return rect ? { domSelector: found.path, rect: roundRect(rect) } : null;
+}
+/**
+ * Resolves a single node id to the node object itself — unlike `findNodeById`, which only
+ * returns `{domSelector, rect}`. Needed wherever a caller must inspect or serialize the node
+ * itself, not just locate it. Returns `null` if the id isn't present in the tree.
+ */
+export function findNodeObjectById(root, domId) {
+    return searchNodeById(root, domId)?.node ?? null;
+}
+const DOM_SELECTOR_SEGMENT_RE = /^([^[]+)\[(\d+)]$/;
+/**
+ * The inverse of `findNodeById`: walks `root` following a `domSelector` path (e.g.
+ * `/html/body[0]/div[2]`, as produced by `findNodeById`/`findNodeByRect`) and returns the
+ * rect of whatever element it still resolves to — or `null` if it doesn't (the element that
+ * path was built against has been removed, or a sibling's tag/order changed enough to shift
+ * indices). Returns the same `{domSelector, rect}` shape as `findNodeById`/`findNodeByRect`,
+ * so callers can use whichever of the three applies interchangeably.
+ *
+ * The first path segment is the root's own bare tag name with no `[index]` (see
+ * `findNodeById`) — there's only one root, so it's skipped rather than checked. Every
+ * segment after that must match `tagName[index]`, `index` being 0-based among `node`'s
+ * children sharing that tag.
+ */
+export function findNodeBySelector(root, path) {
+    const segments = path.split('/').filter(Boolean);
+    if (segments.length === 0)
+        return null;
+    let node = root;
+    for (let i = 1; i < segments.length; i++) {
+        const match = DOM_SELECTOR_SEGMENT_RE.exec(segments[i]);
+        if (!match)
+            return null;
+        const [, tagName, indexStr] = match;
+        const children = (node?.childNodes ?? []).filter((c) => c?.tagName && !c.tagName.startsWith('#') && toDomSelectorTagName(c.tagName) === tagName);
+        node = children[Number(indexStr)];
+        if (!node)
+            return null;
+    }
+    const rect = nodeRect(node);
+    return rect ? { domSelector: path, rect: roundRect(rect) } : null;
+}
+/**
+ * Resolves a batch of node ids against the same already-fetched, already-id-assigned
+ * tree, one `findNodeById` walk per id. Pure — takes the tree as-is, does no fetching of
+ * its own (callers fetch the DOM snapshot once and reuse it here).
+ *
+ * Throws if any id can't be resolved, naming all of them, rather than silently omitting
+ * an entry from the returned map — a caller indexing the result by id (e.g.
+ * `result.get(id)!`) would otherwise get `undefined` for a bad id with no signal why.
+ */
+export function resolveNodeIdsToNodes(root, nodeIds) {
+    const result = new Map();
+    const missing = [];
+    for (const id of nodeIds) {
+        const resolved = findNodeById(root, id);
+        if (resolved)
+            result.set(id, resolved);
+        else
+            missing.push(id);
+    }
+    if (missing.length > 0) {
+        throw new Error(`Node id(s) not found in DOM snapshot: ${missing.join(', ')}`);
+    }
+    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.
+ */
+export function findNodeByRect(root, targetRect, tolerancePx = 5) {
+    let best = null;
+    let bestDelta = Infinity;
+    for (const { node } of flattenTree(root)) {
+        const r = nodeRect(node);
+        if (!r)
+            continue;
+        const dLeft = Math.abs(r.left - targetRect.left);
+        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;
+        }
+    }
+    return best ? findNodeById(root, best.id) : null;
+}
+// ---------------------------------------------------------------------------
+// Reading-order sort
+// ---------------------------------------------------------------------------
+function readingOrderCompare(a, b) {
+    const aR = a.rect, bR = b.rect;
+    if (!aR && !bR)
+        return 0;
+    if (!aR)
+        return 1;
+    if (!bR)
+        return -1;
+    const aBottom = aR.top + aR.height;
+    const bBottom = bR.top + bR.height;
+    const overlapTop = Math.max(aR.top, bR.top);
+    const overlapBottom = Math.min(aBottom, bBottom);
+    const overlap = overlapBottom - overlapTop;
+    const minHeight = Math.min(aR.height, bR.height);
+    // "Same line" when vertical overlap > 50% of the shorter element's height
+    if (minHeight > 0 && overlap / minHeight > 0.5) {
+        return aR.left - bR.left;
+    }
+    return aR.top - bR.top;
+}
+// ---------------------------------------------------------------------------
+// flattenTree
+// ---------------------------------------------------------------------------
+/** Kept past the DOM-diff backend cutover: `findNodeByRect` walks the tree through it. */
+export function flattenTree(root) {
+    const result = [];
+    function traverse(node, depth, parent) {
+        if (!node)
+            return;
+        if (Array.isArray(node)) {
+            for (const n of node)
+                traverse(n, depth, parent);
+            return;
+        }
+        // Skip text/comment nodes and elements without a rect
+        if (!node.tagName || node.tagName.startsWith('#'))
+            return;
+        if (!node.rect)
+            return;
+        const flat = { node, depth, parent };
+        result.push(flat);
+        const elementChildren = (node.childNodes ?? []).filter((c) => c?.tagName && !c.tagName.startsWith('#') && c.rect);
+        const sorted = [...elementChildren].sort(readingOrderCompare);
+        for (const child of sorted) {
+            traverse(child, depth + 1, flat);
+        }
+    }
+    traverse(root, 0, null);
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Property helpers
+// ---------------------------------------------------------------------------
+function roundRect(r) {
+    if (!r)
+        return r;
+    return {
+        left: Math.round(r.left),
+        top: Math.round(r.top),
+        width: Math.round(r.width),
+        height: Math.round(r.height),
+    };
+}
+/**
+ * Returns whether an Applitools DOM capture node could plausibly paint a pixel: it has a
+ * non-zero-size rect and isn't hidden via `display:none`, `visibility:hidden`,
+ * `opacity:0`, or the `hidden` HTML attribute.
+ */
+export function isVisible(node) {
+    const r = node.rect;
+    if (!r || r.width <= 0 || r.height <= 0)
+        return false;
+    const style = node.style ?? {};
+    if ((style.display ?? '').toString().toLowerCase() === 'none')
+        return false;
+    if ((style.visibility ?? '').toString().toLowerCase() === 'hidden')
+        return false;
+    const opacity = parseFloat(style.opacity);
+    if (!Number.isNaN(opacity) && opacity === 0)
+        return false;
+    if (Object.prototype.hasOwnProperty.call(node.attributes ?? {}, 'hidden'))
+        return false;
+    return true;
+}
+// ---------------------------------------------------------------------------
+// filterDiffToArea (final pass — cropping)
+// ---------------------------------------------------------------------------
+//
+// Restricts an already-computed diff to entries relevant to a given area. This must run
+// LAST, after matching/diffing has completed over the full, unrestricted trees. Cropping
+// the input trees before matching (e.g. pruning both sides to `area` before flattening)
+// loses cross-subtree context and can cause the LCS matcher to align the wrong nodes, or
+// fail to recognize an unpruned ancestor as the same persisting element — see
+// the node-ids/cropping caveat in atoms/README.md's "DOM diffing" section.
+function entryIntersectsArea(item, area) {
+    if (item.status === 'displaced') {
+        return rectsIntersect(item.rect, area) || rectsIntersect(item.baseline.rect, area);
+    }
+    if (item.status === 'changed') {
+        return rectsIntersect(item.rect, area) || rectsIntersect(item.baseline.rect, area);
+    }
+    // 'new' (checkpoint-side only) or 'missing', singleton or collapsed (baseline-side only) —
+    // either way, item.rect is the one side that exists for this entry.
+    return rectsIntersect(item.rect, area);
+}
+export function filterDiffToArea(diffs, area) {
+    return diffs.map(item => (item !== null && entryIntersectsArea(item, area) ? item : null));
+}
+// ---------------------------------------------------------------------------
+// excludeNonVisualNodeDiffs (final pass — visual-diff-rect filtering)
+// ---------------------------------------------------------------------------
+//
+// Restricts an already-computed diff to entries that correspond to an actual visual diff —
+// e.g. a match region (ignore/dynamic/layout/etc.) suppresses a pixel diff but not necessarily
+// a DOM-level structural difference underneath it. Like `filterDiffToArea`, this must run
+// LAST, after matching/diffing has completed over the full, unrestricted trees — pruning the
+// input trees themselves before matching risks the same alignment-quality loss described above.
+// Unlike `filterDiffToArea`, baseline-side and checkpoint-side rects are checked against their
+// own, independent rect list (a step's visual diff is itself two-way — see `compareStep`/the
+// `GET .../diff` endpoint's own `image1`/`image2` split), not a single shared area.
+function entryIntersectsVisualDiff(item, baselineDiffs, checkpointDiffs) {
+    const intersectsAny = (r, rects) => !!r && rects.some(rect => rectsIntersect(r, rect));
+    if (item.status === 'displaced') {
+        return intersectsAny(item.rect, checkpointDiffs) || intersectsAny(item.baseline.rect, baselineDiffs);
+    }
+    if (item.status === 'changed') {
+        return intersectsAny(item.rect, checkpointDiffs) || intersectsAny(item.baseline.rect, baselineDiffs);
+    }
+    if (item.status === 'new') {
+        return intersectsAny(item.rect, checkpointDiffs);
+    }
+    // 'missing', singleton or collapsed — baseline-only subtree
+    return intersectsAny(item.rect, baselineDiffs);
+}
+export function excludeNonVisualNodeDiffs(diffs, baselineDiffs, checkpointDiffs) {
+    return diffs.map(item => item !== null && entryIntersectsVisualDiff(item, baselineDiffs, checkpointDiffs) ? item : null);
+}
+// ---------------------------------------------------------------------------
+// serializeDiff
+// ---------------------------------------------------------------------------
+export function serializeDiff(diffs) {
+    const lines = [];
+    for (const diff of diffs) {
+        if (diff === null)
+            continue;
+        const { depth, ...obj } = diff;
+        lines.push('  '.repeat(depth) + JSON.stringify(obj));
+    }
+    return lines.join('\n');
+}
+/**
+ * Extracts one target node's aligned counterpart and rect-filtered diff from an
+ * already-computed alignment (the backend's `fetchDomDiff` result, or an equivalent
+ * `DomAlignment` obtained some other way) — the cheap part once the
+ * whole-tree alignment is done, so a caller with several target nodes against the same pair of
+ * trees runs this once per node without paying for the alignment itself more than once.
+ * `targetNodeId` must be a node id assigned (see `assignNodeIds`) on whichever tree was aligned
+ * as the checkpoint side — its matched baseline id and its own checkpoint rect are read straight
+ * off `alignment.matches` by that id, so a caller never needs to hold onto the actual node object,
+ * only its id, and this works just as well against an alignment that was serialized (e.g. read
+ * back from a cache or a network response) as against one just computed in-process.
+ *
+ * Reading a target's own match off a *global*, whole-tree alignment — rather than a standalone
+ * best-match search for that one node — is deliberate: an element that occupies the same
+ * structural position across captures but now shows entirely different content (e.g. a rotating
+ * carousel slot, or a live counter) would otherwise get matched to wherever its *old* content
+ * happens to reappear elsewhere on the page, rather than to whatever now occupies its own slot.
+ * Aligning the whole page at once keeps a node's in-place replacement — not a content lookalike
+ * somewhere else — as its counterpart, because the aligner is scored on overall sequence
+ * correspondence, not one node in isolation.
+ */
+export function extractNodeDiff(alignment, targetNodeId) {
+    if (!(targetNodeId in alignment.matches))
+        return { found: false, matchedNodeId: null, diff: '' };
+    const match = alignment.matches[targetNodeId];
+    if (!match)
+        return { found: true, matchedNodeId: null, diff: '' };
+    const result = filterDiffToArea(alignment.diff, match.checkpointRect);
+    const diff = serializeDiff(result)
+        .split('\n')
+        .map(line => line.trimStart())
+        .join('\n');
+    return { found: true, matchedNodeId: match.baselineId, diff };
+}

package/dist/sessions/match.js

@@ -0,0 +1,56 @@
+/**
+ * The subset of `AnnotationCategory` (`sessions/regions.ts`) Applitools Eyes' own
+ * `ImageMatchSettings` schema actually has a field for — a raw session's own
+ * `imageMatchSettings` object never has a `mismatching` or `remarks` key, unlike
+ * `annotations`/`identifiedRegions`, which do (those two are a dashboard/annotations-only
+ * concept, not a real match-settings one).
+ */
+export const MATCH_SETTINGS_CATEGORIES = [
+    'content',
+    'dynamic',
+    'floating',
+    'ignore',
+    'layout',
+    'strict',
+    'accessibility',
+];
+function pickCategories(bucket) {
+    const result = {};
+    for (const category of MATCH_SETTINGS_CATEGORIES) {
+        result[category] = bucket?.[category] ?? [];
+    }
+    return result;
+}
+/**
+ * Builds the full `ImageMatchSettings` an `images/compare` request body expects for a step —
+ * ready to use as-is. The rest of the request (`image1`/`image2`/`sessionId`/`batchId`/
+ * `runningSessionId`/`stepIndex`) is the caller's own job, not this function's — none of those
+ * are match-settings concerns.
+ *
+ * - Scalars (`matchLevel`, `scale`, `ignoreCaret`, `ignoreDisplacements`, `useDom`, etc.) come
+ *   straight from `actualAppOutput[stepIndex].imageMatchSettings` — the match settings actually
+ *   in effect for this run.
+ * - `identifiedRegions` (this run's own coded regions) also comes from that same
+ *   `imageMatchSettings` object's own per-category arrays — never falling back to the
+ *   baseline's `identifiedRegions` snapshot: if a category has no entry there, there is no coded
+ *   region of that kind in the current match, full stop.
+ * - The plain, domSelector-anchored region categories are overwritten from
+ *   `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.
+ *
+ * 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
+ * diagnostic display that needs both sides shown) — this only ever needs the one side already in
+ * effect, relayed as-is, by reference.
+ */
+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),
+    };
+}