mechanica 2.2.1 → 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

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