mechanica 2.1.0 → 2.2.0

package/dist/cli.js

@@ -2,38 +2,61 @@ import { t as buildSiteManifest } from "./chunks/site-BVqx8iKj.js";
 import { J as readImageManifest, K as isDerivedAsset, W as fsAssetStore, X as updateImageManifest, et as withRemoteAssets, it as isRasterImage, nt as analyzeImageBuffer, rt as hasSharp } from "./chunks/rich-text-codec-DCv1X0eZ.js";
 import { _ as request, a as git, c as clearPendingLogin, d as hostOrigin, f as savePendingLogin, g as parseRemoteUrl, h as REMOTE_NAME, i as uploadsIgnored, l as getPendingLogin, m as PlatformError, n as remoteAssetsFor, o as gitAuthEnv, p as saveToken, r as runAssetsPull, s as gitOk, t as pushUploads, u as getToken } from "./chunks/assets-5a2WdmFg.js";
 import { exportBuilt } from "./export.js";
+import { i as openPage, o as findDevServer, t as NavigationError } from "./chunks/browser-BCfAv8bW.js";
 import fs, { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { EDITOR_DIST_DIR, LEGACY_UPLOADS_PREFIX, SITE_MANIFEST_FILE, UPLOADS_PREFIX } from "mechanica-shared";
 import { appendFile, mkdir, readFile, readdir, realpath, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
-import { spawn } from "node:child_process";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { build } from "vite";
 //#region src/cli/args.ts
 /** Parse `argv` (without node/script) into a command, positionals and a `--flag[=value]` map. */
-function parseArgs(argv) {
+function parseArgs(argv, options = {}) {
 	const [command, ...rest] = argv;
 	const args = [];
 	const flags = {};
+	for (const token of scanArgs(rest, options)) if (token.flag === void 0) args.push(token.value);
+	else flags[token.flag] = token.value;
+	return {
+		command,
+		args,
+		flags
+	};
+}
+/**
+* Every value a repeatable flag was given, in order — `--section a --section b`
+* → `['a', 'b']`; a bare `--section` contributes `true`. Takes the same `argv`
+* as {@link parseArgs} (command first).
+*/
+function flagValues(argv, name, options = {}) {
+	return scanArgs(argv.slice(1), options).filter((token) => token.flag === name).map((token) => token.value);
+}
+function scanArgs(rest, { booleans = [] }) {
+	const tokens = [];
 	for (let i = 0; i < rest.length; i++) {
 		const arg = rest[i];
 		if (!arg.startsWith("--")) {
-			args.push(arg);
+			tokens.push({ value: arg });
 			continue;
 		}
 		const key = arg.slice(2);
 		if (key.includes("=")) {
 			const eq = key.indexOf("=");
-			flags[key.slice(0, eq)] = key.slice(eq + 1);
-		} else if (rest[i + 1] && !rest[i + 1].startsWith("--")) flags[key] = rest[++i];
-		else flags[key] = true;
+			tokens.push({
+				flag: key.slice(0, eq),
+				value: key.slice(eq + 1)
+			});
+		} else if (!booleans.includes(key) && rest[i + 1] && !rest[i + 1].startsWith("--")) tokens.push({
+			flag: key,
+			value: rest[++i]
+		});
+		else tokens.push({
+			flag: key,
+			value: true
+		});
 	}
-	return {
-		command,
-		args,
-		flags
-	};
+	return tokens;
 }
 //#endregion
 //#region src/cli/platform/engine-version.ts
@@ -621,27 +644,23 @@ async function runPush() {
 	console.info(`\n${branch} is live at ${deploy.url ?? status.url} — ${deploy.pages} page(s)`);
 }
 //#endregion
-//#region src/cli/headless.ts
-/**
-* Headless-browser plumbing shared by `mechanica shot` and `mechanica thumbs`:
-* dev-server discovery, browser discovery/spawn, and a minimal CDP client.
-*
-* 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.
-*/
+//#region src/cli/dev-server.ts
 /**
 * Find a dev server to render against: an explicit origin, a running local
 * Mechanica dev server, or an ephemeral one booted from the project's
 * `vite.config.ts` and torn down afterwards.
+*
+* The only browser-side helper that needs Vite, kept out of `headless.ts` so
+* the public `mechanica/browser` entry never pulls it in.
 */
 async function resolveServer(flag) {
 	if (flag) return {
 		origin: flag.replace(/\/+$/, ""),
 		close: async () => {}
 	};
-	for (const origin of ["http://127.0.0.1:5173", "http://localhost:5173"]) if (await isMechanicaServer(origin)) return {
-		origin,
+	const running = await findDevServer();
+	if (running) return {
+		origin: running,
 		close: async () => {}
 	};
 	console.info("No running dev server found — starting one…");
@@ -658,299 +677,11 @@ async function resolveServer(flag) {
 		close: () => server.close()
 	};
 }
-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`);
-}
-/** Wait for web fonts and all images — normal pages have no injected ready flag. */
-async function settlePageMedia(cdp, sessionId) {
-	await cdp.send("Runtime.evaluate", {
-		expression: `Promise.all([
-        document.fonts ? document.fonts.ready : null,
-        ...[...document.images].map((img) =>
-          img.complete ? null : new Promise((done) => { img.onload = done; img.onerror = done })),
-      ].filter(Boolean)).then(() => true)`,
-		awaitPromise: true,
-		returnByValue: true
-	}, sessionId);
-}
-/** Freeze animations/transitions so captures are deterministic across runs. */
-async function freezeAnimations(cdp, sessionId) {
-	await cdp.send("Runtime.evaluate", { expression: `{
-        const style = document.createElement('style')
-        style.textContent = '*, *::before, *::after { animation: none !important; transition: none !important; caret-color: transparent !important; }'
-        document.head.appendChild(style)
-      }` }, 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
-	};
-}
-/**
-* 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/shot.ts
+var USAGE = "Usage: mechanica shot <blockId | /page/path | URL | file.html> [--page </path>] [--data <json|@file>] [--width 1440,768] [--section <css>]… [--scroll <px[,px…]>] [--no-freeze] [--full] [--out <path>] [--server <url>] [--browser <path>]";
+/** Readiness flag of the standalone block preview route. */
+var PREVIEW_READY = "window.__MECHANICA_PREVIEW_READY__ === true";
 /** Parse a `--width` value into a list of positive integers. Defaults to `[1440]`. */
 function parseWidths(value) {
 	if (!value) return [1440];
@@ -958,6 +689,13 @@ function parseWidths(value) {
 	if (widths.length === 0 || widths.some((w) => !Number.isFinite(w) || w <= 0)) throw new Error(`Invalid --width value "${value}" — expected e.g. 1440 or 1440,768,390`);
 	return widths;
 }
+/** Parse a `--scroll` value (px from the top, comma-separated). Undefined when absent. */
+function parseScrolls(value) {
+	if (value === void 0) return void 0;
+	const parts = value.split(",").map((part) => part.trim());
+	if (parts.some((part) => !/^\d+$/.test(part))) throw new Error(`Invalid --scroll value "${value}" — expected pixels from the top, e.g. 800 or 0,800,1600`);
+	return parts.map(Number);
+}
 /** Resolve `--data`: inline JSON or `@file`, validated to a JSON object. */
 function resolveDataArg(value) {
 	if (!value) return void 0;
@@ -977,13 +715,22 @@ function previewUrl(origin, blockId, data) {
 	const query = data ? `?data=${encodeURIComponent(JSON.stringify(data))}` : "";
 	return `${base}/@mechanica/preview/${encodeURIComponent(blockId)}${query}`;
 }
-/** Resolve the output PNG path for one width. */
-function outputPath(out, name, width, multi) {
-	const suffix = multi ? `-w${width}` : "";
+/**
+* Resolve the output PNG path for one capture. `variant` (`-<section>`,
+* `-y<scroll>`) is always part of the name; the `-w<width>` suffix only when
+* shooting several widths. An `--out` ending in `.png` is a file name, any
+* other value a directory.
+*/
+function outputPath(out, name, width, multi, variant = "") {
+	const suffix = `${variant}${multi ? `-w${width}` : ""}`;
 	if (!out) return join(".mech", "shots", `${name}${suffix}.png`);
-	if (out.endsWith(".png")) return multi ? out.replace(/\.png$/, `${suffix}.png`) : out;
+	if (out.endsWith(".png")) return suffix ? out.replace(/\.png$/, `${suffix}.png`) : out;
 	return join(out, `${name}${suffix}.png`);
 }
+/** The name suffix of one capture: `-<section slug>` and/or `-y<scroll>`. */
+function shotVariant(sectionSlug, scroll) {
+	return `${sectionSlug ? `-${sectionSlug}` : ""}${scroll !== void 0 ? `-y${scroll}` : ""}`;
+}
 /** `/` → `index`, `/docs/getting-started` → `docs-getting-started`. */
 function pageSlug(path) {
 	const trimmed = path.replace(/^\/+|\/+$/g, "");
@@ -993,98 +740,250 @@ function pageSlug(path) {
 function normalizePagePath(path) {
 	return "/" + path.trim().replace(/^\/+|\/+$/g, "");
 }
-var USAGE = "Usage: mechanica shot <blockId | /page/path> [--page </path>] [--data <json|@file>] [--width 1440,768] [--out <path>] [--server <url>] [--browser <path>] [--full]";
+/** Lowercase letters and digits (any script) joined by single dashes. */
+function slugify(value) {
+	return value.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, "-").replace(/^-+|-+$/g, "");
+}
+/**
+* One file-name slug per `--section` selector: `#hero` → `hero`,
+* `.stage > .pin` → `stage-pin`. A selector with no letters or digits becomes
+* `section`; repeats get `-2`, `-3`…
+*/
+function sectionSlugs(selectors) {
+	const seen = /* @__PURE__ */ new Map();
+	return selectors.map((selector) => {
+		const base = slugify(selector).slice(0, 40).replace(/-+$/, "") || "section";
+		const count = (seen.get(base) ?? 0) + 1;
+		seen.set(base, count);
+		return count === 1 ? base : `${base}-${count}`;
+	});
+}
+var WINDOWS_DRIVE_PATH = /^[a-zA-Z]:[\\/]/;
+var RELATIVE_PATH = /^\.\.?[\\/]/;
+var HTML_FILE = /\.html?$/i;
+/**
+* Classify a `shot` target, in this order:
+* - `--page </path>` → that page;
+* - `http://…` / `https://…` → a URL, opened as is;
+* - `file://…`, a Windows drive path (`C:\…`), a `./` or `../` path, or any
+*   path ending in `.html`/`.htm` → a local file (relative to `cwd`);
+* - anything else starting with `/` → a page of this project;
+* - anything else → a block id.
+*/
+function classifyTarget(target, page, cwd = process.cwd()) {
+	if (page) return {
+		kind: "page",
+		path: normalizePagePath(page)
+	};
+	const value = target?.trim();
+	if (!value) throw new Error(USAGE);
+	if (/^https?:\/\//i.test(value)) return {
+		kind: "url",
+		url: parseUrl(value)
+	};
+	if (/^file:\/\//i.test(value)) {
+		const url = parseUrl(value);
+		return {
+			kind: "file",
+			url,
+			file: filePathOf(url)
+		};
+	}
+	if (WINDOWS_DRIVE_PATH.test(value) || RELATIVE_PATH.test(value) || HTML_FILE.test(value)) {
+		const file = resolve(cwd, value);
+		return {
+			kind: "file",
+			url: pathToFileURL(file).href,
+			file
+		};
+	}
+	if (value.startsWith("/")) return {
+		kind: "page",
+		path: normalizePagePath(value)
+	};
+	return {
+		kind: "block",
+		blockId: value
+	};
+}
+function parseUrl(value) {
+	try {
+		return new URL(value).href;
+	} catch {
+		throw new Error(`Invalid URL "${value}"`);
+	}
+}
+function filePathOf(url) {
+	try {
+		return fileURLToPath(url);
+	} catch {
+		return;
+	}
+}
+/**
+* Default output name of a URL or file shot:
+* - a URL → its host (no `www.`, port appended) and path, extension dropped:
+*   `https://example.com/business/evolve` → `example-com-business-evolve`;
+* - a file → its path relative to `cwd` (or its last three path segments when
+*   it lies outside), extension dropped: `design/evolve-level/index.html` →
+*   `design-evolve-level-index`.
+*/
+function foreignShotName(target, cwd = process.cwd()) {
+	if (target.kind === "url") {
+		const url = new URL(target.url);
+		return slugify(`${url.hostname.replace(/^www\./, "") + (url.port ? `-${url.port}` : "")}/${stripExtension(url.pathname)}`) || "shot";
+	}
+	if (target.kind !== "file") throw new Error(`Not a URL or file target: ${target.kind}`);
+	const file = target.file ?? decodeURIComponent(new URL(target.url).pathname);
+	const rel = relative(cwd, file);
+	const inside = rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+	const segments = (inside ? rel : file).split(/[\\/]+/).filter(Boolean);
+	return slugify(stripExtension((inside ? segments : segments.slice(-3)).join("/"))) || "shot";
+}
+function stripExtension(path) {
+	return path.replace(/\.[^./\\]+$/, "");
+}
 /**
-* `mechanica shot <blockId>` / `mechanica shot /page/path` — render one block
-* through the dev preview route (or a whole page, editor overlay stripped) in
-* a headless Chromium and write PNG screenshot(s). Made for agent loops:
-* prints the image paths plus any console/render errors, and fails loudly when
-* the block or page failed to render.
+* How each capture is framed: `--section` boxes, else `--full` (whole
+* document), else the viewport when scrolling (so sticky/pinned states are
+* what's in the picture), else the block element for block shots and the
+* whole document for pages, URLs and files.
+*/
+function captureMode(kind, flags) {
+	if (flags.section) return "section";
+	if (flags.full) return "full";
+	if (flags.scroll) return "viewport";
+	return kind === "block" ? "block" : "full";
+}
+/** Resolve and validate a `shot` invocation without touching a browser or a server. */
+function planShot(target, options = {}, cwd = process.cwd()) {
+	const shotTarget = classifyTarget(target, options.page, cwd);
+	const isBlock = shotTarget.kind === "block";
+	if (!isBlock && options.data) throw new Error("--data applies to block shots only");
+	const selectors = options.section ?? [];
+	if (selectors.length && isBlock) throw new Error("--section applies to page, URL and file shots — a block shot is already clipped to its block");
+	if (selectors.some((selector) => !selector.trim())) throw new Error("--section needs a CSS selector, e.g. --section \"#hero\"");
+	const slugs = sectionSlugs(selectors);
+	const scrolls = parseScrolls(options.scroll);
+	return {
+		target: shotTarget,
+		name: shotTarget.kind === "block" ? shotTarget.blockId : shotTarget.kind === "page" ? `page-${pageSlug(shotTarget.path)}` : foreignShotName(shotTarget, cwd),
+		widths: parseWidths(options.width),
+		scrolls,
+		sections: selectors.map((selector, index) => ({
+			selector: selector.trim(),
+			slug: slugs[index]
+		})),
+		data: resolveDataArg(options.data),
+		mode: captureMode(shotTarget.kind, {
+			section: selectors.length > 0,
+			full: options.full,
+			scroll: !!scrolls
+		}),
+		freeze: !options.noFreeze
+	};
+}
+/**
+* `mechanica shot <target>` — render one block through the dev preview route,
+* a whole page (editor overlay stripped), or a foreign document (any URL, or
+* a local `.html` file such as a design handoff) in a headless Chromium and
+* write PNG screenshot(s): per width, per scroll offset, per `--section`.
+* Made for agent loops: prints the image paths plus any console/render errors,
+* and fails loudly when the block or page failed to render.
 */
 async function runShot(target, options = {}) {
-	const rawPage = options.page ?? (target?.startsWith("/") ? target : void 0);
-	const pagePath = rawPage ? normalizePagePath(rawPage) : void 0;
-	const blockId = pagePath ? void 0 : target;
-	if (!pagePath && !blockId) throw new Error(USAGE);
-	if (pagePath && options.data) throw new Error("--data applies to block shots only");
-	const widths = parseWidths(options.width);
-	const data = resolveDataArg(options.data);
-	const server = await resolveServer(options.server);
-	let browser;
+	const plan = planShot(target, options);
+	const shotTarget = plan.target;
+	if (shotTarget.kind === "file" && shotTarget.file) checkLocalFile(shotTarget.file, target);
+	const local = shotTarget.kind === "block" || shotTarget.kind === "page";
+	const server = local ? await resolveServer(options.server) : void 0;
+	let page;
 	try {
-		browser = await launchBrowser(options.browser);
-		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 consoleLines = [];
-		cdp.onEvent((method, params) => {
-			if (method === "Runtime.consoleAPICalled" && (params.type === "error" || params.type === "warning")) {
-				const text = (params.args ?? []).map((arg) => arg.value ?? arg.description ?? "").join(" ");
-				consoleLines.push(`[console.${params.type}] ${text}`);
-			}
-			if (method === "Runtime.exceptionThrown") {
-				const details = params.exceptionDetails;
-				consoleLines.push(`[pageerror] ${details?.exception?.description ?? details?.text ?? "unknown error"}`);
-			}
+		page = await openPage(void 0, {
+			width: plan.widths[0],
+			browser: options.browser
 		});
-		await cdp.send("Runtime.enable", {}, sessionId);
-		await cdp.send("Page.enable", {}, sessionId);
-		await setViewport(cdp, sessionId, widths[0]);
-		await cdp.send("Emulation.setEmulatedMedia", { features: [{
-			name: "prefers-reduced-motion",
-			value: "reduce"
-		}] }, sessionId);
-		if (pagePath) await ensurePageExists(server.origin, pagePath);
-		const url = pagePath ? `${server.origin}${pagePath}?mechanica-shot=1` : previewUrl(server.origin, blockId, data);
-		const navigation = await cdp.send("Page.navigate", { url }, sessionId);
-		if (navigation.errorText) throw new Error(`Failed to open ${url}: ${navigation.errorText} (is this a Mechanica project?)`);
-		let previewError = null;
-		if (pagePath) {
-			await waitForCondition(cdp, sessionId, "document.readyState === 'complete'", 15e3);
-			await settlePageMedia(cdp, sessionId);
-		} else {
-			await waitForCondition(cdp, sessionId, "window.__MECHANICA_PREVIEW_READY__ === true", 15e3);
-			previewError = await evaluateValue(cdp, sessionId, "window.__MECHANICA_PREVIEW_ERROR__ ?? null");
+		if (shotTarget.kind === "page") await ensurePageExists(server.origin, shotTarget.path);
+		const url = shotUrl(shotTarget, server, plan.data);
+		try {
+			await page.goto(url, shotTarget.kind === "block" ? {
+				ready: PREVIEW_READY,
+				settle: false
+			} : {});
+		} catch (error) {
+			if (!(error instanceof NavigationError)) throw error;
+			throw new Error(local ? `${error.message} (is this a Mechanica project?)` : error.message);
 		}
-		await freezeAnimations(cdp, sessionId);
+		const previewError = shotTarget.kind === "block" ? await page.evaluate("window.__MECHANICA_PREVIEW_ERROR__ ?? null") : null;
+		if (plan.freeze && !plan.scrolls) await page.freezeAnimations();
 		const outputs = [];
-		for (const width of widths) {
-			await setViewport(cdp, sessionId, width);
-			await cdp.send("Runtime.evaluate", {
-				expression: "new Promise((done) => requestAnimationFrame(() => requestAnimationFrame(done)))",
-				awaitPromise: true
-			}, sessionId);
-			const name = pagePath ? `page-${pageSlug(pagePath)}` : blockId;
-			const out = outputPath(options.out, name, width, widths.length > 1);
-			await mkdir(dirname(out), { recursive: true });
-			const clip = (!pagePath && !options.full && !previewError ? await evaluateValue(cdp, sessionId, `(() => {
-              const el = document.querySelector('[data-block-id]')
-              if (!el) return null
-              const rect = el.getBoundingClientRect()
-              if (rect.width < 1 || rect.height < 1) return null
-              return { x: rect.x + scrollX, y: rect.y + scrollY, width: rect.width, height: rect.height }
-            })()`) : null) ?? await fullPageClip(cdp, sessionId);
-			const shot = await cdp.send("Page.captureScreenshot", {
-				format: "png",
-				captureBeyondViewport: true,
-				clip: {
-					...clip,
-					scale: 1
+		const failures = [];
+		for (const width of plan.widths) {
+			await page.setViewport(width);
+			await page.nextFrame();
+			for (const scroll of plan.scrolls ?? [void 0]) {
+				if (scroll !== void 0) {
+					if (plan.freeze) await page.unfreezeAnimations();
+					const reached = await page.scrollTo(scroll);
+					if (reached + 1 < scroll) console.info(`(at ${width}px the page scrolls only to ${Math.round(reached)}px)`);
+					await page.settle();
+					if (plan.freeze) await page.freezeAnimations();
+				}
+				for (const section of plan.sections.length ? plan.sections : [void 0]) {
+					const out = outputPath(options.out, plan.name, width, plan.widths.length > 1, shotVariant(section?.slug, scroll));
+					let png;
+					try {
+						png = await capture(page, plan.mode, section?.selector, previewError);
+					} catch (error) {
+						if (!section) throw error;
+						const where = `at ${width}px` + (scroll !== void 0 ? `, scrolled to ${scroll}px` : "");
+						failures.push(`--section "${section.selector}" ${where}: ${error instanceof Error ? error.message : error}`);
+						continue;
+					}
+					await mkdir(dirname(out), { recursive: true });
+					fs.writeFileSync(out, png);
+					outputs.push(out);
 				}
-			}, sessionId);
-			fs.writeFileSync(out, Buffer.from(shot.data, "base64"));
-			outputs.push(out);
+			}
 		}
-		for (const line of consoleLines) console.info(line);
+		for (const line of page.messages) console.info(line);
 		for (const out of outputs) console.info(`✓ ${out}`);
 		if (previewError) throw new Error(`Block preview failed: ${previewError}`);
-		if (pagePath && consoleLines.some((line) => line.startsWith("[pageerror]"))) throw new Error("The page threw while rendering — see the [pageerror] output above");
+		if (shotTarget.kind === "page" && page.messages.some((line) => line.startsWith("[pageerror]"))) throw new Error("The page threw while rendering — see the [pageerror] output above");
+		if (failures.length === 1) throw new Error(failures[0]);
+		if (failures.length) {
+			for (const failure of failures) console.error(`✗ ${failure}`);
+			throw new Error(`${failures.length} section captures failed — see the ✗ lines above`);
+		}
 	} finally {
-		await browser?.close();
-		await server.close();
+		await page?.close();
+		await server?.close();
+	}
+}
+/** A local target must be an existing file — a directory would render as a file listing. */
+function checkLocalFile(file, raw) {
+	const stat = fs.statSync(file, { throwIfNoEntry: false });
+	if (stat?.isFile()) return;
+	const problem = stat ? `${file} is a directory, not an HTML file` : `File not found: ${file}`;
+	const msys = process.env.MSYSTEM && !HTML_FILE.test(raw) && WINDOWS_DRIVE_PATH.test(raw);
+	throw new Error(msys ? `${problem}. If you meant a page path, Git Bash rewrote it: write it with two slashes (//about) or set MSYS_NO_PATHCONV=1` : problem);
+}
+function shotUrl(target, server, data) {
+	switch (target.kind) {
+		case "block": return previewUrl(server.origin, target.blockId, data);
+		case "page": return `${server.origin}${target.path}?mechanica-shot=1`;
+		default: return target.url;
+	}
+}
+async function capture(page, mode, selector, previewError) {
+	switch (mode) {
+		case "section": return page.screenshot({ section: selector });
+		case "viewport": return page.screenshot();
+		case "full": return page.screenshot({ full: true });
+		case "block": {
+			const clip = previewError ? null : await page.sectionClip("[data-block-id]").catch(() => null);
+			return page.screenshot(clip ? { clip } : { full: true });
+		}
 	}
 }
 /** Fail early with the list of real pages instead of shooting an empty 200. */
@@ -1134,7 +1033,7 @@ function orphanThumbs(files, slugs) {
 async function runThumbs(prefix, options = {}) {
 	const normalizedPrefix = prefix ? normalizePagePath(prefix) : void 0;
 	const server = await resolveServer(options.server);
-	let browser;
+	let tab;
 	try {
 		const listed = await fetch(`${server.origin}/@mechanica/pages`);
 		if (!listed.ok) throw new Error(`Could not list pages (${listed.status}) — is this a Mechanica project?`);
@@ -1146,43 +1045,29 @@ async function runThumbs(prefix, options = {}) {
 		}
 		const outDir = options.out ?? join(".mech", "thumbs");
 		await mkdir(outDir, { recursive: true });
-		browser = await launchBrowser(options.browser);
-		const cdp = browser.client;
-		const { targetId } = await cdp.send("Target.createTarget", { url: "about:blank" });
-		const { sessionId } = await cdp.send("Target.attachToTarget", {
-			targetId,
-			flatten: true
+		tab = await openPage(void 0, {
+			width: CAPTURE_WIDTH,
+			height: VIEWPORT_HEIGHT,
+			browser: options.browser
 		});
-		await cdp.send("Page.enable", {}, sessionId);
-		await cdp.send("Runtime.enable", {}, sessionId);
-		await setViewport(cdp, sessionId, CAPTURE_WIDTH, VIEWPORT_HEIGHT);
-		await cdp.send("Emulation.setEmulatedMedia", { features: [{
-			name: "prefers-reduced-motion",
-			value: "reduce"
-		}] }, sessionId);
 		const failures = [];
 		for (const page of targets) try {
-			const navigation = await cdp.send("Page.navigate", { url: `${server.origin}${page.path}?mechanica-shot=1` }, sessionId);
-			if (navigation.errorText) throw new Error(navigation.errorText);
-			await waitForCondition(cdp, sessionId, "document.readyState === 'complete'", 15e3);
-			await settlePageMedia(cdp, sessionId);
-			await freezeAnimations(cdp, sessionId);
-			const metrics = await cdp.send("Page.getLayoutMetrics", {}, sessionId);
+			await tab.goto(`${server.origin}${page.path}?mechanica-shot=1`);
+			await tab.freezeAnimations();
+			const metrics = await tab.send("Page.getLayoutMetrics");
 			const contentSize = metrics.cssContentSize ?? metrics.contentSize;
 			const height = Math.min(Math.ceil(contentSize.height), MAX_CAPTURE_HEIGHT);
-			const shot = await cdp.send("Page.captureScreenshot", {
-				format: "png",
-				captureBeyondViewport: true,
+			const png = await tab.screenshot({
 				clip: {
 					x: 0,
 					y: 0,
 					width: CAPTURE_WIDTH,
-					height,
-					scale: THUMB_WIDTH / CAPTURE_WIDTH
-				}
-			}, sessionId);
+					height
+				},
+				scale: THUMB_WIDTH / CAPTURE_WIDTH
+			});
 			const out = join(outDir, `${pageSlug(page.path)}.png`);
-			fs.writeFileSync(out, Buffer.from(shot.data, "base64"));
+			fs.writeFileSync(out, png);
 			console.info(`✓ ${page.path} → ${out}`);
 		} catch (error) {
 			failures.push(page.path);
@@ -1197,7 +1082,7 @@ async function runThumbs(prefix, options = {}) {
 		}
 		if (failures.length) throw new Error(`Failed to render ${failures.length} page(s): ${failures.join(", ")}`);
 	} finally {
-		await browser?.close();
+		await tab?.close();
 		await server.close();
 	}
 }
@@ -1215,7 +1100,7 @@ var BLOCK_THUMB_WIDTH = 240;
 */
 async function runBlockThumbs(filter, options = {}) {
 	const server = await resolveServer(options.server);
-	let browser;
+	let tab;
 	try {
 		const listed = await fetch(`${server.origin}/@mechanica/blocks`);
 		if (!listed.ok) throw new Error(`Could not list blocks (${listed.status}) — is this a Mechanica project?`);
@@ -1227,44 +1112,34 @@ async function runBlockThumbs(filter, options = {}) {
 		}
 		const outDir = options.out ?? join(".mech", "thumbs", "blocks");
 		await mkdir(outDir, { recursive: true });
-		browser = await launchBrowser(options.browser);
-		const cdp = browser.client;
-		const { targetId } = await cdp.send("Target.createTarget", { url: "about:blank" });
-		const { sessionId } = await cdp.send("Target.attachToTarget", {
-			targetId,
-			flatten: true
+		tab = await openPage(void 0, {
+			width: BLOCK_CAPTURE_WIDTH,
+			height: BLOCK_MAX_HEIGHT,
+			browser: options.browser
 		});
-		await cdp.send("Page.enable", {}, sessionId);
-		await cdp.send("Runtime.enable", {}, sessionId);
-		await setViewport(cdp, sessionId, BLOCK_CAPTURE_WIDTH, BLOCK_MAX_HEIGHT);
-		await cdp.send("Emulation.setEmulatedMedia", { features: [{
-			name: "prefers-reduced-motion",
-			value: "reduce"
-		}] }, sessionId);
 		const failures = [];
 		for (const block of targets) try {
-			const navigation = await cdp.send("Page.navigate", { url: previewUrl(server.origin, block.id) }, sessionId);
-			if (navigation.errorText) throw new Error(navigation.errorText);
-			await waitForCondition(cdp, sessionId, "window.__MECHANICA_PREVIEW_READY__ === true", 15e3);
-			const previewError = await evaluateValue(cdp, sessionId, "window.__MECHANICA_PREVIEW_ERROR__ ?? null");
+			await tab.goto(previewUrl(server.origin, block.id), {
+				ready: PREVIEW_READY,
+				settle: false
+			});
+			const previewError = await tab.evaluate("window.__MECHANICA_PREVIEW_ERROR__ ?? null");
 			if (previewError) throw new Error(previewError);
-			await settlePageMedia(cdp, sessionId);
-			await freezeAnimations(cdp, sessionId);
-			const measured = await evaluateValue(cdp, sessionId, `document.querySelector('[data-block-id]')?.getBoundingClientRect().height ?? 0`);
+			await tab.settle();
+			await tab.freezeAnimations();
+			const measured = await tab.evaluate(`document.querySelector('[data-block-id]')?.getBoundingClientRect().height ?? 0`);
 			const height = Math.min(BLOCK_MAX_HEIGHT, Math.max(BLOCK_MIN_HEIGHT, Math.ceil(measured)));
-			const shot = await cdp.send("Page.captureScreenshot", {
-				format: "png",
-				captureBeyondViewport: true,
+			const png = await tab.screenshot({
 				clip: {
 					x: 0,
 					y: 0,
 					width: BLOCK_CAPTURE_WIDTH,
-					height,
-					scale: BLOCK_THUMB_WIDTH / BLOCK_CAPTURE_WIDTH
-				}
-			}, sessionId);
+					height
+				},
+				scale: BLOCK_THUMB_WIDTH / BLOCK_CAPTURE_WIDTH
+			});
 			const out = join(outDir, `${block.id}.png`);
-			fs.writeFileSync(out, Buffer.from(shot.data, "base64"));
+			fs.writeFileSync(out, png);
 			console.info(`✓ ${block.id} → ${out}`);
 		} catch (error) {
 			failures.push(block.id);
@@ -1279,7 +1154,7 @@ async function runBlockThumbs(filter, options = {}) {
 		}
 		if (failures.length) throw new Error(`Failed to render ${failures.length} block(s): ${failures.join(", ")}`);
 	} finally {
-		await browser?.close();
+		await tab?.close();
 		await server.close();
 	}
 }
@@ -1314,8 +1189,14 @@ Usage:
                             the site, any other gets an address of its own
   mechanica shot <blockId>  Screenshot one block via the dev preview route
   mechanica shot </path>    Screenshot a whole page (editor overlay stripped)
+  mechanica shot <url | file.html>
+                            Screenshot any URL or local HTML file (a design
+                            handoff) the same way, without a dev server
                             (--page </path>, --data <json|@file>, --width 1440,768,
-                             --out <path>, --server <url>, --browser <path>, --full)
+                             --section <css> (repeatable: one PNG per section),
+                             --scroll <px[,px…]> (viewport after scrolling),
+                             --no-freeze, --full, --out <path>, --server <url>,
+                             --browser <path>)
   mechanica thumbs [/path]  Thumbnail every page (or those under /path) into
                             .mech/thumbs/ for the editor's page browser
                             (--out <dir>, --server <url>, --browser <path>)
@@ -1333,10 +1214,12 @@ Usage:
   mechanica migrate         Bring .mech content up to the current format: uploads
                             are referenced as /media/<file> (was /@mechanica/assets/)
 `;
+var PARSE_OPTIONS = { booleans: ["full", "no-freeze"] };
 /** CLI entry: dispatch a command to its handler. */
 async function run(argv) {
-	const { command, args, flags } = parseArgs(argv);
+	const { command, args, flags } = parseArgs(argv, PARSE_OPTIONS);
 	const str = (value) => typeof value === "string" ? value : void 0;
+	const required = (value) => value === true ? "" : str(value);
 	switch (command) {
 		case "build": return runBuild({ editor: flags.editor === true });
 		case "export": return runExport({
@@ -1370,7 +1253,10 @@ async function run(argv) {
 			out: str(flags.out),
 			server: str(flags.server),
 			browser: str(flags.browser),
-			full: flags.full === true
+			full: flags.full === true,
+			section: flagValues(argv, "section", PARSE_OPTIONS).map((value) => required(value) ?? ""),
+			scroll: required(flags.scroll),
+			noFreeze: flags["no-freeze"] === true
 		});
 		case "thumbs": {
 			const thumbsOptions = {