agent-web-interface 4.0.0

package/dist/src/state/element-identity.js

@@ -0,0 +1,129 @@
+/**
+ * Element Identity
+ *
+ * Generate stable, semantic element IDs (eids) that survive DOM mutations.
+ * Uses semantic hashing instead of transient CDP backend_node_id.
+ */
+import { createHash } from 'crypto';
+// ============================================================================
+// EID Generation
+// ============================================================================
+/**
+ * Compute stable semantic element ID for a node.
+ *
+ * Uses hash of semantic components:
+ * - Role (or kind)
+ * - Accessible name (normalized label)
+ * - Href (for links)
+ * - Landmark path (region + group_path)
+ * - Layer context (modal vs main - prevents collision across layers)
+ * - Position hint (heading context from group_path - scroll-stable)
+ * - Shadow path (disambiguates elements in different shadow roots)
+ *
+ * @param node - Node to compute EID for
+ * @param layer - Optional layer context for disambiguation
+ * @returns 12-character hex hash
+ */
+export function computeEid(node, layer) {
+    // Shadow path ensures elements in different shadow roots get unique EIDs
+    // even if they have identical semantic properties
+    const shadowPath = node.find?.shadow_path?.join('/') ?? '';
+    const components = [
+        node.attributes?.role ?? node.kind,
+        normalizeAccessibleName(node.label),
+        node.attributes?.href ?? '',
+        computeLandmarkPath(node),
+        layer ?? computeLayerFromRegion(node),
+        computePositionHint(node),
+        shadowPath,
+    ];
+    return hashComponents(components);
+}
+/**
+ * Compute layer from node region.
+ * Used when explicit layer not provided.
+ *
+ * @param node - Node to check
+ * @returns Layer name
+ */
+function computeLayerFromRegion(node) {
+    const region = node.where.region ?? 'unknown';
+    return region === 'dialog' ? 'modal' : 'main';
+}
+/**
+ * Normalize accessible name for stable hashing.
+ * - Trim whitespace
+ * - Lowercase
+ * - Collapse multiple spaces
+ * - Cap length at 100 chars
+ *
+ * @param label - Raw label text
+ * @returns Normalized label
+ */
+export function normalizeAccessibleName(label) {
+    return label.trim().toLowerCase().replace(/\s+/g, ' ').substring(0, 100);
+}
+/**
+ * Compute landmark path for a node.
+ * Format: "region/group1/group2"
+ *
+ * @param node - Node to compute path for
+ * @returns Landmark path string
+ */
+export function computeLandmarkPath(node) {
+    const region = node.where.region ?? 'unknown';
+    const path = node.where.group_path ?? [];
+    return `${region}/${path.join('/')}`;
+}
+/**
+ * Compute position hint for stable EID disambiguation.
+ *
+ * Uses only scroll-stable semantic context:
+ * - Nearest heading from group_path (semantic grouping)
+ *
+ * Note: Viewport-dependent data (screen_zone, bbox quadrant) was removed
+ * because it caused EID instability when scrolling. The collision resolution
+ * mechanism (resolveEidCollision) handles any increased collision rate.
+ *
+ * @param node - Node to compute hint for
+ * @returns Position hint string
+ */
+export function computePositionHint(node) {
+    // Use last group from group_path as stable semantic context
+    const groupPath = node.where.group_path ?? [];
+    return groupPath.length > 0 ? groupPath[groupPath.length - 1] : '';
+}
+/**
+ * Hash string components to generate EID.
+ * Uses SHA-256 and returns first 12 hex chars.
+ *
+ * @param components - String components to hash
+ * @returns 12-character hex hash
+ */
+export function hashComponents(components) {
+    const combined = components.join('::');
+    const hash = createHash('sha256').update(combined).digest('hex');
+    return hash.substring(0, 12);
+}
+// ============================================================================
+// EID Collision Handling
+// ============================================================================
+/**
+ * Resolve EID collisions by appending suffix.
+ * If EID already exists in map, append "-2", "-3", etc.
+ *
+ * @param baseEid - Base EID before collision resolution
+ * @param existingEids - Set of already-used EIDs
+ * @returns Unique EID
+ */
+export function resolveEidCollision(baseEid, existingEids) {
+    if (!existingEids.has(baseEid)) {
+        return baseEid;
+    }
+    let suffix = 2;
+    while (existingEids.has(`${baseEid}-${suffix}`)) {
+        suffix++;
+    }
+    return `${baseEid}-${suffix}`;
+}
+//# sourceMappingURL=element-identity.js.map

