@applitools/eyes-results 0.2.0

package/types/geometry/geometry.d.ts

@@ -0,0 +1,24 @@
+export interface Rect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+export declare function parseRect(s: string): Rect;
+/** Inverse of `parseRect` — formats a rect back into `"left,top,width,height"`. */
+export declare function formatRect(rect: Rect): string;
+/**
+ * Returns true if outer completely contains inner (all edges of inner are within outer).
+ * Equal rectangles are considered to contain each other.
+ */
+export declare function rectContains(outer: Rect, inner: Rect): boolean;
+export declare function rectsIntersect(a: Rect, b: Rect): boolean;
+export declare function intersectionArea(a: Rect, b: Rect): number;
+export declare function boundingRect(a: Rect, b: Rect): Rect;
+/**
+ * Expands a rect by `padding` pixels on every side.
+ * When `imageWidth`/`imageHeight` are provided the result is clipped to the image bounds.
+ */
+export declare function padRect(rect: Rect, padding: number, imageWidth?: number, imageHeight?: number): Rect;
+/** Merges pairs of rects that overlap by more than 10% of the smaller rect's area. */
+export declare function unifyRects(rects: Rect[]): Rect[];

package/types/index.d.ts

@@ -0,0 +1,14 @@
+export * from './lib/api-key-provider.js';
+export * from './lib/env.js';
+export * from './lib/phase-tracker.js';
+export * from './geometry/geometry.js';
+export * from './sessions/batch.js';
+export * from './sessions/diffs.js';
+export * from './sessions/dom-history.js';
+export * from './sessions/dom-search.js';
+export * from './sessions/dom.js';
+export * from './sessions/match.js';
+export * from './sessions/regions.js';
+export * from './sessions/session.js';
+export * from './api/api.js';
+export * from './common/common.js';

package/types/lib/api-key-provider.d.ts

@@ -0,0 +1,31 @@
+/**
+ * A source of API keys, so a caller threads one object through a call chain instead of choosing
+ * and passing the right raw key string itself at every call site — the read/write (and, for a
+ * future run-triggering flow, run) distinction is made once, by whoever constructs the provider,
+ * not re-decided by every function that happens to need one. A function that only ever needs one
+ * specific kind of key calls that one getter and never sees the others, so passing a provider
+ * built for the wrong purpose fails at the point of use rather than silently substituting the
+ * wrong credential.
+ */
+export interface ApiKeyProvider {
+    getReadKey(): string;
+    getWriteKey(): string;
+    getRunKey(): string;
+}
+/**
+ * Wraps already-resolved key strings. A getter throws a clear error if its key wasn't supplied —
+ * e.g. a write key deliberately withheld when building a provider for a read-only call — rather
+ * than returning `undefined` and letting a missing credential fail confusingly further down.
+ */
+export declare class StaticApiKeyProvider implements ApiKeyProvider {
+    private readonly keys;
+    constructor(keys: {
+        readKey?: string;
+        writeKey?: string;
+        runKey?: string;
+    });
+    getReadKey(): string;
+    getWriteKey(): string;
+    getRunKey(): string;
+    private require;
+}

package/types/lib/env.d.ts

@@ -0,0 +1,14 @@
+import * as fs from 'fs';
+export interface LoadEnvDeps {
+    existsSync: typeof fs.existsSync;
+    configDotenv: (options: {
+        path: string;
+    }) => unknown;
+}
+export declare const defaultLoadEnvDeps: LoadEnvDeps;
+/**
+ * Walks up from `startDir` (default: the current working directory) looking for a `.env`
+ * file, loading the first one found via `dotenv`. Mirrors the behavior every skill's own
+ * `main.ts` used to inline directly.
+ */
+export declare function loadEnvFromCwd(startDir?: string, deps?: LoadEnvDeps): void;

package/types/lib/phase-tracker.d.ts

