webview-preview 0.0.0-stage → 0.0.1

package/src/engines/webkitgtk.py

@@ -0,0 +1,318 @@
+import argparse
+import json
+import os
+import sys
+
+os.environ.setdefault("GDK_BACKEND", "x11")
+
+import gi
+
+gi.require_version("Gdk", "3.0")
+gi.require_version("Gtk", "3.0")
+gi.require_version("WebKit2", "4.1")
+
+from gi.repository import Gdk, GLib, Gtk, WebKit2
+
+INPUT_SETTLE_MS = 50
+GDK_KEY_NAMES = {
+    "Tab": "Tab", "Enter": "Return", "Escape": "Escape", "Backspace": "BackSpace", "Delete": "Delete",
+    "Insert": "Insert", "Space": "space", "Home": "Home", "End": "End", "PageUp": "Page_Up", "PageDown": "Page_Down",
+    "ArrowUp": "Up", "ArrowDown": "Down", "ArrowLeft": "Left", "ArrowRight": "Right",
+    **{f"F{number}": f"F{number}" for number in range(1, 13)}
+}
+MODIFIER_KEYS = {"Shift": "Shift_L", "Control": "Control_L", "Alt": "Alt_L", "Meta": "Super_L"}
+MODIFIER_MASKS = {
+    "Shift": Gdk.ModifierType.SHIFT_MASK,
+    "Control": Gdk.ModifierType.CONTROL_MASK,
+    "Alt": Gdk.ModifierType.MOD1_MASK,
+    "Meta": Gdk.ModifierType.SUPER_MASK
+}
+
+
+def emit(kind, value):
+    sys.stdout.write(f"{kind}\t{json.dumps(value)}\n")
+    sys.stdout.flush()
+
+
+def parse_args():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("url")
+    parser.add_argument("--steps", required=True)
+    parser.add_argument("--init", required=True)
+    parser.add_argument("--init-errors", required=True)
+    parser.add_argument("--out", required=True)
+    parser.add_argument("--prefix", required=True)
+    parser.add_argument("--width", type=int, required=True)
+    parser.add_argument("--height", type=int, required=True)
+    parser.add_argument("--snap-margin", type=int, required=True)
+    parser.add_argument("--headed", action="store_true")
+    parser.add_argument("--keep-storage", action="store_true")
+    parser.add_argument("--wait-for-timeout-ms", type=int, required=True)
+    parser.add_argument("--wait-for-poll-ms", type=int, required=True)
+    parser.add_argument("--load-settle-ms", type=int, required=True)
+    parser.add_argument("--js-settle-ms", type=int, required=True)
+    parser.add_argument("--timeout-ms", type=int, required=True)
+    return parser.parse_args()
+
+
+def describe(value):
+    if value.is_string():
+        return value.to_string()
+    if value.is_undefined():
+        return "undefined"
+    return value.to_json(0) or value.to_string()
+
+
+def keyval_for(key):
+    if key in GDK_KEY_NAMES:
+        return Gdk.keyval_from_name(GDK_KEY_NAMES[key])
+    return Gdk.unicode_to_keyval(ord(key))
+
+
+def main():
+    args = parse_args()
+    steps = json.loads(args.steps)
+    init_scripts = json.loads(args.init)
+    os.makedirs(args.out, exist_ok=True)
+
+    window = Gtk.Window(title="webview-preview") if args.headed else Gtk.OffscreenWindow()
+    window.set_default_size(args.width, args.height)
+    window.set_size_request(args.width, args.height)
+    manager = WebKit2.UserContentManager()
+    for source in init_scripts:
+        manager.add_script(WebKit2.UserScript.new(
+            source,
+            WebKit2.UserContentInjectedFrames.TOP_FRAME,
+            WebKit2.UserScriptInjectionTime.START,
+            None,
+            None
+        ))
+    view = WebKit2.WebView(user_content_manager=manager, is_ephemeral=not args.keep_storage)
+    window.add(view)
+    window.show_all()
+
+    display = Gdk.Display.get_default()
+    seat = display.get_default_seat()
+    keymap = Gdk.Keymap.get_for_display(display)
+    state = {"index": 0, "failed": False, "started": False}
+
+    def finish(failed=False):
+        state["failed"] = state["failed"] or failed
+        Gtk.main_quit()
+        return False
+
+    def step_failed(message):
+        state["failed"] = True
+        emit("error", message)
+
+    def deliver(event):
+        if args.headed:
+            Gtk.main_do_event(event)
+        else:
+            window.event(event)
+
+    def focus_window():
+        event = Gdk.Event.new(Gdk.EventType.FOCUS_CHANGE)
+        event.focus_change.window = window.get_window()
+        event.focus_change.send_event = 1
+        event.focus_change.in_ = 1
+        event.set_device(seat.get_keyboard())
+        deliver(event)
+        view.grab_focus()
+
+    def key_event(kind, keyval, mask):
+        found, entries = keymap.get_entries_for_keyval(keyval)
+        event = Gdk.Event.new(kind)
+        event.key.window = window.get_window()
+        event.key.send_event = 1
+        event.key.time = Gtk.get_current_event_time()
+        event.key.keyval = keyval
+        event.key.state = mask
+        if found and entries:
+            event.key.hardware_keycode = entries[0].keycode
+        event.set_device(seat.get_keyboard())
+        deliver(event)
+
+    def press(keyval, modifiers=()):
+        mask = Gdk.ModifierType(0)
+        for modifier in modifiers:
+            key_event(Gdk.EventType.KEY_PRESS, Gdk.keyval_from_name(MODIFIER_KEYS[modifier]), mask)
+            mask |= MODIFIER_MASKS[modifier]
+        key_event(Gdk.EventType.KEY_PRESS, keyval, mask)
+        key_event(Gdk.EventType.KEY_RELEASE, keyval, mask)
+        for modifier in reversed(modifiers):
+            key_event(Gdk.EventType.KEY_RELEASE, Gdk.keyval_from_name(MODIFIER_KEYS[modifier]), mask)
+            mask &= ~MODIFIER_MASKS[modifier]
+
+    def mouse(kind, x, y):
+        event = Gdk.Event.new(kind)
+        fields = event.motion if kind == Gdk.EventType.MOTION_NOTIFY else event.button
+        if kind != Gdk.EventType.MOTION_NOTIFY:
+            fields.button = 1
+        fields.window = view.get_window()
+        fields.send_event = 1
+        fields.x = x
+        fields.y = y
+        fields.time = Gtk.get_current_event_time()
+        event.set_device(seat.get_pointer())
+        view.event(event)
+
+    def full_pixbuf():
+        if args.headed:
+            return Gdk.pixbuf_get_from_window(
+                view.get_window(), 0, 0, view.get_allocated_width(), view.get_allocated_height()
+            )
+        return window.get_pixbuf()
+
+    def save(name, pixbuf):
+        path = os.path.join(args.out, f"{args.prefix}{name}.png")
+        pixbuf.savev(path, "png", [], [])
+        emit("saved", path)
+
+    def evaluate(code, on_value, on_error):
+        def on_result(webview, result):
+            try:
+                on_value(describe(webview.evaluate_javascript_finish(result)))
+            except Exception as error:
+                on_error(str(error))
+
+        view.evaluate_javascript(code, -1, None, None, None, on_result)
+
+    def with_rect(step, use):
+        selector = step.get("selector") or step["value"]
+
+        def on_value(text):
+            rect = json.loads(text) if text and text != "null" else None
+            if not rect:
+                step_failed(f"{step['kind']}:{step['value']} failed: no element matches {selector}")
+                return next_step()
+            if rect["width"] <= 0 or rect["height"] <= 0:
+                step_failed(f"{step['kind']}:{step['value']} failed: {selector} has no size (hidden?)")
+                return next_step()
+            use(rect)
+
+        evaluate(step["rect"], on_value, lambda error: (step_failed(f"{step['kind']}:{step['value']} failed: {error}"), next_step()))
+
+    def snap_element(step, rect):
+        pixbuf = full_pixbuf()
+        width, height = view.get_allocated_width(), view.get_allocated_height()
+        scale = pixbuf.get_width() / width
+        margin = args.snap_margin
+        left = max(0, int(rect["x"] - margin))
+        top = max(0, int(rect["y"] - margin))
+        right = min(width, int(rect["x"] + rect["width"] + margin + 0.999))
+        bottom = min(height, int(rect["y"] + rect["height"] + margin + 0.999))
+        if right <= left or bottom <= top:
+            step_failed(f"snap:{step['value']} failed: element is outside the window")
+            return next_step()
+        cropped = pixbuf.new_subpixbuf(
+            int(left * scale), int(top * scale), int((right - left) * scale), int((bottom - top) * scale)
+        ).copy()
+        save(step["value"], cropped)
+        next_step()
+
+    def point_at(step, rect):
+        x = rect["x"] + rect["width"] / 2
+        y = rect["y"] + rect["height"] / 2
+        mouse(Gdk.EventType.MOTION_NOTIFY, x, y)
+        if step["kind"] == "click":
+            mouse(Gdk.EventType.BUTTON_PRESS, x, y)
+            mouse(Gdk.EventType.BUTTON_RELEASE, x, y)
+        GLib.timeout_add(INPUT_SETTLE_MS, run_step)
+
+    def wait_for(step, started):
+        def on_value(text):
+            if text == "true":
+                return next_step()
+            if (GLib.get_monotonic_time() - started) / 1000 >= args.wait_for_timeout_ms:
+                step_failed(f"waitfor:{step['value']} timed out after {args.wait_for_timeout_ms} ms")
+                return next_step()
+            GLib.timeout_add(args.wait_for_poll_ms, lambda: (wait_for(step, started), False)[1])
+
+        evaluate(step["check"], on_value, lambda error: (step_failed(f"waitfor:{step['value']} failed: {error}"), next_step()))
+
+    def next_step():
+        GLib.idle_add(run_step)
+
+    def run_step():
+        if state["index"] >= len(steps):
+            return finish()
+        step = steps[state["index"]]
+        state["index"] += 1
+        kind, value = step["kind"], step["value"]
+
+        if kind == "snap":
+            if step.get("selector"):
+                with_rect(step, lambda rect: snap_element(step, rect))
+            else:
+                save(value, full_pixbuf())
+                next_step()
+        elif kind in ("js", "jsnow"):
+            evaluate(value, lambda _: None, lambda error: emit("error", f"js failed: {error}"))
+            if kind == "js":
+                GLib.timeout_add(args.js_settle_ms, run_step)
+            else:
+                next_step()
+        elif kind == "wait":
+            GLib.timeout_add(int(value), run_step)
+        elif kind == "waitfor":
+            wait_for(step, GLib.get_monotonic_time())
+        elif kind == "resize":
+            width, height = (int(part) for part in value.split("x"))
+            window.set_size_request(width, height)
+            window.resize(width, height)
+            GLib.timeout_add(INPUT_SETTLE_MS, run_step)
+        elif kind == "print":
+            evaluate(
+                value,
+                lambda text: (emit("print", text), next_step()),
+                lambda error: (emit("error", f"print failed: {error}"), next_step())
+            )
+        elif kind in ("hover", "click"):
+            with_rect(step, lambda rect: point_at(step, rect))
+        elif kind == "key":
+            press(keyval_for(step["key"]), step["modifiers"])
+            GLib.timeout_add(INPUT_SETTLE_MS, run_step)
+        elif kind == "type":
+            for character in value:
+                press(Gdk.unicode_to_keyval(ord(character)))
+            GLib.timeout_add(INPUT_SETTLE_MS, run_step)
+        return False
+
+    def start_steps():
+        focus_window()
+        if not init_scripts:
+            return run_step()
+        evaluate(
+            args.init_errors,
+            lambda text: (emit("init-errors", text), next_step()),
+            lambda error: (emit("error", f"init check failed: {error}"), next_step())
+        )
+        return False
+
+    def on_load_changed(_view, event):
+        if event == WebKit2.LoadEvent.FINISHED and not state["started"]:
+            state["started"] = True
+            GLib.timeout_add(args.load_settle_ms, start_steps)
+
+    def on_load_failed(_view, _event, uri, error):
+        emit("error", f"failed to load {uri}: {error.message}")
+        return finish(failed=True)
+
+    def on_timeout():
+        emit("error", f"timed out after {args.timeout_ms} ms")
+        return finish(failed=True)
+
+    view.connect("load-changed", on_load_changed)
+    view.connect("load-failed", on_load_failed)
+    view.load_uri(args.url)
+    GLib.timeout_add(args.timeout_ms, on_timeout)
+    Gtk.main()
+
+    sys.stdout.flush()
+    sys.stderr.flush()
+    os._exit(1 if state["failed"] else 0)
+
+
+if __name__ == "__main__":
+    main()

