webview-preview 0.0.0-stage → 0.0.1

package/bin/webview-preview.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+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 LIST_FLAGS = { "--init": "init", "--init-file": "initFile", "--mock-file": "mockFile" }
+
+const HELP = `Usage: webview-preview [route-or-url] [steps...] [options]
+       webview-preview clean [--dry-run] [--older-than 2h] [--out <dir>] [--config <file>]
+
+Opens the page in a real browser engine, runs the steps in order and saves PNG snapshots.
+
+Steps:
+  js:<code>        run JavaScript, then wait 700 ms
+  jsnow:<code>     run JavaScript, go on right away
+  wait:<ms>        wait
+  waitfor:<css selector>   wait until a matching element is visible (up to --wait-timeout)
+  waitfor:!<css selector>  wait until no matching element is visible
+  snap:<name>      save <out>/<prefix><name>.png
+  print:<expr>     print the value of an expression
+  measure:<css selector>  print size, position, box, visibility, font and text of the element
+  resize:<WxH>     resize the window
+  snap:<name>@<css selector>  save only that element (plus --snap-margin)
+  key:<key>        press a key: Tab, Shift+Tab, Enter, Escape, ArrowDown, Control+a, x …
+  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
+
+Options:
+  --engine <name>  ${ENGINES.join(" | ")} (default: auto)
+  --size <WxH>     window size in CSS pixels (default: 1200x650)
+  --out <dir>      folder for snapshots (default: .webview-preview)
+  --prefix <text>  file name prefix (default: "<engine>-")
+  --scale <n>      device pixel ratio for Playwright engines (default: 1); WebKitGTK renders
+                   1x off-screen and at the screen's scale with --headed
+  --snap-margin <px>  room around snap:name@selector (default: 8)
+  --headed         WebKitGTK: show a real window instead of rendering off-screen
+  --wait-timeout <ms>  how long waitfor waits (default: 10000)
+  --keep-storage   WebKitGTK: keep localStorage, cookies and cache between runs (default: start clean)
+  --compare        compare every snapshot with the baseline of the same name (a missing one is created)
+  --update-baseline  replace the baselines with this run's snapshots
+  --baseline <dir> baseline folder (default: webview-preview-baseline)
+  --max-diff-pixels <n>  pixels allowed to differ before the run fails (default: 0)
+  --compare-tolerance <n>  per-channel difference ignored, 0-255 (default: 2)
+  --base-url <url> prepended to routes that are not full URLs
+  --init <code>    run code before the page's own scripts, on every load (repeatable)
+  --init-file <f>  same, from a file (repeatable)
+  --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
+  --config <file>  config file (default: webview-preview.config.{mjs,js,json})
+  --no-config      ignore config files
+
+Clean:
+  clean            delete the snapshots (*.png, also *.diff.png) in the snapshot folder;
+                   baselines are never touched
+  --dry-run        only list what would be deleted
+  --older-than <t> only files older than 30m, 2h, 7d …
+
+  -h, --help       show this help
+  -v, --version    show the version`;
+
+const parseArgs = argv => {
+	const options = { steps: [] }
+	const positional = [];
+	for (let index = 0; index < argv.length; index += 1) {
+		const arg = argv[index];
+		if (arg === "-h" || arg === "--help") return { help: true }
+		if (arg === "-v" || arg === "--version") return { version: true }
+		if (arg === "--keep-storage") {
+			options.keepStorage = true;
+			continue;
+		}
+		if (arg === "--dry-run") {
+			options.dryRun = true;
+			continue;
+		}
+		if (arg === "--compare" || arg === "--update-baseline") {
+			options[arg === "--compare" ? "compare" : "updateBaseline"] = true;
+			continue;
+		}
+		if (arg === "--headed") {
+			options.headed = true;
+			continue;
+		}
+		if (arg === "--log-requests") {
+			options.logRequests = true;
+			continue;
+		}
+		if (arg === "--no-config") {
+			options.config = false;
+			continue;
+		}
+		const [flag, inline] = arg.split(/=(.*)/s, 2);
+		if (flag in LIST_FLAGS) {
+			const value = inline ?? argv[++index];
+			if (value === undefined) throw new Error(`${flag} needs a value`);
+			(options[LIST_FLAGS[flag]] ??= []).push(value);
+			continue;
+		}
+		if (flag in FLAGS) {
+			const value = inline ?? argv[++index];
+			if (value === undefined) throw new Error(`${flag} needs a value`);
+			options[FLAGS[flag]] = value;
+			continue;
+		}
+		if (arg.startsWith("--")) throw new Error(`Unknown option ${arg}`);
+		positional.push(arg);
+	}
+	const [target, ...steps] = positional;
+	return { options: { ...options, target, steps } }
+}
+
+try {
+	const parsed = parseArgs(process.argv.slice(2));
+	if (parsed.help) {
+		console.log(HELP);
+		process.exit(0);
+	}
+	if (parsed.version) {
+		console.log(JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version);
+		process.exit(0);
+	}
+	if (parsed.options.target === "clean") {
+		const { target, steps, ...cleanOptions } = parsed.options;
+		if (steps.length) throw new Error(`clean takes no steps, got ${steps.join(" ")}`);
+		const { removed, out } = await cleanSnapshots(cleanOptions);
+		for (const file of removed) console.log(file);
+		console.log(`${cleanOptions.dryRun ? "would delete" : "deleted"} ${removed.length} snapshot(s) in ${out}`);
+		process.exit(0);
+	}
+	const result = await preview(parsed.options);
+	for (const file of result.saved) console.log(file);
+	process.exit(result.failed ? 1 : 0);
+} catch (error) {
+	console.error(`webview-preview: ${error.message}`);
+	process.exit(1);
+}

