fix(geolocation): replace setClient with Lookup-based factory SPI (#24259)

## Summary
- Promotes `GeolocationClient` to a public SPI and adds a
`GeolocationClientFactory` extension point resolved through
`com.vaadin.flow.di.Lookup`.
- `Geolocation` queries the factory at construction time and falls back
to the built-in browser-backed client when none is registered.
- `setClient` is retained as a package-private in-JAR seam for
flow-server's own tests; external test drivers and native bridges
register a factory via `META-INF/services`.

## Why
Follow-up to #24211. The `setClient` seam (originally package-private)
breaks under split-classloader topologies (Quarkus, OSGi, JPMS): the JVM
scopes runtime packages by classloader, so a class in `flow-server.jar`
and one in an external JAR with the same package name end up in
**different runtime packages** when their JARs load through different
classloaders. Cross-JAR package-private access then throws
`IllegalAccessError` at class definition time. Reproduced locally and in
CI on browserless-test PR #51:

```
java.lang.IllegalAccessError: class com.vaadin.flow.component.geolocation.BrowserlessGeolocationClient
  cannot access its superinterface com.vaadin.flow.component.geolocation.GeolocationClient
  (BrowserlessGeolocationClient is in unnamed module of loader QuarkusClassLoader @34eb5d01;
   GeolocationClient            is in unnamed module of loader QuarkusClassLoader @272778ae)
```

`Lookup` is classloader-aware and explicitly designed for this kind of
pluggable SPI — it's the canonical Flow pattern (`InstantiatorFactory`,
`RoutePathProvider`, `ResourceProvider`, `StaticFileHandlerFactory`,
`BrowserLiveReloadAccessor`).

## Changes
- `GeolocationClient` → `public interface` with proper SPI Javadoc (no
longer "framework internal").
- `GeolocationClientFactory` (new) → `public interface`, resolved via
`Lookup`; documents the use cases (in-memory test drivers; native
bridges in Cordova/Electron/Capacitor shells).
- `Geolocation` constructor calls `resolveClient(ui)` → looks up a
factory via `VaadinService.getCurrent()` →
`Lookup.lookup(GeolocationClientFactory.class)`; falls back to `new
BrowserGeolocationClient(ui, seed)` when no factory is registered.
- `setClient` stays package-private — flow-server's own tests use it;
external code goes through `Lookup`.
- `BrowserGeolocationClient` Javadoc updated to mention it's the
no-factory default.
- `GeolocationClientSeamTest` now exercises both the public
Lookup-factory path and the in-package `setClient` seam.

No `META-INF/services` file is shipped from flow-server: production has
no factory and uses the fallback. Implementations live in external JARs
(e.g. browserless-test-shared).

## Test plan
- [x] `mvn test -pl :flow-server -Dtest='*Geolocation*'` — 38/38 pass
locally.
- [x] No `@SuppressWarnings("NullAway")` introduced; constructor assigns
the `client` field directly.
- [x] Local end-to-end verification with browserless-test patched to
register a factory: Quarkus suite that previously threw
`IllegalAccessError` now passes (junit6 21/21, quarkus 11/11, including
`QuarkusBrowserlessBaseClassTest` and `QuarkusUnitSecurityTest` that
were failing).
- [ ] Reviewer to confirm SPI shape (factory vs. direct service) is
acceptable for Flow's public API surface.

cc @mcollovati

Author: heruan

flow-server/src/main/java/com/vaadin/flow/component/geolocation/BrowserGeolocationClient.java

@@ -36,9 +36,9 @@
 /**
  * {@link GeolocationClient} implementation backed by the real browser
  * Geolocation API via {@code window.Vaadin.Flow.geolocation} and DOM events.
- * This is the default implementation injected at facade construction time;
- * external browserless test drivers replace it via
- * {@link Geolocation#setClient(GeolocationClient)}.
+ * This is the default implementation used when no
+ * {@link GeolocationClientFactory} is registered through
+ * {@link com.vaadin.flow.di.Lookup Lookup}.
  * <p>
  * <b>Framework internal.</b> Application code does not reference this class
  * directly.

flow-server/src/main/java/com/vaadin/flow/component/geolocation/Geolocation.java

@@ -23,7 +23,10 @@
 
 import com.vaadin.flow.component.Component;
 import com.vaadin.flow.component.UI;
+import com.vaadin.flow.di.Lookup;
 import com.vaadin.flow.function.SerializableConsumer;
+import com.vaadin.flow.server.VaadinContext;
+import com.vaadin.flow.server.VaadinService;
 import com.vaadin.flow.signals.Signal;
 
 /**
@@ -116,14 +119,17 @@ public class Geolocation implements Serializable {
      * {@link UI#getGeolocation()} and should not instantiate this class
      * directly — attempting to create a second instance for a UI that already
      * has one throws.
+     * <p>
+     * The underlying {@link GeolocationClient} is resolved through
+     * {@link Lookup}: if a {@link GeolocationClientFactory} is registered, its
+     * {@link GeolocationClientFactory#create(UI)} produces the client.
+     * Otherwise the built-in browser-backed client is used.
      *
      * @param ui
      *            the UI this facade belongs to
      * @throws IllegalStateException
      *             if the UI already has a Geolocation facade
      */