package/src/index.d.ts

@@ -0,0 +1,86 @@
+export type Engine = "auto" | "webkitgtk" | "msedge" | "chrome" | "chromium" | "webkit";
+
+export type Step =
+	| `js:${string}`
+	| `jsnow:${string}`
+	| `wait:${number}`
+	| `waitfor:${string}`
+	| `measure:${string}`
+	| `snap:${string}`
+	| `print:${string}`
+	| `resize:${number}x${number}`
+	| `key:${string}`
+	| `type:${string}`
+	| `hover:${string}`
+	| `click:${string}`;
+
+export interface ServerOptions {
+	command: string;
+	port: number;
+	host?: string;
+	cwd?: string;
+	readyTimeoutMs?: number;
+}
+
+export interface PreviewConfig {
+	baseUrl?: string;
+	server?: ServerOptions;
+	engine?: Engine;
+	size?: `${number}x${number}`;
+	out?: string;
+	prefix?: string;
+	scale?: number;
+	init?: InitEntry | InitEntry[];
+	mock?: Record<string, MockResponse>;
+	logRequests?: boolean;
+	headed?: boolean;
+	keepStorage?: boolean;
+	waitTimeout?: number;
+	snapMargin?: number;
+	compare?: boolean;
+	updateBaseline?: boolean;
+	baseline?: string;
+	maxDiffPixels?: number;
+	compareTolerance?: number;
+}
+
+export interface MockResponse {
+	status?: number;
+	json?: unknown;
+	body?: string;
+	headers?: Record<string, string>;
+	delayMs?: number;
+}
+
+export type InitEntry = string | { file: string }
+
+export interface PreviewOptions extends PreviewConfig {
+	target?: string;
+	steps?: Step[] | string[];
+	initFile?: string | string[];
+	mockFile?: string | string[];
+	config?: string | false;
+	log?: { info: (message: string) => void; error: (message: string) => void }
+}
+
+export interface PreviewResult {
+	engine: Exclude<Engine, "auto">;
+	url: string;
+	saved: string[];
+	failed: boolean;
+}
+
+export declare const ENGINES: Engine[];
+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 interface CleanOptions {
+	config?: string | false;
+	out?: string;
+	baseline?: string;
+	olderThan?: string;
+	dryRun?: boolean;
+}
+
+export declare function cleanSnapshots(options?: CleanOptions): Promise<{ removed: string[]; out: string }>;

