@ubean/build 0.4.4 → 0.4.6

package/dist/actions-plugin.d.ts

@@ -1,6 +1,6 @@
 import { Plugin } from "vite";
 //#region src/actions-plugin.d.ts
-interface ServerActionsPluginOptions {
+export interface ServerActionsPluginOptions {
   /**
    * The project root directory (used for computing stable action IDs).
    * Defaults to `process.cwd()` at plugin creation time.
@@ -32,31 +32,30 @@ interface DefineActionCall {
  *
  * 跳过注释内的匹配(如 JSDoc 示例)和函数声明(`function defineAction(`)。
  */
-declare function findDefineActionCalls(code: string): DefineActionCall[];
+export declare function findDefineActionCalls(code: string): DefineActionCall[];
 /**
  * 检测源码是否包含 `defineAction(` 调用。
  */
-declare function hasDefineActionCall(code: string): boolean;
+export declare function hasDefineActionCall(code: string): boolean;
 /**
  * 服务端转换:为每个 `defineAction()` 调用注入 `filePath`(以及缺失时的 `name`),
  * 确保 action ID 在 dev / build 之间稳定。
  *
  * 返回转换后的代码;若无 `defineAction` 调用则返回 `null`。
  */
-declare function transformActionsForServer(code: string, filePath: string, root: string): string | null;
+export declare function transformActionsForServer(code: string, filePath: string, root: string): string | null;
 /**
  * 客户端转换:将每个 `defineAction(...)` 调用替换为
  * `__ubean_createActionStub('<id>')`(别名 import,避免与用户代码冲突)。
  *
  * 返回转换后的代码(含注入的 import);若无 `defineAction` 调用则返回 `null`。
  */
-declare function transformActionsForClient(code: string, filePath: string, root: string): string | null;
+export declare function transformActionsForClient(code: string, filePath: string, root: string): string | null;
 /**
  * Vite 插件:Server Actions 的客户端/服务端拆分。
  *
  *  - 服务端(SSR):注入 `filePath`/`name` 到 `defineAction()` 选项。
  *  - 客户端(浏览器):将 `defineAction(...)` 替换为 `createActionStub('<id>')`。
  */
-declare function ubeanServerActionsPlugin(options?: ServerActionsPluginOptions): Plugin;
-//#endregion
-export { ServerActionsPluginOptions, findDefineActionCalls, hasDefineActionCall, transformActionsForClient, transformActionsForServer, ubeanServerActionsPlugin };
+export declare function ubeanServerActionsPlugin(options?: ServerActionsPluginOptions): Plugin;
+//#endregion

package/dist/codegen/index.d.ts

@@ -35,9 +35,9 @@ interface ResolvedAutoImports {
   options: AutoImportOptions;
 }
 /** 将 `boolean | AutoImportOptions` 归一化为分库开关 + 透传选项。 */
-declare function resolveAutoImportsConfig(input: boolean | AutoImportOptions | undefined): ResolvedAutoImports;
+export declare function resolveAutoImportsConfig(input: boolean | AutoImportOptions | undefined): ResolvedAutoImports;
 /** 按分库开关组装内置预设（顺序稳定：ubean client/server → vue → vue-router → vue-i18n → hono-openapi）。 */
-declare function getAutoImportPresets(resolved: ResolvedAutoImports): InlinePreset[];
+export declare function getAutoImportPresets(resolved: ResolvedAutoImports): InlinePreset[];
 interface ResolvedComponentsAutoImport {
   /** 目录扫描 + dts 总开关（`components: false` 时为 `false`；resolver 仍然生效）。 */
   enabled: boolean;
@@ -47,28 +47,28 @@ interface ResolvedComponentsAutoImport {
   options: ComponentsOptions;
 }
 /** 将 `boolean | ComponentsOptions` 归一化。 */
-declare function resolveComponentsConfig(input: boolean | ComponentsOptions | undefined): ResolvedComponentsAutoImport;
+export declare function resolveComponentsConfig(input: boolean | ComponentsOptions | undefined): ResolvedComponentsAutoImport;
 /** unplugin 系选项普遍使用 `Arrayable<T>`，合并进数组前先归一化。 */
-declare function toArray<T>(value: T | T[] | undefined): T[];
-declare const VUE_PRESET: InlinePreset;
-declare const VUE_MACROS_PRESET: InlinePreset;
+export declare function toArray<T>(value: T | T[] | undefined): T[];
+export declare const VUE_PRESET: InlinePreset;
+export declare const VUE_MACROS_PRESET: InlinePreset;
 /**
  * Client-safe symbols sourced from the first-class `ubean/client` entry.
  * These are safe to auto-import in Vue components (browser-side) because
  * `@ubean/client` has zero build-time dependencies and no `node:*` imports.
  */
-declare const UBEAN_CLIENT_PRESET: InlinePreset;
+export declare const UBEAN_CLIENT_PRESET: InlinePreset;
 /**
  * vue-router composables, sourced directly from `vue-router` (not re-exported
  * through `ubean/client` — third-party APIs are imported from their own packages).
  */
-declare const VUE_ROUTER_PRESET: InlinePreset;
+export declare const VUE_ROUTER_PRESET: InlinePreset;
 /**
  * vue-i18n Composition API, sourced directly from `vue-i18n` (ubean no longer
  * wraps `useI18n` — same instance is exposed by the framework-installed
  * vue-i18n plugin; `t` is destructured from the returned composer).
  */
-declare const VUE_I18N_PRESET: InlinePreset;
+export declare const VUE_I18N_PRESET: InlinePreset;
 /**
  * Server-only symbols sourced from the `ubean/server` aggregation entry
  * (`@ubean/app` + `@ubean/routes` + `@ubean/server` + `@ubean/shared/node`).
@@ -85,9 +85,9 @@ declare const VUE_I18N_PRESET: InlinePreset;
  * unplugin-auto-import emit a "Duplicated imports" warning, so they live in
  * the client preset only.
  */
-declare const UBEAN_SERVER_PRESET: InlinePreset;
-declare const HONO_OPENAPI_PRESET: InlinePreset;
-declare const BUILTIN_PRESETS: InlinePreset[];
+export declare const UBEAN_SERVER_PRESET: InlinePreset;
+export declare const HONO_OPENAPI_PRESET: InlinePreset;
+export declare const BUILTIN_PRESETS: InlinePreset[];
 interface ComponentInfo {
   name: string;
   filePath: string;
@@ -100,8 +100,8 @@ interface AutoImportResult {
   autoImportsDtsPath: string;
   componentsDtsPath: string;
 }
-declare function generateAutoImports(_scanResult: ScanResult, options: GenerateAutoImportsOptions): Promise<AutoImportResult>;
-declare function getBuiltinComposables(): Import[];
+export declare function generateAutoImports(_scanResult: ScanResult, options: GenerateAutoImportsOptions): Promise<AutoImportResult>;
+export declare function getBuiltinComposables(): Import[];
 /** unplugin-auto-import 的组装结果（透传字段类型直接引用 unplugin 类型，避免跨包类型命名问题）。 */
 interface UbeanAutoImportConfig {
   imports: Options$1['imports'];
@@ -110,7 +110,7 @@ interface UbeanAutoImportConfig {
   vueTemplate: boolean;
   eslintrc: Options$1['eslintrc'];
 }
-declare function getUbeanAutoImportConfig(options?: {
+export declare function getUbeanAutoImportConfig(options?: {
   cwd?: string;
   srcDir?: string;
   buildDir?: string;
@@ -126,7 +126,7 @@ interface UbeanComponentsConfig {
   dts: Options['dts'];
   deep: boolean;
 }
-declare function getUbeanComponentsConfig(options?: {
+export declare function getUbeanComponentsConfig(options?: {
   cwd?: string;
   srcDir?: string;
   buildDir?: string;
@@ -135,7 +135,7 @@ declare function getUbeanComponentsConfig(options?: {
   /** `ubean.config.ts` 的 `components` 配置。 */
   components?: boolean | ComponentsOptions;
 }): UbeanComponentsConfig;
-declare function generateImportsTransform(imports: Import[]): {
+export declare function generateImportsTransform(imports: Import[]): {
   code: string;
   map?: null;
 };
@@ -147,12 +147,12 @@ interface RouteTypesOptions {
   outDir: string;
   fileName?: string;
 }
-declare function generateRouteTypes(result: ScanResult, options: RouteTypesOptions): Promise<string>;
+export declare function generateRouteTypes(result: ScanResult, options: RouteTypesOptions): Promise<string>;
 interface PageTypesOptions {
   outDir: string;
   fileName?: string;
 }
-declare function generatePageTypes(result: ScanResult, options: PageTypesOptions): Promise<string>;
+export declare function generatePageTypes(result: ScanResult, options: PageTypesOptions): Promise<string>;
 //#endregion
 //#region src/codegen/i18n-types.d.ts
 interface I18nTypesOptions {
@@ -161,13 +161,13 @@ interface I18nTypesOptions {
   defaultLocale?: string;
 }
 /** Convert a JSON message tree into a TypeScript object type body. */
-declare function messagesToTsType(value: unknown, indent?: number): string;
+export declare function messagesToTsType(value: unknown, indent?: number): string;
 /**
  * Generate `.ubean/i18n.d.ts` augmenting vue-i18n `DefineLocaleMessage`
  * from the default locale JSON. Users can also hand-write the same
  * module augmentation if they prefer.
  */
-declare function generateI18nTypes(result: ScanResult, options: I18nTypesOptions): Promise<string | null>;
+export declare function generateI18nTypes(result: ScanResult, options: I18nTypesOptions): Promise<string | null>;
 //#endregion
 //#region src/codegen/openapi-types.d.ts
 /**
@@ -187,7 +187,7 @@ interface GenerateOpenApiTypesOptions {
 /**
  * 从 OpenAPI schema 对象生成 paths 类型声明文件。
  */
-declare function generateOpenApiTypes(schema: unknown, options: GenerateOpenApiTypesOptions): Promise<string>;
+export declare function generateOpenApiTypes(schema: unknown, options: GenerateOpenApiTypesOptions): Promise<string>;
 /**
  * 从 dev server 的 `/_openapi.json` 路由获取 schema 并生成类型声明文件。
  *
@@ -195,18 +195,18 @@ declare function generateOpenApiTypes(schema: unknown, options: GenerateOpenApiT
  * HTML(页面 fallback)而非 JSON。此时跳过生成并返回 `null`,避免抛出
  * `Unexpected token '<'` 之类的误导性错误。
  */
-declare function generateOpenApiTypesFromServer(baseUrl: string, options: GenerateOpenApiTypesOptions): Promise<string | null>;
+export declare function generateOpenApiTypesFromServer(baseUrl: string, options: GenerateOpenApiTypesOptions): Promise<string | null>;
 //#endregion
 //#region src/codegen/index.d.ts
-declare const CODEGEN_CONTRACT_VERSION: 1;
-interface CodegenFileContract {
+export declare const CODEGEN_CONTRACT_VERSION: 1;
+export interface CodegenFileContract {
   name: string;
   module: string | null;
   required: boolean;
   types: string[];
 }
-declare const CODEGEN_FILES: readonly CodegenFileContract[];
-interface CodegenManifest {
+export declare const CODEGEN_FILES: readonly CodegenFileContract[];
+export interface CodegenManifest {
   contractVersion: typeof CODEGEN_CONTRACT_VERSION;
   generatedAt: string;
   files: Array<{
@@ -217,12 +217,12 @@ interface CodegenManifest {
     generated: boolean;
   }>;
 }
-interface CodegenOptions extends Omit<GenerateAutoImportsOptions, 'cwd' | 'srcDir' | 'buildDir'> {
+export interface CodegenOptions extends Omit<GenerateAutoImportsOptions, 'cwd' | 'srcDir' | 'buildDir'> {
   cwd: string;
   srcDir: string;
   buildDir: string;
 }
-interface CodegenResult {
+export interface CodegenResult {
   routeTypesPath: string;
   pageTypesPath: string;
   i18nTypesPath?: string | null;
@@ -230,6 +230,6 @@ interface CodegenResult {
   componentsDtsPath?: string;
   generated: string[];
 }
-declare function generateTypes(result: ScanResult, options: CodegenOptions): Promise<CodegenResult>;
+export declare function generateTypes(result: ScanResult, options: CodegenOptions): Promise<CodegenResult>;
 //#endregion
-export { type AutoImportResult, BUILTIN_PRESETS, CODEGEN_CONTRACT_VERSION, CODEGEN_FILES, CodegenFileContract, CodegenManifest, CodegenOptions, CodegenResult, type ComponentInfo, type GenerateAutoImportsOptions, type GenerateOpenApiTypesOptions, HONO_OPENAPI_PRESET, type I18nTypesOptions, type Import, type InlinePreset, type PageTypesOptions, type ResolvedAutoImports, type ResolvedComponentsAutoImport, type RouteTypesOptions, 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 };
+export type { AutoImportResult, ComponentInfo, GenerateAutoImportsOptions, GenerateOpenApiTypesOptions, I18nTypesOptions, Import, InlinePreset, PageTypesOptions, ResolvedAutoImports, ResolvedComponentsAutoImport, RouteTypesOptions };

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-BqqGw4Dv.js";
+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";
 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-BqqGw4Dv.js → codegen-B3oGeRtK.js}

@@ -369,7 +369,8 @@ function generateComponentsDts(components, dtsPath) {
 	for (const name of [
 		"Link",
 		"Head",
-		"PageView"
+		"PageView",
+		"ClientOnly"
 	]) entries.set(name, `typeof import('ubean/client')['${name}']`);
 	for (const comp of components) {
 		const importPath = `./${toPosixPath(relative(dtsDir, toPosixPath(normalize(comp.filePath))))}`;

package/dist/index.d.ts

@@ -2,8 +2,8 @@ import { a as defineVirtualModule, c as useVirtualRegistry, i as VirtualModuleTr
 import { CompiledLayout, CompiledMiddleware, CompiledPage, CompiledRoute } from "@ubean/routes";
 import { ScannedApiRoute, ScannedLocale, ScannedMiddleware, ScannedPageRoute } from "@ubean/scan";
 //#region src/macros.d.ts
-declare function stripMacros(code: string, macros?: readonly string[]): string;
-declare function transformMacros(code: string, id: string): string | null;
+export declare function stripMacros(code: string, macros?: readonly string[]): string;
+export declare function transformMacros(code: string, id: string): string | null;
 //#endregion
 //#region src/registry.d.ts
 /**
@@ -32,28 +32,28 @@ type ComponentResolver = ((name: string) => any) | {
  * Register a component resolver (e.g. `UiResolver()` from `@soybeanjs/ui/resolver`).
  * The resolver will be merged into `unplugin-vue-components`'s `resolvers` array.
  */
-declare function registerComponentResolver(resolver: ComponentResolver): void;
+export declare function registerComponentResolver(resolver: ComponentResolver): void;
 /**
  * Get all registered component resolvers.
  * Called by `ubeanVite` when constructing the `Components()` plugin.
  */
-declare function getComponentResolvers(): ComponentResolver[];
+export declare function getComponentResolvers(): ComponentResolver[];
 /**
  * Register a CSS import path to be injected into the client entry.
  * e.g. `registerCssImport('@soybeanjs/ui/styles.css')` makes the client
  * entry module prepend `import '@soybeanjs/ui/styles.css'`.
  */
-declare function registerCssImport(cssPath: string): void;
+export declare function registerCssImport(cssPath: string): void;
 /**
  * Get all registered CSS import paths.
  * Called by `createClientEntryVirtualModule` to prepend CSS imports.
  */
-declare function getCssImports(): string[];
+export declare function getCssImports(): string[];
 /**
  * Reset the registry (for testing).
  * @internal
  */
-declare function resetModuleRegistry(): void;
+export declare function resetModuleRegistry(): void;
 //#endregion
 //#region src/ssr-singleton.d.ts
 /**
@@ -68,10 +68,10 @@ declare function resetModuleRegistry(): void;
  * - Prod: `ubean` is bundled (`noExternal`). Do **not** also externalize
  *   `@ubean/i18n` — that would create a second copy beside the bundle.
  */
-declare const SSR_SINGLETON_PACKAGES: readonly ["ubean", "@ubean/client", "@ubean/i18n", "vue-i18n", "@intlify/core", "@intlify/core-base"];
-declare const SSR_SINGLETON_DEDUPE: readonly ["vue", "vue-i18n", "@ubean/client", "@ubean/i18n"];
-declare const SSR_SINGLETON_OPTIMIZE_EXCLUDE: readonly ["ubean", "@ubean/client", "@ubean/i18n"];
-declare function ssrSingletonDevPolicy(): {
+export declare const SSR_SINGLETON_PACKAGES: readonly ["ubean", "@ubean/client", "@ubean/i18n", "vue-i18n", "@intlify/core", "@intlify/core-base"];
+export declare const SSR_SINGLETON_DEDUPE: readonly ["vue", "vue-i18n", "@ubean/client", "@ubean/i18n"];
+export declare const SSR_SINGLETON_OPTIMIZE_EXCLUDE: readonly ["ubean", "@ubean/client", "@ubean/i18n"];
+export declare function ssrSingletonDevPolicy(): {
   resolve: {
     dedupe: string[];
   };
@@ -84,16 +84,16 @@ declare function ssrSingletonDevPolicy(): {
     external: string[];
   };
 };
-declare function ssrSingletonProdSsr(): {
+export declare function ssrSingletonProdSsr(): {
   noExternal: string[];
 };
-declare function ssrSingletonProdOptimizeExclude(extra?: string[]): string[];
+export declare function ssrSingletonProdOptimizeExclude(extra?: string[]): string[];
 //#endregion
 //#region src/virtual-modules.d.ts
-declare function createRoutingVirtualModule(routes: CompiledRoute[], middlewares: CompiledMiddleware[], cwd: string): VirtualModule;
-declare function createPagesVirtualModule(pages: CompiledPage[], layouts: CompiledLayout[], cwd: string): VirtualModule;
-declare function createMetaVirtualModule(): VirtualModule;
-declare function createAppVirtualModule(apiRoutes: ScannedApiRoute[], middlewares: ScannedMiddleware[], pages: ScannedPageRoute[], srcDir: string): VirtualModule;
-declare function createLocalesVirtualModule(_locales: ScannedLocale[], defaultLocale: string | undefined, srcDir?: string, i18nConfigJson?: string): VirtualModule;
+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 createLocalesVirtualModule(_locales: ScannedLocale[], defaultLocale: string | undefined, srcDir?: string, i18nConfigJson?: string): VirtualModule;
 //#endregion
-export { SSR_SINGLETON_DEDUPE, SSR_SINGLETON_OPTIMIZE_EXCLUDE, SSR_SINGLETON_PACKAGES, type VirtualModule, type VirtualModuleContext, VirtualModuleRegistry, type VirtualModuleTransform, createAppVirtualModule, createLocalesVirtualModule, createMetaVirtualModule, createPagesVirtualModule, createRoutingVirtualModule, defineVirtualModule, defineVirtualModulePrefix, getComponentResolvers, getCssImports, registerComponentResolver, registerCssImport, resetModuleRegistry, resetVirtualRegistry, ssrSingletonDevPolicy, ssrSingletonProdOptimizeExclude, ssrSingletonProdSsr, stripMacros, transformMacros, useVirtualRegistry };
+export { type VirtualModule, type VirtualModuleContext, VirtualModuleRegistry, type VirtualModuleTransform, defineVirtualModule, defineVirtualModulePrefix, resetVirtualRegistry, useVirtualRegistry };

package/dist/prerender.d.ts

@@ -2,7 +2,7 @@ import { PrerenderConfig, PrerenderResult, RouteRule } from "@ubean/config";
 import { ScannedPageRoute } from "@ubean/scan";
 import { RouteRule as RouteRule$1 } from "@ubean/shared";
 //#region src/prerender.d.ts
-interface PrerendererOptions {
+export interface PrerendererOptions {
   cwd: string;
   outputDir: string;
   pages: ScannedPageRoute[];
@@ -21,6 +21,18 @@ interface PrerendererOptions {
   routeRules?: Record<string, RouteRule$1>;
   /** Content collection URLs merged into `include` (see `extractContentPageRoutes`). */
   contentRoutes?: string[];
+  /**
+   * 静态 SSG 模式：将 404 哨兵路由加入预渲染队列，产物为 `404.html`
+   * （供 GitHub Pages / Netlify 等静态托管平台的自定义 404 页）。
+   * fetcher 需识别 `STATIC_NOT_FOUND_ROUTE` 并渲染 notFoundPage。
+   */
+  notFoundRoute?: boolean;
+  /**
+   * i18n 多语言展开钩子（docs/adr/0011-lightweight-ssg-direct-render.md）：在 `collectPrerenderRoutes`
+   * 之后、入队之前应用，把收集到的路由扩展为全语言 URL 列表
+   * （如 `/about` → `['/about', '/zh/about']`）。
+   */
+  expandRoutes?: (routes: string[]) => string[];
   fetcher?: (url: string) => Promise<{
     html: string;
     statusCode: number;
@@ -36,7 +48,7 @@ interface PrerendererOptions {
  * 返回的路径列表会进一步与 `pages` 候选池匹配(glob 模式)或直接加入(具体路径)。
  * 动态路由的具象值(如 `/blog/hello-world`)可通过具体路径直接加入。
  */
-declare function extractPrerenderRoutesFromRules(routeRules: Record<string, RouteRule$1> | undefined): string[];
+export declare function extractPrerenderRoutesFromRules(routeRules: Record<string, RouteRule$1> | undefined): string[];
 /**
  * 收集需要预渲染的路由列表。
  *
@@ -50,7 +62,7 @@ declare function extractPrerenderRoutesFromRules(routeRules: Record<string, Rout
  *
  * 返回的 `skipped` 为被 `exclude` 命中的路由集合。
  */
-declare function collectPrerenderRoutes(pages: ScannedPageRoute[], options?: {
+export declare function collectPrerenderRoutes(pages: ScannedPageRoute[], options?: {
   all?: boolean;
   include?: string[];
   exclude?: string[];
@@ -62,7 +74,7 @@ declare function collectPrerenderRoutes(pages: ScannedPageRoute[], options?: {
   routes: string[];
   skipped: string[];
 };
-declare function extractLinks(html: string, baseUrl?: string): string[];
+export declare function extractLinks(html: string, baseUrl?: string): string[];
 /**
  * 将路由路径映射到磁盘文件路径。
  *
@@ -75,7 +87,7 @@ declare function extractLinks(html: string, baseUrl?: string): string[];
  * 处理带扩展名路由是为了避免 `/robots.txt/index.html`、`/sitemap.xml/index.html`
  * 这种被错误转成目录的产物。
  */
-declare function routeToFilePath(route: string, outputDir: string): string;
+export declare function routeToFilePath(route: string, outputDir: string): string;
 /**
  * 将路由路径映射到对应的 `__data.json` 文件路径。
  *
@@ -87,11 +99,11 @@ declare function routeToFilePath(route: string, outputDir: string): string;
  * 与 HTML 不同,这里不需要处理扩展名路由(`.html`/`.txt` 等)—— payload
  * 仅对页面路由有意义,扩展名路由(如 `/robots.txt`)不参与 payload 提取。
  */
-declare function routeToDataFilePath(route: string, outputDir: string): string;
+export declare function routeToDataFilePath(route: string, outputDir: string): string;
 /**
  * `extractDataPayload` 的返回结构。
  */
-interface ExtractedPayload {
+export interface ExtractedPayload {
   /** 从 `__UBEAN_DATA__` 解析出的 payload 数据。 */
   data: Record<string, unknown>;
   /** 替换内联 script 后的 HTML(包含 preload link + 引导脚本)。 */
@@ -114,10 +126,10 @@ interface ExtractedPayload {
  * @param html 预渲染后的完整 HTML
  * @param route 当前路由路径(用于计算 dataUrl)
  */
-declare function extractDataPayload(html: string, route: string): ExtractedPayload | null;
-declare function writePrerenderedFile(filePath: string, html: string): Promise<void>;
-declare function prerender(options: PrerendererOptions): Promise<PrerenderResult>;
-declare function generatePrerenderManifest(result: PrerenderResult, baseUrl?: string): {
+export declare function extractDataPayload(html: string, route: string): ExtractedPayload | null;
+export declare function writePrerenderedFile(filePath: string, html: string): Promise<void>;
+export declare function prerender(options: PrerendererOptions): Promise<PrerenderResult>;
+export declare function generatePrerenderManifest(result: PrerenderResult, baseUrl?: string): {
   routes: string[];
   generatedAt: string;
   errors: Array<{
@@ -126,4 +138,4 @@ declare function generatePrerenderManifest(result: PrerenderResult, baseUrl?: st
   }>;
 };
 //#endregion
-export { ExtractedPayload, PrerendererOptions, type RouteRule, collectPrerenderRoutes, extractDataPayload, extractLinks, extractPrerenderRoutesFromRules, generatePrerenderManifest, prerender, routeToDataFilePath, routeToFilePath, writePrerenderedFile };
+export type { RouteRule };

package/dist/prerender.js

@@ -1,3 +1,4 @@
+import { STATIC_NOT_FOUND_ROUTE } from "./static-render.js";
 import { dirname, join } from "pathe";
 import { resolvePrerenderConfig } from "@ubean/config";
 import { DATA_PAYLOAD_ID } from "@ubean/pages";
@@ -127,6 +128,7 @@ function normalizeHref(href, baseUrl) {
 */
 function routeToFilePath(route, outputDir) {
 	if (route === "/" || route === "") return join(outputDir, "index.html");
+	if (route === "/__ubean_404__") return join(outputDir, "404.html");
 	if (route.endsWith(".html")) return join(outputDir, route);
 	const lastSegment = route.slice(route.lastIndexOf("/") + 1);
 	const dotIdx = lastSegment.lastIndexOf(".");
@@ -213,7 +215,8 @@ async function prerender(options) {
 		routeRules: options.routeRules,
 		contentRoutes: options.contentRoutes
 	});
-	const queue = [...initialRoutes];
+	const queue = [...options.expandRoutes ? options.expandRoutes(initialRoutes) : initialRoutes];
+	if (options.notFoundRoute) queue.unshift(STATIC_NOT_FOUND_ROUTE);
 	const visited = /* @__PURE__ */ new Set();
 	const results = [];
 	const generated = [];
@@ -223,11 +226,12 @@ async function prerender(options) {
 	async function processRoute(route) {
 		if (visited.has(route)) return;
 		visited.add(route);
-		if (config.exclude.some((p) => matchGlob(route, p))) {
+		if (route !== "/__ubean_404__" && config.exclude.some((p) => matchGlob(route, p))) {
 			if (!skipped.includes(route)) skipped.push(route);
 			return;
 		}
-		const result = { route };
+		const displayRoute = route === "/__ubean_404__" ? "/404" : route;
+		const result = { route: displayRoute };
 		try {
 			if (options.fetcher) {
 				const resp = await options.fetcher(route);
@@ -253,7 +257,7 @@ async function prerender(options) {
 					}
 				}
 				await writePrerenderedFile(routeToFilePath(route, outputDir), htmlToWrite);
-				generated.push(route);
+				generated.push(displayRoute);
 				result.html = void 0;
 			} else {
 				const placeholderHtml = `<!DOCTYPE html>
@@ -264,7 +268,7 @@ async function prerender(options) {
 </body>
 </html>`;
 				await writePrerenderedFile(routeToFilePath(route, outputDir), placeholderHtml);
-				generated.push(route);
+				generated.push(displayRoute);
 				result.statusCode = 200;
 			}
 		} catch (err) {

package/dist/production.d.ts

@@ -2,7 +2,7 @@ import { ResolvedConfig } from "@ubean/config";
 import { ScanResult } from "@ubean/scan";
 import { Preset } from "@ubean/preset";
 //#region src/production.d.ts
-interface BuildOptions {
+export interface BuildOptions {
   cwd: string;
   config: ResolvedConfig;
   preset: Preset;
@@ -12,7 +12,7 @@ interface BuildOptions {
   /** Inlined content collections for production SSR (`queryCollection`). */
   contentSnapshot?: Record<string, unknown[]>;
 }
-interface BuildManifest {
+export interface BuildManifest {
   assets: Array<{
     file: string;
     src?: string;
@@ -24,6 +24,5 @@ interface BuildManifest {
   serverDir: string;
   preset: string;
 }
-declare function buildProduction(options: BuildOptions): Promise<BuildManifest>;
-//#endregion
-export { BuildManifest, BuildOptions, buildProduction };
+export declare function buildProduction(options: BuildOptions): Promise<BuildManifest>;
+//#endregion