@@ -0,0 +1,146 @@
+/**
+ * A generic, eyes-agnostic completion registry backing eyes-inspect's workflow tools (and,
+ * eventually, eyes-resolve's own batch-review phases) — persisted to the filesystem so a
+ * restarted server picks an in-progress investigation back up with no special "resume"
+ * handling. Every id is an opaque string a caller constructs deterministically from its own
+ * natural identifiers (a batch/session URL, a step index, a rect) — this module has no
+ * knowledge of what an id represents, only that the same input always hashes to the same
+ * record.
+ *
+ * Alongside that registry sits a second, unrelated facility on the same filesystem substrate:
+ * `log`, a generic call-trace log any caller can append a labeled entry to — see its own doc
+ * comment.
+ */
+export interface PhaseTrackerDeps {
+    readFile: (filePath: string) => string | null;
+    writeFile: (filePath: string, contents: string) => void;
+    /** Appends `contents` to `filePath`, creating it if absent — never reads first. */
+    appendFile: (filePath: string, contents: string) => void;
+    /** Removes `filePath` if it exists — a no-op if it doesn't. */
+    deleteFile: (filePath: string) => void;
+    mkdir: (dirPath: string) => void;
+    /** Blocks the current call for `ms` milliseconds — swapped out in tests to skip real delays. */
+    sleep: (ms: number) => void;
+    /** Root directory every record is written under, partitioned into completions/child-findings/invocations/modes/children/unready-children subdirectories, plus a debug subdirectory holding one log file per scope id a caller has logged under. */
+    stateDir: string;
+}
+export declare const defaultPhaseTrackerDeps: PhaseTrackerDeps;
+export interface Completion<T = unknown> {
+    payload: T;
+    completedAt: string;
+}
+/** The recorded completion for `id`, or `undefined` if `<level>_end` was never (successfully) called for it. */
+export declare function getCompletion<T = unknown>(id: string, deps?: PhaseTrackerDeps): Completion<T> | undefined;
+export declare function isCompleted(id: string, deps?: PhaseTrackerDeps): boolean;
+/**
+ * Persists `payload` as `id`'s completion, stamped with the current time — overwriting
+ * whatever was recorded for `id` before, so revising a summary (or refreshing a stale
+ * completion) is just calling this again.
+ */
+export declare function recordCompletion<T>(id: string, payload: T, deps?: PhaseTrackerDeps): Completion<T>;
+/** `parentId`'s full accumulated child-findings record, read as-is with no live-data filtering. `{}` if no child has ever reported into it. */
+export declare function getChildFindings<T = unknown>(parentId: string, deps?: PhaseTrackerDeps): Record<string, T>;
+/**
+ * Writes (or overwrites) `childId`'s entry in `parentId`'s accumulated findings record,
+ * creating that record the first time any child reports into it. Called once a child's own
+ * `_end` succeeds — independent of whether `childId` is still among `parentId`'s currently-live
+ * children, so a child that later drops out of the live set never loses its findings.
+ */
+export declare function appendChildFinding<T>(parentId: string, childId: string, payload: T, deps?: PhaseTrackerDeps): void;
+export interface InvocationLogEntry {
+    toolName: string;
+    args: unknown;
+    at: string;
+}
+/** Appends one entry to `scopeId`'s invocation log — called as a side effect of every eyes-inspect data tool. */
+export declare function logInvocation(scopeId: string, toolName: string, args: unknown, deps?: PhaseTrackerDeps): void;
+/** Whether `scopeId`'s invocation log contains a call to `toolName` whose `args` satisfy `matcher` — the per-item invocation-verification check backing `step_end`/`diff_end`'s hard gates. */
+export declare function verifyInvocation(scopeId: string, toolName: string, matcher: (args: unknown) => boolean, deps?: PhaseTrackerDeps): boolean;
+/** Persists `mode` as the mode `scopeId` is currently being reviewed in — overwriting whatever was recorded before, so re-entering with the same mode simply re-states it. */
+export declare function recordScopeMode(scopeId: string, mode: string, deps?: PhaseTrackerDeps): void;
+/** The mode last recorded for `scopeId` via `recordScopeMode`, or `undefined` if never recorded. */
+export declare function getScopeMode(scopeId: string, deps?: PhaseTrackerDeps): string | undefined;
+/** Discards `id`'s completion, as if `recordCompletion` had never been called for it. */
+export declare function clearCompletion(id: string, deps?: PhaseTrackerDeps): void;
+/** Discards `parentId`'s entire accumulated child-findings record — every child's entry, not just one. */
+export declare function clearChildFindings(parentId: string, deps?: PhaseTrackerDeps): void;
+/** Discards `scopeId`'s recorded mode, as if `recordScopeMode` had never been called for it. */
+export declare function clearScopeMode(scopeId: string, deps?: PhaseTrackerDeps): void;
+/** Persists the keys of `scopeId`'s children still unready to be finalized, as of its own latest live check — overwriting whatever was recorded before, so a child that has since become ready (or a newly-discovered unready one) is reflected exactly, never accumulated across checks. */
+export declare function recordUnreadyChildren(scopeId: string, childKeys: string[], deps?: PhaseTrackerDeps): void;
+/** The child keys `recordUnreadyChildren` last recorded as unready for `scopeId`, or `[]` if never recorded. */
+export declare function getUnreadyChildren(scopeId: string, deps?: PhaseTrackerDeps): string[];
+/** Discards `scopeId`'s recorded unready-children snapshot, as if `recordUnreadyChildren` had never been called for it. */
+export declare function clearUnreadyChildren(scopeId: string, deps?: PhaseTrackerDeps): void;
+/** `scopeId`'s queued child keys — the stable, append-only set of children discovered live so far, investigated from regardless of what a later live fetch would show. `[]` if none have ever been queued. */
+export declare function getQueuedChildKeys(scopeId: string, deps?: PhaseTrackerDeps): string[];
+/**
+ * Appends any of `liveKeys` not already queued, preserving the existing queue's order with
+ * newcomers appended in their given order — never removes a key, so a child that later drops out
+ * of a live fetch (resolved via propagation, or otherwise) stays queued and gets visited. Returns
+ * the full merged queue; writes only when something actually changed.
+ */
+export declare function queueChildKeys(scopeId: string, liveKeys: string[], deps?: PhaseTrackerDeps): string[];
+/** Discards `scopeId`'s entire queued-children record, as if nothing had ever been queued for it. */
+export declare function clearQueuedChildKeys(scopeId: string, deps?: PhaseTrackerDeps): void;
+/**
+ * Persists `payload` as everything `scopeId`'s own live fetch most recently discovered — e.g. a
+ * batch's full session list, expensive to fetch and shared by everything nested under it —
+ * overwriting whatever was recorded before, so a caller that decides to refresh simply calls this
+ * again. Unlike `queueChildKeys`/`getQueuedChildKeys` (a stable, append-only set of keys a caller
+ * has committed to investigating), this is the raw discovery result itself — including entries
+ * (e.g. still-`Running` sessions) that may not be ready to investigate at all — so a lower-level
+ * scope nested underneath `scopeId` can re-derive its own children from it without repeating the
+ * fetch.
+ */
+export declare function recordDiscoveredChildren<T>(scopeId: string, payload: T, deps?: PhaseTrackerDeps): void;
+/** What `recordDiscoveredChildren` last recorded for `scopeId`, or `undefined` if never recorded. */
+export declare function getDiscoveredChildren<T>(scopeId: string, deps?: PhaseTrackerDeps): T | undefined;
+/** Discards `scopeId`'s recorded discovery, as if `recordDiscoveredChildren` had never been called for it. */
+export declare function clearDiscoveredChildren(scopeId: string, deps?: PhaseTrackerDeps): void;
+/**
+ * The exact filesystem path `log` appends `scopeId`'s entries to — a caller (or a human trying to
+ * find the right file by hand) never has to reimplement this module's own hashing scheme just to
+ * locate it.
+ */
+export declare function getLogFilePath(scopeId: string, deps?: PhaseTrackerDeps): string;
+export interface DebugLogEntry {
+    at: string;
+    label: string;
+    input?: unknown;
+    output?: unknown;
+    error?: unknown;
+    message?: unknown;
+}
+/**
+ * A generic call-trace log: any caller can record one labeled entry, with no fixed vocabulary for
+ * what a call even is — `label` is whatever convention the caller adopts (today, resolution.ts
+ * labels each entry with the traced function's own name; a wholly different caller could start
+ * labeling its own entries tomorrow with no change here). Appends to `scopeId`'s own log file,
+ * partitioned by hashed id the same way every other record in this module is — `scopeId` is just
+ * as opaque to this module as everywhere else it appears, so it's entirely the caller's own choice
+ * whether to pass the same id (e.g. an investigation's root) on every call, consolidating every
+ * entry raised anywhere within it into one file, or a more granular one per call, splitting the
+ * trace up instead. `label` is the only other required field; `input`/`output`/`error`/`message`
+ * are all optional and independent — a call-and-response entry sets `input`/`output`, a failed one
+ * sets `error` (instead of stuffing it into `output`), and anything that isn't a call at all (a
+ * one-off event, a snapshot) just sets `message` to whatever shape fits. Every entry lands as one
+ * line (a JSON-encoded `DebugLogEntry`) in a single NDJSON file at `getLogFilePath(scopeId, deps)`.
+ * There is no reader function: this is meant to be opened directly (as a file on disk, or via
+ * `deps.readFile` in a test) rather than queried back through this module.
+ *
+ * Safe under concurrent callers by construction, not by locking: this never reads the file before
+ * appending (so there's no read-modify-write window for two callers to race), and each entry is
+ * written as a single `appendFile` call — opening for append and writing is one atomic
+ * seek-to-end-and-write at the OS level, so concurrent appends interleave whole lines and never
+ * corrupt or split one another's. The only remaining failure mode is a transient lock on the file
+ * itself (e.g. a concurrent antivirus scan) — `mkdir`/`appendFile` are wrapped in the same
+ * lock-retry backoff (`withRetry`) as every other record this module writes, so a caller never
+ * has to poll for the file to become available itself; a momentarily-busy append just retries.
+ */
+export declare function log(scopeId: string, label: string, fields?: {
+    input?: unknown;
+    output?: unknown;
+    error?: unknown;
+    message?: unknown;
+}, deps?: PhaseTrackerDeps): void;

