mechanica 2.0.2 → 2.0.3

package/dist/export.js

@@ -0,0 +1,580 @@
+import { B as readImageManifest, C as getPagePath, I as UPLOADS_PREFIX, J as hasSharp, L as assetFileOf, N as setPageCodec, R as isDerivedAsset, T as listPages, U as updateImageManifest, a as toBlockMeta, d as readFolderData, f as readFoldersData, i as composedBlockMeta, m as readSiteLocaleOverride, n as blockAssetLinks, p as readSiteData, q as analyzeImageBuffer, r as buildRichTextCodec, t as BLOCKS_MANIFEST_FILE } from "./chunks/page-assets-CM_MCuoa.js";
+import { dirname, join, parse, relative, resolve } from "node:path";
+import { applySeoTags, auditPageHtml, buildRobotsTxt, buildSitemap, findUnknownBlocks, generateProject, isPaginatedQuery, localePath, mergeTranslation, migrateContent, paginationVariantPath, registerFieldSchemas, resolveQueryKey, templateBlockIds, validateLinks, walkSchema, walkTree } from "mechanica-shared";
+import { parsePage } from "mechanica-shared/page-format";
+import { access, copyFile, cp, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+//#region src/cli/export.ts
+/** A page filename stem ending in `@<locale>` is a translation, handled per-locale. */
+var VARIANT_STEM_RE = /@[A-Za-z][A-Za-z0-9_-]*$/;
+/** Set `<html lang>` unless the template already declares one (author wins). */
+function setHtmlLang(html, lang) {
+	if (/<html\b[^>]*\blang\s*=/i.test(html)) return html;
+	return html.replace(/<html\b([^>]*)>/i, `<html$1 lang="${lang}">`);
+}
+/** Read every page JSON under `<mech>/pages` as an exportable page. */
+async function readPages(pagesDir, foldersData = {}, richText) {
+	let entries;
+	try {
+		entries = await readdir(pagesDir, { recursive: true });
+	} catch {
+		return [];
+	}
+	const EXT = ".page.md";
+	const pages = [];
+	for (const relative of entries) {
+		if (!relative.endsWith(EXT)) continue;
+		const parsed = parse(relative);
+		const dir = parsed.dir.replace(/\\/g, "/");
+		const base = parsed.base.slice(0, -8);
+		if (VARIANT_STEM_RE.test(base)) continue;
+		const filePath = join(pagesDir, relative);
+		const file = parsePage(await readFile(filePath, "utf-8"), richText ? { richText } : void 0);
+		if (file.draft) continue;
+		const path = `/${dir}/${base === "index" ? "" : base}`.replace("//", "/").replace(/\/$/, "") || "/";
+		const data = {
+			...dir ? foldersData[dir] : void 0,
+			...file.data ?? {}
+		};
+		const lastmod = typeof file.meta?.lastmod === "string" ? file.meta.lastmod : await stat(filePath).then((s) => s.mtime.toISOString().slice(0, 10)).catch(() => void 0);
+		const meta = path === "/404" ? {
+			noindex: true,
+			...file.meta
+		} : file.meta;
+		pages.push({
+			path,
+			logicalPath: path,
+			content: file.content ?? [],
+			data,
+			name: file.name,
+			lastmod,
+			page: {
+				meta,
+				...file.layout ? { layout: file.layout } : {}
+			}
+		});
+	}
+	return pages;
+}
+/**
+* Read a page's translation for `locale`, returning an {@link ExportPage} at the
+* locale-prefixed path — or `null` when the translation file is missing or is a
+* per-locale draft. Content/data come from the variant file; folder-scoped data
+* merges the same as the base page.
+*/
+async function readTranslation(mechDir, base, locale, config, richText) {
+	const file = getPagePath(mechDir, base.logicalPath, locale);
+	let raw;
+	try {
+		raw = await readFile(file, "utf-8");
+	} catch {
+		return null;
+	}
+	const doc = parsePage(raw, richText ? { richText } : void 0);
+	if (doc.draft) return null;
+	const rel = relative(join(mechDir, "pages"), file).replace(/\\/g, "/");
+	const dir = dirname(rel) === "." ? "" : dirname(rel);
+	let content = doc.content ?? [];
+	let pageData = doc.data ?? {};
+	let pageMeta = doc.meta;
+	try {
+		const baseDoc = parsePage(await readFile(getPagePath(mechDir, base.logicalPath), "utf-8"), richText ? { richText } : void 0);
+		const merged = mergeTranslation({
+			content: baseDoc.content ?? [],
+			data: baseDoc.data ?? {},
+			meta: baseDoc.meta ?? {}
+		}, {
+			content: doc.content ?? [],
+			data: doc.data ?? {},
+			meta: doc.meta ?? {}
+		});
+		content = merged.content;
+		pageData = merged.data;
+		pageMeta = merged.meta;
+	} catch {}
+	const folderData = readFolderData(mechDir, dir || null, locale);
+	const data = {
+		...readSiteLocaleOverride(mechDir, locale),
+		...folderData,
+		...pageData
+	};
+	const lastmod = typeof doc.meta?.lastmod === "string" ? doc.meta.lastmod : await stat(file).then((s) => s.mtime.toISOString().slice(0, 10)).catch(() => void 0);
+	const meta = base.logicalPath === "/404" ? {
+		noindex: true,
+		...pageMeta
+	} : pageMeta;
+	return {
+		path: localePath(base.logicalPath, locale, config),
+		logicalPath: base.logicalPath,
+		locale,
+		content,
+		data,
+		name: doc.name ?? base.name,
+		lastmod,
+		page: {
+			meta,
+			locale,
+			path: base.logicalPath,
+			...base.page?.layout ? { layout: base.page.layout } : {}
+		}
+	};
+}
+/**
+* The breadcrumb trail for a path — every ancestor (root first, the page last)
+* that actually exists as a page, named by its editor label. Feeds the auto
+* BreadcrumbList JSON-LD.
+*/
+function breadcrumbsFor(path, names) {
+	if (path === "/") return [];
+	const trail = ["/"];
+	let current = "";
+	for (const segment of path.slice(1).split("/")) {
+		current += `/${segment}`;
+		trail.push(current);
+	}
+	return trail.filter((p) => names.has(p)).map((p) => ({
+		name: names.get(p),
+		path: p
+	}));
+}
+/**
+* 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,
+			...v.layout ? { layout: v.layout } : {}
+		}
+	};
+}
+/**
+* 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.
+*/
+async function readBlockAssets(cwd) {
+	try {
+		const [manifest, blockFiles] = await Promise.all([readFile(join(cwd, "dist/.vite/manifest.json"), "utf-8").then(JSON.parse), readFile(join(cwd, "dist", BLOCKS_MANIFEST_FILE), "utf-8").then(JSON.parse)]);
+		return {
+			manifest,
+			blockFiles
+		};
+	} catch {
+		return null;
+	}
+}
+/** Where uploaded assets land in the static export. */
+var MEDIA_DIR = "media";
+/**
+* Rewrite the uploaded-asset URLs a composed-block template carries — a
+* `mech:image` node's `src`, any node's `bgImage` fill — through `onFile`, in
+* the base data and every `$bp` layer. Page data goes through `collectFiles`
+* (schema-driven); templates live in the block definition, so they need their
+* own pass. Mutates the defs in place: they are the same objects the SSR
+* runtime's registered components render from.
+*/
+function rewriteComposedAssets(defs, onFile) {
+	const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+	const rewriteLayer = (blockId, layer) => {
+		if (blockId === "mech:image" && typeof layer.src === "string") layer.src = onFile(layer.src);
+		const bg = layer.bgImage;
+		if (isRecord(bg)) {
+			if (typeof bg.src === "string") bg.src = onFile(bg.src);
+			if (typeof bg.croppedSrc === "string") bg.croppedSrc = onFile(bg.croppedSrc);
+		}
+	};
+	for (const def of defs) walkTree(def.template ?? [], (node) => {
+		if (!node.data) return;
+		rewriteLayer(node.blockId, node.data);
+		const bp = node.data.$bp;
+		if (isRecord(bp)) {
+			for (const layer of Object.values(bp)) if (isRecord(layer)) rewriteLayer(node.blockId, layer);
+		}
+	});
+}
+/** Fill a value's missing preview/dimensions from a manifest entry. */
+function fillImageValue(value, entry) {
+	if (entry.previewSrc && (!value.previewSrc || value.previewSrc === value.src)) value.previewSrc = entry.previewSrc;
+	if (entry.width && !value.width) value.width = entry.width;
+	if (entry.height && !value.height) value.height = entry.height;
+}
+/**
+* Fill missing image metadata — LQIP `previewSrc` + intrinsic dimensions —
+* into the state being exported (page files are never touched). Sources, in
+* order: the `.mech/images.json` manifest (written by uploads, editor saves
+* and `mechanica images`), then the optional `sharp` dependency for anything
+* still missing — those computed entries are cached back into the manifest.
+* Without sharp, leftover gaps get a one-time hint.
+*/
+async function backfillImageMeta(pages, blocksMap, mechDir, warn) {
+	const manifest = readImageManifest(mechDir);
+	const incomplete = /* @__PURE__ */ new Map();
+	for (const page of pages) walkTree(page.content, (block) => {
+		const meta = blocksMap.get(block.blockId);
+		if (!meta) return;
+		walkSchema(block.data, meta.props, (value, schema) => {
+			if (schema.format !== "image") return;
+			const file = assetFileOf(value?.src);
+			if (!file) return;
+			const entry = manifest[file];
+			if (entry) fillImageValue(value, entry);
+			if (!value.previewSrc || value.previewSrc === value.src || !value.width || !value.height) incomplete.set(file, [...incomplete.get(file) ?? [], value]);
+		});
+	});
+	if (!incomplete.size) return;
+	if (!await hasSharp()) {
+		warn(`[mechanica] ${incomplete.size} image(s) lack a preview or dimensions — install the optional "sharp" dependency or run \`mechanica images\` to generate them`);
+		return;
+	}
+	const computed = {};
+	for (const [file, values] of incomplete) {
+		const buffer = await readFile(join(mechDir, "assets", file)).catch(() => null);
+		const info = buffer ? await analyzeImageBuffer(buffer) : null;
+		if (!info) continue;
+		computed[file] = info;
+		for (const value of values) fillImageValue(value, info);
+	}
+	try {
+		updateImageManifest(mechDir, computed);
+	} catch {}
+}
+/**
+* Statically render every page of an already-built project into `export/`,
+* returning the generated page paths. This is the post-build core of
+* {@link runExport}, isolated so it can be tested without a Vite build: it
+* expects `<cwd>/dist` (index.html, assets, the loaded `ssr` bundle) and that
+* field schemas have been registered; it reads pages + scoped data from
+* `<cwd>/.mech`.
+*
+* Beyond the pages it also: rewrites + copies uploaded assets
+* (`/@mechanica/assets/…` → `/media/…`, or `<assetsUrl>/media/…` when a CDN
+* base is set), warns about dead internal links,
+* orphaned uploads and page-level SEO issues, emits `404.html` when a `/404`
+* page exists, and — when a site url is known (plugin `siteUrl` option or
+* `--site-url`) — injects the automatic SEO tags (canonical, `og:url`,
+* absolute social-image URLs, pagination prev/next, JSON-LD) and emits
+* `sitemap.xml` + `robots.txt`.
+*/
+async function exportProject(cwd, ssr, options = {}) {
+	const warn = options.onWarn ?? ((message) => console.warn(message));
+	const index = await readFile(join(cwd, "dist/index.html"), "utf-8");
+	const siteUrl = options.siteUrl ?? ssr.site?.url;
+	const siteName = options.siteName ?? ssr.site?.name;
+	const assetsBase = (options.assetsUrl ?? ssr.assetsUrl ?? "").replace(/\/+$/, "");
+	const composedDefs = ssr.composedList ?? [];
+	const blocks = [...ssr.blocksList.map(toBlockMeta), ...composedDefs.map(composedBlockMeta)];
+	const blocksMap = new Map(blocks.map((block) => [block.id, block]));
+	const composedMap = new Map(composedDefs.map((def) => [def.id, def]));
+	const richText = buildRichTextCodec(ssr.blocksList);
+	const foldersData = readFoldersData(join(cwd, ".mech"));
+	const defaultPages = await readPages(join(cwd, ".mech/pages"), foldersData, richText);
+	const projectData = readSiteData(join(cwd, ".mech"));
+	const config = ssr.locales ?? null;
+	const mechDir = join(cwd, ".mech");
+	const pages = [...defaultPages];
+	if (config) {
+		const missing = {};
+		for (const base of defaultPages) {
+			const present = [config.default];
+			for (const locale of config.all) {
+				if (locale === config.default) continue;
+				const translation = await readTranslation(mechDir, base, locale, config, richText);
+				if (translation) {
+					present.push(locale);
+					pages.push(translation);
+				} else if (!base.page?.meta?.noindex) (missing[locale] ??= []).push(base.logicalPath);
+			}
+			base.translations = present;
+			if (base.page) base.locale = config.default;
+			base.page = {
+				...base.page,
+				locale: config.default,
+				locales: present
+			};
+		}
+		const translationsByLogical = new Map(defaultPages.map((p) => [p.logicalPath, p.translations]));
+		for (const page of pages) if (page.locale && page.locale !== config.default) {
+			const present = translationsByLogical.get(page.logicalPath);
+			page.translations = present;
+			page.page = {
+				...page.page,
+				locales: present
+			};
+		}
+		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,
+			generated: ssr.generatedPages
+		}),
+		fetchJson: options.fetchJson ?? (async ({ url, ...init }) => {
+			const res = await fetch(url, init);
+			if (!res.ok) throw new Error(`${url} responded ${res.status}`);
+			return res.json();
+		})
+	};
+	const queryCache = /* @__PURE__ */ new Map();
+	const resolveForPage = (pageNumber, pageLocale) => (key) => {
+		const locale = config && pageLocale && pageLocale !== config.default ? pageLocale : void 0;
+		const cacheKey = `${pageNumber} ${locale ?? ""} ${key}`;
+		let hit = queryCache.get(cacheKey);
+		if (!hit) {
+			hit = resolveQueryKey(querySource, key, {
+				page: pageNumber,
+				locale
+			});
+			queryCache.set(cacheKey, hit);
+		}
+		return hit;
+	};
+	for (const page of pages) {
+		migrateContent(page.content, blocksMap);
+		for (const id of findUnknownBlocks(page.content, blocksMap)) warn(`[mechanica] Page ${page.path} references unknown block "${id}" — it renders as nothing`);
+	}
+	if (ssr.layoutNames) {
+		const layoutNames = ssr.layoutNames;
+		const seen = /* @__PURE__ */ new Set();
+		for (const page of pages) {
+			const layout = page.page?.layout;
+			if (!layout || layoutNames.includes(layout) || seen.has(page.logicalPath)) continue;
+			seen.add(page.logicalPath);
+			warn(layoutNames.length === 0 ? `[mechanica] Page ${page.logicalPath} sets layout "${layout}", but the app declares no layouts (defineMechanicaApp({ layouts }))` : `[mechanica] Page ${page.logicalPath} uses unknown layout "${layout}" — it falls back to "${layoutNames[0]}" (declared: ${layoutNames.join(", ")})`);
+		}
+	}
+	if (!pages.some((page) => page.logicalPath === "/404")) warn("[mechanica] No /404 page — the static host will show its own error page. Create a page at /404 (it exports as 404.html and is noindexed automatically).");
+	for (const issue of validateLinks(pages, blocksMap)) warn(`[mechanica] Broken link on ${issue.page}: ${issue.url} has no matching page`);
+	await backfillImageMeta(pages, blocksMap, join(cwd, ".mech"), warn);
+	const exportDir = resolve(cwd, options.outDir ?? "export");
+	await mkdir(exportDir, { recursive: true });
+	for (const entry of await readdir(exportDir)) await rm(join(exportDir, entry), {
+		recursive: true,
+		force: true
+	});
+	const DIST_PRIVATE = /* @__PURE__ */ new Set([
+		"index.html",
+		"ssr.js",
+		"ssr.js.map",
+		".vite",
+		BLOCKS_MANIFEST_FILE
+	]);
+	const distEntries = await readdir(join(cwd, "dist")).catch(() => []);
+	for (const entry of distEntries) {
+		if (DIST_PRIVATE.has(entry)) continue;
+		await cp(join(cwd, "dist", entry), join(exportDir, entry), { recursive: true });
+	}
+	const referenced = /* @__PURE__ */ new Set();
+	const onFile = (src) => {
+		if (typeof src !== "string" || !src.startsWith("/@mechanica/assets/")) return src;
+		const relative = decodeURIComponent(src.slice(UPLOADS_PREFIX.length));
+		referenced.add(relative);
+		return `${assetsBase}/${MEDIA_DIR}/${relative}`;
+	};
+	rewriteComposedAssets(composedDefs, onFile);
+	const blockAssets = await readBlockAssets(cwd);
+	const pageLinks = blockAssets ? (content) => {
+		const blockIds = /* @__PURE__ */ new Set();
+		const add = (id) => {
+			if (blockIds.has(id)) return;
+			blockIds.add(id);
+			const def = composedMap.get(id);
+			if (def) for (const inner of templateBlockIds(def)) add(inner);
+		};
+		walkTree(content, (block) => add(block.blockId));
+		return blockAssetLinks({
+			blockIds,
+			...blockAssets,
+			base: assetsBase || void 0,
+			alreadyLinked: (file) => index.includes(file)
+		});
+	} : void 0;
+	const projectOptions = {
+		index,
+		blocksMap,
+		dataEntries: ssr.dataEntries ?? [],
+		projectData,
+		site: {
+			url: siteUrl,
+			name: siteName
+		},
+		assetsUrl: assetsBase || void 0,
+		locales: config ?? void 0,
+		render: (state) => ssr.render(state, { resolveQuery: resolveForPage(state.page?.pagination?.page ?? 1, state.page?.locale) }),
+		onFile,
+		pageLinks
+	};
+	const written = [];
+	const writePage = async (path, html) => {
+		const dir = path === "/" ? exportDir : join(exportDir, path);
+		await mkdir(dir, { recursive: true });
+		await writeFile(join(dir, "index.html"), html);
+		written.push(path);
+	};
+	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;
+		const at = (loc) => paginationVariantPath(localePath(source.logicalPath, loc, config), pageNum);
+		return [{
+			hreflang: "x-default",
+			path: at(config.default)
+		}, ...source.translations.map((loc) => ({
+			hreflang: loc,
+			path: at(loc)
+		}))];
+	};
+	const finishPage = (html, path, source, pagination) => {
+		let out = applySeoTags(html, {
+			siteUrl,
+			siteName,
+			path,
+			noindex: source.page?.meta?.noindex === true,
+			pagination,
+			templateHandlesPagination,
+			breadcrumbs: breadcrumbsFor(source.logicalPath, pageNames),
+			alternates: alternatesFor(source, pagination?.page ?? 1)
+		});
+		if (config) out = setHtmlLang(out, source.locale ?? config.default);
+		return out;
+	};
+	const sitemapEntries = [];
+	const recordSitemap = (path, source, pageNum = 1) => {
+		if (path === "/404" || source.page?.meta?.noindex === true) return;
+		sitemapEntries.push({
+			path,
+			lastmod: source.lastmod,
+			alternates: alternatesFor(source, pageNum)
+		});
+	};
+	const knownPaths = new Set(pages.map((page) => page.path));
+	const pageByPath = new Map(pages.map((page) => [page.path, page]));
+	const variants = [];
+	const titlePages = /* @__PURE__ */ new Map();
+	for await (const { html, path, query } of generateProject({
+		...projectOptions,
+		pages
+	})) {
+		const source = pageByPath.get(path);
+		let pageCount = 1;
+		for (const [key, result] of Object.entries(query)) {
+			if (!isPaginatedQuery(key)) continue;
+			pageCount = Math.max(pageCount, result?.pageCount ?? 1);
+		}
+		const pagination = pageCount > 1 ? {
+			page: 1,
+			pageCount,
+			basePath: path
+		} : void 0;
+		const finished = finishPage(html, path, source, pagination);
+		await writePage(path, finished);
+		recordSitemap(path, source);
+		for (const issue of auditPageHtml(finished)) warn(`[mechanica] SEO on ${path}: ${issue}`);
+		const title = finished.match(/<title[^>]*>([\s\S]*?)<\/title>/i)?.[1]?.trim();
+		if (title) titlePages.set(title, [...titlePages.get(title) ?? [], path]);
+		if (!pagination) continue;
+		const base = path === "/" ? "" : path;
+		for (let n = 2; n <= pageCount; n++) {
+			const variantPath = `${base}/${n}`;
+			if (knownPaths.has(variantPath)) throw new Error(`[mechanica] Paginated page ${path} needs ${variantPath}, but a real page already exists at that path — rename that page or adjust the pagination.`);
+			variants.push({
+				...source,
+				path: variantPath,
+				page: {
+					...source.page,
+					pagination: {
+						page: n,
+						pageCount
+					}
+				}
+			});
+		}
+	}
+	for (const [title, paths] of titlePages) if (paths.length > 1) warn(`[mechanica] SEO: ${paths.length} pages share the title "${title}": ${paths.join(", ")}`);
+	for await (const { html, path } of generateProject({
+		...projectOptions,
+		pages: variants
+	})) {
+		const source = variants.find((page) => page.path === path);
+		const basePath = path.replace(/\/\d+$/, "") || "/";
+		await writePage(path, finishPage(html, path, source, {
+			...source.page.pagination,
+			basePath
+		}));
+		recordSitemap(path, source, source.page.pagination.page);
+	}
+	await copyUploads(join(cwd, ".mech/assets"), join(exportDir, MEDIA_DIR), referenced, warn);
+	if (written.includes("/404")) await copyFile(join(exportDir, "404/index.html"), join(exportDir, "404.html"));
+	if (siteUrl) {
+		await writeFile(join(exportDir, "sitemap.xml"), buildSitemap(siteUrl, sitemapEntries));
+		const robotsPath = join(exportDir, "robots.txt");
+		if (!await access(robotsPath).then(() => true, () => false)) await writeFile(robotsPath, buildRobotsTxt(siteUrl));
+	}
+	return written;
+}
+/** Copy referenced uploads into the export; warn about missing + orphaned files. */
+async function copyUploads(assetsDir, outDir, referenced, warn) {
+	for (const relative of referenced) {
+		const target = join(outDir, relative);
+		await mkdir(dirname(target), { recursive: true });
+		await copyFile(join(assetsDir, relative), target).catch(() => {
+			warn(`[mechanica] Missing upload: ${relative} is referenced by a page but not in .mech/assets`);
+		});
+	}
+	const orphans = (await readdir(assetsDir, { recursive: true }).catch(() => [])).map((entry) => entry.replace(/\\/g, "/")).filter((entry) => /\.\w+$/.test(entry) && !referenced.has(entry) && !isDerivedAsset(entry));
+	if (orphans.length) warn(`[mechanica] ${orphans.length} unused upload(s) in .mech/assets (not exported): ${orphans.join(", ")}`);
+}
+/**
+* Statically render an already-built project: load `<cwd>/dist/ssr.js` and run
+* {@link exportProject} over `<cwd>/dist` + `<cwd>/.mech`. Never builds and
+* never loads Vite — this is the entry a hosted render service calls on a
+* bundle a developer pushed (`import { exportBuilt } from 'mechanica/export'`).
+* Warnings are collected into the result and still forwarded to `onWarn`.
+*/
+async function exportBuilt(cwd, options = {}) {
+	registerFieldSchemas();
+	const warnings = [];
+	const onWarn = (message) => {
+		warnings.push(message);
+		(options.onWarn ?? console.warn)(message);
+	};
+	return {
+		pages: await exportProject(cwd, await import(pathToFileURL(join(cwd, "dist/ssr.js")).href), {
+			...options,
+			onWarn
+		}),
+		warnings
+	};
+}
+//#endregion
+export { exportBuilt, exportProject };

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

