webview-preview 0.0.1 → 1.0.0

package/AGENTS.md

@@ -60,8 +60,8 @@ 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.
 
 ## Measuring
 
@@ -112,7 +112,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 +133,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.

package/README.md

@@ -15,15 +15,22 @@ 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)
 - [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)
@@ -160,6 +167,10 @@ 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). | — |
 
 Command-line options win over the config file.
 
@@ -212,6 +223,7 @@ Steps run one after another, after the page has loaded and settled for 1.5 s.
 | `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. |
 | `resize:<W>x<H>` | Resizes the window. |
+| `macro:<name>` | Runs the steps of a macro from the config. See [Macros](#macros). |
 
 ### Selectors
 
@@ -247,6 +259,35 @@ 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.
+
 ## Command line
 
 ```
@@ -271,6 +312,8 @@ 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 |
 | `--config <file>` | Use this config file |
 | `--no-config` | Ignore config files |
 | `-h`, `--help` / `-v`, `--version` | |
@@ -321,8 +364,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 +462,83 @@ 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
-
-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.
+## Desktop bridges: Tauri, Electron, Wails
 
-**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:
+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.
 
-```js
-// preview/tauri.js
-const answers = { app_version: "0.0.1", get_settings: { theme: "dark" } }
+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:
 
-window.__TAURI_INTERNALS__ = {
-	invoke: (command, args) => Promise.resolve(answers[command] ?? null),
-	transformCallback: () => 0,
-	metadata: { currentWindow: { label: "main" }, currentWebview: { label: "main" } }
-}
+```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
 

package/bin/webview-preview.mjs

@@ -2,7 +2,22 @@
 import { readFileSync } from "node:fs";
 import { cleanSnapshots, ENGINES, preview } from "#src/index.mjs";
 