package/types/sessions/batch.d.ts

@@ -0,0 +1,67 @@
+import type { SimplifiedSession } from './session.js';
+/**
+ * The slice of the raw batch entity's fields `toBatchStats` reads. The real response has
+ * many more fields (name, timing, `properties`, etc.) — irrelevant here, so left untyped.
+ */
+export interface BatchInfo {
+    completedCount: number;
+    runningCount: number;
+    abortedCount: number;
+    passedCount: number;
+    failedCount: number;
+    unresolvedCount: number;
+    changedCount: number;
+    stepsCount: number;
+    unresolvedStepsCount: number;
+    changedStepsCount: number;
+    missingStepsCount: number;
+    newStepsCount: number;
+}
+export interface BatchStats {
+    total: number;
+    unresolved: number;
+    passed: number;
+    failed: number;
+    aborted: number;
+    unsaved: number;
+    totalSteps: number;
+    unresolvedSteps: number;
+    unsavedSteps: number;
+    missingSteps: number;
+    newSteps: number;
+}
+/** Shapes a raw batch entity's fields (see `BatchInfo` — fetched via `api`'s `fetchBatchInfo`) into `BatchStats`. */
+export declare function toBatchStats(raw: Partial<BatchInfo>): BatchStats;
+/**
+ * Computes the same `BatchStats` shape as `toBatchStats`, but by counting over a set of
+ * already-`simplifySession`-shaped sessions (`sessions/session`) instead of reading the
+ * (eventually consistent) batch aggregate — so it's always current, at the cost of only
+ * reflecting whatever subset of sessions `sessions` contains (the whole batch, or an
+ * already-filtered slice of it).
+ *
+ * Takes `SimplifiedSession[]`, not raw sessions, for two reasons: it reuses whatever
+ * `simplifySession` call the caller already made (e.g. to also build a session listing)
+ * instead of re-simplifying every session a second time just for this; and it counts a
+ * step's `resolution`/`isUnsaved` exactly as `simplifySession` derived them, with no second,
+ * possibly-diverging notion of what "resolved" means computed from the raw
+ * `appOutputResolution` fields directly. Every entry in `sessions` must have been simplified
+ * with `steps` included (the default) — one shaped with `{ includeSteps: false }` (`steps:
+ * null`) would silently contribute 0 to every step-level count.
+ */
+export declare function computeBatchStats(sessions: SimplifiedSession[]): BatchStats;
+export declare const BATCH_FILTERS: readonly ["unresolved", "unsaved", "mismatching"];
+export type BatchFilter = (typeof BATCH_FILTERS)[number];
+/**
+ * Narrows `sessions` to those matching `filter` — every session, unfiltered, when `filter` is
+ * omitted. `"mismatching"` keeps only sessions with at least one step that's `isMatching: false`,
+ * missing a checkpoint (`checkpoint.id === null` — the test stopped capturing this checkpoint),
+ * or new (`baseline.id === null` — the test started capturing a checkpoint with no prior baseline
+ * to compare against) — a missing/new step still needs a decision even though its own
+ * `isMatching` isn't a reliable signal either way, so it counts regardless of what `isMatching`
+ * reads. Also regardless of a step's own `resolution`: `isMatching` is fixed at comparison time
+ * and never changes afterward, including once a step is accepted/rejected and saved to the
+ * baseline, so it stays a reliable "did this ever differ" signal rather than one a decision
+ * clears. Requires `sessions` to have been simplified with `steps` included (the default); one
+ * shaped with `{ includeSteps: false }` never matches (`steps` is `null`).
+ */
+export declare function filterSessions(sessions: SimplifiedSession[], filter?: BatchFilter): SimplifiedSession[];