package/src/index.mjs

@@ -0,0 +1,81 @@
+import { mkdirSync } from "node:fs";
+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 { compileMock, mockScript, resolveMockFiles } from "#src/page/mock.mjs";
+import { startServer } from "#src/core/server.mjs";
+import { parseSize, parseSteps } from "#src/core/steps.mjs";
+
+export { ENGINES } from "#src/engines/index.mjs";
+export { REQUESTS_KEY } from "#src/page/mock.mjs";
+export { cleanSnapshots } from "#src/snapshots/clean.mjs";
+
+const DEFAULTS = { engine: "auto", size: "1200x650", out: ".webview-preview", steps: ["snap:page"] }
+const ABSOLUTE_URL = /^[a-z][a-z\d+.-]*:/i;
+
+const consoleLog = {
+	info: message => console.log(message),
+	error: message => console.error(message)
+}
+
+export const resolveUrl = (target, baseUrl) => {
+	if (ABSOLUTE_URL.test(target)) return target;
+	if (!baseUrl) throw new Error(`"${target}" is not a full URL; set baseUrl to open routes`);
+	return `${baseUrl}${target.startsWith("/") ? target : `/${target}`}`;
+}
+
+export const preview = async (options = {}) => {
+	const config = options.config === false ? {} : await loadConfig(options.config);
+	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 out = path.resolve(baseDir, merged.out);
+	const url = resolveUrl(merged.target ?? merged.url ?? "/", merged.baseUrl);
+	parseSize(merged.size);
+	const mockFiles = await resolveMockFiles(options.mockFile, process.cwd());
+	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([
+		{ entries: config.init, baseDir },
+		{ entries: options.init, baseDir: process.cwd() },
+		{ entries: options.initFile && [].concat(options.initFile).map(file => ({ file })), baseDir: process.cwd() }
+	], baseDir));
+	mkdirSync(out, { recursive: true });
+
+	const server = merged.server && { cwd: baseDir, ...merged.server }
+	const stopServer = await startServer(server);
+	try {
+		const result = await runEngine(engine, {
+			url,
+			steps,
+			init,
+			size: merged.size,
+			out,
+			prefix: merged.prefix ?? `${engine}-`,
+			scale: merged.scale === undefined ? undefined : Number(merged.scale),
+			snapMargin: Number(merged.snapMargin ?? 8),
+			isHeaded: !!merged.headed,
+			isStorageKept: !!merged.keepStorage,
+			waitForTimeoutMs: Number(merged.waitTimeout ?? 10000),
+			log: merged.log ?? consoleLog
+		});
+		const shouldCompare = !!(merged.compare || merged.updateBaseline);
+		const compareFailed = shouldCompare && compareSnapshots({
+			saved: result.saved,
+			baselineDir: path.resolve(baseDir, merged.baseline ?? "webview-preview-baseline"),
+			updateBaseline: !!merged.updateBaseline,
+			tolerance: Number(merged.compareTolerance ?? 2),
+			maxDiffPixels: Number(merged.maxDiffPixels ?? 0),
+			log: merged.log ?? consoleLog
+		});
+		return { engine, url, ...result, failed: result.failed || compareFailed }
+	} finally {
+		stopServer();
+	}
+}
+
+export const defineConfig = config => config;