-    @SuppressWarnings("NullAway") // setClient always assigns client; the guard
-                                  // throw above it exits before client is used
     public Geolocation(UI ui) {
         if (ui.getGeolocation() != null) {
             throw new IllegalStateException(
@@ -133,12 +139,40 @@ public Geolocation(UI ui) {
         this.ui = ui;
         this.availabilityReadOnly = ui.getInternals()
                 .getGeolocationAvailabilitySignal().asReadonly();
+        this.client = resolveClient(ui);
+        wireClient(this.client);
+    }
+
+    private static GeolocationClient resolveClient(UI ui) {
+        GeolocationClientFactory factory = lookupFactory(ui);
+        if (factory != null) {
+            return factory.create(ui);
+        }
         GeolocationAvailability seed = ui.getInternals()
                 .getGeolocationAvailabilitySignal().peek();
         if (seed == null) {
             seed = GeolocationAvailability.UNKNOWN;
         }
-        setClient(new BrowserGeolocationClient(ui, seed));
+        return new BrowserGeolocationClient(ui, seed);
+    }
+
+    private static @Nullable GeolocationClientFactory lookupFactory(UI ui) {
+        VaadinService service = VaadinService.getCurrent();
+        if (service == null && ui.getSession() != null) {
+            service = ui.getSession().getService();
+        }
+        if (service == null) {
+            return null;
+        }
+        VaadinContext context = service.getContext();
+        if (context == null) {
+            return null;
+        }
+        Lookup lookup = context.getAttribute(Lookup.class);
+        if (lookup == null) {
+            return null;
+        }
+        return lookup.lookup(GeolocationClientFactory.class);
     }
 
     /**
@@ -296,24 +330,16 @@ public Signal<GeolocationAvailability> availabilitySignal() {
         return availabilityReadOnly;
     }
 
-    /**
-     * Replaces this facade's geolocation client.
-     *
-     * @param client
-     *            the replacement client, never null
-     */
     void setClient(GeolocationClient client) {
-        if (this.client != null) {
-            this.client.close();
-        }
+        this.client.close();
         this.client = client;
-        wireAvailability(client);
+        wireClient(client);
     }
 
-    private void wireAvailability(GeolocationClient activeClient) {
+    private void wireClient(GeolocationClient client) {
         ui.getInternals()
-                .setGeolocationAvailability(activeClient.currentAvailability());
-        activeClient.subscribeAvailability(
+                .setGeolocationAvailability(client.currentAvailability());
+        client.subscribeAvailability(
                 next -> ui.getInternals().setGeolocationAvailability(next));
     }
 }

flow-server/src/main/java/com/vaadin/flow/component/geolocation/GeolocationClient.java

@@ -30,17 +30,29 @@
  * position data — the browser in production, an in-memory test driver in unit
  * tests.
  * <p>
+ * <b>Framework internal.</b> Application code does not implement this interface
+ * directly. Replacement clients are installed at facade construction time by
+ * registering a {@link GeolocationClientFactory} through Vaadin's
+ * {@link com.vaadin.flow.di.Lookup Lookup}; {@link Geolocation} then hands the
+ * resulting client every {@link #get}, {@link #startWatch} and
+ * {@link #subscribeAvailability} call. When no factory is registered,
+ * {@code Geolocation} uses the built-in browser-backed client.
+ * <p>
  * <b>Threading:</b> all callbacks on this interface (the future returned by
  * {@link #get}, the {@code onUpdate} consumer passed to {@link #startWatch},
  * and the {@code onChange} consumer passed to {@link #subscribeAvailability})
  * must be invoked on the UI thread.
  */
 @NullMarked
-interface GeolocationClient extends Serializable {
+public interface GeolocationClient extends Serializable {
 
     /**
      * Issues a one-shot position request. The future completes once the client
      * has an answer (a position or an error).
+     *
+     * @param options
+     *            tuning options, or {@code null} for browser defaults
+     * @return a future that completes with the outcome on the UI thread
      */
     CompletableFuture<GeolocationOutcome> get(
             @Nullable GeolocationOptions options);
@@ -49,6 +61,15 @@ CompletableFuture<GeolocationOutcome> get(
      * Starts a watch session bound to {@code owner}. Position and error pushes
      * are delivered via {@code onUpdate}. The returned handle is used to stop
      * the watch and to query whether it is still active.
+     *
+     * @param owner
+     *            the component that owns this watch; detaching the component
+     *            does not auto-stop the watch — the caller is responsible
+     * @param options
+     *            tuning options, or {@code null} for browser defaults
+     * @param onUpdate
+     *            consumer invoked on the UI thread for every push
+     * @return a handle for stopping the watch
      */
     WatchHandle startWatch(Component owner,
             @Nullable GeolocationOptions options,
@@ -57,22 +78,28 @@ WatchHandle startWatch(Component owner,
     /**
      * Subscribes to availability changes. The returned registration removes the
      * subscription.
+     *
+     * @param onChange
+     *            consumer invoked on the UI thread for every availability
+     *            change
+     * @return a registration that removes the subscription when called
      */
     Registration subscribeAvailability(
             SerializableConsumer<GeolocationAvailability> onChange);
 
     /**
      * Returns the most recently observed availability. Implementations must
      * seed an initial value at construction; the result is never null.
+     *
+     * @return the current availability
      */
     GeolocationAvailability currentAvailability();
 
     /**
-     * Releases any resources held by this client. Called when the facade is
-     * replacing one client with another (e.g. when the test controller is
-     * installed) and on UI detach. Idempotent: calling more than once is a
-     * no-op. After {@code close()}, the behavior of {@link #get} and
-     * {@link #startWatch} is undefined and the facade must not call them.
+     * Releases any resources held by this client. Called on UI detach.
+     * Idempotent: calling more than once is a no-op. After {@code close()}, the
+     * behavior of {@link #get} and {@link #startWatch} is undefined and the
+     * facade must not call them.
      */
     void close();
 
@@ -91,6 +118,8 @@ interface WatchHandle extends Serializable {
         /**
          * Returns whether the watch is currently active (has not yet been
          * stopped or auto-cancelled).
+         *
+         * @return {@code true} if the watch is still receiving updates
          */
         boolean isActive();
     }

flow-server/src/main/java/com/vaadin/flow/component/geolocation/GeolocationClientFactory.java

@@ -0,0 +1,52 @@
+/*
+ * Copyright 2000-2026 Vaadin Ltd.
+ *
+ * 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.vaadin.flow.component.geolocation;
+
+import java.io.Serializable;
+
+import org.jspecify.annotations.NullMarked;
+
+import com.vaadin.flow.component.UI;
+import com.vaadin.flow.di.Lookup;
+
+/**
+ * <b>Framework internal.</b> Factory SPI that produces
+ * {@link GeolocationClient} instances per {@link UI}, resolved via
+ * {@link Lookup} when a {@link Geolocation} facade is constructed. When a
+ * factory is registered the resulting client replaces the built-in
+ * browser-backed client for every {@code UI} in the application; when none is,
+ * {@code Geolocation} uses the browser-backed client.
+ * <p>
+ * Used by external browserless test drivers to swap the production wire client
+ * for an in-memory driver in environments where package-private cross-JAR
+ * access is unreliable (split-classloader topologies such as Quarkus).
+ * Application code does not reference this interface directly. May be renamed
+ * or removed in a future release.
+ */
+@NullMarked
+public interface GeolocationClientFactory extends Serializable {
+
+    /**
+     * Creates a {@link GeolocationClient} for the given UI. Called once per UI,
+     * the first time {@link UI#getGeolocation()} is invoked.
+     *
+     * @param ui
+     *            the UI for which the client is created
+     * @return a client that will receive every {@code Geolocation} call for
+     *         that UI; never null
+     */
+    GeolocationClient create(UI ui);
+}

flow-server/src/test/java/com/vaadin/flow/component/geolocation/GeolocationClientSeamTest.java

@@ -22,10 +22,14 @@
 import org.jspecify.annotations.Nullable;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
+import org.mockito.Mockito;
 
 import com.vaadin.flow.component.Component;
 import com.vaadin.flow.component.Tag;
+import com.vaadin.flow.component.UI;
+import com.vaadin.flow.di.Lookup;
 import com.vaadin.flow.function.SerializableConsumer;
+import com.vaadin.flow.server.VaadinService;
 import com.vaadin.flow.shared.Registration;
 import com.vaadin.tests.util.MockUI;
 
@@ -36,9 +40,11 @@
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
 /**
- * Tests the {@link Geolocation#setClient(GeolocationClient)} +
- * {@link GeolocationTracker#handle()} seam — the framework-internal API surface
- * used by external browserless test drivers.
+ * Tests the {@link GeolocationClient} seam — both the public
+ * {@link GeolocationClientFactory} extension point that external test drivers
+ * and native bridges register through {@link Lookup}, and the package-private
+ * {@link Geolocation#setClient(GeolocationClient)} replacement that
+ * flow-server's own tests use.
  */
 class GeolocationClientSeamTest {
 
@@ -53,6 +59,22 @@ void setUp() {
     private static class TestComponent extends Component {
     }
 
+    @Test
+    void lookupFactory_resolvedAtConstruction_clientReceivesGetCalls() {
+        FakeClient fake = new FakeClient();
+        VaadinService service = VaadinService.getCurrent();
+        Lookup lookup = service.getContext().getAttribute(Lookup.class);
+        Mockito.when(lookup.lookup(GeolocationClientFactory.class))
+                .thenReturn(unused -> fake);
+
+        UI freshUi = new MockUI();
+        freshUi.getGeolocation().get(outcome -> {
+        });
+
+        assertEquals(1, fake.getCalls.size(),
+                "factory-produced client should receive get() calls");
+    }
+
     @Test
     void setClient_routesGetThroughInstalledClient() {
         FakeClient fake = new FakeClient();