package/types/sessions/diffs.d.ts

@@ -0,0 +1,26 @@
+import { type Rect } from '../geometry/geometry.js';
+export interface DiffArea extends Rect {
+    diffCount: number;
+}
+/**
+ * Returns coarse page areas containing diffs. Each rect is expanded to at least
+ * `hPad`×`vPad` (centered) before checking for overlap; overlapping inflated rects
+ * are merged into the bounding rect of their originals (not the inflated ones).
+ */
+export declare function diffAreas(rects: Rect[], hPad?: number, vPad?: number): DiffArea[];
+/**
+ * Condenses a large number of DiffAreas into grouped ContainerDiffArea objects.
+ * When the number of areas is <= threshold, returns the original array unchanged.
+ *
+ * Each area is assigned to every grid cell it overlaps. A cell is dense when the
+ * total area of diff pixels covering it meets DENSE_COVERAGE (ratio to cell area).
+ * Dense cells are flood-filled into connected components, each producing a single
+ * ContainerDiffArea bounding box. Adjacent containers (gap ≤ 1 cell, or one contains
+ * the other) are merged. Finally, any unclaimed area whose rect falls completely inside
+ * a container is absorbed into it.
+ */
+export declare function condenseDiffAreas(areas: DiffArea[], threshold?: number): DiffArea[];
+export declare function condenseDiffAreasDetailed(areas: DiffArea[], threshold?: number): {
+    containers: DiffArea[];
+    individuals: DiffArea[];
+};

