browser-use 0.2.0 → 0.3.0

package/dist/controller/views.d.ts

@@ -1,241 +1,164 @@
 import { z } from 'zod';
 export declare const SearchGoogleActionSchema: z.ZodObject<{
     query: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    query: string;
-}, {
-    query: string;
-}>;
+}, z.core.$strip>;
 export type SearchGoogleAction = z.infer<typeof SearchGoogleActionSchema>;
+export declare const SearchActionSchema: z.ZodObject<{
+    query: z.ZodString;
+    engine: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+export type SearchAction = z.infer<typeof SearchActionSchema>;
 export declare const GoToUrlActionSchema: z.ZodObject<{
     url: z.ZodString;
     new_tab: z.ZodDefault<z.ZodBoolean>;
-}, "strip", z.ZodTypeAny, {
-    url: string;
-    new_tab: boolean;
-}, {
-    url: string;
-    new_tab?: boolean | undefined;
-}>;
+}, z.core.$strip>;
 export type GoToUrlAction = z.infer<typeof GoToUrlActionSchema>;
 export declare const WaitActionSchema: z.ZodObject<{
     seconds: z.ZodDefault<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    seconds: number;
-}, {
-    seconds?: number | undefined;
-}>;
+}, z.core.$strip>;
 export type WaitAction = z.infer<typeof WaitActionSchema>;
 export declare const ClickElementActionSchema: z.ZodObject<{
-    index: z.ZodNumber;
-}, "strip", z.ZodTypeAny, {
-    index: number;
-}, {
-    index: number;
-}>;
+    index: z.ZodOptional<z.ZodNumber>;
+    coordinate_x: z.ZodOptional<z.ZodNumber>;
+    coordinate_y: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
 export type ClickElementAction = z.infer<typeof ClickElementActionSchema>;
+export declare const ClickElementActionIndexOnlySchema: z.ZodObject<{
+    index: z.ZodNumber;
+}, z.core.$strip>;
+export type ClickElementActionIndexOnly = z.infer<typeof ClickElementActionIndexOnlySchema>;
 export declare const InputTextActionSchema: z.ZodObject<{
     index: z.ZodNumber;
     text: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    index: number;
-    text: string;
-}, {
-    index: number;
-    text: string;
-}>;
+    clear: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
 export type InputTextAction = z.infer<typeof InputTextActionSchema>;
 export declare const DoneActionSchema: z.ZodObject<{
     text: z.ZodString;
-    success: z.ZodBoolean;
-    files_to_display: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-}, "strip", z.ZodTypeAny, {
-    text: string;
-    success: boolean;
-    files_to_display: string[];
-}, {
-    text: string;
-    success: boolean;
-    files_to_display?: string[] | undefined;
-}>;
+    success: z.ZodDefault<z.ZodBoolean>;
+    files_to_display: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
 export type DoneAction = z.infer<typeof DoneActionSchema>;
 export declare const StructuredOutputActionSchema: <T extends z.ZodTypeAny>(dataSchema: T) => z.ZodObject<{
     success: z.ZodDefault<z.ZodBoolean>;
     data: T;
-}, "strip", z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<{
-    success: z.ZodDefault<z.ZodBoolean>;
-    data: T;
-}>, any> extends infer T_1 ? { [k in keyof T_1]: T_1[k]; } : never, z.baseObjectInputType<{
-    success: z.ZodDefault<z.ZodBoolean>;
-    data: T;
-}> extends infer T_2 ? { [k_1 in keyof T_2]: T_2[k_1]; } : never>;
+}, z.core.$strip>;
 export type StructuredOutputAction<T> = {
     success: boolean;
     data: T;
 };
 export declare const SwitchTabActionSchema: z.ZodObject<{
-    page_id: z.ZodNumber;
-}, "strip", z.ZodTypeAny, {
-    page_id: number;
-}, {
-    page_id: number;
-}>;
+    page_id: z.ZodOptional<z.ZodNumber>;
+    tab_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
 export type SwitchTabAction = z.infer<typeof SwitchTabActionSchema>;
 export declare const CloseTabActionSchema: z.ZodObject<{
-    page_id: z.ZodNumber;
-}, "strip", z.ZodTypeAny, {
-    page_id: number;
-}, {
-    page_id: number;
-}>;
+    page_id: z.ZodOptional<z.ZodNumber>;
+    tab_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
 export type CloseTabAction = z.infer<typeof CloseTabActionSchema>;
 export declare const ScrollActionSchema: z.ZodObject<{
     down: z.ZodDefault<z.ZodBoolean>;
     num_pages: z.ZodDefault<z.ZodNumber>;
+    pages: z.ZodOptional<z.ZodNumber>;
     index: z.ZodOptional<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    down: boolean;
-    num_pages: number;
-    index?: number | undefined;
-}, {
-    index?: number | undefined;
-    down?: boolean | undefined;
-    num_pages?: number | undefined;
-}>;
+}, z.core.$strip>;
 export type ScrollAction = z.infer<typeof ScrollActionSchema>;
 export declare const SendKeysActionSchema: z.ZodObject<{
     keys: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    keys: string;
-}, {
-    keys: string;
-}>;
+}, z.core.$strip>;
 export type SendKeysAction = z.infer<typeof SendKeysActionSchema>;
 export declare const UploadFileActionSchema: z.ZodObject<{
     index: z.ZodNumber;
     path: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    index: number;
-    path: string;
-}, {
-    index: number;
-    path: string;
-}>;
+}, z.core.$strip>;
 export type UploadFileAction = z.infer<typeof UploadFileActionSchema>;
