@askrjs/askr 0.0.51 → 0.0.53

package/dist/ssg/index.js

@@ -1,2 +1,858 @@
-import { createStaticGen } from "./create-static-gen.js";
+import "../access-Bg4RJNC8.js";
+import { a as resolveDeferredValues, b as getRenderHandler, c as bindResolvedRouteData } from "../deferred-lKE8uR0z.js";
+import { n as renderDocument } from "../ssr-CbQO5xd3.js";
+import { n as renderToString } from "../ssr-D3t80Rc0.js";
+import * as fs from "node:fs/promises";
+import * as pathModule from "node:path";
+import * as os from "node:os";
+import * as fsSync from "node:fs";
+//#region src/ssg/route-utils.ts
+function getOutputFilePath(pathStr) {
+	if (pathStr === "/") return "index.html";
+	return `${pathStr.replace(/^\/|\/$/g, "")}/index.html`;
+}
+function interpolateRoutePath(routePath, params) {
+	if (!params) return routePath;
+	return routePath.replace(/\{([^}]+)\}/g, (_, key) => params[key] ?? "");
+}
+function resolveRouteDescriptor(route) {
+	const path = interpolateRoutePath(route.path, route.params);
+	const filePath = getOutputFilePath(path);
+	return {
+		route,
+		path,
+		filePath,
+		routeId: `${path}::${filePath}`,
+		invalidationKeys: route.invalidationKeys?.slice() ?? []
+	};
+}
+//#endregion
+//#region src/ssg/resolve-ssg-data.ts
+function hasOwnRouteData(dataMap, path) {
+	return Object.prototype.hasOwnProperty.call(dataMap, path);
+}
+/**
+* Resolve and validate data for SSG routes
+* Returns a map of route path -> SSRData
+*
+* In phase 1: accepts user-supplied dataOverrides
+* In phase 2: can be extended to auto-discover resources
+*/
+function resolveSsgData(routes, options = {}) {
+	const { dataOverrides = {} } = options;
+	const dataMap = {};
+	for (const route of routes) {
+		const concretePath = interpolateRoutePath(route.path, route.params);
+		const overridePath = concretePath in dataOverrides ? concretePath : route.path in dataOverrides ? route.path : null;
+		if (overridePath) {
+			const data = dataOverrides[overridePath];
+			if (typeof data !== "object" || data === null || Array.isArray(data)) throw new Error(`data for route "${overridePath}" must be an object, got ${typeof data}`);
+			dataMap[overridePath] = data;
+		}
+	}
+	return dataMap;
+}
+function resolveSsgRouteData(dataMap, routePath, concretePath) {
+	if (hasOwnRouteData(dataMap, concretePath)) return {
+		hasData: true,
+		data: dataMap[concretePath]
+	};
+	if (hasOwnRouteData(dataMap, routePath)) return {
+		hasData: true,
+		data: dataMap[routePath]
+	};
+	return {
+		hasData: false,
+		data: void 0
+	};
+}
+function isStringRecord(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	for (const recordValue of Object.values(value)) if (typeof recordValue !== "string") return false;
+	return true;
+}
+function validateRouteShape(route) {
+	if (typeof route.path !== "string" || !route.path.startsWith("/")) throw new Error(`route path must be a string starting with "/", got "${route.path}"`);
+	if (typeof (route.handler ?? route.component) !== "function") throw new Error(`route handler must be a function for path "${route.path}"`);
+	if (route.params !== void 0 && !isStringRecord(route.params)) throw new Error(`route "${route.path}" params must be an object containing only string values`);
+	if (route.invalidationKeys !== void 0) {
+		if (!Array.isArray(route.invalidationKeys)) throw new Error(`route "${route.path}" invalidationKeys must be an array of strings`);
+		for (const key of route.invalidationKeys) if (typeof key !== "string" || key.length === 0) throw new Error(`route "${route.path}" invalidationKeys must contain only non-empty strings`);
+	}
+}
+function validateEntriesResult(route, entries) {
+	if (!Array.isArray(entries)) throw new Error(`route "${route.path}" entries must return an array of param maps`);
+	return entries.map((entry, index) => {
+		if (!isStringRecord(entry)) throw new Error(`route "${route.path}" entries[${index}] must be an object containing only string values`);
+		return entry;
+	});
+}
+async function expandRoutes(routes) {
+	if (!Array.isArray(routes)) throw new Error("routes must be an array");
+	const expanded = [];
+	for (const route of routes) {
+		validateRouteShape(route);
+		if (route.params) expanded.push({
+			...route,
+			entries: void 0
+		});
+		if (!route.entries) {
+			if (!route.params) expanded.push(route);
+			continue;
+		}
+		const entries = validateEntriesResult(route, await route.entries());
+		for (const params of entries) expanded.push({
+			...route,
+			params,
+			entries: void 0
+		});
+	}
+	return expanded;
+}
+/**
+* Validate routes are properly configured
+*/
+function validateRoutes(routes) {
+	if (!Array.isArray(routes)) throw new Error("routes must be an array");
+	const seen = /* @__PURE__ */ new Set();
+	for (const route of routes) {
+		validateRouteShape(route);
+		const key = `${route.path}::${JSON.stringify(route.params || {})}`;
+		if (seen.has(key)) throw new Error(`duplicate route entry detected for path "${route.path}"`);
+		seen.add(key);
+		if (route.path.includes("{")) {
+			const paramNames = Array.from(route.path.matchAll(/\{([^}]+)\}/g)).map((m) => m[1]);
+			if (!route.params) throw new Error(`route "${route.path}" uses path parameters and requires params`);
+			for (const name of paramNames) if (!(name in route.params)) throw new Error(`route "${route.path}" missing required param "${name}"`);
+		}
+	}
+}
+//#endregion
+//#region src/ssg/batch-render.ts
+/**
+* Batch rendering of multiple routes for SSG
+*/
+/**
+* Render multiple routes in parallel with error handling
+*/
+async function batchRenderRoutes(routes, options = {}) {
+	const { seed = 12345, dataMap = {}, concurrency = 1, document } = options;
+	const workerCount = Math.max(1, Math.min(concurrency, routes.length || 1));
+	const results = [];
+	results.length = routes.length;
+	let nextIndex = 0;
+	const renderOne = async (route) => {
+		const startTime = performance.now();
+		const url = interpolateRoutePath(route.path, route.params);
+		const requestUrl = new URL(url, "http://localhost");
+		const resolvedData = resolveSsgRouteData(dataMap, route.path, url);
+		const baseData = resolvedData.hasData ? resolvedData.data : void 0;
+		const resourceCount = resolvedData.hasData && baseData ? Object.keys(baseData).length : 0;
+		const mergedHandler = route.handler ? route.handler : (params, ctx) => {
+			const component = route.component;
+			return component({
+				...route.props,
+				...params
+			}, ctx);
+		};
+		try {
+			let routeData;
+			let hasRouteData = false;
+			if (route.loader) {
+				const controller = new AbortController();
+				const loadContext = {
+					mode: "ssg",
+					params: route.params ?? {},
+					pathname: requestUrl.pathname,
+					search: requestUrl.search,
+					hash: requestUrl.hash,
+					href: `${requestUrl.pathname}${requestUrl.search}${requestUrl.hash}`,
+					auth: {
+						authenticated: false,
+						principal: null,
+						session: null,
+						tenant: null
+					},
+					signal: controller.signal
+				};
+				const loaded = await route.loader({
+					...loadContext,
+					request: new Request(requestUrl)
+				});
+				await resolveDeferredValues(loaded, controller.signal);
+				routeData = loaded;
+				hasRouteData = true;
+			}
+			const html = renderToString({
+				url,
+				routes: [{
+					path: route.path,
+					handler: hasRouteData ? bindResolvedRouteData(mergedHandler, routeData) : mergedHandler,
+					namespace: route.namespace
+				}],
+				seed,
+				data: baseData,
+				document: document === void 0 ? void 0 : ({ appHtml }) => renderDocument(document, {
+					appHtml,
+					context: {
+						mode: "ssg",
+						url,
+						pathname: requestUrl.pathname,
+						search: requestUrl.search,
+						hash: requestUrl.hash,
+						params: route.params ?? {},
+						data: baseData,
+						seed,
+						route: {
+							path: route.path,
+							namespace: route.namespace
+						}
+					}
+				}, "createStaticGen()")
+			});
+			const duration = performance.now() - startTime;
+			return {
+				path: url,
+				filePath: getOutputFilePath(url),
+				html,
+				fileSize: Buffer.byteLength(html, "utf8"),
+				renderDuration: Math.round(duration),
+				resourceCount,
+				status: "success",
+				reason: "full",
+				written: false
+			};
+		} catch (error) {
+			const duration = performance.now() - startTime;
+			return {
+				path: url,
+				filePath: getOutputFilePath(url),
+				html: "",
+				fileSize: 0,
+				renderDuration: Math.round(duration),
+				resourceCount,
+				status: "error",
+				reason: "full",
+				written: false,
+				error: error instanceof Error ? error.message : String(error)
+			};
+		}
+	};
+	const worker = async () => {
+		while (true) {
+			const current = nextIndex;
+			nextIndex += 1;
+			if (current >= routes.length) return;
+			results[current] = await renderOne(routes[current]);
+		}
+	};
+	await Promise.all(Array.from({ length: workerCount }, () => worker()));
+	return results;
+}
+//#endregion
+//#region src/ssg/write-static-files.ts
+/**
+* File I/O for Static Site Generation
+*
+* Uses Node.js fs/path modules to write rendered HTML files to disk.
+* This module is Node-only and not intended for browser builds.
+*/
+/**
+* Write rendered routes to disk
+* Creates outputDir/{route-path}/index.html structure
+*/
+async function writeStaticFiles(results, outputDir, options = {}, fileOperations = fs) {
+	await fileOperations.mkdir(outputDir, { recursive: true });
+	for (const result of results) {
+		if (result.status !== "removed") continue;
+		const fullPath = pathModule.join(outputDir, result.filePath);
+		if (fsSync.existsSync(fullPath)) {
+			await fileOperations.rm(fullPath, { force: true });
+			await pruneEmptyDirs(pathModule.dirname(fullPath), outputDir, fileOperations);
+		}
+	}
+	const pendingWrites = [];
+	for (let index = 0; index < results.length; index += 1) {
+		const result = results[index];
+		if (result.status === "error") {
+			console.warn(`Skipping failed route: ${result.path} - ${result.error}`);
+			continue;
+		}
+		if (result.status === "success" && result.written) pendingWrites.push(result);
+	}
+	const directories = [];
+	const seenDirectories = /* @__PURE__ */ new Set();
+	for (const result of pendingWrites) {
+		const dir = pathModule.dirname(pathModule.join(outputDir, result.filePath));
+		if (!seenDirectories.has(dir)) {
+			seenDirectories.add(dir);
+			directories.push(dir);
+		}
+	}
+	for (const dir of directories) await fileOperations.mkdir(dir, { recursive: true });
+	const concurrency = Math.max(1, Math.min(options.concurrency ?? 8, pendingWrites.length || 1));
+	let nextIndex = 0;
+	const worker = async () => {
+		while (true) {
+			const current = nextIndex;
+			nextIndex += 1;
+			if (current >= pendingWrites.length) return;
+			const result = pendingWrites[current];
+			const fullPath = pathModule.join(outputDir, result.filePath);
+			const tempPath = pathModule.join(pathModule.dirname(fullPath), `.${pathModule.basename(fullPath)}.askr-${process.pid}-${current}.tmp`);
+			try {
+				await fileOperations.writeFile(tempPath, result.html, "utf8");
+				await fileOperations.rename(tempPath, fullPath);
+			} finally {
+				await fileOperations.rm(tempPath, { force: true });
+			}
+		}
+	};
+	await Promise.all(Array.from({ length: concurrency }, () => worker()));
+}
+async function pruneEmptyDirs(startDir, rootDir, fileOperations) {
+	let current = startDir;
+	const normalizedRoot = pathModule.resolve(rootDir);
+	while (current.startsWith(normalizedRoot)) {
+		if (!fsSync.existsSync(current)) break;
+		if ((await fileOperations.readdir(current)).length > 0) break;
+		await fileOperations.rmdir(current);
+		if (pathModule.resolve(current) === normalizedRoot) break;
+		current = pathModule.dirname(current);
+	}
+}
+//#endregion
+//#region src/ssg/generate-metadata.ts
+/**
+* Metadata generation for SSG
+*
+* Generates and serializes metadata about generated static files.
+* This module is Node-only and not intended for browser builds.
+*/
+/**
+* Generate SSGResult from render results
+*/
+function generateSSGResult(results, options = {}) {
+	let successful = 0;
+	let failed = 0;
+	let totalDuration = 0;
+	let rebuilt = 0;
+	let skipped = 0;
+	let removed = 0;
+	for (let index = 0; index < results.length; index += 1) {
+		const result = results[index];
+		totalDuration += result.renderDuration;
+		if (result.status === "success") {
+			successful += 1;
+			rebuilt += 1;
+		} else if (result.status === "error") {
+			failed += 1;
+			rebuilt += 1;
+		} else if (result.status === "skipped") skipped += 1;
+		else if (result.status === "removed") removed += 1;
+	}
+	return {
+		generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		totalRoutes: results.length,
+		successful,
+		failed,
+		totalDuration: Math.round(totalDuration),
+		mode: options.mode ?? "full",
+		rebuilt,
+		skipped,
+		removed,
+		cacheHits: options.cacheHits ?? 0,
+		invalidatedKeys: options.invalidatedKeys?.slice() ?? [],
+		invalidatedRoutes: options.invalidatedRoutes?.slice() ?? [],
+		routes: results
+	};
+}
+/**
+* Convert SSGResult to metadata for JSON serialization
+*/
+function resultToMetadata(result) {
+	const routes = [];
+	for (let index = 0; index < result.routes.length; index += 1) {
+		const route = result.routes[index];
+		routes.push({
+			path: route.path,
+			filePath: route.filePath,
+			fileSize: route.fileSize,
+			renderDuration: route.renderDuration,
+			resourceCount: route.resourceCount,
+			status: route.status,
+			reason: route.reason,
+			written: route.written,
+			error: route.error
+		});
+	}
+	return {
+		generatedAt: result.generatedAt,
+		totalRoutes: result.totalRoutes,
+		successful: result.successful,
+		failed: result.failed,
+		totalDuration: result.totalDuration,
+		mode: result.mode,
+		rebuilt: result.rebuilt,
+		skipped: result.skipped,
+		removed: result.removed,
+		cacheHits: result.cacheHits,
+		invalidatedKeys: result.invalidatedKeys.slice(),
+		invalidatedRoutes: result.invalidatedRoutes.slice(),
+		routes
+	};
+}
+/**
+* Write metadata.json to output directory
+*/
+async function writeMetadata(metadata, outputDir) {
+	const filePath = pathModule.join(outputDir, "metadata.json");
+	await fs.mkdir(outputDir, { recursive: true });
+	await fs.writeFile(filePath, JSON.stringify(metadata, null, 2), "utf8");
+}
+const MANIFEST_DIR = ".askr";
+const MANIFEST_FILE = "ssg-manifest.json";
+function hashHtml(html) {
+	let hash = 2166136261;
+	for (let index = 0; index < html.length; index += 1) {
+		hash ^= html.charCodeAt(index);
+		hash = Math.imul(hash, 16777619);
+	}
+	return (hash >>> 0).toString(16).padStart(8, "0");
+}
+function getIncrementalManifestPath(outputDir) {
+	return pathModule.join(outputDir, MANIFEST_DIR, MANIFEST_FILE);
+}
+function readIncrementalManifest(outputDir, seed) {
+	const manifestPath = getIncrementalManifestPath(outputDir);
+	if (!fsSync.existsSync(manifestPath)) return null;
+	try {
+		const raw = fsSync.readFileSync(manifestPath, "utf8");
+		const parsed = JSON.parse(raw);
+		if (parsed.schemaVersion !== 1 || parsed.seed !== seed || !Array.isArray(parsed.routes)) return null;
+		const routes = parsed.routes.filter((entry) => !!entry && typeof entry.routeId === "string" && typeof entry.path === "string" && typeof entry.filePath === "string" && Array.isArray(entry.invalidationKeys) && (entry.htmlHash === null || typeof entry.htmlHash === "string") && (entry.lastStatus === "success" || entry.lastStatus === "error"));
+		if (routes.length !== parsed.routes.length) return null;
+		return {
+			schemaVersion: 1,
+			seed,
+			mode: parsed.mode === "incremental" ? "incremental" : "full",
+			routes
+		};
+	} catch {
+		return null;
+	}
+}
+async function writeIncrementalManifest(manifest, outputDir) {
+	const manifestPath = getIncrementalManifestPath(outputDir);
+	await fs.mkdir(pathModule.dirname(manifestPath), { recursive: true });
+	await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2), "utf8");
+}
+function getExistingOutputFileSize(outputDir, filePath) {
+	const fullPath = pathModule.join(outputDir, filePath);
+	if (!fsSync.existsSync(fullPath)) return 0;
+	try {
+		return fsSync.statSync(fullPath).size;
+	} catch {
+		return 0;
+	}
+}
+function outputFileExists(outputDir, filePath) {
+	return fsSync.existsSync(pathModule.join(outputDir, filePath));
+}
+//#endregion
+//#region src/ssg/generation-plan.ts
+function dedupeStrings(values) {
+	return values ? Array.from(new Set(values)) : [];
+}
+function getRoutesToRender(selected) {
+	const routes = [];
+	for (let index = 0; index < selected.length; index += 1) routes.push(selected[index].descriptor.route);
+	return routes;
+}
+function selectRouteForGeneration(descriptor, previous, mode, changedKeys, changedRoutes) {
+	if (mode === "full") return {
+		descriptor,
+		reason: "full",
+		previous
+	};
+	if (!previous) return {
+		descriptor,
+		reason: "new-route",
+		previous
+	};
+	if (previous.lastStatus === "error" || previous.htmlHash === null) return {
+		descriptor,
+		reason: "new-route",
+		previous
+	};
+	if (descriptor.invalidationKeys.length === 0) return {
+		descriptor,
+		reason: "no-keys",
+		previous
+	};
+	if (changedRoutes.includes(descriptor.path)) return {
+		descriptor,
+		reason: "changed-route",
+		previous
+	};
+	if (descriptor.invalidationKeys.some((key) => changedKeys.includes(key))) return {
+		descriptor,
+		reason: "changed-key",
+		previous
+	};
+	return {
+		descriptor,
+		reason: "unchanged",
+		previous
+	};
+}
+function collectRemovedRouteResults(manifest, currentRouteIds) {
+	if (!manifest) return [];
+	const results = [];
+	for (let index = 0; index < manifest.routes.length; index += 1) {
+		const entry = manifest.routes[index];
+		if (currentRouteIds.has(entry.routeId)) continue;
+		results.push({
+			path: entry.path,
+			filePath: entry.filePath,
+			html: "",
+			fileSize: 0,
+			renderDuration: 0,
+			resourceCount: 0,
+			status: "removed",
+			reason: "deleted",
+			written: false
+		});
+	}
+	return results;
+}
+//#endregion
+//#region src/ssg/static-routes.ts
+function getRuntimeOnlyDiagnostic(route, path) {
+	const policies = route.policies ?? [];
+	if (route.auth) return `Skipped prerender for "${path}": routes with auth requirements are runtime-only by default.`;
+	if (policies.length > 0) return `Skipped prerender for "${path}": routes with policies are runtime-only by default.`;
+	return null;
+}
+function getRouteResultPath(route) {
+	return route.params ? interpolateRoutePath(route.path, route.params) : route.path;
+}
+function createRuntimeOnlyRoute(route, diagnostic) {
+	const path = getRouteResultPath(route);
+	const filePath = getOutputFilePath(path);
+	return {
+		routeId: `${path}::${filePath}`,
+		result: {
+			path,
+			filePath,
+			html: "",
+			fileSize: 0,
+			renderDuration: 0,
+			resourceCount: 0,
+			status: "skipped",
+			reason: "runtime-only",
+			written: false,
+			error: diagnostic
+		}
+	};
+}
+async function splitStaticRoutes(routes) {
+	const prerenderableRoutes = [];
+	const runtimeOnly = [];
+	const outputRouteIds = [];
+	for (const route of routes) {
+		const diagnostic = getRuntimeOnlyDiagnostic(route, getRouteResultPath(route));
+		if (diagnostic) {
+			const runtimeRoute = createRuntimeOnlyRoute(route, diagnostic);
+			runtimeOnly.push(runtimeRoute);
+			outputRouteIds.push(runtimeRoute.routeId);
+			continue;
+		}
+		const expanded = await expandRoutes([route]);
+		prerenderableRoutes.push(...expanded);
+		for (const expandedRoute of expanded) outputRouteIds.push(resolveRouteDescriptor(expandedRoute).routeId);
+	}
+	return {
+		routes: prerenderableRoutes,
+		runtimeOnly,
+		outputRouteIds
+	};
+}
+function normalizeStaticRoutes(options) {
+	if (options.registry) return routeRegistryToRouteConfigs(options.registry);
+	return [...options.routes ?? []];
+}
+function routeRegistryToRouteConfigs(registry) {
+	const routeConfigs = [];
+	for (const record of registry.manifest.records) {
+		if (record.isFallback) continue;
+		routeConfigs.push({
+			path: record.path,
+			handler: getRenderHandler(record),
+			namespace: record.options.namespace,
+			auth: record.options.auth,
+			policies: record.options.policies,
+			entries: record.options.entries,
+			loader: record.options.loader
+		});
+	}
+	return routeConfigs;
+}
+//#endregion
+//#region src/ssg/create-static-gen.ts
+function resolveParallelism(requested) {
+	if (requested !== "auto") return Math.max(1, requested ?? 1);
+	const maybeNavigator = globalThis;
+	const envWorkers = Number(maybeNavigator.process?.env?.ASKR_SSG_WORKERS ?? maybeNavigator.process?.env?.NUMBER_OF_PROCESSORS ?? maybeNavigator.process?.env?.UV_THREADPOOL_SIZE);
+	if (Number.isFinite(envWorkers) && envWorkers > 0) return Math.max(1, Math.trunc(envWorkers));
+	if (typeof maybeNavigator.navigator?.hardwareConcurrency === "number") return Math.max(1, maybeNavigator.navigator.hardwareConcurrency);
+	const availableParallelism = os.availableParallelism;
+	return Math.max(1, availableParallelism?.() ?? os.cpus().length ?? 1);
+}
+async function createStagingDirectory(outputDir) {
+	const parent = pathModule.dirname(outputDir);
+	const base = pathModule.basename(outputDir);
+	await fs.mkdir(parent, { recursive: true });
+	return fs.mkdtemp(pathModule.join(parent, `.${base}.askr-staging-`));
+}
+function resolveAssetDestination(outputDir, source) {
+	const relativeDestination = source.to ?? pathModule.basename(source.from);
+	const destination = pathModule.resolve(outputDir, relativeDestination);
+	const relative = pathModule.relative(pathModule.resolve(outputDir), destination);
+	if (relative.startsWith("..") || pathModule.isAbsolute(relative)) throw new Error(`SSG asset destination must stay inside outputDir: ${relativeDestination}`);
+	return destination;
+}
+async function copyStaticAssets(assets, outputDir) {
+	for (const source of assets ?? []) {
+		if (!source.from || source.from.trim().length === 0) throw new Error("SSG asset source requires a non-empty from path");
+		const from = pathModule.resolve(source.from);
+		const to = resolveAssetDestination(outputDir, source);
+		await fs.mkdir(pathModule.dirname(to), { recursive: true });
+		await fs.cp(from, to, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+async function replaceOutputDirectory(stagingDir, outputDir, fileOperations = fs) {
+	const parent = pathModule.dirname(outputDir);
+	const backupDir = pathModule.join(parent, `.${pathModule.basename(outputDir)}.askr-backup-${Date.now()}`);
+	let backedUp = false;
+	try {
+		try {
+			await fileOperations.rename(outputDir, backupDir);
+			backedUp = true;
+		} catch (error) {
+			if (error.code !== "ENOENT") throw error;
+		}
+		await fileOperations.rename(stagingDir, outputDir);
+		await fileOperations.rm(backupDir, {
+			recursive: true,
+			force: true
+		});
+	} catch (error) {
+		if (backedUp) {
+			await fileOperations.rm(outputDir, {
+				recursive: true,
+				force: true
+			});
+			await fileOperations.rename(backupDir, outputDir);
+		}
+		throw error;
+	} finally {
+		await fileOperations.rm(stagingDir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+/**
+* Create a Static Site Generator
+*
+* Usage:
+* ```ts
+* const ssg = createStaticGen({
+*   routes: [
+*     { path: '/', component: HomePage },
+*     { path: '/about', component: AboutPage },
+*   ],
+*   outputDir: './dist',
+*   dataOverrides: {
+*     '/api/posts': { posts: [...] }
+*   }
+* });
+*
+* const result = await ssg.generate();
+* console.log(`Generated ${result.successful}/${result.totalRoutes} routes`);
+* ```
+*/
+function createStaticGen(options) {
+	let result = null;
+	const configuredRoutes = normalizeStaticRoutes(options);
+	const seed = options.seed ?? 12345;
+	const resolvedParallelism = resolveParallelism(options.parallelism);
+	const resolvedConcurrency = Math.max(1, options.concurrency ?? resolvedParallelism);
+	if (configuredRoutes.length === 0) throw new Error("routes array or route registry is required");
+	if (!options.outputDir || options.outputDir.trim().length === 0) throw new Error("outputDir is required");
+	return {
+		/**
+		* Generate static HTML for all routes
+		* Writes to outputDir with metadata.json
+		* Returns detailed results
+		*/
+		async generate(generateOptions = {}) {
+			const splitRoutes = await splitStaticRoutes(configuredRoutes);
+			const routes = splitRoutes.routes;
+			validateRoutes(routes);
+			const changedKeys = dedupeStrings(generateOptions.changedKeys);
+			const changedRoutes = dedupeStrings(generateOptions.changedRoutes);
+			const requestedMode = generateOptions.mode ?? "full";
+			const previousManifest = !generateOptions.forceFull && requestedMode === "incremental" ? readIncrementalManifest(options.outputDir, seed) : null;
+			const effectiveMode = generateOptions.forceFull || requestedMode !== "incremental" || previousManifest === null ? "full" : "incremental";
+			const dataMap = resolveSsgData(routes, { dataOverrides: options.dataOverrides });
+			const descriptors = routes.map(resolveRouteDescriptor);
+			const routeResultsById = /* @__PURE__ */ new Map();
+			for (const runtimeRoute of splitRoutes.runtimeOnly) routeResultsById.set(runtimeRoute.routeId, runtimeRoute.result);
+			const eligibleDescriptors = descriptors;
+			const previousEntries = new Map((previousManifest?.routes ?? []).map((entry) => [entry.routeId, entry]));
+			const currentRouteIds = new Set(eligibleDescriptors.map((descriptor) => descriptor.routeId));
+			const selected = [];
+			const routesToRender = [];
+			for (let index = 0; index < eligibleDescriptors.length; index += 1) {
+				const descriptor = eligibleDescriptors[index];
+				const entry = selectRouteForGeneration(descriptor, previousEntries.get(descriptor.routeId) ?? null, effectiveMode, changedKeys, changedRoutes);
+				selected.push(entry);
+				if (entry.reason !== "unchanged") routesToRender.push(entry);
+			}
+			const renderStartTime = performance.now();
+			const renderedResults = routesToRender.length > 0 ? await batchRenderRoutes(getRoutesToRender(routesToRender), {
+				seed,
+				dataMap,
+				concurrency: resolvedConcurrency,
+				document: options.document
+			}) : [];
+			performance.now() - renderStartTime;
+			const renderedByRouteId = /* @__PURE__ */ new Map();
+			for (let index = 0; index < renderedResults.length; index += 1) renderedByRouteId.set(routesToRender[index].descriptor.routeId, renderedResults[index]);
+			let cacheHits = 0;
+			const nextManifestRoutes = [];
+			for (const entry of selected) {
+				const { descriptor, previous, reason } = entry;
+				const resolvedData = resolveSsgRouteData(dataMap, descriptor.route.path, descriptor.path);
+				const baseData = resolvedData.hasData ? resolvedData.data : void 0;
+				const resourceCount = resolvedData.hasData && baseData ? Object.keys(baseData).length : 0;
+				if (reason === "unchanged") {
+					routeResultsById.set(descriptor.routeId, {
+						path: descriptor.path,
+						filePath: descriptor.filePath,
+						html: "",
+						fileSize: previous?.htmlHash !== null && previous !== null ? getExistingOutputFileSize(options.outputDir, descriptor.filePath) : 0,
+						renderDuration: 0,
+						resourceCount,
+						status: "skipped",
+						reason: "unchanged",
+						written: false
+					});
+					if (previous) nextManifestRoutes.push({
+						...previous,
+						path: descriptor.path,
+						filePath: descriptor.filePath,
+						invalidationKeys: descriptor.invalidationKeys.slice()
+					});
+					continue;
+				}
+				const rendered = renderedByRouteId.get(descriptor.routeId);
+				if (!rendered) throw new Error(`Missing rendered result for route "${descriptor.path}"`);
+				const nextResult = {
+					...rendered,
+					path: descriptor.path,
+					filePath: descriptor.filePath,
+					resourceCount,
+					reason,
+					written: false
+				};
+				if (nextResult.status === "success") {
+					const htmlDigest = hashHtml(nextResult.html);
+					const shouldWrite = effectiveMode === "full" || !previous || previous.htmlHash !== htmlDigest || !outputFileExists(options.outputDir, descriptor.filePath);
+					nextResult.written = shouldWrite;
+					if (!shouldWrite) cacheHits += 1;
+					nextManifestRoutes.push({
+						routeId: descriptor.routeId,
+						path: descriptor.path,
+						filePath: descriptor.filePath,
+						invalidationKeys: descriptor.invalidationKeys.slice(),
+						htmlHash: htmlDigest,
+						lastStatus: "success"
+					});
+				} else nextManifestRoutes.push({
+					routeId: descriptor.routeId,
+					path: descriptor.path,
+					filePath: descriptor.filePath,
+					invalidationKeys: descriptor.invalidationKeys.slice(),
+					htmlHash: previous?.htmlHash ?? null,
+					lastStatus: "error"
+				});
+				routeResultsById.set(descriptor.routeId, nextResult);
+			}
+			const removedResults = collectRemovedRouteResults(previousManifest, currentRouteIds);
+			const routeResults = [];
+			for (const routeId of splitRoutes.outputRouteIds) {
+				const routeResult = routeResultsById.get(routeId);
+				if (routeResult) routeResults.push(routeResult);
+			}
+			routeResults.push(...removedResults);
+			result = generateSSGResult(routeResults, {
+				mode: effectiveMode,
+				cacheHits,
+				invalidatedKeys: changedKeys,
+				invalidatedRoutes: changedRoutes
+			});
+			if (effectiveMode === "full" && result.failed > 0) return result;
+			const targetOutputDir = effectiveMode === "full" ? await createStagingDirectory(options.outputDir) : options.outputDir;
+			try {
+				const writeStartTime = performance.now();
+				await writeStaticFiles(routeResults, targetOutputDir, { concurrency: resolvedConcurrency });
+				performance.now() - writeStartTime;
+				await writeMetadata(resultToMetadata(result), targetOutputDir);
+				await writeIncrementalManifest({
+					schemaVersion: 1,
+					seed,
+					mode: effectiveMode,
+					routes: nextManifestRoutes
+				}, targetOutputDir);
+				await copyStaticAssets(options.assets, targetOutputDir);
+				if (effectiveMode === "full") await replaceOutputDirectory(targetOutputDir, options.outputDir);
+			} catch (error) {
+				if (effectiveMode === "full") await fs.rm(targetOutputDir, {
+					recursive: true,
+					force: true
+				});
+				throw error;
+			}
+			return result;
+		},
+		/**
+		* Get effective config in a serializable form for diagnostics.
+		*/
+		getConfig() {
+			return {
+				routeCount: configuredRoutes.length,
+				outputDir: options.outputDir,
+				seed,
+				concurrency: resolvedConcurrency,
+				parallelism: resolvedParallelism,
+				hasDataOverrides: !!options.dataOverrides,
+				assetCount: options.assets?.length ?? 0
+			};
+		},
+		/**
+		* Get the last generation result
+		* Returns null if generate() hasn't been called
+		*/
+		getResult() {
+			return result;
+		}
+	};
+}
+//#endregion
 export { createStaticGen };