@applitools/eyes-results 0.2.0

package/dist/sessions/regions.js

@@ -0,0 +1,280 @@
+import { findNodeByRect, findNodeBySelector } from './dom.js';
+export const ANNOTATION_CATEGORIES = [
+    'content',
+    'dynamic',
+    'floating',
+    'ignore',
+    'mismatching',
+    'layout',
+    'remarks',
+    'strict',
+    'accessibility',
+];
+export function emptyAnnotations() {
+    return {
+        content: [],
+        dynamic: [],
+        floating: [],
+        ignore: [],
+        mismatching: [],
+        layout: [],
+        remarks: [],
+        strict: [],
+        accessibility: [],
+    };
+}
+/**
+ * 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 function resolveDomIdSide(action, rawSession, stepIndex) {
+    if (action === 'accept')
+        return 'checkpoint';
+    if (action === 'reject')
+        return 'baseline';
+    const resolutionEntry = rawSession?.appOutputResolution?.[stepIndex];
+    return resolutionEntry?.replaceExpected === true ? 'checkpoint' : 'baseline';
+}
+/** The raw session's own image record (`{ id, domId, size, hasDom, location, rectangle }`) for a step's baseline or checkpoint image. */
+export function imageForSide(rawSession, stepIndex, side) {
+    return side === 'baseline'
+        ? rawSession?.expectedAppOutput?.[stepIndex]?.image
+        : rawSession?.actualAppOutput?.[stepIndex]?.image;
+}
+function flattenCategoryBucket(source) {
+    const result = [];
+    if (!source)
+        return result;
+    for (const category of ANNOTATION_CATEGORIES) {
+        for (const region of source[category] ?? []) {
+            result.push({ category, region });
+        }
+    }
+    return result;
+}
+/**
+ * Pairs up two flattened coded-region lists — one per image side — into `RegionPair`s by
+ * matching `regionId` within each category (a coded region's `regionId` is the same code-level
+ * locator/name on both sides, so it's a stable join key). Only ever produces one pair per
+ * `checkpoint` entry — a `baseline` entry with no matching `checkpoint` regionId is dropped
+ * entirely, not surfaced with `checkpoint` absent: `imageMatchSettings` reflects what the test
+ * run just asked for, so a coded region no longer requested by the checkpoint isn't part of
+ * the effective set, even if a stale snapshot of it still lingers in `identifiedRegions`. Every
+ * returned pair's `checkpoint` is therefore always populated, by construction, even though
+ * `RegionPair`'s own type doesn't require it.
+ */
+function pairCodedRegions(baseline, checkpoint) {
+    return checkpoint.map(c => {
+        const match = baseline.find(b => b.category === c.category && b.region.regionId === c.region.regionId);
+        return match
+            ? { category: c.category, baseline: match.region, checkpoint: c.region }
+            : { category: c.category, checkpoint: c.region };
+    });
+}
+/**
+ * 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 function getEffectiveRegions(rawSession, stepIndex) {
+    const flatRegions = flattenCategoryBucket(rawSession?.appOutputResolution?.[stepIndex]?.annotations ??
+        rawSession?.expectedAppOutput?.[stepIndex]?.annotations);
+    const regionsOnBaseline = resolveDomIdSide('unchanged', rawSession, stepIndex) === 'baseline';
+    const regions = flatRegions.map(({ category, region }) => regionsOnBaseline ? { category, baseline: region } : { category, checkpoint: region });
+    const baselineCoded = flattenCategoryBucket(rawSession?.appOutputResolution?.[stepIndex]?.identifiedRegions ??
+        rawSession?.expectedAppOutput?.[stepIndex]?.identifiedRegions);
+    const checkpointCoded = flattenCategoryBucket(rawSession?.actualAppOutput?.[stepIndex]?.imageMatchSettings);
+    return { regions, codedRegions: pairCodedRegions(baselineCoded, checkpointCoded) };
+}
+// ---------------------------------------------------------------------------
+// Healing — filling in whichever side of a RegionPair the raw session doesn't encode
+// ---------------------------------------------------------------------------
+// findNodeBySelector/findNodeByRect return a nested {domSelector, rect} shape (DomNode);
+// the Region shape needed elsewhere is flat (domSelector alongside left/top/width/height).
+function toRegion(resolved) {
+    return { domSelector: resolved.domSelector, ...resolved.rect };
+}
+/**
+ * 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 function checkRegions(regions, domSource) {
+    const anchored = [];
+    const nonAnchored = [];
+    for (const pair of regions) {
+        if (pair.baseline && pair.checkpoint)
+            continue; // already complete — nothing to check
+        const region = (pair.baseline ?? pair.checkpoint);
+        if (domSource && region.domSelector && findNodeBySelector(domSource, region.domSelector)) {
+            anchored.push(pair);
+        }
+        else {
+            nonAnchored.push(pair); // no domSelector, a stale one, or nothing to verify against at all
+        }
+    }
+    return { anchored, nonAnchored };
+}
+/**
+ * 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 function clearStaleSelectors(nonAnchored) {
+    let changed = false;
+    for (const pair of nonAnchored) {
+        const region = pair.baseline ?? pair.checkpoint;
+        if (region?.domSelector) {
+            region.domSelector = '';
+            changed = true;
+        }
+    }
+    return changed;
+}
+/**
+ * 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 function healNonAnchoredRegionsBySourceRect(nonAnchored, domSource) {
+    if (!domSource)
+        return false;
+    let changed = false;
+    for (const pair of nonAnchored) {
+        const sourceSide = pair.baseline ? 'baseline' : 'checkpoint';
+        const found = findNodeByRect(domSource, pair[sourceSide]);
+        if (found) {
+            pair[sourceSide] = toRegion(found);
+            changed = true;
+        }
+    }
+    return changed;
+}
+/**
+ * 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 function fillMissingSideWithPlainRect(regions) {
+    for (const pair of regions) {
+        if (pair.baseline && pair.checkpoint)
+            continue;
+        const region = (pair.baseline ?? pair.checkpoint);
+        const missingSide = pair.baseline ? 'checkpoint' : 'baseline';
+        pair[missingSide] = { ...region, domSelector: '' };
+    }
+}
+/**
+ * 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 function fillMissingBaselineForCodedRegions(codedRegions) {
+    for (const pair of codedRegions) {
+        if (pair.baseline)
+            continue;
+        pair.baseline = { ...pair.checkpoint, regionId: '' };
+    }
+}
+/**
+ * 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 function findSimilarExistingRegion(existing, candidate, tolerancePx = 5) {
+    for (const entry of existing) {
+        if (candidate.domSelector && entry.region.domSelector && candidate.domSelector === entry.region.domSelector) {
+            return entry;
+        }
+    }
+    for (const entry of existing) {
+        const r = entry.region;
+        if (Math.abs(r.left - candidate.left) <= tolerancePx &&
+            Math.abs(r.top - candidate.top) <= tolerancePx &&
+            Math.abs(r.width - candidate.width) <= tolerancePx &&
+            Math.abs(r.height - candidate.height) <= tolerancePx) {
+            return entry;
+        }
+    }
+    return 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 function removeSimilarRegion(entries, candidate, tolerancePx = 5) {
+    const match = findSimilarExistingRegion(entries, candidate, tolerancePx);
+    if (!match)
+        return null;
+    entries.splice(entries.indexOf(match), 1);
+    return match;
+}
+/** Buckets a flat, category-tagged region list back into the category-keyed shape the API expects. */
+export function bucketRegions(entries) {
+    const result = emptyAnnotations();
+    for (const entry of entries) {
+        result[entry.category].push(entry.region);
+    }
+    return result;
+}