+export declare const ScreenshotActionSchema: z.ZodObject<{
+    file_name: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ScreenshotAction = z.infer<typeof ScreenshotActionSchema>;
+export declare const EvaluateActionSchema: z.ZodObject<{
+    code: z.ZodString;
+}, z.core.$strip>;
+export type EvaluateAction = z.infer<typeof EvaluateActionSchema>;
 export declare const ExtractPageContentActionSchema: z.ZodObject<{
     value: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    value: string;
-}, {
-    value: string;
-}>;
+}, z.core.$strip>;
 export type ExtractPageContentAction = z.infer<typeof ExtractPageContentActionSchema>;
 export declare const ExtractStructuredDataActionSchema: z.ZodObject<{
     query: z.ZodString;
     extract_links: z.ZodDefault<z.ZodBoolean>;
-}, "strip", z.ZodTypeAny, {
-    query: string;
-    extract_links: boolean;
-}, {
-    query: string;
-    extract_links?: boolean | undefined;
-}>;
+    start_from_char: z.ZodDefault<z.ZodNumber>;
+    output_schema: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, z.core.$strip>;
 export type ExtractStructuredDataAction = z.infer<typeof ExtractStructuredDataActionSchema>;
+export declare const SearchPageActionSchema: z.ZodObject<{
+    pattern: z.ZodString;
+    regex: z.ZodDefault<z.ZodBoolean>;
+    case_sensitive: z.ZodDefault<z.ZodBoolean>;
+    context_chars: z.ZodDefault<z.ZodNumber>;
+    css_scope: z.ZodOptional<z.ZodString>;
+    max_results: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type SearchPageAction = z.infer<typeof SearchPageActionSchema>;
+export declare const FindElementsActionSchema: z.ZodObject<{
+    selector: z.ZodString;
+    attributes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    max_results: z.ZodDefault<z.ZodNumber>;
+    include_text: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type FindElementsAction = z.infer<typeof FindElementsActionSchema>;
 export declare const ReadFileActionSchema: z.ZodObject<{
     file_name: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    file_name: string;
-}, {
-    file_name: string;
-}>;
+}, z.core.$strip>;
 export type ReadFileAction = z.infer<typeof ReadFileActionSchema>;
+export declare const ReadLongContentActionSchema: z.ZodObject<{
+    goal: z.ZodString;
+    source: z.ZodDefault<z.ZodString>;
+    context: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+export type ReadLongContentAction = z.infer<typeof ReadLongContentActionSchema>;
 export declare const WriteFileActionSchema: z.ZodObject<{
     file_name: z.ZodString;
     content: z.ZodString;
     append: z.ZodOptional<z.ZodBoolean>;
     trailing_newline: z.ZodOptional<z.ZodBoolean>;
     leading_newline: z.ZodOptional<z.ZodBoolean>;
-}, "strip", z.ZodTypeAny, {
-    file_name: string;
-    content: string;
-    append?: boolean | undefined;
-    trailing_newline?: boolean | undefined;
-    leading_newline?: boolean | undefined;
-}, {
-    file_name: string;
-    content: string;
-    append?: boolean | undefined;
-    trailing_newline?: boolean | undefined;
-    leading_newline?: boolean | undefined;
-}>;
+}, z.core.$strip>;
 export type WriteFileAction = z.infer<typeof WriteFileActionSchema>;
 export declare const ReplaceFileStrActionSchema: z.ZodObject<{
     file_name: z.ZodString;
     old_str: z.ZodString;
     new_str: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    file_name: string;
-    old_str: string;
-    new_str: string;
-}, {
-    file_name: string;
-    old_str: string;
-    new_str: string;
-}>;
+}, z.core.$strip>;
 export type ReplaceFileStrAction = z.infer<typeof ReplaceFileStrActionSchema>;
 export declare const ScrollToTextActionSchema: z.ZodObject<{
     text: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    text: string;
-}, {
-    text: string;
-}>;
+}, z.core.$strip>;
 export type ScrollToTextAction = z.infer<typeof ScrollToTextActionSchema>;
 export declare const DropdownOptionsActionSchema: z.ZodObject<{
     index: z.ZodNumber;
-}, "strip", z.ZodTypeAny, {
-    index: number;
-}, {
-    index: number;
-}>;
+}, z.core.$strip>;
 export type DropdownOptionsAction = z.infer<typeof DropdownOptionsActionSchema>;
 export declare const SelectDropdownActionSchema: z.ZodObject<{
     index: z.ZodNumber;
     text: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    index: number;
-    text: string;
-}, {
-    index: number;
-    text: string;
-}>;
+}, z.core.$strip>;
 export type SelectDropdownAction = z.infer<typeof SelectDropdownActionSchema>;
 export declare const SheetsRangeActionSchema: z.ZodObject<{
     cell_or_range: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    cell_or_range: string;
-}, {
-    cell_or_range: string;
-}>;
+}, z.core.$strip>;
 export type SheetsRangeAction = z.infer<typeof SheetsRangeActionSchema>;
 export declare const SheetsUpdateActionSchema: z.ZodObject<{
     cell_or_range: z.ZodString;
     value: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    value: string;
-    cell_or_range: string;
-}, {
-    value: string;
-    cell_or_range: string;
-}>;
+}, z.core.$strip>;
 export type SheetsUpdateAction = z.infer<typeof SheetsUpdateActionSchema>;
 export declare const SheetsInputActionSchema: z.ZodObject<{
     text: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    text: string;
-}, {
-    text: string;
-}>;
+}, z.core.$strip>;
 export type SheetsInputAction = z.infer<typeof SheetsInputActionSchema>;
