mechanica 2.2.0 → 2.2.2

package/README.md

@@ -156,6 +156,8 @@ Other `defineBlock` options: `icon`, `description` and `order` for the palette;
 
 Give every block meaningful `previewData`: it drives the palette's hover preview, the standalone preview route and `mechanica shot`. A `$slots` key fills slots with child blocks, e.g. `$slots: { default: [{ blockId: 'card', data: { title: 'One' } }] }`.
 
+The exported site is prerendered, and the browser **hydrates** that HTML rather than rendering it again, so a block must render the same on the server and in the browser: read `window`, `document` or `matchMedia` only in `onMounted` (or behind a client-only flag set there), never in `setup` or the template. The dev server mounts into an empty page and never hydrates, so a mismatch shows only in the built site. To check, build with `MECHANICA_HYDRATION_DEBUG=1 mechanica build` and watch the browser console on the exported pages: each mismatch is logged with the element involved.
+
 ## Pages
 
 Each page is a `.page.md` file under `.mech/pages/`, and its path is the URL: `about.page.md` → `/about`, `blog/index.page.md` → `/blog`, `index.page.md` → `/`.
@@ -254,7 +256,7 @@ Editors can set a focal point and crop from the image field's **Position / Crop*
 
 ## Links and navigation
 
-`<Link :to="…">` takes a path string or a `smartLink` value. Internal links navigate client-side without a full reload, get an `is-active` class on the current page, and add the language prefix on multi-language sites. `useRouter().push(path)` navigates from code, and `useRoute().path` is the current path.
+`<Link :to="…">` takes a path string or a `smartLink` value. Internal links navigate client-side without a full reload, get an `is-active` class on the current page, and add the language prefix on multi-language sites. `useRouter().push(path)` navigates from code, and `useRoute().path` is the current path. A target the client-side navigation cannot take over (an error response, or a page without Mechanica state) is opened as a normal full-page navigation instead.
 
 ## Listing pages and pagination
 
@@ -339,6 +341,8 @@ Every export also warns about missing titles and descriptions, pages without exa
 
 By default all blocks share one `blocks` chunk, cached across pages. Mark heavy, rarely used blocks with `chunk: 'charts'` in `defineBlock` to split them into their own chunk, or set the plugin's `blockChunks: 'per-block'`. The export adds per-page `<link rel="modulepreload">` and stylesheet tags, so each page loads exactly the block code it uses.
 
