Add sync kernel readiness framework with Selenium implementation and default policies

java/docs/locator-engine-user-journey.md

@@ -40,3 +40,4 @@ rememberMe.check();
 - Action pipeline behavior is opt-in via locator actions and does not affect raw WebDriver calls.
 - User journey remains valid as long as locators remain factory-created and strictness defaults are preserved.
 - Stability signal sampling is non-blocking and only enriches diagnostics when used, so the existing journey does not change.
+- Sync kernel readiness waits are opt-in and only apply when frameworks route actions through the SyncKernel helpers.

java/docs/locator-sync-user-journey.md

@@ -0,0 +1,40 @@
+# Locator Sync Kernel User Journey
+
+This document describes the user journey for adopting the Sync Kernel readiness engine in Selenium Java.
+It is opt-in and only applies when framework actions/assert helpers call the Sync Kernel APIs.
+
+## Journey: Action Readiness via SyncKernel
+
+1. **Create or obtain a SyncKernel**
+   - Use `SeleniumSyncKernelFactory` with a WebDriver, policy, and optional BiDi + stability services.
+2. **Hook into action lifecycle**
+   - Framework calls `onBeforeAction` to capture baseline signals.
+   - Framework calls `onAfterAction` with action outcome to trigger readiness waits.
+3. **Wait for intent-specific readiness**
+   - `waitReady` enforces gates based on intent (CLICK, TYPE, NAVIGATE, ASSERT, MODAL).
+   - BiDi-dependent gates are skipped when unsupported, with diagnostics noting degradation.
+4. **Handle diagnostics on timeout**
+   - Failures return `SyncDiagnostics` that include gate states and last signal snapshots.
+
+## Example Flow
+
+```java
+SyncKernel kernel = SeleniumSyncKernelFactory.create(driver, DefaultSyncPolicy.create(), bidi, stability);
+
+ActionContext ctx = new ActionContext(
+    ActionType.CLICK,
+    new WaitTargetElement(buttonElement),
+    null,
+    WaitOptions.defaults(),
+    false);
+
+kernel.onBeforeAction(ctx);
+// perform click here
+kernel.onAfterAction(ctx, ActionOutcome.SUCCESS);
+```
+
+## Impact Check
+
+- The sync kernel does not intercept WebDriver globally; it is only used where actions are routed through it.
+- Existing locator usage and diagnostics remain valid without changes.
+- Readiness waits are bounded by policy timeouts and can be disabled per call using custom policy or options.

java/src/org/openqa/selenium/locator/sync/ActionContext.java

@@ -0,0 +1,44 @@
+package org.openqa.selenium.locator.sync;
+
+import java.util.Objects;
+
+public final class ActionContext {
+  private final ActionType actionType;
+  private final WaitTarget target;
+  private final WaitTarget containerTarget;
+  private final WaitOptions waitOptions;
+  private final boolean jsFallbackUsed;
+
+  public ActionContext(
+      ActionType actionType,
+      WaitTarget target,
+      WaitTarget containerTarget,
+      WaitOptions waitOptions,
+      boolean jsFallbackUsed) {
+    this.actionType = Objects.requireNonNull(actionType, "actionType");
+    this.target = target;
+    this.containerTarget = containerTarget;
+    this.waitOptions = waitOptions == null ? WaitOptions.defaults() : waitOptions;
+    this.jsFallbackUsed = jsFallbackUsed;
+  }
+
+  public ActionType actionType() {
+    return actionType;
+  }
+
+  public WaitTarget target() {
+    return target;
+  }
+
+  public WaitTarget containerTarget() {
+    return containerTarget;
+  }
+
+  public WaitOptions waitOptions() {
+    return waitOptions;
+  }
+
+  public boolean jsFallbackUsed() {
+    return jsFallbackUsed;
+  }
+}

java/src/org/openqa/selenium/locator/sync/ActionOutcome.java

@@ -0,0 +1,7 @@
+package org.openqa.selenium.locator.sync;
+
+public enum ActionOutcome {
+  SUCCESS,
+  FAILURE_RETRYABLE,
+  FAILURE_FATAL
+}

java/src/org/openqa/selenium/locator/sync/ActionType.java

@@ -0,0 +1,19 @@
+package org.openqa.selenium.locator.sync;
+
+public enum ActionType {
+  CLICK,
+  DBLCLICK,
+  RIGHT_CLICK,
+  HOVER,
+  TYPE,
+  CLEAR,
+  SELECT,
+  PRESS_KEY,
+  NAVIGATE_TO,
+  BACK,
+  FORWARD,
+  REFRESH,
+  UPLOAD_FILE,
+  SCROLL_INTO_VIEW,
+  CUSTOM_JS
+}

java/src/org/openqa/selenium/locator/sync/GateStatus.java

