@ubean/build 0.5.2 → 0.6.0-beta.2

package/dist/actions-plugin.js

@@ -63,11 +63,16 @@ function findBalanced(code, openChar, closeChar, startIdx) {
 }
 /**
 * 计算项目相对路径(用于 action ID 生成)。
+*
+* **自己负责去掉 query 与虚拟前缀**：调用方可能传原始 id（`Page.vue?vue&type=script&lang.ts`），
+* 带 query 算出的 id 与不带 query 的不是同一个 —— 客户端 stub 与 服务端注册因此会对不上。
+* 插件入口已经规范化过一次，这里再兜一次，让这两个变换函数单独用也正确。
 */
 function toProjectRelative(filePath, root) {
-	let rel = filePath;
+	const cleanPath = filePath.split("?")[0].replace(/^\0/, "");
+	let rel = cleanPath;
 	if (root) try {
-		rel = relative(root, filePath);
+		rel = relative(root, cleanPath);
 	} catch {}
 	return rel.replace(/\\/g, "/");
 }
@@ -353,8 +358,51 @@ function transformActionsForClient(code, filePath, root) {
 		const replacement = `__ubean_createActionStub(${JSON.stringify(id)})`;
 		result = result.slice(0, call.start) + replacement + result.slice(call.end + 1);
 	}
+	result = stripUnusedSpecifiers(result, [
+		"defineAction",
+		"fail",
+		"ActionError",
+		"defineServerFn"
+	]);
 	const importStmt = `import { createActionStub as __ubean_createActionStub } from '@ubean/routes/runtime';\n`;
-	if (!result.includes("@ubean/routes/runtime'")) result = importStmt + result;
+	if (!result.includes("@ubean/routes/runtime'")) result = injectImport(result, importStmt);
+	return result;
+}
+/**
+* 注入 import：JS/TS 放到文件顶部；**SFC 放到 `<script>` 块内**。
+*
+* 必须是块内 —— `@vitejs/plugin-vue` 会把 script 块的 import 提升进它编译出的主模块，放在 SFC
+* 顶部（`<script>` 之前）会直接变成非法 SFC。这也是「转换必须落在主模块而不是 `?type=script`
+* 子请求」的原因：主模块才是 Vue 真正编译的那份（脚本子请求的转换结果不会被使用）。
+*/
+function injectImport(code, importStmt) {
+	if (!code.trimStart().startsWith("<")) return importStmt + code;
+	const scriptTag = /<script\b[^>]*>/.exec(code);
+	if (!scriptTag) return importStmt + code;
+	const insertAt = scriptTag.index + scriptTag[0].length;
+	return `${code.slice(0, insertAt)}\n${importStmt}${code.slice(insertAt)}`;
+}
+/**
+* 删除已无引用的具名 import 说明符（并清理空掉的 import 语句）。
+*
+* 只处理「命名导入 + from '…'」这一种形态（框架约定：服务端 API 从 `ubean/server` 等入口具名导入）。
+* 判定用「删除 import 语句后名字是否还出现」——够用且不引入解析器依赖；名字出现在字符串/注释里
+* 时会保守地保留该说明符（保留是安全的，删除才危险）。
+*/
+function stripUnusedSpecifiers(code, names) {
+	let result = code;
+	for (const name of new Set(names)) {
+		const match = new RegExp(`^import\\s*\\{([^}]*)\\}\\s*from\\s*(['"][^'"]+['"]);?[ \\t]*$`, "m").exec(result);
+		if (!match) continue;
+		const specifiers = match[1].split(",").map((part) => part.trim()).filter(Boolean);
+		const target = specifiers.find((spec) => spec === name || spec === `${name} as ${name}`);
+		if (!target) continue;
+		const withoutImport = result.replace(match[0], "");
+		if (new RegExp(`\\b${name}\\b`).test(withoutImport)) continue;
+		const remaining = specifiers.filter((spec) => spec !== target);
+		const replacement = remaining.length > 0 ? `import { ${remaining.join(", ")} } from ${match[2]};` : "";
+		result = result.replace(match[0], replacement);
+	}
 	return result;
 }
 /**
@@ -370,13 +418,14 @@ function ubeanServerActionsPlugin(options = {}) {
 		enforce: "pre",
 		transform(code, id, transformOptions) {
 			if (id.includes("/node_modules/") || id.includes("\0")) return null;
-			if (!/\.(ts|js|mts|mjs|tsx|jsx)$/.test(id)) return null;
+			const [filePath, query = ""] = id.split("?");
+			if (!(filePath.endsWith(".vue") && (!query || /(^|&)(vue|type=script)(&|$)/.test(query))) && !/\.(ts|js|mts|mjs|tsx|jsx)$/.test(filePath)) return null;
 			if (!hasDefineActionCall(code)) return null;
 			if (transformOptions?.ssr === true) {
-				const transformed = transformActionsForServer(code, id, root);
+				const transformed = transformActionsForServer(code, filePath, root);
 				return transformed ? { code: transformed } : null;
 			}
-			const transformed = transformActionsForClient(code, id, root);
+			const transformed = transformActionsForClient(code, filePath, root);
 			return transformed ? { code: transformed } : null;
 		}
 	};

package/dist/codegen/index.d.ts

@@ -99,6 +99,8 @@ interface AutoImportResult {
   components: ComponentInfo[];
   autoImportsDtsPath: string;
   componentsDtsPath: string;
+  /** 虚拟组件（配对/单边基名）的 ambient 声明文件。没有虚拟组件时内容为空声明。 */
+  virtualComponentsDtsPath: string;
 }
 export declare function generateAutoImports(_scanResult: ScanResult, options: GenerateAutoImportsOptions): Promise<AutoImportResult>;
 export declare function getBuiltinComposables(): Import[];