package/package.json

@@ -1,6 +1,55 @@
 {
-  "name": "webview-preview",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "webview-preview",
+	"version": "0.0.1",
+	"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",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/n0t4u404/webview-preview.git"
+	},
+	"keywords": [
+		"tauri",
+		"wails",
+		"webview",
+		"webkitgtk",
+		"webview2",
+		"screenshot",
+		"visual-testing",
+		"playwright"
+	],
+	"type": "module",
+	"main": "./src/index.mjs",
+	"types": "./src/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./src/index.d.ts",
+			"default": "./src/index.mjs"
+		}
+	},
+	"imports": {
+		"#src/*": "./src/*"
+	},
+	"bin": {
+		"webview-preview": "bin/webview-preview.mjs"
+	},
+	"files": [
+		"bin",
+		"src",
+		"AGENTS.md"
+	],
+	"engines": {
+		"node": ">=18"
+	},
+	"peerDependencies": {
+		"playwright-core": "^1.40.0"
+	},
+	"peerDependenciesMeta": {
+		"playwright-core": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"playwright-core": "^1.64.1"
+	}
+}

package/src/core/config.mjs

@@ -0,0 +1,16 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const CONFIG_FILES = ["webview-preview.config.mjs", "webview-preview.config.js", "webview-preview.config.json"];
+
+export const loadConfig = async (configPath, cwd = process.cwd()) => {
+	const file = configPath
+		? path.resolve(cwd, configPath)
+		: CONFIG_FILES.map(name => path.join(cwd, name)).find(candidate => existsSync(candidate));
+	if (!file) return {}
+	if (!existsSync(file)) throw new Error(`Config not found: ${file}`);
+	if (file.endsWith(".json")) return { ...JSON.parse(readFileSync(file, "utf8")), configDir: path.dirname(file) }
+	const module = await import(pathToFileURL(file).href);
+	return { ...(module.default ?? module), configDir: path.dirname(file) }
+}

package/src/core/server.mjs

