webview-preview 0.0.1 → 1.1.0

package/AGENTS.md

@@ -16,6 +16,9 @@ Read the [README](./README.md) for install and options. Everything here assumes
 4. Open the PNG only after the numbers make sense. Crop it to the area you care about before looking.
 5. Change, run again, compare the same numbers.
 
+Do not use `--watch`: it never exits. It is for a person keeping a snapshot open while editing; you run the command
+again after each change.
+
 When you report back, say which engine you checked and what you could **not** check (see the limits below).
 
 ## Writing steps
@@ -60,8 +63,15 @@ element.getClientRects().length > 0
   input.dispatchEvent(new Event('input', { bubbles: true })) }
 ```
 
-If the project's preview page exposes helpers (`window.preview.signIn()`, `window.preview.type(name, value)`), use
-them — they are faster and already correct.
+If the project's config has macros (`macros` in `webview-preview.config.mjs` — signing in, opening a dialog), use them
+(`macro:signIn`): they are already correct. A flow you repeat more than twice belongs there too.
+
+## Errors in the page
+
+After the steps the tool prints the page's `console.error` calls, uncaught exceptions and unhandled rejections
+(`console.error: …`, `uncaught: …`, `unhandled rejection: …`). Read them before you look at a snapshot: a blank or
+half-rendered picture almost always has its cause there. Mention any you did not cause — they may be bugs the user
+should know about. Add `--fail-on-error` when the run must fail on them.
 
 ## Measuring
 
@@ -83,7 +93,9 @@ screenshot scale.
 "print:document.querySelector('form').getBoundingClientRect().width"
 ```
 
-**Frame by frame.** To see whether something animates smoothly, jumps, or flickers, record every animation frame into
+**Frame by frame.** To *see* an animation, use `film:` right after the step that starts it —
+`"click:text=New project" "film:open:500@[role=dialog]"` gives one PNG with 10 frames over 500 ms, cropped to the
+dialog. To *measure* whether something animates smoothly, jumps, or flickers, record every animation frame into
 `window` and print the log afterwards. Keep only the frames where the value changed:
 
 ```
@@ -112,7 +124,7 @@ for y in range(320 * scale, 340 * scale):
 
 The screen you need is often behind a login, or empty because the backend is not running. **Never change the app's
 code to skip a check** (no `if (PREVIEW) skipAuth`, no commented-out guards): such switches end up in releases. All of
-it goes into the preview config: `init`, `mock`, helpers. The app's code stays as it is.
+it goes into the preview config: `init`, `mock`, `tauri`, `globals`, `macros`. The app's code stays as it is.
 
 1. **Find out what stands in the way.** Run with `--log-requests` and print the list:
 
@@ -133,9 +145,10 @@ it goes into the preview config: `init`, `mock`, helpers. The app's code stays a
    - session in storage → `init`: `localStorage.setItem('<key>', '<value in the exact format the code parses>')`;
    - session from a request → `mock` that request (`"GET /api/me": { json: { … } }`) and anything else the screen
      loads; take field names from the types / interfaces in the code;
-   - desktop bridge (Tauri `invoke`) → a stub of `window.__TAURI_INTERNALS__` in `init`;
-   - session only in memory (no storage, no request) → steps through the real login form, or a helper the project
-     already exposes (`window.preview.signIn()`).
+   - desktop bridge → `tauri: { commands: { … } }` for Tauri, `globals` with `anyApi({ … })` for Electron's
+     preload API or Wails bindings; the request list shows `invoke <command> -> null` / `call <path> -> default`
+     for every call that still needs an answer;
+   - session only in memory (no storage, no request) → steps through the real login form, saved as a macro.
 
 4. **Check that it worked:** print `location.href` (you stayed on the route) and the request list (every request
    the screen needs is `-> mock …`, none fails), then snap.
@@ -144,6 +157,10 @@ Put the result in the project's `webview-preview.config.mjs` (or `preview/mocks.
 person's — gets there in one command. Mention in your report which requests you mocked and with what data; mocked
 data can hide a real bug in how the app handles the real server.
 