package/dist/src/state/element-identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-identity.js","sourceRoot":"","sources":["../../../src/state/element-identity.ts"],"names":[],"mappings":"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"}

package/dist/src/state/element-ref.types.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Element Reference Types
+ *
+ * Core types for the ElementRef architecture that unifies element identification.
+ * ElementRef wires together stable semantic identity (eid) with actionable targeting data.
+ *
+ * Key principles:
+ * - `eid` is the stable semantic identity (survives DOM mutations)
+ * - `ref` contains targeting data for actual interactions
+ * - Actions resolve via eid → ref, never use eid directly as a click target
+ */
+/**
+ * ElementRef - Unified element reference with stable identity and actionable locators.
+ */
+export interface ElementRef {
+    /** Stable semantic identity - 12-char hash based on role+name+landmark+position */
+    eid: string;
+    /** Targeting reference - how to actually find/click this element */
+    ref: ElementTargetRef;
+}
+/**
+ * ElementTargetRef - Actual targeting data for an element.
+ * Contains multiple strategies for robustness.
+ */
+export interface ElementTargetRef {
+    /** Snapshot that produced this ref - for staleness detection */
+    snapshot_id: string;
+    /** CDP backend node ID - primary targeting method */
+    backend_node_id: number;
+    /** CDP frame ID - for cross-frame targeting */
+    frame_id: string;
+    /** CDP loader ID - changes on navigation, for staleness detection */
+    loader_id: string;
+    /** Locator strategies for fallback/re-resolution */
+    locators: ElementLocators;
+}
+/**
+ * ElementLocators - Multiple strategies for finding an element.
+ */
+export interface ElementLocators {
+    /** Preferred: AX tree locator (most stable) */
+    preferred: {
+        ax: string;
+    };
+    /** Fallback: CSS selector */
+    fallback?: {
+        css: string;
+    };
+}
+/**
+ * SnapshotHealth - Validation result for a snapshot.
+ * Used to detect and handle empty/failed snapshots.
+ */
+export interface SnapshotHealth {
+    /** Whether snapshot is usable for actions */
+    valid: boolean;
+    /** Reason for invalidity or partial status */
+    reason?: 'empty' | 'error' | 'partial';
+    /** Human-readable message */
+    message?: string;
+    /** Metrics for debugging */
+    metrics?: SnapshotHealthMetrics;
+}
+/**
+ * Snapshot health metrics for debugging.
+ */
+export interface SnapshotHealthMetrics {
+    node_count: number;
+    interactive_count: number;
+    capture_duration_ms?: number;
+}
+/**
+ * ClickOutcome - Result of a click action with navigation awareness.
+ * Differentiates between "element gone due to navigation" vs "element stale due to DOM mutation".
+ */
+export type ClickOutcome = ClickOutcomeSuccess | ClickOutcomeStaleElement | ClickOutcomeElementNotFound | ClickOutcomeError;
+/**
+ * Click succeeded, optionally with navigation.
+ */
+export interface ClickOutcomeSuccess {
+    status: 'success';
+    /** Whether the click triggered a page navigation */
+    navigated: boolean;
+}
+/**
+ * Element was stale (removed from DOM).
+ */
+export interface ClickOutcomeStaleElement {
+    status: 'stale_element';
+    /** Why the element became stale */
+    reason: 'dom_mutation' | 'navigation';
+    /** Whether retry was attempted */
+    retried: boolean;
+}
+/**
+ * Element not found by eid.
+ */
+export interface ClickOutcomeElementNotFound {
+    status: 'element_not_found';
+    /** The eid that wasn't found */
+    eid: string;
+    /** Last known label for debugging */
+    last_known_label?: string;
+}
+/**
+ * Error during click.
+ */
+export interface ClickOutcomeError {
+    status: 'error';
+    /** Error message */
+    message: string;
+}
+/**
+ * EidRegistry - Internal state for tracking eid → ElementRef mappings.
+ */
+export interface EidRegistry {
+    /** Map eid -> current ElementRef (updated on each snapshot) */
+    byEid: Map<string, ElementRef>;
+    /** Map snapshot_id:backend_node_id -> eid (reverse lookup) */
+    backendToEid: Map<string, string>;
+    /** Last seen step for each eid (for staleness detection) */
+    lastSeenStep: Map<string, number>;
+}
+/**
+ * Result of updating the registry with a new snapshot.
+ */
+export interface RegistryUpdateResult {
+    /** New eids added in this snapshot */
+    added: string[];
+    /** Eids no longer present (removed from DOM) */
+    removed: string[];
+    /** Eids that were updated with new targeting data */
+    updated: string[];
+}
+//# sourceMappingURL=element-ref.types.d.ts.map