@@ -0,0 +1,57 @@
+import { spawn } from "node:child_process";
+import net from "node:net";
+
+const POLL_MS = 250;
+const DEFAULT_READY_TIMEOUT_MS = 30000;
+
+const isPortOpen = (port, host) => new Promise(resolve => {
+	const socket = net.connect(port, host);
+	socket.once("connect", () => {
+		socket.end();
+		resolve(true);
+	});
+	socket.once("error", () => resolve(false));
+});
+
+const waitForPort = async (port, host, timeoutMs) => {
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline) {
+		if (await isPortOpen(port, host)) return;
+		await new Promise(resolve => setTimeout(resolve, POLL_MS));
+	}
+	throw new Error(`Server did not open port ${port} within ${timeoutMs} ms`);
+}
+
+const stopProcessTree = child => {
+	if (child.exitCode !== null) return;
+	if (process.platform === "win32") {
+		spawn("taskkill", ["/pid", String(child.pid), "/t", "/f"], { stdio: "ignore" });
+		return;
+	}
+	try {
+		process.kill(-child.pid, "SIGTERM");
+	} catch {
+		child.kill("SIGTERM");
+	}
+}
+
+export const startServer = async server => {
+	if (!server) return () => {}
+	const { command, port, host = "localhost", cwd = process.cwd(), readyTimeoutMs = DEFAULT_READY_TIMEOUT_MS } = server;
+	if (!command || !port) throw new Error("server needs both command and port");
+	if (await isPortOpen(port, host)) return () => {}
+
+	const child = spawn(command, {
+		cwd,
+		shell: true,
+		stdio: "ignore",
+		detached: process.platform !== "win32"
+	});
+	try {
+		await waitForPort(port, host, readyTimeoutMs);
+	} catch (error) {
+		stopProcessTree(child);
+		throw error;
+	}
+	return () => stopProcessTree(child);
+}

package/src/core/steps.mjs

