@applitools/eyes-results 0.2.0

package/dist/lib/phase-tracker.js

@@ -0,0 +1,223 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import * as crypto from 'crypto';
+const RETRYABLE_CODES = new Set(['EBUSY', 'EPERM', 'EACCES', 'EAGAIN']);
+const RETRY_ATTEMPTS = 5;
+const RETRY_BASE_DELAY_MS = 20;
+/**
+ * A synchronous blocking sleep (`Atomics.wait` against a throwaway shared buffer) — matches
+ * the rest of this codebase's synchronous fs style (`fs.readFileSync`/`writeFileSync`
+ * throughout `commands.ts`), rather than forcing every phase-tracker call to be async merely
+ * to await a short backoff delay.
+ */
+function busyWaitSleep(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+export const defaultPhaseTrackerDeps = {
+    readFile: p => (fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : null),
+    writeFile: (p, contents) => fs.writeFileSync(p, contents),
+    appendFile: (p, contents) => fs.appendFileSync(p, contents),
+    deleteFile: p => fs.rmSync(p, { force: true }),
+    mkdir: dir => fs.mkdirSync(dir, { recursive: true }),
+    sleep: busyWaitSleep,
+    stateDir: path.join(os.tmpdir(), 'eyes-resolve'),
+};
+/**
+ * Retries `fn` on a transient file-lock error (a momentarily-locked file must never crash a
+ * workflow call — see `lib.md`), with a short exponential backoff between attempts. Any other
+ * error (including a non-`Error` throw with no `.code`) propagates immediately, unretried.
+ */
+function withRetry(fn, deps) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            return fn();
+        }
+        catch (error) {
+            const code = error?.code;
+            if (attempt >= RETRY_ATTEMPTS - 1 || !code || !RETRYABLE_CODES.has(code))
+                throw error;
+            deps.sleep(RETRY_BASE_DELAY_MS * 2 ** attempt);
+        }
+    }
+}
+function hashId(id) {
+    return crypto.createHash('sha256').update(id).digest('hex');
+}
+// path.posix.join/dirname (not path.join/dirname) so the result is deterministic across
+// platforms — Node's fs APIs accept forward slashes on Windows too (same convention as
+// `api/fs-cache.ts`'s `cacheFilePath`).
+function recordPath(deps, kind, id) {
+    return path.posix.join(deps.stateDir, kind, `${hashId(id)}.json`);
+}
+function readJson(deps, filePath) {
+    const contents = withRetry(() => deps.readFile(filePath), deps);
+    return contents === null ? undefined : JSON.parse(contents);
+}
+function writeJson(deps, filePath, value) {
+    withRetry(() => deps.mkdir(path.posix.dirname(filePath)), deps);
+    withRetry(() => deps.writeFile(filePath, JSON.stringify(value)), deps);
+}
+/** The recorded completion for `id`, or `undefined` if `<level>_end` was never (successfully) called for it. */
+export function getCompletion(id, deps = defaultPhaseTrackerDeps) {
+    return readJson(deps, recordPath(deps, 'completions', id));
+}
+export function isCompleted(id, deps = defaultPhaseTrackerDeps) {
+    return getCompletion(id, deps) !== undefined;
+}
+/**
+ * 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 function recordCompletion(id, payload, deps = defaultPhaseTrackerDeps) {
+    const completion = { payload, completedAt: new Date().toISOString() };
+    writeJson(deps, recordPath(deps, 'completions', id), completion);
+    return completion;
+}
+/** `parentId`'s full accumulated child-findings record, read as-is with no live-data filtering. `{}` if no child has ever reported into it. */
+export function getChildFindings(parentId, deps = defaultPhaseTrackerDeps) {
+    return readJson(deps, recordPath(deps, 'child-findings', parentId)) ?? {};
+}
+/**
+ * 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 function appendChildFinding(parentId, childId, payload, deps = defaultPhaseTrackerDeps) {
+    const record = getChildFindings(parentId, deps);
+    record[childId] = payload;
+    writeJson(deps, recordPath(deps, 'child-findings', parentId), record);
+}
+/** Appends one entry to `scopeId`'s invocation log — called as a side effect of every eyes-inspect data tool. */
+export function logInvocation(scopeId, toolName, args, deps = defaultPhaseTrackerDeps) {
+    const filePath = recordPath(deps, 'invocations', scopeId);
+    const log = readJson(deps, filePath) ?? [];
+    log.push({ toolName, args, at: new Date().toISOString() });
+    writeJson(deps, filePath, log);
+}
+/** 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 function verifyInvocation(scopeId, toolName, matcher, deps = defaultPhaseTrackerDeps) {
+    const log = readJson(deps, recordPath(deps, 'invocations', scopeId)) ?? [];
+    return log.some(entry => entry.toolName === toolName && matcher(entry.args));
+}
+/** 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 function recordScopeMode(scopeId, mode, deps = defaultPhaseTrackerDeps) {
+    writeJson(deps, recordPath(deps, 'modes', scopeId), mode);
+}
+/** The mode last recorded for `scopeId` via `recordScopeMode`, or `undefined` if never recorded. */
+export function getScopeMode(scopeId, deps = defaultPhaseTrackerDeps) {
+    return readJson(deps, recordPath(deps, 'modes', scopeId));
+}
+/** Discards `id`'s completion, as if `recordCompletion` had never been called for it. */
+export function clearCompletion(id, deps = defaultPhaseTrackerDeps) {
+    withRetry(() => deps.deleteFile(recordPath(deps, 'completions', id)), deps);
+}
+/** Discards `parentId`'s entire accumulated child-findings record — every child's entry, not just one. */
+export function clearChildFindings(parentId, deps = defaultPhaseTrackerDeps) {
+    withRetry(() => deps.deleteFile(recordPath(deps, 'child-findings', parentId)), deps);
+}
+/** Discards `scopeId`'s recorded mode, as if `recordScopeMode` had never been called for it. */
+export function clearScopeMode(scopeId, deps = defaultPhaseTrackerDeps) {
+    withRetry(() => deps.deleteFile(recordPath(deps, 'modes', scopeId)), deps);
+}
+/** 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 function recordUnreadyChildren(scopeId, childKeys, deps = defaultPhaseTrackerDeps) {
+    writeJson(deps, recordPath(deps, 'unready-children', scopeId), childKeys);
+}
+/** The child keys `recordUnreadyChildren` last recorded as unready for `scopeId`, or `[]` if never recorded. */
+export function getUnreadyChildren(scopeId, deps = defaultPhaseTrackerDeps) {
+    return readJson(deps, recordPath(deps, 'unready-children', scopeId)) ?? [];
+}
+/** Discards `scopeId`'s recorded unready-children snapshot, as if `recordUnreadyChildren` had never been called for it. */
+export function clearUnreadyChildren(scopeId, deps = defaultPhaseTrackerDeps) {
+    withRetry(() => deps.deleteFile(recordPath(deps, 'unready-children', scopeId)), deps);
+}
+/** `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 function getQueuedChildKeys(scopeId, deps = defaultPhaseTrackerDeps) {
+    return readJson(deps, recordPath(deps, 'children', scopeId)) ?? [];
+}
+/**
+ * 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 function queueChildKeys(scopeId, liveKeys, deps = defaultPhaseTrackerDeps) {
+    const existing = getQueuedChildKeys(scopeId, deps);
+    const existingSet = new Set(existing);
+    const fresh = liveKeys.filter(k => !existingSet.has(k));
+    if (fresh.length === 0)
+        return existing;
+    const merged = [...existing, ...fresh];
+    writeJson(deps, recordPath(deps, 'children', scopeId), merged);
+    return merged;
+}
+/** Discards `scopeId`'s entire queued-children record, as if nothing had ever been queued for it. */
+export function clearQueuedChildKeys(scopeId, deps = defaultPhaseTrackerDeps) {
+    withRetry(() => deps.deleteFile(recordPath(deps, 'children', scopeId)), deps);
+}
+/**
+ * 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 function recordDiscoveredChildren(scopeId, payload, deps = defaultPhaseTrackerDeps) {
+    writeJson(deps, recordPath(deps, 'discovered-children', scopeId), payload);
+}
+/** What `recordDiscoveredChildren` last recorded for `scopeId`, or `undefined` if never recorded. */
+export function getDiscoveredChildren(scopeId, deps = defaultPhaseTrackerDeps) {
+    return readJson(deps, recordPath(deps, 'discovered-children', scopeId));
+}
+/** Discards `scopeId`'s recorded discovery, as if `recordDiscoveredChildren` had never been called for it. */
+export function clearDiscoveredChildren(scopeId, deps = defaultPhaseTrackerDeps) {
+    withRetry(() => deps.deleteFile(recordPath(deps, 'discovered-children', scopeId)), deps);
+}
+function debugLogDir(deps) {
+    return path.posix.join(deps.stateDir, 'debug');
+}
+/**
+ * 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 function getLogFilePath(scopeId, deps = defaultPhaseTrackerDeps) {
+    return path.posix.join(debugLogDir(deps), `${hashId(scopeId)}.log`);
+}
+/**
+ * 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 function log(scopeId, label, fields = {}, deps = defaultPhaseTrackerDeps) {
+    const entry = { at: new Date().toISOString(), label, ...fields };
+    withRetry(() => deps.mkdir(debugLogDir(deps)), deps);
+    withRetry(() => deps.appendFile(getLogFilePath(scopeId, deps), `${JSON.stringify(entry)}\n`), deps);
+}

package/dist/sessions/batch.js

@@ -0,0 +1,98 @@
+/** Shapes a raw batch entity's fields (see `BatchInfo` — fetched via `api`'s `fetchBatchInfo`) into `BatchStats`. */
+export function toBatchStats(raw) {
+    return {
+        total: (raw.completedCount ?? 0) + (raw.runningCount ?? 0) + (raw.abortedCount ?? 0),
+        unresolved: raw.unresolvedCount ?? 0,
+        passed: raw.passedCount ?? 0,
+        failed: raw.failedCount ?? 0,
+        aborted: raw.abortedCount ?? 0,
+        unsaved: raw.changedCount ?? 0,
+        totalSteps: raw.stepsCount ?? 0,
+        unresolvedSteps: raw.unresolvedStepsCount ?? 0,
+        unsavedSteps: raw.changedStepsCount ?? 0,
+        missingSteps: raw.missingStepsCount ?? 0,
+        newSteps: raw.newStepsCount ?? 0,
+    };
+}
+/**
+ * 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 function computeBatchStats(sessions) {
+    const stats = {
+        total: sessions.length,
+        unresolved: 0,
+        passed: 0,
+        failed: 0,
+        aborted: 0,
+        unsaved: 0,
+        totalSteps: 0,
+        unresolvedSteps: 0,
+        unsavedSteps: 0,
+        missingSteps: 0,
+        newSteps: 0,
+    };
+    for (const session of sessions) {
+        const status = (session.status ?? '').toLowerCase();
+        if (status === 'unresolved')
+            stats.unresolved++;
+        else if (status === 'passed')
+            stats.passed++;
+        else if (status === 'failed')
+            stats.failed++;
+        if (session.isAborted)
+            stats.aborted++;
+        if (session.isUnsaved)
+            stats.unsaved++;
+        for (const step of session.steps ?? []) {
+            stats.totalSteps++;
+            if (!step.isMatching && step.resolution === 'none')
+                stats.unresolvedSteps++;
+            if (step.isUnsaved)
+                stats.unsavedSteps++;
+            if (step.checkpoint.id === null)
+                stats.missingSteps++;
+            if (step.baseline.id === null)
+                stats.newSteps++;
+        }
+    }
+    return stats;
+}
+// ---------------------------------------------------------------------------
+// Session-level filtering
+// ---------------------------------------------------------------------------
+export const BATCH_FILTERS = ['unresolved', 'unsaved', 'mismatching'];
+/**
+ * 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 function filterSessions(sessions, filter) {
+    if (!filter)
+        return sessions;
+    if (filter === 'unresolved')
+        return sessions.filter(s => s.status.toLowerCase() === 'unresolved');
+    if (filter === 'unsaved')
+        return sessions.filter(s => s.isUnsaved);
+    return sessions.filter(s => (s.steps ?? []).some(step => !step.isMatching || step.checkpoint.id === null || step.baseline.id === null));
+}

package/dist/sessions/diffs.js

@@ -0,0 +1,210 @@
+import { rectContains, rectsIntersect, boundingRect } from '../geometry/geometry.js';
+/**
+ * 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 function diffAreas(rects, hPad = 50, vPad = 25) {
+    let result = rects.map(r => ({ ...r, diffCount: 1 }));
+    let merged = true;
+    while (merged) {
+        merged = false;
+        const inflated = result.map((r) => {
+            const w = Math.max(r.width, hPad);
+            const h = Math.max(r.height, vPad);
+            return { left: r.left + (r.width - w) / 2, top: r.top + (r.height - h) / 2, width: w, height: h };
+        });
+        outer: for (let i = 0; i < result.length; i++) {
+            for (let j = i + 1; j < result.length; j++) {
+                if (rectsIntersect(inflated[i], inflated[j])) {
+                    const mergedRect = {
+                        ...boundingRect(result[i], result[j]),
+                        diffCount: result[i].diffCount + result[j].diffCount,
+                    };
+                    result = [...result.slice(0, i), ...result.slice(i + 1, j), ...result.slice(j + 1), mergedRect];
+                    merged = true;
+                    break outer;
+                }
+            }
+        }
+    }
+    return result;
+}
+const COL_WIDTH = 200; // target column width; numCols = round(boundsWidth / COL_WIDTH)
+const ROW_HEIGHT = 700; // target row height;  numRows = round(boundsHeight / ROW_HEIGHT)
+const DENSE_COVERAGE = 0.3; // min ratio of diff pixel coverage to cell area to mark a cell dense
+const MAX_MERGE_GAP_ROWS = 1;
+const MAX_MERGE_GAP_COLS = 1;
+function cellKey(row, col) {
+    return `${row},${col}`;
+}
+function parseKey(key) {
+    const [row, col] = key.split(',').map(Number);
+    return [row, col];
+}
+/**
+ * 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 function condenseDiffAreas(areas, threshold = 20) {
+    const { containers, individuals } = condenseDiffAreasDetailed(areas, threshold);
+    return [...containers, ...individuals];
+}
+export function condenseDiffAreasDetailed(areas, threshold = 20) {
+    if (areas.length <= threshold)
+        return { containers: [], individuals: areas };
+    // Compute bounding rect of all diff areas and derive a uniform grid.
+    // numCols/numRows are chosen so each cell is as close to COL_WIDTH × ROW_HEIGHT as possible;
+    // edge cells are never narrow/short because the grid divides the bounds evenly.
+    const boundsLeft = Math.min(...areas.map(a => a.left));
+    const boundsTop = Math.min(...areas.map(a => a.top));
+    const boundsRight = Math.max(...areas.map(a => a.left + a.width));
+    const boundsBottom = Math.max(...areas.map(a => a.top + a.height));
+    const boundsWidth = boundsRight - boundsLeft;
+    const boundsHeight = boundsBottom - boundsTop;
+    const numCols = Math.max(1, Math.round(boundsWidth / COL_WIDTH));
+    const numRows = Math.max(1, Math.round(boundsHeight / ROW_HEIGHT));
+    const colW = Math.max(1, boundsWidth / numCols);
+    const rowH = Math.max(1, boundsHeight / numRows);
+    const cellArea = colW * rowH;
+    // Assign each area to every cell it overlaps; accumulate intersection pixel area per cell
+    const cellCoverage = new Map();
+    for (const a of areas) {
+        const colMin = Math.max(0, Math.floor((a.left - boundsLeft) / colW));
+        const colMax = Math.min(numCols - 1, Math.ceil((a.left + a.width - boundsLeft) / colW) - 1);
+        const rowMin = Math.max(0, Math.floor((a.top - boundsTop) / rowH));
+        const rowMax = Math.min(numRows - 1, Math.ceil((a.top + a.height - boundsTop) / rowH) - 1);
+        for (let row = rowMin; row <= rowMax; row++) {
+            for (let col = colMin; col <= colMax; col++) {
+                const cellLeft = boundsLeft + col * colW;
+                const cellTop = boundsTop + row * rowH;
+                const iW = Math.min(a.left + a.width, cellLeft + colW) - Math.max(a.left, cellLeft);
+                const iH = Math.min(a.top + a.height, cellTop + rowH) - Math.max(a.top, cellTop);
+                const iArea = Math.max(0, iW) * Math.max(0, iH);
+                if (iArea > 0) {
+                    const key = cellKey(row, col);
+                    cellCoverage.set(key, (cellCoverage.get(key) ?? 0) + iArea);
+                }
+            }
+        }
+    }
+    // Mark cells whose coverage ratio meets the density threshold
+    const denseCells = new Set();
+    for (const [key, coverage] of cellCoverage) {
+        if (coverage / cellArea >= DENSE_COVERAGE)
+            denseCells.add(key);
+    }
+    // 4-connected flood-fill over dense cells into components
+    const visited = new Set();
+    const components = [];
+    for (const startKey of denseCells) {
+        if (visited.has(startKey))
+            continue;
+        const component = new Set();
+        const queue = [startKey];
+        while (queue.length > 0) {
+            const key = queue.pop();
+            if (visited.has(key))
+                continue;
+            visited.add(key);
+            component.add(key);
+            const [row, col] = parseKey(key);
+            for (const [dr, dc] of [
+                [-1, 0],
+                [1, 0],
+                [0, -1],
+                [0, 1],
+            ]) {
+                const neighborKey = cellKey(row + dr, col + dc);
+                if (denseCells.has(neighborKey) && !visited.has(neighborKey)) {
+                    queue.push(neighborKey);
+                }
+            }
+        }
+        components.push(component);
+    }
+    // For each component, claim every area that overlaps any cell in the component
+    const claimed = new Set();
+    const containers = [];
+    for (const component of components) {
+        const collectedIndices = [];
+        for (let i = 0; i < areas.length; i++) {
+            const a = areas[i];
+            const colMin = Math.max(0, Math.floor((a.left - boundsLeft) / colW));
+            const colMax = Math.min(numCols - 1, Math.ceil((a.left + a.width - boundsLeft) / colW) - 1);
+            const rowMin = Math.max(0, Math.floor((a.top - boundsTop) / rowH));
+            const rowMax = Math.min(numRows - 1, Math.ceil((a.top + a.height - boundsTop) / rowH) - 1);
+            let found = false;
+            outer: for (let row = rowMin; row <= rowMax; row++) {
+                for (let col = colMin; col <= colMax; col++) {
+                    if (component.has(cellKey(row, col))) {
+                        found = true;
+                        break outer;
+                    }
+                }
+            }
+            if (found)
+                collectedIndices.push(i);
+        }
+        if (collectedIndices.length === 0)
+            continue;
+        for (const idx of collectedIndices)
+            claimed.add(idx);
+        let left = Infinity, top = Infinity, right = -Infinity, bottom = -Infinity;
+        let totalDiffCount = 0;
+        for (const idx of collectedIndices) {
+            const a = areas[idx];
+            left = Math.min(left, a.left);
+            top = Math.min(top, a.top);
+            right = Math.max(right, a.left + a.width);
+            bottom = Math.max(bottom, a.top + a.height);
+            totalDiffCount += a.diffCount;
+        }
+        containers.push({ left, top, width: right - left, height: bottom - top, diffCount: totalDiffCount });
+    }
+    // Merge containers that are gap-adjacent (≤ 1 cell in either axis) or where one contains the other
+    let anyMerge = true;
+    while (anyMerge) {
+        anyMerge = false;
+        outer: for (let i = 0; i < containers.length; i++) {
+            for (let j = i + 1; j < containers.length; j++) {
+                const a = containers[i];
+                const b = containers[j];
+                const hGap = Math.max(0, Math.max(a.left, b.left) - Math.min(a.left + a.width, b.left + b.width));
+                const vGap = Math.max(0, Math.max(a.top, b.top) - Math.min(a.top + a.height, b.top + b.height));
+                const contained = rectContains(a, b) || rectContains(b, a);
+                if (!contained && (hGap > MAX_MERGE_GAP_COLS * colW || vGap > MAX_MERGE_GAP_ROWS * rowH))
+                    continue;
+                const left = Math.min(a.left, b.left);
+                const top = Math.min(a.top, b.top);
+                const right = Math.max(a.left + a.width, b.left + b.width);
+                const bottom = Math.max(a.top + a.height, b.top + b.height);
+                containers.splice(j, 1);
+                containers.splice(i, 1);
+                containers.push({ left, top, width: right - left, height: bottom - top, diffCount: a.diffCount + b.diffCount });
+                anyMerge = true;
+                break outer;
+            }
+        }
+    }
+    // Absorb any unclaimed area whose rect falls completely within a container
+    for (let i = 0; i < areas.length; i++) {
+        if (claimed.has(i))
+            continue;
+        for (const container of containers) {
+            if (rectContains(container, areas[i])) {
+                container.diffCount += areas[i].diffCount;
+                claimed.add(i);
+                break;
+            }
+        }
+    }
+    return { containers, individuals: areas.filter((_, i) => !claimed.has(i)) };
+}

package/dist/sessions/dom-history.js

@@ -0,0 +1,107 @@
+import { extractNodeDiff } from './dom.js';
+/**
+ * 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 function createHistoricDomNodeTrackers(currentDomId, nodeIds, currentStep, currentCapturedAt) {
+    return nodeIds.map(nodeId => ({
+        nodeId,
+        anchorDomId: currentDomId,
+        anchorNodeId: nodeId,
+        anchorStep: currentStep,
+        anchorCapturedAt: currentCapturedAt,
+        diffs: [],
+    }));
+}
+/** Groups trackers by their shared anchor domId so the caller can align a historic capture
+ * against that domId once and reuse it for every tracker in the group, instead of once per
+ * tracker. */
+function groupByAnchorDomId(trackers) {
+    const groups = new Map();
+    for (const tracker of trackers) {
+        const group = groups.get(tracker.anchorDomId);
+        if (group)
+            group.push(tracker);
+        else
+            groups.set(tracker.anchorDomId, [tracker]);
+    }
+    return groups;
+}
+/**
+ * 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 async function applyHistoricDom(trackers, historicDom, targetDiffCount, deps) {
+    const active = trackers.filter(t => t.diffs.length < targetDiffCount);
+    const notFound = [];
+    for (const [anchorDomId, group] of groupByAnchorDomId(active)) {
+        const alignment = await deps.fetchAlignment(historicDom.domId, anchorDomId);
+        for (const tracker of group) {
+            const result = extractNodeDiff(alignment, tracker.anchorNodeId);
+            if (!result.found) {
+                notFound.push(tracker.nodeId);
+                continue;
+            }
+            if (!result.matchedNodeId)
+                continue; // poor comparison point — retry this same anchor next time
+            if (result.diff.length > 0) {
+                tracker.diffs.push({
+                    checkpointStep: tracker.anchorStep,
+                    checkpointCapturedAt: tracker.anchorCapturedAt,
+                    baselineStep: historicDom.step,
+                    baselineCapturedAt: historicDom.capturedAt,
+                    diff: result.diff,
+                });
+            }
+            tracker.anchorNodeId = result.matchedNodeId;
+            tracker.anchorDomId = historicDom.domId;
+            tracker.anchorStep = historicDom.step;
+            tracker.anchorCapturedAt = historicDom.capturedAt;
+        }
+    }
+    if (notFound.length > 0) {
+        throw new Error(`Node id(s) not found in DOM snapshot: ${notFound.join(', ')}`);
+    }
+}
+/** Strips tracker-only bookkeeping (the chain anchor) down to the plain
+ * `{nodeId, diffs: [{checkpointStep, checkpointCapturedAt, baselineStep, baselineCapturedAt, diff}]}`
+ * output shape. */
+export function finalizeHistoricDomNodeEvidence(trackers) {
+    return trackers.map(({ nodeId, diffs }) => ({ nodeId, diffs }));
+}