docs: changelog entries and drag-and-drop recipe for unreleased features

CHANGELOG.md

@@ -9,6 +9,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ### Unreleased
 
+- **`Locator.dragTo(Locator)`** — drags one element onto another, including HTML5 drag-and-drop pages that ignore the native gesture. See [Drag and drop](docs-site/docs/recipes/drag-and-drop). (#101)
+- **`debug.slowMoMs` / `debug.highlight`** — dev-only live-triage aids: pause after each `Locator` action and outline the element about to be acted on. Off by default, no cost when off; not for CI. See [Debug](docs-site/docs/configuration.md). (#52)
+- **`withNewWindow(opener, body)` / `withNewTab(...)` on `BasePage`** — run the click that opens a new window, switch to it, run your checks, close it and return to the original window, even if the checks throw. No window opening within `timeouts.explicit` throws `TimeoutException`. See [Handle new windows and tabs](docs-site/docs/recipes/handle-new-windows). (#49)
+- **`browser.version`** — optional exact browser version for local Chrome/Firefox runs, resolved by Selenium Manager. Omit it to use the installed browser. (#51)
+
 ---
 
 ### v3.6.0 — 2026-09-27

docs-site/docs/changelog.md

@@ -11,6 +11,15 @@ All notable changes to Selenium Boot are documented here.
 
 ---
 
+## [Unreleased]
+
+- **`Locator.dragTo(Locator)`** — drags one element onto another, including HTML5 drag-and-drop pages that ignore the native gesture. See [Drag and drop](./recipes/drag-and-drop). (#101)
+- **`debug.slowMoMs` / `debug.highlight`** — dev-only live-triage aids: pause after each `Locator` action and outline the element about to be acted on. Off by default, no cost when off; not for CI. See [Debug](./configuration#debug). (#52)
+- **`withNewWindow(opener, body)` / `withNewTab(...)` on `BasePage`** — run the click that opens a new window, switch to it, run your checks, close it and return to the original window, even if the checks throw. No window opening within `timeouts.explicit` throws `TimeoutException`. See [Handle new windows and tabs](./recipes/handle-new-windows). (#49)
+- **`browser.version`** — optional exact browser version for local Chrome/Firefox runs, resolved by Selenium Manager. Omit it to use the installed browser. (#51)
+
+---
+
 ## [3.6.0] — 2026-09-27
 
 - **`WaitEngine.waitForNetworkIdle()` / `waitForResponse(urlPattern)`** — waits until no network request has been in flight for a quiet period (default 500ms, or a custom `Duration`), or until a response whose URL matches a glob pattern (same syntax as `NetworkMock.stub`) is observed, returning its HTTP status code. Both are bounded by the configured explicit timeout. Works on Chrome/Edge (via CDP) and any BiDi-capable browser such as Firefox; throws `UnsupportedOperationException` on others. Firefox sessions now request a BiDi connection by default (`webSocketUrl` capability) so this works with no extra configuration — an explicit value in the user's own `browser.capabilities` still wins.

docs-site/docs/recipes/drag-and-drop.md

@@ -0,0 +1,20 @@
+---
+description: "Drag one element onto another in Selenium, including HTML5 drag-and-drop pages that ignore the native gesture: Locator.dragTo handles both."
+id: drag-and-drop
+title: Drag and drop
+sidebar_label: Drag and drop
+---
+
+# Drag and drop
+
+`Locator.dragTo(target)` drags one element onto another and drops it there.
+
+```java title="BoardPage.java"
+Locator.byText("Card A").dragTo(Locator.ofCss("#done-column"));
+```
+
+It tries the native drag gesture first. Pages built on the HTML5 drag-and-drop API
+(`draggable="true"` with `dragstart` / `drop` listeners) often ignore that gesture, so when no
+`drop` event reaches the target, `dragTo` dispatches the full event sequence itself. Both elements
+are waited for and re-resolved like every other `Locator` action, so a slow or re-rendering page is
+handled within `timeouts.explicit`; a `LocatorException` is thrown if either element never appears.

docs-site/sidebars.js

@@ -62,6 +62,7 @@ const sidebars = {
         'recipes/download-and-verify-a-pdf',
         'recipes/handle-iframes',
         'recipes/handle-new-windows',
+        'recipes/drag-and-drop',
         'recipes/handle-shadow-dom',
       ],
     },