mechanica 2.2.0 → 2.2.1

package/README.md

@@ -361,7 +361,7 @@ These drive a locally installed Chrome or Edge (or `--browser <path>`) and need
 | --- | --- |
 | `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 \| 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 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; also inside open shadow roots, `#name` also finds the block `[data-block-id="name"]`), `--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) |
@@ -399,7 +399,7 @@ 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`.
+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)` (document, then open shadow roots; `#name` falls back to `[data-block-id="name"]`), `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'

package/dist/browser.js

@@ -1,2 +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";
+import { i as openPage, n as PAGE_LOADED, o as MAX_SHOT_HEIGHT, r as describeSectionError, s as findDevServer, t as NavigationError } from "./chunks/browser-BV2iB_xD.js";
 export { MAX_SHOT_HEIGHT, NavigationError, PAGE_LOADED, describeSectionError, findDevServer, openPage };

package/dist/chunks/{browser-BCfAv8bW.js → browser-BV2iB_xD.js}

@@ -1,7 +1,7 @@
 import fs from "node:fs";
-import { join } from "node:path";
+import { join, win32 } from "node:path";
 import os from "node:os";
-import { spawn } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
 //#region src/cli/headless.ts
 /**
 * Headless-browser plumbing shared by `mechanica shot`, `mechanica thumbs` and
@@ -133,13 +133,56 @@ async function viewportClip(cdp, sessionId) {
 		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. Prefers browsers already on the machine (Edge ships with Windows,
-* Chrome is everywhere), so nothing needs downloading.
+* 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) {
-	const executable = findBrowserExecutable(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",
@@ -150,55 +193,128 @@ async function launchBrowser(explicitPath) {
 		"--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;
+	], {
+		stdio: [
+			"ignore",
+			"ignore",
+			"pipe"
+		],
+		env: browserEnv()
+	});
+	let client;
 	try {
-		endpoint = await waitForDevtoolsEndpoint(child, 2e4);
+		const endpoint = await waitForDevtoolsEndpoint(child, STARTUP_TIMEOUT);
+		client = await CdpClient.connect(endpoint);
 	} catch (error) {
-		await cleanup();
-		throw new Error(`Failed to start ${executable.label} (${executable.path}): ${error instanceof Error ? error.message : error}`);
+		await killBrowserTree(child, userDataDir);
+		await removeProfile(userDataDir);
+		throw error;
 	}
-	const client = await CdpClient.connect(endpoint);
 	return {
 		client,
 		close: async () => {
 			await client.send("Browser.close").catch(() => {});
 			client.dispose();
-			await cleanup();
+			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]);
 			}
@@ -207,54 +323,60 @@ function waitForDevtoolsEndpoint(child, timeout) {
 			clearTimeout(timer);
 			reject(error);
 		});
-		child.on("exit", (code) => {
+		child.on("exit", (code, signal) => {
 			clearTimeout(timer);
-			reject(/* @__PURE__ */ new Error(`browser exited early (code ${code})`));
+			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}` : ""}`));
 		});
 	});
 }
-/** 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");
+/**
+* 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: "Microsoft Edge",
-				path: join(programFilesX86, "Microsoft", "Edge", "Application", "msedge.exe")
+				label: "Google Chrome",
+				path: win32.join(programFiles, ...chrome)
 			},
 			{
-				label: "Microsoft Edge",
-				path: join(programFiles, "Microsoft", "Edge", "Application", "msedge.exe")
+				label: "Google Chrome",
+				path: win32.join(programFilesX86, ...chrome)
 			},
 			{
 				label: "Google Chrome",
-				path: join(programFiles, "Google", "Chrome", "Application", "chrome.exe")
+				path: win32.join(localAppData, ...chrome)
 			},
 			{
-				label: "Google Chrome",
-				path: join(localAppData, "Google", "Chrome", "Application", "chrome.exe")
+				label: "Microsoft Edge",
+				path: win32.join(programFilesX86, ...edge)
+			},
+			{
+				label: "Microsoft Edge",
+				path: win32.join(programFiles, ...edge)
 			}
 		];
 	}
-	if (process.platform === "darwin") return [
+	if (platform === "darwin") return [
 		{
 			label: "Google Chrome",
 			path: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
@@ -353,6 +475,138 @@ var CdpClient = class CdpClient {
 		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
 /**
@@ -413,7 +667,7 @@ async function openPage(url, options = {}) {
 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 "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?`;
 	}
 }