package/src/page/init.mjs

@@ -0,0 +1,32 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+const ERRORS_KEY = "__webviewPreviewInitErrors";
+export const INIT_ERRORS_EXPRESSION = `JSON.stringify(window.${ERRORS_KEY} || [])`;
+const toList = value => value === undefined || value === null ? [] : Array.isArray(value) ? value : [value];
+
+const readEntry = (entry, baseDir, index) => {
+	if (typeof entry === "string") return { label: `init[${index}]`, source: entry }
+	if (entry && typeof entry.file === "string") {
+		const file = path.resolve(baseDir, entry.file);
+		if (!existsSync(file)) throw new Error(`init file not found: ${file}`);
+		return { label: path.basename(file), source: readFileSync(file, "utf8") }
+	}
+	throw new Error(`init entries must be code strings or { file: "path" }, got ${JSON.stringify(entry)}`);
+}
+
+const wrap = ({ label, source }) => `{
+	try {
+		${source}
+	} catch (error) {
+		(window.${ERRORS_KEY} = window.${ERRORS_KEY} || []).push(${JSON.stringify(label)} + ": " + (error && error.message || error));
+	}
+}`;
+
+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)));
+
+export const reportInitErrors = (json, log) => {
+	for (const message of JSON.parse(json || "[]")) log.error(`init failed: ${message}`);
+}