package/dist/src/state/element-ref.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-ref.types.d.ts","sourceRoot":"","sources":["../../../src/state/element-ref.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,mFAAmF;IACnF,GAAG,EAAE,MAAM,CAAC;IAEZ,oEAAoE;IACpE,GAAG,EAAE,gBAAgB,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;IAEpB,qDAAqD;IACrD,eAAe,EAAE,MAAM,CAAC;IAExB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IAEjB,qEAAqE;IACrE,SAAS,EAAE,MAAM,CAAC;IAElB,oDAAoD;IACpD,QAAQ,EAAE,eAAe,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,+CAA+C;IAC/C,SAAS,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IAE1B,6BAA6B;IAC7B,QAAQ,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CAC5B;AAMD;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,6CAA6C;IAC7C,KAAK,EAAE,OAAO,CAAC;IAEf,8CAA8C;IAC9C,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;IAEvC,6BAA6B;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,4BAA4B;IAC5B,OAAO,CAAC,EAAE,qBAAqB,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAMD;;;GAGG;AACH,MAAM,MAAM,YAAY,GACpB,mBAAmB,GACnB,wBAAwB,GACxB,2BAA2B,GAC3B,iBAAiB,CAAC;AAEtB;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,SAAS,CAAC;IAClB,oDAAoD;IACpD,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,eAAe,CAAC;IACxB,mCAAmC;IACnC,MAAM,EAAE,cAAc,GAAG,YAAY,CAAC;IACtC,kCAAkC;IAClC,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,MAAM,EAAE,mBAAmB,CAAC;IAC5B,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,qCAAqC;IACrC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,OAAO,CAAC;IAChB,oBAAoB;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAMD;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,+DAA+D;IAC/D,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAE/B,8DAA8D;IAC9D,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAElC,4DAA4D;IAC5D,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,sCAAsC;IACtC,KAAK,EAAE,MAAM,EAAE,CAAC;IAEhB,gDAAgD;IAChD,OAAO,EAAE,MAAM,EAAE,CAAC;IAElB,qDAAqD;IACrD,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB"}

package/dist/src/state/element-ref.types.js

@@ -0,0 +1,13 @@
+/**
+ * Element Reference Types
+ *
+ * Core types for the ElementRef architecture that unifies element identification.
+ * ElementRef wires together stable semantic identity (eid) with actionable targeting data.
+ *
+ * Key principles:
+ * - `eid` is the stable semantic identity (survives DOM mutations)
+ * - `ref` contains targeting data for actual interactions
+ * - Actions resolve via eid → ref, never use eid directly as a click target
+ */
+export {};
+//# sourceMappingURL=element-ref.types.js.map

