craftdriver 1.4.0 → 1.6.0

package/docs/recipes/run-on-browserstack.md

@@ -0,0 +1,265 @@
+# Run On BrowserStack
+
+A provider-specific walkthrough of [Remote WebDriver](../remote-webdriver.md)
+against [BrowserStack](https://www.browserstack.com). craftdriver's core has
+no BrowserStack-specific code — everything here is the generic `remote`
+launch option plus BrowserStack's own `bstack:options` vendor capabilities,
+which pass straight through untouched. If you're targeting a different
+provider or a self-hosted Grid, start with the
+[Remote WebDriver](../remote-webdriver.md) page instead; this recipe assumes
+you've read it.
+
+The desktop and real-device examples use the hosted
+[login example](https://dtopuzov.github.io/craftdriver/examples/login.html).
+The BrowserStack Local example uses a URL reachable through your own tunnel.
+
+## Credentials
+
+```bash
+export BROWSERSTACK_USERNAME=your_username
+export BROWSERSTACK_ACCESS_KEY=your_access_key
+```
+
+Get these from BrowserStack's Automate dashboard. Never commit them — read
+them from the environment, as shown throughout this page.
+
+## Desktop Chrome (primary example)
+
+```ts
+import { Browser } from 'craftdriver';
+
+const browser = await Browser.launch({
+  browserName: 'chrome',
+  enableBiDi: true,
+  remote: {
+    url: 'https://hub.browserstack.com/wd/hub',
+    auth: {
+      username: process.env.BROWSERSTACK_USERNAME!,
+      password: process.env.BROWSERSTACK_ACCESS_KEY!,
+    },
+    // Allow time for BrowserStack to provision the session.
+    sessionTimeoutMs: 120_000,
+    commandTimeoutMs: 120_000,
+    capabilities: {
+      browserVersion: 'latest',
+      'bstack:options': {
+        os: 'Windows',
+        osVersion: '11',
+        projectName: 'CraftDriver',
+        buildName: 'Remote smoke',
+        sessionName: 'Chrome login flow',
+        seleniumBidi: true,
+        seleniumVersion: '4.20.0',
+      },
+    },
+  },
+});
+
+try {
+  await browser.navigateTo('https://dtopuzov.github.io/craftdriver/examples/login.html');
+  await browser.getByLabel('Username').fill('alice');
+  await browser.getByLabel('Password').fill('secret');
+  await browser.getByRole('button', { name: 'Sign in' }).click();
+  await browser.expect('#welcome').toContainText('Welcome back, alice!');
+} finally {
+  await browser.quit();
+}
+```
+
+BiDi requires both craftdriver's `enableBiDi: true` and BrowserStack's
+`seleniumBidi: true`. The Selenium version above follows BrowserStack's BiDi
+setup example; use the version in BrowserStack's current
+[BiDi guide](https://www.browserstack.com/docs/automate/selenium/bidi-event-driven-testing) or
+Capability Generator when they differ. After launch,
+`browser.isBiDiEnabled()` tells you whether the provider returned a usable
+BiDi endpoint.
+
+**Timeouts matter more remotely.** `sessionTimeoutMs` bounds only the initial
+`POST /session` request (30 seconds when omitted). `commandTimeoutMs` sets the
+default for subsequent Classic WebDriver HTTP commands. BiDi commands use
+their own WebSocket timeouts and are not bounded by `commandTimeoutMs`.
+
+## Concise variants
+
+### Desktop Safari (Classic only)
+
+```ts
+const browser = await Browser.launch({
+  browserName: 'safari',
+  // Remote Safari defaults to Classic.
+  remote: {
+    url: 'https://hub.browserstack.com/wd/hub',
+    auth: { username: process.env.BROWSERSTACK_USERNAME!, password: process.env.BROWSERSTACK_ACCESS_KEY! },
+    capabilities: {
+      'bstack:options': { os: 'OS X', osVersion: 'Sonoma', projectName: 'CraftDriver' },
+    },
+  },
+});
+```
+
+### Android Chrome (real device)
+
+```ts
+const browser = await Browser.launch({
+  browserName: 'chrome',
+  remote: {
+    url: 'https://hub.browserstack.com/wd/hub',
+    auth: { username: process.env.BROWSERSTACK_USERNAME!, password: process.env.BROWSERSTACK_ACCESS_KEY! },
+    capabilities: {
+      'bstack:options': { deviceName: 'Samsung Galaxy S23', osVersion: '13.0', realMobile: true },
+    },
+  },
+});
+```
+
+### iPhone Safari (real device)
+
+```ts
+const browser = await Browser.launch({
+  browserName: 'safari',
+  remote: {
+    url: 'https://hub.browserstack.com/wd/hub',
+    auth: { username: process.env.BROWSERSTACK_USERNAME!, password: process.env.BROWSERSTACK_ACCESS_KEY! },
+    capabilities: {
+      'bstack:options': { deviceName: 'iPhone 15', osVersion: '17', realMobile: true },
+    },
+  },
+});
+```
+
+craftdriver doesn't model devices at all — **BrowserStack owns the real-device
+catalog, and you pick from it.** Set `deviceName`/`osVersion`/`realMobile` in
+`bstack:options` and craftdriver forwards them untouched; there is no
+craftdriver device list to keep in sync. Pick valid values from BrowserStack's
+own sources, not from memory:
+
+- [Devices & platform grid](https://www.browserstack.com/list-of-browsers-and-platforms/automate)
+  — the live catalog of every real device, OS version, and browser available
+  for Automate.
+- [Capabilities reference](https://www.browserstack.com/docs/automate/capabilities)
+  — every `bstack:options` key, plus an interactive Capability Generator that
+  emits the exact capability object for a device you choose.
+
+A fleet's exact devices and OS versions change over time, so verify current
+names against those pages before pinning them in CI.
+
+`gesture.swipe()` and `gesture.pinch()` send W3C touch-pointer actions.
+Whether those actions are supported is determined by the selected real
+device, browser, and BrowserStack. Derive gesture coordinates from
+`window.innerWidth` and `window.innerHeight`; a remote driver can reject
+coordinates outside the device viewport with `move target out of bounds`.
+Assert the page behavior caused by each gesture instead of treating a
+no-error command as proof that the page received it.
+
+## Running a platform list sequentially and in parallel
+
+The three variants above are just different `capabilities`; running a list of
+them is a loop over that list plus [Remote WebDriver](../remote-webdriver.md#parallel-remote-sessions)'s
+same concurrency guarantee — each session gets its own connection pool, so
+quitting one never disrupts another running against the same hub.
+
+```ts
+const platforms = [
+  { browserName: 'chrome', 'bstack:options': { os: 'Windows', osVersion: '11' } },
+  { browserName: 'safari', 'bstack:options': { os: 'OS X', osVersion: 'Sonoma' } },
+  { browserName: 'chrome', 'bstack:options': { deviceName: 'Samsung Galaxy S23', realMobile: true } },
+];
+
+// Sequentially — one BrowserStack session (and its metered minute) at a time.
+for (const { browserName, ...capabilities } of platforms) {
+  const browser = await Browser.launch({
+    browserName,
+    remote: { url: hubUrl, auth, capabilities },
+  });
+  try {
+    await runSmokeFlow(browser);
+  } finally {
+    await browser.quit();
+  }
+}
+
+// In parallel — respect your BrowserStack plan's concurrent-session limit.
+await Promise.all(
+  platforms.map(async ({ browserName, ...capabilities }) => {
+    const browser = await Browser.launch({
+      browserName,
+      remote: { url: hubUrl, auth, capabilities },
+    });
+    try {
+      await runSmokeFlow(browser);
+    } finally {
+      await browser.quit();
+    }
+  })
+);
+```
+
+Running in parallel is useful only up to your plan's concurrent-session
+limit. BrowserStack may queue additional requests within your plan's queue
+allowance and reject requests beyond that allowance, so bound application
+concurrency instead of relying on an unlimited provider queue.
+
+## BrowserStack Local for internal/private sites
+
+craftdriver does not manage the BrowserStack Local process — provider
+infrastructure stays outside the generic library API, the same way
+craftdriver doesn't manage BrowserStack's Grid itself. You run the tunnel;
+craftdriver just launches a session that's told to use it.
+
+1. Run `BrowserStackLocal` yourself, on a machine/CI runner that can reach
+   your internal site, with a unique identifier:
+
+   ```bash
+   ./BrowserStackLocal --key $BROWSERSTACK_ACCESS_KEY --local-identifier ci-run-42
+   ```
+
+2. Wait for it to report ready (its own stdout, or the
+   [`browserstack-local` npm package](https://www.npmjs.com/package/browserstack-local)'s
+   callback if you're launching it programmatically) before starting the
+   session below — a session that requests `local: true` before the tunnel is
+   up simply can't reach the internal site.
+
+3. Set `local: true` in `bstack:options`, matching `localIdentifier` if you
+   have multiple tunnels running (e.g. parallel CI jobs):
+
+   ```ts
+   const browser = await Browser.launch({
+     browserName: 'chrome',
+     remote: {
+       url: 'https://hub.browserstack.com/wd/hub',
+       auth: { username: process.env.BROWSERSTACK_USERNAME!, password: process.env.BROWSERSTACK_ACCESS_KEY! },
+       capabilities: {
+         acceptInsecureCerts: true, // only if the internal site requires it
+         'bstack:options': { local: true, localIdentifier: 'ci-run-42' },
+       },
+     },
+   });
+
+   try {
+     await browser.navigateTo('http://localhost:3000/internal-dashboard');
+     // ...
+   } finally {
+     await browser.quit();
+   }
+   ```
+
+4. Configure tunnel behavior such as `--force-local` and proxy settings on
+   the `BrowserStackLocal` binary. `acceptInsecureCerts` is a standard
+   top-level WebDriver capability, as shown above. Follow BrowserStack's
+   [Local testing docs](https://www.browserstack.com/docs/automate/selenium/local-testing-introduction)
+   for the current tunnel flags.
+
+**Honest caveat:** the remote browser does not automatically inherit your
+test runner's VPN connection just because the tunnel is running somewhere —
+BrowserStack Local specifically proxies traffic through the machine running
+`BrowserStackLocal`, so that machine (not the machine running your test
+script) is what needs network access to the internal site.
+
+## See also
+
+- [Remote WebDriver](../remote-webdriver.md) — the generic, provider-neutral
+  page this recipe builds on.
+- [File Uploads And Downloads](./file-upload-download.md) — desktop remote
+  sessions can upload through Selenium's `se/file` extension; see
+  [Remote WebDriver → Remote file uploads](../remote-webdriver.md#remote-file-uploads)
+  for what's different under the hood.

package/docs/recipes.md

@@ -18,7 +18,10 @@ setup.
 
 The [Electron recipes](#electron) are different: they show the project shape for
 driving a packaged desktop app, so they use paths you adapt to your app repo
-rather than the hosted browser examples.
+rather than the hosted browser examples. The
+[BrowserStack recipe](#external-providers) is also different: it needs real
+provider credentials. Its live test is credential-gated, runs only for trusted
+repository events, and is skipped for forks.
 
 For exact signatures, use the linked feature docs and the
 [API reference](./api-reference.md).
@@ -55,6 +58,17 @@ For exact signatures, use the linked feature docs and the
 | Console and JavaScript errors | Tests should fail if the browser reports unexpected client-side errors.         | [Fail On Console And JavaScript Errors](./recipes/console-error-gate.md) |
 | Debug failing tests           | You need the actions, screenshots, logs, and network activity behind a failure. | [Use Traces To Debug Failing Tests](./recipes/debug-failing-tests-with-traces.md) |
 
+## External Providers
+
+Running against a remote Grid or cloud provider instead of a local browser.
+This recipe needs provider credentials. Its live test is credential-gated,
+runs on trusted pushes and pull requests, and is skipped for forks — see
+[`tests/recipes/README.md`](https://github.com/dtopuzov/craftdriver/blob/main/tests/recipes/README.md).
+
+| Scenario            | Use when                                                     | Recipe                                                   |
+| -------------------- | ------------------------------------------------------------- | --------------------------------------------------------- |
+| Run on BrowserStack | You want to run against real browsers/devices in the cloud.  | [Run On BrowserStack](./recipes/run-on-browserstack.md)  |
+
 ## Electron
 
 Driving a packaged Electron desktop app. These use paths you adapt to your app

package/docs/remote-webdriver.md

@@ -0,0 +1,308 @@
+# Remote WebDriver
+
+`Browser.launch({ remote })` connects to a W3C-compatible remote WebDriver
+endpoint — a self-hosted Selenium Grid, BrowserStack, or another cloud
+provider — instead of starting a local browser/driver process. You use the
+same `Browser` API after launch. Feature availability still depends on the
+browser, protocol, Grid configuration, and provider; BiDi-only features such
+as network interception require the endpoint to return a working
+`webSocketUrl`.
+
+craftdriver's core has **zero provider-specific code**. `remote` speaks plain
+W3C `POST /session` + Basic auth + opaque capability passthrough; a provider's
+own vendor capabilities (BrowserStack's `bstack:options`, or another
+provider's equivalent) pass straight through `remote.capabilities` untouched.
+See the [BrowserStack recipe](./recipes/run-on-browserstack.md) for a
+provider-specific walkthrough — this page stays generic.
+
+> **Not available from the CLI or MCP server.** Both are local dev tools —
+> they help you write and debug tests against a browser on your own machine,
+> not execute against a Grid or cloud. Passing `remote` to either fails fast
+> with a clear error at startup. Use the `Browser.launch({ remote })` library
+> API directly from your own script/test runner instead.
+
+## Local vs. remote session lifecycle
+
+A local launch starts a driver process (`chromedriver`/`geckodriver`/
+`safaridriver`) on your machine, then creates a WebDriver session against it.
+A remote launch skips that local process entirely — no driver download, no
+downloads directory, no browser-binary resolution — and creates the session
+directly against the endpoint you give it:
+
+```ts
+import { Browser } from 'craftdriver';
+
+const browser = await Browser.launch({
+  browserName: 'chrome',
+  remote: {
+    url: 'http://localhost:4444', // Selenium Grid 4 default
+  },
+});
+
+await browser.navigateTo('https://example.com');
+// ...
+await browser.quit(); // DELETEs the remote session
+```
+
+`browser.quit()` closes an active BiDi connection and deletes the WebDriver
+session. There is no local driver process for craftdriver to stop remotely.
+
+## A plain Selenium Grid, no provider-specific capabilities
+
+```ts
+const browser = await Browser.launch({
+  browserName: 'firefox',
+  remote: {
+    url: 'http://grid.internal:4444',
+  },
+});
+```
+
+Nothing above is BrowserStack-specific. Selenium Grid 4 uses the root URL by
+default. If your Grid is configured with a non-root base path, include that
+path in `remote.url`; craftdriver preserves it.
+
+## Authentication
+
+Pass credentials via `remote.auth`, or embed them in `remote.url` for
+Selenium-migration compatibility (`https://user:pass@host/...`) — not both;
+craftdriver rejects the combination rather than silently picking one.
+
+```ts
+const browser = await Browser.launch({
+  browserName: 'chrome',
+  remote: {
+    url: 'https://hub.browserstack.com/wd/hub',
+    auth: {
+      username: process.env.BROWSERSTACK_USERNAME!,
+      password: process.env.BROWSERSTACK_ACCESS_KEY!,
+    },
+  },
+});
+```
+
+Credentials are sent as a standard `Authorization: Basic ...` header on every
+request to the remote endpoint. craftdriver never logs `remote.auth`, never
+includes it in a thrown error's message or `detail`, and never forwards it to
+a BiDi WebSocket connection (some providers proxy `webSocketUrl` through a
+different host than the REST endpoint — Basic auth is tied to the REST
+origin and is never reused there).
+
+**Secret-handling guidance:** treat `remote.auth`/URL-embedded credentials
+like any other secret — read them from environment variables, never commit
+them, and never log the `remote` object itself (its `auth` field and any
+credential embedded in `url` are exactly what you don't want in a CI log).
+
+## Capabilities: standard and vendor-namespaced
+
+`remote.capabilities` is opaque W3C JSON. craftdriver validates that it is an
+object and merges it under `alwaysMatch`; vendor namespaces such as
+`bstack:options` pass through without schema conversion. craftdriver fills in
+`browserName` and its BiDi request defaults only when those values are absent.
+
+```ts
+const browser = await Browser.launch({
+  browserName: 'chrome',
+  remote: {
+    url: 'https://hub.browserstack.com/wd/hub',
+    auth: { username: '...', password: '...' },
+    capabilities: {
+      browserVersion: 'latest',
+      'bstack:options': {
+        os: 'Windows',
+        osVersion: '11',
+        projectName: 'CraftDriver',
+        buildName: 'Remote smoke',
+      },
+    },
+  },
+});
+```
+
+If `remote.capabilities` also sets `browserName`, it must agree
+(case-insensitively) with the top-level `browserName` — craftdriver rejects a
+genuine conflict rather than silently picking one.
+
+### Headless and other browser flags on a remote session
+
+A local launch honors the `HEADLESS` env var and injects `--headless=new` for
+you. A **remote** launch deliberately does not — the remote path is opaque
+passthrough and never adds browser flags itself (it can't assume which browser
+or vendor-option shape the endpoint runs). Pass headless (and any other flag)
+through the browser's own vendor capability:
+
+```ts
+const browser = await Browser.launch({
+  browserName: 'chrome',
+  remote: {
+    url: 'http://grid.internal:4444',
+    capabilities: {
+      'goog:chromeOptions': { args: ['--headless=new', '--no-sandbox', '--disable-dev-shm-usage'] },
+    },
+  },
+});
+```
+
+Use `moz:firefoxOptions.args` (`-headless`) for Firefox and `ms:edgeOptions`
+for Edge. This is how a Grid runs browsers headless on a CI runner with no
+display — no Xvfb required.
+
+## Browser names: not limited to craftdriver's local whitelist
+
+Locally, craftdriver only knows how to launch `chrome`, `chromium`,
+`firefox`, and `safari` — those are the only browsers craftdriver itself
+knows how to spawn a driver process for. Remotely, a Grid or provider may
+offer Edge, older browser versions, or anything else it supports, so
+`browserName` accepts any non-empty string for a remote launch and defaults
+to `'chrome'` when omitted.
+
+## Classic/BiDi negotiation for remote
+
+The default mirrors local policy: `chrome`, `chromium`, `firefox`, and
+`edge`/`microsoftedge` default to BiDi on (`enableBiDi !== false`); `safari`
+and any browser name craftdriver doesn't recognize default to Classic,
+requiring an explicit `enableBiDi: true` to opt in. Unlike local Safari
+(where `enableBiDi: true` is rejected outright), an unrecognized remote
+browser name is allowed to opt in — craftdriver just won't assume BiDi works
+for a name it doesn't know, but it also won't refuse the attempt.
+
+```ts
+const browser = await Browser.launch({
+  browserName: 'MicrosoftEdge',
+  remote: { url: 'https://hub.example.com/wd/hub' },
+});
+```
+
+If the remote endpoint doesn't actually return a `webSocketUrl` in its
+session-create response, craftdriver simply never attempts a BiDi connection
+— no error, no retry, the session runs Classic. If a BiDi connection is
+attempted and fails after retries, craftdriver falls back to Classic and logs
+a warning with the WebSocket URL's query string, fragment, and any embedded
+credentials stripped before logging.
+
+Whether a remote endpoint returns a `webSocketUrl` is up to that endpoint.
+Selenium Grid can proxy WebDriver BiDi when Grid BiDi proxying is enabled and
+the selected node/browser supports it. This project verifies that path with
+Selenium Grid 4.46.0 and Chrome. Administrators can disable the proxy, and a
+provider may require additional capabilities, so check
+`browser.isBiDiEnabled()` before depending on BiDi-only APIs.
+
+## Session and command timeouts
+
+Real remote sessions run over a network, not a loopback socket to a process
+craftdriver just spawned — set generous timeouts:
+
+```ts
+const browser = await Browser.launch({
+  remote: {
+    url: 'https://hub.example.com/wd/hub',
+    sessionTimeoutMs: 120_000, // POST /session — session creation only
+    commandTimeoutMs: 120_000, // applied as the default for every command after
+  },
+});
+```
+
+`sessionTimeoutMs` bounds only the initial session-creation request.
+`commandTimeoutMs` becomes the default for every WebDriver command sent over
+that session afterward (navigate, find, click, evaluate, ...), unless a
+specific call already passes its own timeout.
+
+A timed-out `POST /session` is **not retried** — a client-side timeout on
+session creation doesn't mean the remote end failed; it may have already
+created the session. Blind retry risks creating a second, paid, orphaned
+session on a metered provider, so craftdriver creates a remote session
+exactly once and surfaces the failure if it doesn't succeed. (Local sessions
+still retry — that logic exists for local driver-process readiness lag, which
+doesn't apply here.)
+
+## Parallel remote sessions
+
+Many concurrent sessions against one hub/host is the normal case for a
+Grid or cloud provider — unlike a local launch, where every `DriverService`
+picks its own port. craftdriver gives each remote session its own
+keep-alive connection pool, so quitting one session never disrupts another
+session's in-flight requests, even when they share the same host:port.
+
+```ts
+const [a, b] = await Promise.all([
+  Browser.launch({ browserName: 'chrome', remote: { url: hubUrl } }),
+  Browser.launch({ browserName: 'firefox', remote: { url: hubUrl } }),
+]);
+try {
+  await Promise.all([a.navigateTo(url1), b.navigateTo(url2)]);
+} finally {
+  await a.quit();
+  await b.quit(); // unaffected by a.quit() completing first
+}
+```
+
+## Supported / unsupported feature matrix
+
+The Classic/BiDi split still applies — see
+[WebDriver Standards](./standards.md). Remote endpoints add these constraints:
+
+| Feature | Remote behavior |
+|---|---|
+| File upload (`setInputFiles()`) | Supported when the endpoint implements Selenium's `se/file` extension; see below. Mobile/cloud sessions may require a provider-specific upload mechanism. |
+| Downloads (`waitForDownload()`) | **Unsupported.** Throws `UNSUPPORTED` immediately (not a timeout) — a remote session has no client-visible downloads directory. Use your provider's own download/artifact API if it has one. |
+| Desktop browsers, Edge, unrecognized names | Can be requested; the endpoint decides whether the browser/version is available. See [Browser names](#browser-names-not-limited-to-craftdrivers-local-whitelist). |
+| Real mobile browsers (Android Chrome, iOS Safari) | Device selection is provider-controlled. Pass documented device capabilities through `remote.capabilities`. `gesture.swipe()` and `gesture.pinch()` use W3C touch-pointer actions, but support is determined by the selected device/browser/provider; verify the gestures your suite relies on. |
+
+## Remote file uploads
+
+`setInputFiles()` works transparently on a remote session — you still pass a
+local file path:
+
+```ts
+await browser.find('input[type=file]').setInputFiles('/local/path/report.csv');
+```
+
+Under the hood, a local path cannot be used directly by a remote node.
+craftdriver zips the file, calls Selenium's
+`POST /session/{id}/se/file` extension, and sends the returned remote path to
+the input. This works for desktop Grid/provider sessions that implement that
+extension. Check your provider's documentation for mobile sessions or
+endpoints that do not implement `se/file`.
+
+## Provider tunnels for private/internal sites
+
+craftdriver doesn't manage a provider's tunnel process (e.g. BrowserStack
+Local) — that stays outside the generic library API, the same way craftdriver
+doesn't manage the Grid/hub itself. Start the tunnel yourself (or in CI)
+before launching, then pass whatever capability the provider documents for
+routing through it (e.g. `local: true` in BrowserStack's `bstack:options`).
+See the [BrowserStack recipe](./recipes/run-on-browserstack.md#browserstack-local-for-internalprivate-sites)
+for a worked example.
+
+## Troubleshooting
+
+**Authentication failures** — double check `remote.auth` isn't also set
+alongside URL-embedded credentials (craftdriver rejects that combination at
+launch, before any network call); confirm the credential env vars are
+actually set in the process running your tests, not just your shell.
+
+**Hub base paths** — Selenium Grid 4 uses its root URL by default, for example
+`http://grid.internal:4444`. If your deployment configures a base path (or
+uses a legacy `/wd/hub` path), include it in `remote.url`; craftdriver
+preserves the path you pass.
+
+**Capability mismatch** — for a `session not created` response, inspect the
+provider's error and validate the browser, OS, version, and vendor capability
+names against its current capability generator or platform catalog.
+
+**BiDi connectivity** — if you expect BiDi but `browser.isBiDiEnabled()` is
+`false`, confirm the provider returned a `webSocketUrl` for the session. Some
+providers require their own opt-in capability in addition to craftdriver's
+`enableBiDi`; BrowserStack currently documents `seleniumBidi: true`. Also
+confirm that your network permits outbound WebSocket connections to the
+returned host.
+
+## See also
+
+- [BrowserStack recipe](./recipes/run-on-browserstack.md) — a full,
+  provider-specific walkthrough with desktop, mobile, and BrowserStack Local
+  examples.
+- [Driver Configuration](./driver-configuration.md) — local-only; this page
+  is the remote counterpart.
+- [WebDriver Standards](./standards.md) — the Classic/BiDi split this page
+  builds on.