package/types/sessions/dom-history.d.ts

@@ -0,0 +1,119 @@
+import { type DomAlignment } from './dom.js';
+/** One older DOM capture to compare a suspect node against — labeled and dated, but otherwise
+ * agnostic to where it came from (a past test session today; possibly a past baseline version
+ * later — see this package's README). Despite the name, this is always a *checkpoint* DOM in
+ * the Visual Testing sense (the actual rendering of some past run), never a "baseline" (the
+ * expected/reference image) in that sense — "historic" here is about *when* the capture
+ * happened, an entirely different axis. `step` is an opaque, caller-constructed reference back
+ * to where this capture came from — e.g. `eyes-inspect`'s `history.ts` builds it as
+ * `<batchId>/<sessionId>/<stepIndex>` so the reader can navigate back to that exact step; this
+ * module never inspects or parses it, only carries it through to the output. `domId` identifies
+ * this capture to `FetchAlignmentDeps.fetchAlignment` — always passed as its baseline-role
+ * argument — see `HistoricDomNodeDiffEntry`, whose own `baselineStep`/`baselineCapturedAt`
+ * fields are copied from here and named to match. */
+export interface HistoricDom {
+    step: string;
+    capturedAt: string;
+    domId: string;
+}
+/** One non-empty diff for a suspect node against one older historic version. `checkpointStep`/
+ * `checkpointCapturedAt` and `baselineStep`/`baselineCapturedAt` identify and date the two sides
+ * actually compared for this entry — the tracker's anchor at the time (the current step, on the
+ * first hop that ever produces a diff; an intermediate historic version thereafter) and the
+ * `HistoricDom` it was diffed against, respectively. `baselineStep`/`baselineCapturedAt` are
+ * named to match the `diff` string's own embedded `"baseline"` key (`serializeDiff`
+ * always labels its first/older argument that way), so the two agree rather than
+ * describing the same referent with two different words — but neither side is a literal Visual
+ * Testing baseline; both are checkpoint DOMs, just from different points in time. */
+export interface HistoricDomNodeDiffEntry {
+    checkpointStep: string;
+    checkpointCapturedAt: string;
+    baselineStep: string;
+    baselineCapturedAt: string;
+    diff: string;
+}
+export interface HistoricDomNodeEvidence {
+    nodeId: string;
+    diffs: HistoricDomNodeDiffEntry[];
+}
+/** Mutable per-node accumulator threaded through repeated `applyHistoricDom` calls. */
+export interface HistoricDomNodeTracker {
+    nodeId: string;
+    /** The most recently matched node id/domId pair — the chain's current position. Seeded from
+     * the current step; only ever moves when a hop actually finds a counterpart for it. A hop
+     * that finds none leaves this untouched, so the same anchor is retried against the next
+     * (older) historic candidate rather than falling back to some other reference point. Kept as
+     * a plain id, not the node object itself — the object is never needed again once
+     * `extractNodeDiff` has used it to read the match/rect it needs off the alignment. */
+    anchorDomId: string;
+    anchorNodeId: string;
+    /** Identifies/dates whatever `anchorNodeId` currently refers to — the current step at first,
+     * then whichever historic version the anchor most recently advanced to. Copied onto a diff
+     * entry's `checkpointStep`/`checkpointCapturedAt` so the newer side of a comparison is
+     * traceable even when it isn't the current step (e.g. after the anchor has advanced past one
+     * or more hops, or held through a skipped miss). */
+    anchorStep: string;
+    anchorCapturedAt: string;
+    diffs: HistoricDomNodeDiffEntry[];
+}
+/**
+ * The one piece of I/O `applyHistoricDom` needs — aligning two already-identified DOM captures
+ * by `domId` — injected rather than imported directly, since this package has no network or
+ * filesystem awareness of its own. A caller wires this to whatever aligns-and-caches two domIds
+ * for it (e.g. `api`'s `fetchDomDiff`/`checkDomDiffTask` driven to a ready alignment, closed over
+ * its own `baseUrl`/`keys`); no default is provided here, since no such implementation is within
+ * this package's own reach.
+ */
+export interface FetchAlignmentDeps {
+    fetchAlignment: (baselineDomId: string, checkpointDomId: string) => Promise<DomAlignment>;
+}
+/**
+ * Seeds one tracker per suspect nodeId, anchored at `currentDomId`. Doesn't verify the nodeId
+ * actually exists in the current DOM — that would need fetching the whole tree just to check one
+ * id — so a bad id is simply carried through and only surfaces once (if) a real historic
+ * candidate is actually walked (`applyHistoricDom` catches it there for free, off an alignment it
+ * already has to compute). `currentStep`/`currentCapturedAt` identify and date the tracker's
+ * initial anchor, so the very first diff entry (if any) correctly attributes its checkpoint side
+ * to the current step rather than leaving it implicit.
+ */
+export declare function createHistoricDomNodeTrackers(currentDomId: string, nodeIds: string[], currentStep: string, currentCapturedAt: string): HistoricDomNodeTracker[];
+/**
+ * Applies exactly one older `HistoricDom` to every tracker that still has fewer than
+ * `targetDiffCount` non-empty diffs, mutating each in place — the unit of lazy evaluation a
+ * caller feeds historic DOMs into one at a time as it discovers them (see `history.ts`'s
+ * `walkHistoricSources`), so it can stop pulling further history the moment every tracker has
+ * enough evidence, rather than pre-fetching a fixed batch before knowing how much is needed.
+ *
+ * Each hop diffs a tracker's current anchor against `historicDom.domId` via a *global* alignment
+ * between the two full trees (`deps.fetchAlignment`/`extractNodeDiff`), not a standalone search
+ * for the anchor alone — a single-node content search would chase a content lookalike elsewhere
+ * on the page (e.g. a rotating carousel slot, or a live counter) rather than the element that
+ * actually took its place. When the alignment finds a counterpart, that counterpart becomes the
+ * anchor for the next (older) hop, so the walk tracks the same structural slot across a long
+ * history one hop at a time. Trackers sharing the same anchor domId are aligned against
+ * `historicDom.domId` together, once, via `groupByAnchorDomId` — the alignment itself doesn't
+ * depend on which specific node is being asked about, only on the pair of domIds, so paying for
+ * it once per distinct pair rather than once per tracker avoids pure waste (and, since
+ * `deps.fetchAlignment` is typically itself cached by domId pair, this also means a hop already
+ * paid for elsewhere — e.g. by `eyes_inspect_dom_diff`'s own two-sided diff — is never
+ * recomputed here either).
+ *
+ * When a hop's alignment finds no counterpart for the current anchor, that doesn't mean the
+ * anchor itself is wrong — it may just mean this one historic candidate is a poor comparison
+ * point (an unrelated element elsewhere on the page stealing the alignment's matching capacity,
+ * a transient loading state, and so on). Rather than reverting to some other reference node,
+ * a miss is simply skipped: nothing is recorded, and the anchor is left untouched, so the very
+ * same anchor is retried against the next (older) candidate the next time this is called. The
+ * chain resumes forward from wherever it next finds a match.
+ *
+ * A tracker whose `anchorNodeId` doesn't exist at all in whichever tree just played the
+ * checkpoint role (`extractNodeDiff`'s `found: false`) is different from a poor-comparison miss —
+ * that's `createHistoricDomNodeTrackers` never having verified the caller's nodeId, surfacing now
+ * for the first time. Every such tracker across the whole call is collected and reported in one
+ * combined error, rather than silently left to retry forever.
+ */
+export declare function applyHistoricDom(trackers: HistoricDomNodeTracker[], historicDom: HistoricDom, targetDiffCount: number, deps: FetchAlignmentDeps): Promise<void>;
+/** Strips tracker-only bookkeeping (the chain anchor) down to the plain
+ * `{nodeId, diffs: [{checkpointStep, checkpointCapturedAt, baselineStep, baselineCapturedAt, diff}]}`
+ * output shape. */
+export declare function finalizeHistoricDomNodeEvidence(trackers: HistoricDomNodeTracker[]): HistoricDomNodeEvidence[];

