@applitools/eyes-results 0.2.0

package/types/sessions/dom.d.ts

@@ -0,0 +1,263 @@
+import { type Rect } from '../geometry/geometry.js';
+/**
+ * A DOM snapshot as the backend's pruned-DOM endpoint serves it (`api`'s `fetchPrunedDom`) —
+ * distinct from the raw dom the raw-DOM endpoint returns. Every step below is the *backend's* —
+ * the client-side pruner was removed at the DOM-diff cutover, so no function in this package
+ * performs any of them. Relative to a raw dom, a PrunedDom has:
+ *  - embedded UFG CDN URLs rewritten to their canonical form, so the same resource looks
+ *    identical whether captured on a baseline or checkpoint run
+ *  - every element assigned a stable, sequential `id` (the numbering `assignNodeIds` mirrors),
+ *    against the full unpruned tree, before any cropping happens
+ *  - top-level metadata fields stripped (`css`, `images`, `version`, `scriptVersion`) — never
+ *    part of the tree structure itself
+ *  - whitespace-only `#text` node children removed throughout the tree
+ * It has *not* been cropped to any area — that's `getDomArea`'s separate, uncached, per-call
+ * job, applied to a PrunedDom after it's already been fetched.
+ */
+export type PrunedDom = any;
+/**
+ * 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 declare function nodeRect(node: PrunedDom): Rect | null;
+/**
+ * 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 declare function getDomArea(node: PrunedDom, area: Rect): PrunedDom | PrunedDom[] | null;
+/**
+ * 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 declare function validateDomId(domId: string | null | undefined): string | null;
+/**
+ * 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 declare function assignNodeIds(root: any): void;
+/** A node located by id or by walking a `domSelector` path — the selector that reaches it, and its rect. */
+export interface DomNode {
+    domSelector: string;
+    rect: Rect;
+}
+/**
+ * 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 declare function findNodeById(root: PrunedDom, domId: string): DomNode | 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 declare function findNodeObjectById(root: PrunedDom, domId: string): any | null;
+/**
+ * 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 declare function findNodeBySelector(root: PrunedDom, path: string): DomNode | 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 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.
+ */
+export declare function findNodeByRect(root: PrunedDom, targetRect: Rect, tolerancePx?: number): DomNode | null;
+export interface FlatNode {
+    node: PrunedDom;
+    depth: number;
+    /** This node's parent FlatNode in the same tree, or null/undefined at the root or when built
+     * without parent tracking (e.g. hand-built test fixtures). Lets a consumer walk up to an
+     * ancestor, or find true structural siblings, without re-traversing the tree. */
+    parent?: FlatNode | null;
+}
+export interface DisplacedEntry {
+    status: 'displaced';
+    count: number;
+    depth: number;
+    rect: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+    baseline: {
+        rect: {
+            left: number;
+            top: number;
+            width: number;
+            height: number;
+        };
+    };
+}
+export interface CollapsedMissingEntry {
+    status: 'missing';
+    tagName: string;
+    id: string;
+    depth: number;
+    count: number;
+    attributes?: Record<string, string>;
+    rect: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+}
+/** Common shape shared by `ChangedDiffEntry`/`NewDiffEntry`/`MissingDiffEntry`'s own side of a
+ * comparison — never the full `PrunedDom` node, only the properties an entry ever surfaces. */
+interface DiffEntrySide {
+    style?: Record<string, any>;
+    attributes?: Record<string, string>;
+    text?: string;
+}
+export interface ChangedDiffEntry extends DiffEntrySide {
+    status: 'changed';
+    depth: number;
+    tagName: string;
+    id: string;
+    rect: Rect;
+    baseline: DiffEntrySide & {
+        tagName?: string;
+        id: string;
+        rect: Rect;
+    };
+}
+export interface NewDiffEntry extends DiffEntrySide {
+    status: 'new';
+    depth: number;
+    tagName: string;
+    id: string;
+    rect: Rect;
+}
+/** One baseline-side element with no checkpoint counterpart at all — a single removed element,
+ * as opposed to `CollapsedMissingEntry`'s whole removed subtree. */
+export interface MissingDiffEntry extends DiffEntrySide {
+    status: 'missing';
+    depth: number;
+    tagName: string;
+    id: string;
+    rect: Rect;
+}
+/** One entry of an already-computed `DomAlignment.diff` — the same compact, per-element shape
+ * `serializeDiff` formats into its final string, carrying only each side's own id/rect/changed
+ * properties, never a full `PrunedDom` node or its ancestor chain. */
+export type DiffEntry = ChangedDiffEntry | NewDiffEntry | MissingDiffEntry | DisplacedEntry | CollapsedMissingEntry;
+/** Kept past the DOM-diff backend cutover: `findNodeByRect` walks the tree through it. */
+export declare function flattenTree(root: PrunedDom): FlatNode[];
+/**
+ * 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 declare function isVisible(node: PrunedDom): boolean;
+export declare function filterDiffToArea(diffs: (DiffEntry | null)[], area: Rect): (DiffEntry | null)[];
+export declare function excludeNonVisualNodeDiffs(diffs: (DiffEntry | null)[], baselineDiffs: Rect[], checkpointDiffs: Rect[]): (DiffEntry | null)[];
+export declare function serializeDiff(diffs: (DiffEntry | null)[]): string;
+/** One checkpoint node's own match info, keyed by that node's id in `DomAlignment.matches` — its
+ * matched baseline node's own id (`baselineId`) and the checkpoint node's own `checkpointRect`.
+ * Never the full node objects on either side — see `DomAlignment.matches`'s own doc for why. A
+ * checkpoint node with no baseline counterpart (e.g. a genuinely new element) has no rect worth
+ * keeping here either — nothing about it can be aligned further, so `matches` maps that id to
+ * `null` instead of a `CompactMatch` (see `DomAlignment.matches`'s own doc for the full
+ * three-state shape). */
+export interface CompactMatch {
+    baselineId: string;
+    checkpointRect: Rect;
+}
+export interface DomAlignment {
+    /** One entry per checkpoint node, in one of three states: the key itself absent means the id
+     * doesn't exist on the checkpoint side at all; present but mapped to `null` means the id exists
+     * but has no baseline counterpart; present and mapped to a `CompactMatch` means it does. Compact
+     * by design — never full node objects for the two sides of a match; serializing those (to a
+     * cache file, or a network response) would duplicate most of the tree's own data once per node
+     * it appears in as an ancestor, large enough on a big page to exhaust memory outright. */
+    matches: Record<string, CompactMatch | null>;
+    /** One entry per changed/new/missing/displaced element, already narrowed to `DiffEntry`'s
+     * compact shape — never a full `PrunedDom` node or its ancestor
+     * chain. Cropping to an area (`filterDiffToArea`) or excluding non-visual entries
+     * (`excludeNonVisualNodeDiffs`) are separate, later steps a caller applies to this array
+     * itself. */
+    diff: (DiffEntry | null)[];
+}
+export interface NodeDiffResult {
+    /** Whether `targetNodeId` was found at all on the checkpoint side of the alignment. `false`
+     * means the id genuinely doesn't exist in whichever tree was aligned as the checkpoint side —
+     * distinct from `matchedNodeId: null`, which means the id *was* found but has no baseline
+     * counterpart (e.g. it's a genuinely new element). A caller that only cares whether the id it
+     * asked about actually exists (rather than fetching a whole tree just to check) can rely on
+     * this without an extra call, since it's read off an alignment already being computed. */
+    found: boolean;
+    /** The id of the baseline-side node aligned to `targetNodeId`, or `null` if the global
+     * alignment found no counterpart for it (e.g. it doesn't exist yet on the baseline side).
+     * Always `null` when `found` is `false`. */
+    matchedNodeId: string | null;
+    /** Same compact format `serializeDiff` produces, filtered to the target node's own rect, but
+     * without `serializeDiff`'s own leading per-line indentation — that indent communicates
+     * nesting depth for direct terminal viewing (`dom-diff`'s own use), which is meaningless
+     * once this diff is embedded as a string value inside another JSON structure, and would
+     * vary arbitrarily with how deep the target node itself happens to sit in the page. Always
+     * `''` when `found` is `false` or `matchedNodeId` is `null` — either way there's no baseline
+     * counterpart's own rect left to scope a diff to (`DomAlignment.matches` never keeps one for
+     * an unmatched node). */
+    diff: string;
+}
+/**
+ * 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 declare function extractNodeDiff(alignment: DomAlignment, targetNodeId: string): NodeDiffResult;
+export {};

package/types/sessions/match.d.ts

@@ -0,0 +1,72 @@
+import type { Region } from './regions.js';
+/**
+ * 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 declare const MATCH_SETTINGS_CATEGORIES: readonly ["content", "dynamic", "floating", "ignore", "layout", "strict", "accessibility"];
+export type MatchSettingsCategory = (typeof MATCH_SETTINGS_CATEGORIES)[number];
+/**
+ * Applitools Eyes' own `ImageMatchSettings` structure — the same shape both as stored on a raw
+ * session's `actualAppOutput[stepIndex].imageMatchSettings` and as accepted by an
+ * `images/compare` request body (see `api`'s `compareStep`), built from a raw session via
+ * `getEffectiveMatchSettings` below. Every field is optional — a raw session's own
+ * `imageMatchSettings` isn't guaranteed to carry all of them (nothing here enforces it did), and
+ * a caller building a partial one by hand (e.g. a test fixture) shouldn't have to restate every
+ * scalar/category just to exercise the one it cares about.
+ */
+export interface ImageMatchSettings {
+    matchLevel?: string;
+    ignoreCaret?: boolean;
+    ignoreDisplacements?: boolean;
+    useDom?: boolean;
+    useDL?: boolean;
+    enablePatterns?: boolean;
+    scale?: number;
+    remainder?: number;
+    splitTopHeight?: number;
+    splitBottomHeight?: number;
+    content?: Region[];
+    dynamic?: Region[];
+    floating?: Region[];
+    ignore?: Region[];
+    layout?: Region[];
+    strict?: Region[];
+    accessibility?: Region[];
+    identifiedRegions?: Record<MatchSettingsCategory, Region[]>;
+    /**
+     * Only meaningful on an `images/compare` request body — governs what a `Dynamic` matchLevel
+     * treats as "the same." Never observed on a raw session's own `imageMatchSettings`; omitted,
+     * the server applies its own default.
+     */
+    dynamicMatchLevelSettings?: {
+        ignorePatterns: string[];
+    };
+}
+/**
+ * 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 declare function getEffectiveMatchSettings(rawSession: any, stepIndex: number): ImageMatchSettings;

package/types/sessions/regions.d.ts

@@ -0,0 +1,171 @@
+import { type PrunedDom } from './dom.js';
+/**
+ * A single region, unified across every place this repo encounters one — a dashboard-added,
+ * `domSelector`-anchored annotation; a test-code-defined, `regionId`-anchored coded region; or
+ * an `images/compare` request's own region entry (per Applitools' own compare-endpoint schema,
+ * which is the origin of the `padding*` fields). `domSelector` and `regionId` are each optional
+ * and independent: a region may be anchored by one, the other, both, or neither (a plain rect —
+ * confirmed live all of domSelector-only/regionId-only/plain-rect/combined work), and padding
+ * only ever layers on top of whichever anchor is given.
+ */
+export interface Region {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+    regionId?: string;
+    domSelector?: string;
+    paddingLeft?: number;
+    paddingTop?: number;
+    paddingRight?: number;
+    paddingBottom?: number;
+}
+export declare const ANNOTATION_CATEGORIES: readonly ["content", "dynamic", "floating", "ignore", "mismatching", "layout", "remarks", "strict", "accessibility"];
+export type AnnotationCategory = (typeof ANNOTATION_CATEGORIES)[number];
+export declare function emptyAnnotations(): Record<AnnotationCategory, Region[]>;
+export interface RegionEntry {
+    category: AnnotationCategory;
+    region: Region;
+}
+/**
+ * The same logical region as known on each image side — either may be absent, e.g. because the
+ * raw session doesn't encode that side's version at all, or the region doesn't exist there.
+ * Used both for plain (`annotations`-backed) regions, where either side may be absent, and for
+ * coded regions (see `getEffectiveRegions`'s own `pairCodedRegions`), where `checkpoint` is
+ * always populated by construction — a coded region is only ever surfaced there when it's
+ * defined on the checkpoint side, so a caller working with `codedRegions` can rely on
+ * `checkpoint` being present without an extra check, even though the type itself doesn't
+ * enforce that narrower guarantee.
+ */
+export interface RegionPair {
+    category: AnnotationCategory;
+    baseline?: Region;
+    checkpoint?: Region;
+}
+export interface EffectiveRegions {
+    regions: RegionPair[];
+    codedRegions: RegionPair[];
+}
+/**
+ * Determines which side's DOM a step's regions should reference. `accept`/`reject` always
+ * resolve against the side they're about to make the (new) baseline going forward —
+ * checkpoint or baseline respectively. `unchanged` means an action that doesn't itself
+ * change the step's resolution (e.g. `baseline-regions`/`checkpoint-regions`, or just
+ * inspecting current state), so it must defer to whatever the step's *existing* resolution
+ * already is: a step accepted (but not yet saved) by an earlier call already has the
+ * checkpoint as its baseline-to-be, so a region added now should reference that, not the
+ * original baseline. Only an explicit prior reject, or no resolution at all, means the
+ * original baseline is still the one to reference. `expectedAppOutput`/`actualAppOutput`
+ * never change to reflect a pending resolution — only
+ * `appOutputResolution[stepIndex].replaceExpected` does.
+ */
+export declare function resolveDomIdSide(action: 'accept' | 'reject' | 'unchanged', rawSession: any, stepIndex: number): 'baseline' | 'checkpoint';
+/** The raw session's own image record (`{ id, domId, size, hasDom, location, rectangle }`) for a step's baseline or checkpoint image. */
+export declare function imageForSide(rawSession: any, stepIndex: number, side: 'baseline' | 'checkpoint'): any;
+/**
+ * Extracts every region-shaped structure the raw session encodes for a step, as
+ * baseline/checkpoint pairs — either side of a pair may be `undefined`, for a caller to fill
+ * in later (e.g. via `checkRegions` and the other functions below):
+ *
+ * - `regions` — domSelector-backed `Region[]`, from `annotations`. Only one side is ever
+ *   populated here, since the raw session never encodes an `annotations`-shaped structure for
+ *   both sides at once — `resolveDomIdSide` determines which side these domSelectors actually
+ *   describe. `appOutputResolution[stepIndex].annotations`, when present, overrides
+ *   `expectedAppOutput[stepIndex].annotations` entirely rather than being combined with it —
+ *   the same way an empty category there means "resolved to have none" even when the
+ *   baseline has one.
+ * - `codedRegions` — `regionId`-backed `Region[]`, paired up from `identifiedRegions` (on
+ *   `expectedAppOutput`/`appOutputResolution`, same override rule as `annotations` — always the
+ *   baseline side) and `imageMatchSettings` (on `actualAppOutput` — always the checkpoint side).
+ *   Only ever includes an entry that's defined on the checkpoint side — a baseline
+ *   `identifiedRegions` entry with no matching checkpoint `regionId` is dropped entirely (see
+ *   `pairCodedRegions`), so `checkpoint` is never `undefined` here, only `baseline`.
+ *
+ * Both `annotations` and `identifiedRegions` deliberately exclude `removedAnnotations` — a
+ * historical record of past removals, not part of the current, effective region set.
+ */
+export declare function getEffectiveRegions(rawSession: any, stepIndex: number): EffectiveRegions;
+export interface CheckedRegions {
+    /** Has a `domSelector` that resolved against `domSource`. */
+    anchored: RegionPair[];
+    /** No `domSelector`, or one that failed to resolve against `domSource` (including when `domSource` itself is unavailable) — left as-is either way, *not* cleared. */
+    nonAnchored: RegionPair[];
+}
+/**
+ * Splits every incomplete `RegionPair` (missing one side — see `getEffectiveRegions`) into
+ * anchored/non-anchored, verifying each anchored candidate's `domSelector` against `domSource`
+ * (the DOM of whichever side is already populated) along the way. Purely a classification —
+ * nothing is mutated, so a caller that just wants to inspect a step's regions as currently
+ * encoded (e.g. `eyes-inspect`'s `regions` command) can call this without side effects: a
+ * stale `domSelector` (one that no longer resolves) lands in `nonAnchored` exactly as encoded,
+ * not cleared — only a caller that intends to *heal* it (see `clearStaleSelectors`, below)
+ * should clear it. `anchored` means "has a `domSelector` that actually resolved" — if
+ * `domSource` is `null` (couldn't be fetched), nothing can be verified, so every pair lands in
+ * `nonAnchored`, domSelector or not.
+ */
+export declare function checkRegions(regions: RegionPair[], domSource: PrunedDom): CheckedRegions;
+/**
+ * Clears the `domSelector` (mutating in place) of every pair in `nonAnchored` that still has
+ * one — i.e. a stale one `checkRegions` left untouched — so it can be retried by
+ * `healNonAnchoredRegionsBySourceRect`. A stale selector is never sent to
+ * get-compatible-selectors as-is: live-confirmed against the real API, a single bad input
+ * selector fails the *entire* batched call, not just itself. Returns whether anything was
+ * actually cleared. Only a caller that intends to re-anchor a region calls this (e.g.
+ * `eyes-resolve`'s `resolveStepFlow`) — a caller that just wants to inspect regions as encoded
+ * (`checkRegions`'s other caller) should leave a stale selector alone for diagnosis rather
+ * than heal past it.
+ */
+export declare function clearStaleSelectors(nonAnchored: RegionPair[]): boolean;
+/**
+ * Attempts to anchor each `nonAnchored` pair by finding its region's rect on `domSource` — the
+ * same mechanism a brand-new rect-form region uses to upgrade into a domSelector-backed one.
+ * Mutates a healed pair's existing (source-side) region in place with the found `domSelector`
+ * and accurate rect; a pair with no match is left as a plain rect, unchanged. Returns whether
+ * anything was healed. Pure and synchronous — `domSource` must already be fetched.
+ */
+export declare function healNonAnchoredRegionsBySourceRect(nonAnchored: RegionPair[], domSource: PrunedDom): boolean;
+/**
+ * Fills in whichever side of each `RegionPair` is still missing with a plain, unanchored
+ * copy of its populated side — same rect, no `domSelector`. This doesn't try to find or heal
+ * anything (unlike every other function above); it just guarantees every pair comes out with
+ * both sides present, for a caller (`eyes-inspect`'s `regions` command) that wants a
+ * consistently-shaped, fully "mapped" output to inspect rather than an occasionally-partial
+ * one. Once this runs, a `domSelector` present on one side but empty on the other is itself
+ * diagnostically meaningful — it means that side's `domSelector` is stale, or the anchoring
+ * element genuinely doesn't exist there (get-compatible-selectors mapped it to `null`) —
+ * rather than being an accident of the pair simply never having been looked at.
+ */
+export declare function fillMissingSideWithPlainRect(regions: RegionPair[]): void;
+/**
+ * The coded-region counterpart to `fillMissingSideWithPlainRect` — but one-directional, since
+ * `checkpoint` is never missing to begin with on a coded `RegionPair` (see
+ * `pairCodedRegions`/`getEffectiveRegions`): only `baseline` ever needs filling. Fills it with a
+ * plain copy of `checkpoint` at the same rect, with `regionId` cleared to `''`, rather than
+ * leaving it `undefined`.
+ */
+export declare function fillMissingBaselineForCodedRegions(codedRegions: RegionPair[]): void;
+/**
+ * Finds an existing region "the same" as `candidate`: an exact `domSelector` match
+ * (checked across all candidates first — the stronger signal, survives rect drift), or
+ * else a rect match within `tolerancePx` on all four of left/top/width/height. Searches
+ * across every category, not just the one `candidate` belongs to, so a region that's been
+ * reclassified (e.g. layout -> ignore) is still found and replaced rather than duplicated.
+ */
+export declare function findSimilarExistingRegion(existing: RegionEntry[], candidate: Region, tolerancePx?: number): RegionEntry | null;
+/**
+ * Removes (in place) the entry in `entries` "similar" to `candidate` (see
+ * `findSimilarExistingRegion`), if any, returning the removed entry — or `null` if nothing
+ * matched, so a caller can report exactly what was actually removed (e.g. for a `-<matchLevel>-
+ * <target>` regionOp) rather than just whether something was.
+ *
+ * Live-confirmed against the real API: the `stepUpdates[].annotations` field is a full
+ * replacement of the resolution's active regions, not a delta merged against whatever's
+ * already stored — and `removedAnnotations` isn't actually used for removal at all (the
+ * real Test Manager UI sends it as an empty skeleton even when deleting a region). So the
+ * only correct way to add/remove a region is to fetch the current full set, mutate it
+ * in memory (this function, plus a plain `.push` for adds), and send the *entire* result
+ * back as `annotations` — see eyes-resolve's `resolveStepFlow`.
+ */
+export declare function removeSimilarRegion(entries: RegionEntry[], candidate: Region, tolerancePx?: number): RegionEntry | null;
+/** Buckets a flat, category-tagged region list back into the category-keyed shape the API expects. */
+export declare function bucketRegions(entries: RegionEntry[]): Record<AnnotationCategory, Region[]>;