@@ -53,6 +53,22 @@ export interface ExportOptions {
     assetsUrl?: string;
     /** Warning sink (broken links, orphaned assets). Defaults to `console.warn`. */
     onWarn?: (message: string) => void;
+    /**
+     * Where the static site is written — absolute, or relative to the project
+     * root. Defaults to `export`. The directory is emptied, never removed, so it
+     * may be a mount point (a hosted render writes into a volume).
+     */
+    outDir?: string;
+    /**
+     * How `useFetch` queries get their JSON: receives the options the block
+     * passed (`url` plus any `RequestInit` fields) and resolves with the parsed
+     * body. Defaults to a plain `fetch`. A hosted render — which runs with no
+     * network — supplies its own, so the request is made (and limited) by the
+     * service around it.
+     */
+    fetchJson?: (options: {
+        url: string;
+    } & Record<string, unknown>) => Promise<unknown>;
 }
 /**
  * Statically render every page of an already-built project into `export/`,
@@ -72,5 +88,18 @@ export interface ExportOptions {
  * `sitemap.xml` + `robots.txt`.
  */
 export declare function exportProject(cwd: string, ssr: SsrBundle, options?: ExportOptions): Promise<string[]>;
-/** Build the project, then statically render every page into `export/`. */
-export declare function runExport(options?: ExportOptions): Promise<void>;
+/** What {@link exportBuilt} produced. */
+export interface ExportResult {
+    /** The generated page paths, in render order. */
+    pages: string[];
+    /** Everything the export warned about (broken links, missing uploads, SEO lint). */
+    warnings: string[];
+}
+/**
+ * Statically render an already-built project: load `<cwd>/dist/ssr.js` and run
+ * {@link exportProject} over `<cwd>/dist` + `<cwd>/.mech`. Never builds and
+ * never loads Vite — this is the entry a hosted render service calls on a
+ * bundle a developer pushed (`import { exportBuilt } from 'mechanica/export'`).
+ * Warnings are collected into the result and still forwarded to `onWarn`.
+ */
+export declare function exportBuilt(cwd: string, options?: ExportOptions): Promise<ExportResult>;

