chore: roll to 1.59.0-alpha-1774622285000

- Add Overlay API (page.overlay()) with show/chapter/setVisible
- Add Debugger.requestPause(), change pausedDetails() to return single PausedDetails
- Fix Video.start() to handle path option locally and pass annotate/size to protocol
- Fix Response.httpVersion() to call protocol method
- Fix ResponseImpl to set request.existingResponse in constructor
- Fix TracingImpl to track additionalSources from group() locations
- Fix DialogImpl.dismiss() to swallow TargetClosedErrors for beforeunload dialogs
- Fix HarRouter to merge set-cookie headers
- Fix ConsoleMessagesFilter.SINCE_NAVIGATION serialization to kebab-case
- Fix Locator.normalize() to use resolveSelector protocol message

Author: yury-s

playwright/src/main/java/com/microsoft/playwright/Debugger.java

@@ -35,25 +35,25 @@ public interface Debugger {
   void offPausedStateChanged(Runnable handler);
 
   /**
-   * Returns details about the currently paused calls. Returns an empty array if the debugger is not paused.
+   * Returns details about the currently paused call. Returns {@code null} if the debugger is not paused.
    *
    * @since v1.59
    */
-  List<PausedDetails> pausedDetails();
+  PausedDetails pausedDetails();
   /**
    * Configures the debugger to pause before the next action is executed.
    *
    * <p> Throws if the debugger is already paused. Use {@link com.microsoft.playwright.Debugger#next Debugger.next()} or {@link
    * com.microsoft.playwright.Debugger#runTo Debugger.runTo()} to step while paused.
    *
    * <p> Note that {@link com.microsoft.playwright.Page#pause Page.pause()} is equivalent to a "debugger" statement — it pauses
-   * execution at the call site immediately. On the contrary, {@link com.microsoft.playwright.Debugger#pause
-   * Debugger.pause()} is equivalent to "pause on next statement" — it configures the debugger to pause before the next
-   * action is executed.
+   * execution at the call site immediately. On the contrary, {@link com.microsoft.playwright.Debugger#requestPause
+   * Debugger.requestPause()} is equivalent to "pause on next statement" — it configures the debugger to pause before the
+   * next action is executed.
    *
    * @since v1.59
    */
-  void pause();
+  void requestPause();
   /**
    * Resumes script execution. Throws if the debugger is not paused.
    *

playwright/src/main/java/com/microsoft/playwright/Locator.java

@@ -35,8 +35,8 @@ class AriaSnapshotOptions {
      */
     public Integer depth;
     /**
-     * When set to {@code "ai"}, returns a snapshot optimized for AI consumption with element references. Defaults to {@code
-     * "default"}.
+     * When set to {@code "ai"}, returns a snapshot optimized for AI consumption. Defaults to {@code "default"}. See details
+     * for more information.
      */
     public AriaSnapshotMode mode;
     /**
@@ -55,8 +55,8 @@ public AriaSnapshotOptions setDepth(int depth) {
       return this;
     }
     /**
-     * When set to {@code "ai"}, returns a snapshot optimized for AI consumption with element references. Defaults to {@code
-     * "default"}.
+     * When set to {@code "ai"}, returns a snapshot optimized for AI consumption. Defaults to {@code "default"}. See details
+     * for more information.
      */
     public AriaSnapshotOptions setMode(AriaSnapshotMode mode) {
       this.mode = mode;
@@ -2322,6 +2322,12 @@ public WaitForOptions setTimeout(double timeout) {
    *
    * <p> Below is the HTML markup and the respective ARIA snapshot:
    *
+   * <p> An AI-optimized snapshot, controlled by {@code mode}, is different from a default snapshot:
+   * <ol>
+   * <li> Includes element references {@code [ref=e2]}. 2. Does not wait for an element matching the locator, and throws when no
+   * elements match. 3. Includes snapshots of {@code <iframe>}s inside the target.</li>
+   * </ol>
+   *
    * @since v1.49
    */
   default String ariaSnapshot() {
@@ -2353,6 +2359,12 @@ default String ariaSnapshot() {
    *
    * <p> Below is the HTML markup and the respective ARIA snapshot:
    *
+   * <p> An AI-optimized snapshot, controlled by {@code mode}, is different from a default snapshot:
+   * <ol>
+   * <li> Includes element references {@code [ref=e2]}. 2. Does not wait for an element matching the locator, and throws when no
+   * elements match. 3. Includes snapshots of {@code <iframe>}s inside the target.</li>
+   * </ol>
+   *
    * @since v1.49
    */
   String ariaSnapshot(AriaSnapshotOptions options);

playwright/src/main/java/com/microsoft/playwright/Overlay.java

@@ -0,0 +1,109 @@
+/*
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.microsoft.playwright;
+
+
+/**
+ * Interface for managing page overlays that display persistent visual indicators on top of the page.
+ */
+public interface Overlay {
+  class ShowOptions {
+    /**
+     * Duration in milliseconds after which the overlay is automatically removed. Overlay stays until dismissed if not
+     * provided.
+     */
+    public Double duration;
+
+    /**
+     * Duration in milliseconds after which the overlay is automatically removed. Overlay stays until dismissed if not
+     * provided.
+     */
+    public ShowOptions setDuration(double duration) {
+      this.duration = duration;
+      return this;
+    }
+  }
+  class ChapterOptions {
+    /**
+     * Optional description text displayed below the title.
+     */
+    public String description;
+    /**
+     * Duration in milliseconds after which the overlay is automatically removed. Defaults to {@code 2000}.
+     */
+    public Double duration;
+
+    /**
+     * Optional description text displayed below the title.
+     */
+    public ChapterOptions setDescription(String description) {
+      this.description = description;
+      return this;
+    }
+    /**
+     * Duration in milliseconds after which the overlay is automatically removed. Defaults to {@code 2000}.
+     */
+    public ChapterOptions setDuration(double duration) {
+      this.duration = duration;
+      return this;
+    }
+  }
+  /**
+   * Adds an overlay with the given HTML content. The overlay is displayed on top of the page until removed. Returns a
+   * disposable that removes the overlay when disposed.
+   *
+   * @param html HTML content for the overlay.
+   * @since v1.59
+   */
+  default AutoCloseable show(String html) {
+    return show(html, null);
+  }
+  /**
+   * Adds an overlay with the given HTML content. The overlay is displayed on top of the page until removed. Returns a
+   * disposable that removes the overlay when disposed.
+   *
+   * @param html HTML content for the overlay.
+   * @since v1.59
+   */
+  AutoCloseable show(String html, ShowOptions options);
+  /**
+   * Shows a chapter overlay with a title and optional description, centered on the page with a blurred backdrop. Useful for
+   * narrating video recordings. The overlay is removed after the specified duration, or 2000ms.
+   *
+   * @param title Title text displayed prominently in the overlay.
+   * @since v1.59
+   */
+  default void chapter(String title) {
+    chapter(title, null);
+  }
+  /**
+   * Shows a chapter overlay with a title and optional description, centered on the page with a blurred backdrop. Useful for
+   * narrating video recordings. The overlay is removed after the specified duration, or 2000ms.
+   *
+   * @param title Title text displayed prominently in the overlay.
+   * @since v1.59
+   */
+  void chapter(String title, ChapterOptions options);
+  /**
+   * Sets visibility of all overlays without removing them.
+   *
+   * @param visible Whether overlays should be visible.
+   * @since v1.59
+   */
+  void setVisible(boolean visible);
+}
+

playwright/src/main/java/com/microsoft/playwright/Page.java

@@ -2986,8 +2986,8 @@ class AriaSnapshotOptions {
      */
     public Integer depth;
     /**
-     * When set to {@code "ai"}, returns a snapshot optimized for AI consumption with element references. Defaults to {@code
-     * "default"}.
+     * When set to {@code "ai"}, returns a snapshot optimized for AI consumption: including element references like {@code
+     * [ref=e2]} and snapshots of {@code <iframe>}s. Defaults to {@code "default"}.
      */
     public AriaSnapshotMode mode;
     /**
@@ -3006,8 +3006,8 @@ public AriaSnapshotOptions setDepth(int depth) {
       return this;
     }
     /**
-     * When set to {@code "ai"}, returns a snapshot optimized for AI consumption with element references. Defaults to {@code
-     * "default"}.
+     * When set to {@code "ai"}, returns a snapshot optimized for AI consumption: including element references like {@code
+     * [ref=e2]} and snapshots of {@code <iframe>}s. Defaults to {@code "default"}.
      */
     public AriaSnapshotOptions setMode(AriaSnapshotMode mode) {
       this.mode = mode;
@@ -5880,6 +5880,12 @@ default Locator locator(String selector) {
    * @since v1.8
    */
   Mouse mouse();
+  /**
+   *
+   *
+   * @since v1.59
+   */
+  Overlay overlay();
   /**
    * Adds one-off {@code Dialog} handler. The handler will be removed immediately after next {@code Dialog} is created.
    * <pre>{@code

playwright/src/main/java/com/microsoft/playwright/impl/DebuggerImpl.java

@@ -16,21 +16,19 @@
 
 package com.microsoft.playwright.impl;
 
-import com.google.gson.JsonArray;
 import com.google.gson.JsonObject;
 import com.microsoft.playwright.Debugger;
 import com.microsoft.playwright.options.Location;
 import com.microsoft.playwright.options.PausedDetails;
 
 import java.util.ArrayList;
-import java.util.Arrays;
 import java.util.List;
 
 import static com.microsoft.playwright.impl.Serialization.gson;
 
 class DebuggerImpl extends ChannelOwner implements Debugger {
   private final List<Runnable> pausedStateChangedHandlers = new ArrayList<>();
-  private List<PausedDetails> pausedDetails = new ArrayList<>();
+  private PausedDetails pausedDetails;
 
   DebuggerImpl(ChannelOwner parent, String type, String guid, JsonObject initializer) {
     super(parent, type, guid, initializer);
@@ -39,8 +37,11 @@ class DebuggerImpl extends ChannelOwner implements Debugger {
   @Override
   protected void handleEvent(String event, JsonObject params) {
     if ("pausedStateChanged".equals(event)) {
-      JsonArray details = params.getAsJsonArray("pausedDetails");
-      pausedDetails = Arrays.asList(gson().fromJson(details, PausedDetails[].class));
+      if (params.has("pausedDetails") && !params.get("pausedDetails").isJsonNull()) {
+        pausedDetails = gson().fromJson(params.get("pausedDetails"), PausedDetails.class);
+      } else {
+        pausedDetails = null;
+      }
       for (Runnable handler : new ArrayList<>(pausedStateChangedHandlers)) {
         handler.run();
       }
@@ -58,13 +59,13 @@ public void offPausedStateChanged(Runnable handler) {
   }
 
   @Override
-  public List<PausedDetails> pausedDetails() {
+  public PausedDetails pausedDetails() {
     return pausedDetails;
   }
 
   @Override
-  public void pause() {
-    sendMessage("pause", new JsonObject(), NO_TIMEOUT);
+  public void requestPause() {
+    sendMessage("requestPause", new JsonObject(), NO_TIMEOUT);
   }
 
   @Override

playwright/src/main/java/com/microsoft/playwright/impl/DialogImpl.java

@@ -43,7 +43,11 @@ public void accept(String promptText) {
 
   @Override
   public void dismiss() {
-    sendMessage("dismiss");
+    try {
+      sendMessage("dismiss");
+    } catch (TargetClosedError e) {
+      // Swallow TargetClosedErrors for beforeunload dialogs.
+    }
   }
 
   @Override

playwright/src/main/java/com/microsoft/playwright/impl/HARRouter.java

@@ -16,6 +16,8 @@
 
 package com.microsoft.playwright.impl;
 
+import com.google.gson.JsonArray;
+import com.google.gson.JsonElement;
 import com.google.gson.JsonObject;
 import com.microsoft.playwright.PlaywrightException;
 import com.microsoft.playwright.Request;
@@ -82,7 +84,7 @@ void handle(Route route) {
       if (status == -1) {
         return;
       }
-      Map<String, String> headers = fromNameValues(response.getAsJsonArray("headers"));
+      Map<String, String> headers = mergeSetCookieHeaders(response.getAsJsonArray("headers"));
       byte[] buffer = Base64.getDecoder().decode(response.get("body").getAsString());
       route.fulfill(new Route.FulfillOptions()
         .setStatus(status)
@@ -105,6 +107,25 @@ void handle(Route route) {
     route.abort();
   }
 
+  private static Map<String, String> mergeSetCookieHeaders(JsonArray headersArray) {
+    Map<String, String> result = new java.util.LinkedHashMap<>();
+    for (JsonElement element : headersArray) {
+      JsonObject pair = element.getAsJsonObject();
+      String name = pair.get("name").getAsString();
+      String value = pair.get("value").getAsString();
+      if ("set-cookie".equalsIgnoreCase(name)) {
+        if (!result.containsKey("set-cookie")) {
+          result.put("set-cookie", value);
+        } else {
+          result.put("set-cookie", result.get("set-cookie") + "\n" + value);
+        }
+      } else {
+        result.put(name, value);
+      }
+    }
+    return result;
+  }
+
   void dispose() {
     JsonObject params = new JsonObject();
     params.addProperty("harId", harId);

playwright/src/main/java/com/microsoft/playwright/impl/LocalUtils.java

@@ -34,13 +34,20 @@ JsonArray deviceDescriptors() {
     return initializer.getAsJsonArray("deviceDescriptors");
   }
 
-  void zip(Path zipFile, JsonArray entries, String stacksId, boolean appendMode, boolean includeSources) {
+  void zip(Path zipFile, JsonArray entries, String stacksId, boolean appendMode, boolean includeSources, List<String> additionalSources) {
     JsonObject params = new JsonObject();
     params.addProperty("zipFile", zipFile.toString());
     params.add("entries", entries);
     params.addProperty("mode", appendMode ? "append" : "write");
     params.addProperty("stacksId", stacksId);
     params.addProperty("includeSources", includeSources);
+    if (!additionalSources.isEmpty()) {
+      JsonArray sourcesArray = new JsonArray();
+      for (String source : additionalSources) {
+        sourcesArray.add(source);
+      }
+      params.add("additionalSources", sourcesArray);
+    }
     sendMessage("zip", params, NO_TIMEOUT);
   }
 

playwright/src/main/java/com/microsoft/playwright/impl/LocatorImpl.java

@@ -112,8 +112,8 @@ public List<String> allTextContents() {
   public Locator normalize() {
     JsonObject params = new JsonObject();
     params.addProperty("selector", selector);
-    JsonObject result = frame.sendMessage("normalizeLocator", params, ChannelOwner.NO_TIMEOUT).getAsJsonObject();
-    return new LocatorImpl(frame, result.get("selector").getAsString(), null);
+    JsonObject result = frame.sendMessage("resolveSelector", params, ChannelOwner.NO_TIMEOUT).getAsJsonObject();
+    return new LocatorImpl(frame, result.get("resolvedSelector").getAsString(), null);
   }
 
   @Override