mechanica 2.1.0 → 2.2.1

package/dist/chunks/browser-BV2iB_xD.js

@@ -0,0 +1,810 @@
+import fs from "node:fs";
+import { join, win32 } from "node:path";
+import os from "node:os";
+import { execFile, spawn } from "node:child_process";
+//#region src/cli/headless.ts
+/**
+* Headless-browser plumbing shared by `mechanica shot`, `mechanica thumbs` and
+* the public `mechanica/browser` helper: browser discovery/spawn, a minimal
+* CDP client, page-session helpers, and probing for a running dev server.
+*
+* Talks raw CDP over the platform `WebSocket` instead of using an automation
+* library: Playwright/Puppeteer launch handshakes rely on Node-only fd pipes
+* that hang under Bun, and screenshots need only a handful of CDP calls.
+*
+* Never imports Vite: booting an ephemeral dev server lives in `dev-server.ts`,
+* so `mechanica/browser` stays usable from plain Node scripts.
+*/
+/** Where `mechanica shot`/`thumbs` look for a running dev server first. */
+var DEV_SERVER_ORIGINS = ["http://127.0.0.1:5173", "http://localhost:5173"];
+/** The origin of a running Mechanica dev server on the default port, or null. */
+async function findDevServer(origins = DEV_SERVER_ORIGINS) {
+	for (const origin of origins) if (await isMechanicaServer(origin)) return origin;
+	return null;
+}
+async function isMechanicaServer(origin) {
+	try {
+		return (await fetch(`${origin}/@mechanica/folders`, { signal: AbortSignal.timeout(1e3) })).ok;
+	} catch {
+		return false;
+	}
+}
+async function setViewport(cdp, sessionId, width, height = 900) {
+	await cdp.send("Emulation.setDeviceMetricsOverride", {
+		width,
+		height,
+		deviceScaleFactor: 1,
+		mobile: false
+	}, sessionId);
+}
+async function evaluateValue(cdp, sessionId, expression) {
+	return (await cdp.send("Runtime.evaluate", {
+		expression,
+		returnByValue: true
+	}, sessionId)).result?.value;
+}
+/**
+* Poll an expression on the page until it is `true` or the timeout elapses.
+* Evaluate errors (execution context destroyed mid-navigation) count as "not
+* ready yet" rather than failing the wait.
+*/
+async function waitForCondition(cdp, sessionId, expression, timeout) {
+	const deadline = Date.now() + timeout;
+	while (Date.now() < deadline) {
+		try {
+			if (await evaluateValue(cdp, sessionId, expression)) return;
+		} catch {}
+		await new Promise((resolve) => setTimeout(resolve, 100));
+	}
+	throw new Error(`Timed out after ${timeout}ms waiting for the page to become ready`);
+}
+/** Upper bound for {@link settlePageMedia}: a stalled image must not hang a shot. */
+var SETTLE_TIMEOUT = 1e4;
+/**
+* Wait for web fonts and all images — normal pages have no injected ready flag.
+* Lazy images are switched to eager first: below the fold they would never
+* start loading in a headless tab (the wait used to hang on them), and a
+* full-page capture should show them anyway. Gives up after `timeout` ms.
+*/
+async function settlePageMedia(cdp, sessionId, timeout = SETTLE_TIMEOUT) {
+	await cdp.send("Runtime.evaluate", {
+		expression: `(() => {
+        for (const img of document.images) if (img.loading === 'lazy') img.loading = 'eager'
+        const media = Promise.all([
+          document.fonts ? document.fonts.ready : null,
+          ...[...document.images].map((img) =>
+            img.complete ? null : new Promise((done) => {
+              img.addEventListener('load', done, { once: true })
+              img.addEventListener('error', done, { once: true })
+            })),
+        ].filter(Boolean))
+        return Promise.race([media, new Promise((done) => setTimeout(done, ${timeout}))]).then(() => true)
+      })()`,
+		awaitPromise: true,
+		returnByValue: true
+	}, sessionId);
+}
+var FREEZE_STYLE_ID = "mechanica-freeze-animations";
+/** Freeze animations/transitions so captures are deterministic across runs. Idempotent. */
+async function freezeAnimations(cdp, sessionId) {
+	await cdp.send("Runtime.evaluate", { expression: `{
+        if (!document.getElementById('${FREEZE_STYLE_ID}')) {
+          const style = document.createElement('style')
+          style.id = '${FREEZE_STYLE_ID}'
+          style.textContent = '*, *::before, *::after { animation: none !important; transition: none !important; caret-color: transparent !important; }'
+          document.head.appendChild(style)
+        }
+      }` }, sessionId);
+}
+/** Undo {@link freezeAnimations}: transitions and animations run again. */
+async function unfreezeAnimations(cdp, sessionId) {
+	await cdp.send("Runtime.evaluate", { expression: `document.getElementById('${FREEZE_STYLE_ID}')?.remove()` }, sessionId);
+}
+/** Wait two animation frames: a full style → layout → paint cycle has run. */
+async function nextFrames(cdp, sessionId) {
+	await cdp.send("Runtime.evaluate", {
+		expression: "new Promise((done) => requestAnimationFrame(() => requestAnimationFrame(done)))",
+		awaitPromise: true
+	}, sessionId);
+}
+/** Chromium refuses to encode arbitrarily tall captures — cap and say so. */
+var MAX_SHOT_HEIGHT = 12e3;
+/** The full document size as a screenshot clip. */
+async function fullPageClip(cdp, sessionId) {
+	const metrics = await cdp.send("Page.getLayoutMetrics", {}, sessionId);
+	const size = metrics.cssContentSize ?? metrics.contentSize;
+	const height = Math.min(size.height, MAX_SHOT_HEIGHT);
+	if (height < size.height) console.info(`(page is ${Math.round(size.height)}px tall — clipped to ${MAX_SHOT_HEIGHT}px)`);
+	return {
+		x: 0,
+		y: 0,
+		width: size.width,
+		height
+	};
+}
+/** What is on screen right now (the visual viewport at its scroll offset), as a clip. */
+async function viewportClip(cdp, sessionId) {
+	const metrics = await cdp.send("Page.getLayoutMetrics", {}, sessionId);
+	const viewport = metrics.cssVisualViewport ?? metrics.visualViewport;
+	return {
+		x: viewport.pageX,
+		y: viewport.pageY,
+		width: viewport.clientWidth,
+		height: viewport.clientHeight
+	};
+}
+/** How long a spawned browser may take to print its DevTools endpoint. */
+var STARTUP_TIMEOUT = 2e4;
+/**
+* Spawn a headless Chromium-based browser with a DevTools endpoint and connect
+* to it. With `explicitPath` (`--browser`) only that executable is tried.
+* Otherwise the installed browsers of {@link platformBrowserCandidates} are
+* tried in order until one starts — a browser already on the machine, so
+* nothing needs downloading — and the error names each one that failed.
+*/
+async function launchBrowser(explicitPath) {
+	if (explicitPath) {
+		if (!fs.existsSync(explicitPath)) throw new Error(`--browser not found: ${explicitPath}`);
+		const executable = {
+			label: "browser from --browser",
+			path: explicitPath
+		};
+		try {
+			return await startBrowser(executable);
+		} catch (error) {
+			throw new Error(`Failed to start ${executable.label} (${executable.path}): ${errorMessage(error)}`);
+		}
+	}
+	const candidates = platformBrowserCandidates();
+	const installed = candidates.filter((candidate, index) => candidates.findIndex((other) => other.path === candidate.path) === index && fs.existsSync(candidate.path));
+	if (!installed.length) {
+		const looked = candidates.map((c) => `  ${c.label}: ${c.path}`).join("\n");
+		throw new Error(`No Chromium-based browser found. Looked for:\n${looked}\nInstall Chrome or Edge, or pass --browser <path-to-executable>.`);
+	}
+	return startFirstBrowser(installed, startBrowser);
+}
+/**
+* Try `start` on each candidate in order and return the first browser that
+* comes up. When none does, the error lists every candidate and why it failed.
+*/
+async function startFirstBrowser(candidates, start) {
+	const failures = [];
+	for (const candidate of candidates) try {
+		return await start(candidate);
+	} catch (error) {
+		failures.push(`  ${candidate.label} (${candidate.path}): ${errorMessage(error)}`);
+	}
+	throw new Error(`No browser could be started. Tried:\n${failures.join("\n")}\nPass --browser <path-to-executable> to use another Chromium-based browser.`);
+}
+/**
+* Spawn one browser on a fresh temporary profile and connect to it. When it
+* does not come up (exits early, never prints its endpoint, refuses the
+* connection), everything it started is ended and the profile removed before
+* the error is rethrown.
+*/
+async function startBrowser(executable) {
+	const userDataDir = fs.mkdtempSync(join(os.tmpdir(), "mechanica-shot-"));
+	const child = spawn(executable.path, [
+		"--headless=new",
+		"--remote-debugging-port=0",
+		`--user-data-dir=${userDataDir}`,
+		"--no-first-run",
+		"--no-default-browser-check",
+		"--disable-extensions",
+		"--hide-scrollbars",
+		"about:blank"
+	], {
+		stdio: [
+			"ignore",
+			"ignore",
+			"pipe"
+		],
+		env: browserEnv()
+	});
+	let client;
+	try {
+		const endpoint = await waitForDevtoolsEndpoint(child, STARTUP_TIMEOUT);
+		client = await CdpClient.connect(endpoint);
+	} catch (error) {
+		await killBrowserTree(child, userDataDir);
+		await removeProfile(userDataDir);
+		throw error;
+	}
+	return {
+		client,
+		close: async () => {
+			await client.send("Browser.close").catch(() => {});
+			client.dispose();
+			await stopProcess(child);
+			await removeProfile(userDataDir);
+		}
+	};
+}
+/**
+* The environment a browser starts with. On Windows it leaves out
+* `__COMPAT_LAYER` (Git Bash and some tool runners set it to `RunAsInvoker`):
+* under a compatibility layer Edge relaunches itself without it and exits at
+* once, so the process we spawned never prints its endpoint while the
+* relaunched one keeps running.
+*/
+function browserEnv(env = process.env, platform = process.platform) {
+	if (platform !== "win32") return env;
+	const result = { ...env };
+	for (const key of Object.keys(result)) if (key.toUpperCase() === "__COMPAT_LAYER") delete result[key];
+	return result;
+}
+/**
+* The Windows commands that end a browser which failed to start, best effort:
+* `taskkill /T /F` on its process tree while the spawned process still runs
+* (`pid`), then — because a browser that relaunched itself has outlived the
+* process we spawned — every process still running on its temporary profile,
+* found by the profile's folder name in the command line.
+*/
+function windowsKillCommands(pid, userDataDir) {
+	const commands = [];
+	if (pid) commands.push(["taskkill.exe", [
+		"/T",
+		"/F",
+		"/PID",
+		String(pid)
+	]]);
+	const profile = win32.basename(userDataDir);
+	if (/^[\w.-]+$/.test(profile)) {
+		const script = `Get-CimInstance Win32_Process -Filter "CommandLine LIKE '%${profile}%'" | Where-Object { \$_.ProcessId -ne \$PID } | ForEach-Object { Stop-Process -Id \$_.ProcessId -Force -ErrorAction SilentlyContinue }`;
+		const encoded = Buffer.from(script, "utf16le").toString("base64");
+		commands.push(["powershell.exe", [
+			"-NoProfile",
+			"-NonInteractive",
+			"-EncodedCommand",
+			encoded
+		]]);
+	}
+	return commands;
+}
+/** End a browser that failed to start, with every process it spawned (best effort). */
+async function killBrowserTree(child, userDataDir) {
+	if (process.platform === "win32") for (const [command, args] of windowsKillCommands(isRunning(child) ? child.pid : void 0, userDataDir)) await runQuietly(command, args);
+	await stopProcess(child);
+}
+function isRunning(child) {
+	return child.exitCode === null && child.signalCode === null;
+}
+/** Kill the spawned process (if it still runs) and wait up to 3 s for it to exit. */
+async function stopProcess(child) {
+	if (!isRunning(child)) return;
+	const exited = new Promise((resolve) => {
+		child.once("exit", () => resolve());
+		setTimeout(resolve, 3e3);
+	});
+	child.kill();
+	await exited;
+}
+/** Remove a temporary profile; it can stay locked for a moment after exit on Windows. */
+async function removeProfile(userDataDir) {
+	for (let attempt = 0; attempt < 5; attempt++) try {
+		fs.rmSync(userDataDir, {
+			recursive: true,
+			force: true
+		});
+		return;
+	} catch {
+		await new Promise((resolve) => setTimeout(resolve, 300));
+	}
+}
+/** Run a command, ignoring its output and any failure. */
+function runQuietly(command, args) {
+	return new Promise((resolve) => {
+		execFile(command, args, {
+			timeout: 15e3,
+			windowsHide: true
+		}, () => resolve());
+	});
+}
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/** Read the spawned browser's stderr until it prints its DevTools WebSocket URL. */
+function waitForDevtoolsEndpoint(child, timeout) {
+	return new Promise((resolve, reject) => {
+		let buffer = "";
+		const timer = setTimeout(() => reject(/* @__PURE__ */ new Error(`no DevTools endpoint within ${timeout}ms`)), timeout);
+		let found = false;
+		child.stderr.on("data", (chunk) => {
+			if (found) return;
+			buffer += chunk.toString();
+			const match = buffer.match(/DevTools listening on (ws:\/\/\S+)/);
+			if (match) {
+				found = true;
+				clearTimeout(timer);
+				resolve(match[1]);
+			}
+		});
+		child.on("error", (error) => {
+			clearTimeout(timer);
+			reject(error);
+		});
+		child.on("exit", (code, signal) => {
+			clearTimeout(timer);
+			const said = buffer.trim().split(/\r?\n/).pop()?.trim().slice(0, 200);
+			reject(/* @__PURE__ */ new Error(`browser exited early (${code !== null ? `code ${code}` : signal})${said ? `: ${said}` : ""}`));
+		});
+	});
+}
+/**
+* Known install locations of Chromium-based browsers, in the order they are
+* tried. On Windows Chrome comes first: Edge ships with Windows, so it is the
+* fallback, and it relaunches itself under a compatibility layer (see
+* {@link browserEnv}).
+*/
+function platformBrowserCandidates(platform = process.platform, env = process.env, home = os.homedir()) {
+	if (platform === "win32") {
+		const programFiles = env["ProgramFiles"] ?? "C:\\Program Files";
+		const programFilesX86 = env["ProgramFiles(x86)"] ?? "C:\\Program Files (x86)";
+		const localAppData = env["LOCALAPPDATA"] ?? win32.join(home, "AppData", "Local");
+		const chrome = [
+			"Google",
+			"Chrome",
+			"Application",
+			"chrome.exe"
+		];
+		const edge = [
+			"Microsoft",
+			"Edge",
+			"Application",
+			"msedge.exe"
+		];
+		return [
+			{
+				label: "Google Chrome",
+				path: win32.join(programFiles, ...chrome)
+			},
+			{
+				label: "Google Chrome",
+				path: win32.join(programFilesX86, ...chrome)
+			},
+			{
+				label: "Google Chrome",
+				path: win32.join(localAppData, ...chrome)
+			},
+			{
+				label: "Microsoft Edge",
+				path: win32.join(programFilesX86, ...edge)
+			},
+			{
+				label: "Microsoft Edge",
+				path: win32.join(programFiles, ...edge)
+			}
+		];
+	}
+	if (platform === "darwin") return [
+		{
+			label: "Google Chrome",
+			path: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+		},
+		{
+			label: "Microsoft Edge",
+			path: "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"
+		},
+		{
+			label: "Chromium",
+			path: "/Applications/Chromium.app/Contents/MacOS/Chromium"
+		}
+	];
+	return [
+		{
+			label: "Google Chrome",
+			path: "/usr/bin/google-chrome"
+		},
+		{
+			label: "Chromium",
+			path: "/usr/bin/chromium"
+		},
+		{
+			label: "Chromium",
+			path: "/usr/bin/chromium-browser"
+		},
+		{
+			label: "Microsoft Edge",
+			path: "/usr/bin/microsoft-edge"
+		}
+	];
+}
+/**
+* A minimal Chrome DevTools Protocol client over the platform `WebSocket`
+* (native in Bun and Node ≥ 22): request/response matching by id, plus event
+* fan-out. Flat session mode — pass a `sessionId` to address a page target.
+*/
+var CdpClient = class CdpClient {
+	ws;
+	nextId = 1;
+	pending = /* @__PURE__ */ new Map();
+	listeners = [];
+	constructor(ws) {
+		this.ws = ws;
+		ws.onmessage = (event) => this.onMessage(String(event.data));
+		ws.onclose = () => {
+			for (const { reject } of this.pending.values()) reject(/* @__PURE__ */ new Error("CDP connection closed"));
+			this.pending.clear();
+		};
+	}
+	static connect(url) {
+		return new Promise((resolve, reject) => {
+			const ws = new WebSocket(url);
+			const timer = setTimeout(() => reject(/* @__PURE__ */ new Error(`CDP connect timeout: ${url}`)), 1e4);
+			ws.onopen = () => {
+				clearTimeout(timer);
+				resolve(new CdpClient(ws));
+			};
+			ws.onerror = () => {
+				clearTimeout(timer);
+				reject(/* @__PURE__ */ new Error(`CDP connection failed: ${url}`));
+			};
+		});
+	}
+	send(method, params = {}, sessionId) {
+		const id = this.nextId++;
+		this.ws.send(JSON.stringify({
+			id,
+			method,
+			params,
+			...sessionId ? { sessionId } : {}
+		}));
+		return new Promise((resolve, reject) => this.pending.set(id, {
+			resolve,
+			reject
+		}));
+	}
+	onEvent(listener) {
+		this.listeners.push(listener);
+	}
+	dispose() {
+		try {
+			this.ws.close();
+		} catch {}
+	}
+	onMessage(raw) {
+		const message = JSON.parse(raw);
+		if (typeof message.id === "number") {
+			const pending = this.pending.get(message.id);
+			if (!pending) return;
+			this.pending.delete(message.id);
+			if (message.error) pending.reject(/* @__PURE__ */ new Error(`${message.error.message ?? "CDP error"}`));
+			else pending.resolve(message.result ?? {});
+			return;
+		}
+		if (typeof message.method === "string") for (const listener of this.listeners) listener(message.method, message.params ?? {}, message.sessionId);
+	}
+};
+/**
+* Split a selector at `>>>` into trimmed parts (one part when there is none).
+* A `>>>` inside quotes, brackets or parentheses, or after a backslash, is
+* part of the selector. Throws when a part is empty (`>>> .a`, `.a >>>`).
+*/
+function splitShadowSelector(selector) {
+	const parts = [];
+	let start = 0;
+	let depth = 0;
+	let quote = "";
+	for (let i = 0; i < selector.length; i++) {
+		const char = selector[i];
+		if (char === "\\") {
+			i++;
+			continue;
+		}
+		if (quote) {
+			if (char === quote) quote = "";
+			continue;
+		}
+		if (char === "\"" || char === "'") quote = char;
+		else if (char === "[" || char === "(") depth++;
+		else if ((char === "]" || char === ")") && depth > 0) depth--;
+		else if (depth === 0 && selector.startsWith(">>>", i)) {
+			parts.push(selector.slice(start, i).trim());
+			i += 2;
+			start = i + 1;
+		}
+	}
+	parts.push(selector.slice(start).trim());
+	if (parts.some((part) => !part)) throw new Error(`empty selector around ">>>"`);
+	return parts;
+}
+/**
+* The block-id selector to try when a bare `#name` or `name` matches nothing:
+* `[data-block-id="name"]`. Null for any other selector. A name that is not a
+* valid CSS id (`#1hero`) still gets one, so block ids starting with a digit
+* are reachable too.
+*/
+function blockIdFallback(selector) {
+	const match = /^#?([\p{L}\p{N}_-]+)$/u.exec(selector.trim());
+	return match ? `[data-block-id="${match[1]}"]` : null;
+}
+/**
+* In-page source of `(parts, fallback) => result`, where `parts` is a selector
+* split by {@link splitShadowSelector} and `fallback` is
+* {@link blockIdFallback}'s result (or null). It finds the first element
+* matching `parts`, else the first matching `fallback`, in the document and
+* in every open shadow root, and returns:
+*
+* - `{ element }`;
+* - `{ error: 'invalid', message }` when the selector does not parse (and the
+*   fallback finds nothing);
+* - `{ error: 'missing', ids, blockIds, fallback }`: the readable ids
+*   (`#name`) and the `data-block-id` values on the page, shadow roots
+*   included, for the error message.
+*
+* Plain JS with no outside references: it is sent to the page as text.
+*/
+var FIND_SECTION_SOURCE = String.raw`(parts, fallback) => {
+  // Every open shadow root under scope, depth first in tree order.
+  const shadowRoots = (scope) => {
+    const roots = []
+    const visit = (root) => {
+      for (const el of root.querySelectorAll('*')) {
+        if (el.shadowRoot) {
+          roots.push(el.shadowRoot)
+          visit(el.shadowRoot)
+        }
+      }
+    }
+    visit(scope)
+    return roots
+  }
+  // The first match in scope's own tree, else in the shadow roots under it.
+  const first = (scope, selector) => {
+    const own = scope.querySelector(selector)
+    if (own) return own
+    for (const root of shadowRoots(scope)) {
+      const hit = root.querySelector(selector)
+      if (hit) return hit
+    }
+    return null
+  }
+  const all = (scope, selector) =>
+    [scope, ...shadowRoots(scope)].flatMap((root) => [...root.querySelectorAll(selector)])
+  const query = () => {
+    let scopes = [document]
+    for (const part of parts.slice(0, -1)) {
+      const hosts = new Set(scopes.flatMap((scope) => all(scope, part)))
+      scopes = [...hosts].map((host) => host.shadowRoot || host)
+    }
+    for (const scope of scopes) {
+      const hit = first(scope, parts[parts.length - 1])
+      if (hit) return hit
+    }
+    return null
+  }
+
+  let element = null
+  let invalid = null
+  try {
+    element = query()
+  } catch (error) {
+    invalid = String((error && error.message) || error)
+  }
+  if (!element && fallback) element = first(document, fallback)
+  if (element) return { element }
+  if (invalid) return { error: 'invalid', message: invalid }
+
+  // A hint for the next try: readable ids (not SVG internals or generated
+  // ids) and block ids, in the document and its shadow roots.
+  const ids = new Set()
+  const blockIds = new Set()
+  for (const root of [document, ...shadowRoots(document)]) {
+    for (const el of root.querySelectorAll(root === document ? 'body [id]' : '[id]')) {
+      const id = el.id
+      if (el.closest('svg') || !/^[A-Za-z][\w-]{0,39}$/.test(id) || /^w-node-|[0-9a-f]{8}/i.test(id)) continue
+      ids.add('#' + id)
+    }
+    for (const el of root.querySelectorAll('[data-block-id]')) {
+      const id = el.getAttribute('data-block-id')
+      if (id) blockIds.add(id)
+    }
+  }
+  return {
+    error: 'missing',
+    ids: [...ids].slice(0, ${20}),
+    blockIds: [...blockIds].slice(0, ${20}),
+    fallback,
+  }
+}`;
+//#endregion
+//#region src/cli/browser.ts
+/**
+* `mechanica/browser` — the headless browser behind `mechanica shot` and
+* `mechanica thumbs`, for a site's own scripts: open a page (a dev-server URL,
+* a design handoff's `file://` URL, any site), resize it, scroll it, measure it
+* with `evaluate`, and screenshot it or one section of it.
+*
+* Drives a Chrome/Edge already installed on the machine over raw CDP
+* (`headless.ts`), so there is nothing to download. Needs a global `WebSocket`
+* (Node 22+ or Bun) and never imports Vite.
+*/
+/** Readiness of an ordinary page: the load event has fired. */
+var PAGE_LOADED = "document.readyState === 'complete'";
+var DEFAULT_WIDTH = 1440;
+var DEFAULT_HEIGHT = 900;
+var DEFAULT_TIMEOUT = 15e3;
+/** `goto` could not open the URL at all (DNS, refused connection, missing file…). */
+var NavigationError = class extends Error {
+	url;
+	reason;
+	constructor(url, reason) {
+		super(`Failed to open ${url}: ${reason}`);
+		this.url = url;
+		this.reason = reason;
+		this.name = "NavigationError";
+	}
+};
+/**
+* Launch a headless browser with one tab, sized and media-emulated like
+* `mechanica shot`, and open `url` in it (omit `url` for a blank tab to
+* `goto` later). Always `close()` the page — it owns the browser process.
+*
+* ```ts
+* import { openPage } from 'mechanica/browser'
+*
+* const page = await openPage('file:///…/design/index.html', { width: 390 })
+* try {
+*   const size = await page.evaluate<string>(`getComputedStyle(document.querySelector('h1')).fontSize`)
+*   fs.writeFileSync('hero.png', await page.screenshot({ section: '#hero' }))
+* } finally {
+*   await page.close()
+* }
+* ```
+*/
+async function openPage(url, options = {}) {
+	const browser = await launchBrowser(options.browser);
+	try {
+		const page = await HeadlessPage.create(browser, options);
+		if (url) await page.goto(url, options);
+		return page;
+	} catch (error) {
+		await browser.close();
+		throw error;
+	}
+}
+/** The message for a `sectionClip` that found nothing usable. */
+function describeSectionError(selector, box) {
+	switch (box.error) {
+		case "invalid": return `"${selector}" is not a valid CSS selector (${box.message})`;
+		case "missing": return `No element matches "${selector}"` + (box.fallback ? ` (nor ${box.fallback})` : "") + (box.ids.length ? `. Ids on the page: ${box.ids.join(", ")}` : "") + (box.blockIds?.length ? `. Block ids (data-block-id): ${box.blockIds.join(", ")}` : "");
+		case "empty": return `"${selector}" matched an element with an empty box (${Math.round(box.width)}×${Math.round(box.height)}) — is it hidden at this width?`;
+	}
+}
+var HeadlessPage = class HeadlessPage {
+	browser;
+	sessionId;
+	messages = [];
+	height;
+	constructor(browser, sessionId, height) {
+		this.browser = browser;
+		this.sessionId = sessionId;
+		this.height = height;
+	}
+	static async create(browser, options) {
+		const cdp = browser.client;
+		const { targetId } = await cdp.send("Target.createTarget", { url: "about:blank" });
+		const { sessionId } = await cdp.send("Target.attachToTarget", {
+			targetId,
+			flatten: true
+		});
+		const page = new HeadlessPage(browser, sessionId, options.height ?? DEFAULT_HEIGHT);
+		cdp.onEvent((method, params, eventSession) => {
+			if (eventSession !== sessionId) return;
+			if (method === "Runtime.consoleAPICalled" && (params.type === "error" || params.type === "warning")) {
+				const text = (params.args ?? []).map((arg) => arg.value ?? arg.description ?? "").join(" ");
+				page.messages.push(`[console.${params.type}] ${text}`);
+			}
+			if (method === "Runtime.exceptionThrown") {
+				const details = params.exceptionDetails;
+				page.messages.push(`[pageerror] ${details?.exception?.description ?? details?.text ?? "unknown error"}`);
+			}
+		});
+		await cdp.send("Runtime.enable", {}, sessionId);
+		await cdp.send("Page.enable", {}, sessionId);
+		await setViewport(cdp, sessionId, options.width ?? DEFAULT_WIDTH, page.height);
+		if (options.reducedMotion !== false) await cdp.send("Emulation.setEmulatedMedia", { features: [{
+			name: "prefers-reduced-motion",
+			value: "reduce"
+		}] }, sessionId);
+		return page;
+	}
+	send(method, params = {}) {
+		return this.browser.client.send(method, params, this.sessionId);
+	}
+	async goto(url, options = {}) {
+		const navigation = await this.send("Page.navigate", { url });
+		if (navigation.errorText) throw new NavigationError(url, navigation.errorText);
+		await this.waitFor(options.ready ?? "document.readyState === 'complete'", options.timeout ?? DEFAULT_TIMEOUT);
+		if (options.settle !== false) await this.settle();
+	}
+	async evaluate(expression) {
+		const reply = await this.send("Runtime.evaluate", {
+			expression,
+			returnByValue: true,
+			awaitPromise: true
+		});
+		if (reply.exceptionDetails) {
+			const details = reply.exceptionDetails;
+			throw new Error(`Evaluation failed: ${details.exception?.description ?? details.text ?? "unknown error"}`);
+		}
+		return reply.result?.value;
+	}
+	waitFor(expression, timeout = DEFAULT_TIMEOUT) {
+		return waitForCondition(this.browser.client, this.sessionId, expression, timeout);
+	}
+	async setViewport(width, height = this.height) {
+		this.height = height;
+		await setViewport(this.browser.client, this.sessionId, width, height);
+	}
+	async scrollTo(y) {
+		await this.evaluate(`window.scrollTo({ top: ${Number(y)}, left: 0, behavior: 'instant' })`);
+		await this.nextFrame();
+		return this.evaluate("scrollY");
+	}
+	nextFrame() {
+		return nextFrames(this.browser.client, this.sessionId);
+	}
+	settle() {
+		return settlePageMedia(this.browser.client, this.sessionId, SETTLE_TIMEOUT);
+	}
+	freezeAnimations() {
+		return freezeAnimations(this.browser.client, this.sessionId);
+	}
+	unfreezeAnimations() {
+		return unfreezeAnimations(this.browser.client, this.sessionId);
+	}
+	async sectionClip(selector) {
+		let parts;
+		try {
+			parts = splitShadowSelector(selector);
+		} catch (error) {
+			throw new Error(describeSectionError(selector, {
+				error: "invalid",
+				message: error.message
+			}));
+		}
+		const fallback = parts.length === 1 ? blockIdFallback(selector) : null;
+		const box = await this.evaluate(`((find, parts, fallback) => {
+      const found = find(parts, fallback)
+      if (!found.element) return found
+      const rect = found.element.getBoundingClientRect()
+      if (rect.width < 1 || rect.height < 1) return { error: 'empty', width: rect.width, height: rect.height }
+      return { x: rect.x + scrollX, y: rect.y + scrollY, width: rect.width, height: rect.height }
+    })(${FIND_SECTION_SOURCE}, ${JSON.stringify(parts)}, ${JSON.stringify(fallback)})`);
+		if ("error" in box) throw new Error(describeSectionError(selector, box));
+		return box;
+	}
+	async screenshot(options = {}) {
+		const cdp = this.browser.client;
+		let clip;
+		let beyondViewport = true;
+		if (options.clip) clip = options.clip;
+		else if (options.section) {
+			const box = await this.sectionClip(options.section);
+			clip = {
+				...box,
+				height: Math.min(box.height, MAX_SHOT_HEIGHT)
+			};
+			if (clip.height < box.height) console.info(`("${options.section}" is ${Math.round(box.height)}px tall — clipped to ${MAX_SHOT_HEIGHT}px)`);
+		} else if (options.full) clip = await fullPageClip(cdp, this.sessionId);
+		else {
+			clip = await viewportClip(cdp, this.sessionId);
+			beyondViewport = false;
+		}
+		const shot = await this.send("Page.captureScreenshot", {
+			format: "png",
+			captureBeyondViewport: beyondViewport,
+			clip: {
+				...clip,
+				scale: options.scale ?? 1
+			}
+		});
+		return Buffer.from(shot.data, "base64");
+	}
+	close() {
+		return this.browser.close();
+	}
+};
+//#endregion
+export { splitShadowSelector as a, openPage as i, PAGE_LOADED as n, MAX_SHOT_HEIGHT as o, describeSectionError as r, findDevServer as s, NavigationError as t };