@@ -0,0 +1,169 @@
+export const LOAD_SETTLE_MS = 1500;
+export const JS_SETTLE_MS = 700;
+export const TIMEOUT_MS = 30000;
+export const WAIT_FOR_TIMEOUT_MS = 10000;
+export const WAIT_FOR_POLL_MS = 50;
+
+const STEP_KINDS = new Set(["js", "jsnow", "wait", "waitfor", "snap", "print", "measure", "resize", "key", "type", "hover", "click"]);
+const MODIFIERS = { Shift: "Shift", Control: "Control", Ctrl: "Control", Alt: "Alt", Meta: "Meta" }
+export const KEY_NAMES = [
+	"Tab", "Enter", "Escape", "Backspace", "Delete", "Insert", "Space", "Home", "End", "PageUp", "PageDown",
+	"ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight", ...Array.from({ length: 12 }, (_, index) => `F${index + 1}`)
+];
+
+const PRINT_FORMAT = `(value => {
+	if (typeof value === "string") return value;
+	if (value === undefined) return "undefined";
+	if (typeof Node !== "undefined" && value instanceof Node) return value.nodeType === 1 ? value.outerHTML.slice(0, 200) : String(value.nodeName);
+	try {
+		return JSON.stringify(value) ?? String(value);
+	} catch {
+		return String(value);
+	}
+})`;
+
+export const printExpression = expression => `${PRINT_FORMAT}((${expression}))`;
+
+const QUERY_FUNCTION = `selector => {
+	if (!selector.startsWith("text=")) return [...document.querySelectorAll(selector)];
+	const normalize = value => value.replace(/\\s+/g, " ").trim();
+	const wanted = normalize(selector.slice(5));
+	return [...document.body.querySelectorAll("*")].filter(element =>
+		normalize(element.textContent) === wanted
+		&& ![...element.children].some(child => normalize(child.textContent) === wanted));
+}`;
+
+const VISIBLE_FUNCTION = `element => {
+	if (element.getClientRects().length === 0) return false;
+	if (getComputedStyle(element).visibility === "hidden") return false;
+	for (let node = element; node && node.nodeType === 1; node = node.parentElement) {
+		if (getComputedStyle(node).opacity === "0") return false;
+	}
+	return true;
+}`;
+
+const waitForExpression = (selector, isGone) => `(() => {
+	const query = ${QUERY_FUNCTION};
+	const isVisible = ${VISIBLE_FUNCTION};
+	const visible = query(${JSON.stringify(selector)}).filter(isVisible);
+	if (${isGone ? "true" : "false"}) return visible.length === 0;
+	if (visible.length === 0) return false;
+	const key = "__webviewPreviewWaitFor:" + ${JSON.stringify(selector)};
+	const rects = JSON.stringify(visible.map(element => {
+		const rect = element.getBoundingClientRect();
+		let opacity = 1;
+		for (let node = element; node && node.nodeType === 1; node = node.parentElement) opacity *= Number(getComputedStyle(node).opacity);
+		return [rect.left, rect.top, rect.width, rect.height, Math.round(opacity * 1000)];
+	}));
+	const isStill = window[key] === rects;
+	window[key] = rects;
+	return isStill;
+})()`;
+
+const MEASURE_FUNCTION = `(selector, query, isVisible) => {
+	const all = query(selector);
+	if (all.length === 0) return "measure " + selector + ": no match";
+	const element = all.find(isVisible) ?? all[0];
+	const rect = element.getBoundingClientRect();
+	const style = getComputedStyle(element);
+	const round = value => Math.round(value * 100) / 100;
+	const box = name => {
+		const sides = ["top", "right", "bottom", "left"].map(side => parseFloat(style.getPropertyValue(name + "-" + side + (name === "border" ? "-width" : ""))) || 0);
+		return sides.every(side => side === sides[0]) ? String(sides[0]) : sides.join(" ");
+	};
+	const text = (element.innerText || element.value || "").replace(/\\s+/g, " ").trim().slice(0, 40);
+	return [
+		"measure " + selector + ": " + all.length + " match" + (all.length === 1 ? "" : "es") + (all.length > 1 ? ", showing " + (all.indexOf(element) + 1) : ""),
+		"x " + round(rect.left) + " y " + round(rect.top) + " w " + round(rect.width) + " h " + round(rect.height),
+		"margin " + box("margin") + " padding " + box("padding") + " border " + box("border"),
+		(isVisible(element) ? "visible" : "hidden") + " display " + style.display + " opacity " + style.opacity,
+		"font " + style.fontSize + "/" + style.fontWeight + " color " + style.color + " bg " + style.backgroundColor,
+		...(text ? ['text "' + text + '"'] : [])
+	].join(" · ");
+}`;
+
+const measureExpression = selector => `(${MEASURE_FUNCTION})(${JSON.stringify(selector)}, ${QUERY_FUNCTION}, ${VISIBLE_FUNCTION})`;
+
+const rectExpression = (selector, isScrolled) => `(() => {
+	const query = ${QUERY_FUNCTION};
+	const isVisible = ${VISIBLE_FUNCTION};
+	const all = query(${JSON.stringify(selector)});
+	const visible = all.filter(isVisible);
+	const isOnTop = element => {
+		const rect = element.getBoundingClientRect();
+		const hit = document.elementFromPoint(rect.left + rect.width / 2, rect.top + rect.height / 2);
+		return !!hit && (element === hit || element.contains(hit));
+	};
+	const element = visible.find(isOnTop) ?? visible[0] ?? all[0];
+	if (!element) return "null";
+	${isScrolled ? "element.scrollIntoView({ block: \"nearest\", inline: \"nearest\" });" : ""}
+	const rect = element.getBoundingClientRect();
+	return JSON.stringify({ x: rect.left, y: rect.top, width: rect.width, height: rect.height });
+})()`;
+
+const parseKey = combo => {
+	const parts = combo.split("+");
+	const key = parts.pop();
+	const modifiers = parts.map(part => {
+		if (!(part in MODIFIERS)) throw new Error(`Unknown modifier "${part}" in key:${combo}. Modifiers: Shift, Control, Alt, Meta`);
+		return MODIFIERS[part];
+	});
+	if (!key || (key.length > 1 && !KEY_NAMES.includes(key))) throw new Error(`Unknown key "${key}" in key:${combo}. Keys: a single character or ${KEY_NAMES.join(", ")}`);
+	return { key, modifiers }
+}
+
+export const parseSize = value => {
+	const match = /^(\d+)x(\d+)$/.exec(String(value));
+	if (!match) throw new Error(`Size must look like 1200x650, got "${value}"`);
+	return { width: Number(match[1]), height: Number(match[2]) }
+}
+
+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 (kind === "wait" && !/^\d+$/.test(value)) throw new Error(`wait needs milliseconds, got "${step}"`);
+	if (kind === "resize") parseSize(value);
+	if (kind === "snap") {
+		const at = value.indexOf("@");
+		const name = at === -1 ? value : value.slice(0, at);
+		if (!name) throw new Error(`snap needs a name, got "${step}"`);
+		if (at === -1) return { kind, value: name }
+		const selector = value.slice(at + 1);
+		if (!selector) throw new Error(`snap:name@selector needs a selector, got "${step}"`);
+		return { kind, value: name, selector, rect: rectExpression(selector, false) }
+	}
+	if (kind === "hover" || kind === "click") {
+		if (!value) throw new Error(`${kind} needs a selector, got "${step}"`);
+		return { kind, value, rect: rectExpression(value, true) }
+	}
+	if (kind === "key") return { kind, value, ...parseKey(value) }
+	if (kind === "waitfor") {
+		const isGone = value.startsWith("!");
+		const selector = isGone ? value.slice(1) : value;
+		if (!selector) throw new Error(`waitfor needs a selector, got "${step}"`);
+		return { kind, value, check: waitForExpression(selector, isGone) }
+	}
+	if (kind === "measure") {
+		if (!value) throw new Error(`measure needs a selector, got "${step}"`);
+		return { kind: "print", value: printExpression(measureExpression(value)) }
+	}
+	if (kind === "type" && !value) throw new Error(`type needs text, got "${step}"`);
+	return { kind, value: kind === "print" ? printExpression(value) : value }
+});
+export const parseRect = (json, selector) => {
+	const rect = json && json !== "null" ? JSON.parse(json) : null;
+	if (!rect) throw new Error(`no element matches ${selector}`);
+	if (rect.width <= 0 || rect.height <= 0) throw new Error(`${selector} has no size (hidden?)`);
+	return rect;
+}
+
+export const clipRect = (rect, margin, viewport) => {
+	const left = Math.max(0, Math.floor(rect.x - margin));
+	const top = Math.max(0, Math.floor(rect.y - margin));
+	const right = Math.min(viewport.width, Math.ceil(rect.x + rect.width + margin));
+	const bottom = Math.min(viewport.height, Math.ceil(rect.y + rect.height + margin));
+	if (right <= left || bottom <= top) throw new Error("element is outside the window");
+	return { x: left, y: top, width: right - left, height: bottom - top }
+}