+Code outside blocks follows Vite's defaults. To group it yourself, add your own groups under `build.rollupOptions.output.codeSplitting.groups` in `vite.config.ts`: they are kept next to Mechanica's blocks group and listed before it, so at equal `priority` yours win. The plugin sets `includeDependenciesRecursively: false`, so a group holds exactly the modules its `test` matches.
+
 ## Checking your work visually
 
 ```bash
@@ -361,7 +365,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 +403,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/chunks/{create-mechanica-CYaKXuQd.js → create-mechanica-CMcmeOtG.js}

@@ -1,5 +1,5 @@
 import { computed, defineComponent, h, inject, nextTick, shallowReactive, shallowRef } from "vue";
-import { localePath, resolveComposedTemplate, templateBlockIds, walkTree } from "mechanica-shared";
+import { localePath, paginationVariantPath, resolveComposedTemplate, templateBlockIds, walkTree } from "mechanica-shared";
 //#region src/core/state.ts
 /** Vue injection key for the {@link MechanicaContext}. */
 var mechanicaKey = Symbol("mechanica");
@@ -36,7 +36,7 @@ function createRouter(content, data, options) {
 		if (!baseUrl) return path;
 		return path.startsWith(baseUrl) ? path.slice(baseUrl.length) : path;
 	};
-	const initialPath = isBrowser ? normalizePath(stripBase(window.location.pathname)) : "/";
+	const initialPath = isBrowser ? normalizePath(stripBase(window.location.pathname)) : normalizePath(options.initialPath ?? "/");
 	const currentRoute = shallowReactive({ path: initialPath });
 	const cache = /* @__PURE__ */ new Map();
 	const inflight = /* @__PURE__ */ new Map();
@@ -45,12 +45,14 @@ function createRouter(content, data, options) {
 		const existing = inflight.get(path);
 		if (existing) return existing;
 		const run = async () => {
-			const html = await fetch(path).then((res) => res.text());
+			const res = await fetch(path);
+			const html = res.ok ? await res.text() : "";
 			const match = html.match(/window\.state\s*=\s*(\{.+?\})<\/script>/s)?.[1];
-			const state = match ? JSON.parse(match) : {
-				content: [],
-				data: {}
-			};
+			if (!match) {
+				if (isBrowser) window.location.assign(path);
+				return;
+			}
+			const state = JSON.parse(match);
 			state.page = {
 				...state.page,
 				title: html.match(/<title>(.*?)<\/title>/)?.[1]
@@ -869,6 +871,25 @@ function runtimeLayoutNames() {
 	return window[RUNTIME_KEY]?.layoutNames ?? [];
 }
 //#endregion
+//#region src/core/page-path.ts
+/**
+* The address a page's state is served at: its logical `path` under the
+* locale prefix (`/about` -> `/ru/about`) plus the pagination variant suffix
+* (`/blog` -> `/blog/2`). This is what the browser shows in the address bar for
+* that state, so the server-side router starts there and `<Link>` resolves the
+* same `is-active` on both sides of hydration.
+*
+* The export already serves a variant under its own path (`page.path` is
+* `/blog/2` there, while dev keeps the base `/blog`); a suffix that is
+* already present is kept, as `usePagination().pathFor` does.
+*/
+function servedPagePath(page, locales) {
+	const localized = localePath(page?.path || "/", page?.locale, locales);
+	const variant = page?.pagination?.page ?? 1;
+	if (variant > 1 && localized.endsWith(`/${variant}`)) return localized;
+	return paginationVariantPath(localized, variant);
+}
+//#endregion
 //#region src/core/create-mechanica.ts
 /**
 * Vue plugin that wires the Mechanica runtime: page content, shared data, the
@@ -903,6 +924,7 @@ function createMechanica(options = {}) {
 			router: createRouter(content, data, {
 				mode,
 				baseUrl: initial?.baseUrl,
+				initialPath: servedPagePath(initial?.page, initial?.locales),
 				ensureBlocks: loaders ? async (next) => {
 					await loadBlocks(loaders, next, blocks, composedMap);
 				} : void 0,
@@ -927,7 +949,7 @@ function createMechanica(options = {}) {
 			mergeData: (incoming) => mergeData(context.data, incoming),
 			setPage: (next) => {
 				applyPage(next);
-				if (next.path) context.router.currentRoute.path = context.router.normalizePath(next.path);
+				if (next.path) context.router.currentRoute.path = context.router.normalizePath(servedPagePath(next, initial?.locales));
 			}
 		});
 	} };

package/dist/chunks/{preview-CbUxh2gL.js → preview-BrtQ0KpO.js}

@@ -1,4 +1,4 @@
-import { a as renderBlocks, t as createMechanica } from "./create-mechanica-CYaKXuQd.js";
+import { a as renderBlocks, t as createMechanica } from "./create-mechanica-CMcmeOtG.js";
 import { createApp, defineComponent, h } from "vue";
 import { areFieldSchemasRegistered, buildPreviewData, registerFieldSchemas } from "mechanica-shared";
 import { unfoldSchema } from "compact-json-schema";

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/composer.js

@@ -1,5 +1,5 @@
 import './editor.css';
-import { a as renderBlocks, l as ANCHOR_H, t as createMechanica, u as ANCHOR_V } from "./chunks/create-mechanica-CYaKXuQd.js";
+import { a as renderBlocks, l as ANCHOR_H, t as createMechanica, u as ANCHOR_V } from "./chunks/create-mechanica-CMcmeOtG.js";
 import { A as SmartLinkField_default, C as removeBlock, I as editorBackend, L as createSaveQueue, R as VSelect_default, S as relocateBlock, T as registerBuiltinFieldEditors, _ as findBlock, a as FieldControl_default, b as moveBlock, f as toBlockMeta, g as ensureSlotList, h as duplicateBlock, i as SchemaField_default, m as cloneBlock, n as normalizeTemplate, o as shortcutChar, p as humanize, v as findParentList, w as uid, x as placeBlock, y as findParentSlot, z as VPopover_default } from "./chunks/editor-DoYHG0mS.js";
 import { d as _plugin_vue_export_helper_default, l as VIcon_default, u as contents } from "./chunks/ImagePickerDialog-DJGhtW3r.js";
 import { Fragment, Teleport, computed, createApp, createBlock, createCommentVNode, createElementBlock, createElementVNode, createTextVNode, createVNode, defineComponent, inject, nextTick, normalizeClass, normalizeStyle, onBeforeUnmount, onMounted, onScopeDispose, openBlock, provide, reactive, ref, renderList, renderSlot, resolveComponent, toDisplayString, unref, vModelText, watch, withCtx, withDirectives, withKeys, withModifiers } from "vue";

package/dist/editor.js

@@ -1,6 +1,6 @@
 import './editor.css';
-import { _ as mechanicaKey, a as renderBlocks, c as registerElements, i as createComposedComponent, m as createRouter, n as pushStateUpdate, r as runtimeLayoutNames } from "./chunks/create-mechanica-CYaKXuQd.js";
-import { i as getDataEntries, t as buildPreviewContent } from "./chunks/preview-CbUxh2gL.js";
+import { _ as mechanicaKey, a as renderBlocks, c as registerElements, i as createComposedComponent, m as createRouter, n as pushStateUpdate, r as runtimeLayoutNames } from "./chunks/create-mechanica-CMcmeOtG.js";
+import { i as getDataEntries, t as buildPreviewContent } from "./chunks/preview-BrtQ0KpO.js";
 import { C as removeBlock, D as contextMenuKey, E as registerRichTextWidgets, F as pathFromName, I as editorBackend, L as createSaveQueue, M as filterPages, N as groupPagesByFolder, O as createContextMenu, P as pageThumbUrl, R as VSelect_default, S as relocateBlock, T as registerBuiltinFieldEditors, _ as findBlock, b as moveBlock, c as blockAvailableIn, d as isUnderFolder, f as toBlockMeta, h as duplicateBlock, j as fetchPages, k as VSegmented_default, l as compareBlocks, m as cloneBlock, o as shortcutChar, p as humanize, r as SchemaForm_default, s as blockAvailableForLayout, t as createRootFrame, u as createContentBlock, w as uid, x as placeBlock, y as findParentSlot, z as VPopover_default } from "./chunks/editor-DoYHG0mS.js";
 import { c as useDialog, d as _plugin_vue_export_helper_default, l as VIcon_default, n as VDialog_default, o as createDialogStore, s as dialogKey } from "./chunks/ImagePickerDialog-DJGhtW3r.js";
 import { Fragment, Teleport, Transition, TransitionGroup, computed, createApp, createBlock, createCommentVNode, createElementBlock, createElementVNode, createTextVNode, createVNode, defineComponent, inject, markRaw, mergeProps, nextTick, normalizeClass, normalizeStyle, onBeforeUnmount, onErrorCaptured, onMounted, onScopeDispose, openBlock, provide, reactive, ref, renderList, resolveComponent, resolveDynamicComponent, shallowRef, toDisplayString, unref, useTemplateRef, vModelCheckbox, vModelText, watch, withCtx, withDirectives, withModifiers } from "vue";

package/dist/index.js

@@ -1,5 +1,5 @@
-import { _ as mechanicaKey, a as renderBlocks, c as registerElements, d as Link, f as loadBlocks, g as useRouter, h as useRoute, i as createComposedComponent, m as createRouter, o as elements, p as usedBlockIds, s as isElementBlock, t as createMechanica } from "./chunks/create-mechanica-CYaKXuQd.js";
-import { a as registerDataEntry, i as getDataEntries, n as mountPreviewApp, r as clearDataEntries, t as buildPreviewContent } from "./chunks/preview-CbUxh2gL.js";
+import { _ as mechanicaKey, a as renderBlocks, c as registerElements, d as Link, f as loadBlocks, g as useRouter, h as useRoute, i as createComposedComponent, m as createRouter, o as elements, p as usedBlockIds, s as isElementBlock, t as createMechanica } from "./chunks/create-mechanica-CMcmeOtG.js";
+import { a as registerDataEntry, i as getDataEntries, n as mountPreviewApp, r as clearDataEntries, t as buildPreviewContent } from "./chunks/preview-BrtQ0KpO.js";
 import { computed, createApp, createSSRApp, defineComponent, h, inject, isReactive, onMounted, onServerPrefetch, reactive, ref, shallowReactive } from "vue";
 import { localePath, normalizeClassManifest, passDefaultValue } from "mechanica-shared";
 import { unfoldSchema } from "compact-json-schema";
@@ -205,13 +205,13 @@ var Image = defineComponent({
 			const cropped = !!image.croppedSrc;
 			return h("img", {
 				ref: el,
+				loading: props.eager ? "eager" : "lazy",
+				fetchpriority: props.eager ? "high" : void 0,
+				decoding: "async",
 				src: cropped ? image.croppedSrc : image.src,
 				alt: image.alt ?? "",
 				width: (cropped ? image.croppedWidth : image.width) ?? void 0,
 				height: (cropped ? image.croppedHeight : image.height) ?? void 0,
-				loading: props.eager ? "eager" : "lazy",
-				fetchpriority: props.eager ? "high" : void 0,
-				decoding: "async",
 				style: lqipStyle.value,
 				onLoad: () => {
 					loaded.value = true;

package/dist/plugin.js

@@ -660,6 +660,7 @@ function generateComponentsModule(manifestSpecifier) {
 * `createApp().mount()` with an explicit, generated entry.
 */
 function generateClientEntry(options) {
+	const hydrate = options.hydrate ? "ssr: true, " : "";
 	if (options.lazy) return [
 		`import 'virtual:mechanica/elements.css'`,
 		`import definition from ${JSON.stringify(options.userEntry)}`,
@@ -672,7 +673,7 @@ function generateClientEntry(options) {
 		`const composedMap = new Map(composedList.map((def) => [def.id, def]))`,
 		`loadBlocks(blockLoaders, state.content ?? [], undefined, composedMap).then((blocks) => {`,
 		`  registerComponents(blocks)`,
-		`  createMechanicaApp(definition, { mode: ${JSON.stringify(options.mode)}, state, blocks, blockLoaders, composed: composedList })`,
+		`  createMechanicaApp(definition, { ${hydrate}mode: ${JSON.stringify(options.mode)}, state, blocks, blockLoaders, composed: composedList })`,
 		`    .mount(${JSON.stringify(options.mount)})`,
 		`})`,
 		``
@@ -697,7 +698,7 @@ function generateClientEntry(options) {
 		`const state = window.state ?? { content: [], data: {} }`,
 		`registerComponents(blocksMap)`,
 		...resolveQuery,
-		`createMechanicaApp(definition, { mode: ${JSON.stringify(options.mode)}, state, blocks: blocksMap, composed: composedList${options.mode === "dev" ? ", resolveQuery" : ""} })`,
+		`createMechanicaApp(definition, { ${hydrate}mode: ${JSON.stringify(options.mode)}, state, blocks: blocksMap, composed: composedList${options.mode === "dev" ? ", resolveQuery" : ""} })`,
 		`  .mount(${JSON.stringify(options.mount)})`,
 		``
 	].join("\n");
@@ -1118,18 +1119,22 @@ function mechanica(options = {}) {
 		config(_config, env) {
 			if (env.command !== "build" || env.isSsrBuild) return;
 			if (process.env.MECHANICA_EDITOR_BUILD) return;
-			return { build: { rollupOptions: { output: { codeSplitting: {
-				includeDependenciesRecursively: false,
-				groups: [{
-					...supportsGroupDebugName(this.meta?.rolldownVersion) ? { debugName: "mechanica:blocks" } : {},
-					name: (id, ctx) => {
-						const own = blockChunkNames.get(slash(id.split("?")[0]));
-						if (own !== void 0) return groupName(own);
-						const g = sharedGroupOf(id, ctx, /* @__PURE__ */ new Set());
-						return g === "skip" ? null : g;
-					}
-				}]
-			} } } } };
+			const label = supportsGroupDebugName(this.meta?.rolldownVersion) ? { debugName: "mechanica:blocks" } : {};
+			return {
+				...process.env.MECHANICA_HYDRATION_DEBUG ? { define: { __VUE_PROD_HYDRATION_MISMATCH_DETAILS__: "true" } } : {},
+				build: { rollupOptions: { output: { codeSplitting: {
+					includeDependenciesRecursively: false,
+					groups: [{
+						...label,
+						name: (id, ctx) => {
+							const own = blockChunkNames.get(slash(id.split("?")[0]));
+							if (own !== void 0) return groupName(own);
+							const g = sharedGroupOf(id, ctx, /* @__PURE__ */ new Set());
+							return g === "skip" ? null : g;
+						}
+					}]
+				} } } }
+			};
 		},
 		configResolved(config) {
 			blocksDir = join(config.root, options.blocksDir ?? "src/blocks");
@@ -1196,7 +1201,8 @@ function mechanica(options = {}) {
 				userEntry,
 				mount,
 				mode: isDev || isEditorBuild ? "dev" : "client",
-				lazy: isClientBuild
+				lazy: isClientBuild,
+				hydrate: isClientBuild
 			});
 			if (id === RESOLVED_SSR_ID) return generateSsrEntry({
 				userEntry,

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/dist/types/core/page-path.d.ts

@@ -0,0 +1,13 @@
+import { type LocalesConfig, type PageMeta } from 'mechanica-shared';
+/**
+ * The address a page's state is served at: its logical `path` under the
+ * locale prefix (`/about` -> `/ru/about`) plus the pagination variant suffix
+ * (`/blog` -> `/blog/2`). This is what the browser shows in the address bar for
+ * that state, so the server-side router starts there and `<Link>` resolves the
+ * same `is-active` on both sides of hydration.
+ *
+ * The export already serves a variant under its own path (`page.path` is
+ * `/blog/2` there, while dev keeps the base `/blog`); a suffix that is
+ * already present is kept, as `usePagination().pathFor` does.
+ */
+export declare function servedPagePath(page: PageMeta | undefined, locales?: LocalesConfig | null): string;

package/dist/types/core/router.d.ts

@@ -27,6 +27,13 @@ export interface CreateRouterOptions {
      * runtime context.
      */
     applyState?: (state: State) => void;
+    /**
+     * The address the rendered page is served at (locale prefix and pagination
+     * variant included). The server has no address bar, so this seeds its
+     * current route: `<Link>` then computes the same `is-active` the client
+     * will on hydration. The client reads `window.location` instead.
+     */
+    initialPath?: string;
 }
 /**
  * Create the client-side router. On the server it is inert (no listeners, no

package/dist/types/vite/entries.d.ts

@@ -12,6 +12,15 @@ export interface ClientEntryOptions {
      * components while unused blocks stay in their own chunks, never downloaded.
      */
     lazy?: boolean;
+    /**
+     * Hydrate the server-rendered HTML (`createSSRApp`) instead of mounting
+     * into an empty container. The production client build: the export
+     * prerenders every page, and re-rendering would throw that DOM away and
+     * refetch every image at once (elements the client creates start their
+     * fetch before `loading="lazy"` applies). Dev and the editor build mount
+     * into an empty `#app`, so they keep `createApp`.
+     */
+    hydrate?: boolean;
 }
 /**
  * Generate the client entry that mounts the user's app from their

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mechanica",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "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.2",
     "@vue/compiler-sfc": "^3.5.38",
     "compact-json-schema": "^0.1.5",
     "estree-walker": "^3.0.3",