@@ -0,0 +1,8 @@
+package org.openqa.selenium.locator.sync;
+
+public record GateStatus(
+    boolean active,
+    boolean satisfied,
+    String reason,
+    Long becameTrueAtEpochMs,
+    Long lastChangedAtEpochMs) {}

java/src/org/openqa/selenium/locator/sync/Intent.java

@@ -0,0 +1,10 @@
+package org.openqa.selenium.locator.sync;
+
+public enum Intent {
+  CLICK,
+  TYPE,
+  NAVIGATE,
+  ASSERT,
+  OPEN_MODAL,
+  CLOSE_MODAL
+}

java/src/org/openqa/selenium/locator/sync/SyncDiagnostics.java

@@ -0,0 +1,24 @@
+package org.openqa.selenium.locator.sync;
+
+import java.util.List;
+import java.util.Map;
+import org.openqa.selenium.locator.bidi.model.BidiCapability;
+import org.openqa.selenium.locator.bidi.model.ConsoleSnapshot;
+import org.openqa.selenium.locator.bidi.model.NavigationSnapshot;
+import org.openqa.selenium.locator.bidi.model.NetworkSnapshot;
+import org.openqa.selenium.locator.stability.model.StabilitySnapshot;
+
+public record SyncDiagnostics(
+    Intent intent,
+    String currentUrl,
+    String title,
+    long elapsedMillis,
+    Map<String, GateStatus> gates,
+    BidiCapability bidiCapability,
+    NetworkSnapshot networkSnapshot,
+    ConsoleSnapshot consoleSnapshot,
+    NavigationSnapshot navigationSnapshot,
+    List<StabilitySnapshot> stabilitySamples,
+    String readyState,
+    List<String> notes) {}
+

java/src/org/openqa/selenium/locator/sync/SyncKernel.java

@@ -0,0 +1,13 @@
+package org.openqa.selenium.locator.sync;
+
+public interface SyncKernel {
+  WaitResult waitReady(Intent intent, WaitTarget target, WaitOptions options);
+
+  default WaitResult waitReady(Intent intent) {
+    return waitReady(intent, new WaitTargetNone(), WaitOptions.defaults());
+  }
+
+  void onBeforeAction(ActionContext ctx);
+
+  void onAfterAction(ActionContext ctx, ActionOutcome outcome);
+}

java/src/org/openqa/selenium/locator/sync/SyncTimeoutException.java

@@ -0,0 +1,14 @@
+package org.openqa.selenium.locator.sync;
+
+public class SyncTimeoutException extends RuntimeException {
+  private final WaitResult result;
+
+  public SyncTimeoutException(String message, WaitResult result) {
+    super(message);
+    this.result = result;
+  }
+
+  public WaitResult result() {
+    return result;
+  }
+}

java/src/org/openqa/selenium/locator/sync/WaitOptions.java

@@ -0,0 +1,12 @@
+package org.openqa.selenium.locator.sync;
+
+import java.time.Duration;
+
+public record WaitOptions(
+    Duration timeoutOverride,
+    boolean includeDiagnostics,
+    boolean strictConsoleErrors) {
+  public static WaitOptions defaults() {
+    return new WaitOptions(null, true, false);
+  }
+}

java/src/org/openqa/selenium/locator/sync/WaitResult.java

@@ -0,0 +1,6 @@
+package org.openqa.selenium.locator.sync;
+
+public record WaitResult(
+    boolean success,
+    long elapsedMillis,
+    SyncDiagnostics diagnostics) {}

java/src/org/openqa/selenium/locator/sync/WaitTarget.java

@@ -0,0 +1,3 @@
+package org.openqa.selenium.locator.sync;
+
+public interface WaitTarget {}

java/src/org/openqa/selenium/locator/sync/WaitTargetContainer.java

@@ -0,0 +1,3 @@
+package org.openqa.selenium.locator.sync;
+
+public record WaitTargetContainer(Object elementHandle) implements WaitTarget {}

java/src/org/openqa/selenium/locator/sync/WaitTargetElement.java

@@ -0,0 +1,3 @@
+package org.openqa.selenium.locator.sync;
+
+public record WaitTargetElement(Object elementHandle) implements WaitTarget {}

java/src/org/openqa/selenium/locator/sync/WaitTargetNone.java

@@ -0,0 +1,3 @@
+package org.openqa.selenium.locator.sync;
+
+public record WaitTargetNone() implements WaitTarget {}

java/src/org/openqa/selenium/locator/sync/policy/ConsolePolicy.java

@@ -0,0 +1,10 @@
+package org.openqa.selenium.locator.sync.policy;
+
+import java.util.List;
+import java.util.regex.Pattern;
+
+public record ConsolePolicy(
+    boolean requiredWhenSupported,
+    boolean treatWarnAsFailure,
+    List<Pattern> readinessDenylist,
+    List<Pattern> readinessAllowlist) {}