Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

Keep selector indices unique across CDP sessions

MagMueller5a4b02c4bdc0
diff --git a/browser_use/actor/page.py b/browser_use/actor/page.py
index 5f1c83e25..ff210de2c 100644
--- a/browser_use/actor/page.py
+++ b/browser_use/actor/page.py
@@ -475,7 +475,8 @@ Before you return the element index, reason about the state and elements for a s
from .element import Element as Element_
- return Element_(self._browser_session, element.backend_node_id, self._session_id)
+ element_session = await self._browser_session.cdp_client_for_node(element)
+ return Element_(self._browser_session, element.backend_node_id, element_session.session_id)
async def must_get_element_by_prompt(self, prompt: str, llm: 'BaseChatModel | None' = None) -> 'Element':
"""Get an element by a prompt.
diff --git a/browser_use/agent/service.py b/browser_use/agent/service.py
index eaf2c2c6b..4bee7b6df 100644
--- a/browser_use/agent/service.py
+++ b/browser_use/agent/service.py
@@ -3550,6 +3550,15 @@ class Agent(Generic[Context, AgentStructuredOutput]):
return action
selector_map = browser_state_summary.dom_state.selector_map
+ selector_items = list(selector_map.items())
+ if historical_element.frame_id:
+ same_frame_items = [
+ (index, element) for index, element in selector_items if element.frame_id == historical_element.frame_id
+ ]
+ if same_frame_items:
+ selector_items = same_frame_items + [
+ (index, element) for index, element in selector_items if element.frame_id != historical_element.frame_id
+ ]
highlight_index: int | None = None
match_level: MatchLevel | None = None
@@ -3563,7 +3572,7 @@ class Agent(Generic[Context, AgentStructuredOutput]):
hist_name = historical_element.node_name.lower()
matching_nodes = [
(idx, elem.node_name, elem.attributes.get('name') if elem.attributes else None)
- for idx, elem in selector_map.items()
+ for idx, elem in selector_items
if elem.node_name.lower() == hist_name
]
self.logger.info(
@@ -3572,7 +3581,7 @@ class Agent(Generic[Context, AgentStructuredOutput]):
)
# Level 1: EXACT hash match
- for idx, elem in selector_map.items():
+ for idx, elem in selector_items:
if elem.element_hash == historical_element.element_hash:
highlight_index = idx
match_level = MatchLevel.EXACT
@@ -3584,7 +3593,7 @@ class Agent(Generic[Context, AgentStructuredOutput]):
# Level 2: STABLE hash match (dynamic classes filtered)
# Use stored stable_hash (computed at save time from EnhancedDOMTreeNode - single source of truth)
if highlight_index is None and historical_element.stable_hash is not None:
- for idx, elem in selector_map.items():
+ for idx, elem in selector_items:
if elem.compute_stable_hash() == historical_element.stable_hash:
highlight_index = idx
match_level = MatchLevel.STABLE
@@ -3597,7 +3606,7 @@ class Agent(Generic[Context, AgentStructuredOutput]):
# Level 3: XPATH match
if highlight_index is None and historical_element.x_path:
- for idx, elem in selector_map.items():
+ for idx, elem in selector_items:
if elem.xpath == historical_element.x_path:
highlight_index = idx
match_level = MatchLevel.XPATH
@@ -3612,7 +3621,7 @@ class Agent(Generic[Context, AgentStructuredOutput]):
if highlight_index is None and historical_element.ax_name:
hist_name = historical_element.node_name.lower()
hist_ax_name = historical_element.ax_name
- for idx, elem in selector_map.items():
+ for idx, elem in selector_items:
# Match by node type and accessible name
elem_ax_name = elem.ax_node.name if elem.ax_node else None
if elem.node_name.lower() == hist_name and elem_ax_name == hist_ax_name:
@@ -3624,7 +3633,7 @@ class Agent(Generic[Context, AgentStructuredOutput]):
# Log available ax_names for debugging
same_type_ax_names = [
(idx, elem.ax_node.name if elem.ax_node else None)
- for idx, elem in selector_map.items()
+ for idx, elem in selector_items
if elem.node_name.lower() == hist_name and elem.ax_node and elem.ax_node.name
]
self.logger.debug(
@@ -3641,7 +3650,7 @@ class Agent(Generic[Context, AgentStructuredOutput]):
# Try matching by unique identifiers: name, id, or aria-label
for attr_key in ['name', 'id', 'aria-label']:
if attr_key in hist_attrs and hist_attrs[attr_key]:
- for idx, elem in selector_map.items():
+ for idx, elem in selector_items:
if (
elem.node_name.lower() == hist_name
and elem.attributes
@@ -3659,7 +3668,7 @@ class Agent(Generic[Context, AgentStructuredOutput]):
# Log what was tried and what's available on the page for debugging
same_node_elements = [
(idx, elem.attributes.get('aria-label') or elem.attributes.get('id') or elem.attributes.get('name'))
- for idx, elem in selector_map.items()
+ for idx, elem in selector_items
if elem.node_name.lower() == hist_name and elem.attributes
]
self.logger.info(
diff --git a/browser_use/browser/python_highlights.py b/browser_use/browser/python_highlights.py
index 2d41b7e27..f08247020 100644
--- a/browser_use/browser/python_highlights.py
+++ b/browser_use/browser/python_highlights.py
@@ -380,20 +380,18 @@ def process_element_highlight(
color = get_element_color(tag_name, element_type)
- # Get element index for overlay and apply filtering
- backend_node_id = getattr(element, 'backend_node_id', None)
+ # Use the selector-map key because that is the index shown to the model.
index_text = None
- if backend_node_id is not None:
- if filter_highlight_ids:
- # Use the meaningful text that matches what the LLM sees
- meaningful_text = element.get_meaningful_text_for_llm()
- # Show ID only if meaningful text is less than 5 characters
- if len(meaningful_text) < 3:
- index_text = str(backend_node_id)
- else:
- # Always show ID when filter is disabled
- index_text = str(backend_node_id)
+ if filter_highlight_ids:
+ # Use the meaningful text that matches what the LLM sees
+ meaningful_text = element.get_meaningful_text_for_llm()
+ # Show ID only if meaningful text is less than 5 characters
+ if len(meaningful_text) < 3:
+ index_text = str(element_id)
+ else:
+ # Always show ID when filter is disabled
+ index_text = str(element_id)
# Draw enhanced bounding box with bigger index
draw_enhanced_bounding_box_with_text(
diff --git a/browser_use/browser/session.py b/browser_use/browser/session.py
index c22c487a3..55424f82f 100644
--- a/browser_use/browser/session.py
+++ b/browser_use/browser/session.py
@@ -560,6 +560,7 @@ class BrowserSession(BaseModel):
_cached_browser_state_summary: Any = PrivateAttr(default=None)
_cached_selector_map: dict[int, EnhancedDOMTreeNode] = PrivateAttr(default_factory=dict)
+ _cached_selector_indices: dict[tuple[str, int], int] = PrivateAttr(default_factory=dict)
_downloaded_files: list[str] = PrivateAttr(default_factory=list) # Track files downloaded during this session
_closed_popup_messages: list[str] = PrivateAttr(default_factory=list) # Store messages from auto-closed JavaScript dialogs
@@ -659,6 +660,7 @@ class BrowserSession(BaseModel):
self._cdp_client_root = None # type: ignore
self._cached_browser_state_summary = None
self._cached_selector_map.clear()
+ self._cached_selector_indices.clear()
self._downloaded_files.clear()
self.agent_focus_target_id = None
@@ -1230,6 +1232,7 @@ class BrowserSession(BaseModel):
# Clear cached browser state
self._cached_browser_state_summary = None
self._cached_selector_map.clear()
+ self._cached_selector_indices.clear()
self.logger.debug('🔄 Cached browser state cleared')
# Update agent focus if a specific target_id is provided (only for page/tab targets)
@@ -2400,6 +2403,18 @@ class BrowserSession(BaseModel):
return None
+ def get_selector_index(self, node: EnhancedDOMTreeNode) -> int:
+ """Return the model-visible selector index for a DOM node."""
+ node_identity = (str(node.session_id), node.backend_node_id)
+ return self._cached_selector_indices.get(node_identity, node.backend_node_id)
+
+ def _get_cached_node_by_backend_id(self, backend_node_id: int, session_id: str | None) -> EnhancedDOMTreeNode | None:
+ """Resolve a backend ID only within the CDP session that produced it."""
+ for node in (self._cached_selector_map or {}).values():
+ if node.backend_node_id == backend_node_id and str(node.session_id) == str(session_id):
+ return node
+ return None
+
def update_cached_selector_map(self, selector_map: dict[int, EnhancedDOMTreeNode]) -> None:
"""Update the cached selector map with new DOM state.
@@ -2409,6 +2424,9 @@ class BrowserSession(BaseModel):
selector_map: The new selector map from DOM serialization
"""
self._cached_selector_map = selector_map
+ self._cached_selector_indices = {
+ (str(node.session_id), node.backend_node_id): index for index, node in selector_map.items()
+ }
# Alias for backwards compatibility
async def get_element_by_index(self, index: int) -> EnhancedDOMTreeNode | None:
@@ -2457,11 +2475,10 @@ class BrowserSession(BaseModel):
return None
# Try to find element in cached selector_map (avoids extra CDP call)
- if self._cached_selector_map:
- for node in self._cached_selector_map.values():
- if node.backend_node_id == backend_node_id:
- self.logger.debug(f'Found element at ({x}, {y}) in cached selector_map')
- return node
+ cached_node = self._get_cached_node_by_backend_id(backend_node_id, session_id)
+ if cached_node is not None:
+ self.logger.debug(f'Found element at ({x}, {y}) in cached selector_map')
+ return cached_node
# Not in cache - fall back to CDP DOM.describeNode to get actual node info
try:
@@ -2865,7 +2882,7 @@ class BrowserSession(BaseModel):
try:
import json
- cdp_session = await self.get_or_create_cdp_session()
+ cdp_session = await self.cdp_client_for_node(node)
# Get current coordinates
rect = await self.get_element_coordinates(node.backend_node_id, cdp_session)
@@ -3107,7 +3124,7 @@ class BrowserSession(BaseModel):
# Convert selector_map to the format expected by the highlighting script
elements_data = []
- for _, node in selector_map.items():
+ for element_index, node in selector_map.items():
# Get bounding box using absolute position (includes iframe translations) if available
if node.absolute_position:
# Use absolute position which includes iframe coordinate translations
@@ -3128,6 +3145,7 @@ class BrowserSession(BaseModel):
'frame_id': getattr(node, 'frame_id', None),
'node_id': node.node_id,
'backend_node_id': node.backend_node_id,
+ 'element_index': element_index,
'xpath': node.xpath,
'text_content': node.get_all_children_text()[:50]
if hasattr(node, 'get_all_children_text')
@@ -3213,7 +3231,7 @@ class BrowserSession(BaseModel):
interactiveElements.forEach((element, index) => {{
const highlight = document.createElement('div');
highlight.setAttribute('data-browser-use-highlight', 'element');
- highlight.setAttribute('data-element-id', element.backend_node_id);
+ highlight.setAttribute('data-element-id', element.element_index);
highlight.style.cssText = `
position: absolute;
left: ${{element.x}}px;
@@ -3231,8 +3249,8 @@ class BrowserSession(BaseModel):
border: none;
`;
- // Enhanced label with backend node ID
- const label = createTextElement('div', element.backend_node_id, `
+ // Label with the same selector index shown to the model
+ const label = createTextElement('div', element.element_index, `
position: absolute;
top: -20px;
left: 0;
diff --git a/browser_use/browser/views.py b/browser_use/browser/views.py
index 74830c29c..962a3c84c 100644
--- a/browser_use/browser/views.py
+++ b/browser_use/browser/views.py
@@ -83,6 +83,7 @@ class PaginationButton:
backend_node_id: int # Backend node ID for clicking
text: str # Button text/label
selector: str # XPath or other selector to locate the element
+ selector_index: int | None = None # Model-visible selector index
is_disabled: bool = False # Whether the button appears disabled
diff --git a/browser_use/browser/watchdogs/default_action_watchdog.py b/browser_use/browser/watchdogs/default_action_watchdog.py
index e41475ef8..f56e4fa8f 100644
--- a/browser_use/browser/watchdogs/default_action_watchdog.py
+++ b/browser_use/browser/watchdogs/default_action_watchdog.py
@@ -345,7 +345,7 @@ class DefaultActionWatchdog(BaseWatchdog):
# Use the provided node
element_node = event.node
- index_for_logging = element_node.backend_node_id or 'unknown'
+ index_for_logging = self.browser_session.get_selector_index(element_node)
# Check if element is a file input (should not be clicked)
if self.browser_session.is_file_input(element_node):
@@ -453,7 +453,7 @@ class DefaultActionWatchdog(BaseWatchdog):
try:
# Use the provided node
element_node = event.node
- index_for_logging = element_node.backend_node_id or 'unknown'
+ index_for_logging = self.browser_session.get_selector_index(element_node)
# Check if this is index 0 or a falsy index - type to the page (whatever has focus)
if not element_node.backend_node_id or element_node.backend_node_id == 0:
@@ -530,7 +530,7 @@ class DefaultActionWatchdog(BaseWatchdog):
# Element-specific scrolling if node is provided
if event.node is not None:
element_node = event.node
- index_for_logging = element_node.backend_node_id or 'unknown'
+ index_for_logging = self.browser_session.get_selector_index(element_node)
# Check if the element is an iframe
is_iframe = element_node.tag_name and element_node.tag_name.upper() == 'IFRAME'
@@ -711,14 +711,15 @@ class DefaultActionWatchdog(BaseWatchdog):
# Check if element is a file input or select dropdown - these should not be clicked
tag_name = element_node.tag_name.lower() if element_node.tag_name else ''
element_type = element_node.attributes.get('type', '').lower() if element_node.attributes else ''
+ selector_index = self.browser_session.get_selector_index(element_node)
if tag_name == 'select':
- msg = f'Cannot click on <select> elements. Use dropdown_options(index={element_node.backend_node_id}) action instead.'
+ msg = f'Cannot click on <select> elements. Use dropdown_options(index={selector_index}) action instead.'
# Return error dict instead of raising to avoid ERROR logs
return {'validation_error': msg}
if tag_name == 'input' and element_type == 'file':
- msg = f'Cannot click on file input element (index={element_node.backend_node_id}). File uploads must be handled using upload_file_to_element action.'
+ msg = f'Cannot click on file input element (index={selector_index}). File uploads must be handled using upload_file_to_element action.'
# Return error dict instead of raising to avoid ERROR logs
return {'validation_error': msg}
@@ -1042,17 +1043,18 @@ class DefaultActionWatchdog(BaseWatchdog):
raise e
except Exception as e:
# Extract key element info for error message
+ selector_index = self.browser_session.get_selector_index(element_node)
element_info = f'<{element_node.tag_name or "unknown"}'
- if element_node.backend_node_id:
- element_info += f' index={element_node.backend_node_id}'
+ if selector_index:
+ element_info += f' index={selector_index}'
element_info += '>'
# Create helpful error message based on context
error_detail = f'Failed to click element {element_info}. The element may not be interactable or visible.'
# Add hint if element has index (common in code-use mode)
- if element_node.backend_node_id:
- error_detail += f' If the page changed after navigation/interaction, the index [{element_node.backend_node_id}] may be stale. Get fresh browser state before retrying.'
+ if selector_index:
+ error_detail += f' If the page changed after navigation/interaction, the index [{selector_index}] may be stale. Get fresh browser state before retrying.'
raise BrowserError(
message=f'Failed to click element: {str(e)}',
@@ -2680,7 +2682,7 @@ class DefaultActionWatchdog(BaseWatchdog):
try:
# Use the provided node
element_node = event.node
- index_for_logging = element_node.backend_node_id or 'unknown'
+ index_for_logging = self.browser_session.get_selector_index(element_node)
# Check if it's a file input
if not self.browser_session.is_file_input(element_node):
@@ -2812,7 +2814,7 @@ class DefaultActionWatchdog(BaseWatchdog):
try:
# Use the provided node
element_node = event.node
- index_for_logging = element_node.backend_node_id or 'unknown'
+ index_for_logging = self.browser_session.get_selector_index(element_node)
# Get CDP session for this node
cdp_session = await self.browser_session.cdp_client_for_node(element_node)
@@ -2862,7 +2864,13 @@ class DefaultActionWatchdog(BaseWatchdog):
# If it's an ARIA combobox with aria-controls, handle it specially
if combobox_info.get('isCombobox'):
- return await self._handle_aria_combobox_options(cdp_session, object_id, combobox_info, index_for_logging)
+ return await self._handle_aria_combobox_options(
+ cdp_session,
+ object_id,
+ combobox_info,
+ index_for_logging,
+ element_node.backend_node_id,
+ )
# Use JavaScript to extract dropdown options (existing logic for non-combobox elements)
options_script = """
@@ -3007,7 +3015,8 @@ class DefaultActionWatchdog(BaseWatchdog):
'error': msg,
'short_term_memory': msg,
'long_term_memory': msg,
- 'backend_node_id': str(index_for_logging),
+ 'backend_node_id': str(element_node.backend_node_id),
+ 'selector_index': str(index_for_logging),
}
# Format options for display
@@ -3051,7 +3060,8 @@ class DefaultActionWatchdog(BaseWatchdog):
'message': msg,
'short_term_memory': short_term_memory,
'long_term_memory': long_term_memory,
- 'backend_node_id': str(index_for_logging),
+ 'backend_node_id': str(element_node.backend_node_id),
+ 'selector_index': str(index_for_logging),
}
except BrowserError:
@@ -3075,6 +3085,7 @@ class DefaultActionWatchdog(BaseWatchdog):
object_id: str,
combobox_info: dict,
index_for_logging: int | str,
+ backend_node_id: int,
) -> dict[str, str]:
"""Handle ARIA combobox elements with options in a separate listbox element.
@@ -3241,7 +3252,8 @@ class DefaultActionWatchdog(BaseWatchdog):
'error': msg,
'short_term_memory': msg,
'long_term_memory': msg,
- 'backend_node_id': str(index_for_logging),
+ 'backend_node_id': str(backend_node_id),
+ 'selector_index': str(index_for_logging),
}
# Format options for display
@@ -3269,7 +3281,8 @@ class DefaultActionWatchdog(BaseWatchdog):
'message': msg,
'short_term_memory': msg,
'long_term_memory': f'Got dropdown options for ARIA combobox at index {index_for_logging}',
- 'backend_node_id': str(index_for_logging),
+ 'backend_node_id': str(backend_node_id),
+ 'selector_index': str(index_for_logging),
}
async def on_SelectDropdownOptionEvent(self, event: SelectDropdownOptionEvent) -> dict[str, str]:
@@ -3277,7 +3290,7 @@ class DefaultActionWatchdog(BaseWatchdog):
try:
# Use the provided node
element_node = event.node
- index_for_logging = element_node.backend_node_id or 'unknown'
+ index_for_logging = self.browser_session.get_selector_index(element_node)
target_text = event.text
# Get CDP session for this node
@@ -3658,7 +3671,8 @@ class DefaultActionWatchdog(BaseWatchdog):
'success': 'true',
'message': msg,
'value': fallback_data.get('value', target_text),
- 'backend_node_id': str(index_for_logging),
+ 'backend_node_id': str(element_node.backend_node_id),
+ 'selector_index': str(index_for_logging),
}
else:
self.logger.warning(f'⚠️ Click fallback also failed: {fallback_data.get("error", "unknown")}')
@@ -3673,7 +3687,8 @@ class DefaultActionWatchdog(BaseWatchdog):
'success': 'true',
'message': msg,
'value': selection_result.get('value', target_text),
- 'backend_node_id': str(index_for_logging),
+ 'backend_node_id': str(element_node.backend_node_id),
+ 'selector_index': str(index_for_logging),
}
else:
error_msg = selection_result.get('error', f'Failed to select option: {target_text}')
@@ -3708,14 +3723,16 @@ class DefaultActionWatchdog(BaseWatchdog):
'error': error_msg,
'short_term_memory': short_term_memory,
'long_term_memory': long_term_memory,
- 'backend_node_id': str(index_for_logging),
+ 'backend_node_id': str(element_node.backend_node_id),
+ 'selector_index': str(index_for_logging),
}
# Fallback to regular error result if no available options
return {
'success': 'false',
'error': error_msg,
- 'backend_node_id': str(index_for_logging),
+ 'backend_node_id': str(element_node.backend_node_id),
+ 'selector_index': str(index_for_logging),
}
except Exception as e:
diff --git a/browser_use/browser/watchdogs/dom_watchdog.py b/browser_use/browser/watchdogs/dom_watchdog.py
index 62daa0397..ac22477b3 100644
--- a/browser_use/browser/watchdogs/dom_watchdog.py
+++ b/browser_use/browser/watchdogs/dom_watchdog.py
@@ -730,6 +730,7 @@ class DOMWatchdog(BaseWatchdog):
PaginationButton(
button_type=btn['button_type'], # type: ignore
backend_node_id=btn['backend_node_id'], # type: ignore
+ selector_index=btn['selector_index'], # type: ignore
text=btn['text'], # type: ignore
selector=btn['selector'], # type: ignore
is_disabled=btn['is_disabled'], # type: ignore
diff --git a/browser_use/dom/serializer/eval_serializer.py b/browser_use/dom/serializer/eval_serializer.py
index 64116d255..4c0f66415 100644
--- a/browser_use/dom/serializer/eval_serializer.py
+++ b/browser_use/dom/serializer/eval_serializer.py
@@ -158,7 +158,8 @@ class DOMEvalSerializer:
line = f'{depth_str}'
# Add [i_X] for interactive SVG elements only
if node.is_interactive:
- line += f'[i_{node.original_node.backend_node_id}] '
+ assert node.selector_index is not None
+ line += f'[i_{node.selector_index}] '
line += '<svg'
attributes_str = DOMEvalSerializer._build_compact_attributes(node.original_node)
if attributes_str:
@@ -181,9 +182,10 @@ class DOMEvalSerializer:
# Build compact element representation
line = f'{depth_str}'
- # Add backend node ID notation - [i_X] for interactive elements only
+ # Add model-visible selector notation - [i_X] for interactive elements only
if node.is_interactive:
- line += f'[i_{node.original_node.backend_node_id}] '
+ assert node.selector_index is not None
+ line += f'[i_{node.selector_index}] '
# Non-interactive elements don't get an index notation
line += f'<{tag}'
diff --git a/browser_use/dom/serializer/serializer.py b/browser_use/dom/serializer/serializer.py
index 9eca9c297..d3517c70c 100644
--- a/browser_use/dom/serializer/serializer.py
+++ b/browser_use/dom/serializer/serializer.py
@@ -69,10 +69,20 @@ class DOMTreeSerializer:
self._interactive_counter = 1
self._selector_map: DOMSelectorMap = {}
self._previous_cached_selector_map = previous_cached_state.selector_map if previous_cached_state else None
+ self._previous_node_ids = (
+ {
+ (str(previous_node.session_id), previous_node.backend_node_id)
+ for previous_node in self._previous_cached_selector_map.values()
+ }
+ if self._previous_cached_selector_map
+ else set()
+ )
# Add timing tracking
self.timing_info: dict[str, float] = {}
# Cache for clickable element detection to avoid redundant calls
self._clickable_cache: dict[tuple[str | None, int], bool] = {}
+ self._reserved_backend_node_ids: set[int] = set()
+ self._next_synthetic_index = 1
# Bounding box filtering configuration
self.enable_bbox_filtering = enable_bbox_filtering
self.containment_threshold = containment_threshold or self.DEFAULT_CONTAINMENT_THRESHOLD
@@ -107,6 +117,8 @@ class DOMTreeSerializer:
self._selector_map = {}
self._semantic_groups = []
self._clickable_cache = {} # Clear cache for new serialization
+ self._reserved_backend_node_ids = set()
+ self._next_synthetic_index = 1
# Step 1: Create simplified tree (includes clickable element detection)
start_step1 = time.time()
@@ -138,6 +150,7 @@ class DOMTreeSerializer:
# Step 4: Assign interactive indices to clickable elements
start_step4 = time.time()
+ self._reserve_backend_node_ids(filtered_tree)
self._assign_interactive_indices_and_mark_new_nodes(filtered_tree)
end_step4 = time.time()
self.timing_info['assign_interactive_indices'] = end_step4 - start_step4
@@ -617,6 +630,29 @@ class DOMTreeSerializer:
current = current.parent_node
return False
+ def _reserve_backend_node_ids(self, root: SimplifiedNode | None) -> None:
+ """Reserve every CDP backend ID in one linear traversal."""
+ if root is None:
+ return
+
+ stack = [root]
+ while stack:
+ node = stack.pop()
+ self._reserved_backend_node_ids.add(node.original_node.backend_node_id)
+ stack.extend(node.children)
+ self._next_synthetic_index = max(self._reserved_backend_node_ids, default=0) + 1
+
+ def _allocate_selector_index(self, backend_node_id: int) -> int:
+ """Preserve unique backend IDs and allocate a collision-free model index otherwise."""
+ if backend_node_id not in self._selector_map:
+ return backend_node_id
+
+ while self._next_synthetic_index in self._reserved_backend_node_ids:
+ self._next_synthetic_index += 1
+ selector_index = self._next_synthetic_index
+ self._next_synthetic_index += 1
+ return selector_index
+
def _assign_interactive_indices_and_mark_new_nodes(self, node: SimplifiedNode | None) -> None:
"""Assign interactive indices to clickable elements that are also visible."""
if not node:
@@ -712,17 +748,17 @@ class DOMTreeSerializer:
if should_make_interactive:
# Mark node as interactive
node.is_interactive = True
- # Store backend_node_id in selector map (model outputs backend_node_id)
- self._selector_map[node.original_node.backend_node_id] = node.original_node
+ node.selector_index = self._allocate_selector_index(node.original_node.backend_node_id)
+ self._selector_map[node.selector_index] = node.original_node
self._interactive_counter += 1
# Mark compound components as new for visibility
if node.is_compound_component:
node.is_new = True
- elif self._previous_cached_selector_map:
+ elif self._previous_node_ids:
# Check if node is new for regular elements
- previous_backend_node_ids = {node.backend_node_id for node in self._previous_cached_selector_map.values()}
- if node.original_node.backend_node_id not in previous_backend_node_ids:
+ current_node_id = (str(node.original_node.session_id), node.original_node.backend_node_id)
+ if current_node_id not in self._previous_node_ids:
node.is_new = True
# Process children
@@ -925,8 +961,9 @@ class DOMTreeSerializer:
line = f'{depth_str}{shadow_prefix}'
# Add interactive marker if clickable
if node.is_interactive:
+ assert node.selector_index is not None
new_prefix = '*' if node.is_new else ''
- line += f'{new_prefix}[{node.original_node.backend_node_id}]'
+ line += f'{new_prefix}[{node.selector_index}]'
line += '<svg'
attributes_html_str = DOMTreeSerializer._build_attributes_string(node.original_node, include_attributes, '')
if attributes_html_str:
@@ -1004,10 +1041,10 @@ class DOMTreeSerializer:
# Scrollable container but not clickable
line = f'{depth_str}{shadow_prefix}|scroll element|<{node.original_node.tag_name}'
elif node.is_interactive:
- # Clickable (and possibly scrollable) - show backend_node_id
+ assert node.selector_index is not None
new_prefix = '*' if node.is_new else ''
scroll_prefix = '|scroll element[' if should_show_scroll else '['
- line = f'{depth_str}{shadow_prefix}{new_prefix}{scroll_prefix}{node.original_node.backend_node_id}]<{node.original_node.tag_name}'
+ line = f'{depth_str}{shadow_prefix}{new_prefix}{scroll_prefix}{node.selector_index}]<{node.original_node.tag_name}'
elif node.original_node.tag_name.upper() == 'IFRAME':
# Iframe element (not interactive)
line = f'{depth_str}{shadow_prefix}|IFRAME|<{node.original_node.tag_name}'
diff --git a/browser_use/dom/service.py b/browser_use/dom/service.py
index b1d6a4f7c..2e8dd33be 100644
--- a/browser_use/dom/service.py
+++ b/browser_use/dom/service.py
@@ -1114,6 +1114,7 @@ class DomService:
List of pagination button information dicts with:
- button_type: 'next', 'prev', 'first', 'last', 'page_number'
- backend_node_id: Backend node ID for clicking
+ - selector_index: Model-visible selector index
- text: Button text/label
- selector: XPath selector
- is_disabled: Whether the button appears disabled
@@ -1172,7 +1173,8 @@ class DomService:
pagination_buttons.append(
{
'button_type': button_type,
- 'backend_node_id': index,
+ 'backend_node_id': node.backend_node_id,
+ 'selector_index': index,
'text': node.get_all_children_text().strip() or aria_label or title,
'selector': node.xpath,
'is_disabled': is_disabled,
diff --git a/browser_use/dom/views.py b/browser_use/dom/views.py
index 43df5631b..3c6493ff4 100644
--- a/browser_use/dom/views.py
+++ b/browser_use/dom/views.py
@@ -222,6 +222,7 @@ class SimplifiedNode:
children: list['SimplifiedNode']
should_display: bool = True
is_interactive: bool = False # True if element is in selector_map
+ selector_index: int | None = None
is_new: bool = False
@@ -251,6 +252,7 @@ class SimplifiedNode:
return {
'should_display': self.should_display,
'is_interactive': self.is_interactive,
+ 'selector_index': self.selector_index,
'ignored_by_paint_order': self.ignored_by_paint_order,
'excluded_by_parent': self.excluded_by_parent,
'original_node': cleaned_original_node_json,
diff --git a/tests/ci/browser/test_dom_selector_index_collisions.py b/tests/ci/browser/test_dom_selector_index_collisions.py
new file mode 100644
index 000000000..8ffa75d86
--- /dev/null
+++ b/tests/ci/browser/test_dom_selector_index_collisions.py
@@ -0,0 +1,241 @@
+"""Regression coverage for selector identity across CDP sessions."""
+
+from types import SimpleNamespace
+from typing import Any, cast
+
+import pytest
+
+from browser_use.actor.page import Page
+from browser_use.agent.service import Agent
+from browser_use.browser import python_highlights
+from browser_use.browser.profile import BrowserProfile
+from browser_use.browser.session import BrowserSession
+from browser_use.browser.views import BrowserStateSummary
+from browser_use.dom.serializer.serializer import DOMTreeSerializer
+from browser_use.dom.service import DomService
+from browser_use.dom.views import DOMInteractedElement, DOMRect, EnhancedDOMTreeNode, EnhancedSnapshotNode, NodeType
+
+
+def _node(
+ tag_name: str,
+ *,
+ node_id: int,
+ backend_node_id: int,
+ session_id: str,
+ frame_id: str | None = None,
+) -> EnhancedDOMTreeNode:
+ return EnhancedDOMTreeNode(
+ node_id=node_id,
+ backend_node_id=backend_node_id,
+ node_type=NodeType.ELEMENT_NODE,
+ node_name=tag_name.upper(),
+ node_value='',
+ attributes={},
+ is_scrollable=False,
+ is_visible=True,
+ absolute_position=DOMRect(x=0, y=0, width=100, height=30),
+ target_id=f'target-{session_id}',
+ frame_id=frame_id,
+ session_id=session_id,
+ content_document=None,
+ shadow_root_type=None,
+ shadow_roots=None,
+ parent_node=None,
+ children_nodes=[],
+ ax_node=None,
+ snapshot_node=EnhancedSnapshotNode(
+ is_clickable=None,
+ cursor_style='auto',
+ bounds=DOMRect(x=0, y=0, width=100, height=30),
+ clientRects=DOMRect(x=0, y=0, width=100, height=30),
+ scrollRects=None,
+ computed_styles={
+ 'display': 'block',
+ 'visibility': 'visible',
+ 'opacity': '1',
+ 'background-color': 'rgba(0, 0, 0, 0)',
+ },
+ paint_order=None,
+ stacking_contexts=None,
+ ),
+ )
+
+
+def _serialize(children: list[EnhancedDOMTreeNode]):
+ root = _node('html', node_id=100, backend_node_id=100, session_id='main')
+ root.children_nodes = children
+ for child in children:
+ child.parent_node = root
+ return DOMTreeSerializer(
+ root,
+ enable_bbox_filtering=False,
+ paint_order_filtering=False,
+ ).serialize_accessible_elements()[0]
+
+
+def test_backend_id_collisions_get_unique_selector_indices():
+ """Both controls remain addressable when separate sessions reuse a backend ID."""
+ main_input = _node('input', node_id=1, backend_node_id=5, session_id='main')
+ iframe_input = _node('input', node_id=2, backend_node_id=5, session_id='iframe')
+
+ serialized_state = _serialize([main_input, iframe_input])
+
+ assert list(serialized_state.selector_map) == [5, 101]
+ assert list(serialized_state.selector_map.values()) == [main_input, iframe_input]
+ assert '[5]<input' in serialized_state.llm_representation()
+ assert '[101]<input' in serialized_state.llm_representation()
+ assert '[i_5] <input' in serialized_state.eval_representation()
+ assert '[i_101] <input' in serialized_state.eval_representation()
+
+
+def test_session_lookup_keeps_selector_and_backend_identity_separate():
+ """Action messages and coordinate lookup resolve the intended session-local node."""
+ main_input = _node('input', node_id=1, backend_node_id=5, session_id='main')
+ iframe_input = _node('input', node_id=2, backend_node_id=5, session_id='iframe')
+ session = BrowserSession(browser_profile=BrowserProfile(use_cloud=False))
+ session.update_cached_selector_map({5: main_input, 101: iframe_input})
+
+ assert session.get_selector_index(iframe_input) == 101
+ assert session._get_cached_node_by_backend_id(5, 'main') is main_input
+ assert session._get_cached_node_by_backend_id(5, 'iframe') is iframe_input
+
+
+async def test_history_remapping_prefers_the_original_frame():
+ """History replay must not choose an identical element from a different frame."""
+ main_input = _node(
+ 'input',
+ node_id=1,
+ backend_node_id=5,
+ session_id='main',
+ frame_id='main-frame',
+ )
+ iframe_input = _node(
+ 'input',
+ node_id=2,
+ backend_node_id=5,
+ session_id='iframe',
+ frame_id='iframe-frame',
+ )
+ serialized_state = _serialize([main_input, iframe_input])
+ historical_element = DOMInteractedElement.load_from_enhanced_dom_tree(iframe_input)
+
+ class FakeAction:
+ def __init__(self):
+ self.index = 5
+
+ def get_index(self):
+ return self.index
+
+ def set_index(self, index):
+ self.index = index
+
+ logger = SimpleNamespace(info=lambda *_args: None, debug=lambda *_args: None)
+ agent = cast(Any, SimpleNamespace(logger=logger))
+ action = FakeAction()
+ state = BrowserStateSummary(dom_state=serialized_state, url='https://example.test', title='Test', tabs=[])
+
+ updated_action = await Agent._update_action_indices(agent, historical_element, cast(Any, action), state)
+
+ assert updated_action is action
+ assert action.index == 101
+
+
+def test_pagination_metadata_separates_selector_and_backend_ids():
+ """Public pagination metadata must not label a synthetic selector as a CDP backend ID."""
+ iframe_button = _node('button', node_id=2, backend_node_id=5, session_id='iframe')
+ assert iframe_button.snapshot_node is not None
+ iframe_button.snapshot_node.is_clickable = True
+ iframe_button.attributes['aria-label'] = 'Next'
+
+ buttons = DomService.detect_pagination_buttons({101: iframe_button})
+
+ assert buttons[0]['backend_node_id'] == 5
+ assert buttons[0]['selector_index'] == 101
+
+
+def test_screenshot_overlay_uses_selector_index(monkeypatch):
+ """Visual labels match the collision-free index shown in the DOM text."""
+ iframe_input = _node('input', node_id=2, backend_node_id=5, session_id='iframe')
+ captured_text: list[str | None] = []
+
+ def capture_label(_draw, _bbox, _color, text, *_args):
+ captured_text.append(text)
+
+ monkeypatch.setattr(python_highlights, 'draw_enhanced_bounding_box_with_text', capture_label)
+ python_highlights.process_element_highlight(
+ 101,
+ iframe_input,
+ draw=None,
+ device_pixel_ratio=1,
+ font=None,
+ filter_highlight_ids=False,
+ image_size=(1280, 900),
+ )
+
+ assert captured_text == ['101']
+
+
+async def test_interaction_highlight_uses_the_nodes_cdp_session(monkeypatch):
+ """The transient action highlight must resolve coordinates in the node's OOPIF session."""
+ iframe_input = _node('input', node_id=2, backend_node_id=5, session_id='iframe')
+ session = BrowserSession(browser_profile=BrowserProfile(use_cloud=False))
+ iframe_cdp_session = SimpleNamespace(session_id='iframe')
+ resolved_nodes: list[EnhancedDOMTreeNode] = []
+
+ async def resolve_node_session(_session, node):
+ resolved_nodes.append(node)
+ return iframe_cdp_session
+
+ async def no_coordinates(_session, backend_node_id, cdp_session):
+ assert backend_node_id == 5
+ assert cdp_session is iframe_cdp_session
+ return None
+
+ monkeypatch.setattr(BrowserSession, 'cdp_client_for_node', resolve_node_session)
+ monkeypatch.setattr(BrowserSession, 'get_element_coordinates', no_coordinates)
+
+ await session.highlight_interaction_element(iframe_input)
+
+ assert resolved_nodes == [iframe_input]
+
+
+async def test_actor_prompt_element_uses_the_selected_nodes_session(monkeypatch):
+ """Actor prompt lookup must return an Element bound to the selected OOPIF session."""
+ main_input = _node('input', node_id=1, backend_node_id=5, session_id='main')
+ iframe_input = _node('input', node_id=2, backend_node_id=5, session_id='iframe')
+ serialized_state = _serialize([main_input, iframe_input])
+ root = _node('html', node_id=100, backend_node_id=100, session_id='main')
+ session = BrowserSession(browser_profile=BrowserProfile(use_cloud=False))
+ session._cdp_client_root = cast(Any, SimpleNamespace())
+
+ class FakeSerializer:
+ def __init__(self, *_args, **_kwargs):
+ pass
+
+ def serialize_accessible_elements(self):
+ return serialized_state, {}
+
+ class FakeLLM:
+ async def ainvoke(self, *_args, **_kwargs):
+ return SimpleNamespace(completion=SimpleNamespace(element_highlight_index=101))
+
+ async def get_dom_tree(_service, **_kwargs):
+ return root, {}
+
+ async def resolve_node_session(_session, node):
+ assert node is iframe_input
+ return SimpleNamespace(session_id='iframe')
+
+ monkeypatch.setattr('browser_use.actor.page.DOMTreeSerializer', FakeSerializer)
+ monkeypatch.setattr(DomService, 'get_dom_tree', get_dom_tree)
+ monkeypatch.setattr(BrowserSession, 'cdp_client_for_node', resolve_node_session)
+
+ page = Page(session, target_id='target-main', session_id='main', llm=cast(Any, FakeLLM()))
+ element = await page.get_element_by_prompt('card number')
+
+ assert element is not None
+ assert element._backend_node_id == 5
+ assert element._session_id == 'iframe'