craftdriver 1.3.0 → 1.5.0

package/docs/recipes/electron-app-from-another-repo.md

@@ -0,0 +1,136 @@
+# Test An Electron App From Another Repo
+
+Use this when your Electron application is built in one repository, but your
+CraftDriver tests live in another repository or package. The important part is
+that the test launches the **packaged executable** produced by the app repo.
+
+This recipe assumes a sibling checkout:
+
+```text
+~/git/
+  my-electron-app/
+  my-electron-tests/
+```
+
+## Build the app first
+
+From the app repo, produce the packaged app the same way CI or release builds do:
+
+```bash
+cd ~/git/my-electron-app
+npm ci
+npm run build
+npm run package
+```
+
+The exact command depends on your app. The output is usually under `dist/`,
+`out/`, or `release/`. Point CraftDriver at the executable inside that output,
+not at the source directory.
+
+## Keep the app path in one helper
+
+In the test repo, create a small fixture helper so every test uses the same
+path and Electron version:
+
+```ts
+// tests/fixtures/electron-app.ts
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Browser } from 'craftdriver';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const workspace = path.resolve(here, '..', '..', '..');
+const appRepo = path.join(workspace, 'my-electron-app');
+
+export function appBinaryPath(): string {
+  const override = process.env.MY_APP_BINARY;
+  if (override) return override;
+
+  switch (`${process.platform}-${process.arch}`) {
+    case 'darwin-arm64':
+    case 'darwin-x64':
+      return path.join(appRepo, 'dist/mac/MyApp.app/Contents/MacOS/MyApp');
+    case 'win32-x64':
+      return path.join(appRepo, 'dist/win-unpacked/MyApp.exe');
+    case 'linux-x64':
+      return path.join(appRepo, 'dist/linux-unpacked/my-app');
+    default:
+      throw new Error(`Unsupported Electron test platform: ${os.platform()}-${os.arch()}`);
+  }
+}
+
+export function launchApp(): Promise<Browser> {
+  return Browser.launch({
+    electron: {
+      appBinaryPath: appBinaryPath(),
+      version: process.env.MY_APP_ELECTRON_VERSION ?? '43.1.0',
+      args: process.platform === 'linux' ? ['--no-sandbox'] : [],
+    },
+  });
+}
+```
+
+Use `MY_APP_BINARY` when CI downloads a prebuilt app artifact instead of building
+from a sibling checkout.
+
+## Write the test like a normal renderer test
+
+Electron defaults to Classic WebDriver, so the app loads itself. Do not call
+`navigateTo()` unless you explicitly opted into BiDi and know the renderer URL.
+
+```ts
+// tests/settings.test.ts
+import { afterEach, describe, it } from 'vitest';
+import { Browser, By } from 'craftdriver';
+import { launchApp } from './fixtures/electron-app';
+
+describe('settings window', () => {
+  let browser: Browser | undefined;
+
+  afterEach(async () => {
+    await browser?.quit();
+  });
+
+  it('saves the profile name', async () => {
+    browser = await launchApp();
+
+    const main = await browser.waitForPage({ title: /My App/ });
+    await main.find(By.testId('app-title')).expect().toHaveText('My App');
+
+    await main.click(By.testId('nav-settings'));
+    await main.fill(By.testId('profile-name'), 'Ada Lovelace');
+    await main.click(By.testId('save-settings'));
+
+    await main.find(By.testId('settings-status')).expect().toHaveText('Saved');
+  });
+});
+```
+
+Prefer stable `data-testid` attributes in the Electron renderer. You can inspect
+or debug the app with DevTools while designing selectors, but the test should
+interact with the packaged UI the way a user would.
+
+## CI shape
+
+A common CI flow is:
+
+1. Check out or download the Electron app.
+2. Build/package the app, or download a packaged artifact.
+3. Set `MY_APP_BINARY` and `MY_APP_ELECTRON_VERSION`.
+4. Run the CraftDriver tests.
+
+On Linux, run the tests under Xvfb:
+
+```bash
+xvfb-run -a npm test
+```
+
+On macOS and Windows hosted runners, a display is already available. Do not pass
+headless flags to Electron; it is a desktop GUI app.
+
+## Learn More
+
+- [Testing Electron Apps](../electron.md)
+- [Browser API](../browser-api.md)
+- [Vitest Hooks](./vitest-browser-lifecycle.md)