+Loading and offline states are reachable too: `--latency 2000` (or the step `latency:2000`) keeps every request
+waiting, so you can snap the spinner or skeleton; `offline` / `online` steps drop the connection for `fetch` / XHR,
+switch `navigator.onLine` and fire the events, so an app's offline banner or retry logic shows up for real.
+
 ## Keyboard, mouse and focus
 
 Use the real input steps, not `js:` clicks, whenever the question is about what a person experiences:
@@ -151,6 +168,7 @@ Use the real input steps, not `js:` clicks, whenever the question is about what
 | Question | Steps |
 |---|---|
 | Does Tab go in the right order, does a focus trap hold? | `click:` the first field, then `key:Tab` / `key:Shift+Tab`, `print:document.activeElement…` after each |
+| Does Tab go through the right elements, in order, and stay inside a dialog? | `focusorder` (after opening the dialog); every stop should say `in dialog`, and it should loop back |
 | Is the focus ring visible and not clipped? | `key:Tab` until the element is focused, then `snap:ring@<selector>` (8 px margin included) |
 | Does the hover state look right? | `hover:<selector>`, `wait:300` for the transition, `snap:x@<selector>` |
 | Does typing work (validation, masks, Cyrillic…)? | `click:<input>`, `type:<text>`, `print:` the value / error text |
@@ -177,6 +195,22 @@ npx webview-preview /screen <steps> snap:screen "snap:panel@[data-test=panel]" -
 change is a regression to explain. Use a separate `--baseline` folder for such throw-away checks so you do not
 overwrite the project's committed baselines. Run `webview-preview clean` when you are done with the snapshots.
 
+When the user should see the result too, add `--report` and give them the path to `report.html`: baseline, this run
+and the difference side by side, with the run's output on top.
+
+## Sizes, theme and motion
+
+A layout change can break only the narrow window or only the dark theme. Check them in the same run instead of
+asking the user:
+
+```
+npx webview-preview /screen <steps> snap:screen --size 1200x650,800x600
+npx webview-preview /screen <steps> snap:screen --color-scheme dark
+```
+
+Each size runs the steps from the start and names the snapshots `<prefix><WxH>-<name>.png`. `--reduced-motion`
+makes a page that respects it skip its transitions, so a snapshot right after a click shows the final state.
+
 ## Still out of reach — and a few traps
 
 **Fractional scroll.** `scrollTop = 55.5` is rounded; real wheel and touchpad scrolling can stop between pixels. A
@@ -186,6 +220,9 @@ overwrite the project's committed baselines. Run `webview-preview clean` when yo
 WebKitGTK). The app opens in its default state — the default tab, no saved session — so reach the state you need with
 steps or `init`; do not rely on what an earlier run clicked.
 
+**Tab on macOS.** WebKit on a Mac tabs to text fields only unless Full Keyboard Access is on; buttons and links are
+skipped. That is what users of the app on a Mac get too — use `key:Alt+Tab` there to walk every element.
+
 **Windows' WebView2 itself.** `msedge` is the same engine, not the same embedding; window chrome, scrollbars of the
 host and DPI handling of a native window can differ.
 
@@ -202,6 +239,9 @@ host and DPI handling of a native window can differ.
 - The numbers you defined in step 1 match, in the engine the user runs (`webkitgtk` for Tauri on Linux, `msedge` for
   Windows).
 - No `js failed` / `print failed` / selector errors you did not expect; exit code 0.
+- What you measured by eye is pinned with `assert:` — `assert:document.activeElement.matches('[role=dialog] button')`,
+  `assert:getComputedStyle(document.querySelector('.card')).borderRadius === '12px'` — so a later run proves it in one
+  line. `assert:` shows only the final value; for `a === b` print `a` first if it fails.
 - Keyboard and hover behaviour checked with `key:` / `hover:` where the change touches them.
 - You looked at one snapshot of the final state.
 - You listed what could not be checked: fractional scroll, the other platform's engine, real backend data.

package/README.md

@@ -1,5 +1,7 @@
 # webview-preview
 