package/dist/types/cli/platform/api.d.ts

@@ -0,0 +1,33 @@
+/** A failed platform request: the HTTP status plus the message the platform gave. */
+export declare class PlatformError extends Error {
+    status: number;
+    constructor(status: number, message: string);
+}
+export interface RequestOptions {
+    token?: string | null;
+    /** A JSON body… */
+    body?: unknown;
+    /** …or raw bytes (a bundle). */
+    raw?: Uint8Array;
+}
+/** One request to the platform API; resolves with the parsed JSON body (or null). */
+export declare function request<T = any>(origin: string, method: string, path: string, options?: RequestOptions): Promise<T>;
+/** The saved token for `origin`, or an error telling the user to log in. */
+export declare function requireToken(origin: string): Promise<string>;
+export interface PlatformSite {
+    uuid: string;
+    slug: string;
+    name: string;
+    role: string;
+    gitUrl: string;
+}
+/** The name of the git remote `mechanica link` manages. */
+export declare const REMOTE_NAME = "mechanica";
+/**
+ * Split a site's git remote URL (`https://host/git/<slug>.git`) into the
+ * platform origin and the slug; null for a URL that is not one of ours.
+ */
+export declare function parseRemoteUrl(url: string): {
+    origin: string;
+    slug: string;
+} | null;