@@ -228,6 +230,7 @@ export interface CodegenResult {
   i18nTypesPath?: string | null;
   autoImportsDtsPath?: string;
   componentsDtsPath?: string;
+  virtualComponentsDtsPath?: string;
   generated: string[];
 }
 export declare function generateTypes(result: ScanResult, options: CodegenOptions): Promise<CodegenResult>;

package/dist/codegen/index.js

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

package/dist/{codegen-B3oGeRtK.js → codegen-Up8-XhRo.js}

@@ -260,23 +260,55 @@ function transformImportPath(filePath, srcDir) {
 function isPackageSource(from) {
 	return !from.startsWith(".") && !from.startsWith("/") && !from.startsWith("~");
 }
+/**
+* `.server.vue` / `.client.vue` 不是独立组件，**不能**进自动导入表。
+*
+* 它们是同一个组件的两个变体：`.client.vue` 客户端独有、`.server.vue` 服务端独有，
+* 成对出现时（`Foo.server.vue` + `Foo.client.vue`）由 `@ubean/islands` 的
+* `resolveId` 按基名 `Foo.vue` 生成配对包装。用户侧的用法是**显式 import**
+* （`import Foo from './Foo.vue'` 或直接 import 某一半），不存在 `<Foo.server />` 这种写法。
+*
+* 而按文件名派生名字会把它们扫成 `Foo.server` / `Foo.client` —— 这些名字进了
+* `components.d.ts` 就是**非法 TypeScript**：ubean 自己的写入器会产出未加引号的
+* 带点键（接口成员不允许限定名，`@ts-nocheck` 也压不住语法错误），
+* unplugin-vue-components 重写时会产出 `const 'Foo.server': …`（`declare global` 块里
+* 非法）—— 结果示例项目的 `pnpm type-check` 直接红。
+*
+* codegen 侧在 `scanComponentsDir` 里按这个形态分区（半成品不进组件表，但会被收成虚拟组件）；
+* unplugin 没有分区逻辑，所以这份 glob 直接喂给它的 `globsExclude`（`./vue-plugin.ts`），
+* 保证两个写入器都不产出这些条目。
+*/
+const COMPONENT_HALF_GLOBS = ["**/*.server.vue", "**/*.client.vue"];
 async function scanComponentsDir(dir, srcDir, directoryAsNamespace, ignore = [
 	"**/*.test.*",
 	"**/*.spec.*",
 	"**/_*"
 ]) {
 	const components = [];
+	const virtualComponents = [];
 	const files = await glob("**/*.vue", {
 		cwd: dir,
 		dot: true,
 		ignore,
 		absolute: true
 	}).catch(() => []);
+	/** 基名 → 半成品真实路径（`/foo/Base.server.vue` 等）。 */
+	const halves = /* @__PURE__ */ new Map();
+	/** 同目录下真实存在的 `.vue` 基名 —— 它们由 TS 自行解析，不需要 ambient 声明。 */
+	const realBases = /* @__PURE__ */ new Set();
 	for (const fullPath of files.sort()) {
 		const relativeToSrc = toPosixPath(relative(srcDir, fullPath));
 		const relativeToDir = toPosixPath(relative(dir, fullPath));
 		const base = fileBasename(fullPath);
 		if (base.startsWith("_")) continue;
+		const half = /^(.*)\.(server|client)$/.exec(base);
+		if (half) {
+			const entry = halves.get(half[1]) ?? {};
+			entry[half[2]] = fullPath;
+			halves.set(half[1], entry);
+			continue;
+		}
+		realBases.add(base);
 		let name;
 		if (directoryAsNamespace) {
 			const dirPart = fileDirname(relativeToDir) === "." ? "" : fileDirname(relativeToDir);
@@ -291,7 +323,18 @@ async function scanComponentsDir(dir, srcDir, directoryAsNamespace, ignore = [
 			pascalName: name
 		});
 	}
-	return components;
+	for (const [baseName, pair] of halves) {
+		if (realBases.has(baseName)) continue;
+		virtualComponents.push({
+			baseName,
+			name: toPascalCase(baseName),
+			typeSourcePath: pair.server ?? pair.client
+		});
+	}
+	return {
+		components,
+		virtualComponents
+	};
 }
 async function generateAutoImports(_scanResult, options) {
 	const { cwd, srcDir, buildDir, dirs = {}, autoImports: autoImportsInput, components: componentsInput } = options;
@@ -304,6 +347,7 @@ async function generateAutoImports(_scanResult, options) {
 	const componentsDir = dirs.components || "components";
 	let composablesImports = [];
 	let components = [];
+	const virtualComponents = [];
 	const autoImportsDtsPath = join(outDir, "auto-imports.d.ts");
 	const componentsDtsPath = join(outDir, "components.d.ts");
 	if (resolvedAutoImports.enabled) {
@@ -330,29 +374,86 @@ async function generateAutoImports(_scanResult, options) {
 				from: transformImportPath(imp.from, srcDir)
 			};
 		});
-		const dtsContent = toTypeDeclarationFile(composablesImports, { resolvePath: (imp) => {
-			if (isPackageSource(imp.from)) return imp.from;
-			return transformImportPath(imp.from, srcDir);
-		} });
-		await writeFile(autoImportsDtsPath, dtsContent, "utf-8");
+		const resolveFrom = (from) => isPackageSource(from) ? from : transformImportPath(from, srcDir);
+		const dtsContent = toTypeDeclarationFile(composablesImports, { resolvePath: (imp) => resolveFrom(imp.from) });
+		await writeFile(autoImportsDtsPath, `${dtsContent}\n\n${buildTemplateAutoImportBlock(composablesImports, resolveFrom)}`, "utf-8");
 	} else await writeFile(autoImportsDtsPath, "// Auto-generated by ubean - auto-imports disabled\n/* eslint-disable */\n// @ts-nocheck\nexport {}\n", "utf-8");
 	if (resolvedComponents.enabled) {
 		const allComponentsDirs = [join(srcDir, componentsDir), ...resolvedComponents.options.dirs ?? []];
 		for (const dir of allComponentsDirs) {
 			const scanned = await scanComponentsDir(dir, srcDir, directoryAsNamespace);
-			components.push(...scanned);
+			components.push(...scanned.components);
+			virtualComponents.push(...scanned.virtualComponents);
 		}
 	}
 	const componentsDts = generateComponentsDts(components, componentsDtsPath);
 	await writeFile(componentsDtsPath, componentsDts, "utf-8");
+	const virtualComponentsDtsPath = join(outDir, "virtual-components.d.ts");
+	await writeFile(virtualComponentsDtsPath, generateVirtualComponentsDts(virtualComponents, virtualComponentsDtsPath), "utf-8");
 	return {
 		composablesImports,
 		components,
 		autoImportsDtsPath,
-		componentsDtsPath
+		componentsDtsPath,
+		virtualComponentsDtsPath
 	};
 }
 /**
+* 生成「模板里的自动导入」声明段（对齐 `AutoImport({ vueTemplate: true })` 的产物）。
+*
+* **为什么必须自己产出这段**：模板表达式里的标识符由 vue 的**组件实例类型**解析
+* （vue-tsc 把模板编译成 `__VLS_ctx.x`，即 `ComponentCustomProperties`），而不是走模块作用域的
+* 全局声明。只有 `declare global { const … }` 时，`<script setup>` 里的自动导入照常工作，而
+* **模板里**用同一个 helper 会报 `Property 'isPageCached' does not exist on type '{ $: … }'`。
+*
+* ubean 的 codegen 与 unplugin-auto-import 写的是同一份文件（谁后写谁赢），所以两边都必须产出
+* 这段：codegen 只在 `prepare` / CLI dev / build 跑，unplugin 在每次 Vite dev/build 重写 ——
+* 少一段就会出现「先跑 CLI 时红、跑过一次 dev 后变绿」这种漂移。
+*/
+function buildTemplateAutoImportBlock(imports, resolveFrom) {
+	return [
+		"// for vue template auto import",
+		"import { UnwrapRef } from 'vue'",
+		"declare module 'vue' {",
+		"  interface GlobalComponents {}",
+		"  interface ComponentCustomProperties {",
+		...imports.filter((imp) => imp.name && imp.from && imp.type !== true).map((imp) => `    readonly ${toDtsKey(imp.name)}: UnwrapRef<typeof import('${resolveFrom(imp.from)}')['${imp.name}']>`).sort(),
+		"  }",
+		"}"
+	].join("\n");
+}
+/**
+* 生成 `.ubean/virtual-components.d.ts` —— 虚拟组件（配对/单边基名）的 ambient 声明。
+*
+* 为什么必须单独一份文件：这份内容会被 `unplugin-vue-components` 的重写丢掉（它只捞
+* `GlobalComponents` 接口里的条目，周围的 `declare module` 语句一律不保留），而
+* `components.d.ts` 正是它拥有的文件。
+*
+* 用**通配**说明符（`*foo.vue`）而不是相对路径：`declare module` 里的相对路径只在「说明符
+* 字符串完全相同」时匹配，而同一个虚拟组件可以从任意目录、任意相对路径导入。通配声明只在
+* TS 无法解析到真实文件时才生效，因此不会遮蔽真实 `.vue` 文件。
+*
+* 类型取服务端变体（配对与 server-only 都有），单边 `.client.vue` 则取客户端变体 —— 与
+* 运行时首屏渲染的那一侧一致。
+*/
+function generateVirtualComponentsDts(virtual, dtsPath) {
+	const dtsDir = fileDirname(toPosixPath(normalize(dtsPath)));
+	const lines = [
+		"// Auto-generated by ubean - do not edit manually",
+		"/* eslint-disable */",
+		"// @ts-nocheck",
+		"",
+		"// 本文件刻意保持 script（非模块）语义，让下面的声明成为全局 ambient 声明。",
+		""
+	];
+	const sorted = [...virtual].sort((a, b) => a.baseName.localeCompare(b.baseName));
+	for (const comp of sorted) {
+		const rel = toPosixPath(relative(dtsDir, toPosixPath(normalize(comp.typeSourcePath))));
+		lines.push(`// ${comp.name}：磁盘上没有 ${comp.baseName}.vue，由 @ubean/islands 按同名 .server.vue / .client.vue 合成`, `declare module '*${comp.baseName}.vue' {`, `  const component: typeof import('./${rel}')['default'];`, "  export default component;", "}", "");
+	}
+	return `${lines.join("\n")}\n`;
+}
+/**
 * Generate the `.ubean/components.d.ts` in a format compatible with
 * unplugin-vue-components (both writers own the same file).
 *
@@ -390,12 +491,26 @@ function generateComponentsDts(components, dtsPath) {
 		"  export interface GlobalComponents {"
 	];
 	const sorted = [...entries.entries()].sort(([a], [b]) => a.localeCompare(b));
-	lines.push(...sorted.map(([name, declaration]) => `    ${name}: ${declaration}`));
+	lines.push(...sorted.map(([name, declaration]) => `    ${toDtsKey(name)}: ${declaration}`));
 	lines.push("  }");
 	lines.push("}");
 	lines.push("");
 	return `${lines.join("\n")}\n`;
 }
+/**
+* 接口成员名 → 合法的 TS 键。
+*
+* 名字里含 `.` 时（如 `My.Comp.vue` 这种文件名）直接写就是**限定名**，在接口里是语法
+* 错误 —— 而语法错误不受本文件顶部 `@ts-nocheck` 影响，整个 d.ts 会连累项目 type-check。
+* 加引号后是合法的字符串字面量键，且 unplugin-vue-components 重写时也用同样形式
+* （实测它把非标识符名写成 `'My.Comp': …`），两边不会互相反复改写。
+*
+* 注意这里只改**写法**不改名字：名字必须与 unplugin 的派生结果一致，否则两个写入器
+* 会各自重写同一份文件。
+*/
+function toDtsKey(name) {
+	return /^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name);
+}
 function getBuiltinComposables() {
 	const imports = [];
 	for (const preset of BUILTIN_PRESETS) for (const name of preset.imports) if (typeof name === "string") imports.push({
@@ -725,6 +840,12 @@ const CODEGEN_FILES = [
 		module: null,
 		required: true,
 		types: []
+	},
+	{
+		name: "virtual-components.d.ts",
+		module: null,
+		required: false,
+		types: []
 	}
 ];
 async function generateTypes(result, options) {
@@ -741,13 +862,13 @@ async function generateTypes(result, options) {
 	generated.push(pageTypesPath);
 	const i18nTypesPath = await generateI18nTypes(result, { outDir });
 	if (i18nTypesPath) generated.push(i18nTypesPath);
-	const { autoImportsDtsPath, componentsDtsPath } = await generateAutoImports(result, {
+	const { autoImportsDtsPath, componentsDtsPath, virtualComponentsDtsPath } = await generateAutoImports(result, {
 		cwd,
 		srcDir,
 		buildDir,
 		...autoImportOptions
 	});
-	generated.push(autoImportsDtsPath, componentsDtsPath);
+	generated.push(autoImportsDtsPath, componentsDtsPath, virtualComponentsDtsPath);
 	const manifest = {
 		contractVersion: 1,
 		generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -765,8 +886,9 @@ async function generateTypes(result, options) {
 		i18nTypesPath,
 		autoImportsDtsPath,
 		componentsDtsPath,
+		virtualComponentsDtsPath,
 		generated
 	};
 }
 //#endregion
-export { getUbeanComponentsConfig as C, toArray as E, getUbeanAutoImportConfig as S, resolveComponentsConfig as T, VUE_ROUTER_PRESET as _, generateOpenApiTypesFromServer as a, getAutoImportPresets as b, generateI18nTypes as c, HONO_OPENAPI_PRESET as d, UBEAN_CLIENT_PRESET as f, VUE_PRESET as g, VUE_MACROS_PRESET as h, generateOpenApiTypes as i, messagesToTsType as l, VUE_I18N_PRESET as m, CODEGEN_FILES as n, generatePageTypes as o, UBEAN_SERVER_PRESET as p, generateTypes as r, generateRouteTypes as s, CODEGEN_CONTRACT_VERSION as t, BUILTIN_PRESETS as u, generateAutoImports as v, resolveAutoImportsConfig as w, getBuiltinComposables as x, generateImportsTransform as y };
+export { getUbeanAutoImportConfig as C, toArray as D, resolveComponentsConfig as E, getBuiltinComposables as S, resolveAutoImportsConfig as T, VUE_PRESET as _, generateOpenApiTypesFromServer as a, generateImportsTransform as b, generateI18nTypes as c, COMPONENT_HALF_GLOBS as d, HONO_OPENAPI_PRESET as f, VUE_MACROS_PRESET as g, VUE_I18N_PRESET as h, generateOpenApiTypes as i, messagesToTsType as l, UBEAN_SERVER_PRESET as m, CODEGEN_FILES as n, generatePageTypes as o, UBEAN_CLIENT_PRESET as p, generateTypes as r, generateRouteTypes as s, CODEGEN_CONTRACT_VERSION as t, BUILTIN_PRESETS as u, VUE_ROUTER_PRESET as v, getUbeanComponentsConfig as w, getAutoImportPresets as x, generateAutoImports as y };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { a as defineVirtualModule, c as useVirtualRegistry, i as VirtualModuleTransform, n as VirtualModuleContext, o as defineVirtualModulePrefix, r as VirtualModuleRegistry, s as resetVirtualRegistry, t as VirtualModule } from "./virtual-registry-BF0jYPle.js";
+import { a as VirtualModuleTransform, c as defineVirtualModulePrefix, i as VirtualModuleResolver, l as resetVirtualRegistry, n as VirtualModuleContext, o as createVirtualRegistry, r as VirtualModuleRegistry, s as defineVirtualModule, t as VirtualModule, u as useVirtualRegistry } from "./virtual-registry-CaU8k-YP.js";
 import { CompiledLayout, CompiledMiddleware, CompiledPage, CompiledRoute } from "@ubean/routes";
 import { ScannedApiRoute, ScannedLocale, ScannedMiddleware, ScannedPageRoute } from "@ubean/scan";
 //#region src/macros.d.ts
@@ -96,4 +96,4 @@ export declare function createMetaVirtualModule(): VirtualModule;
 export declare function createAppVirtualModule(apiRoutes: ScannedApiRoute[], middlewares: ScannedMiddleware[], pages: ScannedPageRoute[], srcDir: string): VirtualModule;
 export declare function createLocalesVirtualModule(_locales: ScannedLocale[], defaultLocale: string | undefined, srcDir?: string, i18nConfigJson?: string): VirtualModule;
 //#endregion
-export { type VirtualModule, type VirtualModuleContext, VirtualModuleRegistry, type VirtualModuleTransform, defineVirtualModule, defineVirtualModulePrefix, resetVirtualRegistry, useVirtualRegistry };
+export { type VirtualModule, type VirtualModuleContext, VirtualModuleRegistry, type VirtualModuleResolver, type VirtualModuleTransform, createVirtualRegistry, defineVirtualModule, defineVirtualModulePrefix, resetVirtualRegistry, useVirtualRegistry };

package/dist/index.js

@@ -1,4 +1,3 @@
-import { a as useVirtualRegistry, i as resetVirtualRegistry, n as defineVirtualModule, r as defineVirtualModulePrefix, t as VirtualModuleRegistry } from "./virtual-registry-BWkaQHXN.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-vLkLkAfT.js";
-import { a as ssrSingletonProdOptimizeExclude, c as getCssImports, d as resetModuleRegistry, i as ssrSingletonDevPolicy, l as registerComponentResolver, n as SSR_SINGLETON_OPTIMIZE_EXCLUDE, o as ssrSingletonProdSsr, r as SSR_SINGLETON_PACKAGES, s as getComponentResolvers, t as SSR_SINGLETON_DEDUPE, u as registerCssImport } from "./ssr-singleton-CEQi_H6-.js";
-export { SSR_SINGLETON_DEDUPE, SSR_SINGLETON_OPTIMIZE_EXCLUDE, SSR_SINGLETON_PACKAGES, VirtualModuleRegistry, createAppVirtualModule, createLocalesVirtualModule, createMetaVirtualModule, createPagesVirtualModule, createRoutingVirtualModule, defineVirtualModule, defineVirtualModulePrefix, getComponentResolvers, getCssImports, registerComponentResolver, registerCssImport, resetModuleRegistry, resetVirtualRegistry, ssrSingletonDevPolicy, ssrSingletonProdOptimizeExclude, ssrSingletonProdSsr, stripMacros, transformMacros, useVirtualRegistry };
+import { _ as resetVirtualRegistry, a as ssrSingletonProdOptimizeExclude, c as getComponentResolvers, d as registerCssImport, f as resetModuleRegistry, g as defineVirtualModulePrefix, h as defineVirtualModule, i as ssrSingletonDevPolicy, l as getCssImports, m as createVirtualRegistry, n as SSR_SINGLETON_OPTIMIZE_EXCLUDE, o as ssrSingletonProdSsr, p as VirtualModuleRegistry, r as SSR_SINGLETON_PACKAGES, t as SSR_SINGLETON_DEDUPE, u as registerComponentResolver, v as useVirtualRegistry } from "./ssr-singleton-DPTawJSx.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-CvGWlsXj.js";
+export { SSR_SINGLETON_DEDUPE, SSR_SINGLETON_OPTIMIZE_EXCLUDE, SSR_SINGLETON_PACKAGES, VirtualModuleRegistry, createAppVirtualModule, createLocalesVirtualModule, createMetaVirtualModule, createPagesVirtualModule, createRoutingVirtualModule, createVirtualRegistry, defineVirtualModule, defineVirtualModulePrefix, getComponentResolvers, getCssImports, registerComponentResolver, registerCssImport, resetModuleRegistry, resetVirtualRegistry, ssrSingletonDevPolicy, ssrSingletonProdOptimizeExclude, ssrSingletonProdSsr, stripMacros, transformMacros, useVirtualRegistry };

package/dist/prerender.d.ts

@@ -1,4 +1,4 @@
-import { PrerenderConfig, PrerenderResult, RouteRule } from "@ubean/config";
+import { PrerenderConfig, PrerenderResult, ResolvedPrerenderConfig, RouteRule } from "@ubean/config";
 import { ScannedPageRoute } from "@ubean/scan";
 import { RouteRule as RouteRule$1 } from "@ubean/shared";
 //#region src/prerender.d.ts
@@ -128,6 +128,18 @@ export interface ExtractedPayload {
  */
 export declare function extractDataPayload(html: string, route: string): ExtractedPayload | null;
 export declare function writePrerenderedFile(filePath: string, html: string): Promise<void>;
+/**
+ * 预渲染产物的落盘目录（**唯一**计算处，`prerender()` 与搜索索引共用）。
+ *
+ * 优先用显式配置的 `prerender.staticDir`；未配置时从**本次构建的** `build.outputDir` 派生为
+ * `<outputDir>/public`。
+ *
+ * 为什么不能给 `staticDir` 一个写死的默认值（曾经是 `'dist/public'`）：`build.outputDir` 会被
+ * preset（`dist/aws` 等）与 `--outDir` 改动，而写死的默认值不跟着动 —— 实测 `ubean build --outDir
+ * .temp-x` 的客户端产物落在 `.temp-x/public`，预渲染 HTML 却写进了 `dist/public`：产物被劈成两
+ * 半，且失败是静默的（两边都不报错，只有产物树里少文件）。
+ */
+export declare function resolvePrerenderStaticDir(cwd: string, buildOutputDir: string, prerenderConfig: Pick<ResolvedPrerenderConfig, 'staticDir'>): string;
 export declare function prerender(options: PrerendererOptions): Promise<PrerenderResult>;
 export declare function generatePrerenderManifest(result: PrerenderResult, baseUrl?: string): {
   routes: string[];

package/dist/prerender.js

@@ -1,8 +1,8 @@
 import { STATIC_NOT_FOUND_ROUTE } from "./static-render.js";
-import { dirname, join } from "pathe";
+import { dirname, isAbsolute, join } from "pathe";
 import { resolvePrerenderConfig } from "@ubean/config";
-import { DATA_PAYLOAD_ID } from "@ubean/pages";
 import { mkdir, writeFile } from "node:fs/promises";
+import { DATA_PAYLOAD_ID } from "@ubean/pages";
 import { matchGlob } from "@ubean/shared";
 //#region src/prerender.ts
 const LINK_REGEX = /<a[^>]+href=["']([^"']+)["'][^>]*>/gi;
@@ -196,6 +196,21 @@ const _logger = {
 	success: (msg) => console.log(msg),
 	debug: (_msg) => {}
 };
+/**
+* 预渲染产物的落盘目录（**唯一**计算处，`prerender()` 与搜索索引共用）。
+*
+* 优先用显式配置的 `prerender.staticDir`；未配置时从**本次构建的** `build.outputDir` 派生为
+* `<outputDir>/public`。
+*
+* 为什么不能给 `staticDir` 一个写死的默认值（曾经是 `'dist/public'`）：`build.outputDir` 会被
+* preset（`dist/aws` 等）与 `--outDir` 改动，而写死的默认值不跟着动 —— 实测 `ubean build --outDir
+* .temp-x` 的客户端产物落在 `.temp-x/public`，预渲染 HTML 却写进了 `dist/public`：产物被劈成两
+* 半，且失败是静默的（两边都不报错，只有产物树里少文件）。
+*/
+function resolvePrerenderStaticDir(cwd, buildOutputDir, prerenderConfig) {
+	if (prerenderConfig.staticDir) return isAbsolute(prerenderConfig.staticDir) ? prerenderConfig.staticDir : join(cwd, prerenderConfig.staticDir);
+	return isAbsolute(buildOutputDir) ? join(buildOutputDir, "public") : join(cwd, buildOutputDir, "public");
+}
 async function prerender(options) {
 	const startTime = Date.now();
 	const config = resolvePrerenderConfig(options.prerender);
@@ -207,7 +222,7 @@ async function prerender(options) {
 		skipped: [],
 		duration: 0
 	};
-	const outputDir = join(options.cwd, config.staticDir);
+	const outputDir = resolvePrerenderStaticDir(options.cwd, options.outputDir, config);
 	const { routes: initialRoutes, skipped: initiallySkipped } = collectPrerenderRoutes(options.pages, {
 		all: config.all,
 		include: config.include,
@@ -309,4 +324,4 @@ function generatePrerenderManifest(result, baseUrl = "/") {
 	};
 }
 //#endregion
-export { collectPrerenderRoutes, extractDataPayload, extractLinks, extractPrerenderRoutesFromRules, generatePrerenderManifest, prerender, routeToDataFilePath, routeToFilePath, writePrerenderedFile };
+export { collectPrerenderRoutes, extractDataPayload, extractLinks, extractPrerenderRoutesFromRules, generatePrerenderManifest, prerender, resolvePrerenderStaticDir, routeToDataFilePath, routeToFilePath, writePrerenderedFile };

package/dist/production.d.ts

@@ -1,6 +1,20 @@
+import { r as VirtualModuleRegistry } from "./virtual-registry-CaU8k-YP.js";
 import { ResolvedConfig } from "@ubean/config";
-import { ScanResult } from "@ubean/scan";
 import { Preset } from "@ubean/preset";
+import { ScanResult } from "@ubean/scan";
+import { Plugin } from "vite";
+//#region src/vite/build-app.d.ts
+/**
+ * 一次 `createBuilder` 完成整套生产构建（`ubean build` 与 `vite build` 共用的唯一编排）。
+ *
+ * **驱动权声明**：本函数自己就是编排者，因此先在环境里声明「构建由调用方驱动」，让插件侧的
+ * `config` 钩子**不要**再注册它自己的 `builder.buildApp` —— 否则同一个 config 的 `builder` 字段
+ * 会被插件返回值合并掉，本函数的内联编排不再执行、`manifest` 保持 undefined，表现为**静默返回
+ * undefined**（RM-V36 把开关默认打开后由 `build-parity.test.ts` 实测撞到）。与 CLI 用的是同一个
+ * 环境变量，结束后还原，避免影响同进程内的其它调用。
+ */
+export declare function buildWithEnvironments(options: BuildOptions): Promise<BuildManifest>;
+//#endregion
 //#region src/production.d.ts
 export interface BuildOptions {
   cwd: string;
@@ -24,5 +38,47 @@ export interface BuildManifest {
   serverDir: string;
   preset: string;
 }
-export declare function buildProduction(options: BuildOptions): Promise<BuildManifest>;
+/**
+ * 把扫描到的页面序列化进服务端入口（`const _pages = [...]`）。
+ *
+ * **白名单必须覆盖语义字段**：此前只序列化了 `relativePath/name/route/layout/reuseTarget/isReuse/
+ * pageMeta`，于是 `matchers` / `slot` **在生产构建里丢失** ——
+ * dev 用扫描得到的活对象（`enhanceDevApp` / `buildDevSsrRoutes` 直接拿 `scanResult.pages`），所以本地
+ * 一切正常，只有构建产物坏掉：带着 `[id=numeric]` 的路由在 dev 返回 404、在生产返回 200（实测）。
+ * 这类「dev 正常、产物丢失元数据」的缺陷对用户最不友好，因此单独抽成函数并配单测
+ * （`packages/builder/test/page-metadata.test.ts`）。
+ *
+ * 不含 `fullPath`/`dirname`/`basename`（构建机上的文件系统细节，产物不需要）与 `frontmatter`
+ * （Markdown 页正文用，服务端路由不消费）。拦截路由的两个字段（`interceptFrom` /
+ * `interceptTarget`）曾在这份白名单里，随该约定一起移除（[docs/adr/0010] 刻意不做）。
+ */
+export declare function serializePagesForEntry(pages: ScanResult['pages']): string;
+export declare function generateVirtualModulesToDisk(cwd: string, config: ResolvedConfig, scanResult: ScanResult, virtualDir: string, preset: Preset, registry: VirtualModuleRegistry, contentSnapshot?: Record<string, unknown[]>): Promise<string>;
+export type PresetBuildConfig = ReturnType<typeof getPresetBuildConfig>;
+export declare function getPresetBuildConfig(preset: Preset): {
+  format: "esm";
+  target: string;
+  entryType: "node";
+  external: (string | RegExp)[];
+} | {
+  format: "esm";
+  target: string;
+  entryType: "worker";
+  external: (string | RegExp)[];
+} | {
+  format: "esm";
+  target: string;
+  entryType: "fetch";
+  external: (string | RegExp)[];
+};
+/**
+ * SSR 期的 islands 注册表空壳插件。
+ *
+ * 真正的注册表由 `ubeanIslandsPlugin` 在**客户端**构建期填充；SSR 期 islands 由服务端渲染
+ * （不水合），空壳即可 —— 但不能让它以裸 `virtual:ubean-islands-registry` 泄漏给 Node。
+ */
+export declare function createIslandsSsrStubPlugin(): Plugin;
+export declare function generateNodeServerEntry(): string;
+export declare function generateStandardHandlerEntry(): string;
+export declare function generateCloudflareWorkerEntry(): string;
 //#endregion