+[![test](https://github.com/n0t4u404/webview-preview/actions/workflows/test.yml/badge.svg)](https://github.com/n0t4u404/webview-preview/actions/workflows/test.yml)
+
 See your UI the way your desktop app really renders it. `webview-preview` opens a page in the **same engine your app
 runs on** — WebKitGTK on Linux, Edge (the WebView2 engine) on Windows, WebKit on macOS — runs a list of steps
 (click, type, wait, measure) and saves PNG snapshots.
@@ -15,15 +17,23 @@ npx webview-preview https://example.com snap:home
 # → .webview-preview/webkitgtk-home.png  (on Linux)
 ```
 
+**What it is — and what it is not.** A tool to *look at* a screen in the real engine: open it in the state you need,
+press keys, measure, snap, compare with yesterday. Steps stay one-liners you can type in a terminal; mocks and
+desktop stubs only say *what to answer* so the screen renders. It is not a test runner: no test suites, no stateful
+mocks, no `expect` library, no retries. For end-to-end tests use Playwright Test or WebdriverIO — the stubs here are
+plain init scripts and fit there too.
+
 - [Which engine matches my app](#which-engine-matches-my-app)
 - [Install](#install)
 - [Quick start](#quick-start)
 - [Config file](#config-file)
 - [Steps](#steps)
+- [Macros](#macros)
+- [Errors in the page](#errors-in-the-page)
 - [Command line](#command-line)
 - [JavaScript API](#javascript-api)
 - [Login, backend and other things outside the page](#login-backend-and-other-things-outside-the-page)
-- [Running a Tauri UI outside Tauri](#running-a-tauri-ui-outside-tauri)
+- [Desktop bridges: Tauri, Electron, Wails](#desktop-bridges-tauri-electron-wails)
 - [Comparing with a baseline](#comparing-with-a-baseline)
 - [Cleaning up snapshots](#cleaning-up-snapshots)
 - [Recipes](#recipes)
@@ -148,7 +158,12 @@ npx webview-preview /settings snap:settings
 | `server.cwd` | Folder for `server.command`. | the config's folder |
 | `server.readyTimeoutMs` | How long to wait for the port. | `30000` |
 | `engine` | See [engines](#which-engine-matches-my-app). | `auto` |
-| `size` | Window size in CSS pixels, `WxH`. | `1200x650` |
+| `size` | Window size in CSS pixels, `WxH`. Several sizes — `"1200x650,800x600"` or a list — run the steps once per size; snapshots get the size in the name: `webkitgtk-800x600-page.png`. | `1200x650` |
+| `colorScheme` | `prefers-color-scheme` for the page: `light` or `dark`. | system |
+| `reducedMotion` | `prefers-reduced-motion: reduce` for the page. | `false` |
+| `report` | Write `<out>/report.html` after every run. See [Comparing with a baseline](#comparing-with-a-baseline). | `false` |
+| `watch` | What `--watch` follows: a folder, a file or a list, relative to the config's folder. The config file itself is always followed. | `src` if it exists, else the config's folder |
+| `offline` / `latency` | Start offline / delay every `fetch` / XHR request by ms. See [Slow network and offline](#4-slow-network-and-offline). | `false` / `0` |
 | `out` | Snapshot folder, relative to the config's folder. | `.webview-preview` |
 | `prefix` | File name prefix. | `<engine>-` |
 | `scale` | Device pixel ratio for Playwright engines (`2` = HiDPI). WebKitGTK: off-screen snapshots are 1×, `--headed` ones follow your screen. | `1` |
@@ -160,6 +175,11 @@ npx webview-preview /settings snap:settings
 | `init` | Code that runs **before the page's own scripts**, on every load: a string, `{ file: "path" }`, or a list of them. See [below](#1-init--set-things-up-before-the-app-starts). | — |
 | `mock` | Answers for `fetch` / `XMLHttpRequest` requests: `{ "GET /api/me": { json: { … } } }`. See [below](#2-mock--answer-backend-requests). | — |
 | `logRequests` | List every `fetch` / `XMLHttpRequest` request in `window.__webviewPreviewRequests` (also on whenever `mock` is set). | `false` |
+| `tauri` | Stub the Tauri bridge: `true`, or `{ commands: { … }, label: "main" }`. See [Desktop bridges](#desktop-bridges-tauri-electron-wails). | — |
+| `globals` | Objects to put on `window` before the page starts, by path: `{ "window.api": anyApi({ … }) }`. See [Desktop bridges](#desktop-bridges-tauri-electron-wails). | — |
+| `locale` | `navigator.language` for the page, `en-US`, `ru-RU` … Playwright engines also switch `Intl` and `Accept-Language`; WebKitGTK only `navigator.language`. | system |
+| `macros` | Named lists of steps, run with `macro:<name>`. See [Macros](#macros). | — |
+| `failOnError` | Exit with 1 when the page logged `console.error` or threw. See [Errors in the page](#errors-in-the-page). | `false` |
 
 Command-line options win over the config file.
 
@@ -211,7 +231,13 @@ Steps run one after another, after the page has loaded and settled for 1.5 s.
 | `click:<selector>` | Clicks the middle of the element with the real mouse — focus moves, `:active` and `:focus` apply like for a person. |
 | `print:<expression>` | Prints the value: strings as they are, DOM elements as their HTML (first 200 characters), everything else as JSON. Promises are not awaited. |
 | `measure:<selector>` | Prints one line about the element: how many match, position and size, margin / padding / border, visible or hidden, display, opacity, font, colours and text. |
+| `offline` / `online` | Drops the connection for `fetch` / XHR and brings it back, with `navigator.onLine` and the events, then waits 700 ms like `js:`. See [Slow network and offline](#4-slow-network-and-offline). |
+| `latency:<ms>` | Delays every `fetch` / XHR request from now on; `latency:0` turns it off. |
+| `focusorder` / `focusorder:<n>` | Presses `Tab` with the real keyboard n times (20 by default) and prints where focus went, one line per stop — tag, role, name, label, "in dialog" — and `→ back to 1 after N stops` when it loops. Shows a focus trap, a skipped field or focus escaping a dialog at a glance. Starts from the current focus. |
+| `assert:<expression>` | Checks that the expression is truthy: prints `assert ok: …`, or `assert failed: … — got <value>` / `— threw <message>` and makes the run exit with 1. The other steps still run. |
+| `film:<name>:<ms>[/<n>][@<selector>]` | Takes n frames (10 by default, up to 60) evenly over ms, starting now, and puts them into one `<prefix><name>.png`, 5 per row, left to right. With a selector every frame is cropped to the area the element covered during the whole film (plus `--snap-margin`). Prints the real time of every frame: `film open: 10 frames at 0 55 111 … 500 ms`. Put it right after the step that starts the animation. |
 | `resize:<W>x<H>` | Resizes the window. |
+| `macro:<name>` | Runs the steps of a macro from the config. See [Macros](#macros). |
 
 ### Selectors
 
@@ -247,6 +273,50 @@ npx webview-preview / \
 
 On Windows PowerShell use the same double quotes; inside them, keep JavaScript strings in single quotes.
 
+## Macros
+
+Steps you repeat — signing in, opening a dialog — go into the config under a name:
+
+```js
+export default {
+	macros: {
+		signIn: [
+			"js:location.hash = '#/sign-in'",
+			"waitfor:input[name=email]",
+			"click:input[name=email]",
+			"type:demo@example.com",
+			"click:input[name=password]",
+			"type:secret",
+			"click:button[type=submit]",
+			"waitfor:[role=tab]"
+		],
+		openSettings: ["macro:signIn", "click:text=Settings", "waitfor:[role=dialog]"]
+	}
+}
+```
+
+```sh
+npx webview-preview / macro:openSettings snap:settings
+```
+
+A macro may run other macros; one that runs itself stops with an error. Prefer real clicks and typing over setting
+values from code: the run then goes through the same handlers, focus and validation as for a person.
+
+## Errors in the page
+
+Every run collects what went wrong inside the page — `console.error` calls, uncaught exceptions and unhandled promise
+rejections — and prints them after the steps, the same message once with a count:
+
+```
+console.error: Failed to load {"code":500} (×2)
+unhandled rejection: Error: no session — global code@http://localhost:5173/src/app.tsx:4:25
+uncaught: TypeError: null is not an object (evaluating 'user.name') — onclick@http://localhost:5173/src/app.tsx:12:5
+```
+
+A blank snapshot usually has its reason here. With `--fail-on-error` (`failOnError: true`) the run exits with 1 when
+there is anything to print — useful in CI. Pages opened from `file://` report uncaught errors only as
+"Script error." in WebKit; serve the page over `http://` to see them.
+
 ## Command line
 
 ```
@@ -256,7 +326,11 @@ webview-preview [route-or-url] [steps...] [options]
 | Option | |
 |---|---|
 | `--engine <name>` | `auto`, `webkitgtk`, `msedge`, `chrome`, `chromium`, `webkit` |
-| `--size <WxH>` | Window size |
+| `--size <WxH>` | Window size; several, comma-separated: `1200x650,800x600` |
+| `--color-scheme <light\|dark>` | `prefers-color-scheme` for the page |
+| `--reduced-motion` | `prefers-reduced-motion: reduce` for the page |
+| `--watch` | Run again whenever a file changes; the server stays up between runs. Ctrl+C to stop |
+| `--offline` / `--latency <ms>` | Start offline / delay every `fetch` / XHR request |
 | `--out <dir>` | Snapshot folder |
 | `--prefix <text>` | File name prefix |
 | `--scale <n>` | Device pixel ratio (Playwright engines) |
@@ -264,6 +338,7 @@ webview-preview [route-or-url] [steps...] [options]
 | `--snap-margin <px>` | Room around `snap:name@selector` |
 | `--wait-timeout <ms>` | How long `waitfor:` waits |
 | `--keep-storage` | WebKitGTK: keep storage between runs |
+| `--report` | Write `<out>/report.html` with the output and all snapshots (baseline and difference after `--compare`) |
 | `--compare` / `--update-baseline` | Compare snapshots with baselines / replace the baselines |
 | `--baseline <dir>` / `--max-diff-pixels <n>` / `--compare-tolerance <n>` | Baseline folder, allowed difference |
 | `--base-url <url>` | Base for routes |
@@ -271,6 +346,9 @@ webview-preview [route-or-url] [steps...] [options]
 | `--init-file <file>` | Same, from a file (repeatable) |
 | `--mock-file <file>` | Mocks from a `.json` or `.mjs` file (repeatable, added to the config's `mock`) |
 | `--log-requests` | Only list requests, answer nothing |
+| `--tauri` | Stub the Tauri bridge (answers from `tauri.commands` in the config) |
+| `--locale <tag>` | `navigator.language` for the page |
+| `--fail-on-error` | Exit with 1 when the page logged `console.error` or threw |
 | `--config <file>` | Use this config file |
 | `--no-config` | Ignore config files |
 | `-h`, `--help` / `-v`, `--version` | |
@@ -309,6 +387,9 @@ result.failed; // false
 `preview()` reads the config file the same way the CLI does; pass `config: false` to skip it or `config: "path"` to
 choose one. Types are included.
 
+`watchPreview(options, onRun)` is `--watch`: it runs once, then again on every change, calls `onRun(result)` after
+each run and resolves to a function that stops watching and the server.
+
 ## Login, backend and other things outside the page
 
 A real app rarely shows the screen you want straight away: it checks a session and sends you to a login page, it
@@ -321,8 +402,8 @@ Change what the page *receives* instead, only for the preview run:
 | A session or token kept in `localStorage`, `sessionStorage`, cookies | [`init`](#1-init--set-things-up-before-the-app-starts) |
 | Requests to your backend (`fetch`, `axios`, `XMLHttpRequest`) | [`mock`](#2-mock--answer-backend-requests) |
 | You don't know yet what the app requests | [`--log-requests`](#3-find-out-what-the-app-requests) |
-| Desktop APIs (Tauri `invoke`, window controls) | [`init`](#1-init--set-things-up-before-the-app-starts) with a stub, see [Tauri](#running-a-tauri-ui-outside-tauri) |
-| Login that lives only in memory, or a flow you want to click through | steps or helpers: `js:preview.signIn()` |
+| Desktop APIs (Tauri `invoke`, Electron preload, Wails bindings) | [`tauri`, `globals`](#desktop-bridges-tauri-electron-wails) |
+| Login that lives only in memory, or a flow you want to click through | steps, kept as a [macro](#macros): `macro:signIn` |
 
 ### 1. `init` — set things up before the app starts
 
@@ -419,92 +500,99 @@ With `mock` set, the same list shows which requests were answered: `GET /api/me
 desktop side does by itself (a Tauri command that calls a server from Rust). For desktop calls, stub the bridge in
 `init`; for the rest, run the real service locally.
 
-## Running a Tauri UI outside Tauri
+### 4. Slow network and offline
 
-Your Tauri frontend calls `invoke` and window APIs. Outside the app there is no Tauri, so those calls fail — and the
-screen you want to see may never render.
+How does the screen look while data is on its way, and what happens when the connection drops?
 
-**Quick way — a stub in `init`.** `@tauri-apps/api` talks to `window.__TAURI_INTERNALS__`; define it before the app
-starts and every `invoke` gets your answer:
+```sh
+npx webview-preview /dashboard --latency 2000 wait:300 snap:loading wait:2500 snap:loaded
+npx webview-preview /dashboard waitfor:.instance-card offline snap:offline online wait:1000 snap:back-online
+```
 
-```js
-// preview/tauri.js
-const answers = { app_version: "0.0.1", get_settings: { theme: "dark" } }
+| | |
+|---|---|
+| `latency:<ms>` step / `--latency <ms>` / `latency` in the config | Every `fetch` / XHR request waits that long first, answers from `mock` too. `latency:0` turns it off. |
+| `offline` / `online` steps, `--offline` / `offline: true` | `navigator.onLine` turns `false`, the page gets the `offline` event, `fetch` rejects with `TypeError: Failed to fetch`, XHR fires `error`. `online` brings it all back and fires `online`. `--offline` starts that way; the page itself still loads. |
 
-window.__TAURI_INTERNALS__ = {
-	invoke: (command, args) => Promise.resolve(answers[command] ?? null),
-	transformCallback: () => 0,
-	metadata: { currentWindow: { label: "main" }, currentWebview: { label: "main" } }
-}
+While offline, the request list shows `GET /api/me -> offline`. Like `mock`, this covers `fetch` and XHR only:
+pictures, WebSocket and the desktop side keep their connection.
+
+
+Your frontend calls the desktop side: Tauri's `invoke`, an Electron preload API, Wails bindings. Outside the app
+there is no desktop side, so those calls fail — and the screen you want may never render. `webview-preview` puts a
+stand-in in place before the page starts, so you open **your real entry page**, not a copy made for previews.
+
+Every call to a stand-in is listed in `window.__webviewPreviewRequests`, next to `fetch` / XHR requests — print it
+to see what the page asks for and what is still unanswered:
+
+```sh
+npx webview-preview / wait:2000 "print:__webviewPreviewRequests.join('\n')"
+# invoke plugin:app|version -> stub
+# invoke get_settings -> null
+# call window.api.onUpdate -> default
 ```
 
+### Tauri
+
 ```js
-// webview-preview.config.mjs
 export default {
 	baseUrl: "http://localhost:1420",
 	server: { command: "npx vite --port 1420 --strictPort", port: 1420 },
-	init: { file: "preview/tauri.js" }
+	tauri: {
+		commands: {
+			"plugin:app|version": "1.4.0",
+			get_settings: { theme: "dark" },
+			greet: ({ name }) => `Hello, ${name}`
+		}
+	}
 }
 ```
 
-**Bigger apps — a preview entry page.** When you also want helpers (sign in, switch language, go offline) and typed
-stubs, give the preview its own entry:
-
-1. **A stub** — set before anything imports `@tauri-apps/api`:
-
-   ```ts
-   // src/preview/tauri-stub.ts
-   const answers: Record<string, unknown> = { app_version: "0.0.1" }
+Or just `--tauri` on the command line. What you get (Tauri 2, `@tauri-apps/api`):
 
-   Object.assign(window, {
-   	__TAURI_INTERNALS__: {
-   		invoke: (command: string) => Promise.resolve(answers[command] ?? null),
-   		transformCallback: () => 0,
-   		metadata: { currentWindow: { label: "main" }, currentWebview: { label: "main" } }
-   	}
-   });
-   ```
+- `invoke` answers from `commands` — a value, or a function of the arguments (it may be `async`). A command not in
+  the list gets `null`. Plugin commands are named as `@tauri-apps/api` sends them: `plugin:<plugin>|<command>`.
+- Built-in answers you can override: `plugin:app|version` / `name` / `tauri_version`, window state
+  (`plugin:window|is_maximized` → `false`, `is_focused` → `true`, `scale_factor`, `inner_size` …).
+- Events work inside the page: `listen`, `once`, `emit`, `unlisten`. To act as the Rust side, emit from a step:
+  `js:__webviewPreview.emit("download-progress", { percent: 40 })`.
+- `getCurrentWindow()` / `getCurrentWebview()` get the label `main` (`label` changes it), `isTauri()` is `true`,
+  `convertFileSrc` and `path.sep` work.
 
-2. **An entry** that renders your app after the stub:
+Functions in `commands` are copied into the page as source code, so they cannot use variables from the config
+file — only their arguments and what is in the page.
 
-   ```ts
-   // src/preview/index.tsx
-   import "./tauri-stub";
-   import { createRoot } from "react-dom/client";
-   import { App } from "../app";
+### Electron, Wails and other bridges — `globals`
 
-   createRoot(document.getElementById("root")!).render(<App />);
-   ```
+`globals` puts objects on `window` by path before the page starts. `anyApi()` is a stand-in that answers **any**
+call: awaiting it gives `null`, calling the result works too (handy for "subscribe" functions that return an
+"unsubscribe"). Pass the members you care about:
 
-   plus `src/preview/index.html` that loads it. With Vite, add the page to `build.rollupOptions.input` only if you
-   want it in builds — the dev server serves it either way.
-
-3. **Helpers** for states that are tedious to reach with clicks — signing in, switching language, going offline:
-
-   ```ts
-   Object.assign(window, {
-   	preview: {
-   		signIn: () => { /* fill the form, submit */ },
-   		language: (code: string) => i18n.changeLanguage(code)
-   	}
-   });
-   ```
+```js
+import { anyApi, defineConfig } from "webview-preview";
 
-   ```sh
-   npx webview-preview /settings "js:preview.signIn()" wait:3000 snap:settings
-   ```
+export default defineConfig({
+	globals: {
+		// Electron: what your preload exposes with contextBridge.exposeInMainWorld("api", …)
+		"window.api": anyApi({
+			getVersion: async () => "1.4.0",
+			platform: "linux"
+		}),
+
+		// Wails: generated bindings and the runtime
+		"window.go": anyApi(),
+		"window.runtime": anyApi()
+	}
+});
+```
 
-4. **Config:**
+Plain values work as well: `"window.__APP_CONFIG__": { apiUrl: "http://localhost:3000" }`.
 
-   ```js
-   export default {
-   	baseUrl: "http://localhost:1420/src/preview/index.html#",
-   	server: { command: "npx vite --port 1420 --strictPort", port: 1420 }
-   }
-   ```
+### What stays different
 
-Real Rust is not involved, so anything that depends on it shows what the stub answers. That is the trade-off for
-checking a screen in seconds.
+Real Rust, Node or Go is not involved: anything that depends on it shows what the stand-in answers. Window chrome,
+native menus and dialogs are not there. That is the trade-off for checking a screen in seconds without building
+the app.
 
 ## Comparing with a baseline
 
@@ -526,6 +614,9 @@ npx webview-preview /settings snap:settings "snap:menu@[role=menu]" --compare
   The `.diff.png` shows the snapshot in grey with the changed pixels in red. More than `maxDiffPixels` changed
   (default `0`) → exit code `1`.
 - **The change is intended**: `--update-baseline` replaces the baselines with this run's snapshots.
+- **See it all on one page**: add `--report`. `<out>/report.html` shows the run's output and every snapshot —
+  after `--compare` with the baseline, this run and the difference side by side, changed ones marked red. Open it in
+  any browser; it works without a server and follows the system's light or dark theme.
 
 Snapshots differ between engines and screen scales, so the engine is part of the file name (`webkitgtk-…`,
 `msedge-…`) and each engine has its own baselines. `compareTolerance` (default `2` of 255 per channel) ignores
@@ -557,8 +648,38 @@ for engine in webkitgtk chrome; do npx webview-preview /settings --engine $engin
 
 ```sh
 npx webview-preview / snap:wide resize:900x500 wait:300 snap:narrow
+npx webview-preview / snap:home --size 1200x650,800x600,480x800
+```
+
+**Keep a snapshot fresh while you edit** — leave it running next to the editor and keep the PNG open:
+
+```sh
+npx webview-preview /settings waitfor:.settings snap:settings "measure:.settings" --watch
 ```
 
+Every save runs the steps again from a clean page (the dev server stays up), prints the numbers and rewrites the
+snapshot. A change of the config file is picked up too.
+
+**See an animation, not only where it ends** — a dialog that opens:
+
+```sh
+npx webview-preview / "click:text=New project" "film:open:500@[role=dialog]"
+```
+
+One picture with 10 frames: you see whether it fades and grows smoothly, starts from the wrong place, jumps at the end
+or plays twice. Frames are real screenshots taken as fast as the engine allows, so the printed times are what to
+trust, not the planned spacing.
+
+**Light and dark, with and without motion:**
+
+```sh
+for scheme in light dark; do npx webview-preview / snap:home-$scheme --color-scheme $scheme; done
+npx webview-preview / click:.menu-button snap:menu-open --reduced-motion
+```
+
+With `--reduced-motion` a page that respects it skips its transitions, so a snapshot right after a click shows the
+final state instead of a frame in the middle of the animation — and you see whether the page respects it at all.
+
 **Measure instead of looking** — sizes and positions are more reliable than eyes:
 
 ```sh
@@ -599,6 +720,8 @@ More of these — animations frame by frame, measuring, getting past login — i
 | `WebKitGTK engine needs Linux with python3-gi and WebKit2 4.1` | Install the [Linux packages](#linux--webkitgtk). |
 | `This engine needs playwright-core` | `npm i -D playwright-core`. |
 | `Executable doesn't exist` (Playwright) | `npx playwright install webkit` (or `chromium`); for `msedge` / `chrome` install the browser itself. |
+| macOS, `webkit`: `Tab` skips buttons and links | That is macOS: with Full Keyboard Access off (the default) WebKit tabs to text fields only — a Tauri app on a Mac behaves the same. Use `key:Alt+Tab` to reach every element, as Option+Tab does in Safari. |
+| WebKitGTK in CI | Run under `xvfb-run -a` (it needs an X display even off-screen); `sudo apt-get install -y python3-gi gir1.2-webkit2-4.1 xvfb`. |
 | `Server did not open port …` | The `server.command` failed or uses another port. Run it by hand to see why; raise `readyTimeoutMs` for slow starts. |
 | `"/route" is not a full URL` | Set `baseUrl` in the config or pass `--base-url`. |
 | Blank snapshot | The page needs more time or threw on start: add `wait:2000`, and `print:document.body.innerHTML.length`. |
@@ -619,6 +742,17 @@ agent to it (for example from `CLAUDE.md` or `AGENTS.md` in your project):
 UI changes: check them in the real engine with `npx webview-preview` — see node_modules/webview-preview/AGENTS.md.
 ```
 
+## Development
+
+```sh
+npm test                                   # the default engine for this system
+WEBVIEW_PREVIEW_ENGINE=chrome npm test     # one engine
+```
+
+The tests open `test/fixture/index.html` and check snapshots, input, focus order, errors, mock, offline, sizes,
+`film:`, compare and the report. GitHub Actions runs them on every push: WebKitGTK and Chromium on Linux, Edge and
+Chrome on Windows, WebKit on macOS; snapshots and reports of every run are kept as artifacts.
+
 ## License
 
 MIT © n0t4u404