I implemented an independent Python rule that stops instead of pressing the first of two identically named buttons. It tests current observation identity, completeness, name, role and frame conditions without a real browser or account. The result is selection data, not a click.
State the trusted-observation assumption first
Inputs are an observation, expected context and target. Context contains tab, epoch and snapshot, all of which must match the observation. Keys and types are checked. This pure comparison cannot select a current target from an old epoch or different snapshot.
It does not collect browser observations or authenticate them. A caller inventing matching numbers would defeat the intended protection. A real adapter must derive trusted observations and expected context from the host. Validation of data and authentication of its provenance are different responsibilities.
Use exact normalized names and roles
Name and role are required and compared after whitespace normalization and lowercasing. Save is not a partial match for Save draft. Declared href, frame and viewport conditions narrow selection only when supplied. Href is an exact metadata string, not a verified network destination.
The caller must establish that an added condition reflects the request. Guessing a frame merely to leave one candidate would hide ambiguity. This module compares an explicit contract rather than interpreting its meaning, and it is not a copy of the production browser's richer reference and frame support.
Treat hidden, disabled and offscreen as different states
Invisible candidates are excluded. Disabled candidates still count toward ambiguity; a uniquely selected disabled candidate fails. The resolver does not silently erase it and choose another button. Integer one is also rejected where an actual boolean is required.
Offscreen candidates are not automatically ignored. Equal names inside and outside the viewport remain ambiguous unless an explicit viewport condition narrows them. Removing implicit proximity preferences makes the caller declare its selection criterion. Real occlusion and native click coordinates are outside this module.
Explore the implementation
Complete independent synthetic implementation
"""Resolve one declared target in a trusted synthetic observation. No actions."""
import copy
class TargetError(ValueError):pass
def _keys(value,keys):
if not isinstance(value,dict) or set(value)!=set(keys):raise TargetError('INVALID_FIELDS')
def _text(value):
if not isinstance(value,str) or not value.strip() or len(value)>500:raise TargetError('INVALID_TEXT')
def _context(value):
_keys(value,['tab','epoch','snapshot'])
_text(value['tab']);_text(value['snapshot'])
if type(value['epoch']) is not int or value['epoch']<0:raise TargetError('INVALID_EPOCH')
def _norm(value):return ' '.join(value.strip().split()).lower()
def resolve_target(observation,expected,target):
"""All metadata is supplied, not authenticated. Recheck real state at dispatch."""
_keys(observation,['context','has_more','elements']);_context(observation['context']);_context(expected)
if observation['context']!=expected:raise TargetError('STALE_OBSERVATION')
if type(observation['has_more']) is not bool:raise TargetError('INVALID_COMPLETENESS')
_keys(target,['name','role','href','frame','in_viewport'])
_text(target['name']);_text(target['role'])
for field in ['href','frame']:
if target[field] is not None:_text(target[field])
if target['in_viewport'] is not None and type(target['in_viewport']) is not bool:raise TargetError('INVALID_VIEWPORT')
elements=observation['elements']
if not isinstance(elements,list) or len(elements)>1000:raise TargetError('INVALID_ELEMENTS')
seen=set();matches=[]
for element in elements:
_keys(element,['id','name','role','href','frame','visible','in_viewport','disabled'])
for field in ['id','name','role','frame']:_text(element[field])
if element['href'] is not None:_text(element['href'])
if any(type(element[k]) is not bool for k in ['visible','in_viewport','disabled']):raise TargetError('INVALID_STATE')
if element['id'] in seen:raise TargetError('DUPLICATE_REFERENCE')
seen.add(element['id'])
if not element['visible']:continue
if _norm(element['name'])!=_norm(target['name']) or _norm(element['role'])!=_norm(target['role']):continue
if any(target[k] is not None and target[k]!=element[k] for k in ['href','frame','in_viewport']):continue
matches.append(element)
if observation['has_more']:raise TargetError('TARGET_QUERY_TRUNCATED')
if len(matches)>1:raise TargetError('TARGET_AMBIGUOUS')
if not matches:raise TargetError('TARGET_NOT_FOUND')
if matches[0]['disabled']:raise TargetError('TARGET_DISABLED')
return {'context':copy.deepcopy(expected),'target':copy.deepcopy(matches[0]),'authorized':False,'dispatched':False}
A truncated observation cannot establish uniqueness
When more results remain, even a single match in the current slice fails as truncated. Reusing one reference ID for different nodes also fails. A plausible first item does not establish a unique target.
Twenty-one tests cover uniqueness, duplicates, hidden and disabled duplicates, one disabled target, offscreen ambiguity, explicit viewport, frame and href conditions. Changed tab, epoch and snapshot, truncation, invalid types, unknown fields and unchanged inputs have separate checks. The code tests stopping boundaries as well as successful selection.
Generate actual synthetic selection records
Five records show unique selection, ambiguous names, truncated observation, an old document and explicit frame narrowing. Local Python generated them. The displayed selector reads stored results; it does not discover visitor tabs or press a button on the current site.
After source tests, the package procedure compares file hashes, extracts the public ZIP into another folder and runs the same twenty-one tests. Both inline language viewers are checked against records with DOM stubs. These verify synthetic code and record display, not rendered-browser interaction, live-site operation or keyboard review.
Responsibilities immediately before a real click
The ZIP contains complete code, tests, examples, record generation and README, using the standard library with modification and reuse permitted. Authorization and dispatch always remain false in the result. Successful selection establishes neither account permission nor live-node actionability.
An adapter must recheck the actual document, node, occlusion, references and task permissions before dispatch, then read the outcome. This function does not lock the page between selection and action. I share a small decision component for studying ambiguity rather than presenting it as a whole browser automation engine.