package/src/engines/index.mjs

@@ -0,0 +1,17 @@
+import { isWebkitGtkAvailable, runWebkitGtk } from "#src/engines/webkitgtk.mjs";
+import { runPlaywright } from "#src/engines/playwright.mjs";
+
+export const ENGINES = ["auto", "webkitgtk", "msedge", "chrome", "chromium", "webkit"];
+
+export const resolveEngine = engine => {
+	if (!ENGINES.includes(engine)) throw new Error(`Unknown engine "${engine}". Engines: ${ENGINES.join(", ")}`);
+	if (engine !== "auto") return engine;
+	if (isWebkitGtkAvailable()) return "webkitgtk";
+	if (process.platform === "win32") return "msedge";
+	if (process.platform === "darwin") return "webkit";
+	throw new Error("No engine found for auto: install WebKitGTK for Python (python3-gi, gir1.2-webkit2-4.1) or pass --engine chrome / chromium");
+}
+
+export const runEngine = (engine, options) => engine === "webkitgtk"
+	? runWebkitGtk(options)
+	: runPlaywright({ engine, ...options });

package/src/engines/playwright.mjs

@@ -0,0 +1,104 @@
+import path from "node:path";
+import { INIT_ERRORS_EXPRESSION, reportInitErrors } from "#src/page/init.mjs";
+import { clipRect, JS_SETTLE_MS, LOAD_SETTLE_MS, parseRect, parseSize, TIMEOUT_MS, WAIT_FOR_POLL_MS, WAIT_FOR_TIMEOUT_MS } from "#src/core/steps.mjs";
+
+const CHANNELS = {
+	msedge: "msedge",
+	chrome: "chrome",
+	chromium: undefined
+}
+
+const loadPlaywright = async () => {
+	try {
+		return await import("playwright-core");
+	} catch {
+		throw new Error("This engine needs playwright-core: npm i -D playwright-core");
+	}
+}
+
+export const runPlaywright = async ({ engine, url, steps, init = [], size, 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 });
+	const saved = [];
+	let failed = false;
+
+	try {
+		const page = await browser.newPage({ viewport: parseSize(size), deviceScaleFactor: scale ?? 1 });
+		page.setDefaultTimeout(TIMEOUT_MS);
+		for (const content of init) await page.addInitScript({ content });
+		await page.goto(url, { waitUntil: "load" });
+		await page.waitForTimeout(LOAD_SETTLE_MS);
+		if (init.length) reportInitErrors(await page.evaluate(INIT_ERRORS_EXPRESSION), log);
+
+		const evaluate = async code => {
+			try {
+				return { value: await page.evaluate(code) }
+			} catch (error) {
+				return { error: error.message.split("\n")[0] }
+			}
+		}
+
+		const elementRect = async step => {
+			const result = await evaluate(step.rect);
+			if (result.error) throw new Error(`${step.kind}:${step.value} failed: ${result.error}`);
+			return parseRect(result.value, step.selector ?? step.value);
+		}
+
+		const runStep = async step => {
+			const { kind, value } = step;
+			if (kind === "snap") {
+				const file = path.join(out, `${prefix}${value}.png`);
+				const clip = step.selector ? clipRect(await elementRect(step), snapMargin, page.viewportSize()) : undefined;
+				await page.screenshot({ path: file, clip });
+				saved.push(file);
+			} else if (kind === "hover" || kind === "click") {
+				const rect = await elementRect(step);
+				const x = rect.x + rect.width / 2;
+				const y = rect.y + rect.height / 2;
+				if (kind === "hover") await page.mouse.move(x, y);
+				else await page.mouse.click(x, y);
+			} else if (kind === "key") {
+				await page.keyboard.press([...step.modifiers, step.key === " " ? "Space" : step.key].join("+"));
+			} else if (kind === "type") {
+				await page.keyboard.type(value);
+			} else if (kind === "js" || kind === "jsnow") {
+				const result = await evaluate(value);
+				if (result.error) log.error(`js failed: ${result.error}`);
+				if (kind === "js") await page.waitForTimeout(JS_SETTLE_MS);
+			} else if (kind === "waitfor") {
+				try {
+					await page.waitForFunction(step.check, undefined, { timeout: waitForTimeoutMs, polling: WAIT_FOR_POLL_MS });
+				} catch (error) {
+					throw new Error(/Timeout/i.test(error.message)
+						? `waitfor:${value} timed out after ${waitForTimeoutMs} ms`
+						: `waitfor:${value} failed: ${error.message.split("\n")[0]}`);
+				}
+			} else if (kind === "wait") {
+				await page.waitForTimeout(Number(value));
+			} else if (kind === "resize") {
+				await page.setViewportSize(parseSize(value));
+			} else if (kind === "print") {
+				const result = await evaluate(value);
+				if (result.error) log.error(`print failed: ${result.error}`);
+				else log.info(String(result.value));
+			}
+		}
+
+		for (const step of steps) {
+			try {
+				await runStep(step);
+			} catch (error) {
+				failed = true;
+				log.error(error.message.split("\n")[0]);
+			}
+		}
+	} catch (error) {
+		failed = true;
+		log.error(error.message);
+	} finally {
+		await browser.close();
+	}
+
+	return { saved, failed }
+}

