playwright-core 1.55.0-alpha-2025-07-29 → 1.55.0-alpha-1753913825000

package/lib/server/screenshotter.js

@@ -166,20 +166,20 @@ class Screenshotter {
       progress.log("taking page screenshot");
       const viewportSize = await this._originalViewportSize(progress);
       await this._preparePageForScreenshot(progress, this._page.mainFrame(), options.style, options.caret !== "initial", options.animations === "disabled");
-      if (options.fullPage) {
-        const fullPageSize = await this._fullPageSize(progress);
-        let documentRect = { x: 0, y: 0, width: fullPageSize.width, height: fullPageSize.height };
-        const fitsViewport = fullPageSize.width <= viewportSize.width && fullPageSize.height <= viewportSize.height;
-        if (options.clip)
-          documentRect = trimClipToSize(options.clip, documentRect);
-        const buffer2 = await this._screenshot(progress, format, documentRect, void 0, fitsViewport, options);
+      try {
+        if (options.fullPage) {
+          const fullPageSize = await this._fullPageSize(progress);
+          let documentRect = { x: 0, y: 0, width: fullPageSize.width, height: fullPageSize.height };
+          const fitsViewport = fullPageSize.width <= viewportSize.width && fullPageSize.height <= viewportSize.height;
+          if (options.clip)
+            documentRect = trimClipToSize(options.clip, documentRect);
+          return await this._screenshot(progress, format, documentRect, void 0, fitsViewport, options);
+        }
+        const viewportRect = options.clip ? trimClipToSize(options.clip, viewportSize) : { x: 0, y: 0, ...viewportSize };
+        return await this._screenshot(progress, format, void 0, viewportRect, true, options);
+      } finally {
         await this._restorePageAfterScreenshot();
-        return buffer2;
       }
-      const viewportRect = options.clip ? trimClipToSize(options.clip, viewportSize) : { x: 0, y: 0, ...viewportSize };
-      const buffer = await this._screenshot(progress, format, void 0, viewportRect, true, options);
-      await this._restorePageAfterScreenshot();
-      return buffer;
     });
   }
   async screenshotElement(progress, handle, options) {
@@ -188,36 +188,42 @@ class Screenshotter {
       progress.log("taking element screenshot");
       const viewportSize = await this._originalViewportSize(progress);
       await this._preparePageForScreenshot(progress, handle._frame, options.style, options.caret !== "initial", options.animations === "disabled");
-      await handle._waitAndScrollIntoViewIfNeeded(
-        progress,
-        true
-        /* waitForVisible */
-      );
-      const boundingBox = await progress.race(handle.boundingBox());
-      (0, import_utils.assert)(boundingBox, "Node is either not visible or not an HTMLElement");
-      (0, import_utils.assert)(boundingBox.width !== 0, "Node has 0 width.");
-      (0, import_utils.assert)(boundingBox.height !== 0, "Node has 0 height.");
-      const fitsViewport = boundingBox.width <= viewportSize.width && boundingBox.height <= viewportSize.height;
-      const scrollOffset = await this._page.mainFrame().waitForFunctionValueInUtility(progress, () => ({ x: window.scrollX, y: window.scrollY }));
-      const documentRect = { ...boundingBox };
-      documentRect.x += scrollOffset.x;
-      documentRect.y += scrollOffset.y;
-      const buffer = await this._screenshot(progress, format, import_helper.helper.enclosingIntRect(documentRect), void 0, fitsViewport, options);
-      await this._restorePageAfterScreenshot();
-      return buffer;
+      try {
+        await handle._waitAndScrollIntoViewIfNeeded(
+          progress,
+          true
+          /* waitForVisible */
+        );
+        const boundingBox = await progress.race(handle.boundingBox());
+        (0, import_utils.assert)(boundingBox, "Node is either not visible or not an HTMLElement");
+        (0, import_utils.assert)(boundingBox.width !== 0, "Node has 0 width.");
+        (0, import_utils.assert)(boundingBox.height !== 0, "Node has 0 height.");
+        const fitsViewport = boundingBox.width <= viewportSize.width && boundingBox.height <= viewportSize.height;
+        const scrollOffset = await this._page.mainFrame().waitForFunctionValueInUtility(progress, () => ({ x: window.scrollX, y: window.scrollY }));
+        const documentRect = { ...boundingBox };
+        documentRect.x += scrollOffset.x;
+        documentRect.y += scrollOffset.y;
+        return await this._screenshot(progress, format, import_helper.helper.enclosingIntRect(documentRect), void 0, fitsViewport, options);
+      } finally {
+        await this._restorePageAfterScreenshot();
+      }
     });
   }
   async _preparePageForScreenshot(progress, frame, screenshotStyle, hideCaret, disableAnimations) {
     if (disableAnimations)
       progress.log("  disabled all CSS animations");
     const syncAnimations = this._page.delegate.shouldToggleStyleSheetToSyncAnimations();
-    progress.cleanupWhenAborted(() => this._restorePageAfterScreenshot());
     await progress.race(this._page.safeNonStallingEvaluateInAllFrames("(" + inPagePrepareForScreenshots.toString() + `)(${JSON.stringify(screenshotStyle)}, ${hideCaret}, ${disableAnimations}, ${syncAnimations})`, "utility"));
-    if (!process.env.PW_TEST_SCREENSHOT_NO_FONTS_READY) {
-      progress.log("waiting for fonts to load...");
-      await progress.race(frame.nonStallingEvaluateInExistingContext("document.fonts.ready", "utility").catch(() => {
-      }));
-      progress.log("fonts loaded");
+    try {
+      if (!process.env.PW_TEST_SCREENSHOT_NO_FONTS_READY) {
+        progress.log("waiting for fonts to load...");
+        await progress.race(frame.nonStallingEvaluateInExistingContext("document.fonts.ready", "utility").catch(() => {
+        }));
+        progress.log("fonts loaded");
+      }
+    } catch (error) {
+      await this._restorePageAfterScreenshot();
+      throw error;
     }
   }
   async _restorePageAfterScreenshot() {
@@ -227,39 +233,49 @@ class Screenshotter {
     if (!options.mask || !options.mask.length)
       return () => Promise.resolve();
     const framesToParsedSelectors = new import_multimap.MultiMap();
-    const cleanup = async () => {
-      await Promise.all([...framesToParsedSelectors.keys()].map(async (frame) => {
-        await frame.hideHighlight();
-      }));
-    };
-    progress.cleanupWhenAborted(cleanup);
     await progress.race(Promise.all((options.mask || []).map(async ({ frame, selector }) => {
       const pair = await frame.selectors.resolveFrameForSelector(selector);
       if (pair)
         framesToParsedSelectors.set(pair.frame, pair.info.parsed);
     })));
-    await progress.race(Promise.all([...framesToParsedSelectors.keys()].map(async (frame) => {
-      await frame.maskSelectors(framesToParsedSelectors.get(frame), options.maskColor || "#F0F");
-    })));
-    return cleanup;
+    const frames = [...framesToParsedSelectors.keys()];
+    const cleanup = async () => {
+      await Promise.all(frames.map((frame) => frame.hideHighlight()));
+    };
+    try {
+      const promises = frames.map((frame) => frame.maskSelectors(framesToParsedSelectors.get(frame), options.maskColor || "#F0F"));
+      await progress.race(Promise.all(promises));
+      return cleanup;
+    } catch (error) {
+      cleanup().catch(() => {
+      });
+      throw error;
+    }
   }
   async _screenshot(progress, format, documentRect, viewportRect, fitsViewport, options) {
     if (options.__testHookBeforeScreenshot)
       await progress.race(options.__testHookBeforeScreenshot());
     const shouldSetDefaultBackground = options.omitBackground && format === "png";
-    if (shouldSetDefaultBackground) {
-      progress.cleanupWhenAborted(() => this._page.delegate.setBackgroundColor());
+    if (shouldSetDefaultBackground)
       await progress.race(this._page.delegate.setBackgroundColor({ r: 0, g: 0, b: 0, a: 0 }));
-    }
     const cleanupHighlight = await this._maskElements(progress, options);
-    const quality = format === "jpeg" ? options.quality ?? 80 : void 0;
-    const buffer = await this._page.delegate.takeScreenshot(progress, format, documentRect, viewportRect, quality, fitsViewport, options.scale || "device");
-    await cleanupHighlight();
-    if (shouldSetDefaultBackground)
-      await progress.race(this._page.delegate.setBackgroundColor());
-    if (options.__testHookAfterScreenshot)
-      await progress.race(options.__testHookAfterScreenshot());
-    return buffer;
+    try {
+      const quality = format === "jpeg" ? options.quality ?? 80 : void 0;
+      const buffer = await this._page.delegate.takeScreenshot(progress, format, documentRect, viewportRect, quality, fitsViewport, options.scale || "device");
+      await cleanupHighlight();
+      if (shouldSetDefaultBackground)
+        await this._page.delegate.setBackgroundColor();
+      if (options.__testHookAfterScreenshot)
+        await progress.race(options.__testHookAfterScreenshot());
+      return buffer;
+    } catch (error) {
+      cleanupHighlight().catch(() => {
+      });
+      if (shouldSetDefaultBackground)
+        this._page.delegate.setBackgroundColor().catch(() => {
+        });
+      throw error;
+    }
   }
 }
 class TaskQueue {

package/lib/server/socksClientCertificatesInterceptor.js

@@ -44,6 +44,7 @@ var import_browserContext = require("./browserContext");
 var import_network = require("./utils/network");
 var import_debugLogger = require("./utils/debugLogger");
 var import_happyEyeballs = require("./utils/happyEyeballs");
+var import_utilsBundle = require("../utilsBundle");
 let dummyServerTlsOptions = void 0;
 function loadDummyServerCertsIfNeeded() {
   if (dummyServerTlsOptions)
@@ -84,7 +85,7 @@ class ALPNCache {
 }
 class SocksProxyConnection {
   constructor(socksProxy, uid, host, port) {
-    this.firstPackageReceived = false;
+    this._firstPackageReceived = false;
     this._closed = false;
     this.socksProxy = socksProxy;
     this.uid = uid;
@@ -92,55 +93,57 @@ class SocksProxyConnection {
     this.port = port;
     this._targetCloseEventListener = () => {
       this.socksProxy._socksProxy.sendSocketEnd({ uid: this.uid });
-      this.internalTLS?.destroy();
+      this._internalTLS?.destroy();
       this._dummyServer?.close();
     };
+    this._internal = new import_stream.default.Duplex({
+      read: () => {
+      },
+      write: (data, encoding, callback) => {
+        this.socksProxy._socksProxy.sendSocketData({ uid: this.uid, data });
+        callback();
+      }
+    });
   }
   async connect() {
-    if (this.socksProxy.proxyAgentFromOptions)
-      this.target = await this.socksProxy.proxyAgentFromOptions.callback(new import_events.EventEmitter(), { host: rewriteToLocalhostIfNeeded(this.host), port: this.port, secureEndpoint: false });
+    const proxyAgent = this.socksProxy.getProxyAgent(this.host, this.port);
+    if (proxyAgent)
+      this._target = await proxyAgent.callback(new import_events.EventEmitter(), { host: rewriteToLocalhostIfNeeded(this.host), port: this.port, secureEndpoint: false });
     else
-      this.target = await (0, import_happyEyeballs.createSocket)(rewriteToLocalhostIfNeeded(this.host), this.port);
-    this.target.once("close", this._targetCloseEventListener);
-    this.target.once("error", (error) => this.socksProxy._socksProxy.sendSocketError({ uid: this.uid, error: error.message }));
+      this._target = await (0, import_happyEyeballs.createSocket)(rewriteToLocalhostIfNeeded(this.host), this.port);
+    this._target.once("close", this._targetCloseEventListener);
+    this._target.once("error", (error) => this.socksProxy._socksProxy.sendSocketError({ uid: this.uid, error: error.message }));
     if (this._closed) {
-      this.target.destroy();
+      this._target.destroy();
       return;
     }
     this.socksProxy._socksProxy.socketConnected({
       uid: this.uid,
-      host: this.target.localAddress,
-      port: this.target.localPort
+      host: this._target.localAddress,
+      port: this._target.localPort
     });
   }
   onClose() {
-    this.target.destroy();
-    this.internalTLS?.destroy();
+    this._target.destroy();
+    this._internalTLS?.destroy();
     this._dummyServer?.close();
     this._closed = true;
   }
   onData(data) {
-    if (!this.firstPackageReceived) {
-      this.firstPackageReceived = true;
+    if (!this._firstPackageReceived) {
+      this._firstPackageReceived = true;
       if (data[0] === 22)
-        this._attachTLSListeners();
+        this._establishTlsTunnel(this._internal, data);
       else
-        this.target.on("data", (data2) => this.socksProxy._socksProxy.sendSocketData({ uid: this.uid, data: data2 }));
+        this._establishPlaintextTunnel(this._internal);
     }
-    if (this.internal)
-      this.internal.push(data);
-    else
-      this.target.write(data);
+    this._internal.push(data);
   }
-  _attachTLSListeners() {
-    this.internal = new import_stream.default.Duplex({
-      read: () => {
-      },
-      write: (data, encoding, callback) => {
-        this.socksProxy._socksProxy.sendSocketData({ uid: this.uid, data });
-        callback();
-      }
-    });
+  _establishPlaintextTunnel(internal) {
+    internal.pipe(this._target);
+    this._target.pipe(internal);
+  }
+  _establishTlsTunnel(internal, clientHello) {
     this.socksProxy.alpnCache.get(rewriteToLocalhostIfNeeded(this.host), this.port, (alpnProtocolChosenByServer) => {
       import_debugLogger.debugLogger.log("client-certificates", `Proxy->Target ${this.host}:${this.port} chooses ALPN ${alpnProtocolChosenByServer}`);
       if (this._closed)
@@ -149,9 +152,9 @@ class SocksProxyConnection {
         ...dummyServerTlsOptions,
         ALPNProtocols: alpnProtocolChosenByServer === "h2" ? ["h2", "http/1.1"] : ["http/1.1"]
       });
-      this._dummyServer.emit("connection", this.internal);
+      this._dummyServer.emit("connection", this._internal);
       this._dummyServer.once("secureConnection", (internalTLS) => {
-        this.internalTLS = internalTLS;
+        this._internalTLS = internalTLS;
         import_debugLogger.debugLogger.log("client-certificates", `Browser->Proxy ${this.host}:${this.port} chooses ALPN ${internalTLS.alpnProtocol}`);
         let targetTLS = void 0;
         const handleError = (error) => {
@@ -159,10 +162,10 @@ class SocksProxyConnection {
           const responseBody = (0, import_utils.escapeHTML)("Playwright client-certificate error: " + error.message).replaceAll("\n", " <br>");
           if (internalTLS?.alpnProtocol === "h2") {
             if ("performServerHandshake" in import_http2.default) {
-              this.target.removeListener("close", this._targetCloseEventListener);
+              this._target.removeListener("close", this._targetCloseEventListener);
               const session = import_http2.default.performServerHandshake(internalTLS);
               session.on("error", () => {
-                this.target.destroy();
+                this._target.destroy();
                 this._targetCloseEventListener();
               });
               session.once("stream", (stream2) => {
@@ -172,14 +175,14 @@ class SocksProxyConnection {
                 });
                 const cleanup = () => {
                   session.close();
-                  this.target.destroy();
+                  this._target.destroy();
                   this._targetCloseEventListener();
                 };
                 stream2.end(responseBody, cleanup);
                 stream2.once("error", cleanup);
               });
             } else {
-              this.target.destroy();
+              this._target.destroy();
             }
           } else {
             internalTLS.end([
@@ -189,7 +192,7 @@ class SocksProxyConnection {
               "",
               responseBody
             ].join("\r\n"));
-            this.target.destroy();
+            this._target.destroy();
           }
         };
         if (this._closed) {
@@ -197,7 +200,7 @@ class SocksProxyConnection {
           return;
         }
         targetTLS = import_tls.default.connect({
-          socket: this.target,
+          socket: this._target,
           host: this.host,
           port: this.port,
           rejectUnauthorized: !this.socksProxy.ignoreHTTPSErrors,
@@ -209,7 +212,7 @@ class SocksProxyConnection {
           internalTLS.pipe(targetTLS);
           targetTLS.pipe(internalTLS);
         });
-        internalTLS.once("error", () => this.target.destroy());
+        internalTLS.once("error", () => this._target.destroy());
         targetTLS.once("error", handleError);
       });
     });
@@ -222,7 +225,7 @@ class ClientCertificatesProxy {
     (0, import_browserContext.verifyClientCertificates)(contextOptions.clientCertificates);
     this.alpnCache = new ALPNCache();
     this.ignoreHTTPSErrors = contextOptions.ignoreHTTPSErrors;
-    this.proxyAgentFromOptions = (0, import_network.createProxyAgent)(contextOptions.proxy);
+    this._proxy = contextOptions.proxy;
     this._initSecureContexts(contextOptions.clientCertificates);
     this._socksProxy = new import_socksProxy.SocksProxy();
     this._socksProxy.setPattern("*");
@@ -236,7 +239,7 @@ class ClientCertificatesProxy {
         this._socksProxy.socketFailed({ uid: payload.uid, errorCode: error.code });
       }
     });
-    this._socksProxy.addListener(import_socksProxy.SocksProxy.Events.SocksData, async (payload) => {
+    this._socksProxy.addListener(import_socksProxy.SocksProxy.Events.SocksData, (payload) => {
       this._connections.get(payload.uid)?.onData(payload.data);
     });
     this._socksProxy.addListener(import_socksProxy.SocksProxy.Events.SocksClosed, (payload) => {
@@ -245,6 +248,14 @@ class ClientCertificatesProxy {
     });
     loadDummyServerCertsIfNeeded();
   }
+  getProxyAgent(host, port) {
+    const proxyFromOptions = (0, import_network.createProxyAgent)(this._proxy);
+    if (proxyFromOptions)
+      return proxyFromOptions;
+    const proxyFromEnv = (0, import_utilsBundle.getProxyForUrl)(`https://${host}:${port}`);
+    if (proxyFromEnv)
+      return (0, import_network.createProxyAgent)({ server: proxyFromEnv });
+  }
   _initSecureContexts(clientCertificates) {
     const origin2certs = /* @__PURE__ */ new Map();
     for (const cert of clientCertificates || []) {
@@ -262,10 +273,15 @@ class ClientCertificatesProxy {
       }
     }
   }
-  static async create(contextOptions) {
+  static async create(progress, contextOptions) {
     const proxy = new ClientCertificatesProxy(contextOptions);
-    await proxy._socksProxy.listen(0, "127.0.0.1");
-    return proxy;
+    try {
+      await progress.race(proxy._socksProxy.listen(0, "127.0.0.1"));
+      return proxy;
+    } catch (error) {
+      await proxy.close();
+      throw error;
+    }
   }
   proxySettings() {
     return { server: `socks5://127.0.0.1:${this._socksProxy.port()}` };

package/lib/server/transport.js

@@ -97,11 +97,10 @@ class WebSocketTransport {
     const logUrl = stripQueryParams(url);
     progress?.log(`<ws connecting> ${logUrl}`);
     const transport = new WebSocketTransport(progress, url, logUrl, { ...options, followRedirects: !!options.followRedirects && hadRedirects });
-    progress?.cleanupWhenAborted(() => transport.closeAndWait());
     const resultPromise = new Promise((fulfill, reject) => {
       transport._ws.on("open", async () => {
         progress?.log(`<ws connected> ${logUrl}`);
-        fulfill({ transport });
+        fulfill({});
       });
       transport._ws.on("error", (event) => {
         progress?.log(`<ws connect error> ${logUrl} ${event.message}`);
@@ -130,20 +129,25 @@ ${Buffer.concat(chunks)}` : errorPrefix;
         });
       });
     });
-    const result = progress ? await progress.race(resultPromise) : await resultPromise;
-    if (result.redirect) {
-      const newHeaders = Object.fromEntries(Object.entries(options.headers || {}).filter(([name]) => {
-        return !name.includes("access-key") && name.toLowerCase() !== "authorization";
-      }));
-      return WebSocketTransport._connect(
-        progress,
-        result.redirect.headers.location,
-        { ...options, headers: newHeaders },
-        true
-        /* hadRedirects */
-      );
+    try {
+      const result = progress ? await progress.race(resultPromise) : await resultPromise;
+      if (result.redirect) {
+        const newHeaders = Object.fromEntries(Object.entries(options.headers || {}).filter(([name]) => {
+          return !name.includes("access-key") && name.toLowerCase() !== "authorization";
+        }));
+        return WebSocketTransport._connect(
+          progress,
+          result.redirect.headers.location,
+          { ...options, headers: newHeaders },
+          true
+          /* hadRedirects */
+        );
+      }
+      return transport;
+    } catch (error) {
+      await transport.closeAndWait();
+      throw error;
     }
-    return transport;
   }
   send(message) {
     this._ws.send(JSON.stringify(message));

package/lib/server/utils/network.js

@@ -44,6 +44,7 @@ var import_https = __toESM(require("https"));
 var import_url = __toESM(require("url"));
 var import_utilsBundle = require("../../utilsBundle");
 var import_happyEyeballs = require("./happyEyeballs");
+var import_manualPromise = require("../../utils/isomorphic/manualPromise");
 const NET_DEFAULT_TIMEOUT = 3e4;
 function httpRequest(params, onResponse, onError) {
   const parsedUrl = import_url.default.parse(params.url);
@@ -90,26 +91,36 @@ function httpRequest(params, onResponse, onError) {
       request.abort();
     });
   }
-  cancelRequest = (e) => request.destroy(e);
+  cancelRequest = (e) => {
+    try {
+      request.destroy(e);
+    } catch {
+    }
+  };
   request.end(params.data);
   return { cancel: (e) => cancelRequest(e) };
 }
-function fetchData(progress, params, onError) {
-  const promise = new Promise((resolve, reject) => {
-    const { cancel } = httpRequest(params, async (response) => {
-      if (response.statusCode !== 200) {
-        const error = onError ? await onError(params, response) : new Error(`fetch failed: server returned code ${response.statusCode}. URL: ${params.url}`);
-        reject(error);
-        return;
-      }
-      let body = "";
-      response.on("data", (chunk) => body += chunk);
-      response.on("error", (error) => reject(error));
-      response.on("end", () => resolve(body));
-    }, reject);
-    progress?.cleanupWhenAborted(cancel);
-  });
-  return progress ? progress.race(promise) : promise;
+async function fetchData(progress, params, onError) {
+  const promise = new import_manualPromise.ManualPromise();
+  const { cancel } = httpRequest(params, async (response) => {
+    if (response.statusCode !== 200) {
+      const error = onError ? await onError(params, response) : new Error(`fetch failed: server returned code ${response.statusCode}. URL: ${params.url}`);
+      promise.reject(error);
+      return;
+    }
+    let body = "";
+    response.on("data", (chunk) => body += chunk);
+    response.on("error", (error) => promise.reject(error));
+    response.on("end", () => promise.resolve(body));
+  }, (error) => promise.reject(error));
+  if (!progress)
+    return promise;
+  try {
+    return await progress.race(promise);
+  } catch (error) {
+    cancel(error);
+    throw error;
+  }
 }
 function shouldBypassProxy(url2, bypass) {
   if (!bypass)

package/lib/server/utils/processLauncher.js

@@ -132,7 +132,10 @@ async function launchProcess(options) {
     spawnedProcess.once("error", (error) => {
       failed(new Error("Failed to launch: " + error));
     });
-    return failedPromise.then((e) => Promise.reject(e));
+    return failedPromise.then(async (error) => {
+      await cleanup();
+      throw error;
+    });
   }
   options.log(`<launched> pid=${spawnedProcess.pid}`);
   const stdout = readline.createInterface({ input: spawnedProcess.stdout });

package/lib/utils/isomorphic/ariaSnapshot.js

@@ -20,13 +20,14 @@ var ariaSnapshot_exports = {};
 __export(ariaSnapshot_exports, {
   KeyParser: () => KeyParser,
   ParserError: () => ParserError,
+  findNewElementRef: () => findNewElementRef,
   parseAriaSnapshot: () => parseAriaSnapshot,
   parseAriaSnapshotUnsafe: () => parseAriaSnapshotUnsafe,
   valueOrRegex: () => valueOrRegex
 });
 module.exports = __toCommonJS(ariaSnapshot_exports);
-function parseAriaSnapshotUnsafe(yaml, text) {
-  const result = parseAriaSnapshot(yaml, text);
+function parseAriaSnapshotUnsafe(yaml, text, options = {}) {
+  const result = parseAriaSnapshot(yaml, text, options);
   if (result.errors.length)
     throw new Error(result.errors[0].message);
   return result.fragment;
@@ -187,7 +188,7 @@ function valueOrRegex(value) {
 class KeyParser {
   static parse(text, options, errors) {
     try {
-      return new KeyParser(text.value)._parse();
+      return new KeyParser(text.value, options)._parse();
     } catch (e) {
       if (e instanceof ParserError) {
         const message = options.prettyErrors === false ? e.message : e.message + ":\n\n" + text.value + "\n" + " ".repeat(e.pos) + "^\n";
@@ -200,10 +201,11 @@ class KeyParser {
       throw e;
     }
   }
-  constructor(input) {
+  constructor(input, options) {
     this._input = input;
     this._pos = 0;
     this._length = input.length;
+    this._options = options;
   }
   _peek() {
     return this._input[this._pos] || "";
@@ -331,6 +333,10 @@ class KeyParser {
     return result;
   }
   _applyAttribute(node, key, value, errorPos) {
+    if (this._options.allowRef && key === "ref") {
+      node.ref = value;
+      return;
+    }
     if (key === "checked") {
       this._assert(value === "true" || value === "false" || value === "mixed", 'Value of "checked" attribute must be a boolean or "mixed"', errorPos);
       node.checked = value === "true" ? true : value === "false" ? false : "mixed";
@@ -366,6 +372,8 @@ class KeyParser {
       node.selected = value === "true";
       return;
     }
+    if (this._options.allowUnknownAttributes)
+      return;
     this._assert(false, `Unsupported attribute [${key}]`, errorPos);
   }
   _assert(value, message, valuePos) {
@@ -379,10 +387,56 @@ class ParserError extends Error {
     this.pos = pos;
   }
 }
+function findNewElementRef(yaml, fromSnapshot, toSnapshot) {
+  function fillMap(root, map, position) {
+    let size = 1;
+    let childPosition = position + size;
+    for (const child of root.children || []) {
+      if (child.kind === "role") {
+        size += fillMap(child, map, childPosition);
+        childPosition += size;
+      } else {
+        size++;
+        childPosition++;
+      }
+    }
+    if (!["none", "presentation", "fragment", "iframe", "generic"].includes(root.role) && typeof root.name === "string" && root.name) {
+      let byRole = map.get(root.role);
+      if (!byRole) {
+        byRole = /* @__PURE__ */ new Map();
+        map.set(root.role, byRole);
+      }
+      const existing = byRole.get(root.name);
+      const sizeAndPosition = size * 100 - position;
+      if (!existing || existing.sizeAndPosition < sizeAndPosition)
+        byRole.set(root.name, { node: root, sizeAndPosition });
+    }
+    return size;
+  }
+  const fromMap = /* @__PURE__ */ new Map();
+  const from = parseAriaSnapshotUnsafe(yaml, fromSnapshot, { allowRef: true, allowUnknownAttributes: true });
+  if (from.kind === "role")
+    fillMap(from, fromMap, 0);
+  const toMap = /* @__PURE__ */ new Map();
+  const to = parseAriaSnapshotUnsafe(yaml, toSnapshot, { allowRef: true, allowUnknownAttributes: true });
+  if (to.kind === "role")
+    fillMap(to, toMap, 0);
+  const result = [];
+  for (const [role, byRole] of toMap) {
+    for (const [name, byName] of byRole) {
+      const inFrom = fromMap.get(role)?.get(name);
+      if (!inFrom)
+        result.push(byName);
+    }
+  }
+  result.sort((a, b) => b.sizeAndPosition - a.sizeAndPosition);
+  return result.find((r) => r.node.ref)?.node.ref;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   KeyParser,
   ParserError,
+  findNewElementRef,
   parseAriaSnapshot,
   parseAriaSnapshotUnsafe,
   valueOrRegex