@ubean/build 0.6.7 → 0.6.9

package/README.md

@@ -383,7 +383,7 @@ const manifest = await buildWithEnvironments({
 | `createIslandsSsrStubPlugin()`                                                                          | Non-functional islands registry for SSR                                                      |
 
 **`serializePagesForEntry()` is a whitelist, and the whitelist is load-bearing.** It previously
-serialized only `relativePath` / `name` / `route` / `layout` / `reuseTarget` / `isReuse` / `pageMeta`,
+serialized only `relativePath` / `name` / `route` / `layout` / `reuseTarget` / `pageKind` / `pageMeta`,
 so `matchers` and `slot` **disappeared from production builds** — dev used the live scanned objects
 and behaved correctly, while a `[id=numeric]` route returned 404 in dev and 200 in production. Add a
 field to `ScannedPage` and you must add it here too; `packages/builder/test/page-metadata.test.ts`

package/README.zh-CN.md

@@ -373,7 +373,7 @@ const manifest = await buildWithEnvironments({
 | `createIslandsSsrStubPlugin()`                                                                          | SSR 期的 islands 注册表空壳                                                                   |
 
 **`serializePagesForEntry()` 是一份白名单，而这份白名单承载语义。** 它此前只序列化
-`relativePath` / `name` / `route` / `layout` / `reuseTarget` / `isReuse` / `pageMeta`，于是 `matchers` 与 `slot`
+`relativePath` / `name` / `route` / `layout` / `reuseTarget` / `pageKind` / `pageMeta`，于是 `matchers` 与 `slot`
 **在生产构建里消失** —— dev 用扫描得到的活对象因此一切正常，而带 `[id=numeric]` 的路由在 dev 返回 404、
 在生产返回 200。给 `ScannedPage` 加字段就必须同步加到这里；`packages/builder/test/page-metadata.test.ts`
 逐字段锁住这份名单。

package/dist/codegen/index.js

@@ -1 +1 @@
-export { d as BUILTIN_PRESETS, t as CODEGEN_CONTRACT_VERSION, n as CODEGEN_FILES, r as CODEGEN_NON_CONTRACT_FILES, p as HONO_OPENAPI_PRESET, m as UBEAN_CLIENT_PRESET, h as UBEAN_SERVER_PRESET, g as VUE_I18N_PRESET, _ as VUE_MACROS_PRESET, v as VUE_PRESET, y as VUE_ROUTER_PRESET, b as generateAutoImports, l as generateI18nTypes, x as generateImportsTransform, a as generateOpenApiTypes, o as generateOpenApiTypesFromServer, s as generatePageTypes, c as generateRouteTypes, i as generateTypes, S as getAutoImportPresets, C as getBuiltinComposables, w as getUbeanAutoImportConfig, T as getUbeanComponentsConfig, u as messagesToTsType, E as resolveAutoImportsConfig, D as resolveComponentsConfig, O as toArray } from "../codegen-CUlE95gB.js";
+export { d as BUILTIN_PRESETS, t as CODEGEN_CONTRACT_VERSION, n as CODEGEN_FILES, r as CODEGEN_NON_CONTRACT_FILES, p as HONO_OPENAPI_PRESET, m as UBEAN_CLIENT_PRESET, h as UBEAN_SERVER_PRESET, g as VUE_I18N_PRESET, _ as VUE_MACROS_PRESET, v as VUE_PRESET, y as VUE_ROUTER_PRESET, b as generateAutoImports, l as generateI18nTypes, x as generateImportsTransform, a as generateOpenApiTypes, o as generateOpenApiTypesFromServer, s as generatePageTypes, c as generateRouteTypes, i as generateTypes, S as getAutoImportPresets, C as getBuiltinComposables, w as getUbeanAutoImportConfig, T as getUbeanComponentsConfig, u as messagesToTsType, E as resolveAutoImportsConfig, D as resolveComponentsConfig, O as toArray } from "../codegen-RzEXvOPR.js";

package/dist/{codegen-CUlE95gB.js → codegen-RzEXvOPR.js}

@@ -1,4 +1,4 @@
-import { r as resolveEnvModules } from "./types-JZjwXWJd.js";
+import { r as resolveEnvModules } from "./types-C2WT1hXQ.js";
 import { isAbsolute, join, normalize, relative } from "pathe";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { glob } from "tinyglobby";
@@ -33,11 +33,34 @@ function tsTypeOfLiteral(value) {
 	if (typeof value === "boolean") return "boolean";
 	return "string";
 }
-function renderModuleTypes(moduleId, fields) {
-	if (fields.length === 0) return `declare module '${moduleId}' {\n  // env.schema is empty\n}\n`;
-	return `declare module '${moduleId}' {\n${fields.map((f) => {
-		return `  export const ${f.key}: ${f.type}${f.optional ? " | undefined" : ""};`;
-	}).join("\n")}\n}\n`;
+/**
+* 把 `envField.*({ description })` 渲染成 JSDoc 行。
+*
+* 转义行内注释终止符：说明文字里出现它就提前闭合注释，后面的声明会变成语法错误 ——
+* 而报错位置指向生成的 `.d.ts`（用户不该去改的文件），完全看不出根因。
+* 多行说明逐行加 ` * ` 前缀，否则第二行会跑到注释外面。
+*/
+function renderJsDoc(description) {
+	const lines = description.replaceAll("*/", "*\\/").split(/\r?\n/).map((line) => line.trimEnd());
+	if (lines.length === 1) return [`  /** ${lines[0]} */`];
+	return [
+		"  /**",
+		...lines.map((line) => `   * ${line}`.trimEnd()),
+		"   */"
+	];
+}
+function renderModuleTypes(moduleId, fields, extraLines = []) {
+	const lines = fields.flatMap((f) => {
+		const decl = `  export const ${f.key}: ${f.type}${f.optional ? " | undefined" : ""};`;
+		return f.description ? [...renderJsDoc(f.description), decl] : [decl];
+	});
+	const body = [
+		...lines,
+		...lines.length > 0 && extraLines.length > 0 ? [""] : [],
+		...extraLines
+	];
+	if (body.length === 0) return `declare module '${moduleId}' {\n  // env.schema is empty\n}\n`;
+	return `declare module '${moduleId}' {\n${body.join("\n")}\n}\n`;
 }
 /**
 * 从 `import.meta.env` 快照生成 `ImportMetaEnv`。
@@ -59,6 +82,15 @@ function renderImportMetaEnv(importMetaEnv) {
 	}).join("\n")}\n}\n`;
 }
 /**
+* `renderEnvServerModule()` 生成的源码除了字段还会 `export function getSecret(key)`
+* （`packages/builder/src/env/types.ts`），但早先这里只声明字段 —— 用户按
+* `docs/contracts/env-v1.md` 的指引去 import 它，`tsc` 直接报 TS2305。
+*
+* 源码里还有一个 `__env`，它是生成代码的内部聚合对象，刻意**不**声明：声明了就等于
+* 把它纳入公开 API，而它有更好的具名导出可用。
+*/
+const ENV_SERVER_EXTRA_EXPORTS = ["  /** 读取未在 `env.schema` 里声明的变量（动态 / per-request 场景）。 */", "  export function getSecret(key: string): string | undefined;"];
+/**
 * 生成 `.ubean/env.d.ts`。
 *
 * 顶层**不能**出现 `export {}`：`ImportMetaEnv` 的声明必须留在全局作用域，一旦文件变成
@@ -77,7 +109,7 @@ interface ImportMeta {
   readonly env: ImportMetaEnv;
 }
 
-${renderModuleTypes("ubean:env/client", modules.client)}${renderModuleTypes("ubean:env/server", modules.server)}`;
+${renderModuleTypes("ubean:env/client", modules.client)}${renderModuleTypes("ubean:env/server", modules.server, ENV_SERVER_EXTRA_EXPORTS)}`;
 	await mkdir(outDir, { recursive: true });
 	const outPath = join(outDir, fileName);
 	await writeFile(outPath, contents, "utf8");

package/dist/env/plugin.d.ts

@@ -20,6 +20,8 @@ interface EnvFieldSpec {
   /** TypeScript 字面量类型，直接写进 `.ubean/env.d.ts`。 */
   type: string;
   optional: boolean;
+  /** 字段说明（`envField.*({ description })`），写进 `.ubean/env.d.ts` 的 JSDoc。 */
+  description?: string;
   /**
    * 已解析的值：
    * - `context: 'client'` → 构建期内联用的字面量（来自 `import.meta.env` / `.env`，已含 default 回退）

package/dist/env/plugin.js

@@ -1,4 +1,4 @@
-import { n as renderEnvServerModule, r as resolveEnvModules, t as renderEnvClientModule } from "../types-JZjwXWJd.js";
+import { n as renderEnvServerModule, r as resolveEnvModules, t as renderEnvClientModule } from "../types-C2WT1hXQ.js";
 import { loadEnv } from "vite";
 //#region src/env/plugin.ts
 /**

package/dist/index.d.ts

@@ -109,7 +109,12 @@ export declare function ssrSingletonProdOptimizeExclude(extra?: string[]): strin
 export declare function createRoutingVirtualModule(routes: CompiledRoute[], middlewares: CompiledMiddleware[], cwd: string): VirtualModule;
 export declare function createPagesVirtualModule(pages: CompiledPage[], layouts: CompiledLayout[], cwd: string): VirtualModule;
 export declare function createMetaVirtualModule(): VirtualModule;
-export declare function createAppVirtualModule(apiRoutes: ScannedApiRoute[], middlewares: ScannedMiddleware[], pages: ScannedPageRoute[], srcDir: string): VirtualModule;
+export declare function createAppVirtualModule(apiRoutes: ScannedApiRoute[], middlewares: ScannedMiddleware[], pages: ScannedPageRoute[], srcDir: string,
+/**
+ * 页面 glob 扩展名(逗号分隔,无点),来自 `pageGlobExtensions()`。
+ * 不传时用全开集合,仅兼容旧调用方式。
+ */
+pageExtensions?: string): VirtualModule;
 export declare function createLocalesVirtualModule(_locales: ScannedLocale[], defaultLocale: string | undefined, srcDir?: string, i18nConfigJson?: string): VirtualModule;
 //#endregion
 export { type VirtualModule, type VirtualModuleContext, VirtualModuleRegistry, type VirtualModuleResolver, type VirtualModuleTransform, createVirtualRegistry, defineVirtualModule, defineVirtualModulePrefix, resetVirtualRegistry, useVirtualRegistry };

package/dist/index.js

@@ -1,3 +1,3 @@
 import { _ as defineVirtualModule, a as ssrSingletonProdOptimizeExclude, b as useVirtualRegistry, c as getComponentResolvers, d as registerComponentResolver, f as registerCssImport, g as createVirtualRegistry, h as VirtualModuleRegistry, i as ssrSingletonDevPolicy, l as getCssImports, m as resetModuleRegistry, n as SSR_SINGLETON_OPTIMIZE_EXCLUDE, o as ssrSingletonProdSsr, p as registerHeadScript, r as SSR_SINGLETON_PACKAGES, t as SSR_SINGLETON_DEDUPE, u as getHeadScripts, v as defineVirtualModulePrefix, y as resetVirtualRegistry } from "./ssr-singleton-CUHZLgiO.js";
-import { a as createRoutingVirtualModule, i as createPagesVirtualModule, n as createLocalesVirtualModule, o as stripMacros, r as createMetaVirtualModule, s as transformMacros, t as createAppVirtualModule } from "./virtual-modules-B3aE-Fmn.js";
+import { a as createRoutingVirtualModule, i as createPagesVirtualModule, n as createLocalesVirtualModule, o as stripMacros, r as createMetaVirtualModule, s as transformMacros, t as createAppVirtualModule } from "./virtual-modules-7mD1FgVQ.js";
 export { SSR_SINGLETON_DEDUPE, SSR_SINGLETON_OPTIMIZE_EXCLUDE, SSR_SINGLETON_PACKAGES, VirtualModuleRegistry, createAppVirtualModule, createLocalesVirtualModule, createMetaVirtualModule, createPagesVirtualModule, createRoutingVirtualModule, createVirtualRegistry, defineVirtualModule, defineVirtualModulePrefix, getComponentResolvers, getCssImports, getHeadScripts, registerComponentResolver, registerCssImport, registerHeadScript, resetModuleRegistry, resetVirtualRegistry, ssrSingletonDevPolicy, ssrSingletonProdOptimizeExclude, ssrSingletonProdSsr, stripMacros, transformMacros, useVirtualRegistry };

package/dist/production.d.ts

@@ -46,7 +46,7 @@ export interface BuildManifest {
 /**
  * 把扫描到的页面序列化进服务端入口（`const _pages = [...]`）。
  *
- * **白名单必须覆盖语义字段**：此前只序列化了 `relativePath/name/route/layout/reuseTarget/isReuse/
+ * **白名单必须覆盖语义字段**：此前只序列化了 `relativePath/name/route/layout/reuseTarget/pageKind/
  * pageMeta`，于是 `matchers` / `slot` **在生产构建里丢失** ——
  * dev 用扫描得到的活对象（`enhanceDevApp` / `buildDevSsrRoutes` 直接拿 `scanResult.pages`），所以本地
  * 一切正常，只有构建产物坏掉：带着 `[id=numeric]` 的路由在 dev 返回 404、在生产返回 200（实测）。

package/dist/production.js

@@ -1 +1 @@
-export { T as buildWithEnvironments, v as createIslandsSsrStubPlugin, y as generateCloudflareWorkerEntry, b as generateNodeServerEntry, x as generateStandardHandlerEntry, S as generateVirtualModulesToDisk, C as getPresetBuildConfig, w as serializePagesForEntry } from "./vite--HujaLpA.js";
+export { T as buildWithEnvironments, v as createIslandsSsrStubPlugin, y as generateCloudflareWorkerEntry, b as generateNodeServerEntry, x as generateStandardHandlerEntry, S as generateVirtualModulesToDisk, C as getPresetBuildConfig, w as serializePagesForEntry } from "./vite-k9_n0K9x.js";

package/dist/{types-JZjwXWJd.js → types-C2WT1hXQ.js}

@@ -10,6 +10,17 @@ import { isEnvFieldMeta } from "@ubean/shared";
 * 维度规则照抄 Astro `astro:env`：`client+public` / `server+public` / `server+secret` 三种合法，
 * `client+secret` 在**规范化阶段**就抛错（配置期失败，比构建期失败早）。
 */
+/**
+* 判断一个 schema 条目是不是**运行期**校验器（Standard Schema / `safeParse`）。
+*
+* 这类值不能进 `env.schema` —— 见 `resolveEnvModules()` 里的抛错说明。
+*/
+function isRuntimeSchema(def) {
+	if (typeof def !== "object" || def === null) return false;
+	const standard = def["~standard"];
+	if (typeof standard === "object" && standard !== null && typeof standard.validate === "function") return true;
+	return typeof def.safeParse === "function";
+}
 function typeOfField(def) {
 	if (isEnvFieldMeta(def)) {
 		if (def.type === "enum") return (def.values ?? []).map((v) => JSON.stringify(v)).join(" | ") || "string";
@@ -44,6 +55,8 @@ function resolveEnvModules(input) {
 	const client = [];
 	const server = [];
 	for (const [key, def] of Object.entries(schema)) {
+		if (isRuntimeSchema(def)) throw new Error(`Invalid env field "${key}": a runtime schema (Standard Schema / safeParse) cannot be used in \`env.schema\` in ubean.config.ts.\nGenerated env modules are source files and only carry plain metadata, so the validator would be silently dropped.
+Use \`envField.*({ context, access })\` here, or move the field into \`defineEnv({ schema })\` in server code if you need schema validation.`);
 		const { context, access } = dimensionsOf(def);
 		if (context === "client" && access === "secret") throw new Error(`Invalid env field "${key}": context 'client' cannot be combined with access 'secret'. Secrets never reach the client — use \`{ context: 'server', access: 'secret' }\`.`);
 		const meta = isEnvFieldMeta(def) ? def : null;
@@ -56,6 +69,7 @@ function resolveEnvModules(input) {
 			optional,
 			sourceKey: key
 		};
+		if (meta?.description) spec.description = meta.description;
 		if (context === "client") {
 			const raw = importMetaEnv[key] ?? dotEnv[key];
 			const resolved = raw === void 0 || raw === "" ? meta?.default : raw;

package/dist/{virtual-modules-B3aE-Fmn.js → virtual-modules-7mD1FgVQ.js}

@@ -1,5 +1,6 @@
 import { _ as defineVirtualModule } from "./ssr-singleton-CUHZLgiO.js";
 import { extractScriptBlocks, parseScriptAst, statementCall } from "@ubean/vue/vite";
+import { resolvePageKind } from "@ubean/vue";
 import { isAbsolute, relative } from "pathe";
 //#region src/macros.ts
 /**
@@ -157,7 +158,7 @@ function createMetaVirtualModule() {
 		return `export const UBEAN_VERSION = "0.0.1";\nexport default { version: UBEAN_VERSION };`;
 	});
 }
-function createAppVirtualModule(apiRoutes, middlewares, pages, srcDir) {
+function createAppVirtualModule(apiRoutes, middlewares, pages, srcDir, pageExtensions) {
 	return defineVirtualModule("ubean:app-config", () => {
 		const routesJson = apiRoutes.map((r) => JSON.stringify({
 			relativePath: r.relativePath,
@@ -174,8 +175,7 @@ function createAppVirtualModule(apiRoutes, middlewares, pages, srcDir) {
 			relativePath: p.relativePath,
 			name: p.name,
 			route: p.route,
-			isReuse: p.isReuse,
-			isMeta: p.isMeta,
+			pageKind: resolvePageKind(p),
 			routable: p.routable,
 			layout: p.layout
 		}));
@@ -184,7 +184,7 @@ function createAppVirtualModule(apiRoutes, middlewares, pages, srcDir) {
 		return `
 const routeModules = import.meta.glob([${JSON.stringify(`${prefix}/routes/**/*.{ts,js,mjs}`)}], { eager: false });
 const middlewareModules = import.meta.glob([${JSON.stringify(`${prefix}/middleware/**/*.{ts,js,mjs}`)}], { eager: false });
-const pageModules = import.meta.glob([${JSON.stringify(`${prefix}/pages/**/*.{vue,ts,tsx,js,jsx}`)}], { eager: false });
+const pageModules = import.meta.glob([${JSON.stringify(`${prefix}/pages/**/*.{${pageExtensions ?? "vue,ts,tsx,js,jsx"}}`)}], { eager: false });
 
 const _srcPrefix = ${JSON.stringify(prefix)};
 function normalizeKey(p) {

package/dist/{vite--HujaLpA.js → vite-k9_n0K9x.js}

@@ -1,9 +1,10 @@
 import { a as ssrSingletonProdOptimizeExclude, g as createVirtualRegistry, o as ssrSingletonProdSsr, x as __exportAll } from "./ssr-singleton-CUHZLgiO.js";
-import { a as createRoutingVirtualModule, i as createPagesVirtualModule, n as createLocalesVirtualModule, r as createMetaVirtualModule, s as transformMacros, t as createAppVirtualModule } from "./virtual-modules-B3aE-Fmn.js";
-import { a as generateOpenApiTypes, i as generateTypes } from "./codegen-CUlE95gB.js";
-import { _ as sendWebResponse, a as createServerEntryVirtualModule, d as ensureDevApp, i as createClientEntryVirtualModule, n as ubeanVite, o as createVueAppEntryVirtualModule, r as composeHeadScripts, s as createVuePagesVirtualModule, v as toWebRequest, x as getDevScanCoordinator } from "./vue-Z4wVSxSE.js";
+import { a as createRoutingVirtualModule, i as createPagesVirtualModule, n as createLocalesVirtualModule, r as createMetaVirtualModule, s as transformMacros, t as createAppVirtualModule } from "./virtual-modules-7mD1FgVQ.js";
+import { a as generateOpenApiTypes, i as generateTypes } from "./codegen-RzEXvOPR.js";
+import { _ as sendWebResponse, a as createServerEntryVirtualModule, d as ensureDevApp, i as createClientEntryVirtualModule, n as ubeanVite, o as createVueAppEntryVirtualModule, r as composeHeadScripts, s as createVuePagesVirtualModule, v as toWebRequest, x as getDevScanCoordinator } from "./vue-lK-WDLZZ.js";
 import { createStaticSsgRenderer } from "./static-render.js";
 import { prerender, resolvePrerenderStaticDir } from "./prerender.js";
+import { resolvePageKind } from "@ubean/vue";
 import { dirname, isAbsolute, join, relative, resolve } from "pathe";
 import * as nodeFs from "node:fs";
 import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
@@ -35,6 +36,35 @@ function localeVueParamFromI18n(config) {
 	}) || void 0;
 }
 //#endregion
+//#region src/page-glob.ts
+/**
+* 页面 glob 的扩展名集合。
+*
+* `import.meta.glob` 的范围必须与扫描器一致，否则会出现「扫描说不含 tsx、产物却
+* 仍然把 `src/pages/*.tsx` 拉进构建」→ 构建期 `[PARSE_ERROR] Unexpected JSX expression`
+* （关掉 JSX 时依然报错的真实原因）。
+*
+* 两类后缀与 `pages.extensions` 无关、始终参与：
+* - `ts` / `js` —— `.reuse.ts` / `.meta.ts`（及其 `.js` 版本）是纯元数据文件
+*   （只含 `definePage`），扫描器用独立 pattern `**\/*.reuse.{ts,js}` /
+*   `**\/*.meta.{ts,js}` 收起，**不受 `extensions` 影响**。glob 缺了 ts/js，
+*   元数据页能扫到却加载不到 → 路由表与实际可加载模块脱节。
+*   顺带覆盖用户把 `ts` 显式写进 `extensions` 的情形。
+* - `md` / `mdx` —— markdown 页面，由 `markdown` 开关决定加不加
+*/
+function pageGlobExtensions(extensions, markdownExts = []) {
+	const base = extensions && extensions.length > 0 ? extensions : [
+		"vue",
+		"tsx",
+		"jsx"
+	];
+	const all = new Set(base);
+	all.add("ts");
+	all.add("js");
+	for (const ext of markdownExts) all.add(ext);
+	return [...all].join(",");
+}
+//#endregion
 //#region src/ssg-entry.ts
 /**
 * 生成 renderer setup 代码块（`_rendererRoutes` + `_pageRenderer`）。
@@ -64,7 +94,7 @@ const _localeVueParam = ${JSON.stringify(localeVueParam)};
 const _pageToRoute = p => {
   // For reuse routes, load the target page's module (the .reuse.ts file
   // only contains definePage metadata, not a Vue component).
-  const _targetPage = p.isReuse && p.reuseTarget ? _pages.find(tp => tp.name === p.reuseTarget) : undefined;
+  const _targetPage = p.pageKind === 'reuse' && p.reuseTarget ? _pages.find(tp => tp.name === p.reuseTarget) : undefined;
   const _loaderKey = _targetPage?.relativePath || p.relativePath;
   return {
     path: _localeVueParam
@@ -80,7 +110,10 @@ const _pageToRoute = p => {
     meta: {
       layout: p.layout === false ? false : p.layout || _defaultLayout,
       pageName: p.name,
-      cache: p.cache === true ? true : undefined
+      cache: p.cache === true ? true : undefined,
+      /* 同客户端 buildRouteMeta：透传 definePage({ meta })。否则靠 meta（如 iframeUrl）
+         取参数的页面在 SSR 首屏渲染空态，水合后才有值。 */
+      ...(p.pageMeta?.meta || undefined)
     }
   };
 };
@@ -264,7 +297,7 @@ export async function renderStaticPage(input) {
 
   // loader 检测 warn（模块加载有缓存，此处与渲染共用同一实例）
   const _targetPage =
-    page.isReuse && page.reuseTarget ? _pages.find(tp => tp.name === page.reuseTarget) : undefined;
+    page.pageKind === 'reuse' && page.reuseTarget ? _pages.find(tp => tp.name === page.reuseTarget) : undefined;
   const _loaderKey = (_targetPage && _targetPage.relativePath) || page.relativePath;
   const _modLoader = pageLoaders[_loaderKey];
   if (_modLoader && !_loaderWarned.has(page.name)) {
@@ -1415,7 +1448,7 @@ function toVitePath(p) {
 /**
 * 把扫描到的页面序列化进服务端入口（`const _pages = [...]`）。
 *
-* **白名单必须覆盖语义字段**：此前只序列化了 `relativePath/name/route/layout/reuseTarget/isReuse/
+* **白名单必须覆盖语义字段**：此前只序列化了 `relativePath/name/route/layout/reuseTarget/pageKind/
 * pageMeta`，于是 `matchers` / `slot` **在生产构建里丢失** ——
 * dev 用扫描得到的活对象（`enhanceDevApp` / `buildDevSsrRoutes` 直接拿 `scanResult.pages`），所以本地
 * 一切正常，只有构建产物坏掉：带着 `[id=numeric]` 的路由在 dev 返回 404、在生产返回 200（实测）。
@@ -1434,8 +1467,7 @@ function serializePagesForEntry(pages) {
 		path: p.path,
 		layout: p.layout,
 		cache: p.cache,
-		isReuse: p.isReuse,
-		isMeta: p.isMeta,
+		pageKind: resolvePageKind(p),
 		routable: p.routable,
 		isMarkdown: p.isMarkdown,
 		reuseTarget: p.reuseTarget,
@@ -1453,6 +1485,8 @@ async function generateVirtualModulesToDisk(cwd, config, scanResult, virtualDir,
 	const srcDirAbs = resolve(cwd, config.srcDir);
 	const viteSrcDir = toVitePath(relative(cwd, srcDirAbs));
 	const viteSrcPrefix = viteSrcDir ? `/${viteSrcDir}` : "";
+	const mdPageExts = config.markdown?.enabled === false ? [] : config.markdown?.mdx === true ? ["md", "mdx"] : ["md"];
+	const pagesExts = pageGlobExtensions(config.pages?.extensions, mdPageExts);
 	registry.register(createRoutingVirtualModule(scanResult.apiRoutes.map((r) => ({
 		method: r.method?.toUpperCase() || "ALL",
 		path: r.route,
@@ -1481,7 +1515,7 @@ async function generateVirtualModulesToDisk(cwd, config, scanResult, virtualDir,
 		registry.register(createVueAppEntryVirtualModule(scanResult.appEntry));
 		registry.register(createClientEntryVirtualModule());
 	}
-	registry.register(createAppVirtualModule(scanResult.apiRoutes, scanResult.middlewares, hasPages ? scanResult.pages : [], viteSrcPrefix || "/"));
+	registry.register(createAppVirtualModule(scanResult.apiRoutes, scanResult.middlewares, hasPages ? scanResult.pages : [], viteSrcPrefix || "/", pagesExts));
 	registry.register(createLocalesVirtualModule(scanResult.locales, scanResult.defaultLocale, viteSrcPrefix || "/", serializeI18nConfig(config.i18n)));
 	if (hasServer) registry.register(createServerEntryVirtualModule(scanResult.serverEntry));
 	async function writeModule(id, filename, header = "// Auto-generated by ubean\n") {
@@ -1501,7 +1535,7 @@ async function generateVirtualModulesToDisk(cwd, config, scanResult, virtualDir,
 	}
 	if (hasServer) await writeModule("virtual:ubean-server", "server-entry.ts", "");
 	await writeFile(join(virtualDir, "islands-registry.ts"), "export const islands = {};\n", "utf-8");
-	const pagesGlob = JSON.stringify(`${viteSrcPrefix}/pages/**/*.{vue,ts,tsx,js,jsx,md,mdx}`);
+	const pagesGlob = JSON.stringify(`${viteSrcPrefix}/pages/**/*.{${pagesExts}}`);
 	const routesGlob = JSON.stringify(`${viteSrcPrefix}/routes/**/*.{ts,js,mjs}`);
 	const middlewareGlob = JSON.stringify(`${viteSrcPrefix}/middleware/**/*.{ts,js,mjs}`);
 	const layoutsGlob = JSON.stringify(`${viteSrcPrefix}/layouts/**/*.{vue,ts}`);
@@ -2598,7 +2632,8 @@ function ubeanPlugin(options) {
 						cwd: ubeanConfig.rootDir,
 						srcDir: ubeanConfig.srcDir,
 						dirs: ubeanConfig.dir,
-						ignore: ubeanConfig.scanOptions?.ignore
+						ignore: ubeanConfig.scanOptions?.ignore,
+						pageExtensions: ubeanConfig.pages?.extensions
 					});
 					const { snapshot: contentSnapshot } = await loadContentForBuild(ubeanConfig.rootDir, ubeanConfig.content);
 					await runEnvBuilds(builder, await prepareBuild(createBuildContext({
@@ -2682,6 +2717,7 @@ function ubeanPlugin(options) {
 				srcDir: ubeanConfig.srcDir,
 				dirs: ubeanConfig.dir,
 				ignore: ubeanConfig.scanOptions?.ignore,
+				pageExtensions: ubeanConfig.pages?.extensions,
 				source,
 				scan: () => scanProjectOnce(),
 				reload: () => server.ws.send({ type: "full-reload" }),
@@ -2762,7 +2798,8 @@ function ubeanPlugin(options) {
 			cwd: ubeanConfig.rootDir,
 			srcDir: ubeanConfig.srcDir,
 			dirs: ubeanConfig.dir,
-			ignore: ubeanConfig.scanOptions?.ignore
+			ignore: ubeanConfig.scanOptions?.ignore,
+			pageExtensions: ubeanConfig.pages?.extensions
 		});
 	}
 	async function scanAndRegister() {
@@ -2840,7 +2877,7 @@ function ubeanPlugin(options) {
 			isDefault: l.isDefault
 		})), ubeanConfig.rootDir));
 		virtualRegistry.register(createMetaVirtualModule());
-		virtualRegistry.register(createAppVirtualModule(result.apiRoutes, result.middlewares, result.pages, viteSrcPrefix || "/"));
+		virtualRegistry.register(createAppVirtualModule(result.apiRoutes, result.middlewares, result.pages, viteSrcPrefix || "/", pageGlobExtensions(ubeanConfig.pages?.extensions, ubeanConfig.markdown?.enabled === false ? [] : ubeanConfig.markdown?.mdx === true ? ["md", "mdx"] : ["md"])));
 		virtualRegistry.register(createLocalesVirtualModule(result.locales, result.defaultLocale, viteSrcPrefix || "/", serializeI18nConfig(ubeanConfig.i18n)));
 		await maybeGenerateRouteFiles(ubeanConfig, result).catch((err) => {
 			console.warn("[ubean:core] Route file generation failed:", err?.message || err);

package/dist/vite.d.ts

@@ -404,6 +404,12 @@ interface DevSsrRoute {
     layout: string | string[] | false | null;
     pageName: string;
     cache?: true;
+    /**
+     * 其余键是 `definePage({ meta })` 的透传（`iframeUrl` / `title` / `i18nKey` …）。
+     * 不声明的话，用到这些 meta 的页面（例如按 `meta.iframeUrl` 取地址的内嵌页）
+     * 在 SSR 首屏渲染成空态，水合后客户端才有值 —— 首屏与水合结果不一致。
+     */
+    [key: string]: unknown;
   };
 }
 interface DevSsrRoutesOptions {

package/dist/vite.js

@@ -1,4 +1,4 @@
 import { g as createVirtualRegistry } from "./ssr-singleton-CUHZLgiO.js";
-import { A as buildDevSsrRoutes, C as peekDevScanCoordinator, D as resolveDevSecurityHeaders, E as createDevAppReady, O as resolveLocaleVueParam, S as onDevScan, T as createDevApp, _ as sendWebResponse, b as createDevScanCoordinator, c as DEVTOOLS_PASS_THROUGH_PREFIXES, d as ensureDevApp, f as getDevApp, g as ubeanDevRequestPlugin, h as isViteResourceRequest, j as toVueRouterPagePath, k as enhanceDevApp, l as collectDevCssLinks, m as isFrameworkHtmlPage, p as injectStylesheetLinks, u as createUbeanRequestHandlers, v as toWebRequest, w as bootstrapDevApp, x as getDevScanCoordinator, y as DEV_SCAN_DIRS } from "./vue-Z4wVSxSE.js";
-import { D as createCloudflarePreviewRunner, E as MINIFLARE_INSTALL_HINT, O as defaultLoadMiniflare, _ as ubeanPreviewPlugin, a as createEnvRunnerTransport, c as getDevWorkerEntrySource, d as attachPreviewMiddleware, f as createPreviewMiddleware, g as sendPreviewStatus, h as sendPreviewFile, i as bridgeEnvRunnerInvokes, k as readCompatibilityDate, l as invalidateDevWorkerModules, m as resolvePreviewFile, n as UBEAN_DEV_ENV_NAME, o as createUbeanDevEnvironmentFactory, p as previewMimeType, r as UbeanDevEnvironment, s as DEV_WORKER_FILE, t as ubeanPlugin, u as writeDevWorkerEntry } from "./vite--HujaLpA.js";
+import { A as buildDevSsrRoutes, C as peekDevScanCoordinator, D as resolveDevSecurityHeaders, E as createDevAppReady, O as resolveLocaleVueParam, S as onDevScan, T as createDevApp, _ as sendWebResponse, b as createDevScanCoordinator, c as DEVTOOLS_PASS_THROUGH_PREFIXES, d as ensureDevApp, f as getDevApp, g as ubeanDevRequestPlugin, h as isViteResourceRequest, j as toVueRouterPagePath, k as enhanceDevApp, l as collectDevCssLinks, m as isFrameworkHtmlPage, p as injectStylesheetLinks, u as createUbeanRequestHandlers, v as toWebRequest, w as bootstrapDevApp, x as getDevScanCoordinator, y as DEV_SCAN_DIRS } from "./vue-lK-WDLZZ.js";
+import { D as createCloudflarePreviewRunner, E as MINIFLARE_INSTALL_HINT, O as defaultLoadMiniflare, _ as ubeanPreviewPlugin, a as createEnvRunnerTransport, c as getDevWorkerEntrySource, d as attachPreviewMiddleware, f as createPreviewMiddleware, g as sendPreviewStatus, h as sendPreviewFile, i as bridgeEnvRunnerInvokes, k as readCompatibilityDate, l as invalidateDevWorkerModules, m as resolvePreviewFile, n as UBEAN_DEV_ENV_NAME, o as createUbeanDevEnvironmentFactory, p as previewMimeType, r as UbeanDevEnvironment, s as DEV_WORKER_FILE, t as ubeanPlugin, u as writeDevWorkerEntry } from "./vite-k9_n0K9x.js";
 export { DEVTOOLS_PASS_THROUGH_PREFIXES, DEV_SCAN_DIRS, DEV_WORKER_FILE, MINIFLARE_INSTALL_HINT, UBEAN_DEV_ENV_NAME, UbeanDevEnvironment, attachPreviewMiddleware, bootstrapDevApp, bridgeEnvRunnerInvokes, buildDevSsrRoutes, collectDevCssLinks, createCloudflarePreviewRunner, createDevApp, createDevAppReady, createDevScanCoordinator, createEnvRunnerTransport, createPreviewMiddleware, createUbeanDevEnvironmentFactory, createUbeanRequestHandlers, createVirtualRegistry, defaultLoadMiniflare, enhanceDevApp, ensureDevApp, getDevApp, getDevScanCoordinator, getDevWorkerEntrySource, injectStylesheetLinks, invalidateDevWorkerModules, isFrameworkHtmlPage, isViteResourceRequest, onDevScan, peekDevScanCoordinator, previewMimeType, readCompatibilityDate, resolveDevSecurityHeaders, resolveLocaleVueParam, resolvePreviewFile, sendPreviewFile, sendPreviewStatus, sendWebResponse, toVueRouterPagePath, toWebRequest, ubeanDevRequestPlugin, ubeanPlugin, ubeanPreviewPlugin, writeDevWorkerEntry };

package/dist/{vue-Z4wVSxSE.js → vue-lK-WDLZZ.js}

@@ -1,10 +1,11 @@
 import { _ as defineVirtualModule, c as getComponentResolvers, g as createVirtualRegistry, i as ssrSingletonDevPolicy, l as getCssImports, u as getHeadScripts } from "./ssr-singleton-CUHZLgiO.js";
-import { D as resolveComponentsConfig, E as resolveAutoImportsConfig, O as toArray, S as getAutoImportPresets, f as COMPONENT_HALF_GLOBS } from "./codegen-CUlE95gB.js";
+import { D as resolveComponentsConfig, E as resolveAutoImportsConfig, O as toArray, S as getAutoImportPresets, f as COMPONENT_HALF_GLOBS } from "./codegen-RzEXvOPR.js";
 import { createRequire } from "node:module";
 import { generatePagesModuleSource } from "@ubean/vue/vite";
+import { resolvePageKind } from "@ubean/vue";
 import { isAbsolute, join, normalize, relative, resolve } from "pathe";
 import { existsSync } from "node:fs";
-import { loadUbeanConfig, localePathsOf } from "@ubean/config";
+import { loadUbeanConfig, localePathsOf, resolvePageCompilers } from "@ubean/config";
 import { scanProject } from "@ubean/scan";
 import { applyServerConfig, createUbeanApp } from "@ubean/app";
 import { getVueLocaleParam, toVueRouterLocalePath } from "@ubean/i18n";
@@ -54,7 +55,7 @@ function buildDevSsrRoutes(options) {
 	const pageByName = /* @__PURE__ */ new Map();
 	for (const page of routablePages) pageByName.set(page.name, page);
 	const componentFor = (page) => {
-		const fullPath = (page.isReuse && page.reuseTarget ? pageByName.get(page.reuseTarget) : void 0)?.fullPath || page.fullPath;
+		const fullPath = (resolvePageKind(page) === "reuse" && page.reuseTarget ? pageByName.get(page.reuseTarget) : void 0)?.fullPath || page.fullPath;
 		return async () => await loadComponent(fullPath);
 	};
 	const routeFor = (page) => ({
@@ -64,7 +65,8 @@ function buildDevSsrRoutes(options) {
 		meta: {
 			layout: page.layout === false ? false : page.layout || defaultLayout,
 			pageName: page.name,
-			cache: page.cache === true ? true : void 0
+			cache: page.cache === true ? true : void 0,
+			...page.pageMeta?.meta
 		}
 	});
 	const grouped = /* @__PURE__ */ new Map();
@@ -120,7 +122,7 @@ function enhanceDevApp(options) {
 	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;
+		const fullPath = (resolvePageKind(page) === "reuse" && page.reuseTarget ? pageByName.get(page.reuseTarget) : void 0)?.fullPath || page.fullPath;
 		pageLoaders[page.relativePath] = () => loadModule(fullPath);
 	}
 	app.options.pageLoaders = pageLoaders;
@@ -241,7 +243,8 @@ async function createDevApp(options) {
 		cwd: rootDir,
 		srcDir: config.srcDir,
 		dirs: config.dir,
-		ignore: config.scanOptions?.ignore
+		ignore: config.scanOptions?.ignore,
+		pageExtensions: config.pages?.extensions
 	});
 	const app = createUbeanApp({
 		rootDir,
@@ -1547,6 +1550,23 @@ export function resolveServerConfig(mode) {
 //#endregion
 //#region src/vue-plugin.ts
 const VUE_PLUGIN_INCLUDE = [/\.vue$/, /\.md$/];
+/**
+* 懒加载 `@vitejs/plugin-vue-jsx`。
+*
+* 用 `createRequire` 而不是静态 import：只有真的写了 JSX 页面时才付 babel 链路的加载
+* 成本（`@babel/core` + `@babel/plugin-transform-typescript` + `@vue/babel-plugin-jsx`）。
+* 同时用 ESM interop 兼容默认导出与具名导出两种形状（不同版本各写过一种）。
+*/
+function createVueJsxPlugin() {
+	const require = createRequire(import.meta.url);
+	let mod;
+	try {
+		mod = require("@vitejs/plugin-vue-jsx");
+	} catch {
+		throw new Error("[ubean] `pages.extensions` 含 `tsx`/`jsx`，需要 `@vitejs/plugin-vue-jsx`，但未解析到该包。\n  pnpm add -D @vitejs/plugin-vue-jsx\n  或从 `ubean.config.ts` 去掉 JSX 扩展名（`pages: { extensions: ['vue'] }`）。");
+	}
+	return (mod?.default?.default ?? mod?.default ?? mod)();
+}
 const VIRTUAL_PAGES = "virtual:ubean-pages";
 const VIRTUAL_APP = "virtual:ubean-app";
 const VIRTUAL_CLIENT = "virtual:ubean-client-entry";
@@ -1620,7 +1640,8 @@ function ubeanVite(options) {
 			cwd: ubeanConfig.rootDir,
 			srcDir: ubeanConfig.srcDir,
 			dirs: ubeanConfig.dir,
-			ignore: ubeanConfig.scanOptions?.ignore
+			ignore: ubeanConfig.scanOptions?.ignore,
+			pageExtensions: ubeanConfig.pages?.extensions
 		});
 	}
 	async function scanAndRegister() {
@@ -1737,6 +1758,7 @@ function ubeanVite(options) {
 				srcDir: ubeanConfig.srcDir,
 				dirs: ubeanConfig.dir,
 				ignore: ubeanConfig.scanOptions?.ignore,
+				pageExtensions: ubeanConfig.pages?.extensions,
 				source,
 				scan: scanProjectOnce,
 				reload: () => server.ws.send({ type: "full-reload" }),
@@ -1756,10 +1778,12 @@ function ubeanVite(options) {
 			});
 		}
 	}];
-	if (options.vue !== false) plugins.unshift(vue({
+	const pageCompilers = resolvePageCompilers(ubeanConfig.pages?.extensions ?? []);
+	if (options.vue !== false && pageCompilers.vue) plugins.unshift(vue({
 		include: VUE_PLUGIN_INCLUDE,
 		template: { compilerOptions: { isCustomElement: (tag) => tag.startsWith("ubean-") } }
 	}));
+	if (pageCompilers.jsx) plugins.push(createVueJsxPlugin());
 	if (ubeanConfig.i18n?.enabled !== false) plugins.push(VueI18nPlugin({
 		include: [join(srcDir, "locales/**")],
 		ssr: true,

package/dist/vue.js

@@ -1 +1 @@
-export { t as VUE_PLUGIN_INCLUDE, r as composeHeadScripts, i as createClientEntryVirtualModule, a as createServerEntryVirtualModule, o as createVueAppEntryVirtualModule, s as createVuePagesVirtualModule, n as default, n as ubeanVite } from "./vue-Z4wVSxSE.js";
+export { t as VUE_PLUGIN_INCLUDE, r as composeHeadScripts, i as createClientEntryVirtualModule, a as createServerEntryVirtualModule, o as createVueAppEntryVirtualModule, s as createVuePagesVirtualModule, n as default, n as ubeanVite } from "./vue-lK-WDLZZ.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ubean/build",
-  "version": "0.6.7",
+  "version": "0.6.9",
   "description": "Vite plugins, production build, SSG prerender, type codegen, and Server Actions plugin for ubean",
   "files": [
     "dist"
@@ -49,20 +49,21 @@
   },
   "dependencies": {
     "@intlify/unplugin-vue-i18n": "11.2.7",
-    "@ubean/app": "0.6.7",
-    "@ubean/client": "0.6.7",
-    "@ubean/config": "0.6.7",
-    "@ubean/i18n": "0.6.7",
-    "@ubean/islands": "0.6.7",
-    "@ubean/markdown": "0.6.7",
-    "@ubean/pages": "0.6.7",
-    "@ubean/preset": "0.6.7",
-    "@ubean/routes": "0.6.7",
-    "@ubean/scan": "0.6.7",
-    "@ubean/server": "0.6.7",
-    "@ubean/shared": "0.6.7",
-    "@ubean/vue": "0.6.7",
+    "@ubean/app": "0.6.9",
+    "@ubean/client": "0.6.9",
+    "@ubean/config": "0.6.9",
+    "@ubean/i18n": "0.6.9",
+    "@ubean/islands": "0.6.9",
+    "@ubean/markdown": "0.6.9",
+    "@ubean/pages": "0.6.9",
+    "@ubean/preset": "0.6.9",
+    "@ubean/routes": "0.6.9",
+    "@ubean/scan": "0.6.9",
+    "@ubean/server": "0.6.9",
+    "@ubean/shared": "0.6.9",
+    "@ubean/vue": "0.6.9",
     "@vitejs/plugin-vue": "^6.0.10",
+    "@vitejs/plugin-vue-jsx": "^5.1.6",
     "openapi-typescript": "^7.13.0",
     "pathe": "^2.0.3",
     "tinyglobby": "^0.2.17",