@ubean/build 0.5.1 → 0.6.0-beta.1

package/dist/vue-BrbbaXTC.js

@@ -0,0 +1,1729 @@
+import { c as getComponentResolvers, h as defineVirtualModule, i as ssrSingletonDevPolicy, l as getCssImports, m as createVirtualRegistry } from "./ssr-singleton-DPTawJSx.js";
+import { E as toArray, T as resolveComponentsConfig, b as getAutoImportPresets, w as resolveAutoImportsConfig } from "./codegen-B3oGeRtK.js";
+import { createRequire } from "node:module";
+import { join, resolve } from "pathe";
+import { loadUbeanConfig } from "@ubean/config";
+import { scanProject } from "@ubean/scan";
+import { getVueLocaleParam, toVueRouterLocalePath } from "@ubean/i18n";
+import { getColorModeScript, getPartyTownScript, resolveColorModeConfig, resolvePartyTownConfig } from "@ubean/client";
+import { transformWithOxc } from "vite";
+import vue from "@vitejs/plugin-vue";
+import Components from "unplugin-vue-components/vite";
+import Markdown from "unplugin-vue-markdown/vite";
+import AutoImport from "unplugin-auto-import/vite";
+import { ubeanMdxPlugin } from "@ubean/markdown";
+import { renderFaviconLink } from "@ubean/pages";
+import VueI18nPlugin from "@intlify/unplugin-vue-i18n/vite";
+import { applyServerConfig, createUbeanApp } from "@ubean/app";
+import { generatePagesModuleSource } from "@ubean/vue/vite";
+//#region src/dev/dev-scan.ts
+/** 触发扫描的目录名（相对 `srcDir`）。并集来自 core 与 vue 两个插件此前的清单。 */
+const DEV_SCAN_DIRS = [
+	"routes",
+	"middleware",
+	"pages",
+	"layouts",
+	"plugins",
+	"app",
+	"api",
+	"locales"
+];
+const SCAN_FILE_EXTENSIONS = /\.(ts|js|mjs|cjs|mts|cts|vue|json|md|mdx)$/;
+/**
+* `srcDir` **根部**的入口文件名（`app.ts` / `app.vue` / `App.vue` / `server.ts` /
+* `server.dev.ts` …）。它们不在任何被监听的目录里，却同样决定服务端行为
+* （appRoot、defineApp、defineServer），因此必须纳入判据。
+*
+* 用静态规则而不是「等第一次扫描拿到 appEntry 再登记」：后者在入口文件本身是第一个改动对象时
+* 会漏掉 —— 首次扫描永远等不到，入口文件也就永远进不了监听集合（这正是此前「改 app.ts
+* 完全不触发重扫」的缺陷）。
+*/
+const ENTRY_FILE_PATTERN = /^(app|App)(\.(server|client))?\.(ts|js|mjs|mts|vue)$|^server(\.(dev|prod))?\.(ts|js|mjs|mts)$/;
+function createDevScanCoordinator(options) {
+	const { rootDir, source, debounceMs = 150 } = options;
+	const srcDir = options.srcDir.startsWith("/") ? options.srcDir : `${rootDir}/${options.srcDir}`;
+	const srcDirNormalized = srcDir.replace(/\/+$/, "");
+	const subscribers = /* @__PURE__ */ new Set();
+	const pending = /* @__PURE__ */ new Set();
+	let debounceTimer = null;
+	let running = null;
+	let rerunRequested = false;
+	let started = false;
+	const warn = options.onError ?? ((error) => console.error("[ubean] scan failed:", error));
+	/** 扫描目录（绝对）与「额外监听的文件」（入口文件，由扫描结果给出）。 */
+	const scanDirPaths = DEV_SCAN_DIRS.map((dir) => `${srcDirNormalized}/${dir}`);
+	const extraWatchFiles = /* @__PURE__ */ new Set();
+	function isIgnored(file) {
+		if (file.startsWith(".ubean/") || file.includes("/.ubean/")) return true;
+		if (file.includes("/node_modules/") || file.includes("/.git/")) return true;
+		if (file.endsWith(".bak")) return true;
+		return (options.ignore ?? []).some((pattern) => file.includes(pattern.replace(/\*/g, "")));
+	}
+	/**
+	* 事件是否与扫描相关。
+	*
+	* 判据是**绝对路径**（Vite 的 watcher 给的就是绝对路径）：早先 CLI 那套监听自己把
+	* `srcDir` 与事件名拼成路径，`path.join` 遇到绝对路径不重置导致拼出 `<cwd><cwd>/src/...`，
+	* 所有监听目标 ENOENT 且异常被吞 —— 表现为「服务端改动完全不生效」。这里不做任何路径拼接。
+	*/
+	function isScanRelevant(file) {
+		if (!file.endsWith(".vue") && !SCAN_FILE_EXTENSIONS.test(file)) return false;
+		if (extraWatchFiles.has(file)) return true;
+		if (!file.startsWith(`${srcDirNormalized}/`)) return false;
+		const rest = file.slice(srcDirNormalized.length + 1);
+		if (DEV_SCAN_DIRS.includes(rest.split("/")[0])) return true;
+		return !rest.includes("/") && ENTRY_FILE_PATTERN.test(rest);
+	}
+	function registerExtraFiles(result) {
+		const entries = [
+			result.appEntry?.shared,
+			result.appEntry?.server,
+			result.appEntry?.client,
+			result.appEntry?.root,
+			result.serverEntry?.shared,
+			result.serverEntry?.dev,
+			result.serverEntry?.prod
+		];
+		for (const entry of entries) if (entry?.exists && entry.fullPath && !extraWatchFiles.has(entry.fullPath)) {
+			extraWatchFiles.add(entry.fullPath);
+			source.add(entry.fullPath);
+		}
+	}
+	async function runScan(changed) {
+		const result = await (options.scan ?? (() => scanProject({
+			cwd: rootDir,
+			srcDir,
+			dirs: options.dirs,
+			ignore: options.ignore
+		})))();
+		registerExtraFiles(result);
+		for (const subscriber of subscribers) await subscriber(result, changed);
+		options.reload?.();
+		return result;
+	}
+	async function rescan(changed = []) {
+		if (running) {
+			rerunRequested = true;
+			return running;
+		}
+		running = runScan(changed).catch((error) => {
+			warn(error);
+			throw error;
+		});
+		try {
+			return await running;
+		} finally {
+			running = null;
+			if (rerunRequested) {
+				rerunRequested = false;
+				rescan([...pending]).catch(() => {});
+			}
+		}
+	}
+	function queue(file) {
+		pending.add(file);
+		if (debounceTimer) clearTimeout(debounceTimer);
+		debounceTimer = setTimeout(() => {
+			debounceTimer = null;
+			const changed = [...pending];
+			pending.clear();
+			rescan(changed).catch(() => {});
+		}, debounceMs);
+	}
+	const onFileEvent = (file) => {
+		if (isIgnored(file) || !isScanRelevant(file)) return;
+		queue(file);
+	};
+	return {
+		subscribe(fn) {
+			subscribers.add(fn);
+			return () => subscribers.delete(fn);
+		},
+		start() {
+			if (started) return;
+			started = true;
+			for (const dir of scanDirPaths) source.add(dir);
+			source.on("add", onFileEvent);
+			source.on("unlink", onFileEvent);
+			source.on("change", onFileEvent);
+		},
+		rescan,
+		subscriberCount: () => subscribers.size,
+		stop() {
+			if (!started) return;
+			started = false;
+			source.off?.("add", onFileEvent);
+			source.off?.("unlink", onFileEvent);
+			source.off?.("change", onFileEvent);
+			if (debounceTimer) {
+				clearTimeout(debounceTimer);
+				debounceTimer = null;
+			}
+			pending.clear();
+		}
+	};
+}
+const SCAN_STATE_KEY = "__ubeanScanState";
+function scanStateOf(server) {
+	const holder = server;
+	holder[SCAN_STATE_KEY] ??= {};
+	return holder[SCAN_STATE_KEY];
+}
+/**
+* 取（或建立）该 dev server 的协调器。
+*
+* core 与 vue 插件都调用它，因此**先到的那个**负责建实例；后到的拿同一个。
+* `init` 只在首次调用时执行。
+*/
+function getDevScanCoordinator(server, init) {
+	const state = scanStateOf(server);
+	if (state.coordinator) return state.coordinator;
+	const coordinator = createDevScanCoordinator(init(server.watcher));
+	state.coordinator = coordinator;
+	if (state.pending) {
+		for (const fn of state.pending) coordinator.subscribe(fn);
+		state.pending = void 0;
+	}
+	coordinator.start();
+	return coordinator;
+}
+/**
+* 取该 dev server **已存在**的协调器（不存在返回 undefined）。
+*
+* 给「只想触发一次扫描」的调用方用（CLI 的 `rescan()`）：`getDevScanCoordinator` 需要 init
+* 参数、会在缺失时建实例，不适合这里。
+*/
+function peekDevScanCoordinator(server) {
+	return scanStateOf(server).coordinator;
+}
+/**
+* 订阅 dev 扫描（CLI 用：每次扫描后重建 Hono app 并让浏览器重载）。
+*
+* 允许在协调器建立之前订阅：`getDevScanCoordinator` 会把已登记的订阅转交给新实例。
+*/
+function onDevScan(server, handler) {
+	const state = scanStateOf(server);
+	if (state.coordinator) return state.coordinator.subscribe(handler);
+	state.pending ??= /* @__PURE__ */ new Set();
+	state.pending.add(handler);
+	return () => state.pending?.delete(handler);
+}
+//#endregion
+//#region src/dev/dev-ssr-routes.ts
+/**
+* dev/SSR 路由表（RM-V11 的组成部件，从 CLI dev server 抽出）。
+*
+* 这里解决的是一个**曾经出过缺陷**的问题类别：服务端 SSR 用的路由表与客户端
+* `virtual:ubean-pages` 的路由表由两处代码各自拼装，一旦不一致就会出现
+* 「SSR 与客户端解析到不同 route record」→ 水合不一致，甚至整页降级。
+*
+* 已实测的两次事故：
+* - **R8**：dev 的服务端路由表只由扫描到的页面构成，**漏了客户端的 404 catch-all**，
+*   于是渲染未知路径时 vue-router 报 `VUE_ROUTER_R0004` 无匹配，页面只渲染出布局外壳，
+*   404 组件自身的 DOM 与 `useHead` 标题全部缺失。
+* - 语言前缀路由：服务端若不带与客户端相同的 locale param，`/zh/xxx` 会落到 catch-all。
+*
+* 因此本模块把「和客户端保持一致」变成可测的约束（见 `dev-ssr-routes.test.ts` 里
+* 直接对照 `generatePagesModuleSource` 产出的客户端路由表），而不是靠两处注释互相提醒。
+*/
+/** 扫描器方言 `**:slug`（catch-all）→ vue-router 的 `:slug(.*)*`。 */
+function toVueRouterPagePath(route) {
+	return route.replace(/\*\*:(\w[\w-]*)/g, ":$1(.*)*");
+}
+/**
+* 构建 SSR 路由表。
+*
+* 顺序与形状刻意对齐客户端：页面按扫描顺序、reuse 路由复用目标页面的组件、
+* 最后是 404 catch-all。catch-all 用 `/:locale?/:pathMatch(.*)*` —— SSR 渲染的是
+* **请求 URL 本身**（不像 SSG 渲染静态产物、可以用 `/404`），必须与客户端同形才能
+* 让两侧 `useRoute()` 解析出同一份 matched 结构。
+*/
+function buildDevSsrRoutes(options) {
+	const { pages, layouts, loadComponent, localeVueParam, notFoundPage } = options;
+	const defaultLayout = layouts.find((l) => l.isDefault)?.name ?? null;
+	const withLocale = (path) => localeVueParam ? toVueRouterLocalePath(path, localeVueParam) : path;
+	const pageByName = /* @__PURE__ */ new Map();
+	for (const page of pages) pageByName.set(page.name, page);
+	const componentFor = (page) => {
+		const fullPath = (page.isReuse && page.reuseTarget ? pageByName.get(page.reuseTarget) : void 0)?.fullPath || page.fullPath;
+		return async () => await loadComponent(fullPath);
+	};
+	const routeFor = (page) => ({
+		path: withLocale(toVueRouterPagePath(page.route)),
+		name: page.name,
+		component: componentFor(page),
+		meta: {
+			layout: page.layout === false ? false : page.layout || defaultLayout,
+			pageName: page.name,
+			cache: page.cache === true ? true : void 0
+		}
+	});
+	const grouped = /* @__PURE__ */ new Map();
+	for (const page of pages) {
+		const group = grouped.get(page.route) ?? { slots: [] };
+		if (page.slot) group.slots.push(page);
+		else if (!group.default) group.default = page;
+		grouped.set(page.route, group);
+	}
+	const routes = [];
+	for (const group of grouped.values()) {
+		const primary = group.default ?? group.slots[0];
+		if (!primary) continue;
+		const route = routeFor(primary);
+		if (group.slots.length > 0) {
+			const components = {};
+			if (group.default) components.default = componentFor(group.default);
+			for (const slotPage of group.slots) components[slotPage.slot] = componentFor(slotPage);
+			delete route.component;
+			route.components = components;
+		}
+		routes.push(route);
+	}
+	if (notFoundPage) routes.push({
+		path: withLocale("/:pathMatch(.*)*"),
+		name: "NotFound",
+		component: async () => await loadComponent(notFoundPage.fullPath),
+		meta: {
+			layout: notFoundPage.layout === false ? false : notFoundPage.layout || defaultLayout,
+			pageName: "NotFound"
+		}
+	});
+	return routes;
+}
+//#endregion
+//#region src/dev/dev-host-app.ts
+/**
+* 把 Vite SSR 图的加载器与 SSR 渲染器接到 host app 上。
+*
+* 必须在**每次** app 实例更新后调用（CLI 的 `updateApp`）：闭包持有模块加载器，
+* HMR 后需要重新指向新的扫描结果与 Vite 模块图。
+*/
+function enhanceDevApp(options) {
+	const { app, layouts = [], loadModule, localeVueParam, backend, startCronScheduler, onCronError } = options;
+	app.options.layouts = layouts;
+	const routeLoaders = {};
+	for (const route of app.options.routes || []) {
+		const fullPath = route.fullPath;
+		routeLoaders[route.relativePath] = () => loadModule(fullPath);
+	}
+	app.options.routeLoaders = routeLoaders;
+	const pageByName = /* @__PURE__ */ new Map();
+	for (const page of app.options.pages || []) pageByName.set(page.name, page);
+	const pageLoaders = {};
+	for (const page of app.options.pages || []) {
+		const fullPath = (page.isReuse && page.reuseTarget ? pageByName.get(page.reuseTarget) : void 0)?.fullPath || page.fullPath;
+		pageLoaders[page.relativePath] = () => loadModule(fullPath);
+	}
+	app.options.pageLoaders = pageLoaders;
+	const middlewareLoaders = {};
+	for (const mw of app.options.middleware || []) {
+		const fullPath = mw.fullPath;
+		middlewareLoaders[mw.relativePath] = () => loadModule(fullPath);
+	}
+	app.options.middlewareLoaders = middlewareLoaders;
+	const cronFiles = app.options.crons || [];
+	if (cronFiles.length > 0 && startCronScheduler) Promise.all(cronFiles.map((c) => loadModule(c.fullPath))).then(() => startCronScheduler()).catch((error) => {
+		if (onCronError) onCronError(error);
+		else console.error("[ubean] Failed to load cron files:", error);
+	});
+	if (backend) {
+		app.resetInit();
+		return app;
+	}
+	const layoutMap = /* @__PURE__ */ new Map();
+	for (const layout of layouts) layoutMap.set(layout.name, layout.fullPath);
+	const defaultLayout = layouts.find((l) => l.isDefault)?.name || null;
+	const routes = buildDevSsrRoutes({
+		pages: app.options.pages || [],
+		layouts,
+		localeVueParam,
+		loadComponent: loadModule,
+		notFoundPage: app.options.notFoundPage
+	});
+	let appConfigModule = null;
+	const getAppConfigModule = () => {
+		if (!appConfigModule) appConfigModule = loadModule("virtual:ubean-app");
+		return appConfigModule;
+	};
+	app.options.pageRenderer = options.createRenderer({
+		routes,
+		async resolveLayoutComponent(name) {
+			if (name === false || name == null) return null;
+			const fullPath = layoutMap.get(name);
+			if (!fullPath) return null;
+			const mod = await loadModule(fullPath);
+			return mod.default || mod;
+		},
+		defaultLayout,
+		async resolveAppConfig() {
+			return (await getAppConfigModule()).resolveAppConfig?.("server");
+		}
+	});
+	return app;
+}
+//#endregion
+//#region src/dev/dev-app.ts
+/**
+* 宿主 dev app 的创建与自举（RM-V11）。
+*
+* 与同目录 `dev-host-app.ts` 的分工：
+* - `enhanceDevApp()`：把 Vite SSR 图的加载器/渲染器**接到**一个已存在的 app 上；
+* - 本模块：**创建**那个 app（扫描 → `createUbeanApp`），并负责首次请求前的 ready 流程。
+*
+* 之所以要从 CLI 搬进来：ADR-0012 §3 的目标形态是 Vite 持有 server、框架插件自举 ——
+* 插件拿不到「CLI 造好的 app」，就必须能自己造。
+*
+* 三个出口按依赖递增排列，调用方按自己拿得到的东西选：
+* 1. `createDevApp()` —— 不需要 Vite server（CLI 的 dev 命令用它）；
+* 2. `createDevAppReady()` —— 需要一个 `loadModule`（`server.ssrLoadModule`）；
+* 3. `bootstrapDevApp()` —— 两者 + `enhanceDevApp`，即插件自举时的完整入口。
+*
+* 日志策略（请求日志的级别与过滤）刻意不搬：那是 CLI 的 `logging` 配置域与终端呈现，
+* 由调用方通过 `configureApp` 挂 hook，builder 只保证结构。
+*/
+const fallbackLogger = {
+	warn: (message) => console.warn(message),
+	error: (message) => console.error(message),
+	info: (message) => console.log(message)
+};
+/** 请求日志里跳过内部路径的前缀（与 CLI 的旧实现一致）。 */
+const REQUEST_LOG_INTERNAL_PREFIXES = ["/_", "/@"];
+/** 超过该毫秒数的请求提升为 warn（慢请求告警）。 */
+const REQUEST_LOG_SLOW_THRESHOLD = 1e3;
+/**
+* 请求日志 hook（`logging.request` 分类）：默认关闭。
+*
+* RM-V14 从 CLI 的 dev 命令搬来：dev 请求现在由插件服务（`vite dev` 也是），日志策略属于
+* **配置域**（`ubean.config.ts` 的 `logging.request`）而不是某个命令的实现细节，放在这里
+* 两条路径才能给出一致的输出。
+*
+* 资源/模块请求在 Vite 中间件层即被消费，不会进到 app —— 因此天然只记录应用请求。
+*/
+function attachRequestLogger(app, enabled, logger) {
+	if (!enabled) return;
+	const requestStartTimes = /* @__PURE__ */ new WeakMap();
+	const isInternalPath = (path) => REQUEST_LOG_INTERNAL_PREFIXES.some((prefix) => path.startsWith(prefix));
+	app.hooks.hook("request:start", (c) => {
+		requestStartTimes.set(c, Date.now());
+	});
+	app.hooks.hook("request:end", (c, res) => {
+		const start = requestStartTimes.get(c);
+		const duration = start === void 0 ? 0 : Date.now() - start;
+		const line = `${c.req.method} ${c.req.path} ${res.status} ${duration}ms`;
+		if (res.status >= 500) {
+			logger.error(line);
+			return;
+		}
+		if (isInternalPath(c.req.path)) return;
+		if (res.status >= 400 || duration >= REQUEST_LOG_SLOW_THRESHOLD) {
+			logger.warn(line);
+			return;
+		}
+		logger.info(line);
+	});
+	app.hooks.hook("request:error", (c, err) => {
+		logger.error(`${c.req.method} ${c.req.path} ERROR ${err instanceof Error ? err.message : String(err)}`);
+	});
+}
+/** 扫描（可选）并创建 dev 用的宿主 app —— 不需要 Vite server。 */
+async function createDevApp(options) {
+	const { rootDir, config, configureApp, logger } = options;
+	const scanResult = options.scanResult ?? await scanProject({
+		cwd: rootDir,
+		srcDir: config.srcDir,
+		dirs: config.dir,
+		ignore: config.scanOptions?.ignore
+	});
+	const app = createUbeanApp({
+		rootDir,
+		routes: scanResult.apiRoutes,
+		middleware: scanResult.middlewares,
+		pages: scanResult.pages,
+		crons: scanResult.crons,
+		routeRules: config.routeRules || {},
+		publicDir: config.dir.public,
+		pageAssetTags: config.favicon ? { favicon: config.favicon } : void 0,
+		openAPI: {
+			title: "UBEAN Dev API",
+			scalarPath: "/_scalar",
+			openAPIPath: "/_openapi.json"
+		},
+		i18nConfig: config.i18n,
+		ssrExclude: config.ssr.exclude,
+		streaming: config.ssr.streaming,
+		notFoundPage: scanResult.notFoundPage,
+		csrf: config.security === false ? false : config.security?.csrf ?? true,
+		securityHeaders: options.securityHeaders ?? resolveDevSecurityHeaders(config),
+		dataCache: config.dataCache,
+		cache: config.cache?.store === "fs" ? {
+			store: "fs",
+			dir: config.cache.dir
+		} : { dir: config.cache?.dir },
+		seoConventions: { srcDir: config.srcDir }
+	});
+	configureApp?.(app);
+	attachRequestLogger(app, config.logging?.request === true, logger ?? fallbackLogger);
+	return {
+		app,
+		scanResult,
+		layouts: scanResult.layouts
+	};
+}
+/**
+* 首次处理请求前的初始化：加载 locales、应用用户 `defineServer` 配置、`app.init()`、
+* 调一次 `onServerReady`。
+*
+* 每次 app 实例更换后都要重新建一个（CLI 的 `updateApp` / HMR 之后）：新实例需要重新应用
+* 配置并重新走 init，旧实例的 ready 缓存不能复用。
+*/
+function createDevAppReady(options) {
+	const { app, loadModule } = options;
+	const logger = options.logger ?? fallbackLogger;
+	let readyPromise = null;
+	let cachedServerConfig = null;
+	let serverReadyCalled = false;
+	const ready = (() => {
+		readyPromise ??= (async () => {
+			try {
+				await loadModule("ubean:locales");
+			} catch (error) {
+				logger.warn(`[ubean] Failed to resolve locales module: ${String(error)}`);
+			}
+			try {
+				const serverMod = await loadModule("virtual:ubean-server");
+				if (serverMod?.resolveServerConfig) {
+					cachedServerConfig = serverMod.resolveServerConfig("dev");
+					await applyServerConfig(app, cachedServerConfig);
+				}
+			} catch (error) {
+				logger.warn(`[ubean] Failed to load server config: ${String(error)}`);
+			}
+			await app.init();
+			if (!serverReadyCalled) {
+				serverReadyCalled = true;
+				if (cachedServerConfig?.onServerReady) try {
+					await cachedServerConfig.onServerReady(app);
+				} catch (error) {
+					logger.warn(`[ubean] onServerReady error: ${String(error)}`);
+				}
+			}
+		})();
+		return readyPromise;
+	});
+	ready.serverConfig = () => cachedServerConfig;
+	return ready;
+}
+/**
+* 插件自举入口：创建 app → 接上 Vite SSR 图 → 准备好 ready。
+*
+* `vite dev` 场景下由框架插件调用（无 CLI 参与）；`ubean dev` 目前分两步调用
+* （`createDevApp` 在 CLI、`createDevAppReady` 在 dev server），因为 CLI 需要在 Vite server
+* 建起来之前就把 app 交给 DevTools/runner。RM-V12 摘除 CLI 的 server 层后两者会合并。
+*/
+async function bootstrapDevApp(options) {
+	const created = await createDevApp(options);
+	const enhance = (target, targetLayouts) => enhanceDevApp({
+		app: target,
+		layouts: targetLayouts,
+		loadModule: options.loadModule,
+		createRenderer: options.createRenderer,
+		localeVueParam: resolveLocaleVueParam(options.config),
+		backend: options.config.mode === "backend",
+		startCronScheduler: options.startCronScheduler,
+		onCronError: (error) => (options.logger ?? fallbackLogger).error(`[ubean] Failed to load cron files: ${String(error)}`)
+	});
+	const bootstrap = {
+		app: created.app,
+		scanResult: created.scanResult,
+		layouts: created.layouts,
+		ready: createDevAppReady({
+			app: created.app,
+			loadModule: options.loadModule,
+			logger: options.logger
+		}),
+		async rebuild(scanResult) {
+			const next = await createDevApp({
+				...options,
+				scanResult
+			});
+			bootstrap.app = next.app;
+			bootstrap.scanResult = next.scanResult;
+			bootstrap.layouts = next.layouts;
+			bootstrap.ready = createDevAppReady({
+				app: next.app,
+				loadModule: options.loadModule,
+				logger: options.logger
+			});
+			enhance(next.app, next.layouts);
+		}
+	};
+	enhance(bootstrap.app, bootstrap.layouts);
+	return bootstrap;
+}
+/**
+* `config.security` → dev 安全头默认值。
+*
+* ssg 模式默认关闭：静态产物没有框架运行时的安全头，dev 下也没有需要保护的服务端渲染面。
+*/
+function resolveDevSecurityHeaders(config) {
+	const security = config.security;
+	if (security === false) return false;
+	if (security?.headers === false) return false;
+	if (security?.headers !== void 0) return security.headers;
+	return config.mode !== "ssg";
+}
+/**
+* locale param 必须与客户端 `virtual:ubean-pages` 的路由表一致，否则 `/zh/xxx` 在服务端
+* 落不到对应路由（会掉进 404 catch-all），而客户端渲染的是真实页面 → 水合不一致。
+* i18n 未启用或不需要前缀时返回空串。
+*/
+function resolveLocaleVueParam(config) {
+	const i18n = config.i18n;
+	if (!i18n?.enabled || !i18n.locales?.length) return "";
+	return getVueLocaleParam({
+		defaultLocale: i18n.defaultLocale,
+		locales: i18n.locales.map((l) => l.code),
+		strategy: i18n.strategy
+	});
+}
+//#endregion
+//#region src/dev/node-web.ts
+/**
+* `node:http` 请求 → Web `Request`。
+*
+* 非 GET/HEAD 时直接把 `IncomingMessage`（可读流）作为 body；undici 要求流式 body 显式
+* 声明 `duplex: 'half'`，否则构造 `Request` 会抛错。
+*/
+async function toWebRequest(req, host, protocol) {
+	const url = `${protocol}://${req.headers.host || host}${req.url || "/"}`;
+	const headers = new Headers();
+	for (const [key, value] of Object.entries(req.headers)) if (value) {
+		if (Array.isArray(value)) for (const v of value) headers.append(key, v);
+		else headers.set(key, value);
+	}
+	const method = req.method || "GET";
+	return new Request(url, {
+		method,
+		headers,
+		body: method === "GET" || method === "HEAD" ? void 0 : req,
+		duplex: "half"
+	});
+}
+/** Web `Response` → `node:http` 响应：写入状态与头，再流式转发 body（不整体缓冲）。 */
+async function sendWebResponse(res, webRes) {
+	res.statusCode = webRes.status;
+	res.statusMessage = webRes.statusText;
+	webRes.headers.forEach((value, key) => {
+		res.setHeader(key, value);
+	});
+	if (webRes.body) {
+		const reader = webRes.body.getReader();
+		try {
+			while (true) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				res.write(value);
+			}
+		} finally {
+			reader.releaseLock();
+		}
+	}
+	res.end();
+}
+//#endregion
+//#region src/dev/dev-request-router.ts
+/**
+* Vite 内部的 URL 前缀。这些路径与文件系统无关，交回 Vite 才能正确解析。
+*
+* `/@vite/` 客户端与 HMR 运行时；`/@id/` 虚拟模块；`/@fs/` 工作区外的绝对路径；
+* `/node_modules/` 依赖；`/__vite_ping` 心跳（`Accept: text/x-vite-ping`）。
+*/
+const VITE_URL_PREFIXES = [
+	"/@vite/",
+	"/@id/",
+	"/@fs/",
+	"/node_modules/",
+	"/__vite_ping"
+];
+/**
+* ubean 保留命名空间：`_` 前缀是内置路由（`/_health`、`/_openapi.json`、`/_scalar`、
+* `/_devtools`、`/_iconify`），`__` 前缀是运行时端点（`/__actions`、`/__server-component`），
+* `/api/` 是约定俗成的 API 前缀。这些必须归 ubean —— 注意 `_` 规则要先于静态扩展名规则，
+* 否则 `/_openapi.json` 会被当成 `.json` 静态资源。
+*/
+const RESERVED_APP_PREFIXES = [
+	"/_",
+	"/__",
+	"/api/"
+];
+/**
+* DevTools 相关、**必须交给 Vite** 的命名空间前缀（DTK 外壳 + ubean DevTools SPA）。
+*
+* 它们全落在 `_` / `__` 保留命名空间里，判据默认会判给 ubean → 应用 404，因此调用方要把这份
+* 前缀整体传给 `passThrough`。两个条目覆盖了 DTK 实际使用的四个名字：
+* - `/__devtools` → `/__devtools/`（外壳 HTML、RPC、WS）、`/__devtools-assets/`（DTK 自带 UI
+*   的静态资源，dock 图标的 `vite-plus.svg` 就在这里）、`/__devtools-client-imports.js`
+*   （dock 客户端模块的虚拟模块）；
+* - `/_devtools` → `/_devtools/index.html`（DTK 以 iframe 载入的 SPA）及其 `assets/*` 与
+*   `/_devtools/__connection.json`。裸 `/_devtools` 由 `devtoolsRedirect` 抢先 302，不受影响。
+*
+* 2026-09-17 实测：`/__devtools-assets/vite-plus.svg`（应用页控制台报 404）与
+* `/_devtools/index.html`（DevTools 面板空白的真凶）此前都落进了应用 404。
+*/
+const DEVTOOLS_PASS_THROUGH_PREFIXES = ["/__devtools", "/_devtools"];
+/**
+* 框架内置的 **HTML 页面**（不是应用页面）：`/_scalar`（Scalar API 文档）与 `/_devtools`
+* （DevTools SPA）。
+*
+* 它们由框架自己产出 HTML，文档里**没有**应用的挂载点，因此不能走应用的客户端入口注入 ——
+* 被注入时浏览器报 `Failed to mount app: mount target selector "#app" returned null`，且 Vite 的
+* HTML transform 会把页面里的内联脚本（Scalar 的 `data-configuration` 块）改写成 html-proxy
+* 模块，页面直接崩（2026-09-17 实测：DevTools 的 API Docs 面板整页空白）。
+*
+* 判据被两处共用 —— dev 请求路由（决定要不要对响应做 `transformIndexHtml`）与 vue 插件的
+* `transformIndexHtml`（决定要不要注入客户端入口）；单点维护，避免两边各写一份字符串判定。
+*/
+const FRAMEWORK_HTML_PAGES = ["/_devtools", "/_scalar"];
+/** 该 URL 是否指向框架内置的 HTML 页面（见 {@link FRAMEWORK_HTML_PAGES}）。 */
+function isFrameworkHtmlPage(url) {
+	const pathname = url.split("?")[0].split("#")[0];
+	return FRAMEWORK_HTML_PAGES.some((page) => pathname === page || pathname.startsWith(`${page}/`));
+}
+/** 「取模块而不是取页面」的查询标记：Vite 的 import-analysis 会在这些请求上加它们。 */
+const MODULE_QUERY_FLAGS = /* @__PURE__ */ new Set([
+	"import",
+	"raw",
+	"url",
+	"inline",
+	"direct",
+	"worker",
+	"vue",
+	"html-proxy"
+]);
+/**
+* `Sec-Fetch-Dest` 中表示「资源」的取值（非文档）。导航请求是 `document`，
+* `fetch()`/XHR 是 `empty` —— 后者既可能是 API 调用也可能是资源请求，因此不能作为判据，
+* 交给扩展名规则。
+*/
+const RESOURCE_DESTS = /* @__PURE__ */ new Set([
+	"audio",
+	"embed",
+	"font",
+	"image",
+	"manifest",
+	"object",
+	"paintworklet",
+	"script",
+	"serviceworker",
+	"sharedworker",
+	"style",
+	"track",
+	"video",
+	"worker",
+	"xslt"
+]);
+/**
+* 会被 Vite 当资源处理的扩展名。刻意保守：只列真实静态资源与可编译模块后缀，
+* `.txt` / `.xml` 这类「既可能是静态文件也可能是应用约定路由」（`robots.txt`、`sitemap.xml`）
+* 也列进来 —— 没有对应静态文件时 Vite 会 `next()`，由 post 兜底回到应用，行为仍然正确。
+*/
+const ASSET_EXTENSIONS = /* @__PURE__ */ new Set([
+	"avif",
+	"br",
+	"bmp",
+	"cjs",
+	"css",
+	"csv",
+	"eot",
+	"gif",
+	"gz",
+	"ico",
+	"jpeg",
+	"jpg",
+	"js",
+	"json",
+	"map",
+	"mjs",
+	"md",
+	"mdx",
+	"mp3",
+	"mp4",
+	"ogg",
+	"otf",
+	"pdf",
+	"png",
+	"scss",
+	"sass",
+	"less",
+	"styl",
+	"svg",
+	"ts",
+	"tsx",
+	"ttf",
+	"txt",
+	"vue",
+	"wasm",
+	"wav",
+	"webm",
+	"webmanifest",
+	"webp",
+	"woff",
+	"woff2",
+	"xml",
+	"zip"
+]);
+/** `header` 可能是数组（Node 对重复头部的表示）。 */
+function headerValue(headers, name) {
+	const value = headers[name];
+	if (!value) return "";
+	return (Array.isArray(value) ? value[0] : value).toLowerCase();
+}
+function hasModuleQuery(search) {
+	if (!search) return false;
+	for (const part of search.slice(1).split("&")) {
+		const key = part.split("=")[0];
+		if (MODULE_QUERY_FLAGS.has(key)) return true;
+	}
+	return false;
+}
+function hasAssetExtension(pathname) {
+	const lastSegment = pathname.slice(pathname.lastIndexOf("/") + 1);
+	const dot = lastSegment.lastIndexOf(".");
+	if (dot <= 0 || dot === lastSegment.length - 1) return false;
+	return ASSET_EXTENSIONS.has(lastSegment.slice(dot + 1).toLowerCase());
+}
+/**
+* 这个请求是不是「Vite 的资源请求」？`true` → 交给 Vite；`false` → 归 ubean。
+*
+* 纯函数（只读 URL 与请求头），便于单测钉住判据 —— 这是 RM-V10 最容易出错的部分。
+*/
+function isViteResourceRequest(url, headers = {}) {
+	const [rawPath, search = ""] = url.split("#")[0].split(/(?=\?)/);
+	const pathname = decodeURIComponent(rawPath || "/");
+	if (VITE_URL_PREFIXES.some((prefix) => pathname === prefix.slice(0, -1) || pathname.startsWith(prefix))) return true;
+	if (hasModuleQuery(search)) return true;
+	if (RESERVED_APP_PREFIXES.some((prefix) => pathname === prefix.slice(0, -1) || pathname.startsWith(prefix))) return false;
+	const dest = headerValue(headers, "sec-fetch-dest");
+	if (dest === "document") return false;
+	if (RESOURCE_DESTS.has(dest)) return true;
+	if (hasAssetExtension(pathname)) return true;
+	return false;
+}
+const VALID_ID_PREFIX = "/@id/";
+const NULL_BYTE_PLACEHOLDER = "__x00__";
+/**
+* 虚拟模块 id 在模块图里带原始 `\0` 标记（如 UnoCSS 的 `\0/__uno.css`），而 NUL 是非法 HTML
+* 字符（parse5 报 `unexpected-null-character`）。这里镜像 Vite 自己的 `wrapId` 编码。
+*/
+function toDevCssHref(url) {
+	return url.includes("\0") ? `${VALID_ID_PREFIX}${url.replace(/\0/g, NULL_BYTE_PLACEHOLDER)}` : url;
+}
+/**
+* 从客户端模块图收集 render-blocking CSS 链接。
+*
+* dev 下由 JS 引入的 CSS（虚拟 uno.css 入口、全局样式、字体 css）要等客户端模块图执行完才生效，
+* SSR HTML 在这段间隙是**无样式**的（FOUC）。把同一批 CSS 以阻塞 `<link>` 注入，浏览器可与 JS
+* 并行抓取，首屏即有样式。
+*
+* `?direct` 让 Vite 的 transform 中间件返回原始 CSS（`Content-Type: text/css`）而不是注入式 JS
+* 包装；URL 自带查询串的模块（SFC `<style>` 块形如 `*.vue?vue&type=style`）无法这样服务，跳过。
+*/
+function collectDevCssLinks(moduleGraph) {
+	const links = /* @__PURE__ */ new Set();
+	for (const mod of moduleGraph.idToModuleMap.values()) {
+		const { url, id } = mod;
+		if (!url || url.includes("?")) continue;
+		if (id?.endsWith(".css") || url.endsWith(".css")) links.add(`${toDevCssHref(url)}?direct`);
+	}
+	return [...links];
+}
+/** 在 `</head>` 前插入阻塞样式链接。 */
+function injectStylesheetLinks(html, hrefs) {
+	if (!hrefs.length || !html.includes("</head>")) return html;
+	const tags = hrefs.map((href) => `<link rel="stylesheet" href="${href}">`).join("");
+	return html.replace("</head>", `${tags}</head>`);
+}
+/** 缺省 cron 启动器：动态加载，避免把服务端运行时拉进插件模块的顶层依赖。 */
+async function defaultCronScheduler() {
+	(await import("@ubean/server/cron")).startCronScheduler();
+}
+/**
+* 自举式 handler：首次调用时创建宿主 dev app（`bootstrapDevApp`），之后复用同一实例。
+*
+* 复用同一个 promise 而不是每次请求重建：`bootstrapDevApp` 会扫盘并加载 SSR 图，重建等于
+* 每个请求都重扫；同时保证并发首请求只自举一次。
+*/
+/**
+* 自举出来的 app（供 DevTools 的 playground 等按需取用）。挂在 server 对象上，理由同
+* dev-scan 的协调器：用户 `vite.config.ts` 由 Vite 打包加载，插件与 CLI 可能持有不同的模块实例。
+*/
+const DEV_APP_KEY = "__ubeanDevApp";
+/** 取该 dev server 上自举出的 app（还没自举时返回 undefined）。 */
+function getDevApp(server) {
+	return server[DEV_APP_KEY];
+}
+function createLazyBootstrapHandler(server, options = {}) {
+	let bootstrapPromise = null;
+	const start = async () => {
+		const rootDir = options.rootDir ?? server.config.root;
+		return bootstrapDevApp({
+			rootDir,
+			config: options.loadConfig ? await options.loadConfig(rootDir) : await loadUbeanConfig(rootDir),
+			loadModule: (id) => server.ssrLoadModule(id),
+			createRenderer: (await server.ssrLoadModule("@ubean/client/ssr")).createVueRenderer,
+			startCronScheduler: options.startCronScheduler ?? defaultCronScheduler,
+			logger: server.config.logger
+		});
+	};
+	onDevScan(server, async (result) => {
+		await (await bootstrapPromise?.catch(() => null))?.rebuild(result);
+	});
+	return async (request) => {
+		bootstrapPromise ??= start().then((bootstrap) => {
+			server[DEV_APP_KEY] = bootstrap.app;
+			return bootstrap;
+		});
+		const bootstrap = await bootstrapPromise;
+		await bootstrap.ready();
+		server[DEV_APP_KEY] = bootstrap.app;
+		return bootstrap.app.fetch(request);
+	};
+}
+/** 500 错误页。dev 才看得到，直接给可读的原文与栈。 */
+function renderErrorPage(error) {
+	return `<!DOCTYPE html>
+<html>
+  <head>
+    <title>Server Error</title>
+    <style>
+      body { font-family: monospace; padding: 2rem; background: #1a1a1a; color: #ff6b6b; }
+      pre { background: #2d2d2d; padding: 1rem; border-radius: 4px; overflow-x: auto; }
+    </style>
+  </head>
+  <body>
+    <h1>500 · ubean dev server error</h1>
+    <pre>${(error instanceof Error ? `${error.message}\n\n${error.stack ?? ""}` : String(error)).replace(/[&<>]/g, (ch) => ({
+		"&": "&amp;",
+		"<": "&lt;",
+		">": "&gt;"
+	})[ch])}</pre>
+  </body>
+</html>`;
+}
+/**
+* 构造 pre / post 两个 connect 中间件。
+*
+* 需要 Vite dev server 实例：一是拿不到它就调不了 `transformIndexHtml`（客户端入口注入），
+* 二是 CSS 链接要从**客户端**环境的模块图里收集。
+*/
+function createUbeanRequestHandlers(server, options) {
+	const { skipHtmlTransform, onError } = options;
+	const handler = options.handler ?? createLazyBootstrapHandler(server, options.bootstrap);
+	async function respond(req, res) {
+		const url = req.url || "/";
+		const webReq = await toWebRequest(req, "localhost", req.socket?.encrypted ? "https" : "http");
+		const webRes = await handler(webReq, { url });
+		const contentType = webRes.headers.get("content-type") || "";
+		const skipTransform = skipHtmlTransform?.(url) ?? false;
+		const isPage = !isFrameworkHtmlPage(url);
+		if (contentType.includes("text/html") && webRes.body && !skipTransform && isPage) {
+			const html = await webRes.text();
+			const cssLinks = collectDevCssLinks(server.environments.client.moduleGraph);
+			const transformed = await server.transformIndexHtml(url, injectStylesheetLinks(html, cssLinks));
+			res.statusCode = webRes.status;
+			res.statusMessage = webRes.statusText;
+			webRes.headers.forEach((value, key) => {
+				res.setHeader(key, value);
+			});
+			res.end(transformed);
+			return;
+		}
+		await sendWebResponse(res, webRes);
+	}
+	/** 统一错误处理：SSR 栈映射回源码，响应头已发出时只能断开。 */
+	async function guard(req, res, run) {
+		try {
+			await run();
+		} catch (error) {
+			server.ssrFixStacktrace(error);
+			if (onError) onError(error, { url: req.url || "/" });
+			else server.config.logger.error(String(error instanceof Error ? error.stack : error));
+			if (!res.headersSent) {
+				res.statusCode = 500;
+				res.setHeader("Content-Type", "text/html; charset=utf-8");
+				res.end(renderErrorPage(error));
+			} else res.end();
+		}
+	}
+	const passThrough = options.passThrough ?? [];
+	const isPassThrough = (url) => {
+		const pathname = url.split("?")[0].split("#")[0];
+		return passThrough.some((prefix) => pathname.startsWith(prefix));
+	};
+	const pre = (req, res, next) => {
+		if (isPassThrough(req.url || "/") || isViteResourceRequest(req.url || "/", req.headers)) {
+			next();
+			return;
+		}
+		guard(req, res, () => respond(req, res));
+	};
+	const post = (req, res, next) => {
+		if (res.writableEnded) {
+			next();
+			return;
+		}
+		guard(req, res, () => respond(req, res));
+	};
+	return {
+		pre,
+		post
+	};
+}
+/**
+* 把请求路由注册进 Vite 插件生命周期（RM-V10 的插件形态）。
+*
+* `appType: 'custom'` 是**必须**的：默认的 `spa`/`mpa` 会在静态中间件之后挂
+* `htmlFallbackMiddleware` + `indexHtmlMiddleware`，把未知路径一律改写成 `index.html`
+* 并用 Vite 自己的 HTML 服务 —— 那样页面请求就轮不到 ubean 了。设为 `custom` 后这两层被摘掉，
+* 未匹配请求正好落到我们的 post 中间件。
+*/
+function ubeanDevRequestPlugin(options) {
+	return {
+		name: "ubean:dev-request",
+		config() {
+			return { appType: "custom" };
+		},
+		configureServer(server) {
+			const { pre, post } = createUbeanRequestHandlers(server, options);
+			if (options.devtoolsRedirect) server.middlewares.use((req, res, next) => {
+				const pathname = (req.url || "/").split("?")[0].split("#")[0];
+				if (pathname === "/_devtools" || pathname === "/_devtools/") {
+					res.statusCode = 302;
+					res.setHeader("Location", "/__devtools/");
+					res.end();
+					return;
+				}
+				next();
+			});
+			server.middlewares.use(pre);
+			return () => {
+				server.middlewares.use(post);
+			};
+		}
+	};
+}
+//#endregion
+//#region src/vue-virtual-modules.ts
+/**
+* 页面虚拟模块(`virtual:ubean-pages`)。
+*
+* 生成逻辑已沉淀到 `@ubean/vue/vite` 的 `generatePagesModuleSource`
+* (页面路由唯一所有者,与精简内核 `virtual:ubean-vue-routes` 共用同一
+* 生成器)。此处仅保留框架层的模块 ID 注册(`defineVirtualModule`)与
+* 兼容签名;route meta 相比旧版额外携带 `matchers` / `transition` /
+* `requiresAuth` / `head` / `definePage({ meta })` 透传字段(超集,
+* 使 `createMatcherGuard()` 与 SPA head guard 在框架模式下同样可用)。
+*/
+function createVuePagesVirtualModule(pages, layouts, notFoundPage, loadingPage, errorPage, localeVueParam) {
+	return defineVirtualModule("virtual:ubean-pages", () => generatePagesModuleSource({
+		pages,
+		layouts,
+		notFoundPage,
+		loadingPage,
+		errorPage
+	}, { vueParam: localeVueParam }));
+}
+const EMPTY_APP_ENTRY = {
+	shared: { exists: false },
+	server: { exists: false },
+	client: { exists: false }
+};
+function createVueAppEntryVirtualModule(appEntry = EMPTY_APP_ENTRY) {
+	return defineVirtualModule("virtual:ubean-app", () => {
+		const hasSharedApp = appEntry.shared.exists;
+		const hasServerApp = appEntry.server.exists;
+		const hasClientApp = appEntry.client.exists;
+		const hasRootApp = appEntry.root?.exists;
+		return `${`
+// Auto-generated by ubean - do not edit
+/* eslint-disable */
+${hasSharedApp ? `import _sharedApp from ${JSON.stringify(appEntry.shared.fullPath)};` : "const _sharedApp = null;"}
+${hasServerApp ? `import _serverApp from ${JSON.stringify(appEntry.server.fullPath)};` : "const _serverApp = null;"}
+${hasClientApp ? `import _clientApp from ${JSON.stringify(appEntry.client.fullPath)};` : "const _clientApp = null;"}
+${hasRootApp ? `import _rootApp from ${JSON.stringify(appEntry.root.fullPath)};` : "const _rootApp = null;"}
+
+import {
+  createUbeanClientApp,
+  createUbeanSSRApp,
+  usePage,
+  useHead,
+  useSeoMeta,
+  Link,
+  Head,
+  getInitialPageData,
+  getInitialState,
+  defineApp,
+  applyAppConfig,
+  createDefaultAppConfig,
+  createClientHead,
+  createServerHead,
+  hydrateIslands,
+  hasPendingIslands,
+  scheduleIslandHydration,
+  configureI18nRuntime
+} from 'ubean/client';
+// useRouter 由 vue-router 直源(ubean 不再透传第三方 API)
+import { useRouter } from 'vue-router';
+
+import { i18nConfig as _i18nConfig, loadLocale as _loadLocale } from 'ubean:locales';
+
+if (_i18nConfig && _i18nConfig.enabled !== false) {
+  configureI18nRuntime({
+    config: {
+      defaultLocale: _i18nConfig.defaultLocale,
+      locales: (_i18nConfig.locales || []).map(l => typeof l === 'string' ? l : l.code),
+      strategy: _i18nConfig.strategy || 'prefix_except_default',
+      fallbackLocale: _i18nConfig.fallbackLocale || _i18nConfig.defaultLocale,
+      cookieName: (_i18nConfig.detectBrowserLanguage && _i18nConfig.detectBrowserLanguage.cookieName) || 'ubean_locale',
+      baseUrl: _i18nConfig.baseUrl || '',
+      vueI18n: _i18nConfig.vueI18n
+    },
+    loadLocale: _loadLocale,
+    locales: (_i18nConfig.locales || []).map(l => typeof l === 'string' ? { code: l } : l)
+  });
+}
+
+export {
+  createUbeanClientApp,
+  createUbeanSSRApp,
+  usePage,
+  useRouter,
+  useHead,
+  useSeoMeta,
+  Link,
+  Head,
+  getInitialPageData,
+  getInitialState,
+  defineApp,
+  applyAppConfig,
+  createDefaultAppConfig
+};
+
+import {
+  routes,
+  resolvePageComponent,
+  resolveLayoutComponent,
+  defaultLayout,
+  pageNames,
+  layoutNames,
+  resolveLoadingComponent,
+  resolveErrorComponent,
+  hasNotFoundPage,
+  hasErrorPage
+} from 'virtual:ubean-pages';
+
+export {
+  routes,
+  resolvePageComponent,
+  resolveLayoutComponent,
+  defaultLayout,
+  pageNames,
+  layoutNames,
+  resolveLoadingComponent,
+  resolveErrorComponent,
+  hasNotFoundPage,
+  hasErrorPage
+};
+
+function _mergeAppConfig(base, ...configs) {
+  const result = { ...base };
+  for (const cfg of configs) {
+    if (!cfg) continue;
+    if (cfg.plugins) result.plugins = [...(result.plugins || []), ...cfg.plugins];
+    if (cfg.globalComponents) result.globalComponents = { ...(result.globalComponents || {}), ...cfg.globalComponents };
+    if (cfg.provides) result.provides = { ...(result.provides || {}), ...cfg.provides };
+    if (cfg.head) result.head = { ...(result.head || {}), ...cfg.head };
+    if (cfg.rootId) result.rootId = cfg.rootId;
+    if (cfg.rootAttrs) result.rootAttrs = { ...(result.rootAttrs || {}), ...cfg.rootAttrs };
+    if (cfg.onAppCreated) result.onAppCreated = cfg.onAppCreated;
+    if (cfg.onClientReady) result.onClientReady = cfg.onClientReady;
+    if (cfg.errorComponent) result.errorComponent = cfg.errorComponent;
+    if (cfg.loadingComponent) result.loadingComponent = cfg.loadingComponent;
+    if (cfg.appRoot) result.appRoot = cfg.appRoot;
+    if (cfg.viewTransitions !== undefined) result.viewTransitions = cfg.viewTransitions;
+    if (cfg.serializeState) result.serializeState = cfg.serializeState;
+    if (cfg.hydrateState) result.hydrateState = cfg.hydrateState;
+  }
+  // router.setup:累加语义 — shared 和 client/server 各自定义的 setup 都会执行
+  // (顺序:shared 先,client/server 后)。这样 shared 可放通用守卫(如埋点),
+  // client/server 可放环境专用守卫(如 SSR 鉴权)。
+  const setups = [];
+  for (const cfg of [base, ...configs]) {
+    if (cfg?.router?.setup) setups.push(cfg.router.setup);
+  }
+  // scrollBehavior 为函数不可合并,后者覆盖(shared 之后定义的 client/server 生效)。
+  let scrollBehavior;
+  for (const cfg of [base, ...configs]) {
+    if (cfg?.router?.scrollBehavior !== undefined) scrollBehavior = cfg.router.scrollBehavior;
+  }
+  const router = {};
+  if (setups.length > 0) {
+    router.setup = setups.length === 1 ? setups[0] : (r) => { for (const s of setups) s(r); };
+  }
+  if (scrollBehavior !== undefined) router.scrollBehavior = scrollBehavior;
+  if (setups.length > 0 || scrollBehavior !== undefined) result.router = router;
+  return result;
+}
+
+export function resolveAppConfig(mode) {
+  const base = createDefaultAppConfig();
+  // src/app.vue / src/App.vue 自动检测(小写优先)作为默认 appRoot;
+  // 显式 defineApp({ appRoot }) 在下方 merge 时按"后者覆盖"盖过它。
+  // 注入 base 而非在消费点 || _rootApp,保证走 resolveAppConfig('server')
+  // 的 dev/prod SSR(经 @ubean/client/ssr 的 createVueRenderer)与客户端
+  // resolveAppConfig('client') 读到一致的 appRoot → 水合结构不 mismatch。
+  if (_rootApp) base.appRoot = _rootApp;
+  if (!_sharedApp && !_serverApp && !_clientApp) return base;
+
+  const sharedCfg = typeof _sharedApp === 'function' ? _sharedApp() : _sharedApp;
+  const serverCfg = mode === 'server' && _serverApp ? (typeof _serverApp === 'function' ? _serverApp() : _serverApp) : null;
+  const clientCfg = mode === 'client' && _clientApp ? (typeof _clientApp === 'function' ? _clientApp() : _clientApp) : null;
+
+  const merged = _mergeAppConfig(base, sharedCfg, mode === 'server' ? serverCfg : clientCfg);
+
+  // onAppCreated: shared config is the default; server/client-specific overrides it if present.
+  if (sharedCfg?.onAppCreated) merged.onAppCreated = sharedCfg.onAppCreated;
+  if (mode === 'client' && clientCfg?.onClientReady) merged.onClientReady = clientCfg.onClientReady;
+  else if (mode === 'server' && serverCfg?.onAppCreated) merged.onAppCreated = serverCfg.onAppCreated;
+
+  return merged;
+}
+
+export async function createApp() {
+  const config = resolveAppConfig('client');
+  const head = createClientHead();
+
+  // Push global app head (from defineApp) as defaults before any page-level head.
+  if (config.head) {
+    const headInput = {};
+    if (config.head.title) headInput.title = config.head.title;
+    if (config.head.htmlAttrs) headInput.htmlAttrs = config.head.htmlAttrs;
+    if (config.head.bodyAttrs) headInput.bodyAttrs = config.head.bodyAttrs;
+    if (config.head.meta) headInput.meta = config.head.meta;
+    if (config.head.link) headInput.link = config.head.link;
+    if (config.head.script) headInput.script = config.head.script;
+    head.push(headInput);
+  }
+
+  // Resolve the auto-detected loading/error components from pages/loading.vue
+  // and pages/error.vue. These loaders return Promises (dynamic imports), so
+  // they MUST be awaited — otherwise 'resolveComp' markRaw's the unresolved
+  // Promise object and passes it to <Suspense>/<ErrorBoundary> as the
+  // 'component' prop, causing "Hydration node mismatch: server <div> vs
+  // client Symbol(v-fgt)" (rendering a Promise produces a fragment).
+  // defineApp({ loadingComponent/errorComponent }) takes priority.
+  const loadingComponent = config.loadingComponent || (await resolveLoadingComponent()) || undefined;
+  const errorComponent = config.errorComponent || (await resolveErrorComponent()) || undefined;
+
+  const initialPage = getInitialPageData();
+  const instance = createUbeanClientApp({
+    routes,
+    resolveLayoutComponent,
+    defaultLayout,
+    head,
+    viewTransitions: config.viewTransitions,
+    initialPage: initialPage || undefined,
+    hydrate: !!initialPage,
+    router: config.router,
+    loadingComponent,
+    errorComponent,
+    // appRoot 已在 resolveAppConfig 中合并(src/App.vue 默认 + defineApp 显式覆盖)
+    appRoot: config.appRoot
+  });
+
+  applyAppConfig(instance.app, config, 'client');
+
+  if (config.onAppCreated) config.onAppCreated(instance.app);
+
+  // SSR 状态水合:在 applyAppConfig(注册插件)之后、mount 之前调用。
+  // getInitialState() 从 DOM 的 __UBEAN_STATE__ script 读取服务端
+  // serializeState 产生的状态对象(如 Pinia 的 state)。
+  // 必须在 mount 前执行,否则 store 已初始化为默认值,水合无效。
+  if (config.hydrateState) {
+    const state = getInitialState();
+    config.hydrateState(instance.app, state);
+  }
+
+  const mountApp = () => {
+    instance.app.mount('#' + (config.rootId || 'app'));
+    if (config.onClientReady) {
+      config.onClientReady(instance.app);
+    }
+    // Islands: first mount always waits two rAFs so Vue's patch finishes.
+    // SPA afterEach waits one rAF, then skips the second when no pending islands.
+    var appRoot = function () {
+      return document.getElementById('app') || undefined;
+    };
+    var hydrateNow = function () {
+      hydrateIslands({ appContext: instance.app, root: appRoot() });
+    };
+    var pendingIslands = function () {
+      return hasPendingIslands(appRoot());
+    };
+    scheduleIslandHydration({
+      requestAnimationFrame: requestAnimationFrame,
+      hasPending: pendingIslands,
+      hydrate: hydrateNow,
+      forceDoubleFrame: true
+    });
+    instance.router.afterEach(function () {
+      scheduleIslandHydration({
+        requestAnimationFrame: requestAnimationFrame,
+        hasPending: pendingIslands,
+        hydrate: hydrateNow
+      });
+    });
+  };
+
+  // When hydrating SSR content, must wait for router to be ready before mounting,
+  // otherwise RouterView has no matched route and causes hydration mismatch.
+  if (initialPage) {
+    instance.router
+      .isReady()
+      .then(async function () {
+        // SSR HTML 已包含布局链;客户端水合首帧必须同样就绪(布局是异步
+        // 解析的),否则首帧渲染裸 PageView 导致 hydration mismatch。
+        await instance.preloadLayouts();
+      })
+      .then(mountApp);
+  } else {
+    mountApp();
+  }
+
+  return instance;
+}
+
+export async function createSSRApp(initialPage) {
+  const config = resolveAppConfig('server');
+  const head = createServerHead();
+
+  // SSR doesn't need Suspense fallback (server resolves async synchronously),
+  // but we still pass it for consistency. Await the loaders so resolved
+  // Component values (not Promises) are passed to createUbeanSSRApp.
+  const loadingComponent = config.loadingComponent || (await resolveLoadingComponent()) || undefined;
+
+  const errorComponent = config.errorComponent || (await resolveErrorComponent()) || undefined;
+
+  const { app, router } = createUbeanSSRApp(initialPage, {
+    routes,
+    resolveLayoutComponent,
+    defaultLayout,
+    head,
+    router: config.router,
+    loadingComponent,
+    errorComponent,
+    // appRoot 已在 resolveAppConfig 中合并(src/App.vue 默认 + defineApp 显式覆盖),
+    // 客户端水合同理会从 resolveAppConfig('client') 读到一致的值。
+    appRoot: config.appRoot
+  });
+
+  applyAppConfig(app, config, 'server');
+
+  if (config.onAppCreated) config.onAppCreated(app);
+
+  return { app, router, head, config };
+}
+
+export const rootId = 'app';
+`.trim()}\n`;
+	});
+}
+function createClientEntryVirtualModule() {
+	return defineVirtualModule("virtual:ubean-client-entry", () => {
+		return `${`
+// Auto-generated by ubean client entry - do not edit
+/* eslint-disable */
+${getCssImports().map((css) => `import ${JSON.stringify(css)};`).join("\n")}
+import { createApp } from 'virtual:ubean-app';
+
+createApp();
+`.trim()}\n`;
+	});
+}
+const EMPTY_SERVER_ENTRY = {
+	shared: { exists: false },
+	dev: { exists: false },
+	prod: { exists: false }
+};
+function createServerEntryVirtualModule(serverEntry = EMPTY_SERVER_ENTRY) {
+	return defineVirtualModule("virtual:ubean-server", () => {
+		const hasShared = serverEntry.shared.exists;
+		const hasDev = serverEntry.dev.exists;
+		const hasProd = serverEntry.prod.exists;
+		return `${`
+// Auto-generated by ubean server entry - do not edit
+/* eslint-disable */
+${hasShared ? `import _sharedServer from ${JSON.stringify(serverEntry.shared.fullPath)};` : "const _sharedServer = null;"}
+${hasDev ? `import _devServer from ${JSON.stringify(serverEntry.dev.fullPath)};` : "const _devServer = null;"}
+${hasProd ? `import _prodServer from ${JSON.stringify(serverEntry.prod.fullPath)};` : "const _prodServer = null;"}
+
+import {
+  defineServer,
+  createDefaultServerConfig,
+  mergeServerConfigs
+} from 'ubean/server';
+
+export {
+  defineServer,
+  createDefaultServerConfig,
+  mergeServerConfigs
+};
+
+/**
+ * Resolve the user's server config for the given mode ('dev' | 'prod').
+ * Merges shared config with mode-specific config. Returns an empty
+ * config when no server entry file exists.
+ */
+export function resolveServerConfig(mode) {
+  const base = createDefaultServerConfig();
+
+  if (!_sharedServer && !_devServer && !_prodServer) return base;
+
+  const sharedCfg = typeof _sharedServer === 'function' ? _sharedServer() : _sharedServer;
+  const modeCfg = mode === 'dev'
+    ? (typeof _devServer === 'function' ? _devServer() : _devServer)
+    : (typeof _prodServer === 'function' ? _prodServer() : _prodServer);
+
+  return mergeServerConfigs(base, sharedCfg, modeCfg);
+}
+`.trim()}\n`;
+	});
+}
+//#endregion
+//#region src/vue-plugin.ts
+const VUE_PLUGIN_INCLUDE = [/\.vue$/, /\.md$/];
+const VIRTUAL_PAGES = "virtual:ubean-pages";
+const VIRTUAL_APP = "virtual:ubean-app";
+const VIRTUAL_CLIENT = "virtual:ubean-client-entry";
+const VIRTUAL_SERVER = "virtual:ubean-server";
+const CLIENT_ENTRY_URL = `/@id/${VIRTUAL_CLIENT}`;
+const TS_VIRTUAL_IDS = [
+	VIRTUAL_PAGES,
+	VIRTUAL_APP,
+	VIRTUAL_SERVER
+];
+const VIRTUAL_IDS = [
+	VIRTUAL_PAGES,
+	VIRTUAL_APP,
+	VIRTUAL_CLIENT,
+	VIRTUAL_SERVER
+];
+const HASH_ID_TO_VIRTUAL = {
+	"#ubean-pages": VIRTUAL_PAGES,
+	"#ubean-app": VIRTUAL_APP,
+	"#ubean-client-entry": VIRTUAL_CLIENT,
+	"#ubean-server": VIRTUAL_SERVER
+};
+const NULL_PREFIX = "\0";
+const VIRTUAL_EXT = ".ts";
+function toResolvedVirtualId(virtualId) {
+	return NULL_PREFIX + virtualId + VIRTUAL_EXT;
+}
+function parseResolvedVirtualId(resolvedId) {
+	if (!resolvedId.startsWith(NULL_PREFIX)) return void 0;
+	const withoutPrefix = resolvedId.slice(1);
+	if (!withoutPrefix.endsWith(VIRTUAL_EXT)) return void 0;
+	const virtualId = withoutPrefix.slice(0, -3);
+	return VIRTUAL_IDS.includes(virtualId) ? virtualId : void 0;
+}
+function localeVueParamFromConfig(config) {
+	if (config.i18n?.enabled === false) return void 0;
+	const codes = (config.i18n?.locales || []).map((l) => l.code);
+	if (codes.length === 0) return void 0;
+	return getVueLocaleParam({
+		defaultLocale: config.i18n.defaultLocale,
+		locales: codes,
+		strategy: config.i18n.strategy
+	}) || void 0;
+}
+function ubeanVite(options) {
+	const { config: ubeanConfig } = options;
+	const virtualRegistry = options.registry ?? createVirtualRegistry();
+	const srcDir = resolve(ubeanConfig.rootDir, ubeanConfig.srcDir);
+	const dtsDir = join(ubeanConfig.rootDir, ".ubean");
+	const markdownEnabled = ubeanConfig.markdown?.enabled !== false;
+	const mdxEnabled = ubeanConfig.markdown?.mdx === true;
+	const autoImports = resolveAutoImportsConfig(ubeanConfig.autoImports);
+	const componentsAutoImport = resolveComponentsConfig(ubeanConfig.components);
+	const markdownComponentsAutoImport = ubeanConfig.markdown?.components?.autoImport !== false;
+	const composablesDirName = ubeanConfig.dir.composables || "composables";
+	const componentsDirName = ubeanConfig.dir.components || "components";
+	const composablesDirs = [join(srcDir, composablesDirName), ...autoImports.options.dirs ?? []];
+	const componentsDirs = [join(srcDir, componentsDirName), ...componentsAutoImport.options.dirs ?? []];
+	const mdExtensions = mdxEnabled ? ["md", "mdx"] : ["md"];
+	function getVirtualModule(virtualId) {
+		return virtualRegistry.getModules().find((m) => m.id === virtualId);
+	}
+	async function loadVirtualModule(virtualId) {
+		const mod = getVirtualModule(virtualId);
+		if (!mod) return void 0;
+		return mod.load();
+	}
+	function scanProjectOnce() {
+		return scanProject({
+			cwd: ubeanConfig.rootDir,
+			srcDir: ubeanConfig.srcDir,
+			dirs: ubeanConfig.dir,
+			ignore: ubeanConfig.scanOptions?.ignore
+		});
+	}
+	async function scanAndRegister() {
+		applyScan(await scanProjectOnce());
+	}
+	/**
+	* 依据扫描结果重建本插件的虚拟模块。
+	*
+	* 与扫描分离（RM-V13）：dev 下扫描由 `dev-scan.ts` 的协调器统一触发一次，core / vue / CLI
+	* 三个订阅者各取所需；`buildStart` 与构建期则继续走 `scanAndRegister()`。
+	*/
+	function applyScan(result) {
+		virtualRegistry.register(createVuePagesVirtualModule(result.pages, result.layouts, result.notFoundPage, result.loadingPage, result.errorPage, localeVueParamFromConfig(ubeanConfig)));
+		virtualRegistry.register(createVueAppEntryVirtualModule(result.appEntry));
+		virtualRegistry.register(createServerEntryVirtualModule(result.serverEntry));
+		virtualRegistry.register(createClientEntryVirtualModule());
+	}
+	const HASH_IDS = Object.keys(HASH_ID_TO_VIRTUAL);
+	const plugins = [{
+		name: "ubean:vue",
+		enforce: "pre",
+		async buildStart() {
+			await scanAndRegister();
+		},
+		resolveId(id, importer, opts) {
+			if (HASH_ID_TO_VIRTUAL[id]) return toResolvedVirtualId(HASH_ID_TO_VIRTUAL[id]);
+			if (VIRTUAL_IDS.includes(id)) return toResolvedVirtualId(id);
+			if (id === "@ubean/i18n" && !opts?.ssr) return this.resolve("@ubean/i18n/browser", importer, {
+				skipSelf: true,
+				...opts
+			});
+		},
+		async load(id) {
+			const virtualId = parseResolvedVirtualId(id);
+			if (virtualId) {
+				let code = await loadVirtualModule(virtualId);
+				if (code && TS_VIRTUAL_IDS.includes(virtualId)) code = (await transformWithOxc(code, `${virtualId}.ts`)).code;
+				return code;
+			}
+		},
+		config() {
+			const require = createRequire(import.meta.url);
+			let vueI18nEntry = "vue-i18n";
+			let intlifyCoreEntry = "@intlify/core";
+			let intlifyBaseEntry = "@intlify/core-base";
+			try {
+				vueI18nEntry = require.resolve("vue-i18n/dist/vue-i18n.esm-bundler.js");
+			} catch {
+				try {
+					vueI18nEntry = require.resolve("vue-i18n");
+				} catch {}
+			}
+			try {
+				intlifyCoreEntry = require.resolve("@intlify/core/dist/core.node.mjs");
+			} catch {}
+			try {
+				intlifyBaseEntry = require.resolve("@intlify/core-base/dist/core-base.mjs");
+			} catch {}
+			const singleton = ssrSingletonDevPolicy();
+			return {
+				appType: "custom",
+				resolve: {
+					...singleton.resolve,
+					alias: {
+						"vue-i18n": vueI18nEntry,
+						"@intlify/core": intlifyCoreEntry,
+						"@intlify/core-base": intlifyBaseEntry
+					}
+				},
+				optimizeDeps: {
+					exclude: [
+						...singleton.optimizeDeps.exclude,
+						...VIRTUAL_IDS,
+						...HASH_IDS
+					],
+					include: singleton.optimizeDeps.include
+				},
+				ssr: singleton.ssr
+			};
+		},
+		transformIndexHtml(html, ctx) {
+			if (ctx?.path && isFrameworkHtmlPage(ctx.path)) return html;
+			let result = html;
+			const colorModeConfig = ubeanConfig.colorMode;
+			if (colorModeConfig !== false) {
+				const script = getColorModeScript(resolveColorModeConfig(colorModeConfig));
+				result = result.replace("<head>", `<head>\n    ${script}`);
+			}
+			const partyTownConfig = ubeanConfig.partyTown;
+			if (partyTownConfig !== false && partyTownConfig !== void 0) {
+				const resolved = resolvePartyTownConfig(partyTownConfig === true ? { enabled: true } : partyTownConfig);
+				if (resolved.enabled) {
+					const script = getPartyTownScript(resolved);
+					if (script) result = result.replace("</head>", `    ${script}\n</head>`);
+				}
+			}
+			if (!/<link\b[^>]*rel=["']icon["']/i.test(result)) {
+				const faviconLink = renderFaviconLink(ubeanConfig.favicon ?? void 0);
+				if (faviconLink) result = result.replace("<head>", `<head>\n    ${faviconLink}`);
+			}
+			if (result.includes(CLIENT_ENTRY_URL) || result.includes(VIRTUAL_CLIENT)) return result;
+			return result.replace("</body>", `  <script type="module" src="${CLIENT_ENTRY_URL}"><\/script>\n</body>`);
+		},
+		configureServer(server) {
+			getDevScanCoordinator(server, (source) => ({
+				rootDir: ubeanConfig.rootDir,
+				srcDir: ubeanConfig.srcDir,
+				dirs: ubeanConfig.dir,
+				ignore: ubeanConfig.scanOptions?.ignore,
+				source,
+				scan: scanProjectOnce,
+				reload: () => server.ws.send({ type: "full-reload" })
+			})).subscribe((result) => {
+				applyScan(result);
+				for (const vid of VIRTUAL_IDS) {
+					const mod = server.moduleGraph.getModuleById(toResolvedVirtualId(vid));
+					if (mod) server.moduleGraph.invalidateModule(mod);
+				}
+			});
+		}
+	}];
+	if (options.vue !== false) plugins.unshift(vue({
+		include: VUE_PLUGIN_INCLUDE,
+		template: { compilerOptions: { isCustomElement: (tag) => tag.startsWith("ubean-") } }
+	}));
+	if (ubeanConfig.i18n?.enabled !== false) plugins.push(VueI18nPlugin({
+		include: [join(srcDir, "locales/**")],
+		ssr: true,
+		compositionOnly: true,
+		runtimeOnly: false
+	}));
+	if (markdownEnabled) {
+		const markdownOptions = {
+			...ubeanConfig.markdown?.markdownExit,
+			html: true
+		};
+		plugins.push(Markdown({
+			markdownOptions,
+			wrapperClasses: ubeanConfig.markdown?.wrapperClass ?? "markdown-body",
+			headEnabled: true,
+			headField: "head"
+		}));
+	}
+	if (mdxEnabled) plugins.push(ubeanMdxPlugin({
+		remarkPlugins: ubeanConfig.markdown?.remarkPlugins || [],
+		rehypePlugins: ubeanConfig.markdown?.rehypePlugins || []
+	}));
+	if (autoImports.enabled) {
+		const userAutoImports = autoImports.options;
+		plugins.push(AutoImport({
+			vueTemplate: true,
+			eslintrc: { enabled: false },
+			...userAutoImports,
+			imports: [...getAutoImportPresets(autoImports), ...toArray(userAutoImports.imports)],
+			dirs: composablesDirs,
+			dts: userAutoImports.dts === void 0 ? join(dtsDir, "auto-imports.d.ts") : userAutoImports.dts
+		}));
+	}
+	const UBEAN_BUILTIN_COMPONENTS = [
+		"Link",
+		"Head",
+		"PageView",
+		"ClientOnly"
+	];
+	function ubeanComponentsResolver(componentName) {
+		if (UBEAN_BUILTIN_COMPONENTS.includes(componentName)) return {
+			name: componentName,
+			from: "ubean/client"
+		};
+	}
+	const dynamicResolvers = [...componentsAutoImport.ubean ? [ubeanComponentsResolver] : [], (name) => {
+		for (const resolver of getComponentResolvers()) {
+			const result = typeof resolver === "function" ? resolver(name) : resolver.resolve(name);
+			if (result) return result;
+		}
+	}];
+	if (componentsAutoImport.enabled) {
+		const userComponents = componentsAutoImport.options;
+		const extensions = ["vue"];
+		const includePatterns = [/\.vue$/, /\.vue\?vue/];
+		if (markdownEnabled && markdownComponentsAutoImport) {
+			extensions.push(...mdExtensions);
+			includePatterns.push(/\.md$/);
+			if (mdxEnabled) includePatterns.push(/\.mdx$/);
+		}
+		plugins.push(Components({
+			deep: true,
+			...userComponents,
+			dirs: componentsDirs,
+			extensions,
+			include: includePatterns,
+			dts: userComponents.dts === void 0 ? join(dtsDir, "components.d.ts") : userComponents.dts,
+			resolvers: [...dynamicResolvers, ...toArray(userComponents.resolvers)]
+		}));
+	} else plugins.push(Components({
+		dts: true,
+		resolvers: dynamicResolvers
+	}));
+	const searchConfig = ubeanConfig.search;
+	if (searchConfig !== false && searchConfig !== void 0) plugins.push({
+		name: "ubean:pagefind",
+		apply: "build",
+		closeBundle() {
+			return runPagefindIndexing(ubeanConfig, searchConfig);
+		}
+	});
+	return plugins;
+}
+/**
+* P9-26: Run the Pagefind CLI to index built HTML files.
+*
+* Spawns `npx pagefind --site <dir>` after the build. If the `pagefind`
+* package is not installed, prints a helpful warning instead of failing.
+*/
+async function runPagefindIndexing(ubeanConfig, searchConfig) {
+	const { spawn } = await import("node:child_process");
+	const { resolve: resolvePath } = await import("node:path");
+	const isObjectConfig = typeof searchConfig === "object";
+	if (!(isObjectConfig ? searchConfig.enabled !== false : true)) return;
+	const outDir = isObjectConfig && searchConfig.site ? searchConfig.site : "dist";
+	const indexPath = isObjectConfig && searchConfig.indexPath ? searchConfig.indexPath : "pagefind";
+	const verbose = isObjectConfig && searchConfig.verbose === true;
+	const args = [
+		"pagefind",
+		"--site",
+		resolvePath(ubeanConfig.rootDir, outDir),
+		"--output-subdir",
+		indexPath
+	];
+	if (isObjectConfig && searchConfig.glob) args.push("--glob", searchConfig.glob);
+	if (isObjectConfig && searchConfig.excludeSelectors) for (const selector of searchConfig.excludeSelectors) args.push("--exclude-selectors", selector);
+	if (verbose) args.push("--verbose");
+	return new Promise((resolvePromise) => {
+		const child = spawn("npx", args, {
+			stdio: "inherit",
+			cwd: ubeanConfig.rootDir,
+			shell: true
+		});
+		child.on("error", (err) => {
+			if (err.code === "ENOENT" || /not found/i.test(err.message)) console.warn("[ubean:pagefind] Pagefind CLI not found. Install it with `pnpm add -D pagefind` to enable full-text search.");
+			else console.error("[ubean:pagefind] Failed to run Pagefind:", err.message);
+			resolvePromise();
+		});
+		child.on("exit", (code) => {
+			if (code === 0) console.log("[ubean:pagefind] Search index generated successfully.");
+			else console.warn(`[ubean:pagefind] Pagefind exited with code ${code}. Search index may be incomplete.`);
+			resolvePromise();
+		});
+	});
+}
+//#endregion
+export { buildDevSsrRoutes as C, getDevScanCoordinator as D, createDevScanCoordinator as E, onDevScan as O, enhanceDevApp as S, DEV_SCAN_DIRS as T, bootstrapDevApp as _, createVueAppEntryVirtualModule as a, resolveDevSecurityHeaders as b, collectDevCssLinks as c, injectStylesheetLinks as d, isFrameworkHtmlPage as f, toWebRequest as g, sendWebResponse as h, createServerEntryVirtualModule as i, peekDevScanCoordinator as k, createUbeanRequestHandlers as l, ubeanDevRequestPlugin as m, ubeanVite as n, createVuePagesVirtualModule as o, isViteResourceRequest as p, createClientEntryVirtualModule as r, DEVTOOLS_PASS_THROUGH_PREFIXES as s, VUE_PLUGIN_INCLUDE as t, getDevApp as u, createDevApp as v, toVueRouterPagePath as w, resolveLocaleVueParam as x, createDevAppReady as y };