craftdriver 1.3.0 → 1.5.0

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/electron.md

@@ -0,0 +1,419 @@
+# Testing Electron Apps
+
+CraftDriver can launch a packaged Electron app and test its **renderer** with
+the same `Browser` API used for web pages: locators, clicks, form fills,
+assertions, viewport screenshots, element screenshots, `evaluate()`, and
+page/window helpers.
+
+For apps you control, CraftDriver can also access the main process and replace
+native open, save, and message dialogs with deterministic test results.
+
+## Quick Start
+
+Launch the packaged executable and pass the Electron version used by the app:
+
+```ts
+import { Browser, By } from 'craftdriver';
+
+const browser = await Browser.launch({
+  electron: {
+    appBinaryPath: '/path/to/YourApp',
+    version: '43.1.0',
+  },
+});
+
+try {
+  await browser.find(By.testId('app-title')).expect().toHaveText('Your App');
+  await browser.click(By.testId('nav-settings'));
+  await browser.fill(By.testId('name'), 'Ada');
+  await browser.click(By.testId('save'));
+  await browser.find(By.testId('status')).expect().toHaveText('Saved');
+} finally {
+  await browser.quit();
+}
+```
+
+Electron launches default to Classic WebDriver. The app loads its own UI, so you
+usually do **not** call `navigateTo()`.
+
+For a fuller project layout, see
+[Test An Electron App From Another Repo](./recipes/electron-app-from-another-repo.md).
+
+## Mock Native Dialogs
+
+Native operating-system dialogs are outside the DOM, so WebDriver cannot click
+their buttons or select their files. Mock the Electron main-process method before
+the renderer action that opens it:
+
+```ts
+const browser = await Browser.launch({
+  electron: {
+    appBinaryPath: '/path/to/YourApp',
+    version: '43.1.0',
+    mainProcess: true,
+  },
+});
+
+const openDialog = await browser.electron.mockDialog('showOpenDialog', {
+  canceled: false,
+  filePaths: ['/fixtures/invoice.pdf'],
+});
+
+await browser.click(By.testId('choose-file'));
+await browser.find(By.testId('selected-file')).expect().toHaveText('/fixtures/invoice.pdf');
+
+expect(await openDialog.getCallCount()).toBe(1);
+expect(await openDialog.getCalls()).toEqual([
+  {
+    options: {
+      title: 'Choose an invoice',
+      properties: ['openFile'],
+    },
+  },
+]);
+
+await openDialog.restore();
+```
+
+`mockDialog()` supports Electron's asynchronous `showOpenDialog`,
+`showSaveDialog`, and `showMessageBox` methods. The supplied result has the same
+shape as the real Electron result:
+
+```ts
+await browser.electron.mockDialog('showSaveDialog', {
+  canceled: false,
+  filePath: '/fixtures/export.csv',
+});
+
+await browser.electron.mockDialog('showMessageBox', {
+  response: 1,
+  checkboxChecked: false,
+});
+```
+
+The returned mock provides `getCalls()`, `getCallCount()`, `clearCalls()`, and
+`restore()`. CraftDriver also restores active dialog mocks during
+`browser.quit()`. Call records contain the dialog options; Electron's optional
+parent `BrowserWindow` is intentionally excluded because it cannot cross the
+test-process boundary.
+
+See [Mock A Native Electron File Dialog](./recipes/electron-native-dialog.md)
+for the complete renderer, preload, main-process, and test flow.
+
+## Mock Any Electron API
+
+`mockDialog()` is a typed convenience over a general primitive: `mock()` replaces
+**any** `electron.<api>.<fn>` main-process method with a scripted return value and
+a call recorder. Reach for it when your app calls into Electron beyond dialogs —
+`shell.openExternal`, `app.getPath`, `safeStorage.encryptString`, `clipboard.*`,
+and so on.
+
+```ts
+// Stop a "Open in browser" button from actually launching a browser, and assert
+// the app asked to open the right URL — without leaving the test machine.
+const openExternal = await browser.electron.mock('shell', 'openExternal', true);
+
+await browser.click(By.testId('open-docs'));
+
+expect(await openExternal.getCalls()).toEqual([{ args: ['https://example.com/docs'] }]);
+await openExternal.restore();
+```
+
+The returned mock mirrors the dialog mock: `getCalls()` (each call is
+`{ args: [...] }`), `getCallCount()`, `clearCalls()`, `mockReturnValue(value)` to
+re-script the return, and `restore()`. Active mocks are also restored on
+`browser.quit()`.
+
+Notes:
+
+- The scripted value is returned **as-is**, not wrapped in a Promise, so it works
+  for both synchronous methods (`app.getName()`) and `await`ed asynchronous ones
+  (`safeStorage`-style APIs). For an async method, pass the already-resolved value.
+- Recorded call arguments and the return value must be JSON-serializable; complex
+  values (a `BrowserWindow`, a `Buffer`) are recorded as a descriptive placeholder
+  rather than crossing the process boundary.
+- Mocking the same `api.fn` twice throws until you `restore()` the first mock.
+
+See [Mock Electron APIs](./recipes/electron-mock-apis.md) for `shell.openExternal`
+and `clipboard.writeText` flows end to end.
+
+## Test Deep Links (Custom Protocols)
+
+If your app registers a custom URL scheme (`myapp://…`), `triggerDeeplink()` opens
+one against the **running** app exactly as the OS would when a browser, email, or
+another app hands off the link — so your real `open-url` / `second-instance`
+handler runs. It is fire-and-forget: it resolves once the OS launcher is spawned,
+so assert the effect through your app afterwards.
+
+```ts
+await browser.electron.triggerDeeplink('myapp://open?file=test.txt');
+
+// Assert however your app surfaces the link — a renderer element, a main-process
+// log, or state read back with executeMain.
+await browser.find(By.testId('deeplink-result')).expect().toHaveText('myapp://open?file=test.txt');
+```
+
+Your **app** must:
+
+- register the protocol — `app.setAsDefaultProtocolClient('myapp')` plus the
+  packager's protocol declaration (electron-builder `protocols:` / Forge
+  `protocols`), which writes the macOS `CFBundleURLTypes` and Windows registry
+  entries; and
+- hold the single-instance lock (`app.requestSingleInstanceLock()`) and read the
+  URL from `open-url` (macOS) and `second-instance` argv (Windows, Linux).
+
+Platform notes:
+
+- **macOS** delivers the URL to the running instance via `open-url`; no extra
+  routing is needed. The bundle must be known to LaunchServices (installed, or
+  registered with `lsregister`).
+- **Windows / Linux** would launch a *second* process; craftdriver appends the
+  running app's user-data dir as a `userData` query parameter (auto-detected via
+  the main process) so the single-instance lock routes the link to the test
+  instance. Windows also needs `appBinaryPath` set on launch.
+- Only custom protocols are accepted; `http`/`https`/`file` throw `INVALID_ARGUMENT`.
+
+See [Test An Electron Deep Link](./recipes/electron-deep-link.md) for the complete
+app + test flow.
+
+### Can this test a production build?
+
+Yes, when that packaged build accepts Electron's `--inspect` argument. Electron
+controls this with the `EnableNodeCliInspectArguments` fuse, which is enabled by
+default. CraftDriver launches the existing executable with a local,
+session-scoped inspector and replaces the dialog function in memory. It does not
+patch the executable or require a test hook in your application code. Code
+signing by itself does not prevent this.
+
+Security-hardened applications often disable this fuse. CraftDriver cannot turn
+it back on after packaging or signing, and renderer-only automation will continue
+to work but `mock()`, `mockDialog()`, and `executeMain()` will not. When that
+happens CraftDriver reads the fuse straight from the packaged binary and the error
+says so precisely — `ELECTRON_MAIN_UNAVAILABLE` with `detail.fuseStatus:
+'disabled'` and the fix below — instead of a generic "inspector unreachable".
+Build a separate test artifact with the fuse enabled **before code signing**:
+
+```js
+const { FusesPlugin } = require('@electron-forge/plugin-fuses');
+const { FuseV1Options, FuseVersion } = require('@electron/fuses');
+
+module.exports = {
+  // ...your normal Forge configuration
+  plugins: [
+    new FusesPlugin({
+      version: FuseVersion.V1,
+      [FuseV1Options.EnableNodeCliInspectArguments]: true,
+    }),
+  ],
+};
+```
+
+For another packager, use `@electron/fuses` in its pre-sign packaging hook and
+set `FuseV1Options.EnableNodeCliInspectArguments` to `true`. Keep the production
+artifact hardened if that is your security policy; the test artifact should be
+stored and distributed like other internal test tooling.
+
+This is build instrumentation, not application instrumentation. Your app should
+continue to use Electron normally, for example `dialog.showOpenDialog(...)` in an
+IPC handler. One limitation is that CraftDriver replaces the method on
+`electron.dialog`; if your app copies that function into another variable before
+the test installs the mock, the copied reference cannot be replaced. Prefer
+calling `dialog.showOpenDialog(...)` at the point of use.
+
+## Package The App First
+
+`appBinaryPath` must point to the packaged app executable. Do not point it at an
+Electron source directory, a `.app` bundle root, a `.dmg`, or an installer.
+
+Typical executable paths:
+
+| OS      | `appBinaryPath`                                 |
+| ------- | ----------------------------------------------- |
+| macOS   | `YourApp.app/Contents/MacOS/YourApp`            |
+| Windows | `YourApp.exe`                                   |
+| Linux   | the unpacked binary, e.g. `yourapp` (lowercase) |
+
+If you point chromedriver at an unpackaged app directory, Electron can start as
+a plain Chromium window and your app UI will not load. Package with your normal
+Electron Forge, electron-builder, or release-build command first.
+
+## Match The Driver To Electron
+
+Electron bundles its own Chromium. The chromedriver used for the test must match
+that bundled Chromium major, not the Chrome installed on the machine.
+
+The recommended setup is:
+
+```ts
+await Browser.launch({
+  electron: {
+    appBinaryPath: '/path/to/YourApp',
+    version: '43.1.0',
+  },
+});
+```
+
+With `version`, CraftDriver maps the Electron version to the bundled Chromium
+major and downloads a matching Chrome-for-Testing chromedriver.
+
+Other valid driver sources:
+
+- `electron.chromedriverPath` when you already have a matching chromedriver.
+- `CRAFTDRIVER_ELECTRON_CHROMEDRIVER_PATH` for a CI-wide override.
+- `electron-chromedriver` installed in the test project.
+- macOS packaged app detection. If you omit `version`, CraftDriver can read the
+  Electron version from a packaged `.app` and resolve the driver from that.
+
+For Linux and Windows packaged apps, pass `version` or an explicit driver path.
+CraftDriver does not use a system Chrome driver for Electron, because it would
+often be the wrong Chromium version.
+
+Version-based driver resolution works for Electron majors known to CraftDriver
+and Chromium majors published by Chrome for Testing. If your app uses an older,
+newer, or custom Electron/Chromium build, use `chromedriverPath`.
+
+## Windows And Splash Screens
+
+Many desktop apps open a splash window first, then replace it with the main
+window. Wait for the real window by title or URL:
+
+```ts
+const browser = await Browser.launch({
+  electron: { appBinaryPath: '/path/to/YourApp', version: '43.1.0' },
+});
+
+const main = await browser.waitForPage({ title: /Your App/ });
+await main.find(By.testId('app-root')).expect().toBeVisible();
+```
+
+The returned `Page` is bound to that window. In Electron's default Classic mode,
+`waitForPage({ title | url })` also makes the matched window current, so
+top-level calls such as `browser.find(...)` and `browser.click(...)` target it.
+
+Use `browser.pages()` to list open top-level windows. If the current splash
+window closes and exactly one window remains, `browser.activePage()` recovers to
+that remaining window. If several windows remain, select one explicitly with
+`waitForPage()` or `pages()`.
+
+## Electron API Differences
+
+Most renderer-facing APIs work the same way they do for browser tests. The main
+differences are launch shape and protocol defaults.
+
+Use these Electron-specific launch options:
+
+```ts
+await Browser.launch({
+  electron: {
+    appBinaryPath: '/path/to/YourApp',
+    version: '43.1.0',
+    args: ['--lang=de-DE'],
+  },
+});
+```
+
+Do not combine `electron` with browser-only launch options:
+
+| Browser option                     | Electron alternative                                                                               |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `browserName`                      | Omit it; Electron uses its bundled Chromium.                                                       |
+| `browserPath`                      | Use `electron.appBinaryPath`.                                                                      |
+| top-level `args`                   | Use `electron.args`.                                                                               |
+| `chromeService` / `firefoxService` | Use `electronService` only when custom driver service settings are needed.                         |
+| `mobileEmulation`                  | Not applicable to desktop Electron apps; use `setViewportSize()` for responsive renderer coverage. |
+
+Electron is also always a GUI app in this V1 flow. CraftDriver does not add
+headless flags for Electron, even if `HEADLESS=true`.
+
+## BiDi-Only Features
+
+Electron defaults to Classic WebDriver because that keeps the packaged app's
+initial UI loaded and ready to test.
+
+Some CraftDriver APIs require BiDi. For Electron, you must launch with
+`enableBiDi: true` before using them:
+
+- `browser.logs`
+- `browser.network`, `waitForRequest()`, and `waitForResponse()`
+- `browser.startTrace()`
+- `browser.openPage()`
+- `browser.newContext()`, `browser.contexts()`, and `browser.defaultContext`
+- `browser.addInitScript()`
+- `browser.grantPermissions()`, `setGeolocation()`, and `emulate()`
+- `browser.screenshot({ fullPage: true })`
+
+BiDi has an Electron-specific caveat: chromedriver resets the initial renderer
+to `about:blank` during BiDi negotiation. Only opt in when you need one of the
+features above and can navigate to a known renderer URL:
+
+```ts
+const browser = await Browser.launch({
+  electron: { appBinaryPath: '/path/to/YourApp', version: '43.1.0' },
+  enableBiDi: true,
+});
+
+await browser.navigateTo('file:///path/inside/app/index.html');
+```
+
+Viewport and element screenshots do not require BiDi.
+
+## CI Notes
+
+Electron needs a display:
+
+- On Linux CI, run under a virtual display such as `xvfb-run`.
+- On macOS and Windows hosted runners, a display is usually already available.
+- Do not pass headless flags to Electron.
+- For disposable Linux CI fixtures, use `electron.args: ['--no-sandbox']` if the
+  unpacked app cannot start its sandbox.
+
+```ts
+await Browser.launch({
+  electron: {
+    appBinaryPath,
+    version: '43.1.0',
+    args: process.platform === 'linux' ? ['--no-sandbox'] : [],
+  },
+});
+```
+
+Prefer an exact Electron version in CI so driver resolution is repeatable.
+
+## Compatibility
+
+The automated Electron suite currently covers Electron **43.1.0** (Chromium 150) on Linux x64 and Windows x64. A real macOS production app, Fiddler
+Everywhere 7.8.0 (Electron 39.8.6 / Chromium 142), has also been driven
+manually.
+
+Other Electron versions are best-effort until they are added to the tested
+matrix.
+
+## Troubleshooting
+
+Set `CRAFTDRIVER_DEBUG=1` to print the selected app path, protocol, platform,
+Electron version when known, chromedriver path, driver source, and detected
+driver version. Arguments and environment values are not printed.
+
+Common failures:
+
+- **The app opens as a blank/plain Chromium window** — package the app and point
+  `appBinaryPath` at the packaged executable, not the source directory.
+- **Session creation fails with a driver mismatch** — pass the app's Electron
+  version or an explicit matching chromedriver.
+- **The driver is for the wrong CPU architecture** — use a chromedriver for the
+  host architecture.
+- **Linux CI exits during launch** — run under `xvfb-run`; for disposable
+  unpacked fixtures, try `electron.args: ['--no-sandbox']`.
+- **macOS blocks launch** — confirm the app executable can run on that machine.
+  If you provide a custom `chromedriverPath`, confirm that binary can run too.
+  Using `electron.version` lets CraftDriver resolve the Chrome-for-Testing driver
+  instead of relying on a local driver file.
+- **Manual launch opens Node.js instead of your app** — if
+  `ELECTRON_RUN_AS_NODE=1` is set in your shell, an Electron executable runs like
+  Node.js and does not open the desktop app window. CraftDriver removes that
+  variable when it launches your app. If you run the app yourself from a
+  terminal, unset it first:
+
+  ```bash
+  env -u ELECTRON_RUN_AS_NODE /path/to/YourApp
+  ```

