alumnium 0.16.0 → 0.18.0

package/dist/Alumni.d.ts

@@ -7,11 +7,15 @@ import { Data } from "./clients/typecasting.js";
 import { BaseDriver } from "./drivers/BaseDriver.js";
 import { Element } from "./drivers/index.js";
 import { Model } from "./Model.js";
+import { DoResult } from "./result.js";
 import { ToolClass } from "./tools/BaseTool.js";
 export interface AlumniOptions {
     url?: string;
     model?: Model;
     extraTools?: ToolClass[];
+    planner?: boolean;
+    changeAnalysis?: boolean;
+    excludedAttributes?: Set<string>;
 }
 export interface VisionOptions {
     vision?: boolean;
@@ -23,9 +27,10 @@ export declare class Alumni {
     cache: Cache;
     private url;
     private model;
+    private changeAnalysis;
     constructor(driver: WebDriver | Page | Browser, options?: AlumniOptions);
     quit(): Promise<void>;
-    do(goal: string): Promise<void>;
+    do(goal: string): Promise<DoResult>;
     check(statement: string, options?: VisionOptions): Promise<string>;
     get(data: string, options?: VisionOptions): Promise<Data>;
     find(description: string): Promise<Element>;

package/dist/Alumni.js

@@ -1,3 +1,12 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
 import { WebDriver } from "selenium-webdriver";
 import { Area } from "./Area.js";
 import { Cache } from "./Cache.js";
@@ -8,18 +17,18 @@ import { SeleniumDriver } from "./drivers/SeleniumDriver.js";
 import { AssertionError } from "./errors/AssertionError.js";
 import { Model } from "./Model.js";
 import { BaseTool } from "./tools/BaseTool.js";
-import { ClickTool } from "./tools/ClickTool.js";
-import { DragAndDropTool } from "./tools/DragAndDropTool.js";
-import { HoverTool } from "./tools/HoverTool.js";
-import { PressKeyTool } from "./tools/PressKeyTool.js";
-import { SelectTool } from "./tools/SelectTool.js";
-import { TypeTool } from "./tools/TypeTool.js";
 import { getLogger } from "./utils/logger.js";
+import { retry } from "./utils/retry.js";
 const logger = getLogger(["Alumni"]);
+const changeAnalysis = (process.env.ALUMNIUM_CHANGE_ANALYSIS || "false").toLowerCase() === "true";
+const planner = (process.env.ALUMNIUM_PLANNER || "true").toLowerCase() === "true";
+const excludedAttributes = new Set((process.env.ALUMNIUM_EXCLUDE_ATTRIBUTES || "").split(",").filter(Boolean));
 export class Alumni {
     constructor(driver, options = {}) {
+        this.tools = {};
         this.url = options.url || "http://localhost:8013";
         this.model = options.model || Model.current;
+        this.changeAnalysis = options.changeAnalysis ?? changeAnalysis;
         // Wrap driver or use directly if already wrapped
         if (driver instanceof WebDriver) {
             this.driver = new SeleniumDriver(driver);
@@ -35,23 +44,14 @@ export class Alumni {
         else {
             throw new Error(`Unsupported driver type '${typeof driver}'`);
         }
-        // Initialize tools
-        this.tools = {
-            ClickTool,
-            TypeTool,
-            HoverTool,
-            SelectTool,
-            PressKeyTool,
-            DragAndDropTool,
-        };
-        // Add extra tools if provided
-        if (options.extraTools) {
-            for (const tool of options.extraTools) {
-                this.tools[tool.name] = tool;
-            }
+        for (const tool of new Set([
+            ...this.driver.supportedTools,
+            ...(options.extraTools || []),
+        ])) {
+            this.tools[tool.name] = tool;
         }
         // Initialize HTTP client
-        this.client = new HttpClient(this.url, this.model, this.driver.platform, this.tools);
+        this.client = new HttpClient(this.url, this.model, this.driver.platform, this.tools, options.planner ?? planner, options.excludedAttributes ?? excludedAttributes);
         this.cache = new Cache(this.client);
         logger.info(`Using model: ${this.model.provider}/${this.model.name}`);
         logger.info(`Using HTTP client with server: ${this.url}`);
@@ -61,27 +61,45 @@ export class Alumni {
         await this.driver.quit();
     }
     async do(goal) {
+        const app = await this.driver.app();
         const initialAccessibilityTree = await this.driver.getAccessibilityTree();
-        const steps = await this.client.planActions(goal, initialAccessibilityTree.toStr());
+        const beforeTree = this.changeAnalysis
+            ? initialAccessibilityTree.toStr()
+            : null;
+        const beforeUrl = this.changeAnalysis ? await this.driver.url() : null;
+        const { explanation, steps } = await this.client.planActions(goal, initialAccessibilityTree.toStr(), app);
+        let finalExplanation = explanation;
+        const executedSteps = [];
         for (let idx = 0; idx < steps.length; idx++) {
             const step = steps[idx];
             // Use initial tree for first step, fresh tree for subsequent steps
             const accessibilityTree = idx === 0
                 ? initialAccessibilityTree
                 : await this.driver.getAccessibilityTree();
-            const actorResponse = await this.client.executeAction(goal, step, accessibilityTree.toStr());
-            // Execute tool calls
-            for (const toolCall of actorResponse) {
-                await BaseTool.executeToolCall(toolCall, this.tools, this.driver);
+            const { explanation: actorExplanation, actions } = await this.client.executeAction(goal, step, accessibilityTree.toStr(), app);
+            // When planner is off, explanation is just the goal — replace with actor's reasoning.
+            if (finalExplanation === goal) {
+                finalExplanation = actorExplanation;
+            }
+            const calledTools = [];
+            for (const toolCall of actions) {
+                const calledTool = await BaseTool.executeToolCall(toolCall, this.tools, this.driver);
+                calledTools.push(calledTool);
             }
+            executedSteps.push({ name: step, tools: calledTools });
+        }
+        let changes = "";
+        if (this.changeAnalysis && executedSteps.length > 0) {
+            changes = await this.client.analyzeChanges(beforeTree, beforeUrl, (await this.driver.getAccessibilityTree()).toStr(), await this.driver.url());
         }
+        return { explanation: finalExplanation, steps: executedSteps, changes };
     }
     async check(statement, options = {}) {
         const screenshot = options.vision
             ? await this.driver.screenshot()
             : undefined;
         const accessibilityTree = await this.driver.getAccessibilityTree();
-        const [explanation, value] = await this.client.retrieve(`Is the following true or false - ${statement}`, accessibilityTree.toStr(), await this.driver.title(), await this.driver.url(), screenshot);
+        const [explanation, value] = await this.client.retrieve(`Is the following true or false - ${statement}`, accessibilityTree.toStr(), await this.driver.title(), await this.driver.url(), screenshot, await this.driver.app());
         if (!value) {
             throw new AssertionError(explanation);
         }
@@ -92,18 +110,17 @@ export class Alumni {
             ? await this.driver.screenshot()
             : undefined;
         const accessibilityTree = await this.driver.getAccessibilityTree();
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        const [_explanation, value] = await this.client.retrieve(data, accessibilityTree.toStr(), await this.driver.title(), await this.driver.url(), screenshot);
-        return value;
+        const [explanation, value] = await this.client.retrieve(data, accessibilityTree.toStr(), await this.driver.title(), await this.driver.url(), screenshot, await this.driver.app());
+        return value === null ? explanation : value;
     }
     async find(description) {
         const accessibilityTree = await this.driver.getAccessibilityTree();
-        const response = await this.client.findElement(description, accessibilityTree.toStr());
+        const response = await this.client.findElement(description, accessibilityTree.toStr(), await this.driver.app());
         return this.driver.findElement(response.id);
     }
     async area(description) {
         const accessibilityTree = await this.driver.getAccessibilityTree();
-        const response = await this.client.findArea(description, accessibilityTree.toStr());
+        const response = await this.client.findArea(description, accessibilityTree.toStr(), await this.driver.app());
         const scopedTree = accessibilityTree.scopeToArea(response.id);
         return new Area(response.id, response.explanation, scopedTree, this.driver, this.tools, this.client);
     }
@@ -117,3 +134,27 @@ export class Alumni {
         return await this.client.getStats();
     }
 }
+__decorate([
+    retry(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", Promise)
+], Alumni.prototype, "do", null);
+__decorate([
+    retry(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object]),
+    __metadata("design:returntype", Promise)
+], Alumni.prototype, "check", null);
+__decorate([
+    retry(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object]),
+    __metadata("design:returntype", Promise)
+], Alumni.prototype, "get", null);
+__decorate([
+    retry(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", Promise)
+], Alumni.prototype, "find", null);

package/dist/Area.d.ts

@@ -4,6 +4,7 @@ import { HttpClient } from "./clients/HttpClient.js";
 import { Data } from "./clients/typecasting.js";
 import { BaseDriver } from "./drivers/BaseDriver.js";
 import { Element } from "./drivers/index.js";
+import { DoResult } from "./result.js";
 import { ToolClass } from "./tools/BaseTool.js";
 export declare class Area {
     id: number;
@@ -13,7 +14,7 @@ export declare class Area {
     private tools;
     private client;
     constructor(id: number, description: string, accessibilityTree: BaseAccessibilityTree, driver: BaseDriver, tools: Record<string, ToolClass>, client: HttpClient);
-    do(goal: string): Promise<void>;
+    do(goal: string): Promise<DoResult>;
     check(statement: string, options?: VisionOptions): Promise<string>;
     get(data: string, options?: VisionOptions): Promise<Data>;
     find(description: string): Promise<Element>;

package/dist/Area.js

@@ -1,5 +1,15 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
 import { AssertionError } from "./errors/AssertionError.js";
 import { BaseTool } from "./tools/BaseTool.js";
+import { retry } from "./utils/retry.js";
 export class Area {
     constructor(id, description, accessibilityTree, driver, tools, client) {
         this.id = id;
@@ -10,20 +20,30 @@ export class Area {
         this.client = client;
     }
     async do(goal) {
-        const steps = await this.client.planActions(goal, this.accessibilityTree.toStr());
+        const app = await this.driver.app();
+        const { explanation, steps } = await this.client.planActions(goal, this.accessibilityTree.toStr(), app);
+        let finalExplanation = explanation;
+        const executedSteps = [];
         for (const step of steps) {
-            const actorResponse = await this.client.executeAction(goal, step, this.accessibilityTree.toStr());
-            // Execute tool calls
-            for (const toolCall of actorResponse) {
-                await BaseTool.executeToolCall(toolCall, this.tools, this.driver);
+            const { explanation: actorExplanation, actions } = await this.client.executeAction(goal, step, this.accessibilityTree.toStr(), app);
+            // When planner is off, explanation is just the goal — replace with actor's reasoning.
+            if (finalExplanation === goal) {
+                finalExplanation = actorExplanation;
             }
+            const calledTools = [];
+            for (const toolCall of actions) {
+                const calledTool = await BaseTool.executeToolCall(toolCall, this.tools, this.driver);
+                calledTools.push(calledTool);
+            }
+            executedSteps.push({ name: step, tools: calledTools });
         }
+        return { explanation: finalExplanation, steps: executedSteps, changes: "" };
     }
     async check(statement, options = {}) {
         const screenshot = options.vision
             ? await this.driver.screenshot()
             : undefined;
-        const [explanation, value] = await this.client.retrieve(`Is the following true or false - ${statement}`, this.accessibilityTree.toStr(), await this.driver.title(), await this.driver.url(), screenshot);
+        const [explanation, value] = await this.client.retrieve(`Is the following true or false - ${statement}`, this.accessibilityTree.toStr(), await this.driver.title(), await this.driver.url(), screenshot, await this.driver.app());
         if (!value) {
             throw new AssertionError(explanation);
         }
@@ -33,12 +53,35 @@ export class Area {
         const screenshot = options.vision
             ? await this.driver.screenshot()
             : undefined;
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        const [_explanation, value] = await this.client.retrieve(data, this.accessibilityTree.toStr(), await this.driver.title(), await this.driver.url(), screenshot);
-        return value;
+        const [explanation, value] = await this.client.retrieve(data, this.accessibilityTree.toStr(), await this.driver.title(), await this.driver.url(), screenshot, await this.driver.app());
+        return value === null ? explanation : value;
     }
     async find(description) {
-        const response = await this.client.findElement(description, this.accessibilityTree.toStr());
+        const response = await this.client.findElement(description, this.accessibilityTree.toStr(), await this.driver.app());
         return this.driver.findElement(response.id);
     }
 }
+__decorate([
+    retry(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", Promise)
+], Area.prototype, "do", null);
+__decorate([
+    retry(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object]),
+    __metadata("design:returntype", Promise)
+], Area.prototype, "check", null);
+__decorate([
+    retry(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object]),
+    __metadata("design:returntype", Promise)
+], Area.prototype, "get", null);
+__decorate([
+    retry(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", Promise)
+], Area.prototype, "find", null);

package/dist/Model.d.ts

@@ -1,4 +1,5 @@
 export declare enum Provider {
+    AZURE_FOUNDRY = "azure_foundry",
     AZURE_OPENAI = "azure_openai",
     ANTHROPIC = "anthropic",
     AWS_ANTHROPIC = "aws_anthropic",

package/dist/Model.js

@@ -1,5 +1,6 @@
 export var Provider;
 (function (Provider) {
+    Provider["AZURE_FOUNDRY"] = "azure_foundry";
     Provider["AZURE_OPENAI"] = "azure_openai";
     Provider["ANTHROPIC"] = "anthropic";
     Provider["AWS_ANTHROPIC"] = "aws_anthropic";
@@ -15,17 +16,18 @@ export var Provider;
 export class ModelName {
 }
 ModelName.DEFAULT = {
-    [Provider.AZURE_OPENAI]: "gpt-4o-mini",
+    [Provider.AZURE_FOUNDRY]: "gpt-5-nano",
+    [Provider.AZURE_OPENAI]: "gpt-5-nano",
     [Provider.ANTHROPIC]: "claude-haiku-4-5-20251001",
     [Provider.AWS_ANTHROPIC]: "us.anthropic.claude-haiku-4-5-20251001-v1:0",
     [Provider.AWS_META]: "us.meta.llama4-maverick-17b-instruct-v1:0",
-    [Provider.DEEPSEEK]: "deepseek-chat",
+    [Provider.DEEPSEEK]: "deepseek-reasoner",
     [Provider.GITHUB]: "gpt-4o-mini",
-    [Provider.GOOGLE]: "gemini-2.0-flash-001",
+    [Provider.GOOGLE]: "gemini-3.1-flash-lite-preview",
     [Provider.MISTRALAI]: "mistral-medium-2505",
     [Provider.OLLAMA]: "mistral-small3.1",
-    [Provider.OPENAI]: "gpt-4o-mini-2024-07-18",
-    [Provider.XAI]: "grok-4-fast-non-reasoning",
+    [Provider.OPENAI]: "gpt-5-nano-2025-08-07",
+    [Provider.XAI]: "grok-4-1-fast-reasoning",
 };
 export class Model {
     constructor(provider, name) {

package/dist/accessibility/AccessibilityElement.d.ts

@@ -10,5 +10,8 @@ export declare class AccessibilityElement {
     androidText?: string;
     androidContentDesc?: string;
     androidBounds?: string;
-    constructor(id?: number, name?: string, label?: string, type?: string, value?: string, backendNodeId?: number, androidResourceId?: string, androidClass?: string, androidText?: string, androidContentDesc?: string, androidBounds?: string);
+    frame?: object;
+    locatorInfo?: Record<string, unknown>;
+    frameChain?: number[];
+    constructor(id?: number, name?: string, label?: string, type?: string, value?: string, backendNodeId?: number, androidResourceId?: string, androidClass?: string, androidText?: string, androidContentDesc?: string, androidBounds?: string, frame?: object, locatorInfo?: Record<string, unknown>, frameChain?: number[]);
 }

package/dist/accessibility/AccessibilityElement.js

@@ -1,5 +1,5 @@
 export class AccessibilityElement {
-    constructor(id, name, label, type, value, backendNodeId, androidResourceId, androidClass, androidText, androidContentDesc, androidBounds) {
+    constructor(id, name, label, type, value, backendNodeId, androidResourceId, androidClass, androidText, androidContentDesc, androidBounds, frame, locatorInfo, frameChain) {
         this.id = id;
         this.backendNodeId = backendNodeId;
         this.name = name;
@@ -11,5 +11,8 @@ export class AccessibilityElement {
         this.androidText = androidText;
         this.androidContentDesc = androidContentDesc;
         this.androidBounds = androidBounds;
+        this.frame = frame;
+        this.locatorInfo = locatorInfo;
+        this.frameChain = frameChain;
     }
 }

package/dist/accessibility/ChromiumAccessibilityTree.d.ts

@@ -4,11 +4,14 @@ export declare class ChromiumAccessibilityTree extends BaseAccessibilityTree {
     private cdpResponse;
     private nextRawId;
     private raw;
+    private frameMap;
+    private frameChainMap;
     constructor(cdpResponse: unknown);
     private static fromXml;
     toStr(): string;
     private nodeToXml;
     private elementToString;
+    private unescapeXml;
     elementById(rawId: number): AccessibilityElement;
     scopeToArea(rawId: number): ChromiumAccessibilityTree;
     private findElementByRawId;

package/dist/accessibility/ChromiumAccessibilityTree.js

@@ -5,11 +5,16 @@ export class ChromiumAccessibilityTree extends BaseAccessibilityTree {
         super();
         this.nextRawId = 0;
         this.raw = null;
+        this.frameMap = new Map();
+        this.frameChainMap = new Map(); // raw_id -> frame chain
         this.cdpResponse = cdpResponse;
     }
-    static fromXml(xmlString) {
+    static fromXml(xmlString, frameMap) {
         const instance = new ChromiumAccessibilityTree({ nodes: [] });
         instance.raw = xmlString;
+        if (frameMap) {
+            instance.frameMap = frameMap;
+        }
         return instance;
     }
     toStr() {
@@ -17,18 +22,38 @@ export class ChromiumAccessibilityTree extends BaseAccessibilityTree {
             return this.raw;
         }
         const nodes = this.cdpResponse.nodes;
+        if (!nodes || nodes.length === 0) {
+            this.raw = "";
+            return this.raw;
+        }
         const nodeLookup = {};
         for (const node of nodes) {
             nodeLookup[node.nodeId] = node;
         }
-        // Build tree structure and convert to XML
-        const rootNodes = [];
+        // Build mapping: backendDOMNodeId -> list of iframe child root nodes
+        // This allows us to inline iframe content inside their parent <Iframe> elements
+        const iframeChildren = new Map();
+        const trueRoots = [];
         for (const node of nodes) {
             if (!node.parentId) {
-                const xmlNode = this.nodeToXml(node, nodeLookup);
-                rootNodes.push(xmlNode);
+                const parentIframeId = node._parent_iframe_backend_node_id;
+                if (parentIframeId !== undefined) {
+                    if (!iframeChildren.has(parentIframeId)) {
+                        iframeChildren.set(parentIframeId, []);
+                    }
+                    iframeChildren.get(parentIframeId).push(node);
+                }
+                else {
+                    trueRoots.push(node);
+                }
             }
         }
+        // Build tree structure and convert to XML (only from true roots)
+        const rootNodes = [];
+        for (const node of trueRoots) {
+            const xmlNode = this.nodeToXml(node, nodeLookup, iframeChildren);
+            rootNodes.push(xmlNode);
+        }
         // Combine all root nodes into a single XML string
         let xmlString = "";
         for (const root of rootNodes) {
@@ -37,7 +62,7 @@ export class ChromiumAccessibilityTree extends BaseAccessibilityTree {
         this.raw = xmlString;
         return this.raw;
     }
-    nodeToXml(node, nodeLookup) {
+    nodeToXml(node, nodeLookup, iframeChildren) {
         const role = node.role?.value || "unknown";
         const elem = {
             tag: role,
@@ -47,6 +72,24 @@ export class ChromiumAccessibilityTree extends BaseAccessibilityTree {
         // Add our own sequential raw_id attribute
         this.nextRawId++;
         elem.attributes.raw_id = String(this.nextRawId);
+        // Store frame reference if present
+        if (node._frame) {
+            this.frameMap.set(this.nextRawId, node._frame);
+        }
+        // Store frame chain if present (for Selenium nested frame switching)
+        if (node._frame_chain) {
+            this.frameChainMap.set(this.nextRawId, node._frame_chain);
+        }
+        // Store Playwright node metadata
+        if (node._playwright_node) {
+            elem.attributes._playwright_node = "true";
+        }
+        if (node._locator_info) {
+            elem.attributes._locator_info = JSON.stringify(node._locator_info);
+        }
+        if (node._frame_url) {
+            elem.attributes._frame_url = node._frame_url;
+        }
         // Add all node attributes as XML attributes
         if (node.backendDOMNodeId !== undefined) {
             elem.attributes.backendDOMNodeId = String(node.backendDOMNodeId);
@@ -84,11 +127,19 @@ export class ChromiumAccessibilityTree extends BaseAccessibilityTree {
         if (node.childIds) {
             for (const childId of node.childIds) {
                 if (childId in nodeLookup) {
-                    const childElem = this.nodeToXml(nodeLookup[childId], nodeLookup);
+                    const childElem = this.nodeToXml(nodeLookup[childId], nodeLookup, iframeChildren);
                     elem.children.push(childElem);
                 }
             }
         }
+        // Inline iframe content: if this element is an iframe, add its child trees
+        const backendNodeId = node.backendDOMNodeId;
+        if (backendNodeId !== undefined && iframeChildren.has(backendNodeId)) {
+            for (const childRoot of iframeChildren.get(backendNodeId)) {
+                const childElem = this.nodeToXml(childRoot, nodeLookup, iframeChildren);
+                elem.children.push(childElem);
+            }
+        }
         return elem;
     }
     elementToString(elem, indent) {
@@ -124,17 +175,39 @@ export class ChromiumAccessibilityTree extends BaseAccessibilityTree {
         }
         return result;
     }
+    unescapeXml(value) {
+        return value
+            .replace(/&apos;/g, "'")
+            .replace(/&quot;/g, '"')
+            .replace(/&gt;/g, ">")
+            .replace(/&lt;/g, "<")
+            .replace(/&amp;/g, "&");
+    }
     elementById(rawId) {
         const rawXml = this.toStr();
         const element = this.findElementByRawId(rawXml, rawId);
         if (!element) {
             throw new Error(`No element with raw_id=${rawId} found`);
         }
+        // Handle Playwright nodes (cross-origin iframes)
+        if (element.attributes._playwright_node === "true") {
+            // Synthetic frame node
+            if (element.attributes._frame_url) {
+                return new AccessibilityElement(undefined, undefined, undefined, element.tag, undefined, undefined, undefined, undefined, undefined, undefined, undefined, this.frameMap.get(rawId), { _synthetic_frame: true, _frame_url: element.attributes._frame_url });
+            }
+            // Regular Playwright node with locator info
+            const locatorInfo = element.attributes
+                ._locator_info
+                ? JSON.parse(element.attributes._locator_info)
+                : {};
+            return new AccessibilityElement(undefined, undefined, undefined, element.tag, undefined, undefined, undefined, undefined, undefined, undefined, undefined, this.frameMap.get(rawId), locatorInfo);
+        }
+        // Existing CDP node logic
         const backendNodeIdStr = element.attributes.backendDOMNodeId;
         if (!backendNodeIdStr) {
             throw new Error(`Element with raw_id=${rawId} has no backendDOMNodeId attribute`);
         }
-        return new AccessibilityElement(undefined, undefined, undefined, element.tag, undefined, parseInt(backendNodeIdStr));
+        return new AccessibilityElement(undefined, undefined, undefined, element.tag, undefined, parseInt(backendNodeIdStr), undefined, undefined, undefined, undefined, undefined, this.frameMap.get(rawId), undefined, this.frameChainMap.get(rawId));
     }
     scopeToArea(rawId) {
         const rawXml = this.toStr();
@@ -143,7 +216,7 @@ export class ChromiumAccessibilityTree extends BaseAccessibilityTree {
             return this;
         }
         const scopedXml = this.elementToString(element, 0);
-        return ChromiumAccessibilityTree.fromXml(scopedXml);
+        return ChromiumAccessibilityTree.fromXml(scopedXml, this.frameMap);
     }
     findElementByRawId(xmlString, targetRawId) {
         // Parse the XML string to find the element
@@ -195,6 +268,10 @@ export class ChromiumAccessibilityTree extends BaseAccessibilityTree {
                 while ((attrMatch = attrRegex.exec(attrsString)) !== null) {
                     attributes[attrMatch[1]] = attrMatch[2];
                 }
+                // Unescape XML entities in attribute values
+                for (const key of Object.keys(attributes)) {
+                    attributes[key] = this.unescapeXml(attributes[key]);
+                }
                 const elem = {
                     tag: tagName,
                     attributes,

package/dist/accessibility/UIAutomator2AccessibilityTree.d.ts

@@ -5,6 +5,7 @@ export declare class UIAutomator2AccessibilityTree extends BaseAccessibilityTree
     private nextRawId;
     private raw;
     constructor(xmlString: string);
+    private static fromXml;
     toStr(): string;
     private addRawIds;
     elementById(rawId: number): AccessibilityElement;

package/dist/accessibility/UIAutomator2AccessibilityTree.js

@@ -12,6 +12,11 @@ export class UIAutomator2AccessibilityTree extends BaseAccessibilityTree {
         const cleanedXmlContent = cleanedLines.join("\n");
         this.xmlString = `<?xml version='1.0' encoding='UTF-8' standalone='yes' ?>\n<root>\n${cleanedXmlContent}\n</root>`;
     }
+    static fromXml(xmlString) {
+        const instance = new UIAutomator2AccessibilityTree("");
+        instance.raw = xmlString;
+        return instance;
+    }
     toStr() {
         if (this.raw !== null) {
             return this.raw;
@@ -53,7 +58,7 @@ export class UIAutomator2AccessibilityTree extends BaseAccessibilityTree {
             return this;
         }
         const scopedXml = this.elementToString(element, 0);
-        return new UIAutomator2AccessibilityTree(scopedXml);
+        return UIAutomator2AccessibilityTree.fromXml(scopedXml);
     }
     findElementByRawId(xmlString, targetRawId) {
         const elements = this.parseSimpleXml(xmlString);

package/dist/accessibility/XCUITestAccessibilityTree.d.ts

@@ -5,11 +5,13 @@ export declare class XCUITestAccessibilityTree extends BaseAccessibilityTree {
     private nextRawId;
     private raw;
     constructor(xmlString: string);
+    private static fromXml;
     toStr(): string;
     private addRawIds;
     elementById(rawId: number): AccessibilityElement;
     scopeToArea(rawId: number): XCUITestAccessibilityTree;
     private findElementByRawId;
     private elementToString;
+    private decodeHtmlEntities;
     private parseSimpleXml;
 }