-const FLAGS = { "--engine": "engine", "--size": "size", "--out": "out", "--prefix": "prefix", "--scale": "scale", "--config": "config", "--base-url": "baseUrl", "--snap-margin": "snapMargin", "--baseline": "baseline", "--max-diff-pixels": "maxDiffPixels", "--compare-tolerance": "compareTolerance", "--older-than": "olderThan", "--wait-timeout": "waitTimeout" }
+const FLAGS = {
+	"--engine": "engine",
+	"--size": "size",
+	"--out": "out",
+	"--prefix": "prefix",
+	"--scale": "scale",
+	"--config": "config",
+	"--base-url": "baseUrl",
+	"--snap-margin": "snapMargin",
+	"--baseline": "baseline",
+	"--max-diff-pixels": "maxDiffPixels",
+	"--compare-tolerance": "compareTolerance",
+	"--older-than": "olderThan",
+	"--wait-timeout": "waitTimeout",
+	"--locale": "locale"
+}
 const LIST_FLAGS = { "--init": "init", "--init-file": "initFile", "--mock-file": "mockFile" }
 
 const HELP = `Usage: webview-preview [route-or-url] [steps...] [options]
@@ -25,6 +40,7 @@ Steps:
   type:<text>      type text with the keyboard
   hover:<css selector>  move the mouse to the element's centre
   click:<css selector>  click the element's centre with the mouse
+  macro:<name>     run the steps of a macro from the config (macros: { name: [...] })
 
 Options:
   --engine <name>  ${ENGINES.join(" | ")} (default: auto)
@@ -48,6 +64,9 @@ Options:
   --mock-file <f>  answer fetch/XHR requests from a .json/.mjs file of mocks (repeatable);
                    every request is listed in window.__webviewPreviewRequests
   --log-requests   only list fetch/XHR requests in window.__webviewPreviewRequests
+  --tauri          stub the Tauri bridge (invoke, events, window); answers come from
+                   tauri.commands in the config, anything else gets null
+  --locale <tag>   navigator.language for the page: en-US, ru-RU … (Playwright: also Intl)
   --config <file>  config file (default: webview-preview.config.{mjs,js,json})
   --no-config      ignore config files
 
@@ -83,6 +102,10 @@ const parseArgs = argv => {
 			options.headed = true;
 			continue;
 		}
+		if (arg === "--tauri") {
+			options.tauri = true;
+			continue;
+		}
 		if (arg === "--log-requests") {
 			options.logRequests = true;
 			continue;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "webview-preview",
-	"version": "0.0.1",
+	"version": "1.0.0",
 	"description": "Open your UI in the engine your desktop app really runs on (WebKitGTK, Edge/WebView2, WebKit), drive it with steps and save PNG snapshots.",
 	"license": "MIT",
 	"author": "n0t4u404",

package/src/core/steps.mjs

@@ -112,6 +112,19 @@ const parseKey = combo => {
 	return { key, modifiers }
 }
 
+export const expandMacros = (steps, macros = {}, trail = []) => steps.flatMap(step => {
+	if (!step.startsWith("macro:")) return [step];
+	const name = step.slice(6);
+	if (!Object.hasOwn(macros, name)) {
+		const known = Object.keys(macros);
+		throw new Error(`Unknown macro "${name}". Macros: ${known.length ? known.join(", ") : "none — add them to macros in the config"}`);
+	}
+	if (trail.includes(name)) throw new Error(`macro:${name} uses itself: ${[...trail, name].join(" → ")}`);
+	const body = macros[name];
+	if (!Array.isArray(body) || !body.every(item => typeof item === "string")) throw new Error(`macro "${name}" must be a list of steps`);
+	return expandMacros(body, macros, [...trail, name]);
+})
+
 export const parseSize = value => {
 	const match = /^(\d+)x(\d+)$/.exec(String(value));
 	if (!match) throw new Error(`Size must look like 1200x650, got "${value}"`);
@@ -122,7 +135,7 @@ export const parseSteps = steps => steps.map(step => {
 	const separator = step.indexOf(":");
 	const kind = separator === -1 ? step : step.slice(0, separator);
 	const value = separator === -1 ? "" : step.slice(separator + 1);
-	if (!STEP_KINDS.has(kind)) throw new Error(`Unknown step "${step}". Steps: ${[...STEP_KINDS].join(", ")}`);
+	if (!STEP_KINDS.has(kind)) throw new Error(`Unknown step "${step}". Steps: ${[...STEP_KINDS, "macro"].join(", ")}`);
 	if (kind === "wait" && !/^\d+$/.test(value)) throw new Error(`wait needs milliseconds, got "${step}"`);
 	if (kind === "resize") parseSize(value);
 	if (kind === "snap") {

package/src/engines/playwright.mjs

@@ -16,7 +16,7 @@ const loadPlaywright = async () => {
 	}
 }
 
-export const runPlaywright = async ({ engine, url, steps, init = [], size, out, prefix, scale, snapMargin = 8, waitForTimeoutMs = WAIT_FOR_TIMEOUT_MS, log }) => {
+export const runPlaywright = async ({ engine, url, steps, init = [], size, locale, out, prefix, scale, snapMargin = 8, waitForTimeoutMs = WAIT_FOR_TIMEOUT_MS, log }) => {
 	const playwright = await loadPlaywright();
 	const browserType = engine === "webkit" ? playwright.webkit : playwright.chromium;
 	const browser = await browserType.launch({ channel: CHANNELS[engine], headless: true });
@@ -24,7 +24,7 @@ export const runPlaywright = async ({ engine, url, steps, init = [], size, out,
 	let failed = false;
 
 	try {
-		const page = await browser.newPage({ viewport: parseSize(size), deviceScaleFactor: scale ?? 1 });
+		const page = await browser.newPage({ viewport: parseSize(size), deviceScaleFactor: scale ?? 1, locale });
 		page.setDefaultTimeout(TIMEOUT_MS);
 		for (const content of init) await page.addInitScript({ content });
 		await page.goto(url, { waitUntil: "load" });

package/src/index.d.ts

@@ -12,7 +12,8 @@ export type Step =
 	| `key:${string}`
 	| `type:${string}`
 	| `hover:${string}`
-	| `click:${string}`;
+	| `click:${string}`
+	| `macro:${string}`;
 
 export interface ServerOptions {
 	command: string;
@@ -42,6 +43,19 @@ export interface PreviewConfig {
 	baseline?: string;
 	maxDiffPixels?: number;
 	compareTolerance?: number;
+	tauri?: boolean | TauriStub;
+	globals?: Record<string, unknown>;
+	locale?: string;
+	macros?: Record<string, Step[] | string[]>;
+}
+
+export interface TauriStub {
+	commands?: Record<string, unknown | ((args: Record<string, unknown>) => unknown)>;
+	label?: string;
+}
+
+export interface AnyApi {
+	readonly members: Record<string, unknown>;
 }
 
 export interface MockResponse {
@@ -75,6 +89,7 @@ export declare const REQUESTS_KEY: "__webviewPreviewRequests";
 export declare function resolveUrl(target: string, baseUrl?: string): string;
 export declare function preview(options?: PreviewOptions): Promise<PreviewResult>;
 export declare function defineConfig(config: PreviewConfig): PreviewConfig;
+export declare function anyApi(members?: Record<string, unknown>): AnyApi;
 export interface CleanOptions {
 	config?: string | false;
 	out?: string;

package/src/index.mjs

@@ -3,14 +3,17 @@ import path from "node:path";
 import { compareSnapshots } from "#src/snapshots/compare.mjs";
 import { loadConfig } from "#src/core/config.mjs";
 import { resolveEngine, runEngine } from "#src/engines/index.mjs";
-import { resolveInit } from "#src/page/init.mjs";
+import { checkLocale, globalsScript, localeScript } from "#src/page/globals.mjs";
+import { resolveInit, wrapInit } from "#src/page/init.mjs";
 import { compileMock, mockScript, resolveMockFiles } from "#src/page/mock.mjs";
 import { startServer } from "#src/core/server.mjs";
-import { parseSize, parseSteps } from "#src/core/steps.mjs";
+import { expandMacros, parseSize, parseSteps } from "#src/core/steps.mjs";
+import { resolveTauri, tauriScript } from "#src/page/tauri.mjs";
 
 export { ENGINES } from "#src/engines/index.mjs";
 export { REQUESTS_KEY } from "#src/page/mock.mjs";
 export { cleanSnapshots } from "#src/snapshots/clean.mjs";
+export { anyApi } from "#src/page/source.mjs";
 
 const DEFAULTS = { engine: "auto", size: "1200x650", out: ".webview-preview", steps: ["snap:page"] }
 const ABSOLUTE_URL = /^[a-z][a-z\d+.-]*:/i;
@@ -31,7 +34,8 @@ export const preview = async (options = {}) => {
 	const merged = { ...DEFAULTS, ...config, ...Object.fromEntries(Object.entries(options).filter(([, value]) => value !== undefined)) }
 	const baseDir = config.configDir ?? process.cwd();
 	const engine = resolveEngine(merged.engine);
-	const steps = parseSteps(merged.steps.length ? merged.steps : DEFAULTS.steps);
+	const macros = { ...config.macros, ...options.macros }
+	const steps = parseSteps(expandMacros(merged.steps.length ? merged.steps : DEFAULTS.steps, macros));
 	const out = path.resolve(baseDir, merged.out);
 	const url = resolveUrl(merged.target ?? merged.url ?? "/", merged.baseUrl);
 	parseSize(merged.size);
@@ -39,7 +43,22 @@ export const preview = async (options = {}) => {
 	const hasMock = config.mock !== undefined || options.mock !== undefined || mockFiles.length > 0
 		|| !!(options.logRequests ?? config.logRequests);
 	const mockRules = compileMock([config.mock, ...mockFiles, options.mock]);
-	const init = (hasMock ? [mockScript(mockRules)] : []).concat(resolveInit([
+	const locale = merged.locale === undefined ? undefined : checkLocale(String(merged.locale));
+	const tauri = resolveTauri(config.tauri, options.tauri);
+	const globals = { ...config.globals, ...options.globals }
+	const stubs = [
+		locale && { label: "locale", source: localeScript(locale) },
+		tauri && { label: "tauri", source: tauriScript(tauri) },
+		Object.keys(globals).length && { label: "globals", source: globalsScript(globals) }
+	].filter(Boolean).map(stub => {
+		try {
+			new Function(stub.source);
+		} catch (error) {
+			throw new Error(`${stub.label}: the generated script does not parse (${error.message}); check the functions in your config`);
+		}
+		return wrapInit(stub);
+	});
+	const init = stubs.concat(hasMock ? [mockScript(mockRules)] : [], resolveInit([
 		{ entries: config.init, baseDir },
 		{ entries: options.init, baseDir: process.cwd() },
 		{ entries: options.initFile && [].concat(options.initFile).map(file => ({ file })), baseDir: process.cwd() }
@@ -54,6 +73,7 @@ export const preview = async (options = {}) => {
 			steps,
 			init,
 			size: merged.size,
+			locale,
 			out,
 			prefix: merged.prefix ?? `${engine}-`,
 			scale: merged.scale === undefined ? undefined : Number(merged.scale),

package/src/page/globals.mjs

@@ -0,0 +1,37 @@
+import { ANY_FUNCTION, toSource } from "#src/page/source.mjs";
+
+const GLOBAL_PATH = /^(window\.)?[A-Za-z_$][\w$]*(\.[A-Za-z_$][\w$]*)*$/;
+const LOCALE = /^[a-z]{2,3}(-[A-Za-z\d]{2,8})*$/i;
+
+export const globalsScript = globals => {
+	const entries = Object.entries(globals).map(([path, value]) => {
+		if (!GLOBAL_PATH.test(path)) throw new Error(`globals: "${path}" must be a dotted path like window.api or window.go.main`);
+		const name = path.startsWith("window.") ? path : `window.${path}`;
+		return `assign(${JSON.stringify(name)}, ${toSource(value, name)});`;
+	});
+	return `(() => {
+	const __webviewPreviewAny = ${ANY_FUNCTION};
+	const assign = (path, value) => {
+		const parts = path.split(".").slice(1);
+		const last = parts.pop();
+		let target = window;
+		for (const part of parts) {
+			if (target[part] === undefined || target[part] === null) target[part] = {};
+			target = target[part];
+		}
+		target[last] = value;
+	}
+	${entries.join("\n\t")}
+})();`;
+}
+
+export const checkLocale = locale => {
+	if (!LOCALE.test(locale)) throw new Error(`locale must look like en-US or ru, got "${locale}"`);
+	return locale;
+}
+
+export const localeScript = locale => `(() => {
+	const language = ${JSON.stringify(checkLocale(locale))};
+	Object.defineProperty(Navigator.prototype, "language", { get: () => language, configurable: true });
+	Object.defineProperty(Navigator.prototype, "languages", { get: () => [language], configurable: true });
+})();`;

package/src/page/init.mjs

@@ -15,7 +15,7 @@ const readEntry = (entry, baseDir, index) => {
 	throw new Error(`init entries must be code strings or { file: "path" }, got ${JSON.stringify(entry)}`);
 }
 
-const wrap = ({ label, source }) => `{
+export const wrapInit = ({ label, source }) => `{
 	try {
 		${source}
 	} catch (error) {
@@ -25,7 +25,7 @@ const wrap = ({ label, source }) => `{
 
 export const resolveInit = (groups, baseDir) => groups
 	.flatMap(group => toList(group.entries).map(entry => ({ entry, baseDir: group.baseDir })))
-	.map(({ entry, baseDir: dir }, index) => wrap(readEntry(entry, dir ?? baseDir, index)));
+	.map(({ entry, baseDir: dir }, index) => wrapInit(readEntry(entry, dir ?? baseDir, index)));
 
 export const reportInitErrors = (json, log) => {
 	for (const message of JSON.parse(json || "[]")) log.error(`init failed: ${message}`);

package/src/page/source.mjs

@@ -0,0 +1,55 @@
+const ANY_API = Symbol.for("webview-preview.anyApi");
+
+export const anyApi = (members = {}) => ({ [ANY_API]: true, members });
+
+const asExpression = source => {
+	try {
+		new Function(`return (${source})`);
+		return source;
+	} catch {
+		return source.startsWith("async ") ? `async function ${source.slice(6)}` : `function ${source}`;
+	}
+}
+
+export const toSource = (value, name = "value") => {
+	if (typeof value === "function") return `(${asExpression(value.toString())})`;
+	if (value === undefined) return "undefined";
+	if (Array.isArray(value)) return `[${value.map((item, index) => toSource(item, `${name}[${index}]`)).join(", ")}]`;
+	if (value && typeof value === "object") {
+		if (value[ANY_API]) return `__webviewPreviewAny(${toSource(value.members, name)}, ${JSON.stringify(name)})`;
+		const entries = Object.entries(value).map(([key, item]) => `${JSON.stringify(key)}: ${toSource(item, `${name}.${key}`)}`);
+		return `{ ${entries.join(", ")} }`;
+	}
+	return JSON.stringify(value);
+}
+
+export const RECORD_FUNCTION = `call => (window.__webviewPreviewRequests = window.__webviewPreviewRequests || []).push(call)`;
+
+export const ANY_FUNCTION = `(members, name) => {
+	const record = ${RECORD_FUNCTION};
+	const settled = () => new Proxy(function () {}, {
+		get: (_, key) => key === "then" ? resolve => resolve(null) : key === Symbol.toPrimitive ? () => "" : settled(),
+		apply: () => settled()
+	});
+
+	const node = path => new Proxy(function () {}, {
+		get: (_, key) => {
+			if (typeof key === "symbol") return key === Symbol.toPrimitive ? () => "" : undefined;
+			if (key === "then" || key === "toJSON") return undefined;
+			if (path === name && Object.prototype.hasOwnProperty.call(members, key)) {
+				const member = members[key];
+				if (typeof member !== "function") return member;
+				return (...args) => {
+					record("call " + path + "." + key + " -> stub");
+					return member(...args);
+				}
+			}
+			return node(path + "." + key);
+		},
+		apply: () => {
+			record("call " + path + " -> default");
+			return settled();
+		}
+	});
+	return node(name);
+}`;

package/src/page/tauri.mjs

@@ -0,0 +1,95 @@
+import { ANY_FUNCTION, RECORD_FUNCTION, toSource } from "#src/page/source.mjs";
+
+const DEFAULT_COMMANDS = {
+	"plugin:app|version": "0.0.0",
+	"plugin:app|name": "app",
+	"plugin:app|tauri_version": "2.0.0",
+	"plugin:window|is_maximized": false,
+	"plugin:window|is_minimized": false,
+	"plugin:window|is_fullscreen": false,
+	"plugin:window|is_focused": true,
+	"plugin:window|is_visible": true,
+	"plugin:window|is_decorated": true,
+	"plugin:window|is_resizable": true,
+	"plugin:window|scale_factor": () => window.devicePixelRatio,
+	"plugin:window|inner_size": () => ({ width: window.innerWidth, height: window.innerHeight }),
+	"plugin:window|outer_size": () => ({ width: window.innerWidth, height: window.innerHeight })
+}
+
+export const resolveTauri = (fromConfig, fromOptions) => {
+	const pick = value => value === true ? {} : value && typeof value === "object" ? value : null;
+	const config = pick(fromConfig);
+	const options = pick(fromOptions);
+	if (!config && !options) return null;
+	return {
+		label: options?.label ?? config?.label ?? "main",
+		commands: { ...config?.commands, ...options?.commands }
+	}
+}
+
+export const tauriScript = ({ label, commands }) => `(() => {
+	const __webviewPreviewAny = ${ANY_FUNCTION};
+	const record = ${RECORD_FUNCTION};
+	const commands = Object.assign(${toSource(DEFAULT_COMMANDS)}, ${toSource(commands, "tauri")});
+	const callbacks = new Map();
+	const listeners = new Map();
+	let nextId = 1;
+
+	const transformCallback = (callback, once = false) => {
+		const id = nextId++;
+		callbacks.set(id, data => {
+			if (once) callbacks.delete(id);
+			return callback && callback(data);
+		});
+		return id;
+	}
+
+	const runCallback = (id, data) => {
+		const callback = callbacks.get(id);
+		if (callback) callback(data);
+	}
+
+	const removeListener = (event, id) => {
+		callbacks.delete(id);
+		const ids = listeners.get(event);
+		if (ids && ids.includes(id)) ids.splice(ids.indexOf(id), 1);
+	}
+
+	const emit = (event, payload) => {
+		for (const id of [...(listeners.get(event) || [])]) runCallback(id, { event, id, payload });
+	}
+
+	const events = {
+		"plugin:event|listen": ({ event, handler }) => {
+			if (!listeners.has(event)) listeners.set(event, []);
+			listeners.get(event).push(handler);
+			return handler;
+		},
+		"plugin:event|unlisten": ({ event, eventId }) => removeListener(event, eventId),
+		"plugin:event|emit": ({ event, payload }) => emit(event, payload),
+		"plugin:event|emit_to": ({ event, payload }) => emit(event, payload)
+	}
+
+	const invoke = async (command, args = {}) => {
+		if (events[command]) return events[command](args) ?? null;
+		const isKnown = Object.prototype.hasOwnProperty.call(commands, command);
+		record("invoke " + command + (isKnown ? " -> stub" : " -> null"));
+		if (!isKnown) return null;
+		const answer = commands[command];
+		return typeof answer === "function" ? answer(args) : answer;
+	}
+
+	window.__TAURI_INTERNALS__ = {
+		invoke,
+		transformCallback,
+		unregisterCallback: id => callbacks.delete(id),
+		runCallback,
+		callbacks,
+		convertFileSrc: (path, protocol = "asset") => protocol + "://localhost/" + encodeURIComponent(path),
+		metadata: { currentWindow: { label: ${JSON.stringify(label)} }, currentWebview: { windowLabel: ${JSON.stringify(label)}, label: ${JSON.stringify(label)} } },
+		plugins: { path: { sep: "/", delimiter: ":" } }
+	}
+	window.__TAURI_EVENT_PLUGIN_INTERNALS__ = { unregisterListener: removeListener }
+	window.isTauri = true;
+	window.__webviewPreview = Object.assign(window.__webviewPreview || {}, { emit });
+})();`;