package/docs/error-codes.md

@@ -49,6 +49,11 @@ try {
 | `UNSUPPORTED` | Feature exists but is unavailable on this browser/transport (e.g. Chromium-only over Firefox, or a BiDi-only feature with BiDi disabled). | Enable BiDi (`enableBiDi: true`) or switch browser. |
 | `STATE_INVALID` | Method called in the wrong state (e.g. `stopTrace()` without `startTrace()`). | Call the prerequisite first. |
 | `DRIVER_ERROR` | A WebDriver command returned a protocol error (non-200 response) — e.g. `stale element reference`, `element click intercepted`, `invalid selector` — or a transport-level failure. | `error.detail.webDriverError` carries the W3C JSON error code and `error.detail.webDriverMessage` the driver's message; recovery loops match on `webDriverError`. Also inspect `error.cause`. |
+| `ELECTRON_DRIVER_MISMATCH` | The resolved chromedriver can't drive the Electron app, caught **before** a session is created. | `error.detail.kind` is `'chromium-major'` (driver major ≠ the app's bundled Chromium; see `driverMajor` / `expectedChromiumMajor` / `electronVersion`) or `'arch'` (`driverArch` ≠ `runtimeArch`). The `hint` names the fix. |
+| `ELECTRON_LAUNCH_FAILED` | The Electron app process exited during session creation ("Chrome instance exited"). | `error.detail` carries the diagnosed cause (`macSigning: 'unsigned'`/`'adhoc'` on macOS, `sandboxDisabled: false` on Linux); `hint` is the top remediation; the message appends the chromedriver output tail; `error.cause` is the original driver error. |
+| `ELECTRON_MAIN_UNAVAILABLE` | `browser.electron.executeMain(...)` couldn't reach the app's main process. | Launch with `electron: { mainProcess: true }`; ensure the app build keeps the `EnableNodeCliInspectArguments` fuse enabled (default). `hint` names the fix. |
+| `ELECTRON_MAIN_THREW` | The `executeMain(...)` callback threw inside the Electron main process. | The main-process exception text is in the message; treat like a failed assertion about main-process state. |
+| `ELECTRON_DEEPLINK_FAILED` | `browser.electron.triggerDeeplink(url)` could not open the custom-protocol URL. | An unsupported platform, a missing `appBinaryPath` on Windows, or the OS `open`/`gio`/`rundll32` launcher failed (`error.detail.command`, `error.cause`). An invalid or `http(s)`/`file` URL throws `INVALID_ARGUMENT` instead. |
 
 ## Stability
 

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

@@ -13,6 +13,9 @@ hero:
     - theme: brand
       text: Get Started
       link: /getting-started
+    - theme: alt
+      text: Recipes
+      link: /recipes
     - theme: alt
       text: API Reference
       link: /api-reference
@@ -30,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
@@ -55,6 +58,7 @@ await browser.quit();
 | You want to...                    | Start                                   |
 | --------------------------------- | --------------------------------------- |
 | Write browser automation          | [Getting Started](./getting-started.md) |
+| Solve a common testing workflow   | [Recipes](./recipes.md)                 |
 | Give an AI coding agent a browser | [AI Agent Guide](./agents.md)           |
 
 ## Good Stuff To Read Next

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>