-export declare const NoParamsActionSchema: z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>;
+export declare const NoParamsActionSchema: z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
 export type NoParamsAction = z.infer<typeof NoParamsActionSchema>;

package/dist/controller/views.js

@@ -2,6 +2,10 @@ import { z } from 'zod';
 export const SearchGoogleActionSchema = z.object({
     query: z.string(),
 });
+export const SearchActionSchema = z.object({
+    query: z.string(),
+    engine: z.string().default('duckduckgo'),
+});
 export const GoToUrlActionSchema = z.object({
     url: z.string(),
     new_tab: z.boolean().default(false),
@@ -10,30 +14,44 @@ export const WaitActionSchema = z.object({
     seconds: z.number().default(3),
 });
 export const ClickElementActionSchema = z.object({
-    index: z.number().int(),
+    index: z.number().int().min(1).optional(),
+    coordinate_x: z.number().int().optional(),
+    coordinate_y: z.number().int().optional(),
+});
+export const ClickElementActionIndexOnlySchema = z.object({
+    index: z.number().int().min(1),
 });
 export const InputTextActionSchema = z.object({
-    index: z.number().int(),
+    index: z.number().int().min(0),
     text: z.string(),
+    clear: z.boolean().default(true),
 });
 export const DoneActionSchema = z.object({
     text: z.string(),
-    success: z.boolean(),
+    success: z.boolean().default(true),
     files_to_display: z.array(z.string()).default([]),
 });
 export const StructuredOutputActionSchema = (dataSchema) => z.object({
-    success: z.boolean().default(true),
+    success: z
+        .boolean()
+        .default(true)
+        .describe('True if user_request completed successfully'),
     data: dataSchema,
 });
-export const SwitchTabActionSchema = z.object({
-    page_id: z.number().int(),
-});
-export const CloseTabActionSchema = z.object({
-    page_id: z.number().int(),
+const TabIdentifierActionSchema = z
+    .object({
+    page_id: z.number().int().optional(),
+    tab_id: z.string().trim().length(4).optional(),
+})
+    .refine((value) => value.page_id != null || value.tab_id != null, {
+    message: 'Provide tab_id or page_id',
 });
+export const SwitchTabActionSchema = TabIdentifierActionSchema;
+export const CloseTabActionSchema = TabIdentifierActionSchema;
 export const ScrollActionSchema = z.object({
     down: z.boolean().default(true), // Default to scroll down
     num_pages: z.number().default(1), // Default to 1 page
+    pages: z.number().optional(), // Alias for num_pages
     index: z.number().int().optional(),
 });
 export const SendKeysActionSchema = z.object({
@@ -43,16 +61,43 @@ export const UploadFileActionSchema = z.object({
     index: z.number().int(),
     path: z.string(),
 });
+export const ScreenshotActionSchema = z.object({
+    file_name: z.string().optional(),
+});
+export const EvaluateActionSchema = z.object({
+    code: z.string(),
+});
 export const ExtractPageContentActionSchema = z.object({
     value: z.string(),
 });
 export const ExtractStructuredDataActionSchema = z.object({
     query: z.string(),
     extract_links: z.boolean().default(false),
+    start_from_char: z.number().int().default(0),
+    output_schema: z.record(z.string(), z.unknown()).nullable().optional(),
+});
+export const SearchPageActionSchema = z.object({
+    pattern: z.string(),
+    regex: z.boolean().default(false),
+    case_sensitive: z.boolean().default(false),
+    context_chars: z.number().int().default(150),
+    css_scope: z.string().optional(),
+    max_results: z.number().int().default(25),
+});
+export const FindElementsActionSchema = z.object({
+    selector: z.string(),
+    attributes: z.array(z.string()).optional(),
+    max_results: z.number().int().default(50),
+    include_text: z.boolean().default(true),
 });
 export const ReadFileActionSchema = z.object({
     file_name: z.string(),
 });
+export const ReadLongContentActionSchema = z.object({
+    goal: z.string(),
+    source: z.string().default('page'),
+    context: z.string().default(''),
+});
 export const WriteFileActionSchema = z.object({
     file_name: z.string(),
     content: z.string(),
@@ -69,10 +114,10 @@ export const ScrollToTextActionSchema = z.object({
     text: z.string(),
 });
 export const DropdownOptionsActionSchema = z.object({
-    index: z.number().int(),
+    index: z.number().int().min(1),
 });
 export const SelectDropdownActionSchema = z.object({
-    index: z.number().int(),
+    index: z.number().int().min(1),
     text: z.string(),
 });
 export const SheetsRangeActionSchema = z.object({
@@ -85,4 +130,8 @@ export const SheetsUpdateActionSchema = z.object({
 export const SheetsInputActionSchema = z.object({
     text: z.string(),
 });
-export const NoParamsActionSchema = z.object({}).passthrough();
+export const NoParamsActionSchema = z
+    .object({
+    description: z.string().optional(),
+})
+    .passthrough();

package/dist/dom/history-tree-processor/service.d.ts

@@ -1,6 +1,11 @@
 import { DOMHistoryElement, HashedDomElement } from './view.js';
 import { DOMElementNode } from '../views.js';
 export declare class HistoryTreeProcessor {
+    static get_accessible_name(dom_element: DOMElementNode): string | null;
+    static compute_element_hash(dom_element: DOMElementNode): string;
+    static compute_stable_hash(dom_element: DOMElementNode): string;
+    static _filter_dynamic_classes(class_value: string): string;
+    static _compute_element_hash(dom_element: DOMElementNode, stable: boolean): string;
     static convert_dom_element_to_history_element(dom_element: DOMElementNode, css_selector?: string | null): DOMHistoryElement;
     static find_history_element_in_tree(dom_history_element: DOMHistoryElement, tree: DOMElementNode): DOMElementNode | null;
     static compare_history_element_and_dom_element(dom_history_element: DOMHistoryElement, dom_element: DOMElementNode): boolean;

package/dist/dom/history-tree-processor/service.js

@@ -2,33 +2,188 @@ import crypto from 'node:crypto';
 import { DOMHistoryElement, HashedDomElement } from './view.js';
 import { DOMElementNode } from '../views.js';
 const sha256 = (value) => crypto.createHash('sha256').update(value).digest('hex');
+const STATIC_HASH_ATTRIBUTES = new Set([
+    'class',
+    'id',
+    'name',
+    'type',
+    'placeholder',
+    'aria-label',
+    'title',
+    'role',
+    'data-testid',
+    'data-test',
+    'data-cy',
+    'for',
+    'required',
+    'disabled',
+    'readonly',
+    'checked',
+    'selected',
+    'multiple',
+    'href',
+    'target',
+    'rel',
+    'aria-describedby',
+    'aria-labelledby',
+    'aria-controls',
+    'aria-owns',
+    'aria-live',
+    'aria-atomic',
+    'aria-busy',
+    'aria-disabled',
+    'aria-hidden',
+    'aria-pressed',
+    'aria-autocomplete',
+    'aria-checked',
+    'aria-selected',
+    'list',
+    'tabindex',
+    'alt',
+    'src',
+    'lang',
+    'itemscope',
+    'itemtype',
+    'itemprop',
+    'aria-valuemin',
+    'aria-valuemax',
+    'aria-valuenow',
+    'aria-placeholder',
+]);
+const DYNAMIC_CLASS_PATTERNS = [
+    'focus',
+    'hover',
+    'active',
+    'selected',
+    'disabled',
+    'animation',
+    'transition',
+    'loading',
+    'open',
+    'closed',
+    'expanded',
+    'collapsed',
+    'visible',
+    'hidden',
+    'pressed',
+    'checked',
+    'highlighted',
+    'current',
+    'entering',
+    'leaving',
+];
 export class HistoryTreeProcessor {
+    static get_accessible_name(dom_element) {
+        const ariaLabel = dom_element.attributes?.['aria-label']?.trim();
+        if (ariaLabel) {
+            return ariaLabel;
+        }
+        const title = dom_element.attributes?.title?.trim();
+        if (title) {
+            return title;
+        }
+        const text = dom_element.get_all_text_till_next_clickable_element().trim();
+        return text ? text : null;
+    }
+    static compute_element_hash(dom_element) {
+        return this._compute_element_hash(dom_element, false);
+    }
+    static compute_stable_hash(dom_element) {
+        return this._compute_element_hash(dom_element, true);
+    }
+    static _filter_dynamic_classes(class_value) {
+        const classes = class_value
+            .split(/\s+/)
+            .map((value) => value.trim())
+            .filter(Boolean);
+        const stable = classes.filter((cls) => !DYNAMIC_CLASS_PATTERNS.some((pattern) => cls.toLowerCase().includes(pattern)));
+        return stable.sort().join(' ');
+    }
+    static _compute_element_hash(dom_element, stable) {
+        const parent_branch_path = this._get_parent_branch_path(dom_element);
+        const parent_branch_path_string = parent_branch_path.join('/');
+        const normalized_attributes = Object.entries(dom_element.attributes ?? {})
+            .filter(([key, value]) => {
+            if (!STATIC_HASH_ATTRIBUTES.has(key)) {
+                return false;
+            }
+            return String(value).trim().length > 0;
+        })
+            .map(([key, value]) => {
+            if (stable && key === 'class') {
+                const filtered = this._filter_dynamic_classes(String(value));
+                return [key, filtered];
+            }
+            return [key, String(value)];
+        })
+            .filter(([, value]) => value.length > 0)
+            .sort(([a], [b]) => a.localeCompare(b));
+        const attributes_string = normalized_attributes
+            .map(([key, value]) => `${key}=${value}`)
+            .join('');
+        const ax_name = this.get_accessible_name(dom_element);
+        const ax_suffix = ax_name ? `|ax_name=${ax_name}` : '';
+        const combined_string = `${parent_branch_path_string}|${attributes_string}${ax_suffix}`;
+        return sha256(combined_string).slice(0, 16);
+    }
     static convert_dom_element_to_history_element(dom_element, css_selector = null) {
         const parent_branch_path = this._get_parent_branch_path(dom_element);
-        return new DOMHistoryElement(dom_element.tag_name, dom_element.xpath, dom_element.highlight_index ?? null, parent_branch_path, dom_element.attributes, dom_element.shadow_root, css_selector, dom_element.page_coordinates, dom_element.viewport_coordinates, dom_element.viewport_info);
+        const axName = this.get_accessible_name(dom_element);
+        const elementHash = this.compute_element_hash(dom_element);
+        const stableHash = this.compute_stable_hash(dom_element);
+        return new DOMHistoryElement(dom_element.tag_name, dom_element.xpath, dom_element.highlight_index ?? null, parent_branch_path, dom_element.attributes, dom_element.shadow_root, css_selector, dom_element.page_coordinates, dom_element.viewport_coordinates, dom_element.viewport_info, elementHash, stableHash, axName);
     }
     static find_history_element_in_tree(dom_history_element, tree) {
-        const hashed = this._hash_dom_history_element(dom_history_element);
-        const process_node = (node) => {
-            if (node.highlight_index !== null && node.highlight_index !== undefined) {
-                const hashed_node = this._hash_dom_element(node);
-                if (hashed_node.equals(hashed)) {
-                    return node;
-                }
+        const process_node = (node, matcher) => {
+            if (node.highlight_index !== null &&
+                node.highlight_index !== undefined &&
+                matcher(node)) {
+                return node;
             }
             for (const child of node.children) {
-                if (child instanceof DOMElementNode) {
-                    const result = process_node(child);
-                    if (result) {
-                        return result;
-                    }
+                if (!(child instanceof DOMElementNode)) {
+                    continue;
+                }
+                const result = process_node(child, matcher);
+                if (result) {
+                    return result;
                 }
             }
             return null;
         };
-        return process_node(tree);
+        if (dom_history_element.element_hash) {
+            const exact = process_node(tree, (candidate) => this.compute_element_hash(candidate) ===
+                dom_history_element.element_hash);
+            if (exact) {
+                return exact;
+            }
+        }
+        if (dom_history_element.stable_hash) {
+            const stable = process_node(tree, (candidate) => this.compute_stable_hash(candidate) ===
+                dom_history_element.stable_hash);
+            if (stable) {
+                return stable;
+            }
+        }
+        const hashed = this._hash_dom_history_element(dom_history_element);
+        return process_node(tree, (candidate) => {
+            const hashed_node = this._hash_dom_element(candidate);
+            return hashed_node.equals(hashed);
+        });
     }
     static compare_history_element_and_dom_element(dom_history_element, dom_element) {
+        if (dom_history_element.element_hash) {
+            if (this.compute_element_hash(dom_element) ===
+                dom_history_element.element_hash) {
+                return true;
+            }
+        }
+        if (dom_history_element.stable_hash) {
+            if (this.compute_stable_hash(dom_element) ===
+                dom_history_element.stable_hash) {
+                return true;
+            }
+        }
         const hashed_history = this._hash_dom_history_element(dom_history_element);
         const hashed_dom = this._hash_dom_element(dom_element);
         return hashed_history.equals(hashed_dom);

package/dist/dom/history-tree-processor/view.d.ts

@@ -38,7 +38,10 @@ export declare class DOMHistoryElement {
     page_coordinates: CoordinateSet | null;
     viewport_coordinates: CoordinateSet | null;
     viewport_info: ViewportInfo | null;
-    constructor(tag_name: string, xpath: string, highlight_index: number | null, entire_parent_branch_path: string[], attributes: Record<string, string>, shadow_root?: boolean, css_selector?: string | null, page_coordinates?: CoordinateSet | null, viewport_coordinates?: CoordinateSet | null, viewport_info?: ViewportInfo | null);
+    element_hash: string | null;
+    stable_hash: string | null;
+    ax_name: string | null;
+    constructor(tag_name: string, xpath: string, highlight_index: number | null, entire_parent_branch_path: string[], attributes: Record<string, string>, shadow_root?: boolean, css_selector?: string | null, page_coordinates?: CoordinateSet | null, viewport_coordinates?: CoordinateSet | null, viewport_info?: ViewportInfo | null, element_hash?: string | null, stable_hash?: string | null, ax_name?: string | null);
     to_dict(): {
         tag_name: string;
         xpath: string;
@@ -50,5 +53,8 @@ export declare class DOMHistoryElement {
         page_coordinates: CoordinateSet | null;
         viewport_coordinates: CoordinateSet | null;
         viewport_info: ViewportInfo | null;
+        element_hash: string | null;
+        stable_hash: string | null;
+        ax_name: string | null;
     };
 }