package/types/sessions/dom-search.d.ts

@@ -0,0 +1,113 @@
+type RelKind = 'descendant' | 'ancestor' | 'child' | 'parent' | 'sibling' | 'nthChild';
+type RelTarget = {
+    type: 'id';
+    id: string;
+} | {
+    type: 'expr';
+    ast: PredicateAST;
+};
+type BoundsTarget = {
+    type: 'id';
+    id: string;
+} | {
+    type: 'point';
+    x: number;
+    y: number;
+} | {
+    type: 'rect';
+    rect: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+};
+type SizeOpKind = 'larger' | 'smaller' | 'wider' | 'narrower' | 'taller' | 'shorter';
+type SizeTarget = {
+    type: 'id';
+    id: string;
+} | {
+    type: 'rect';
+    rect: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+} | {
+    type: 'size';
+    width: number;
+    height: number;
+} | {
+    type: 'value';
+    value: number;
+};
+type DirOpKind = 'above' | 'below' | 'leftOf' | 'rightOf';
+type DirTarget = {
+    type: 'id';
+    id: string;
+} | {
+    type: 'rect';
+    rect: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+};
+type CompareOpKey = 'eq' | 'neq' | 'lt' | 'lte' | 'gt' | 'gte' | 'startsWith' | 'endsWith' | 'contains' | 'in' | 'regex';
+export type PredicateAST = {
+    type: 'or';
+    left: PredicateAST;
+    right: PredicateAST;
+} | {
+    type: 'and';
+    left: PredicateAST;
+    right: PredicateAST;
+} | {
+    type: 'not';
+    inner: PredicateAST;
+} | {
+    type: 'bounds';
+    op: 'contains' | 'intersects' | 'containedBy';
+    target: BoundsTarget;
+} | {
+    type: 'rel';
+    kind: RelKind;
+    ordinal?: number;
+    target: RelTarget;
+} | {
+    type: 'size';
+    kind: SizeOpKind;
+    target: SizeTarget;
+} | {
+    type: 'dir';
+    kind: DirOpKind;
+    target: DirTarget;
+} | {
+    type: 'prop';
+    path: string[];
+    op: CompareOpKey;
+    value: string | string[] | RegExp;
+} | {
+    type: 'nullary';
+    name: string;
+} | {
+    type: 'hasAttr';
+    name: string;
+};
+export declare function parsePredicate(source: string): PredicateAST;
+export declare function astNeedsIndex(ast: PredicateAST): boolean;
+/**
+ * Searches a DOM capture for elements matching a boolean predicate. See `llm-docs/dom-search.md`
+ * in this package (shipped in the tarball) for the full predicate language documentation (grammar,
+ * operators, examples) — that file is the canonical, copy-paste-friendly source; don't re-describe
+ * the grammar here or anywhere else, keep it in sync by editing it and copying it where it's
+ * needed instead.
+ *
+ * @param domCaptureJson Raw JSON text of a DOM capture file (as written by eyes-inspect's `dom` command) — a single node, or an array of nodes.
+ * @param predicateSource The predicate string described in `llm-docs/dom-search.md`.
+ * @returns One line per matching element, most indented lines the deepest — each line is that element's own properties (minus `childNodes`) as JSON, with a trailing `# <text>` comment when it has non-empty text.
+ */
+export declare function searchDom(domCaptureJson: string, predicateSource: string): string;
+export {};