Add transport layer that will be used by generated BiDi Modules

java/src/org/openqa/selenium/bidi/BiDi.java

@@ -167,4 +167,8 @@ public void clearListeners() {
   public BiDiSessionStatus getBidiSessionStatus() {
     return send(new Command<>("session.status", emptyMap(), BiDiSessionStatus.class));
   }
+
+  public Handle asHandle() {
+    return new Handle(this);
+  }
 }

java/src/org/openqa/selenium/bidi/BiDiProvider.java

@@ -70,6 +70,11 @@ public Optional<BiDi> maybeGetBiDi() {
       public BiDi getBiDi() {
         return biDi.get();
       }
+
+      @Override
+      public Handle getHandle() {
+        return biDi.get().asHandle();
+      }
     };
   }
 

java/src/org/openqa/selenium/bidi/Handle.java

@@ -0,0 +1,51 @@
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The SFC licenses this file
+// to you 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 org.openqa.selenium.bidi;
+
+import java.util.function.Consumer;
+import org.openqa.selenium.Beta;
+
+/**
+ * An opaque handle to the active BiDi connection, used by {@link Module} subclasses to send
+ * commands and subscribe to events.
+ *
+ * <p>Constructor and all methods are package-private: external callers that hold a {@code Handle}
+ * reference cannot invoke it, only pass it to module constructors inside this package. Create an
+ * instance via {@link BiDi#asHandle()}.
+ */
+@Beta
+public class Handle {
+
+  private final BiDi bidi;
+
+  Handle(BiDi bidi) {
+    this.bidi = bidi;
+  }
+
+  <X> X send(Command<X> command) {
+    return bidi.send(command);
+  }
+
+  <X> String subscribe(Event<X> event, Consumer<X> handler) {
+    return bidi.addListener(event, handler);
+  }
+
+  void unsubscribe(String subscriptionId) {
+    bidi.removeListener(subscriptionId);
+  }
+}

java/src/org/openqa/selenium/bidi/HasBiDi.java

@@ -38,4 +38,6 @@ default BiDi getBiDi() {
    */
   @Deprecated(since = "4.46", forRemoval = true)
   Optional<BiDi> maybeGetBiDi();
+
+  Handle getHandle();
 }

java/src/org/openqa/selenium/bidi/Module.java

@@ -0,0 +1,55 @@
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The SFC licenses this file
+// to you 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 org.openqa.selenium.bidi;
+
+import java.util.function.Consumer;
+import org.openqa.selenium.Beta;
+import org.openqa.selenium.WebDriver;
+import org.openqa.selenium.internal.Require;
+
+/**
+ * Base class for generated BiDi module classes.
+ *
+ * <p>Subclasses delegate all wire operations through the driver's shared {@link Handle} — no new
+ * WebSocket connection is opened.
+ */
+@Beta
+public abstract class Module {
+
+  private final Handle handle;
+
+  protected Module(WebDriver driver) {
+    Require.nonNull("WebDriver", driver);
+    if (!(driver instanceof HasBiDi)) {
+      throw new BiDiException("WebDriver does not support BiDi protocol");
+    }
+    this.handle = ((HasBiDi) driver).getHandle();
+  }
+
+  protected final <X> X send(Command<X> command) {
+    return handle.send(command);
+  }
+
+  protected final <X> String subscribe(Event<X> event, Consumer<X> handler) {
+    return handle.subscribe(event, handler);
+  }
+
+  protected final void unsubscribe(String subscriptionId) {
+    handle.unsubscribe(subscriptionId);
+  }
+}

java/src/org/openqa/selenium/remote/RemoteWebDriver.java

@@ -80,7 +80,9 @@
 import org.openqa.selenium.WebElement;
 import org.openqa.selenium.WindowType;
 import org.openqa.selenium.bidi.BiDi;
+import org.openqa.selenium.bidi.BiDiException;
 import org.openqa.selenium.bidi.Connection;
+import org.openqa.selenium.bidi.Handle;
 import org.openqa.selenium.bidi.HasBiDi;
 import org.openqa.selenium.devtools.DevTools;
 import org.openqa.selenium.devtools.HasDevTools;
@@ -475,6 +477,22 @@ public Optional<BiDi> maybeGetBiDi() {
     return biDi;
   }
 
+  // Calls maybeGetBiDi() rather than reading the private field directly so that subclasses
+  // that override maybeGetBiDi() (e.g. AppiumDriver) are not broken before they migrate to
+  // overriding getHandle(). Remove the @SuppressWarnings and switch to the field once
+  // maybeGetBiDi() is deleted.
+  @SuppressWarnings("deprecation")
+  @Override
+  public Handle getHandle() {
+    return maybeGetBiDi()
+        .map(BiDi::asHandle)
+        .orElseThrow(
+            () ->
+                new BiDiException(
+                    "Check if this browser version supports BiDi and if the"
+                        + " 'webSocketUrl: true' capability is set."));
+  }
+
   // Misc
 
   @Override