package/src/page/mock.mjs

@@ -0,0 +1,117 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const METHODS = new Set(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]);
+const RESPONSE_KEYS = new Set(["status", "json", "body", "headers", "delayMs"]);
+export const REQUESTS_KEY = "__webviewPreviewRequests";
+
+const globToRegExp = pattern => {
+	const source = pattern
+		.split(/(\*\*|\*)/)
+		.map(part => part === "**" ? ".*" : part === "*" ? "[^/]*" : part.replace(/[.+?^${}()|[\]\\]/g, "\\$&"))
+		.join("");
+	return `^${source}$`;
+}
+
+const parseKey = key => {
+	const [first, ...rest] = key.trim().split(/\s+/);
+	const hasMethod = METHODS.has(first.toUpperCase()) && rest.length > 0;
+	const pattern = hasMethod ? rest.join(" ") : key.trim();
+	return {
+		method: hasMethod ? first.toUpperCase() : null,
+		pattern,
+		regex: globToRegExp(pattern),
+		isFullUrl: /^https?:\/\//i.test(pattern),
+		withQuery: pattern.includes("?")
+	}
+}
+
+const parseResponse = (key, response) => {
+	if (!response || typeof response !== "object") throw new Error(`mock "${key}" must be an object like { json: … } or { status: 500 }`);
+	const unknown = Object.keys(response).filter(name => !RESPONSE_KEYS.has(name));
+	if (unknown.length) throw new Error(`mock "${key}": unknown field ${unknown.join(", ")}; use ${[...RESPONSE_KEYS].join(", ")}`);
+	if ("json" in response && "body" in response) throw new Error(`mock "${key}": use json or body, not both`);
+	const isJson = "json" in response;
+	return {
+		status: response.status ?? 200,
+		body: isJson ? JSON.stringify(response.json) : String(response.body ?? ""),
+		headers: { ...(isJson ? { "content-type": "application/json" } : {}), ...(response.headers ?? {}) },
+		delayMs: response.delayMs ?? 0
+	}
+}
+
+export const loadMockFile = async file => {
+	if (!existsSync(file)) throw new Error(`mock file not found: ${file}`);
+	if (file.endsWith(".json")) return JSON.parse(readFileSync(file, "utf8"));
+	const module = await import(pathToFileURL(file).href);
+	return module.default ?? module;
+}
+
+export const compileMock = mocks => Object.entries(Object.assign({}, ...mocks.filter(Boolean)))
+	.map(([key, response]) => ({ key, ...parseKey(key), ...parseResponse(key, response) }));
+
+export const resolveMockFiles = async (files, baseDir) => Promise.all(
+	[].concat(files ?? []).map(file => loadMockFile(path.resolve(baseDir, file)))
+);
+
+export const mockScript = rules => `(() => {
+	const rules = ${JSON.stringify(rules)}.map(rule => ({ ...rule, regex: new RegExp(rule.regex) }));
+	const requests = window.${REQUESTS_KEY} = window.${REQUESTS_KEY} || [];
+	const find = (method, url) => {
+		const address = new URL(url, location.href);
+		return rules.find(rule => {
+			if (rule.method && rule.method !== method) return false;
+			const base = rule.isFullUrl ? address.origin + address.pathname : address.pathname;
+			return rule.regex.test(rule.withQuery ? base + address.search : base);
+		});
+	}
+	
+	const record = (method, url, rule) => {
+		const address = new URL(url, location.href);
+		const shown = address.origin === location.origin ? address.pathname + address.search : address.href;
+		requests.push(method + " " + shown + (rule ? " -> mock " + rule.status : " -> network"));
+	}
+	const wait = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+	const originalFetch = window.fetch.bind(window);
+	window.fetch = async (input, init) => {
+		const url = typeof input === "string" || input instanceof URL ? String(input) : input.url;
+		const method = String(init && init.method || input && input.method || "GET").toUpperCase();
+		const rule = find(method, url);
+		record(method, url, rule);
+		if (!rule) return originalFetch(input, init);
+		if (rule.delayMs) await wait(rule.delayMs);
+		return new Response(rule.status === 204 || rule.status === 304 ? null : rule.body, { status: rule.status, headers: rule.headers });
+	}
+
+	const define = (target, name, value) => Object.defineProperty(target, name, { value, configurable: true });
+	const originalOpen = XMLHttpRequest.prototype.open;
+	const originalSend = XMLHttpRequest.prototype.send;
+	XMLHttpRequest.prototype.open = function (method, url, ...rest) {
+		this.__webviewPreview = { method: String(method).toUpperCase(), url: String(url) }
+		return originalOpen.call(this, method, url, ...rest);
+	}
+	
+	XMLHttpRequest.prototype.send = function (body) {
+		const info = this.__webviewPreview;
+		const rule = info && find(info.method, info.url);
+		if (info) record(info.method, info.url, rule);
+		if (!rule) return originalSend.call(this, body);
+		const xhr = this;
+		const headers = Object.fromEntries(Object.entries(rule.headers).map(([name, value]) => [name.toLowerCase(), String(value)]));
+		setTimeout(() => {
+			define(xhr, "readyState", 4);
+			define(xhr, "status", rule.status);
+			define(xhr, "statusText", "");
+			define(xhr, "responseURL", new URL(info.url, location.href).href);
+			define(xhr, "responseText", rule.body);
+			define(xhr, "response", xhr.responseType === "json" ? (rule.body ? JSON.parse(rule.body) : null) : rule.body);
+			define(xhr, "getResponseHeader", name => headers[String(name).toLowerCase()] ?? null);
+			define(xhr, "getAllResponseHeaders", () => Object.entries(headers).map(([name, value]) => name + ": " + value).join("\\r\\n"));
+			xhr.dispatchEvent(new Event("readystatechange"));
+			xhr.dispatchEvent(new ProgressEvent("load"));
+			xhr.dispatchEvent(new ProgressEvent("loadend"));
+		}, rule.delayMs);
+	}
+})();`;