package/dist/src/state/element-ref.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-ref.types.js","sourceRoot":"","sources":["../../../src/state/element-ref.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/src/state/element-registry.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Element Registry
+ *
+ * Manages eid → ElementRef mappings across snapshots.
+ * Provides lookup by eid for action tools, enabling the transition from
+ * transient node_id to stable semantic eid for element targeting.
+ *
+ * Key responsibilities:
+ * - Build ElementRef from ReadableNode
+ * - Track eid across snapshot updates
+ * - Provide lookup by eid for action tools
+ * - Detect stale elements
+ */
+import type { BaseSnapshot } from '../snapshot/snapshot.types.js';
+import type { ElementRef, RegistryUpdateResult } from './element-ref.types.js';
+/**
+ * ElementRegistry - Manages eid → ElementRef mappings across snapshots.
+ *
+ * Usage:
+ * 1. Call updateFromSnapshot() after each new snapshot
+ * 2. Use getByEid() in action tools to resolve eid to ElementRef
+ * 3. Use getEidByBackendNodeId() for reverse lookup (legacy node_id support)
+ */
+export declare class ElementRegistry {
+    private registry;
+    private currentStep;
+    private currentSnapshotId;
+    /**
+     * Update registry with new snapshot.
+     * Builds ElementRef for each interactive node and tracks changes.
+     *
+     * @param snapshot - New snapshot to process
+     * @param activeLayer - Active layer for eid computation
+     * @returns List of added, removed, and updated eids
+     */
+    updateFromSnapshot(snapshot: BaseSnapshot, activeLayer: string): RegistryUpdateResult;
+    /**
+     * Build ElementRef from ReadableNode.
+     *
+     * @param node - Source node
+     * @param eid - Computed eid
+     * @param snapshotId - Snapshot ID
+     * @param activeLayer - Active layer for locator scoping
+     * @returns ElementRef
+     */
+    private buildElementRef;
+    /**
+     * Lookup element by eid.
+     *
+     * @param eid - Element ID to lookup
+     * @returns ElementRef or undefined if not found
+     */
+    getByEid(eid: string): ElementRef | undefined;
+    /**
+     * Lookup eid by backend_node_id in current snapshot.
+     * Used for backwards compatibility with node_id-based tools.
+     *
+     * @param backendNodeId - CDP backend node ID
+     * @returns eid or undefined
+     */
+    getEidByBackendNodeId(backendNodeId: number): string | undefined;
+    /**
+     * Lookup eid by backend_node_id in any snapshot.
+     *
+     * @param snapshotId - Snapshot ID
+     * @param backendNodeId - CDP backend node ID
+     * @returns eid or undefined
+     */
+    getEidBySnapshotAndBackendNodeId(snapshotId: string, backendNodeId: number): string | undefined;
+    /**
+     * Get all current eids.
+     *
+     * @returns Array of all tracked eids
+     */
+    getAllEids(): string[];
+    /**
+     * Check if an eid is stale (not seen in recent snapshots).
+     *
+     * @param eid - Element ID to check
+     * @param maxStaleSteps - Maximum steps since last seen (default: 2)
+     * @returns true if stale
+     */
+    isStale(eid: string, maxStaleSteps?: number): boolean;
+    /**
+     * Get current step counter.
+     */
+    getCurrentStep(): number;
+    /**
+     * Get current snapshot ID.
+     */
+    getCurrentSnapshotId(): string;
+    /**
+     * Clear registry (on session close or full navigation).
+     */
+    clear(): void;
+    /**
+     * Get number of tracked elements.
+     */
+    size(): number;
+}
+/**
+ * Get or create element registry for a page.
+ *
+ * @param pageId - Page ID
+ * @returns ElementRegistry instance
+ */
+export declare function getElementRegistry(pageId: string): ElementRegistry;
+/**
+ * Remove element registry for a page (call on page close).
+ *
+ * @param pageId - Page ID
+ */
+export declare function removeElementRegistry(pageId: string): void;
+/**
+ * Clear all element registries (call on session close).
+ */
+export declare function clearAllElementRegistries(): void;
+//# sourceMappingURL=element-registry.d.ts.map