package/types/sessions/session.d.ts

@@ -0,0 +1,97 @@
+export interface ImageInfo {
+    id: string | null;
+    domId: string | null;
+    size: {
+        width: number;
+        height: number;
+    } | null;
+}
+export interface SessionEnvironment {
+    browser: string | null;
+    device: string | null;
+    os: string | null;
+    width: number | null;
+    height: number | null;
+}
+export interface SessionStep {
+    tag: string | undefined;
+    baseline: ImageInfo;
+    checkpoint: ImageInfo;
+    isMatching: boolean;
+    resolution: 'accepted' | 'rejected' | 'none';
+    /** A pending resolution or region change on this step, not yet committed via `save`. */
+    isUnsaved: boolean;
+}
+export interface SimplifiedSession {
+    sessionId: string;
+    sessionName: string;
+    appName: string;
+    status: string;
+    isUnsaved: boolean;
+    isAborted: boolean;
+    environment: SessionEnvironment;
+    startedAt: string;
+    /** `null` when shaped with `{ includeSteps: false }` — see `simplifySession`. */
+    steps: SessionStep[] | null;
+}
+/**
+ * Whether a raw session currently has any pending, unsaved change — an accept/reject decision
+ * or a region edit not yet committed via `save`. Checks every step's own
+ * `appOutputResolution[i].isChanged` flag (the same signal each step's own `isUnsaved` below is
+ * derived from), not the raw session's own top-level `isModified` field — confirmed live:
+ * `isModified` is sticky, staying `true` forever once a session was ever changed, even long
+ * after that change was fully cleared (e.g. via a batch-wide reset), so it can't signal "has a
+ * pending change right now." Independent of whether `simplifySession` was asked to compute
+ * `steps` — this reads `appOutputResolution` directly, so it's correct either way.
+ */
+export declare function hasUnsavedChanges(rawData: any): boolean;
+/**
+ * Whether `stepIndex`'s checkpoint already carries a human accept/reject decision — the same
+ * `resolution` a step gets in `simplifySession` below, pulled out standalone so a caller only
+ * needs one step's status without shaping (or paying for) the whole session's `steps` array.
+ * A resolution entry can exist purely from a region edit, with no accept/reject decision behind
+ * it (no `replaceExpected` field) — only a real boolean there counts as resolved, however each
+ * side originally read.
+ */
+export declare function getStepResolution(rawData: any, stepIndex: number): 'accepted' | 'rejected' | 'none';
+/**
+ * Extracts a raw session's scenario id — the join key for the session-history query (see
+ * `api`'s `fetchSessionHistory`) — confirmed live as a top-level `scenarioId` field,
+ * distinct from `scenarioName` (already mapped to `SimplifiedSession.sessionName`). Throws
+ * rather than returning `undefined` so a caller building a history query fails loudly instead
+ * of silently querying with a bad/missing id.
+ */
+export declare function extractScenarioId(rawData: any): string;
+/**
+ * Throws a clear "step index N is out of range" error if `stepIndex` doesn't correspond to an
+ * actual step in the raw session. Callers that work from the raw, unshaped session directly
+ * (unlike this module's own `simplifySession`, which already has a bounds-checked `steps`
+ * array) would otherwise silently index past the end of `expectedAppOutput`/`actualAppOutput`
+ * and read `undefined` — which `validateDomId` then reports as "this step has no DOM capture",
+ * indistinguishable from a real step that simply wasn't DOM-captured.
+ */
+export declare function validateStepIndex(rawSession: any, stepIndex: number): void;
+/** Total step count for a raw session — the longer of its baseline/checkpoint image arrays. */
+export declare function getStepCount(rawSession: any): number;
+/**
+ * Shapes a raw Eyes session API response into a compact summary — one representation
+ * shared by both a single-session inspection (`steps` command, full `steps` array) and a
+ * batch listing (`batch` command, one entry per session — pass `{ includeSteps: false }`
+ * there to skip computing `steps` for every session in the batch, which that listing has
+ * no use for since step-level counts are already aggregated separately into `sessions/batch`'s
+ * `BatchStats`).
+ *
+ * Overloaded so the common case (steps included, by default or explicitly) types `steps`
+ * as a real array rather than `Array | null` — only `{ includeSteps: false }` narrows it to
+ * `null`, matching what the implementation actually returns in each case.
+ */
+export declare function simplifySession(rawData: any, options?: {
+    includeSteps?: true;
+}): SimplifiedSession & {
+    steps: SessionStep[];
+};
+export declare function simplifySession(rawData: any, options: {
+    includeSteps: false;
+}): SimplifiedSession & {
+    steps: null;
+};