@@ -501,25 +755,23 @@ var HeadlessPage = class HeadlessPage {
 		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()
+		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 }
-    })(${JSON.stringify(selector)})`);
+    })(${FIND_SECTION_SOURCE}, ${JSON.stringify(parts)}, ${JSON.stringify(fallback)})`);
 		if ("error" in box) throw new Error(describeSectionError(selector, box));
 		return box;
 	}
@@ -555,4 +807,4 @@ var HeadlessPage = class HeadlessPage {
 	}
 };
 //#endregion
-export { MAX_SHOT_HEIGHT as a, openPage as i, PAGE_LOADED as n, findDevServer as o, describeSectionError as r, NavigationError as t };
+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 };

package/dist/cli.js

@@ -2,7 +2,7 @@ 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 { a as splitShadowSelector, i as openPage, s as findDevServer, t as NavigationError } from "./chunks/browser-BV2iB_xD.js";
 import fs, { readFileSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { EDITOR_DIST_DIR, LEGACY_UPLOADS_PREFIX, SITE_MANIFEST_FILE, UPLOADS_PREFIX } from "mechanica-shared";
@@ -679,7 +679,7 @@ async function resolveServer(flag) {
 }
 //#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>]";
+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>]\n--section also looks inside open shadow roots (\"host >>> inner\" crosses one explicitly); a bare #name (or name) that matches nothing finds the Mechanica block [data-block-id=\"name\"].";
 /** 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]`. */
@@ -863,6 +863,11 @@ function planShot(target, options = {}, cwd = process.cwd()) {
 	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\"");
+	for (const selector of selectors) try {
+		splitShadowSelector(selector);
+	} catch (error) {
+		throw new Error(`--section "${selector}": ${error instanceof Error ? error.message : error}`);
+	}
 	const slugs = sectionSlugs(selectors);
 	const scrolls = parseScrolls(options.scroll);
 	return {
@@ -1193,7 +1198,9 @@ Usage:
                             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,
-                             --section <css> (repeatable: one PNG per section),
+                             --section <css> (repeatable: one PNG per section;
+                             looks inside open shadow roots, "host >>> inner"
+                             crosses one; #name also finds [data-block-id=name]),
                              --scroll <px[,px…]> (viewport after scrolling),
                              --no-freeze, --full, --out <path>, --server <url>,
                              --browser <path>)

package/dist/types/cli/browser.d.ts

@@ -25,7 +25,10 @@ export interface OpenPageOptions extends GotoOptions {
     width?: number;
     /** Viewport height in CSS px. Default 900. */
     height?: number;
-    /** A Chromium-based executable. Default: Edge or Chrome from their usual install paths. */
+    /**
+     * A Chromium-based executable. Default: the first installed browser that
+     * starts, from the usual install paths (on Windows Chrome, then Edge).
+     */
     browser?: string;
     /**
      * Emulate `prefers-reduced-motion: reduce`, as `mechanica shot` does: pages
@@ -36,7 +39,7 @@ export interface OpenPageOptions extends GotoOptions {
 export interface ScreenshotOptions {
     /** An explicit region in document coordinates. Wins over everything else. */
     clip?: Clip;
-    /** A CSS selector: the bounding box of the first matching element. */
+    /** A CSS selector: the bounding box of the first matching element (see {@link BrowserPage.sectionClip}). */
     section?: string;
     /** The whole document (height capped at {@link MAX_SHOT_HEIGHT}). */
     full?: boolean;
@@ -71,7 +74,13 @@ export interface BrowserPage {
     freezeAnimations(): Promise<void>;
     /** Undo {@link freezeAnimations}. */
     unfreezeAnimations(): Promise<void>;
-    /** The document-coordinate box of the first element matching `selector`. Throws when none matches or the box is empty. */
+    /**
+     * The document-coordinate box of the first element matching `selector`.
+     * Looks in the document, then in every open shadow root (`host >>> inner`
+     * crosses into `host`'s shadow root explicitly). A bare `#name` or `name`
+     * that matches nothing falls back to `[data-block-id="name"]`, a Mechanica
+     * block. Throws when nothing matches or the box is empty.
+     */
     sectionClip(selector: string): Promise<Clip>;
     /**
      * A PNG of the page: `clip`, else `section`, else `full`, else what is in
@@ -106,7 +115,12 @@ type SectionBox = Clip | {
     message: string;
 } | {
     error: 'missing';
+    /** Readable ids on the page (`#name`), shadow roots included. */
     ids: string[];
+    /** `data-block-id` values on the page. */
+    blockIds?: string[];
+    /** The block-id selector that was tried as well. */
+    fallback?: string | null;
 } | {
     error: 'empty';
     width: number;

package/dist/types/cli/headless.d.ts

@@ -42,12 +42,54 @@ export interface LaunchedBrowser {
     client: CdpClient;
     close: () => Promise<void>;
 }
+/** A Chromium-based browser executable to try. */
+export interface BrowserExecutable {
+    label: string;
+    path: string;
+}
 /**
  * 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.
+ * 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.
  */
 export declare function launchBrowser(explicitPath?: string): Promise<LaunchedBrowser>;
+/**
+ * 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.
+ */
+export declare function startFirstBrowser<T>(candidates: BrowserExecutable[], start: (candidate: BrowserExecutable) => Promise<T>): Promise<T>;
+/**
+ * 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.
+ */
+export declare function startBrowser(executable: BrowserExecutable): Promise<LaunchedBrowser>;
+/**
+ * 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.
+ */
+export declare function browserEnv(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): NodeJS.ProcessEnv;
+/**
+ * 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.
+ */
+export declare function windowsKillCommands(pid: number | undefined, userDataDir: string): Array<[string, string[]]>;
+/**
+ * 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}).
+ */
+export declare function platformBrowserCandidates(platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv, home?: string): BrowserExecutable[];
 type CdpEventListener = (method: string, params: any, sessionId?: string) => void;
 /**
  * A minimal Chrome DevTools Protocol client over the platform `WebSocket`

package/dist/types/cli/section-query.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Finding the element behind a section selector (`mechanica shot --section`,
+ * `BrowserPage.sectionClip`): the lookup that runs in the page, and the pure
+ * helpers that prepare its arguments.
+ *
+ * - **Shadow DOM.** Design handoffs render their sections inside custom
+ *   elements with open shadow roots, where `document.querySelector` sees
+ *   nothing. The lookup tries the document first, then every open shadow root
+ *   in tree order (depth first), matching the selector within each root.
+ *   Slotted content belongs to its host's tree, so that tree's query covers
+ *   it. `host >>> inner` crosses into the shadow root of `host` explicitly.
+ * - **Block ids.** Mechanica renders a block with `data-block-id="<node id>"`
+ *   and no `id`, so a bare `#hero` (or `hero`) that matches nothing falls back
+ *   to `[data-block-id="hero"]`.
+ */
+/** Crosses into the shadow root of the elements matched by the part before it. */
+export declare const SHADOW_COMBINATOR = ">>>";
+/**
+ * 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 >>>`).
+ */
+export declare function splitShadowSelector(selector: string): string[];
+/**
+ * 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.
+ */
+export declare function blockIdFallback(selector: string): string | null;
+/** Readable ids and block ids listed in a "no match" error, at most this many of each. */
+export declare const MAX_LISTED_IDS = 20;
+/**
+ * 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.
+ */
+export declare const FIND_SECTION_SOURCE: string;

package/dist/types/cli/shot.d.ts

@@ -13,7 +13,12 @@ export interface ShotOptions {
     browser?: string;
     /** Screenshot the full page instead of clipping to the block element (or to the viewport with `scroll`). */
     full?: boolean;
-    /** CSS selectors (`--section`, repeatable): one PNG each, clipped to the first match. Page/URL/file shots only. */
+    /**
+     * CSS selectors (`--section`, repeatable): one PNG each, clipped to the first
+     * match — in the document or an open shadow root (`host >>> inner` crosses
+     * one explicitly); a bare `#name` that matches nothing finds
+     * `[data-block-id="name"]`. Page/URL/file shots only.
+     */
     section?: string[];
     /** Scroll offset(s) in px, comma-separated: capture the viewport scrolled there. */
     scroll?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mechanica",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "description": "Build Vue 3 websites with a visual block editor",
   "license": "MIT",
   "repository": {
@@ -70,7 +70,7 @@
     "prepublishOnly": "bun ../../scripts/ensure-bun-publish.js && bun run build"
   },
   "dependencies": {
-    "mechanica-shared": "2.2.0",
+    "mechanica-shared": "2.2.1",
     "@vue/compiler-sfc": "^3.5.38",
     "compact-json-schema": "^0.1.5",
     "estree-walker": "^3.0.3",