package/dist/src/state/element-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-registry.d.ts","sourceRoot":"","sources":["../../../src/state/element-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAgB,MAAM,+BAA+B,CAAC;AAChF,OAAO,KAAK,EACV,UAAU,EAGV,oBAAoB,EACrB,MAAM,wBAAwB,CAAC;AAShC;;;;;;;GAOG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAId;IAEF,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,iBAAiB,CAAM;IAE/B;;;;;;;OAOG;IACH,kBAAkB,CAAC,QAAQ,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,GAAG,oBAAoB;IAmDrF;;;;;;;;OAQG;IACH,OAAO,CAAC,eAAe;IAsBvB;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI7C;;;;;;OAMG;IACH,qBAAqB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIhE;;;;;;OAMG;IACH,gCAAgC,CAAC,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI/F;;;;OAIG;IACH,UAAU,IAAI,MAAM,EAAE;IAItB;;;;;;OAMG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,SAAI,GAAG,OAAO;IAMhD;;OAEG;IACH,cAAc,IAAI,MAAM;IAIxB;;OAEG;IACH,oBAAoB,IAAI,MAAM;IAI9B;;OAEG;IACH,KAAK,IAAI,IAAI;IAQb;;OAEG;IACH,IAAI,IAAI,MAAM;CAGf;AAWD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,CAKlE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAE1D;AAED;;GAEG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD"}

package/dist/src/state/element-registry.js