package/src/engines/webkitgtk.mjs

@@ -0,0 +1,67 @@
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { INIT_ERRORS_EXPRESSION, reportInitErrors } from "#src/page/init.mjs";
+import { JS_SETTLE_MS, LOAD_SETTLE_MS, parseSize, TIMEOUT_MS, WAIT_FOR_POLL_MS, WAIT_FOR_TIMEOUT_MS } from "#src/core/steps.mjs";
+
+const SCRIPT = fileURLToPath(new URL("./webkitgtk.py", import.meta.url));
+const PROBE = "import gi; gi.require_version('Gtk', '3.0'); gi.require_version('WebKit2', '4.1')";
+
+export const isWebkitGtkAvailable = () => process.platform === "linux"
+	&& spawnSync("python3", ["-c", PROBE], { stdio: "ignore" }).status === 0;
+
+export const runWebkitGtk = ({ url, steps, init = [], size, out, prefix, snapMargin = 8, isHeaded = false, isStorageKept = false, waitForTimeoutMs = WAIT_FOR_TIMEOUT_MS, timeoutMs = TIMEOUT_MS, log }) => new Promise((resolve, reject) => {
+	if (!isWebkitGtkAvailable()) {
+		reject(new Error("WebKitGTK engine needs Linux with python3-gi and WebKit2 4.1 (gir1.2-webkit2-4.1)"));
+		return;
+	}
+
+	const { width, height } = parseSize(size);
+	const child = spawn("python3", [
+		SCRIPT, url,
+		"--steps", JSON.stringify(steps),
+		"--init", JSON.stringify(init),
+		"--init-errors", INIT_ERRORS_EXPRESSION,
+		"--out", out,
+		"--prefix", prefix,
+		"--width", String(width),
+		"--height", String(height),
+		"--snap-margin", String(snapMargin),
+		...(isHeaded ? ["--headed"] : []),
+		...(isStorageKept ? ["--keep-storage"] : []),
+		"--wait-for-timeout-ms", String(waitForTimeoutMs),
+		"--wait-for-poll-ms", String(WAIT_FOR_POLL_MS),
+		"--load-settle-ms", String(LOAD_SETTLE_MS),
+		"--js-settle-ms", String(JS_SETTLE_MS),
+		"--timeout-ms", String(timeoutMs)
+	], {
+		stdio: ["ignore", "pipe", "pipe"],
+		env: { PYTHONUNBUFFERED: "1", ...process.env }
+	});
+
+	const saved = [];
+	let buffer = "";
+	child.stdout.setEncoding("utf8");
+	child.stdout.on("data", chunk => {
+		buffer += chunk;
+		const lines = buffer.split("\n");
+		buffer = lines.pop() ?? "";
+		for (const line of lines) {
+			const tab = line.indexOf("\t");
+			if (tab === -1) continue;
+			const kind = line.slice(0, tab);
+			const value = JSON.parse(line.slice(tab + 1));
+			if (kind === "saved") saved.push(value);
+			else if (kind === "print") log.info(value);
+			else if (kind === "error") log.error(value);
+			else if (kind === "init-errors") reportInitErrors(value, log);
+		}
+	});
+	child.stderr.setEncoding("utf8");
+	child.stderr.on("data", chunk => {
+		for (const line of chunk.split("\n")) {
+			if (line.trim() && !/Gdk-(WARNING|CRITICAL)/.test(line)) process.stderr.write(`${line}\n`);
+		}
+	});
+	child.once("error", reject);
+	child.once("exit", code => resolve({ saved, failed: code !== 0 }));
+});