mechanica 2.0.0-alpha.5 → 2.0.0-alpha.7

package/dist/cli.js

@@ -204,6 +204,34 @@ function breadcrumbsFor(path, names) {
 	}));
 }
 /**
+* Map a baked {@link VirtualPage} to an {@link ExportPage}. The provider emits
+* one per (logical page × locale) and self-declares `locale`/`locales`, so the
+* mapping just localizes the served `path` and carries the alternates — it never
+* goes through the file-based `readTranslation`.
+*/
+function virtualToExportPage(v, config) {
+	const isDefault = !config || !v.locale || v.locale === config.default;
+	const locale = config ? v.locale ?? config.default : void 0;
+	const path = isDefault ? v.path : localePath(v.path, v.locale, config);
+	const name = typeof v.meta?.title === "string" ? v.meta.title : void 0;
+	return {
+		path,
+		logicalPath: v.path,
+		locale,
+		translations: v.locales,
+		content: v.content ?? [],
+		data: v.data ?? {},
+		name,
+		lastmod: v.lastmod,
+		page: {
+			meta: v.meta ?? {},
+			locale,
+			locales: v.locales,
+			path: v.path
+		}
+	};
+}
+/**
 * Load the pieces needed to preload per-page block chunks: the client build's
 * Vite manifest and the plugin's block map. Older builds (or builds outside
 * `mechanica build`) may not have them — links are simply skipped then.
@@ -328,6 +356,15 @@ async function exportProject(cwd, ssr, options = {}) {
 		}
 		for (const [locale, paths] of Object.entries(missing)) if (paths.length) warn(`[mechanica] locale "${locale}" is missing ${paths.length} translation(s) (rendered only in ${config.default}): ${paths.join(", ")}`);
 	}
+	if (ssr.generatedPages?.length) {
+		const taken = new Set(pages.map((page) => page.path));
+		for (const vp of ssr.generatedPages) {
+			const generated = virtualToExportPage(vp, config);
+			if (taken.has(generated.path)) throw new Error(`[mechanica] generatePages produced "${generated.path}", but a page already exists there — change the generated path or remove the conflicting page.`);
+			taken.add(generated.path);
+			pages.push(generated);
+		}
+	}
 	setPageCodec(richText);
 	const querySource = {
 		listPages: (opts) => listPages(join(cwd, ".mech"), opts),
@@ -421,6 +458,7 @@ async function exportProject(cwd, ssr, options = {}) {
 	};
 	const templateHandlesPagination = index.includes("page.pagination");
 	const pageNames = new Map(defaultPages.map((page) => [page.logicalPath, page.name ?? (page.logicalPath === "/" ? "Home" : page.logicalPath.split("/").pop())]));
+	for (const vp of ssr.generatedPages ?? []) pageNames.set(vp.path, typeof vp.meta?.title === "string" ? vp.meta.title : vp.path.split("/").pop());
 	/** hreflang alternates for a translated page (each locale + x-default), at page N. */
 	const alternatesFor = (source, pageNum = 1) => {
 		if (!config || !source.translations || source.translations.length < 2) return void 0;

package/dist/editor.js

@@ -3007,6 +3007,7 @@ var savePath = () => {
 };
 var pageVersion = state.version ?? null;
 var forceNextSave = false;
+var readOnly = state.generated === true;
 var localizedIds = new Set(dataEntries.filter((entry) => entry.localized).map((entry) => entry.id));
 /**
 * Split the editable snapshot for the wire: shared site/folder data stays in
@@ -3072,6 +3073,7 @@ async function loadState(path) {
 	pageVersion = fresh.version ?? null;
 	pagePath = fresh.page?.path ?? path;
 	pageLocale = fresh.page?.locale;
+	readOnly = fresh.generated === true;
 	externalState.value = fresh;
 	return true;
 }
@@ -3152,7 +3154,9 @@ createApp(EditorApp_default, {
 	uploadFile,
 	uploadDerived,
 	listImages,
-	onChange: (snapshot) => saveQueue.push(snapshot),
+	onChange: (snapshot) => {
+		if (!readOnly) saveQueue.push(snapshot);
+	},
 	save: saveController,
 	externalState,
 	navigation

package/dist/plugin.js

@@ -2,7 +2,7 @@ import { A as renamePage, D as pageUrlOf, E as movePage, F as translationsOf, G
 import fs, { existsSync, readFileSync, readdirSync } from "node:fs";
 import { basename, join, relative, resolve, sep } from "node:path";
 import { parseVueRequest } from "@vitejs/plugin-vue";
-import { mergeTranslation, normalizeLocales, parseLocalePath, passDataToHTML, resolveQueryKey, serializeState } from "mechanica-shared";
+import { localePath, mergeTranslation, normalizeLocales, parseLocalePath, passDataToHTML, resolveQueryKey, serializeState } from "mechanica-shared";
 import { babelParse, parse as parse$1 } from "@vue/compiler-sfc";
 import { walk } from "estree-walker";
 import MagicString from "magic-string";
@@ -10,6 +10,18 @@ import { parseComposedBlock, serializeComposedBlock } from "mechanica-shared/blo
 import { createHash } from "node:crypto";
 import { promises } from "fs";
 import path from "path";
+//#region src/vite/generate-pages.ts
+/** Run every provider's `list` once and flatten the results. */
+async function collectGeneratedPages(providers, ctx) {
+	if (!providers?.length) return [];
+	return (await Promise.all(providers.map((p) => (typeof p === "function" ? p : p.list)(ctx)))).flat();
+}
+/** The served (locale-prefixed) URL a generated page renders at. */
+function generatedServedPath(page, config) {
+	if (!config || !page.locale || page.locale === config.default) return page.path;
+	return localePath(page.path, page.locale, config);
+}
+//#endregion
 //#region src/compiler/compile-block.ts
 /**
 * The macro name authors call inside a block's `<script setup>`.
@@ -764,6 +776,7 @@ function generateSsrEntry(options) {
 		`registerComponents(blocksMap)`,
 		`export const site = ${JSON.stringify(options.site ?? {})}`,
 		`export const locales = ${JSON.stringify(options.locales ?? null)}`,
+		`export const generatedPages = ${JSON.stringify(options.generatedPages ?? [])}`,
 		`export const dataEntries = getDataEntries()`,
 		``,
 		`export async function render(state, context = {}) {`,
@@ -913,6 +926,49 @@ function buildPageState(mechDir, urlPath, config) {
 		...baseContent ? { baseContent } : {}
 	};
 }
+/**
+* The dev state for a programmatically generated page ({@link VirtualPage}) —
+* the file-free counterpart of {@link buildPageState}. It replicates the same
+* shape (content with block-prop defaults + image meta filled, the
+* site‹folder‹page data merge, and `page.locale`/`page.locales`), but reads its
+* content/data/meta from the baked page rather than a `.page.md`. `version` is
+* null and `generated` is set, so the editor treats it as read-only and never
+* queues a save against a file that doesn't exist.
+*/
+function buildGeneratedState(mechDir, vp, config) {
+	const content = vp.content ?? [];
+	fillContentDefaults(content);
+	fillImageMeta(mechDir, content);
+	const localeCode = !config || !vp.locale || vp.locale === config.default ? void 0 : vp.locale;
+	const folder = folderOf(mechDir, vp.path);
+	const siteData = readSiteData(mechDir, localeCode);
+	const folderData = readFolderData(mechDir, folder, localeCode);
+	const pageData = vp.data ?? {};
+	const pageMeta = {
+		path: vp.path,
+		meta: vp.meta ?? {}
+	};
+	if (config) {
+		pageMeta.locale = vp.locale ?? config.default;
+		pageMeta.locales = vp.locales ?? [config.default];
+	}
+	return {
+		content,
+		data: {
+			...siteData,
+			...folderData,
+			...pageData
+		},
+		siteData,
+		folderData,
+		pageData,
+		folder,
+		page: pageMeta,
+		version: null,
+		generated: true,
+		...config ? { locales: config } : {}
+	};
+}
 //#endregion
 //#region src/vite/dev/composed-store.ts
 /**
@@ -1055,6 +1111,8 @@ function createDevMiddleware(mechDir, options = {}) {
 				const pathParam = query.get("path");
 				if (!pathParam) return json({ error: "Missing path" }, 400);
 				await options.ready?.();
+				const generated = (await options.generated?.())?.byServed.get(pathParam);
+				if (generated) return json(buildGeneratedState(mechDir, generated, config));
 				return json(buildPageState(mechDir, pathParam, config));
 			}
 			if (pathname === "/pages" && req.method === "GET") return json(listPages(mechDir, config ? { locales: config } : {}));
@@ -1137,6 +1195,7 @@ function createDevMiddleware(mechDir, options = {}) {
 			if (pathname === "/save" && req.method === "POST") {
 				const pathParam = query.get("path");
 				if (!pathParam) return json({ error: "Missing path" }, 400);
+				if ((await options.generated?.())?.logical.has(pathParam)) return json({ error: "This page is generated and read-only" }, 409);
 				const locale = variantCode(query.get("locale"));
 				const body = JSON.parse((await readBody(req)).toString("utf-8"));
 				if (!body.force && typeof body.version === "string") {
@@ -1392,6 +1451,34 @@ function mechanica(options = {}) {
 	let locales = null;
 	let isClientBuild = false;
 	let lazyBlockFiles = null;
+	let generatedPagesCache = null;
+	const loadGeneratedPages = () => {
+		if (!generatedPagesCache) {
+			const ctx = {
+				root,
+				mechDir,
+				locales
+			};
+			generatedPagesCache = collectGeneratedPages(options.generatePages, ctx);
+		}
+		return generatedPagesCache;
+	};
+	let generatedIndexCache = null;
+	const loadGeneratedIndex = () => {
+		if (!generatedIndexCache) generatedIndexCache = loadGeneratedPages().then((pages) => {
+			const byServed = /* @__PURE__ */ new Map();
+			const logical = /* @__PURE__ */ new Set();
+			for (const page of pages) {
+				byServed.set(generatedServedPath(page, locales), page);
+				logical.add(page.path);
+			}
+			return {
+				byServed,
+				logical
+			};
+		});
+		return generatedIndexCache;
+	};
 	const blockSchemas = /* @__PURE__ */ new Map();
 	const blockChunkNames = /* @__PURE__ */ new Map();
 	const bundleBlocks = (options.blockChunks ?? "bundled") === "bundled";