package/dist/sessions/session.js

@@ -0,0 +1,115 @@
+/**
+ * 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 function hasUnsavedChanges(rawData) {
+    const appOutputResolution = rawData.appOutputResolution ?? [];
+    return appOutputResolution.some((entry) => entry?.isChanged === true);
+}
+/**
+ * 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 function getStepResolution(rawData, stepIndex) {
+    const resolutionEntry = rawData?.appOutputResolution?.[stepIndex];
+    return typeof resolutionEntry?.replaceExpected === 'boolean'
+        ? resolutionEntry.replaceExpected
+            ? '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 function extractScenarioId(rawData) {
+    const scenarioId = rawData?.scenarioId;
+    if (typeof scenarioId !== 'string' || !scenarioId) {
+        throw new Error('Raw session has no scenarioId field — cannot look up its session history.');
+    }
+    return scenarioId;
+}
+/**
+ * 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 function validateStepIndex(rawSession, stepIndex) {
+    const stepCount = getStepCount(rawSession);
+    if (stepIndex < 0 || stepIndex >= stepCount) {
+        throw new Error(`Step index ${stepIndex} is out of range (session has ${stepCount} steps)`);
+    }
+}
+/** Total step count for a raw session — the longer of its baseline/checkpoint image arrays. */
+export function getStepCount(rawSession) {
+    return Math.max(rawSession?.expectedAppOutput?.length ?? 0, rawSession?.actualAppOutput?.length ?? 0);
+}
+export function simplifySession(rawData, options) {
+    let steps = null;
+    if (options?.includeSteps ?? true) {
+        steps = [];
+        const expectedOutputs = rawData.expectedAppOutput || [];
+        const actualOutputs = rawData.actualAppOutput || [];
+        const appOutputResolution = rawData.appOutputResolution || [];
+        for (let i = 0; i < Math.max(expectedOutputs.length, actualOutputs.length); i++) {
+            const expected = expectedOutputs[i];
+            const actual = actualOutputs[i];
+            if (!expected && !actual)
+                continue;
+            const tag = actual?.tag;
+            const isMatching = actual?.isMatching ?? false;
+            const resolution = getStepResolution(rawData, i);
+            const resolutionEntry = appOutputResolution[i];
+            steps.push({
+                tag,
+                baseline: {
+                    id: expected?.image?.id ?? null,
+                    domId: expected?.image?.domId ?? null,
+                    size: expected?.image?.size ?? null,
+                },
+                checkpoint: {
+                    id: actual?.image?.id ?? null,
+                    domId: actual?.image?.domId ?? null,
+                    size: actual?.image?.size ?? null,
+                },
+                isMatching,
+                resolution,
+                isUnsaved: resolutionEntry?.isChanged === true,
+            });
+        }
+    }
+    const env = rawData.env ?? {};
+    return {
+        sessionId: rawData.id,
+        sessionName: rawData.scenarioName,
+        appName: rawData.appName,
+        status: rawData.status,
+        isUnsaved: hasUnsavedChanges(rawData),
+        isAborted: rawData.isAborted === true,
+        environment: {
+            browser: env.hostingApp ?? null,
+            device: env.deviceInfo ?? null,
+            os: env.os ?? null,
+            width: env.displaySize?.width ?? null,
+            height: env.displaySize?.height ?? null,
+        },
+        startedAt: rawData.startedAt,
+        steps,
+    };
+}

