mechanica 2.1.0 → 2.2.0

package/README.md

@@ -344,19 +344,24 @@ By default all blocks share one `blocks` chunk, cached across pages. Mark heavy,
 ```bash
 npx mechanica shot hero                     # screenshot one block, from its previewData
 npx mechanica shot /about --width 1440,390  # a whole page, at two widths
+npx mechanica shot design/landing/index.html --width 1440,390   # a design handoff, the same way
+npx mechanica shot /about --section "#pricing" --section "footer" # one PNG per section
+npx mechanica shot /about --scroll 800,1600 # the viewport after scrolling (sticky, scroll-driven states)
 npx mechanica thumbs                        # page thumbnails for the editor's page browser
 npx mechanica thumbs --blocks               # block thumbnails for the palette
 ```
 
 These drive a locally installed Chrome or Edge (or `--browser <path>`) and need Node.js 22+ or Bun. They reuse a dev server running on port 5173 and start one if there isn't. Screenshots go to `.mech/shots/`, which is handy for reviewing a block or letting an AI assistant check its own work.
 
+`shot` also takes any `http(s)://` URL, a `file://` URL or a path to a local `.html` file, and renders it with the same browser, widths, waits and animation freeze as your own pages, without a dev server. That lets you compare a design handoff with the page you built from it, section by section: run both with the same `--width` and `--section` flags. `--scroll <px>` scrolls first and captures what is on screen, so sticky stages and scroll-revealed content show their later states. `--no-freeze` leaves animations and transitions running. For your own scripts (for example, measuring computed styles in the design and on the site), `mechanica/browser` exposes the same headless browser (see [API](#api)).
+
 ## CLI
 
 | Command | What it does |
 | --- | --- |
 | `mechanica export` | Build, then render every page to static HTML in `export/`. Flags: `--site-url`, `--site-name`, `--assets-url` (serve `/assets` and `/media` from a CDN) |
 | `mechanica build` | Build the client and server bundles into `dist/` (`export` runs this for you) |
-| `mechanica shot <blockId \| /path>` | Screenshot a block or a page. Flags: `--width`, `--data`, `--out`, `--full`, `--server`, `--browser` |
+| `mechanica shot <blockId \| /path \| url \| file.html>` | Screenshot a block, a page, any URL or a local HTML file (a design handoff; no dev server needed). Flags: `--width`, `--section <css>` (repeatable, one PNG each), `--scroll <px[,px…]>` (the viewport after scrolling), `--no-freeze`, `--full`, `--data` (blocks), `--out`, `--server`, `--browser` |
 | `mechanica thumbs [--blocks]` | Regenerate page or block thumbnails for the editor |
 | `mechanica images` | Generate image dimensions and blur-up previews for `.mech/assets` (needs `sharp`; `--force` redoes all) |
 | `mechanica login` | Sign in to the Mechanica platform: it prints a link to open and approve in the browser (signing in or registering on the way) and keeps the access token for this machine. In a terminal it waits for the approval; run from a coding agent, it prints the link and returns, and the next `link` or `push` finishes the sign-in (`--wait`, `--no-wait`, `--host`, or `--token` to store a token made in the dashboard) |
@@ -394,6 +399,21 @@ From `mechanica`:
 
 From `mechanica/plugin`: `mechanica` and the `PageProvider` type. From `mechanica/widgets`: `defineWidget` and `useWidgetServices` (uploads and the image picker inside widget editors). `mechanica/editor` and `mechanica/composer` are loaded by the plugin in development; you don't import them. From `mechanica/export`: `exportBuilt(projectDir, options)`, which statically renders an already built project (`dist/` + `.mech/`) without running a build and resolves to `{ pages, warnings }` — for render services that receive a prebuilt bundle; `options.outDir` sets where the site is written, and `options.fetchJson` replaces how `useFetch` requests are made.
 
+From `mechanica/browser`: the headless browser behind `mechanica shot`, for your own Node 22+ or Bun scripts. It needs no dev server and no Vite. `openPage(url, { width, height, browser })` launches a local Chrome or Edge and resolves to a page with `evaluate(expression)`, `setViewport(width, height)`, `scrollTo(y)`, `settle()` (fonts and images), `freezeAnimations()`, `sectionClip(selector)`, `screenshot({ clip, section, full, scale })` (a PNG `Buffer`; with no options, what is in the viewport), `goto(url)`, `messages` (console errors and page errors) and `close()`. `findDevServer()` returns the origin of a running dev server, or `null`.
+
+```js
+import { openPage } from 'mechanica/browser'
+
+const page = await openPage(new URL('design/landing/index.html', import.meta.url).href, { width: 390 })
+try {
+  const size = await page.evaluate(`getComputedStyle(document.querySelector('#hero h1')).fontSize`)
+  await page.scrollTo(1200)
+  const png = await page.screenshot({ section: '#hero' })
+} finally {
+  await page.close()
+}
+```
+
 ## Upgrading from 2.0
 
 - Uploaded files are addressed as `/media/<file>` in page files, shared data and rich text; 2.0 wrote `/@mechanica/assets/<file>`. The old address still works everywhere, so nothing breaks — run `npx mechanica migrate` once to rewrite it, and don't serve anything of your own under `/media/`.

package/dist/browser.js

@@ -0,0 +1,2 @@
+import { a as MAX_SHOT_HEIGHT, i as openPage, n as PAGE_LOADED, o as findDevServer, r as describeSectionError, t as NavigationError } from "./chunks/browser-BCfAv8bW.js";
+export { MAX_SHOT_HEIGHT, NavigationError, PAGE_LOADED, describeSectionError, findDevServer, openPage };

package/dist/chunks/browser-BCfAv8bW.js

@@ -0,0 +1,558 @@
+import fs from "node:fs";
+import { join } from "node:path";
+import os from "node:os";
+import { 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
+	};
+}
+/**
+* Spawn a headless Chromium-based browser with a DevTools endpoint and connect
+* to it. Prefers browsers already on the machine (Edge ships with Windows,
+* Chrome is everywhere), so nothing needs downloading.
+*/
+async function launchBrowser(explicitPath) {
+	const executable = findBrowserExecutable(explicitPath);
+	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"
+	] });
+	const cleanup = async () => {
+		const exited = new Promise((resolve) => {
+			if (child.exitCode != null) return resolve();
+			child.once("exit", () => resolve());
+			setTimeout(resolve, 3e3);
+		});
+		child.kill();
+		await exited;
+		for (let attempt = 0; attempt < 3; attempt++) try {
+			fs.rmSync(userDataDir, {
+				recursive: true,
+				force: true
+			});
+			return;
+		} catch {
+			await new Promise((resolve) => setTimeout(resolve, 300));
+		}
+	};
+	let endpoint;
+	try {
+		endpoint = await waitForDevtoolsEndpoint(child, 2e4);
+	} catch (error) {
+		await cleanup();
+		throw new Error(`Failed to start ${executable.label} (${executable.path}): ${error instanceof Error ? error.message : error}`);
+	}
+	const client = await CdpClient.connect(endpoint);
+	return {
+		client,
+		close: async () => {
+			await client.send("Browser.close").catch(() => {});
+			client.dispose();
+			await cleanup();
+		}
+	};
+}
+/** 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);
+		child.stderr.on("data", (chunk) => {
+			buffer += chunk.toString();
+			const match = buffer.match(/DevTools listening on (ws:\/\/\S+)/);
+			if (match) {
+				clearTimeout(timer);
+				resolve(match[1]);
+			}
+		});
+		child.on("error", (error) => {
+			clearTimeout(timer);
+			reject(error);
+		});
+		child.on("exit", (code) => {
+			clearTimeout(timer);
+			reject(/* @__PURE__ */ new Error(`browser exited early (code ${code})`));
+		});
+	});
+}
+/** Find a Chromium-based executable: an explicit path, or a known install location. */
+function findBrowserExecutable(explicitPath) {
+	if (explicitPath) {
+		if (!fs.existsSync(explicitPath)) throw new Error(`--browser not found: ${explicitPath}`);
+		return {
+			label: "browser from --browser",
+			path: explicitPath
+		};
+	}
+	const candidates = platformBrowserCandidates();
+	const found = candidates.find((candidate) => fs.existsSync(candidate.path));
+	if (!found) {
+		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 found;
+}
+function platformBrowserCandidates() {
+	if (process.platform === "win32") {
+		const programFiles = process.env["ProgramFiles"] ?? "C:\\Program Files";
+		const programFilesX86 = process.env["ProgramFiles(x86)"] ?? "C:\\Program Files (x86)";
+		const localAppData = process.env["LOCALAPPDATA"] ?? join(os.homedir(), "AppData", "Local");
+		return [
+			{
+				label: "Microsoft Edge",
+				path: join(programFilesX86, "Microsoft", "Edge", "Application", "msedge.exe")
+			},
+			{
+				label: "Microsoft Edge",
+				path: join(programFiles, "Microsoft", "Edge", "Application", "msedge.exe")
+			},
+			{
+				label: "Google Chrome",
+				path: join(programFiles, "Google", "Chrome", "Application", "chrome.exe")
+			},
+			{
+				label: "Google Chrome",
+				path: join(localAppData, "Google", "Chrome", "Application", "chrome.exe")
+			}
+		];
+	}
+	if (process.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);
+	}
+};
+//#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.ids.length ? `. Ids on the page: ${box.ids.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) {
+		const box = await this.evaluate(`((selector) => {
+      let element
+      try {
+        element = document.querySelector(selector)
+      } catch (error) {
+        return { error: 'invalid', message: String((error && error.message) || error) }
+      }
+      if (!element) {
+        // A hint for the next try: readable ids of page elements (not SVG internals or generated ids).
+        const ids = [...document.querySelectorAll('body [id]')]
+          .filter((el) => !el.closest('svg'))
+          .map((el) => el.id)
+          .filter((id) => /^[A-Za-z][\\w-]{0,39}$/.test(id) && !/^w-node-|[0-9a-f]{8}/i.test(id))
+        return { error: 'missing', ids: [...new Set(ids)].slice(0, 20).map((id) => '#' + id) }
+      }
+      const rect = 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 }
+    })(${JSON.stringify(selector)})`);
+		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 { MAX_SHOT_HEIGHT as a, openPage as i, PAGE_LOADED as n, findDevServer as o, describeSectionError as r, NavigationError as t };