@ubean/routes 0.2.0

package/dist/index.js

@@ -0,0 +1,1128 @@
+import { addRoute, createRouter, findRoute } from "rou3";
+import { validateParams } from "@ubean/scan";
+import { isServerAction, matchAnyGlob } from "@ubean/shared";
+import { parseFormActionName, runAction } from "@ubean/actions";
+import { openAPIRouteHandler } from "hono-openapi";
+//#region src/handler.ts
+function isResponse(value) {
+	return value instanceof Response;
+}
+function convertReturnValue(value) {
+	if (isResponse(value)) return value;
+	if (typeof value === "string") return new Response(value, { headers: { "Content-Type": "text/plain; charset=utf-8" } });
+	return new Response(JSON.stringify(value), { headers: { "Content-Type": "application/json; charset=utf-8" } });
+}
+function isMetaHandler(h) {
+	return typeof h === "function" && h.__brand === "meta";
+}
+function defineHandler(...handlers) {
+	if (handlers.length === 0) throw new Error("defineHandler requires at least one handler");
+	const metaList = [];
+	const middlewares = [];
+	const finalHandler = handlers[handlers.length - 1];
+	for (let i = 0; i < handlers.length - 1; i++) {
+		const h = handlers[i];
+		if (isMetaHandler(h)) metaList.push(h.meta);
+		else middlewares.push(h);
+	}
+	const routeMeta = Object.assign({ requiresAuth: true }, ...metaList);
+	const wrappedFinal = async (c) => {
+		return convertReturnValue(await finalHandler(c, async () => {}));
+	};
+	const allHandlers = [...middlewares, wrappedFinal];
+	Object.defineProperty(allHandlers, "__routeMeta", {
+		value: routeMeta,
+		enumerable: false,
+		configurable: false
+	});
+	return allHandlers;
+}
+function isHandlerChain(obj) {
+	return Array.isArray(obj) && obj.__routeMeta !== void 0;
+}
+function extractRouteMeta(handlers) {
+	return handlers.__routeMeta ?? { requiresAuth: true };
+}
+function defineHandlerMeta(meta) {
+	const fn = async (_c, next) => next();
+	Object.assign(fn, {
+		__brand: "meta",
+		meta
+	});
+	return fn;
+}
+function defineMiddleware(handler) {
+	return handler;
+}
+//#endregion
+//#region src/server-router.ts
+var UbeanRouter = class {
+	apiContext;
+	middlewares;
+	pages;
+	layouts;
+	constructor() {
+		this.apiContext = createRouter();
+		this.middlewares = [];
+		this.pages = /* @__PURE__ */ new Map();
+		this.layouts = /* @__PURE__ */ new Map();
+	}
+	addApiRoute(route) {
+		const data = {
+			method: route.method?.toUpperCase() || "ALL",
+			path: route.route,
+			id: `${route.method}:${route.route}`,
+			filePath: route.fullPath
+		};
+		addRoute(this.apiContext, data.method, route.route, data);
+	}
+	addMiddleware(mw) {
+		this.middlewares.push({
+			path: "/**",
+			filePath: mw.fullPath,
+			order: mw.order,
+			global: mw.global
+		});
+		this.middlewares.sort((a, b) => a.order - b.order);
+	}
+	addPage(page) {
+		this.pages.set(page.name, {
+			name: page.name,
+			path: page.route,
+			filePath: page.fullPath,
+			layout: page.layout,
+			reuseTarget: page.reuseTarget
+		});
+	}
+	addLayout(layout) {
+		this.layouts.set(layout.name, {
+			name: layout.name,
+			filePath: layout.fullPath,
+			isDefault: layout.isDefault
+		});
+	}
+	matchApi(method, path) {
+		return findRoute(this.apiContext, method.toUpperCase(), path)?.data;
+	}
+	getMiddlewares() {
+		return [...this.middlewares];
+	}
+	getPages() {
+		return [...this.pages.values()];
+	}
+	getPage(name) {
+		return this.pages.get(name);
+	}
+	getLayout(name) {
+		return this.layouts.get(name);
+	}
+	getDefaultLayout() {
+		return [...this.layouts.values()].find((l) => l.isDefault);
+	}
+	getLayouts() {
+		return [...this.layouts.values()];
+	}
+	getPageRouteNames() {
+		return [...this.pages.keys()];
+	}
+};
+let _router = null;
+function useRouter() {
+	if (!_router) _router = new UbeanRouter();
+	return _router;
+}
+/**
+* 创建服务端 rou3 router 实例(无参数)。
+*
+* 命名说明:与 `@ubean/client` 的 `createUbeanRouter`(Vue Router 工厂,
+* 接受 options)曾是同名冲突,服务端版本改名 `createServerRouter` 彻底消歧。
+*/
+function createServerRouter() {
+	_router = new UbeanRouter();
+	return _router;
+}
+//#endregion
+//#region src/bot-detection.ts
+const BOT_PATTERN = new RegExp([
+	"googlebot",
+	"bingbot",
+	"baiduspider",
+	"yandexbot",
+	"duckduckbot",
+	"slurp",
+	"sogou",
+	"exabot",
+	"facebot",
+	"ia_archiver",
+	"applebot",
+	"bytespider",
+	"petalbot",
+	"facebookexternalhit",
+	"twitterbot",
+	"linkedinbot",
+	"slacker",
+	"slackbot",
+	"telegrambot",
+	"whatsapp",
+	"skypeuripreview",
+	"discordbot",
+	"pinterestbot",
+	"redditbot",
+	"crawler",
+	"spider",
+	"bot/",
+	"bot;",
+	"preview",
+	"fetcher",
+	"scraper",
+	"ahrefsbot",
+	"semrushbot",
+	"mj12bot",
+	"dotbot",
+	"pingdom",
+	"gtmetrix",
+	"pagespeed",
+	"googlestackdrivermonitoring"
+].map((t) => t.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|"), "i");
+/**
+* 判断 User-Agent 是否为爬虫/社交预览机器人。
+*
+* @param ua User-Agent 字符串(来自 `c.req.header('user-agent')`)
+* @returns `true` 表示疑似爬虫,应降级为缓冲渲染以保证 metadata 完整
+*/
+function isBotUserAgent(ua) {
+	if (!ua) return false;
+	return BOT_PATTERN.test(ua);
+}
+//#endregion
+//#region src/page-actions.ts
+/**
+* Shared redirect/non-redirect Response handling for both the legacy
+* `mod.action(c)` path and the `mod.actions` map path.
+*
+* Returns a `Response` to return to the client, or `null` to fall through
+* (caller leaves `actionResult` as the Response for downstream handling).
+*/
+function handleActionResponse(c, response, isPagesReq) {
+	if (response.status >= 300 && response.status < 400) {
+		const redirectUrl = response.headers.get("Location");
+		if (redirectUrl) {
+			if (isPagesReq(c)) return c.json({ redirect: redirectUrl }, {
+				status: 200,
+				headers: { "X-Ubean-Redirect": redirectUrl }
+			});
+			return response;
+		}
+	}
+	if (isPagesReq(c)) return response;
+	return null;
+}
+/**
+* Run a `ServerAction` (from a page module's `actions` map) against the
+* current Hono context via `runAction` from `@ubean/actions`.
+*
+* Returns one of:
+*  - `{ response }` — handler returned/threw a `Response` (redirect)
+*  - `{ errors }` — validation failure, `fail()` from the handler, or a
+*    thrown error (mapped to `{ _error: message }`)
+*  - `{ data }` — successful return value (merged into page props)
+*/
+async function runServerAction(action, c) {
+	const result = await runAction(action, c);
+	if (result.response) return { response: result.response };
+	if (result.errors) return { errors: result.errors ?? {} };
+	if (result.error) return { errors: { _error: result.error.message } };
+	return { data: result.data };
+}
+//#endregion
+//#region src/route-rules.ts
+function compileRulePath(pattern) {
+	const DOUBLE = "__DWC__";
+	const SINGLE = "__SWC__";
+	let s = pattern;
+	s = s.replace(/\/\*\*/g, `/${DOUBLE}`);
+	s = s.replace(/\*/g, SINGLE);
+	s = s.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+	s = s.replace(new RegExp(SINGLE, "g"), "[^/]*");
+	s = s.replace(new RegExp(`/${DOUBLE}`, "g"), "(?:/.*)?");
+	return new RegExp(`^${s}$`);
+}
+/**
+* 排序权重计算:提升更"具体"的规则优先匹配。
+*
+* P9-03 引入 `ssr`/`prerender`/`isr` 字段后,具体路径(如 `/admin/*`)应优先于
+* 通配路径(如 `/**`)被匹配,以便 per-route 字段优先级正确。
+*
+* P9-04 扩展:`ppr` 字段同样参与 specificity 计算。
+*/
+function ruleSpecificity(rule) {
+	return (rule.redirect ? 3 : 0) + (rule.rewrite ? 2 : 0) + (rule.headers ? 1 : 0) + (rule.ssr !== void 0 ? 1 : 0) + (rule.isr !== void 0 ? 1 : 0) + (rule.prerender !== void 0 ? 1 : 0) + (rule.ppr !== void 0 ? 1 : 0);
+}
+/**
+* 路径特异性计算:作为 rule specificity 的 tiebreaker。
+*
+* - 字面段越多越具体(`/a/b/c` > `/a/b` > `/a`)
+* - 通配符降低特异性(`**` 比 `*` 更不具体)
+* - 用于在 rule specificity 相同时,让更具体的路径优先匹配
+*   (如 `/admin/profile` 优先于 `/admin/**`)
+*/
+function pathSpecificity(pattern) {
+	const segments = pattern.split("/").filter((s) => s.length > 0);
+	let score = 0;
+	for (const seg of segments) if (seg === "**") score -= 10;
+	else if (seg.includes("*")) score -= 1;
+	else score += 1;
+	return score;
+}
+function compileRouteRules(rules) {
+	return Object.entries(rules).map(([path, rule]) => ({
+		path,
+		pattern: compileRulePath(path),
+		rule
+	})).sort((a, b) => {
+		const ruleDiff = ruleSpecificity(b.rule) - ruleSpecificity(a.rule);
+		if (ruleDiff !== 0) return ruleDiff;
+		return pathSpecificity(b.path) - pathSpecificity(a.path);
+	});
+}
+/**
+* 规范化 `isr` 字段为 `IsrRule` 对象形式。
+* `number` → `{ ttl: n }`,`undefined` → `undefined`。
+*/
+function normalizeIsrRule(isr) {
+	if (isr === void 0) return void 0;
+	if (typeof isr === "number") return { ttl: isr };
+	return isr;
+}
+function matchRouteRules(path, compiledRules) {
+	const matched = {};
+	for (const { pattern, rule } of compiledRules) if (pattern.test(path)) {
+		if (rule.headers) matched.headers = {
+			...matched.headers,
+			...rule.headers
+		};
+		if (rule.redirect && !matched.redirect) matched.redirect = rule.redirect;
+		if (rule.rewrite && !matched.rewrite) matched.rewrite = rule.rewrite;
+		if (rule.cache) matched.cache = {
+			...matched.cache,
+			...rule.cache
+		};
+		if (rule.ssr !== void 0 && matched.ssr === void 0) matched.ssr = rule.ssr;
+		if (rule.prerender !== void 0 && matched.prerender === void 0) matched.prerender = rule.prerender;
+		if (rule.isr !== void 0 && matched.isr === void 0) matched.isr = rule.isr;
+		if (rule.ppr !== void 0 && matched.ppr === void 0) matched.ppr = rule.ppr;
+	}
+	return matched;
+}
+function resolveRedirectUrl(redirect, currentPath) {
+	if (typeof redirect === "string") return {
+		url: redirect,
+		statusCode: 307
+	};
+	let url = redirect.to;
+	if (url.startsWith("./") || url.startsWith("../")) {
+		const base = currentPath.replace(/\/[^/]*$/, "/");
+		url = new URL(url, `http://localhost${base}`).pathname;
+	}
+	return {
+		url,
+		statusCode: redirect.statusCode || 307
+	};
+}
+function buildCacheControlHeader(cache) {
+	if (!cache) return null;
+	const parts = [];
+	if (cache.ttl !== void 0) {
+		parts.push(`public, max-age=${cache.ttl}`);
+		if (cache.swr) parts.push(`stale-while-revalidate=${cache.ttl}`);
+	}
+	return parts.length > 0 ? parts.join(", ") : null;
+}
+function createRouteRulesMiddleware(rules) {
+	const compiled = compileRouteRules(rules);
+	return async function routeRulesMiddleware(c, next) {
+		const path = c.req.path;
+		const matched = matchRouteRules(path, compiled);
+		if (Object.keys(matched).length > 0) c.set("routeRule", matched);
+		if (Object.keys(matched).length === 0) {
+			await next();
+			return;
+		}
+		if (matched.redirect) {
+			const { url, statusCode } = resolveRedirectUrl(matched.redirect, path);
+			return c.redirect(url, statusCode);
+		}
+		if (matched.headers) for (const [key, value] of Object.entries(matched.headers)) c.header(key, value);
+		const cacheHeader = buildCacheControlHeader(matched.cache);
+		if (cacheHeader) c.header("Cache-Control", cacheHeader);
+		await next();
+	};
+}
+//#endregion
+//#region src/isr.ts
+const ISR_KEY_PREFIX = "isr:";
+const REVALIDATING = /* @__PURE__ */ new Set();
+function buildIsrCacheKey(pathname) {
+	return `${ISR_KEY_PREFIX}${pathname}`;
+}
+/**
+* 读取缓存的 ISR entry(仅未过期)。
+*/
+async function getIsrCache(store, pathname) {
+	const key = buildIsrCacheKey(pathname);
+	const entry = await store.get(key);
+	if (!entry) return void 0;
+	return {
+		html: new TextDecoder().decode(entry.body),
+		status: entry.status,
+		headers: entry.headers
+	};
+}
+/**
+* 读取缓存的 ISR entry(即使已过期,用于 SWR)。
+* 后端不支持 `peek` 时退化为 `get`(无 SWR)。
+*/
+async function getStaleIsrCache(store, pathname) {
+	if (!store.peek) return getIsrCache(store, pathname);
+	const key = buildIsrCacheKey(pathname);
+	const entry = await store.peek(key);
+	if (!entry) return void 0;
+	return {
+		html: new TextDecoder().decode(entry.body),
+		status: entry.status,
+		headers: entry.headers
+	};
+}
+/**
+* 写入 ISR 缓存。
+*/
+async function setIsrCache(store, pathname, entry, ttl) {
+	const key = buildIsrCacheKey(pathname);
+	const body = new TextEncoder().encode(entry.html).buffer;
+	await store.set(key, {
+		body,
+		headers: entry.headers,
+		status: entry.status,
+		statusText: ""
+	}, ttl);
+}
+/**
+* 失效指定路径的 ISR 缓存。需要调用方提供 store(避免本包依赖全局单例)。
+*/
+async function invalidateIsrCache(store, pathname) {
+	return store.delete(buildIsrCacheKey(pathname));
+}
+/**
+* 失效所有匹配模式的 ISR 缓存。仅对内存存储有效(读取底层 Map)。
+*/
+async function invalidateIsrCachePattern(store, pattern) {
+	const memStore = store;
+	if (!memStore.store) return 0;
+	let count = 0;
+	for (const k of Array.from(memStore.store.keys())) {
+		if (!k.startsWith(ISR_KEY_PREFIX)) continue;
+		const path = k.slice(4);
+		if (pattern.test(path)) {
+			await store.delete(k);
+			count++;
+		}
+	}
+	return count;
+}
+/**
+* 判断 entry 是否已过期。配合 `getStaleIsrCache` 用于 SWR 判定。
+* 仅内存存储可用 —— 其他后端在 `getStaleIsrCache` 已退化为 `get`(永远 fresh),
+* 不会进入此分支。
+*/
+function isIsrEntryStale(pathname, store) {
+	const memStore = store;
+	if (!memStore.store) return false;
+	const entry = memStore.store.get(buildIsrCacheKey(pathname));
+	if (!entry?.expiresAt) return false;
+	return Date.now() > entry.expiresAt;
+}
+/**
+* ISR 主入口:检查缓存 → 命中则返回,未命中/过期则调用 render 重新生成。
+*
+* 返回 `Response` 表示 ISR 处理完成(直接返回给客户端),
+* 返回 `undefined` 表示无 ISR 规则或调用方应自行处理(由 `serveIsr` 内部逻辑决定)。
+*
+* 实现说明:使用 `peek`(若可用)而非 `get` 来读取缓存,避免 `get` 在
+* 过期时删除 entry 导致 SWR 无法读取旧内容。后端不支持 `peek` 时退化为 `get`
+* (SWR 自动降级为同步重新生成)。
+*/
+async function serveIsr(_c, options) {
+	const store = options.store;
+	const { pathname, rule, render } = options;
+	const key = buildIsrCacheKey(pathname);
+	const rawEntry = store.peek ? await store.peek(key) : await store.get(key);
+	if (rawEntry) {
+		const isStale = Date.now() > rawEntry.expiresAt;
+		const html = new TextDecoder().decode(rawEntry.body);
+		if (!isStale) {
+			const headers = new Headers(rawEntry.headers);
+			headers.set("X-ISR", "HIT");
+			return new Response(html, {
+				status: rawEntry.status,
+				headers
+			});
+		}
+		if (rule.swr) {
+			const revalKey = key;
+			if (!REVALIDATING.has(revalKey)) {
+				REVALIDATING.add(revalKey);
+				render().then(async (result) => {
+					await setIsrCache(store, pathname, {
+						html: result.html,
+						status: result.status ?? 200,
+						headers: result.headers ?? { "Content-Type": "text/html; charset=utf-8" }
+					}, rule.ttl);
+				}).catch(() => {}).finally(() => {
+					REVALIDATING.delete(revalKey);
+				});
+			}
+			const headers = new Headers(rawEntry.headers);
+			headers.set("X-ISR", "STALE");
+			return new Response(html, {
+				status: rawEntry.status,
+				headers
+			});
+		}
+	}
+	const result = await render();
+	const status = result.status ?? 200;
+	const headers = result.headers ?? { "Content-Type": "text/html; charset=utf-8" };
+	if (status >= 200 && status < 300) await setIsrCache(store, pathname, {
+		html: result.html,
+		status,
+		headers
+	}, rule.ttl);
+	const respHeaders = new Headers(headers);
+	respHeaders.set("X-ISR", "MISS");
+	return new Response(result.html, {
+		status,
+		headers: respHeaders
+	});
+}
+/**
+* 从 context 读取匹配到的 routeRule,提取 ISR 规则。
+* 返回 `undefined` 表示该路由未启用 ISR。
+*/
+function getIsrRuleFromContext(c) {
+	const rule = c.get("routeRule");
+	if (!rule?.isr) return void 0;
+	return normalizeIsrRule(rule.isr);
+}
+//#endregion
+//#region src/router.ts
+const HTTP_METHODS = [
+	"GET",
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE",
+	"HEAD",
+	"OPTIONS"
+];
+function normalizeMethod(m) {
+	if (!m) return void 0;
+	const upper = m.toUpperCase();
+	return HTTP_METHODS.includes(upper) ? upper : void 0;
+}
+function convertUbeanRoutePath(path) {
+	let honoPath = path;
+	if (/\/\*\*:/.test(honoPath)) honoPath = "*";
+	honoPath = honoPath.replace(/\[(\.\.\.)?([^\]]+)\]/g, (_m, rest, name) => {
+		if (rest) return `*${name}`;
+		return `:${name}`;
+	});
+	return honoPath;
+}
+/**
+* Sort page routes so catch-all routes (`/**:slug`, converted to Hono `*`)
+* are registered last. Hono's RegExpRouter matches in registration order,
+* so a catch-all registered before a specific path (e.g. `/`) would swallow
+* it. File-system sort order puts `[...slug].vue` before `index.vue`
+* (`[` < `i`), which is wrong for Hono — this sort corrects it.
+*
+* Stable: non-catch-all pages keep their original relative order.
+*/
+function sortPagesForRegistration(pages) {
+	return [...pages].sort((a, b) => {
+		const aCatchall = /\/\*\*:/.test(a.route);
+		const bCatchall = /\/\*\*:/.test(b.route);
+		if (aCatchall && !bCatchall) return 1;
+		if (!aCatchall && bCatchall) return -1;
+		return 0;
+	});
+}
+function middlewarePathToHonoPath(relativePath) {
+	const segments = relativePath.replace(/\.(mjs|js|jsx|cjs|ts|tsx|mts|cts)$/i, "").split("/");
+	if (segments.length === 1) return "/*";
+	return `${`/${segments.slice(0, -1).join("/")}`}/*`;
+}
+function matchMiddlewarePath(mountPath, routePath) {
+	if (mountPath === "*" || mountPath === "/*") return true;
+	if (mountPath.endsWith("/*")) {
+		const prefix = mountPath.slice(0, -1);
+		return routePath === prefix.slice(0, -1) || routePath.startsWith(prefix);
+	}
+	return routePath === mountPath;
+}
+function resolveRouteExport(mod, method) {
+	const namedHandler = mod[method];
+	if (isHandlerChain(namedHandler)) return namedHandler;
+	if (typeof namedHandler === "function") return namedHandler;
+	const lowerHandler = mod[method.toLowerCase()];
+	if (isHandlerChain(lowerHandler)) return lowerHandler;
+	if (typeof lowerHandler === "function") return lowerHandler;
+	if (isHandlerChain(mod.default)) return mod.default;
+	if (typeof mod.default === "function") return mod.default;
+	return null;
+}
+let _pagesMod;
+let _i18nMod;
+async function loadPages() {
+	if (_pagesMod !== void 0) return _pagesMod;
+	try {
+		_pagesMod = await import("@ubean/pages");
+	} catch {
+		_pagesMod = null;
+	}
+	return _pagesMod;
+}
+async function loadI18n() {
+	if (_i18nMod !== void 0) return _i18nMod;
+	try {
+		_i18nMod = await import("@ubean/i18n");
+	} catch {
+		_i18nMod = null;
+	}
+	return _i18nMod;
+}
+async function registerApiRoutes(app, options) {
+	const { routes, middleware, routeLoaders, middlewareLoaders } = options;
+	const sortedMiddleware = [...middleware].sort((a, b) => a.order - b.order);
+	const loadedUserMiddleware = [];
+	for (const mw of sortedMiddleware) {
+		await app.hooks.callHook("middleware:register", mw);
+		const loader = middlewareLoaders[mw.relativePath];
+		if (loader) try {
+			const mod = await loader();
+			if (mod.default) {
+				const mountPath = mw.global ? "*" : middlewarePathToHonoPath(mw.relativePath);
+				loadedUserMiddleware.push({
+					mountPath,
+					handler: mod.default
+				});
+			}
+		} catch {}
+	}
+	function getMatchingMiddleware(routePath) {
+		return loadedUserMiddleware.filter((mw) => matchMiddlewarePath(mw.mountPath, routePath)).map((mw) => mw.handler);
+	}
+	const routesByPath = /* @__PURE__ */ new Map();
+	const routeFileGroups = /* @__PURE__ */ new Map();
+	for (const route of routes) {
+		const key = route.relativePath;
+		const group = routeFileGroups.get(key);
+		if (group) group.push(route);
+		else routeFileGroups.set(key, [route]);
+	}
+	for (const [relativePath, routeGroup] of routeFileGroups) {
+		const loader = routeLoaders[relativePath];
+		if (!loader) continue;
+		const first = routeGroup[0];
+		const honoPath = convertUbeanRoutePath(first.route);
+		let pathMethods = routesByPath.get(honoPath);
+		if (!pathMethods) {
+			pathMethods = /* @__PURE__ */ new Map();
+			routesByPath.set(honoPath, pathMethods);
+		}
+		let mod;
+		try {
+			mod = await loader();
+		} catch {
+			continue;
+		}
+		for (const route of routeGroup) {
+			const method = normalizeMethod(route.method);
+			if (!method) continue;
+			const resolved = resolveRouteExport(mod, method);
+			if (resolved) pathMethods.set(method, {
+				definition: resolved,
+				fileMeta: first.fileMeta,
+				matchers: first.matchers
+			});
+		}
+	}
+	for (const [honoPath, pathMethods] of routesByPath) for (const [method, entry] of pathMethods) {
+		const { definition, fileMeta, matchers } = entry;
+		const matchingMiddleware = getMatchingMiddleware(honoPath);
+		const matcherMiddleware = async (c, next) => {
+			if (!matchers) {
+				await next();
+				return;
+			}
+			const params = c.req.param();
+			if (!validateParams(matchers, params)) return c.json({
+				error: "Not Found",
+				path: c.req.path,
+				method: c.req.method
+			}, 404);
+			await next();
+		};
+		if (isHandlerChain(definition)) {
+			const routeMeta = { ...extractRouteMeta(definition) };
+			if (fileMeta) Object.assign(routeMeta, fileMeta);
+			await app.hooks.callHook("route:register", {
+				method,
+				path: honoPath,
+				handler: definition,
+				meta: routeMeta
+			});
+			const metaMiddleware = async (c, next) => {
+				c.set("route", {
+					meta: routeMeta,
+					path: c.req.path,
+					method: c.req.method
+				});
+				await next();
+			};
+			const honoHandlers = [
+				metaMiddleware,
+				matcherMiddleware,
+				...matchingMiddleware,
+				...definition
+			];
+			app.on(method.toLowerCase(), honoPath, ...honoHandlers);
+		} else {
+			const routeMeta = {
+				requiresAuth: true,
+				...fileMeta
+			};
+			const metaMiddleware = async (c, next) => {
+				c.set("route", {
+					meta: routeMeta,
+					path: c.req.path,
+					method: c.req.method
+				});
+				await next();
+			};
+			const handlerWrapper = async (c) => {
+				const result = await definition(c);
+				if (result instanceof Response) return result;
+				if (typeof result === "string") return new Response(result, { headers: { "Content-Type": "text/plain; charset=utf-8" } });
+				return new Response(JSON.stringify(result), { headers: { "Content-Type": "application/json; charset=utf-8" } });
+			};
+			await app.hooks.callHook("route:register", {
+				method,
+				path: honoPath,
+				handler: definition,
+				meta: routeMeta
+			});
+			const honoHandlers = [
+				metaMiddleware,
+				matcherMiddleware,
+				...matchingMiddleware,
+				handlerWrapper
+			];
+			app.on(method.toLowerCase(), honoPath, ...honoHandlers);
+		}
+	}
+}
+async function registerPageRoutes(app, options) {
+	const { pages, layouts = [], middleware, middlewareLoaders, i18nConfig } = options;
+	const pagesMod = await loadPages();
+	if (!pagesMod) return;
+	const sortedMiddleware = [...middleware].sort((a, b) => a.order - b.order);
+	const loadedUserMiddleware = [];
+	for (const mw of sortedMiddleware) {
+		const loader = middlewareLoaders[mw.relativePath];
+		if (loader) try {
+			const mod = await loader();
+			if (mod.default) {
+				const mountPath = mw.global ? "*" : middlewarePathToHonoPath(mw.relativePath);
+				loadedUserMiddleware.push({
+					mountPath,
+					handler: mod.default
+				});
+			}
+		} catch {}
+	}
+	function getMatchingMiddleware(routePath) {
+		return loadedUserMiddleware.filter((mw) => matchMiddlewarePath(mw.mountPath, routePath)).map((mw) => mw.handler);
+	}
+	function getLocalePrefixedPaths(honoPath) {
+		if (!i18nConfig) return [];
+		const { strategy, defaultLocale, locales = [] } = i18nConfig;
+		if (strategy === "no_prefix") return [];
+		const result = [];
+		for (const locale of locales) {
+			if (strategy === "prefix_except_default" && locale === defaultLocale) continue;
+			const cleanPath = honoPath === "/" ? "" : honoPath;
+			result.push({
+				locale,
+				path: `/${locale}${cleanPath}`
+			});
+		}
+		return result;
+	}
+	const hasDefaultLayout = layouts.some((l) => l.isDefault);
+	const { isPagesRequest, pageJsonResponse, renderPage, renderPageToStream } = pagesMod;
+	const pageLoaders = options.pageLoaders;
+	const pageRenderer = options.pageRenderer;
+	const pageAssetTags = options.pageAssetTags;
+	const ssrExclude = options.ssrExclude ?? [];
+	const streaming = options.streaming === true;
+	const botFallback = options.botFallback !== false;
+	const cacheStore = options.cacheStore;
+	const colorModeScript = options.colorModeScript;
+	const injectColorMode = (html) => colorModeScript ? html.replace("<head>", `<head>\n    ${colorModeScript}`) : html;
+	async function handlePageRequest(c, page, method, loaderKey) {
+		c.set("route", {
+			meta: { requiresAuth: page.pageMeta?.requiresAuth ?? true },
+			path: c.req.path,
+			method: c.req.method
+		});
+		let loader;
+		let mod;
+		let loaderResult;
+		let actionResult;
+		let actionErrors = null;
+		if (pageLoaders) {
+			loader = pageLoaders[loaderKey ?? page.relativePath];
+			if (loader) try {
+				mod = await loader();
+			} catch {}
+		}
+		if (method === "POST") {
+			const actionsExport = mod?.actions;
+			if (actionsExport && typeof actionsExport === "object") {
+				const action = actionsExport[parseFormActionName(c.req.url)];
+				if (action && isServerAction(action)) {
+					const res = await runServerAction(action, c);
+					if (res.response) {
+						const handled = handleActionResponse(c, res.response, isPagesRequest);
+						if (handled) return handled;
+						actionResult = res.response;
+					} else if (res.errors) actionErrors = res.errors;
+					else actionResult = res.data;
+				}
+			} else if (mod?.action && typeof mod.action === "function") try {
+				actionResult = await mod.action(c);
+				if (actionResult instanceof Response) {
+					const handled = handleActionResponse(c, actionResult, isPagesRequest);
+					if (handled) return handled;
+				}
+				if (actionResult && typeof actionResult === "object" && "errors" in actionResult) {
+					actionErrors = actionResult.errors;
+					actionResult = void 0;
+				}
+			} catch (err) {
+				if (err instanceof Response) {
+					const handled = handleActionResponse(c, err, isPagesRequest);
+					if (handled) return handled;
+					return err;
+				}
+				if (isPagesRequest(c)) return c.json({ error: err instanceof Error ? err.message : String(err) }, 500);
+				actionErrors = { _error: err instanceof Error ? err.message : String(err) };
+			}
+		}
+		if (mod?.loader && typeof mod.loader === "function") try {
+			loaderResult = await mod.loader(c);
+			if (loaderResult instanceof Response) return loaderResult;
+		} catch {}
+		const props = { ...loaderResult };
+		if (actionResult !== void 0 && actionResult && typeof actionResult === "object") Object.assign(props, actionResult);
+		const pageObj = {
+			component: page.reuseTarget || page.name,
+			props,
+			params: c.req.param(),
+			url: (c.get("pathWithoutLocale") || c.req.path) + (c.req.url.includes("?") ? new URL(c.req.url).search : ""),
+			layout: page.layout === false ? false : page.layout || page.pageMeta?.layout || (hasDefaultLayout ? "default" : false),
+			errors: actionErrors,
+			head: page.pageMeta?.head
+		};
+		if (isPagesRequest(c)) return pageJsonResponse(pageObj);
+		if (method === "POST" && actionResult instanceof Response) return actionResult;
+		const currentLocale = c.get("locale") || "";
+		const renderContext = {
+			locale: currentLocale,
+			localeDir: "ltr"
+		};
+		const i18nMod = await loadI18n();
+		if (i18nMod && currentLocale) {
+			renderContext.localeDir = i18nMod.getLocaleDir(currentLocale);
+			renderContext.messages = i18nMod.getLocaleMessages(currentLocale);
+			renderContext.availableLocales = i18nMod.getRegisteredLocalesMeta();
+		}
+		const routeRule = c.get("routeRule");
+		const perRouteSsr = routeRule?.ssr;
+		const isrRule = normalizeIsrRule(routeRule?.isr);
+		const pprEnabled = routeRule?.ppr === true;
+		let excluded = matchAnyGlob(page.route, ssrExclude);
+		let routeStreaming = streaming;
+		if (perRouteSsr === false) excluded = true;
+		else if (perRouteSsr === true) excluded = false;
+		else if (perRouteSsr === "streaming") {
+			excluded = false;
+			routeStreaming = true;
+		} else if (pprEnabled) {
+			excluded = false;
+			routeStreaming = true;
+		}
+		const renderer = excluded ? null : pageRenderer ?? null;
+		if (isrRule && cacheStore && method === "GET") {
+			const pathname = new URL(c.req.url).pathname;
+			const isrResponse = await serveIsr(c, {
+				pathname,
+				rule: isrRule,
+				store: cacheStore,
+				render: async () => {
+					return {
+						html: await renderPage(pageObj, pageAssetTags ?? {}, renderer, "app", renderContext),
+						status: 200,
+						headers: { "Content-Type": "text/html; charset=utf-8" }
+					};
+				}
+			});
+			if (isrResponse) return isrResponse;
+		}
+		const userAgent = c.req.header("user-agent");
+		const isBot = botFallback && isBotUserAgent(userAgent);
+		if (routeStreaming && renderer && !isBot) {
+			const stream = renderPageToStream(pageObj, pageAssetTags ?? {}, renderer, "app", renderContext);
+			const headers = { "Content-Type": "text/html; charset=utf-8" };
+			if (pprEnabled) headers["X-PPR"] = "true";
+			return c.body(stream, {
+				headers,
+				...method === "POST" && actionErrors ? { status: 422 } : {}
+			});
+		}
+		const html = await renderPage(pageObj, pageAssetTags ?? {}, renderer, "app", renderContext);
+		return c.html(injectColorMode(html), method === "POST" && actionErrors ? { status: 422 } : void 0);
+	}
+	const pageByName = /* @__PURE__ */ new Map();
+	for (const p of pages) pageByName.set(p.name, p);
+	const sortedPages = sortPagesForRegistration(pages);
+	for (const page of sortedPages) {
+		const honoPath = convertUbeanRoutePath(page.route);
+		const matchingMiddleware = getMatchingMiddleware(honoPath);
+		const pageMeta = { requiresAuth: page.pageMeta?.requiresAuth ?? true };
+		const metaMiddleware = async (c, next) => {
+			c.set("route", {
+				meta: pageMeta,
+				path: c.req.path,
+				method: c.req.method
+			});
+			await next();
+		};
+		const matcherMiddleware = async (c, next) => {
+			if (!page.matchers) {
+				await next();
+				return;
+			}
+			const params = c.req.param();
+			if (!validateParams(page.matchers, params)) return c.json({
+				error: "Not Found",
+				path: c.req.path,
+				method: c.req.method
+			}, 404);
+			await next();
+		};
+		const loaderKey = page.isReuse && page.reuseTarget ? pageByName.get(page.reuseTarget)?.relativePath ?? page.relativePath : page.relativePath;
+		const pageHandler = (method) => async (c) => handlePageRequest(c, page, method, loaderKey);
+		app.on(["GET"], honoPath, metaMiddleware, matcherMiddleware, ...matchingMiddleware, pageHandler("GET"));
+		app.on(["POST"], honoPath, metaMiddleware, matcherMiddleware, ...matchingMiddleware, pageHandler("POST"));
+		for (const { path: localePath } of getLocalePrefixedPaths(honoPath)) {
+			const localeMetaMiddleware = async (c, next) => {
+				c.set("route", {
+					meta: pageMeta,
+					path: c.req.path,
+					method: c.req.method
+				});
+				await next();
+			};
+			app.on(["GET"], localePath, localeMetaMiddleware, matcherMiddleware, ...matchingMiddleware, pageHandler("GET"));
+			app.on(["POST"], localePath, localeMetaMiddleware, matcherMiddleware, ...matchingMiddleware, pageHandler("POST"));
+		}
+	}
+	if (options.notFoundPage) {
+		const notFoundPage = options.notFoundPage;
+		const pageAssetTagsOpt = options.pageAssetTags;
+		const _ssrExclude = options.ssrExclude ?? [];
+		const pageRendererOpt = options.pageRenderer;
+		app.get("*", async (c) => {
+			const path = c.req.path;
+			if (path.startsWith("/api/") || path.startsWith("/_")) return c.json({
+				error: "Not Found",
+				path,
+				method: c.req.method
+			}, 404);
+			if (isPagesRequest(c)) return pageJsonResponse({
+				component: "NotFound",
+				props: {},
+				params: {},
+				url: path + (c.req.url.includes("?") ? new URL(c.req.url).search : ""),
+				layout: (Array.isArray(notFoundPage.layout) ? notFoundPage.layout[0] : notFoundPage.layout) ?? (layouts.some((l) => l.isDefault) ? "default" : false),
+				errors: null,
+				head: notFoundPage.pageMeta?.head
+			});
+			const currentLocale = c.get("locale") || "";
+			const renderContext = {
+				locale: currentLocale,
+				localeDir: "ltr"
+			};
+			const i18nMod = await loadI18n();
+			if (i18nMod && currentLocale) {
+				renderContext.localeDir = i18nMod.getLocaleDir(currentLocale);
+				renderContext.messages = i18nMod.getLocaleMessages(currentLocale);
+				renderContext.availableLocales = i18nMod.getRegisteredLocalesMeta();
+			}
+			const pageObj = {
+				component: "NotFound",
+				props: {},
+				params: {},
+				url: path + (c.req.url.includes("?") ? new URL(c.req.url).search : ""),
+				layout: notFoundPage.layout ?? (layouts.some((l) => l.isDefault) ? "default" : false),
+				errors: null,
+				head: notFoundPage.pageMeta?.head
+			};
+			const renderer = matchAnyGlob("/*", _ssrExclude) ? null : pageRendererOpt ?? null;
+			const userAgent = c.req.header("user-agent");
+			const isBot = botFallback && isBotUserAgent(userAgent);
+			if (streaming && renderer && !isBot) {
+				const stream = renderPageToStream(pageObj, pageAssetTagsOpt ?? {}, renderer, "app", renderContext);
+				return c.body(stream, {
+					headers: { "Content-Type": "text/html; charset=utf-8" },
+					status: 404
+				});
+			}
+			const html = await renderPage(pageObj, pageAssetTagsOpt ?? {}, renderer, "app", renderContext);
+			return c.html(injectColorMode(html), 404);
+		});
+	}
+}
+async function registerRoutes(app, options) {
+	await registerApiRoutes(app, options);
+	await registerPageRoutes(app, options);
+}
+function createRouteLoader(importMetaGlob) {
+	return Object.fromEntries(Object.entries(importMetaGlob).map(([key, loader]) => {
+		return [key.replace(/^\.\//, ""), loader];
+	}));
+}
+//#endregion
+//#region src/internal-fetch.ts
+const FETCHER_KEY = "__ubean_internal_fetcher__";
+function setInternalFetcher(fetcher) {
+	globalThis[FETCHER_KEY] = fetcher;
+}
+function getInternalFetcher() {
+	return globalThis[FETCHER_KEY] || null;
+}
+function clearInternalFetcher() {
+	delete globalThis[FETCHER_KEY];
+}
+const FORWARD_HEADER_DEFAULTS = [
+	"cookie",
+	"authorization",
+	"x-request-id",
+	"x-forwarded-for",
+	"x-forwarded-proto",
+	"x-real-ip",
+	"accept-language",
+	"user-agent"
+];
+function applyContextHeaders(headers, c, forwardHeaders) {
+	const names = forwardHeaders || FORWARD_HEADER_DEFAULTS;
+	for (const name of names) {
+		const value = c.req.header(name);
+		if (value) headers.set(name, value);
+	}
+	const requestId = c.get("requestId");
+	if (requestId) headers.set("x-request-id", requestId);
+}
+/**
+* 创建进程内调度适配器。
+*
+* 将注册的 Hono `app.fetch` 包装为 `@soybeanjs/fetch` 的 `FetchAdapter`,
+* 使其可通过 `createRequest` / `createTypedClient` / `toFlatTypedClient` 等 API
+* 进行进程内调度(不发起新的网络请求)。
+*
+* 消费者可直接组合使用:
+* ```typescript
+* import { createInternalAdapter } from '@ubean/routes';
+* import { createRequest, createTypedClient } from '@soybeanjs/fetch';
+*
+* const adapter = createInternalAdapter(c);
+* const request = createRequest({ adapter, retry: { retries: 0 } }, { isBackendSuccess: () => true });
+* const api = createTypedClient<paths>(request);
+* ```
+*
+* @param c - Hono Context(可选,用于转发 cookie/authorization 等请求头)
+* @param options - 选项(`headers` 自定义额外 header,`forwardHeaders` 自定义转发 header 列表)
+*/
+function createInternalAdapter(c, options) {
+	const forwardHeaders = options?.forwardHeaders;
+	const extraHeaders = options?.headers;
+	return async (url, init) => {
+		const fetcher = getInternalFetcher();
+		if (!fetcher) throw new Error("[ubean] createInternalAdapter: fetcher not registered. Call setInternalFetcher() with your app.fetch first.");
+		const headers = new Headers(init.headers);
+		headers.set("x-internal-request", "1");
+		if (c) applyContextHeaders(headers, c, forwardHeaders);
+		if (extraHeaders) for (const [k, v] of Object.entries(extraHeaders)) headers.set(k, v);
+		const requestUrl = url.startsWith("http") ? url : new URL(url, "http://internal");
+		return fetcher(new Request(requestUrl, {
+			...init,
+			headers
+		}));
+	};
+}
+//#endregion
+//#region src/openapi.ts
+function registerOpenAPIRoutes(app, options = {}) {
+	const { scalarPath = "/_scalar", openAPIPath = "/_openapi.json", title = "API Reference" } = options;
+	const openapiHandler = openAPIRouteHandler(app, { documentation: {
+		info: {
+			title: options.title || "UBEAN API",
+			version: options.version || "1.0.0",
+			description: options.description
+		},
+		servers: options.baseURL ? [{ url: options.baseURL }] : void 0
+	} });
+	app.get(openAPIPath, openapiHandler);
+	app.get(scalarPath, (c) => {
+		const scalarHTML = `<!doctype html>
+<html>
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>${title}</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    html, body { width: 100%; height: 100%; }
+    body { background: #0f0f12; }
+  </style>
+</head>
+<body>
+  <script
+    id="api-reference"
+    data-url="${openAPIPath}"
+    data-configuration='{
+      "theme": "purple",
+      "layout": "modern",
+      "hideClientButton": false,
+      "defaultHttpClient": { "targetKey": "shell", "clientKey": "curl" }
+    }'
+  ><\/script>
+  <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"><\/script>
+</body>
+</html>`;
+		return c.html(scalarHTML);
+	});
+}
+//#endregion
+export { UbeanRouter, buildIsrCacheKey, clearInternalFetcher, compileRouteRules, createInternalAdapter, createRouteLoader, createRouteRulesMiddleware, createServerRouter, defineHandler, defineHandlerMeta, defineMiddleware, extractRouteMeta, getInternalFetcher, getIsrCache, getIsrRuleFromContext, getStaleIsrCache, invalidateIsrCache, invalidateIsrCachePattern, isBotUserAgent, isHandlerChain, isIsrEntryStale, matchRouteRules, normalizeIsrRule, registerApiRoutes, registerOpenAPIRoutes, registerPageRoutes, registerRoutes, serveIsr, setInternalFetcher, setIsrCache, sortPagesForRegistration, useRouter };