package/llm-docs/dom-search.md

@@ -0,0 +1,164 @@
+# dom-search predicate language
+
+`dom-search` searches a DOM capture (the JSON produced by eyes-inspect's `dom` command) for elements matching a predicate, and prints one line per match — indented to show its depth in the tree.
+
+Only real tag elements are matched; text and comment nodes are never matched directly. Every element also gets a virtual `text` property: the concatenation of its own direct text content. A matching element with non-empty text has that text appended to its output line after a `#`.
+
+A predicate is one of seven kinds of check — a **property comparison**, a **bounds (geometry) check**, a **size comparison**, a **direction check**, a **relationship check**, an **attribute-presence check**, or a **shortcut keyword** — combined with `and`, `or`, `not`, and parentheses.
+
+Several of these checks need to reference *another* element rather than the one being tested. Do that with `node <id>`, using the element's `id` field — e.g. `node 12`; it shows up in bounds checks, size comparisons, direction checks, and relationship checks below. Relationship checks additionally accept a sub-predicate in place of `node <id>`, describing the other element instead of naming its id — see "Checking relationships" below.
+
+## Boolean combinations
+
+Combine any predicates with `and`, `or`, `not` (or the symbols `&&`, `||`, `!`) and parentheses. `not` binds tighter than `and`, which binds tighter than `or` — same as most programming languages. Use parentheses to override that.
+
+```
+image and gif
+tagName = 'DIV' or tagName = 'SPAN'
+not (tagName = 'SPAN')
+```
+
+## Comparing a property
+
+Reference a property by its path — `tagName`, `attributes.class`, `attributes.data-testid`, `style.display`, `rect.width`, `rect.left`, or the virtual `text` property — and compare it to a value:
+
+- **Equality**: `=` or `equals`, and `!=` or `not-equals`.
+- **Ordering** (numeric — also handles CSS lengths like `"16px"`): `<`/`less-than`, `<=`/`less-than-or-equal`, `>`/`greater-than`, `>=`/`greater-than-or-equal`.
+- **String matching**: `starts-with`, `ends-with`, `contains`.
+- **Regex**: `matches`, `regex`, or `=~`, with the value written as `/pattern/flags`.
+- **Membership**: `in`, with a parenthesized, comma-separated list of values.
+
+String comparisons are case-insensitive. A property that doesn't exist on an element just fails to match — it never causes an error. Examples:
+
+```
+tagName = 'DIV'
+attributes.class contains 'btn'
+rect.width > 200
+style.display != 'none'
+attributes.href starts-with 'https://'
+tagName =~ /^H[1-6]$/
+attributes.type in ('button', 'submit', 'reset')
+```
+
+Values with no spaces can be written bare (`tagName = DIV`). A value containing spaces or special characters must be single-quoted (`attributes.class = 'nav item'`) — there is no double-quoted form, so a literal `"` never needs escaping and isn't itself an escape sequence. Inside a quoted value, `\'`, `\\`, `\n`, `\t`, and `\r` are recognized escapes — so `text = 'line one\nline two'` matches an element whose text spans two lines. A regex literal (`/pattern/flags`) doesn't need this — its own `\n`/`\t`/etc. are interpreted by the regex engine directly.
+
+## Checking geometry
+
+Test an element's bounding rectangle against a point, a rectangle, or another element:
+
+```
+bounds contains 400,300              (a point, "x,y")
+bounds contains 0,0,500,200          (a rectangle, "left,top,width,height")
+bounds contains node 12              (the element with id 12)
+bounds intersects node 12
+bounds contained-by node 12
+```
+
+`bounds` and `rect` are interchangeable here. An element with no rectangle never matches a geometry check. (Writing `rect.width` or another dotted path still works as an ordinary property comparison — only a bare `rect`/`bounds` followed directly by `contains`/`intersects`/`contained-by` is a geometry check.)
+
+## Comparing size
+
+Compare an element's area, width, or height against a literal number, another element's dimensions, or a plain size/rectangle:
+
+```
+larger-than node 12          (area bigger than element 12's area)
+smaller-than 5000            (area smaller than 5000 square px)
+wider-than node 12           (width greater than element 12's width)
+narrower-than 300            (width less than 300px)
+taller-than 0,0,200,80       (height greater than 80 — a rect's own height, position ignored)
+shorter-than 200,80          (height less than 80 — a plain "width,height" size)
+```
+
+The target can be `node <id>` (use that element's dimensions), a rectangle (4 numbers — only its width/height matter, not its position), a plain size (2 numbers, `width,height`), or a single bare number — interpreted as area for `larger-than`/`smaller-than`, width for `wider-than`/`narrower-than`, height for `taller-than`/`shorter-than`. An element with no rectangle (as either the subject or the `node` target) never matches.
+
+## Checking direction
+
+Test whether an element is entirely above, below, left of, or right of another element or rectangle — not just overlapping it, but fully past the relevant edge:
+
+```
+above node 12
+below node 12
+left-of node 12
+right-of 0,0,500,200
+```
+
+`right-of T` means entirely to the right of T's right edge; `left-of T` entirely to the left of T's left edge; `above`/`below` work the same way against T's top/bottom edge. An element that merely overlaps the target matches none of the four.
+
+## Checking relationships
+
+Test an element's position in the tree relative to another element:
+
+```
+descendant-of node 12
+ancestor-of node 12
+child-of node 12
+parent-of node 12
+sibling-of node 12
+2nd child-of node 12
+first child-of node 12
+```
+
+Ordinal forms (`1st`, `2nd`, ... `20th`, or `first`, `second`, ... `twentieth`) count only element children, ignoring text.
+
+Instead of `node <id>`, you can give a whole sub-predicate in parentheses, describing the other element instead of naming it — this lets you say "some ancestor/descendant/sibling that looks like X" without knowing its id:
+
+```
+child-of (tagName = 'FORM')
+2nd child-of (ancestor-of text and tagName = 'BUTTON')
+```
+
+The second example reads as: "the 2nd child of some element that is itself a BUTTON with a descendant that has text."
+
+## Checking attribute presence
+
+Test whether an element has a given attribute at all, regardless of its value:
+
+```
+has-attribute src
+has-attribute 'data-testid'
+```
+
+The name is matched case-insensitively and can be written bare (no spaces) or single-quoted. This differs from `attributes.<name> != ''` in one case: an attribute present with an empty value (e.g. `alt=""`) counts as present for `has-attribute`, but would fail a `!= ''` check.
+
+## Shortcut keywords
+
+A handful of common checks are a single word, with no operator or value:
+
+| Keyword | Matches |
+|---|---|
+| `text` | Has non-empty text |
+| `image` | Looks like a visual image (broad heuristic — see below) |
+| `gif` | Is an `IMG` (specifically, not the broader `image` set) whose `src` ends with `.gif` |
+| `logo` | `class`/`id`/`alt` contains "logo" |
+| `link` | Is an `A` |
+| `button` | Is a `BUTTON`, a `button`/`submit`/`reset` `INPUT`, or has `role="button"` |
+| `heading` | Is `H1` through `H6` |
+| `hidden` | `display:none`, `visibility:hidden`, `opacity:0`, zero width/height (or no rect), or has a `hidden` attribute |
+| `visible` | The exact inverse of `hidden` |
+| `empty` | Has no text and no element children |
+| `true` | Always matches — every element |
+| `false` | Never matches |
+
+`image` is a broad heuristic, not a single structural check — it's meant to answer "does this look like an image to a person looking at the page", not "is this literally an `<img>` tag". It matches any of:
+
+- an `IMG`, `SVG`, or `PICTURE` element (by tag, regardless of attributes)
+- any element with a CSS `background-image` other than `none`
+
+Because it's a heuristic, expect both false positives and false negatives: a `DIV` styled with a decorative `background-image` counts as an "image" even though it's not meaningfully one, while an icon rendered via an icon font (a glyph character styled with a special font, no image-related attribute or style at all) is invisible to this check and will never match. When you need the strict "literally an `<img>` tag" meaning instead, write `tagName = 'IMG'` directly.
+
+**Results include hidden elements by default** — dom-search doesn't filter anything out unless the predicate says so, since silently hiding a match is worse than an unwanted one (you might be searching precisely because an element is unexpectedly hidden). **To skip hidden elements, start the predicate with `visible and ...`**, e.g. `visible and tagName = 'BUTTON'`.
+
+## More examples
+
+```
+tagName = 'DIV' and attributes.class contains 'btn'
+image and gif
+heading and text
+rect.width > 200 and not (tagName = 'SPAN')
+attributes.type in ('button', 'submit')
+bounds contains 400,300
+descendant-of node 12
+larger-than node 12
+right-of node 12
+has-attribute 'aria-label'
+```

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@applitools/eyes-results",
+  "version": "0.2.0",
+  "description": "Applitools Eyes REST plumbing, DOM diffing, and session/batch shaping",
+  "keywords": [
+    "applitools",
+    "eyes",
+    "visual-testing",
+    "dom-diff",
+    "sessions"
+  ],
+  "homepage": "https://applitools.com",
+  "bugs": {
+    "url": "https://github.com/applitools/eyes.sdk.javascript1/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/applitools/eyes.sdk.javascript1.git",
+    "directory": "js/packages/eyes-results"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "author": {
+    "name": "Applitools Team",
+    "email": "team@applitools.com"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "types",
+    "llm-docs/dom-search.md"
+  ],
+  "scripts": {
+    "lint": "run --top-level eslint '**/*.ts'",
+    "build": "run --top-level tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "type-check": "run --top-level tsc --noEmit"
+  },
+  "dependencies": {
+    "@applitools/req": "1.11.3",
+    "dotenv": "^16.6.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "typescript": "~5.9.3",
+    "vitest": "^4.1.9"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "lavamoat": {
+    "allowScripts": {
+      "vitest>jsdom>ws>bufferutil": false,
+      "vitest>jsdom>ws>utf-8-validate": false,
+      "vitest>vite>esbuild": false
+    }
+  }
+}

package/types/api/api.d.ts

@@ -0,0 +1,17 @@
+export * from './url-parsing.js';
+export * from './polling.js';
+export * from './req-results.js';
+export * from './tasks.js';
+export * from './fs-cache.js';
+export * from './gzip.js';
+export * from './dom-fetch.js';
+export * from './dom-diff.js';
+export * from './image-fetch.js';
+export * from './session-fetch.js';
+export * from './selector-mapping.js';
+export * from './diff-fetch.js';
+export * from './session-updates.js';
+export * from './find-regions.js';
+export * from './session-history-fetch.js';
+export * from './compare-step.js';
+export * from './same-diff-as.js';