package/src/snapshots/clean.mjs

@@ -0,0 +1,36 @@
+import { existsSync, readdirSync, rmSync, statSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { loadConfig } from "#src/core/config.mjs";
+
+const DURATION = /^(\d+)(m|h|d)$/;
+const UNIT_MS = {
+	m: 60_000,
+	h: 3_600_000,
+	d: 86_400_000
+}
+
+const parseDuration = value => {
+	const match = DURATION.exec(String(value));
+	if (!match) throw new Error(`--older-than needs a duration like 30m, 2h or 7d, got "${value}"`);
+	return Number(match[1]) * UNIT_MS[match[2]];
+}
+
+export const cleanSnapshots = async (options = {}) => {
+	const config = options.config === false ? {} : await loadConfig(options.config);
+	const baseDir = config.configDir ?? process.cwd();
+	const out = path.resolve(baseDir, options.out ?? config.out ?? ".webview-preview");
+	const baseline = path.resolve(baseDir, options.baseline ?? config.baseline ?? "webview-preview-baseline");
+	const protectedDirs = [path.parse(out).root, os.homedir(), process.cwd(), baseDir, baseline].map(dir => path.resolve(dir));
+	if (protectedDirs.includes(out)) throw new Error(`refusing to clean ${out}: point "out" at a folder used only for snapshots`);
+	if (!existsSync(out)) return { removed: [], out }
+
+	const maxAge = options.olderThan ? parseDuration(options.olderThan) : 0;
+	const now = Date.now();
+	const removed = readdirSync(out)
+		.filter(name => name.toLowerCase().endsWith(".png"))
+		.map(name => path.join(out, name))
+		.filter(file => statSync(file).isFile() && now - statSync(file).mtimeMs >= maxAge);
+	if (!options.dryRun) for (const file of removed) rmSync(file);
+	return { removed, out }
+}