@@ -0,0 +1,222 @@
+/**
+ * Element Registry
+ *
+ * Manages eid → ElementRef mappings across snapshots.
+ * Provides lookup by eid for action tools, enabling the transition from
+ * transient node_id to stable semantic eid for element targeting.
+ *
+ * Key responsibilities:
+ * - Build ElementRef from ReadableNode
+ * - Track eid across snapshot updates
+ * - Provide lookup by eid for action tools
+ * - Detect stale elements
+ */
+import { computeEid, resolveEidCollision } from './element-identity.js';
+import { generateLocator } from './locator-generator.js';
+import { isInteractiveKind } from './actionables-filter.js';
+// ============================================================================
+// Element Registry Class
+// ============================================================================
+/**
+ * ElementRegistry - Manages eid → ElementRef mappings across snapshots.
+ *
+ * Usage:
+ * 1. Call updateFromSnapshot() after each new snapshot
+ * 2. Use getByEid() in action tools to resolve eid to ElementRef
+ * 3. Use getEidByBackendNodeId() for reverse lookup (legacy node_id support)
+ */
+export class ElementRegistry {
+    registry = {
+        byEid: new Map(),
+        backendToEid: new Map(),
+        lastSeenStep: new Map(),
+    };
+    currentStep = 0;
+    currentSnapshotId = '';
+    /**
+     * Update registry with new snapshot.
+     * Builds ElementRef for each interactive node and tracks changes.
+     *
+     * @param snapshot - New snapshot to process
+     * @param activeLayer - Active layer for eid computation
+     * @returns List of added, removed, and updated eids
+     */
+    updateFromSnapshot(snapshot, activeLayer) {
+        this.currentStep++;
+        this.currentSnapshotId = snapshot.snapshot_id;
+        const previousEids = new Set(this.registry.byEid.keys());
+        const currentEids = new Set();
+        const usedEids = new Set();
+        const added = [];
+        const updated = [];
+        // Process all interactive nodes
+        for (const node of snapshot.nodes) {
+            // Only track interactive elements
+            if (!isInteractiveKind(node.kind))
+                continue;
+            // Compute eid (with collision resolution)
+            const baseEid = computeEid(node, activeLayer);
+            const eid = resolveEidCollision(baseEid, usedEids);
+            usedEids.add(eid);
+            currentEids.add(eid);
+            // Build ElementRef
+            const ref = this.buildElementRef(node, eid, snapshot.snapshot_id, activeLayer);
+            // Track whether this is new or updated
+            if (!previousEids.has(eid)) {
+                added.push(eid);
+            }
+            else {
+                updated.push(eid);
+            }
+            // Update registry
+            this.registry.byEid.set(eid, ref);
+            this.registry.backendToEid.set(`${snapshot.snapshot_id}:${node.backend_node_id}`, eid);
+            this.registry.lastSeenStep.set(eid, this.currentStep);
+        }
+        // Find removed eids (present in previous, not in current)
+        const removed = [];
+        for (const eid of previousEids) {
+            if (!currentEids.has(eid)) {
+                removed.push(eid);
+                // Don't delete immediately - keep for staleness detection
+                // Mark as not seen in current step (lastSeenStep not updated)
+            }
+        }
+        return { added, removed, updated };
+    }
+    /**
+     * Build ElementRef from ReadableNode.
+     *
+     * @param node - Source node
+     * @param eid - Computed eid
+     * @param snapshotId - Snapshot ID
+     * @param activeLayer - Active layer for locator scoping
+     * @returns ElementRef
+     */
+    buildElementRef(node, eid, snapshotId, activeLayer) {
+        const locatorInfo = generateLocator(node, activeLayer);
+        const ref = {
+            snapshot_id: snapshotId,
+            backend_node_id: node.backend_node_id,
+            frame_id: node.frame_id,
+            loader_id: node.loader_id,
+            locators: {
+                preferred: locatorInfo.preferred,
+                fallback: locatorInfo.fallback,
+            },
+        };
+        return { eid, ref };
+    }
+    /**
+     * Lookup element by eid.
+     *
+     * @param eid - Element ID to lookup
+     * @returns ElementRef or undefined if not found
+     */
+    getByEid(eid) {
+        return this.registry.byEid.get(eid);
+    }
+    /**
+     * Lookup eid by backend_node_id in current snapshot.
+     * Used for backwards compatibility with node_id-based tools.
+     *
+     * @param backendNodeId - CDP backend node ID
+     * @returns eid or undefined
+     */
+    getEidByBackendNodeId(backendNodeId) {
+        return this.registry.backendToEid.get(`${this.currentSnapshotId}:${backendNodeId}`);
+    }
+    /**
+     * Lookup eid by backend_node_id in any snapshot.
+     *
+     * @param snapshotId - Snapshot ID
+     * @param backendNodeId - CDP backend node ID
+     * @returns eid or undefined
+     */
+    getEidBySnapshotAndBackendNodeId(snapshotId, backendNodeId) {
+        return this.registry.backendToEid.get(`${snapshotId}:${backendNodeId}`);
+    }
+    /**
+     * Get all current eids.
+     *
+     * @returns Array of all tracked eids
+     */
+    getAllEids() {
+        return Array.from(this.registry.byEid.keys());
+    }
+    /**
+     * Check if an eid is stale (not seen in recent snapshots).
+     *
+     * @param eid - Element ID to check
+     * @param maxStaleSteps - Maximum steps since last seen (default: 2)
+     * @returns true if stale
+     */
+    isStale(eid, maxStaleSteps = 2) {
+        const lastSeen = this.registry.lastSeenStep.get(eid);
+        if (lastSeen === undefined)
+            return true;
+        return this.currentStep - lastSeen > maxStaleSteps;
+    }
+    /**
+     * Get current step counter.
+     */
+    getCurrentStep() {
+        return this.currentStep;
+    }
+    /**
+     * Get current snapshot ID.
+     */
+    getCurrentSnapshotId() {
+        return this.currentSnapshotId;
+    }
+    /**
+     * Clear registry (on session close or full navigation).
+     */
+    clear() {
+        this.registry.byEid.clear();
+        this.registry.backendToEid.clear();
+        this.registry.lastSeenStep.clear();
+        this.currentStep = 0;
+        this.currentSnapshotId = '';
+    }
+    /**
+     * Get number of tracked elements.
+     */
+    size() {
+        return this.registry.byEid.size;
+    }
+}
+// ============================================================================
+// Registry Factory
+// ============================================================================
+/**
+ * Global registry of element registries (one per page).
+ */
+const registries = new Map();
+/**
+ * Get or create element registry for a page.
+ *
+ * @param pageId - Page ID
+ * @returns ElementRegistry instance
+ */
+export function getElementRegistry(pageId) {
+    if (!registries.has(pageId)) {
+        registries.set(pageId, new ElementRegistry());
+    }
+    return registries.get(pageId);
+}
+/**
+ * Remove element registry for a page (call on page close).
+ *
+ * @param pageId - Page ID
+ */
+export function removeElementRegistry(pageId) {
+    registries.delete(pageId);
+}
+/**
+ * Clear all element registries (call on session close).
+ */
+export function clearAllElementRegistries() {
+    registries.clear();
+}
+//# sourceMappingURL=element-registry.js.map

package/dist/src/state/element-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-registry.js","sourceRoot":"","sources":["../../../src/state/element-registry.ts"],"names":[],"mappings":"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"}