craftdriver 1.4.0 → 1.5.0

package/dist/lib/webelement.js

@@ -1,6 +1,106 @@
 import { HttpClient } from './http.js';
 export const W3C_ELEMENT_KEY = 'element-6066-11e4-a52e-4f735466cecf';
 export const LEGACY_ELEMENT_KEY = 'ELEMENT';
+/**
+ * W3C-compatible "is element displayed" algorithm, executed via
+ * `POST /execute/sync`. Faithfully reproduces the behavior of Selenium's
+ * `bot.dom.isShown_` (the atom chromedriver and geckodriver's native
+ * `is displayed` commands are compiled from), so results match the browsers
+ * that currently answer via the legacy `/element/{id}/displayed` endpoint —
+ * while also working on Safari, whose command table omits that endpoint.
+ *
+ * Written in ES5-compatible style (plain `function`s, `var`, `for` loops) to
+ * match the other scripts sent to `/execute/sync` in this codebase and to run
+ * safely across every supported Classic remote end. Receives the element as
+ * `arguments[0]` and returns a boolean.
+ *
+ * Rules, each mirroring the corresponding `bot.dom` behavior:
+ *  - `<input type="hidden">` and `<noscript>` are never shown.
+ *  - `display:none` on the element OR any ancestor hides it. `display` is not
+ *    inherited, so the ancestor chain must be walked explicitly.
+ *  - `visibility:hidden`/`collapse` hides it. `visibility` IS inherited, and a
+ *    descendant may override an ancestor back to `visible`, so we check only the
+ *    element's OWN computed value (getComputedStyle already resolves
+ *    inheritance) — this both matches `bot.dom` and is more correct than walking
+ *    the chain for visibility.
+ *  - No positive-area box hides it, unless a child has one (zero-size wrappers)
+ *    or it is a `<br>` (a legitimately zero-width line break). Mirrors
+ *    `bot.dom.positiveSize_`.
+ *  - Being clipped out of view by an `overflow:hidden` ancestor hides it,
+ *    matching `bot.dom.OverflowState.HIDDEN`. An element scrolled out of a
+ *    `scroll`/`auto` ancestor is still considered shown (it can be scrolled
+ *    into view — `bot.dom.OverflowState.SCROLL`), so it is not treated as
+ *    hidden here.
+ */
+const IS_DISPLAYED_ATOM = `
+var elem = arguments[0];
+if (!elem || elem.nodeType !== 1) { return false; }
+
+var win = elem.ownerDocument.defaultView || window;
+function style(e, prop) {
+  var cs = win.getComputedStyle(e, null);
+  return cs ? cs.getPropertyValue(prop) : '';
+}
+
+// <input type="hidden"> is never shown (bot.dom.isShown_).
+var tag = elem.tagName ? elem.tagName.toUpperCase() : '';
+if (tag === 'INPUT' && (elem.type || '').toLowerCase() === 'hidden') { return false; }
+// <noscript> is not rendered.
+if (tag === 'NOSCRIPT') { return false; }
+
+// display:none on the element or any ancestor hides it. display is NOT
+// inherited, so the whole chain must be checked (bot.dom.displayed_).
+var node = elem;
+while (node && node.nodeType === 1) {
+  if (style(node, 'display') === 'none') { return false; }
+  node = node.parentElement;
+}
+
+// visibility:hidden/collapse hides it. visibility IS inherited but overridable
+// by descendants, so checking the element's own computed value is correct.
+var vis = style(elem, 'visibility');
+if (vis === 'hidden' || vis === 'collapse') { return false; }
+
+// An element with no positive-area box is not shown, unless a child has one
+// (zero-size wrapper) or it is a <br> (bot.dom.positiveSize_).
+function positiveSize(e) {
+  var r = e.getBoundingClientRect();
+  if (r.width > 0 && r.height > 0) { return true; }
+  if (e.tagName && e.tagName.toUpperCase() === 'BR') { return true; }
+  var kids = e.childNodes;
+  for (var i = 0; i < kids.length; i++) {
+    var k = kids[i];
+    if (k.nodeType === 1 && positiveSize(k)) { return true; }
+  }
+  return false;
+}
+if (!positiveSize(elem)) { return false; }
+
+// Clipped out of view by an overflow:hidden ancestor => hidden
+// (bot.dom.OverflowState.HIDDEN). scroll/auto ancestors are treated as shown
+// (OverflowState.SCROLL — scrollable into view). position:fixed escapes
+// ancestor clipping, so skip the check for fixed elements.
+if (style(elem, 'position') !== 'fixed') {
+  var rect = elem.getBoundingClientRect();
+  var parent = elem.parentElement;
+  while (parent) {
+    var ox = style(parent, 'overflow-x');
+    var oy = style(parent, 'overflow-y');
+    if (ox === 'hidden' || oy === 'hidden' || ox === 'clip' || oy === 'clip') {
+      var pr = parent.getBoundingClientRect();
+      var clippedX = (ox === 'hidden' || ox === 'clip') &&
+        (rect.right <= pr.left || rect.left >= pr.right);
+      var clippedY = (oy === 'hidden' || oy === 'clip') &&
+        (rect.bottom <= pr.top || rect.top >= pr.bottom);
+      if (clippedX || clippedY) { return false; }
+    }
+    if (style(parent, 'position') === 'fixed') { break; }
+    parent = parent.parentElement;
+  }
+}
+
+return true;
+`;
 export class WebElement {
     endpoint;
     sessionId;
@@ -43,10 +143,26 @@ export class WebElement {
         return { [W3C_ELEMENT_KEY]: this.elementId, [LEGACY_ELEMENT_KEY]: this.elementId };
     }
     async isDisplayed() {
+        // The legacy `GET /element/{id}/displayed` endpoint is a pre-W3C JSON Wire
+        // Protocol command. chromedriver/geckodriver still accept it for backward
+        // compatibility, but it was never part of W3C WebDriver Classic and is
+        // absent from Apple's Safari 12+ command table. We therefore compute
+        // displayedness the same way every real driver does under the hood: by
+        // executing the well-known "displayedness atom" via the standard
+        // `POST /execute/sync` command, which every Classic remote end supports.
+        //
+        // The script below mirrors Selenium's `bot.dom.isShown_`
+        // (selenium/javascript/atoms/dom.js) — the exact algorithm chromedriver's
+        // and geckodriver's `is displayed` implementations are compiled from, and
+        // the same one wdio/Playwright rely on. Keeping it byte-for-byte faithful
+        // in behavior is what preserves existing Chrome/Chromium/Firefox results;
+        // this is a protocol change, not a semantics change. Each rule is annotated
+        // with the `bot.dom` behavior it reproduces so a reviewer can verify it.
         const client = new HttpClient(this.endpoint);
         const res = await client.send({
-            method: 'GET',
-            path: `/session/${this.sessionId}/element/${this.elementId}/displayed`,
+            method: 'POST',
+            path: `/session/${this.sessionId}/execute/sync`,
+            body: { script: IS_DISPLAYED_ATOM, args: [this.toJSON()] },
         });
         const value = res?.value ?? res;
         return Boolean(value);

package/dist/lib/webelement.js.map

@@ -1 +1 @@
-{"version":3,"file":"webelement.js","sourceRoot":"","sources":["../../src/lib/webelement.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"webelement.js","sourceRoot":"","sources":["../../src/lib/webelement.ts"],"names":[],"mappings":"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"}

package/docs/api-reference.md

@@ -153,6 +153,8 @@ Handle stable CraftDriver errors or customize browser driver services.
 | `ChromeServiceOptions` | type | — | [getting-started](getting-started.md) |
 | `FirefoxService` | class | — | [getting-started](getting-started.md) |
 | `FirefoxServiceOptions` | type | — | [getting-started](getting-started.md) |
+| `SafariService` | class | — | [getting-started](getting-started.md) |
+| `SafariServiceOptions` | type | — | [getting-started](getting-started.md) |
 
 ## Other Exports
 
@@ -166,4 +168,4 @@ Exports that are public but not yet assigned to a feature group.
 | `ElectronRemoteOptions` | type | Extra context ElectronRemote needs beyond the inspector endpoint. | [electron](electron.md) |
 | `PageMatcher` | type | Selects a top-level page by `url` and/or `title` for {@link Browser.waitForPage}. A string matches as a substring; a `RegExp` is tested. When both fields are given, both must match. | [browser-api](browser-api.md) |
 
-Total exports: **82**.
+Total exports: **84**.

package/docs/driver-configuration.md

@@ -279,3 +279,57 @@ const browser = await Browser.launch({
   }),
 });
 ```
+
+## Safari (macOS): driver ships with the browser
+
+Everything above (steps 1–9, the download chain, the TTL cache) resolves
+**chromedriver**/**geckodriver** — binaries craftdriver may fetch and cache on
+disk. `browserName: 'safari'` doesn't fit that model at all: Apple ships
+`safaridriver` as part of macOS/Safari itself, so there is no download, no
+version-matching problem, and no cache to warm. This page covers only driver
+**resolution**; for setup (`safaridriver --enable`), capabilities, limitations,
+and Safari Technology Preview, see the [**Safari guide**](./safari.md).
+
+`SafariService` resolves the `safaridriver` binary through its own chain —
+first match wins, and none of these steps ever triggers a network call:
+
+| Step | Source |
+|---|---|
+| 1 | `binaryPath` passed to `new SafariService({ binaryPath })` |
+| 2 | `CRAFTDRIVER_SAFARIDRIVER_PATH` env var |
+| 3 | `CRAFTDRIVER_DRIVER_PATH` env var (generic fallback, shared with Chrome/Firefox) |
+| 4 | `/usr/bin/safaridriver` (the fixed system location on macOS) |
+| 5 | `safaridriver` on `PATH` |
+| 6 | a clear, actionable error if nothing resolves — craftdriver never downloads a `safaridriver` |
+
+To pin **Safari Technology Preview**, point `binaryPath` at its bundled driver
+(`/Applications/Safari Technology Preview.app/Contents/MacOS/safaridriver`) —
+see the [Safari guide](./safari.md#safari-technology-preview).
+
+### Extra `safaridriver` arguments
+
+`SafariService` accepts `args`, passed through verbatim after `--port <port>`.
+The most useful one is `--diagnose`, which turns on `safaridriver`'s
+diagnostic logging (written under `~/Library/Logs/com.apple.WebDriver/`) —
+handy when a Safari session fails to start and the driver's own stdout/stderr
+isn't enough to tell why:
+
+```typescript
+const browser = await Browser.launch({
+  browserName: 'safari',
+  safariService: new SafariService({ args: ['--diagnose'] }),
+});
+```
+
+### What's different from Chrome/Firefox here
+
+- No `CRAFTDRIVER_CACHE_DIR`, `CRAFTDRIVER_DRIVER_TTL`, or `CRAFTDRIVER_OFFLINE`
+  behavior applies to Safari — there's nothing cached or downloaded to
+  configure.
+- No browser-binary resolution chain (`browserPath` / `CRAFTDRIVER_CHROME_PATH`-
+  style) exists for Safari — you select which Safari build's driver to use via
+  `SafariService.binaryPath` directly, as shown above, not via a separate
+  browser-path option.
+- `enableBiDi: true` is rejected before launch — Safari has no documented
+  WebDriver BiDi endpoint to negotiate. See
+  [WebDriver Standards → Safari is Classic-only](./standards.md#safari-is-classic-only).

package/docs/getting-started.md

@@ -75,29 +75,49 @@ returns the same `Page` the shortcuts would target.
 
 ## Launch Options
 
+The simplest launch runs Chrome:
+
+```typescript
+const browser = await Browser.launch(); // Chrome by default
+```
+
+Pick a browser with `browserName`:
+
 ```typescript
-// Chrome (default)
 const browser = await Browser.launch({
-  browserName: 'chrome', // 'chrome' | 'chromium' | 'firefox'
+  browserName: 'firefox', // 'chrome' | 'chromium' | 'firefox' | 'safari'
   storageState: './session.json', // optional: pre-load saved session state
 });
+```
+
+To switch browsers from an environment variable in your own tests, read it
+yourself and pass it to `browserName` — craftdriver doesn't read any browser
+env var for you:
 
-// Firefox
+```typescript
 const browser = await Browser.launch({
-  browserName: 'firefox',
+  browserName: process.env.BROWSER_NAME ?? 'chrome',
 });
 ```
 
-### Running tests on Firefox
+### Safari
 
-Set `BROWSER_NAME=firefox` before running your test command:
+Safari runs on macOS with the same API, as a smaller Classic-only tier. Enable
+automation once (`safaridriver --enable`) and launch:
 
-```bash
-BROWSER_NAME=firefox npx vitest run
-# or use the built-in script if your package.json has it:
-npm run test:firefox
+```typescript
+const browser = await Browser.launch({ browserName: 'safari' });
+await browser.navigateTo('http://127.0.0.1:8080/login.html');
+await browser.fill('#username', 'alice');
+await browser.click('#submit');
+await browser.quit();
 ```
 
+Safari is macOS-only, headed, and serial (one session at a time), and doesn't
+support BiDi-only features (network mocking, tracing, emulation, …). See the
+[**Safari guide**](./safari.md) for the full picture — setup, what works, and
+Safari Technology Preview.
+
 ### Custom WebDriver binary or port
 
 `Browser.launch()` resolves the driver binary automatically. To pin a

package/docs/index.md

@@ -33,7 +33,7 @@ features:
     details: CLI, MCP server, and assistant rules are there when you want coding agents to drive the browser too.
 ---
 
-## One Install
+## Quick Start
 
 ```bash
 npm install craftdriver --save-dev

package/docs/public/examples/displayed.html

@@ -0,0 +1,86 @@
+<!doctype html>
+<html lang="en">
+
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Craftdriver Displayedness</title>
+  <style>
+    body {
+      font-family: system-ui, Arial, sans-serif;
+      margin: 1rem;
+    }
+
+    /* An ancestor hidden via display:none. Its descendant #hidden-by-ancestor
+       has no style of its own but must count as not displayed. */
+    #display-none-ancestor {
+      display: none;
+    }
+
+    /* Own visibility:hidden. */
+    #visibility-hidden {
+      visibility: hidden;
+    }
+
+    /* Zero-sized content: no rendered box, overflow clipped. */
+    #zero-size {
+      width: 0;
+      height: 0;
+      overflow: hidden;
+    }
+
+    /* A scrollable-but-CLIPPING (overflow:hidden) container. The child at the
+       bottom is scrolled out of the container's viewport, so it is clipped and
+       not displayed (bot.dom OverflowState.HIDDEN). */
+    #clip-container {
+      width: 120px;
+      height: 80px;
+      overflow: hidden;
+      border: 1px solid #ccc;
+    }
+
+    #clip-spacer {
+      height: 400px;
+    }
+  </style>
+</head>
+
+<body>
+  <div class="container">
+    <!-- Plainly visible baseline. -->
+    <div id="visible-el">I am visible</div>
+
+    <!-- Hidden by a display:none ancestor. -->
+    <div id="display-none-ancestor">
+      <div id="hidden-by-ancestor">Hidden because my ancestor is display:none</div>
+    </div>
+
+    <!-- Own display:none. -->
+    <div id="display-none-self" style="display: none">Hidden by my own display:none</div>
+
+    <!-- Own visibility:hidden. -->
+    <div id="visibility-hidden">Hidden by my own visibility:hidden</div>
+
+    <!-- Visibility hidden ancestor with a visible descendant override:
+         the child sets visibility:visible and MUST count as displayed. -->
+    <div style="visibility: hidden">
+      <div id="visibility-visible-override" style="visibility: visible">
+        Visible again despite hidden ancestor
+      </div>
+    </div>
+
+    <!-- Zero-sized content. -->
+    <div id="zero-size">unrenderable</div>
+
+    <!-- A <br> is legitimately zero-width but should count as displayed. -->
+    <br id="line-break" />
+
+    <!-- Element scrolled out of an overflow:hidden container's viewport. -->
+    <div id="clip-container">
+      <div id="clip-spacer"></div>
+      <div id="scrolled-out-of-clip">I am below the clipped fold</div>
+    </div>
+  </div>
+</body>
+
+</html>

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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "craftdriver",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Modern WebDriver automation library for NodeJS",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,6 +17,7 @@
     "test:firefox": "BROWSER_NAME=firefox HEADLESS=true vitest run --maxWorkers=2",
     "test:chrome": "BROWSER_NAME=chrome vitest run",
     "test:chromium": "BROWSER_NAME=chromium vitest run",
+    "test:safari": "BROWSER_NAME=safari vitest run tests/safari.test.ts --maxWorkers=1",
     "test:recipes": "HEADLESS=true vitest run --config vitest.recipes.config.ts",
     "test:electron": "vitest run --config vitest.electron.config.ts",
     "bench": "HEADLESS=true vitest run --config vitest.perf.config.ts",
@@ -40,6 +41,7 @@
     "firefox",
     "chrome",
     "chromium",
+    "safari",
     "electron",
     "electron-testing",
     "desktop-app-testing",

package/skills/craftdriver/SKILL.md

@@ -36,7 +36,10 @@ break the moment markup shifts.
 4. BiDi features (`network`, `logs`, tracing, init scripts, true load
    events) work out of the box — `enableBiDi` defaults to `true`. They only
    break if you explicitly pass `enableBiDi: false`; the error code on the
-   wrong transport is `UNSUPPORTED`.
+   wrong transport is `UNSUPPORTED`. Exception: `browserName: 'safari'`
+   defaults `enableBiDi` to `false` and rejects `true` — Safari is
+   Classic-only (macOS, headed, one session at a time). See
+   [docs/safari.md](../../docs/safari.md).
 5. Tests fetch from the example server. Start it in a separate
    terminal: `npm run examples:start` before `npm test`.
 

package/skills/craftdriver/cheatsheet.md

@@ -10,11 +10,14 @@ list.
 import { Browser } from 'craftdriver';
 
 const browser = await Browser.launch({
-  browserName: 'chrome',   // 'chrome' | 'chromium' | 'firefox'
+  browserName: 'chrome',   // 'chrome' | 'chromium' | 'firefox' | 'safari'
   headless: true,
   // enableBiDi defaults to true — network / logs / tracing / init scripts
   // all need it, so only set enableBiDi: false if you must disable it.
 });
+// 'safari' is macOS-only, headed only (no `headless`),
+// one session at a time, WebDriver Classic only (enableBiDi is rejected).
+// See docs/safari.md.
 try {
   await browser.navigateTo('https://example.com');
   // ...