@@ -1577,7 +1664,8 @@ function mechanica(options = {}) {
 					url: options.siteUrl,
 					name: options.siteName
 				},
-				locales
+				locales,
+				generatedPages: await loadGeneratedPages()
 			});
 			if (id === RESOLVED_PREVIEW_ID) return generatePreviewEntry({ userEntry });
 			if (id === RESOLVED_WIDGETS_ID) return collectWidgets(widgetsDir, (p) => this.resolve(p));
@@ -1611,6 +1699,7 @@ function mechanica(options = {}) {
 			server.middlewares.use("/@mechanica/composer", createComposerMiddleware());
 			server.middlewares.use("/@mechanica", createDevMiddleware(mechDir, {
 				locales,
+				generated: () => loadGeneratedIndex(),
 				ready: () => ensurePageCodec(server),
 				blocks: async () => {
 					const compiled = ((await server.ssrLoadModule("virtual:mechanica/blocks")).blocksList ?? []).map((component) => {
@@ -1700,7 +1789,8 @@ function mechanica(options = {}) {
 				if (/\.\w+$/.test(urlPath)) return html;
 				const withEditor = !url.searchParams.has("mechanica-shot");
 				if (ctx.server) await ensurePageCodec(ctx.server);
-				const state = buildPageState(mechDir, urlPath, locales);
+				const generated = (await loadGeneratedIndex()).byServed.get(urlPath);
+				const state = generated ? buildGeneratedState(mechDir, generated, locales) : buildPageState(mechDir, urlPath, locales);
 				const inject = [
 					`<script>window.state=${serializeState(state)}<\/script>`,
 					`<script type="module">`,

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

@@ -1,4 +1,4 @@
-import { type ComposedBlockDefinition, type LocalesConfig, type RenderResult } from 'mechanica-shared';
+import { type ComposedBlockDefinition, type LocalesConfig, type RenderResult, type VirtualPage } from 'mechanica-shared';
 import { type BlockComponent } from '../editor/lib/block-meta';
 /** An already-built SSR bundle (`dist/ssr.js`) exposes these. */
 export interface SsrBundle {
@@ -24,6 +24,9 @@ export interface SsrBundle {
     };
     /** The site's locale config baked in from the plugin's `locales` option. */
     locales?: LocalesConfig | null;
+    /** Programmatically generated pages (plugin `generatePages`), baked as plain
+     *  data at build so they render without a `.page.md` file. */
+    generatedPages?: VirtualPage[];
 }
 export interface ExportOptions {
     /**

package/dist/types/vite/dev/middleware.d.ts

@@ -1,5 +1,5 @@
 import type { Connect } from 'vite';
-import type { LocalesConfig } from 'mechanica-shared';
+import type { LocalesConfig, VirtualPage } from 'mechanica-shared';
 /** What `/blocks` reports per block — enough for the thumbs CLI to walk them. */
 export interface BlockListing {
     id: string;
@@ -13,6 +13,15 @@ export interface DevMiddlewareOptions {
     blocks?: () => Promise<BlockListing[]> | BlockListing[];
     /** The site's locale config (multi-language sites); null/absent = i18n off. */
     locales?: LocalesConfig | null;
+    /**
+     * Generated routes (plugin `generatePages`): a served-path → page map (for
+     * `/state`) and the set of their logical paths (for the read-only `/save`
+     * guard). Absent when no providers are configured.
+     */
+    generated?: () => Promise<{
+        byServed: Map<string, VirtualPage>;
+        logical: Set<string>;
+    }>;
 }
 /**
  * The `/@mechanica` dev middleware: page CRUD, asset upload/serve, folder list,

package/dist/types/vite/dev/page-state.d.ts

@@ -1,4 +1,4 @@
-import { type LocalesConfig, type PageMeta } from 'mechanica-shared';
+import { type LocalesConfig, type PageMeta, type VirtualPage } from 'mechanica-shared';
 /**
  * The dev state for a page: effective data resolved site < folder < page, plus
  * the scope buckets the editor edits, and the page's on-disk version for
@@ -29,3 +29,26 @@ export declare function buildPageState(mechDir: string, urlPath: string, config?
     page: PageMeta;
     version: string | null;
 };
+/**
+ * The dev state for a programmatically generated page ({@link VirtualPage}) —
+ * the file-free counterpart of {@link buildPageState}. It replicates the same
+ * shape (content with block-prop defaults + image meta filled, the
+ * site‹folder‹page data merge, and `page.locale`/`page.locales`), but reads its
+ * content/data/meta from the baked page rather than a `.page.md`. `version` is
+ * null and `generated` is set, so the editor treats it as read-only and never
+ * queues a save against a file that doesn't exist.
+ */
+export declare function buildGeneratedState(mechDir: string, vp: VirtualPage, config?: LocalesConfig | null): {
+    locales?: LocalesConfig | undefined;
+    content: import("mechanica-shared").ContentBlock[];
+    data: {
+        [x: string]: unknown;
+    };
+    siteData: Record<string, unknown>;
+    folderData: Record<string, unknown>;
+    pageData: Record<string, unknown>;
+    folder: string | null;
+    page: PageMeta;
+    version: null;
+    generated: boolean;
+};

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

@@ -61,6 +61,9 @@ export interface SsrEntryOptions {
     /** The site's locale config (multi-language) — rides the bundle so the export
      *  can walk translations, and gets baked into each page's `state.locales`. */
     locales?: import('mechanica-shared').LocalesConfig | null;
+    /** Programmatically generated pages (plugin `generatePages`), run at build and
+     *  baked as plain data so `mechanica export` renders them without a file. */
+    generatedPages?: import('mechanica-shared').VirtualPage[];
 }
 /**
  * Generate the SSR entry. Exposes the block list, data entries and a `render`

package/dist/types/vite/generate-pages.d.ts

@@ -0,0 +1,35 @@
+import { type LocalesConfig, type VirtualPage } from 'mechanica-shared';
+/**
+ * Programmatic route generation (`generatePages`).
+ *
+ * A provider turns some source — a glob of Markdown, a CMS, anything — into a
+ * list of {@link VirtualPage}s: pages with no `.page.md` file, rendered through
+ * the normal pipeline. The plugin runs `list` at build and bakes the output
+ * into the SSR bundle for the static export (see `generateSsrEntry`), and runs
+ * it at dev-server start into a route map.
+ *
+ * These are build-side types (a provider gets fs paths) — they live with the
+ * plugin options, not in the `mechanica-shared` barrel the client imports.
+ * `resolve`/`revalidate` are reserved for the future render backend (render one
+ * path on a webhook without enumerating the whole source); Phase 1 uses `list`.
+ */
+export interface PageProviderCtx {
+    /** The Vite project root (absolute). */
+    root: string;
+    /** The project's `.mech` directory (absolute). */
+    mechDir: string;
+    /** The site's locale config, or null when i18n is off. */
+    locales: LocalesConfig | null;
+}
+export type PageProvider = ((ctx: PageProviderCtx) => VirtualPage[] | Promise<VirtualPage[]>) | {
+    /** Enumerate every page (static export, sitemap, dev route map). */
+    list: (ctx: PageProviderCtx) => VirtualPage[] | Promise<VirtualPage[]>;
+    /** Reserved: render one path without enumerating — backend ISR / lazy dev. */
+    resolve?: (path: string, ctx: PageProviderCtx) => VirtualPage | null | Promise<VirtualPage | null>;
+    /** Reserved: cache/revalidation hint for the backend. */
+    revalidate?: number | ((page: VirtualPage) => number);
+};
+/** Run every provider's `list` once and flatten the results. */
+export declare function collectGeneratedPages(providers: PageProvider[] | undefined, ctx: PageProviderCtx): Promise<VirtualPage[]>;
+/** The served (locale-prefixed) URL a generated page renders at. */
+export declare function generatedServedPath(page: VirtualPage, config: LocalesConfig | null): string;

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

@@ -1,4 +1,5 @@
 export { mechanica, BLOCKS_MODULE_ID, CLIENT_MODULE_ID, WIDGETS_MODULE_ID, type MechanicaPluginOptions, } from './plugin';
+export { type PageProvider, type PageProviderCtx } from './generate-pages';
 export { default as svgGlob } from '../svg-plugin';
 export { collectBlocks } from './collect-blocks';
 export { collectWidgets } from './collect-widgets';

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

@@ -1,4 +1,5 @@
 import type { Plugin } from 'vite';
+import { type PageProvider } from './generate-pages';
 /** Virtual module exposing the collected block components. */
 export declare const BLOCKS_MODULE_ID = "virtual:mechanica/blocks";
 /** Virtual module that mounts the user's app (generated client entry). */
@@ -58,6 +59,14 @@ export interface MechanicaPluginOptions {
      * locale) = i18n off — nothing changes for existing sites.
      */
     locales?: import('mechanica-shared').LocalesOption;
+    /**
+     * Programmatic route generation. Each provider returns a list of pages built
+     * from any source (a content glob, a CMS, …) — rendered through the normal
+     * pipeline with no `.page.md` file per route. Providers run at build (their
+     * output is baked into the static export) and at dev-server start; generated
+     * pages are read-only. See GENERATED-PAGES.md.
+     */
+    generatePages?: PageProvider[];
     /**
      * How the production client build chunks block code.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mechanica",
-  "version": "2.0.0-alpha.5",
+  "version": "2.0.0-alpha.7",
   "description": "Build Vue 3 websites with a visual block editor",
   "license": "MIT",
   "repository": {
@@ -63,7 +63,7 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "mechanica-shared": "workspace:*",
+    "mechanica-shared": "2.0.0-alpha.4",
     "@vue/compiler-sfc": "^3.5.38",
     "compact-json-schema": "^0.1.5",
     "estree-walker": "^3.0.3",

package/src/cli/export.ts

@@ -25,6 +25,7 @@ import {
   type QuerySource,
   type RenderResult,
   type SitemapEntry,
+  type VirtualPage,
 } from 'mechanica-shared'
 import { parsePage, type RichTextCodec } from 'mechanica-shared/page-format'
 import { toBlockMeta, composedBlockMeta, type BlockComponent } from '../editor/lib/block-meta'
@@ -228,6 +229,34 @@ export interface SsrBundle {
   site?: { url?: string; name?: string }
   /** The site's locale config baked in from the plugin's `locales` option. */
   locales?: LocalesConfig | null
+  /** Programmatically generated pages (plugin `generatePages`), baked as plain
+   *  data at build so they render without a `.page.md` file. */
+  generatedPages?: VirtualPage[]
+}
+
+/**
+ * Map a baked {@link VirtualPage} to an {@link ExportPage}. The provider emits
+ * one per (logical page × locale) and self-declares `locale`/`locales`, so the
+ * mapping just localizes the served `path` and carries the alternates — it never
+ * goes through the file-based `readTranslation`.
+ */
+function virtualToExportPage(v: VirtualPage, config: LocalesConfig | null): ExportPage {
+  const isDefault = !config || !v.locale || v.locale === config.default
+  const locale = config ? (v.locale ?? config.default) : undefined
+  const path = isDefault ? v.path : localePath(v.path, v.locale!, config!)
+  const name = typeof v.meta?.title === 'string' ? v.meta.title : undefined
+  return {
+    path,
+    logicalPath: v.path,
+    locale,
+    translations: v.locales,
+    content: v.content ?? [],
+    data: v.data ?? {},
+    name,
+    lastmod: v.lastmod,
+    // `state.page.path` stays the logical path so `<Link>` prefixes it per locale.
+    page: { meta: v.meta ?? {}, locale, locales: v.locales, path: v.path },
+  }
 }
 
 export interface ExportOptions {
@@ -421,6 +450,24 @@ export async function exportProject(
     }
   }
 
+  // Programmatically generated routes (plugin `generatePages`), baked into the
+  // SSR bundle as plain data. They self-declare locale/translations, so they
+  // join after the file-based i18n pass — never through `readTranslation`.
+  if (ssr.generatedPages?.length) {
+    const taken = new Set(pages.map((page) => page.path))
+    for (const vp of ssr.generatedPages) {
+      const generated = virtualToExportPage(vp, config)
+      if (taken.has(generated.path)) {
+        throw new Error(
+          `[mechanica] generatePages produced "${generated.path}", but a page already exists ` +
+            `there — change the generated path or remove the conflicting page.`,
+        )
+      }
+      taken.add(generated.path)
+      pages.push(generated)
+    }
+  }
+
   // Queries (`usePages`/`usePagination`/`useFetch`) resolve at build time
   // against the same `.mech` store, memoized per (page-number, key) across the
   // whole export — a nav query shared by 100 pages resolves once. The codec is
@@ -554,6 +601,12 @@ export async function exportProject(
       page.name ?? (page.logicalPath === '/' ? 'Home' : page.logicalPath.split('/').pop()!),
     ]),
   )
+  // Generated pages contribute their own crumb (and any generated ancestor like
+  // `/docs/api`) so the BreadcrumbList JSON-LD includes the full trail; keyed by
+  // logical path, so the per-locale variants collapse to one entry.
+  for (const vp of ssr.generatedPages ?? []) {
+    pageNames.set(vp.path, typeof vp.meta?.title === 'string' ? vp.meta.title : vp.path.split('/').pop()!)
+  }
 
   /** hreflang alternates for a translated page (each locale + x-default), at page N. */
   const alternatesFor = (source: ExportPage, pageNum = 1): { hreflang: string; path: string }[] | undefined => {

package/src/editor/editor.ts

@@ -45,6 +45,9 @@ const savePath = () => {
 // editor never silently clobbers e.g. Claude's edits to the .page.md.
 let pageVersion: string | null = (state as { version?: string | null }).version ?? null
 let forceNextSave = false
+// A programmatically generated page (plugin `generatePages`) has no file — the
+// editor renders it but never queues a save (the dev server would reject it).
+let readOnly = state.generated === true
 
 // `localized` data entries: their site/folder value is translated per locale, so
 // the save payload routes them to separate buckets the dev server writes to the
@@ -125,6 +128,7 @@ async function loadState(path: string): Promise<boolean> {
   pageVersion = fresh.version ?? null
   pagePath = fresh.page?.path ?? path
   pageLocale = fresh.page?.locale
+  readOnly = fresh.generated === true
   externalState.value = fresh
   return true
 }
@@ -234,7 +238,9 @@ createApp(EditorApp, {
   uploadFile,
   uploadDerived,
   listImages,
-  onChange: (snapshot: EditorSnapshot) => saveQueue.push(snapshot),
+  onChange: (snapshot: EditorSnapshot) => {
+    if (!readOnly) saveQueue.push(snapshot)
+  },
   save: saveController,
   externalState,
   navigation,

package/src/vite/dev/middleware.ts

@@ -16,7 +16,7 @@ import {
   deleteTranslation,
   PageExistsError,
 } from './pages-store'
-import type { LocalesConfig } from 'mechanica-shared'
+import type { LocalesConfig, VirtualPage } from 'mechanica-shared'
 import { saveUpload, saveDerivedAsset, listImages } from './assets-store'
 import { resolveDevQuery } from './query-dev'
 import {
@@ -26,7 +26,7 @@ import {
   mergeLocaleFolderData,
   folderOf,
 } from './data-store'
-import { buildPageState } from './page-state'
+import { buildPageState, buildGeneratedState } from './page-state'
 import {
   listComposedBlocks,
   readComposedBlock,
@@ -52,6 +52,12 @@ export interface DevMiddlewareOptions {
   blocks?: () => Promise<BlockListing[]> | BlockListing[]
   /** The site's locale config (multi-language sites); null/absent = i18n off. */
   locales?: LocalesConfig | null
+  /**
+   * Generated routes (plugin `generatePages`): a served-path → page map (for
+   * `/state`) and the set of their logical paths (for the read-only `/save`
+   * guard). Absent when no providers are configured.
+   */
+  generated?: () => Promise<{ byServed: Map<string, VirtualPage>; logical: Set<string> }>
 }
 
 /**
@@ -138,6 +144,8 @@ export function createDevMiddleware(
         const pathParam = query.get('path')
         if (!pathParam) return json({ error: 'Missing path' }, 400)
         await options.ready?.()
+        const generated = (await options.generated?.())?.byServed.get(pathParam)
+        if (generated) return json(buildGeneratedState(mechDir, generated, config))
         return json(buildPageState(mechDir, pathParam, config))
       }
 
@@ -238,6 +246,11 @@ export function createDevMiddleware(
       if (pathname === '/save' && req.method === 'POST') {
         const pathParam = query.get('path')
         if (!pathParam) return json({ error: 'Missing path' }, 400)
+        // Generated pages (plugin `generatePages`) have no file — reject a save
+        // rather than writing a stray `.page.md` at their path.
+        if ((await options.generated?.())?.logical.has(pathParam)) {
+          return json({ error: 'This page is generated and read-only' }, 409)
+        }
         // A non-default `locale` writes to that translation's variant file; the
         // default locale (or i18n off) writes the base page.
         const locale = variantCode(query.get('locale'))

package/src/vite/dev/page-state.ts

@@ -1,4 +1,4 @@
-import { parseLocalePath, mergeTranslation, type LocalesConfig, type PageMeta } from 'mechanica-shared'
+import { parseLocalePath, mergeTranslation, type LocalesConfig, type PageMeta, type VirtualPage } from 'mechanica-shared'
 import {
   readPage,
   pageVersion,
@@ -126,3 +126,42 @@ export function buildPageState(
     ...(baseContent ? { baseContent } : {}),
   }
 }
+
+/**
+ * The dev state for a programmatically generated page ({@link VirtualPage}) —
+ * the file-free counterpart of {@link buildPageState}. It replicates the same
+ * shape (content with block-prop defaults + image meta filled, the
+ * site‹folder‹page data merge, and `page.locale`/`page.locales`), but reads its
+ * content/data/meta from the baked page rather than a `.page.md`. `version` is
+ * null and `generated` is set, so the editor treats it as read-only and never
+ * queues a save against a file that doesn't exist.
+ */
+export function buildGeneratedState(mechDir: string, vp: VirtualPage, config?: LocalesConfig | null) {
+  const content = vp.content ?? []
+  fillContentDefaults(content)
+  fillImageMeta(mechDir, content)
+
+  const isDefaultLocale = !config || !vp.locale || vp.locale === config.default
+  const localeCode = isDefaultLocale ? undefined : vp.locale
+  const folder = folderOf(mechDir, vp.path)
+  const siteData = readSiteData(mechDir, localeCode)
+  const folderData = readFolderData(mechDir, folder, localeCode)
+  const pageData = vp.data ?? {}
+  const pageMeta: PageMeta = { path: vp.path, meta: vp.meta ?? {} }
+  if (config) {
+    pageMeta.locale = vp.locale ?? config.default
+    pageMeta.locales = vp.locales ?? [config.default]
+  }
+  return {
+    content,
+    data: { ...siteData, ...folderData, ...pageData },
+    siteData,
+    folderData,
+    pageData,
+    folder,
+    page: pageMeta,
+    version: null,
+    generated: true,
+    ...(config ? { locales: config } : {}),
+  }
+}

package/src/vite/entries.ts

@@ -153,6 +153,9 @@ export interface SsrEntryOptions {
   /** The site's locale config (multi-language) — rides the bundle so the export
    *  can walk translations, and gets baked into each page's `state.locales`. */
   locales?: import('mechanica-shared').LocalesConfig | null
+  /** Programmatically generated pages (plugin `generatePages`), run at build and
+   *  baked as plain data so `mechanica export` renders them without a file. */
+  generatedPages?: import('mechanica-shared').VirtualPage[]
 }
 
 /**
@@ -176,6 +179,7 @@ export function generateSsrEntry(options: SsrEntryOptions): string {
     `registerComponents(blocksMap)`,
     `export const site = ${JSON.stringify(options.site ?? {})}`,
     `export const locales = ${JSON.stringify(options.locales ?? null)}`,
+    `export const generatedPages = ${JSON.stringify(options.generatedPages ?? [])}`,
     `export const dataEntries = getDataEntries()`,
     ``,
     `export async function render(state, context = {}) {`,

package/src/vite/generate-pages.ts

@@ -0,0 +1,51 @@
+import { localePath, type LocalesConfig, type VirtualPage } from 'mechanica-shared'
+
+/**
+ * Programmatic route generation (`generatePages`).
+ *
+ * A provider turns some source — a glob of Markdown, a CMS, anything — into a
+ * list of {@link VirtualPage}s: pages with no `.page.md` file, rendered through
+ * the normal pipeline. The plugin runs `list` at build and bakes the output
+ * into the SSR bundle for the static export (see `generateSsrEntry`), and runs
+ * it at dev-server start into a route map.
+ *
+ * These are build-side types (a provider gets fs paths) — they live with the
+ * plugin options, not in the `mechanica-shared` barrel the client imports.
+ * `resolve`/`revalidate` are reserved for the future render backend (render one
+ * path on a webhook without enumerating the whole source); Phase 1 uses `list`.
+ */
+export interface PageProviderCtx {
+  /** The Vite project root (absolute). */
+  root: string
+  /** The project's `.mech` directory (absolute). */
+  mechDir: string
+  /** The site's locale config, or null when i18n is off. */
+  locales: LocalesConfig | null
+}
+
+export type PageProvider =
+  | ((ctx: PageProviderCtx) => VirtualPage[] | Promise<VirtualPage[]>)
+  | {
+      /** Enumerate every page (static export, sitemap, dev route map). */
+      list: (ctx: PageProviderCtx) => VirtualPage[] | Promise<VirtualPage[]>
+      /** Reserved: render one path without enumerating — backend ISR / lazy dev. */
+      resolve?: (path: string, ctx: PageProviderCtx) => VirtualPage | null | Promise<VirtualPage | null>
+      /** Reserved: cache/revalidation hint for the backend. */
+      revalidate?: number | ((page: VirtualPage) => number)
+    }
+
+/** Run every provider's `list` once and flatten the results. */
+export async function collectGeneratedPages(
+  providers: PageProvider[] | undefined,
+  ctx: PageProviderCtx,
+): Promise<VirtualPage[]> {
+  if (!providers?.length) return []
+  const lists = await Promise.all(providers.map((p) => (typeof p === 'function' ? p : p.list)(ctx)))
+  return lists.flat()
+}
+
+/** The served (locale-prefixed) URL a generated page renders at. */
+export function generatedServedPath(page: VirtualPage, config: LocalesConfig | null): string {
+  if (!config || !page.locale || page.locale === config.default) return page.path
+  return localePath(page.path, page.locale, config)
+}

package/src/vite/index.ts

@@ -5,6 +5,7 @@ export {
   WIDGETS_MODULE_ID,
   type MechanicaPluginOptions,
 } from './plugin'
+export { type PageProvider, type PageProviderCtx } from './generate-pages'
 export { default as svgGlob } from '../svg-plugin'
 export { collectBlocks } from './collect-blocks'
 export { collectWidgets } from './collect-widgets'

package/src/vite/plugin.ts

@@ -2,7 +2,13 @@ import { existsSync, readFileSync } from 'node:fs'
 import { join, relative } from 'node:path'
 import type { Plugin } from 'vite'
 import { parseVueRequest } from '@vitejs/plugin-vue'
-import { passDataToHTML, serializeState, normalizeLocales, type LocalesConfig } from 'mechanica-shared'
+import { passDataToHTML, serializeState, normalizeLocales, type LocalesConfig, type VirtualPage } from 'mechanica-shared'
+import {
+  collectGeneratedPages,
+  generatedServedPath,
+  type PageProvider,
+  type PageProviderCtx,
+} from './generate-pages'
 import { compileBlock } from '../compiler/compile-block'
 import { emitElementsCss } from '../elements/emit-css'
 import { parseComposerBreakpoints } from './read-breakpoints'
@@ -21,7 +27,7 @@ import { createPreviewMiddleware } from './dev/preview'
 import { createComposerMiddleware } from './dev/composer'
 import { setPageCodec, setPageBlocks, pageUrlOf } from './dev/pages-store'
 import { toBlockMeta, composedBlockMeta } from '../editor/lib/block-meta'
-import { buildPageState } from './dev/page-state'
+import { buildPageState, buildGeneratedState } from './dev/page-state'
 import { wasRecentlyMutated } from './dev/fs-utils'
 import { buildRichTextCodec } from './rich-text-codec'
 import { BLOCKS_MANIFEST_FILE } from '../cli/page-assets'
@@ -95,6 +101,14 @@ export interface MechanicaPluginOptions {
    * locale) = i18n off — nothing changes for existing sites.
    */
   locales?: import('mechanica-shared').LocalesOption
+  /**
+   * Programmatic route generation. Each provider returns a list of pages built
+   * from any source (a content glob, a CMS, …) — rendered through the normal
+   * pipeline with no `.page.md` file per route. Providers run at build (their
+   * output is baked into the static export) and at dev-server start; generated
+   * pages are read-only. See GENERATED-PAGES.md.
+   */
+  generatePages?: PageProvider[]
   /**
    * How the production client build chunks block code.
    *
@@ -139,6 +153,34 @@ export function mechanica(options: MechanicaPluginOptions = {}): Plugin {
   // emitted as `mechanica-blocks.json` for `mechanica export`.
   let lazyBlockFiles: Map<string, string> | null = null
 
+  // Generated pages (`generatePages`): run each provider's `list` once, cached.
+  // The output is baked into the SSR bundle for export; in dev a served-path →
+  // page map resolves navigations and a logical-path set backs the read-only
+  // save guard.
+  let generatedPagesCache: Promise<VirtualPage[]> | null = null
+  const loadGeneratedPages = (): Promise<VirtualPage[]> => {
+    if (!generatedPagesCache) {
+      const ctx: PageProviderCtx = { root, mechDir, locales }
+      generatedPagesCache = collectGeneratedPages(options.generatePages, ctx)
+    }
+    return generatedPagesCache
+  }
+  let generatedIndexCache: Promise<{ byServed: Map<string, VirtualPage>; logical: Set<string> }> | null = null
+  const loadGeneratedIndex = (): Promise<{ byServed: Map<string, VirtualPage>; logical: Set<string> }> => {
+    if (!generatedIndexCache) {
+      generatedIndexCache = loadGeneratedPages().then((pages) => {
+        const byServed = new Map<string, VirtualPage>()
+        const logical = new Set<string>()
+        for (const page of pages) {
+          byServed.set(generatedServedPath(page, locales), page)
+          logical.add(page.path)
+        }
+        return { byServed, logical }
+      })
+    }
+    return generatedIndexCache
+  }
+
   // Last compiled `blockSchema` literal per block file (normalized path), so a
   // hot update can tell schema edits (need a re-collect + reload so the editor
   // sees fresh metadata) from template/style edits (normal HMR).
@@ -419,6 +461,7 @@ export function mechanica(options: MechanicaPluginOptions = {}): Plugin {
           userEntry,
           site: { url: options.siteUrl, name: options.siteName },
           locales,
+          generatedPages: await loadGeneratedPages(),
         })
       }
       if (id === RESOLVED_PREVIEW_ID) {
@@ -479,6 +522,9 @@ export function mechanica(options: MechanicaPluginOptions = {}): Plugin {
         '/@mechanica',
         createDevMiddleware(mechDir, {
           locales,
+          // Resolve generated routes for `/state` and guard them read-only on
+          // `/save` — they have no file to write.
+          generated: () => loadGeneratedIndex(),
           ready: () => ensurePageCodec(server),
           // Block listing for `mechanica thumbs --blocks` — loaded fresh so a
           // re-collected blocks module (HMR add/remove) is reflected. Composed
@@ -598,10 +644,16 @@ export function mechanica(options: MechanicaPluginOptions = {}): Plugin {
 
         // Ensure richText fields hydrate as Block[] (not raw Markdown).
         if (ctx.server) await ensurePageCodec(ctx.server)
+        // A programmatically generated route (plugin `generatePages`) has no
+        // page file — synthesize its state from the baked page instead. Falls
+        // through to the file-based resolver for authored pages.
+        const generated = (await loadGeneratedIndex()).byServed.get(urlPath)
         // Site < folder < page resolution plus the editor's scope buckets and
         // the page's on-disk version (for optimistic-concurrency saves). A
         // locale-prefixed URL (`/ru/about`) resolves to that translation.
-        const state = buildPageState(mechDir, urlPath, locales)
+        const state = generated
+          ? buildGeneratedState(mechDir, generated, locales)
+          : buildPageState(mechDir, urlPath, locales)
         const inject = [
           `<script>window.state=${serializeState(state)}</script>`,
           `<script type="module">`,