package/docs/recipes/electron-deep-link.md

@@ -0,0 +1,117 @@
+# Test An Electron Deep Link
+
+Use this pattern when your app registers a custom URL scheme (`myapp://…`) and you
+want to verify it handles a link the OS delivers from outside the app. CraftDriver
+opens the link through the real OS launcher, so your production `open-url` /
+`second-instance` handler runs unchanged.
+
+## Application code
+
+Register the protocol and route incoming links to the window. This is normal
+production code, not test instrumentation:
+
+```js
+const { app, BrowserWindow } = require('electron');
+
+const SCHEME = 'myapp';
+let mainWindow = null;
+let lastDeeplink = null;
+
+app.setAsDefaultProtocolClient(SCHEME);
+
+function handleDeeplink(url) {
+  if (!url) return;
+  lastDeeplink = url;
+  if (mainWindow && !mainWindow.isDestroyed()) mainWindow.webContents.send('deeplink', url);
+}
+
+// macOS: the running instance receives the URL here.
+app.on('open-url', (event, url) => {
+  event.preventDefault();
+  handleDeeplink(url);
+});
+
+// Windows/Linux: a deep link launches a second process. Hold the single-instance
+// lock so its argv is routed back into the running instance instead of opening a
+// duplicate window.
+if (!app.requestSingleInstanceLock()) {
+  app.quit();
+} else {
+  app.on('second-instance', (_event, argv) => {
+    handleDeeplink(argv.find((a) => a.startsWith(`${SCHEME}://`)));
+  });
+}
+```
+
+Declare the scheme so the packaged app is registered with the OS. With
+electron-builder:
+
+```yaml
+# electron-builder.yml
+protocols:
+  - name: My App Protocol
+    schemes:
+      - myapp
+```
+
+Forward the link to the renderer through a narrow preload API:
+
+```js
+const { contextBridge, ipcRenderer } = require('electron');
+
+contextBridge.exposeInMainWorld('myapp', {
+  onDeeplink: (cb) => ipcRenderer.on('deeplink', (_event, url) => cb(url)),
+});
+```
+
+```js
+// renderer
+window.myapp?.onDeeplink((url) => {
+  document.querySelector('[data-testid="deeplink-result"]').textContent = url;
+});
+```
+
+## Test code
+
+```ts
+import { Browser, By } from 'craftdriver';
+import { expect, test } from 'vitest';
+
+test('handles an incoming deep link', async () => {
+  const browser = await Browser.launch({
+    electron: {
+      appBinaryPath: process.env.APP_PATH!, // required on Windows to route the link
+      version: process.env.ELECTRON_VERSION!,
+      mainProcess: true, // lets craftdriver auto-detect the user-data dir (Windows/Linux)
+    },
+  });
+
+  try {
+    const url = 'myapp://open?file=test.txt';
+    await browser.electron.triggerDeeplink(url);
+
+    // triggerDeeplink is fire-and-forget: assert the effect through the app.
+    await browser.find(By.testId('deeplink-result')).expect().toHaveText(url);
+
+    // Only custom protocols are valid targets.
+    await expect(browser.electron.triggerDeeplink('https://example.com')).rejects.toThrow();
+  } finally {
+    await browser.quit();
+  }
+});
+```
+
+The reference example implements this exact flow (scheme `craftdriver-example://`)
+in [`craftdriver-examples`](https://github.com/dtopuzov/craftdriver-examples/tree/main/electron).
+
+## Notes
+
+- **macOS** needs the app bundle known to LaunchServices — installed in
+  `/Applications`, or registered once with `lsregister -f MyApp.app`.
+- **Windows / Linux** launch a second process for the link; craftdriver appends the
+  running app's user-data dir as a `userData` query parameter so the single-instance
+  lock hands the link to the test instance. Your app should honor that parameter
+  when it sets its user-data path if you run isolated instances.
+- Like `mockDialog()` and `executeMain()`, deep-link routing that inspects the app
+  via the main process needs the `EnableNodeCliInspectArguments` fuse enabled; the
+  OS launch itself does not.

package/docs/recipes/electron-mock-apis.md

@@ -0,0 +1,88 @@
+# Mock Electron APIs (shell, clipboard, app…)
+
+Native dialogs have a typed helper (`mockDialog()`), but plenty of Electron
+behavior you want to keep out of a test run doesn't: opening the user's browser
+(`shell.openExternal`), writing the system clipboard (`clipboard.writeText`),
+resolving OS paths (`app.getPath`), and so on. `browser.electron.mock()` replaces
+any `electron.<api>.<fn>` main-process method with a scripted return and a call
+recorder, so you can drive the real UI and assert what it asked the OS to do —
+without the OS actually doing it.
+
+Needs main-process access (`electron: { mainProcess: true }`), like `executeMain`
+and `mockDialog`.
+
+## Stop a "share" button from launching a browser
+
+Application code — a normal renderer → preload → IPC → `shell.openExternal` flow:
+
+```js
+// main.js
+const { ipcMain, shell } = require('electron');
+ipcMain.handle('share:open', (_event, url) => shell.openExternal(url));
+```
+
+```js
+// preload.js
+const { contextBridge, ipcRenderer } = require('electron');
+contextBridge.exposeInMainWorld('share', { open: (url) => ipcRenderer.invoke('share:open', url) });
+```
+
+Test — mock the final `shell.openExternal`, click, and assert the URL it received:
+
+```ts
+import { Browser, By } from 'craftdriver';
+import { expect, test } from 'vitest';
+
+test('share button opens the right URL without launching a browser', async () => {
+  const browser = await Browser.launch({
+    electron: { appBinaryPath: process.env.APP_PATH!, mainProcess: true },
+  });
+
+  try {
+    // shell.openExternal resolves to true on success — script that.
+    const openExternal = await browser.electron.mock('shell', 'openExternal', true);
+
+    await browser.click(By.testId('share-btn'));
+
+    expect(await openExternal.getCalls()).toEqual([{ args: ['https://example.com/report/42'] }]);
+    await openExternal.restore();
+  } finally {
+    await browser.quit();
+  }
+});
+```
+
+Each recorded call is `{ args: [...] }` with the (JSON-safe) arguments the app
+passed. The rest of the handle mirrors `mockDialog`: `getCallCount()`,
+`clearCalls()`, `mockReturnValue(value)` to re-script mid-test, and `restore()`
+(also restored on `browser.quit()`).
+
+## Assert what the app copied to the clipboard
+
+```ts
+const writeText = await browser.electron.mock('clipboard', 'writeText');
+
+await browser.click(By.testId('copy-link-btn'));
+
+expect(await writeText.getCalls()).toEqual([{ args: ['https://example.com/report/42'] }]);
+await writeText.restore();
+```
+
+Here no return value is scripted — `clipboard.writeText` returns nothing, so the
+mock returns `undefined` and you assert purely on the recorded arguments.
+
+## Notes
+
+- The scripted value is returned **as-is** (not wrapped in a Promise), so it works
+  for synchronous methods (`app.getName()`, `app.getPath()`) and `await`ed
+  asynchronous ones (`shell.openExternal`). Pass the already-resolved value for an
+  async method.
+- Arguments and the return value must be JSON-serializable; a non-serializable
+  argument (a `BrowserWindow`, a `Buffer`) is recorded as a descriptive placeholder
+  rather than crossing the process boundary.
+- `mock()` targets **object-namespace** methods (`shell`, `clipboard`, `app`,
+  `dialog`, …). Class-based APIs such as `Notification` or `Menu` are not covered by
+  it today — mock the app code that *constructs* them instead, or drive them through
+  your own IPC surface.
+- Reach for the typed [`mockDialog()`](../electron.md#mock-native-dialogs) for file,
+  save, and message dialogs; it validates the result shape for you.

package/docs/recipes/electron-native-dialog.md

@@ -0,0 +1,105 @@
+# Mock A Native Electron File Dialog
+
+Use this pattern when a renderer action opens Electron's operating-system file
+picker. The real app remains structured normally: a sandboxed renderer calls a
+narrow preload API, the preload sends IPC, and the main process opens the native
+dialog. The test replaces only the final `dialog.showOpenDialog()` call.
+
+## Application code
+
+Register the dialog in the main process:
+
+```js
+const { BrowserWindow, dialog, ipcMain } = require('electron');
+
+ipcMain.handle('native-dialog:open-file', (event) => {
+  const parent = BrowserWindow.fromWebContents(event.sender);
+  const options = {
+    title: 'Choose a text file',
+    properties: ['openFile'],
+    filters: [{ name: 'Text files', extensions: ['txt', 'md'] }],
+  };
+
+  return parent ? dialog.showOpenDialog(parent, options) : dialog.showOpenDialog(options);
+});
+```
+
+Expose only the operation the renderer needs:
+
+```js
+const { contextBridge, ipcRenderer } = require('electron');
+
+contextBridge.exposeInMainWorld('craftdriverExample', {
+  openFile: () => ipcRenderer.invoke('native-dialog:open-file'),
+});
+```
+
+The renderer can use the returned value like the real Electron result:
+
+```js
+document.querySelector('[data-testid="open-native-file-btn"]').addEventListener('click', async () => {
+  const result = await window.craftdriverExample.openFile();
+  document.querySelector('[data-testid="native-dialog-result"]').textContent = result.canceled
+    ? 'cancelled'
+    : result.filePaths.join(', ');
+});
+```
+
+## Test code
+
+Opt in to main-process access and install the mock before clicking:
+
+```ts
+import { Browser, By } from 'craftdriver';
+import { expect, test } from 'vitest';
+
+test('selects an invoice without opening an OS dialog', async () => {
+  const browser = await Browser.launch({
+    electron: {
+      appBinaryPath: process.env.APP_PATH!,
+      version: process.env.ELECTRON_VERSION!,
+      mainProcess: true,
+    },
+  });
+
+  try {
+    const dialog = await browser.electron.mockDialog('showOpenDialog', {
+      canceled: false,
+      filePaths: ['/fixtures/invoice.txt'],
+    });
+
+    await browser.click(By.testId('open-native-file-btn'));
+    await browser
+      .find(By.testId('native-dialog-result'))
+      .expect()
+      .toHaveText('/fixtures/invoice.txt');
+
+    // The click reached the main process: the mock recorded the exact options the
+    // ipcMain handler passed to dialog.showOpenDialog — no OS dialog ever opened.
+    expect(await dialog.getCalls()).toEqual([
+      {
+        options: {
+          title: 'Choose a text file',
+          properties: ['openFile'],
+          filters: [{ name: 'Text files', extensions: ['txt', 'md'] }],
+        },
+      },
+    ]);
+  } finally {
+    await browser.quit();
+  }
+});
+```
+
+The reference example implements this exact flow in
+[`craftdriver-examples`](https://github.com/dtopuzov/craftdriver-examples/tree/main/electron).
+
+## Production and hardened builds
+
+No application test hook is required. This works against an unchanged packaged
+production artifact when its `EnableNodeCliInspectArguments` Electron fuse is
+enabled. The fuse is enabled by default, but security-hardened builds may disable
+it. A disabled fuse cannot be changed after the app is signed; package a separate
+test artifact with that fuse enabled. See
+[Testing Electron Apps](../electron.md#can-this-test-a-production-build) for the
+Forge configuration and security boundary.

package/docs/recipes.md

@@ -16,23 +16,27 @@ launched `browser` — unless it shows a `Browser.launch(...)` call itself. See
 [Vitest Hooks recipe](./recipes/vitest-browser-lifecycle.md) for the surrounding
 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.
+
 For exact signatures, use the linked feature docs and the
 [API reference](./api-reference.md).
 
 ## Start Here
 
-| Scenario           | Use when                                                          | Recipe                                                     |
-| ------------------ | ---------------------------------------------------------------- | --------------------------------------------------------- |
-| Find elements      | You're new and need to point CraftDriver at the element you want. | [Find Elements On The Page](./recipes/find-elements.md)   |
+| Scenario      | Use when                                                          | Recipe                                                  |
+| ------------- | ----------------------------------------------------------------- | ------------------------------------------------------- |
+| Find elements | You're new and need to point CraftDriver at the element you want. | [Find Elements On The Page](./recipes/find-elements.md) |
 
 ## Test Structure
 
-| Scenario                  | Use when                                                                   | Recipe                                                                     |
-| ------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
-| Vitest browser lifecycle  | You want one browser per test file and a fresh page per test.              | [Use CraftDriver With Vitest Hooks](./recipes/vitest-browser-lifecycle.md) |
-| Login once, reuse session | Login UI is slow or noisy and most tests start signed in.                  | [Log In Once And Reuse The Session](./recipes/login-once-reuse-session.md) |
-| Multi-user flows          | You need Alice and Bob signed in at the same time without leaking cookies. | [Test Multi-User Workflows](./recipes/multi-user-contexts.md)              |
-| Page objects              | Selectors and steps are copy-pasted across tests and break together.       | [Organize Flows With Page Objects](./recipes/page-objects.md)              |
+| Scenario                       | Use when                                                                   | Recipe                                                                                |
+| ------------------------------ | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| Vitest browser lifecycle       | You want one browser per test file and a fresh page per test.              | [Use CraftDriver With Vitest Hooks](./recipes/vitest-browser-lifecycle.md)            |
+| Login once, reuse session      | Login UI is slow or noisy and most tests start signed in.                  | [Log In Once And Reuse The Session](./recipes/login-once-reuse-session.md)            |
+| Multi-user flows               | You need Alice and Bob signed in at the same time without leaking cookies. | [Test Multi-User Workflows](./recipes/multi-user-contexts.md)                         |
+| Page objects                   | Selectors and steps are copy-pasted across tests and break together.       | [Organize Flows With Page Objects](./recipes/page-objects.md)                         |
 
 ## App Behavior
 
@@ -50,3 +54,18 @@ For exact signatures, use the linked feature docs and the
 | Accessibility regression gate | CI should fail on serious page or component accessibility issues.               | [Run Accessibility Gates](./recipes/accessibility-gate.md)               |
 | 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) |
+
+## Electron
+
+Driving a packaged Electron desktop app. These use paths you adapt to your app
+repo rather than the hosted browser examples, and the mocking/deep-link recipes
+need main-process access (`electron: { mainProcess: true }`). See
+[Testing Electron Apps](./electron.md) for setup, drivers, and the security
+boundary.
+
+| Scenario                       | Use when                                                                   | Recipe                                                                                |
+| ------------------------------ | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| Electron app from another repo | Your packaged Electron app is built in one repo and tested from another.   | [Test An Electron App From Another Repo](./recipes/electron-app-from-another-repo.md) |
+| Electron native dialog         | A renderer flow opens an operating-system file, save, or message dialog.   | [Mock A Native Electron File Dialog](./recipes/electron-native-dialog.md)             |
+| Electron API mocking           | A flow calls `shell.openExternal`, `clipboard.writeText`, or similar.      | [Mock Electron APIs](./recipes/electron-mock-apis.md)                                 |
+| Electron deep link             | Your app registers a `myapp://` scheme and must handle links from the OS.  | [Test An Electron Deep Link](./recipes/electron-deep-link.md)                         |

package/docs/safari.md

@@ -0,0 +1,118 @@
+# Safari
+
+CraftDriver drives **real desktop Safari on macOS** through W3C WebDriver
+Classic.
+
+## One-time setup
+
+Safari's driver (`safaridriver`) ships with macOS — **nothing to install or
+download**. You only have to turn on automation **once per machine**:
+
+```bash
+safaridriver --enable
+```
+
+This is the single prerequisite.
+
+CraftDriver never runs `--enable` for you. If automation isn't enabled, a
+launch fails immediately with that exact remedy rather than hanging.
+
+## Quick start
+
+```typescript
+import { Browser } from 'craftdriver';
+
+const browser = await Browser.launch({ browserName: 'safari' });
+await browser.navigateTo('http://127.0.0.1:8080/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').toHaveText('Welcome back, alice!');
+await browser.quit();
+```
+
+Same API as every other browser — locators, actions, assertions, and
+auto-waiting all work unchanged.
+
+## What works
+
+Navigation, locators, and element queries · click / fill / clear / keyboard /
+desktop mouse · `evaluate()` (sync & async JS) · frames and iframes · window &
+popup enumeration · **imperative dialogs** (`getAlertText` / `acceptAlert` /
+`dismissAlert` / `sendAlertText`) · viewport and element screenshots · cookies
+and storage (via the standard Classic cookie endpoints) · accessibility checks.
+
+## What isn't supported
+
+Safari exposes no WebDriver BiDi endpoint, so everything event- or
+BiDi-driven is unavailable — and each of these throws a clear
+[`UNSUPPORTED`](./error-codes.md) error immediately, never a silent hang:
+
+- network mocking / interception and request/response waits
+- console & JavaScript-error capture, tracing
+- BiDi user contexts and emulation (permissions, geolocation,
+  locale/timezone, offline, color-scheme)
+- init/preload scripts and the virtual clock
+- event-driven dialogs (`onDialog` / `waitForDialog`) — use the imperative
+  methods above
+- full-page screenshots and `openPage()`
+- CraftDriver-managed downloads (`waitForDownload`)
+
+Desktop Safari is also **not** iPhone/iPad Safari — there is no mobile or
+touch emulation.
+
+## Limitations to plan around
+
+- **macOS-only.** There is no Safari for Linux or Windows, and none is coming.
+  Trying to launch Safari off macOS throws `UNSUPPORTED`.
+- **Headed only.** No headless mode — every launch opens a visible automation
+  window (with a purple banner). Don't interact with it while a test runs.
+  Setting `HEADLESS=true` with Safari is rejected up front.
+- **Serial only.** Only one Safari WebDriver session can be active on a Mac at
+  a time. A second concurrent launch is refused with an actionable error
+  (never a hang) — run Safari tests serially.
+
+## Safari Technology Preview
+
+STP ships its own `safaridriver`; point `SafariService` at it. This is also
+the one way to get a **second concurrent session** on one Mac — stable Safari
+and STP each run one session at the same time.
+
+```typescript
+import { Browser, SafariService } from 'craftdriver';
+
+const browser = await Browser.launch({
+  browserName: 'safari',
+  safariService: new SafariService({
+    binaryPath: '/Applications/Safari Technology Preview.app/Contents/MacOS/safaridriver',
+  }),
+});
+```
+
+Enable automation once for STP too: `/Applications/Safari Technology Preview.app/Contents/MacOS/safaridriver --enable`.
+
+## Running Safari tests
+
+Run Safari **serially** — one session at a time. With Vitest that's
+`--maxWorkers=1`:
+
+```bash
+vitest run --maxWorkers=1
+```
+
+Keep it headed (don't set `HEADLESS`), on macOS with Remote Automation enabled.
+In CI, use a macOS runner; parallelism across Safari needs **separate macOS
+hosts**.
+
+## Troubleshooting
+
+| Symptom | Fix |
+| --- | --- |
+| `You must enable 'Allow remote automation'…` | Run `safaridriver --enable` once (see [setup](#one-time-setup)). |
+| Second launch fails while one session is open | Expected — Safari is serial. Serialize your tests, or use STP for a second session. |
+| `Could not find 'safaridriver'` | You're not on macOS, or Safari is missing. For a non-standard install, set `CRAFTDRIVER_SAFARIDRIVER_PATH` or `SafariService({ binaryPath })`. |
+
+## See also
+
+- [Driver Configuration → Safari](./driver-configuration.md#safari-macos-driver-ships-with-the-browser) — the no-download driver-resolution chain.
+- [WebDriver Standards](./standards.md#safari-is-classic-only) — why Safari is Classic-only.

package/docs/standards.md

@@ -16,6 +16,19 @@ That protocol choice is the center of the project. CraftDriver tries to provide
 
 CraftDriver picks the practical protocol path behind a single public API. You call `browser.click()`, `browser.navigateTo()`, `browser.network.mock()`, or `browser.startTrace()`; the library handles the transport details.
 
+### Safari is Classic-only
+
+`browserName: 'safari'` always uses WebDriver Classic and never negotiates
+`webSocketUrl`. This isn't a temporary gap CraftDriver plans to close — Apple
+does not currently document a supported WebDriver BiDi endpoint for Safari or
+Safari Technology Preview, so there's no BiDi transport to opt into. CraftDriver
+rejects `enableBiDi: true` for Safari with a clear `UNSUPPORTED` error before
+launch rather than silently downgrading, and every BiDi-only method (network,
+logs, tracing, contexts, permissions/geolocation/emulation, full-page
+screenshots, event-driven dialogs) fails the same way when called on a Safari
+session. See the [Safari guide](./safari.md) for what remains available on
+Classic.
+
 ## Why It Matters
 
 Standards-based automation gives projects a few useful properties:

package/docs/why-craftdriver.md

@@ -5,7 +5,7 @@ CraftDriver is for writing boringly reliable automation against real browsers, w
 ## What It Cares About
 
 - 🍺 **Focused Node.js API** - browser automation without a giant framework around it.
-- 🧭 **Real browsers** - drives installed Chrome, Chromium, and Firefox instead of patched browser engine builds.
+- 🧭 **Real browsers** - drives installed Chrome, Chromium, and Firefox instead of patched browser engine builds, plus real ([Safari on macOS](./safari.md)).
 - 🌐 **Standards that age well** - W3C WebDriver standards stay stable while browser-private protocols change.
 - 🚦 **Readable, auto-waited flows** - role, label, text, test id, CSS, XPath, click, fill, and expect.
 - 📡 **Network control** - mock, block, intercept, and wait for browser requests and responses.

package/docs/zero-config-drivers.md

@@ -62,3 +62,15 @@ Manual configuration is useful when:
   [Driver Configuration → Browser Binary Configuration](./driver-configuration.md#browser-binary-configuration)
 
 See [Driver Configuration](./driver-configuration.md) for the full reference.
+
+## Safari: nothing to resolve, nothing to download
+
+The auto-download model above doesn't apply to `browserName: 'safari'`.
+`safaridriver` ships as part of macOS/Safari itself — there's no version to
+match, no binary to fetch, and no cache to warm. CraftDriver only ever
+**locates** the driver Apple already installed. The single prerequisite is
+turning automation on once per Mac with `safaridriver --enable`.
+
+See the [**Safari guide**](./safari.md) for setup and capabilities, and
+[Driver Configuration → Safari](./driver-configuration.md#safari-macos-driver-ships-with-the-browser)
+for the driver-resolution chain.