@ubean/app 0.6.0 → 0.6.1-beta.3

package/dist/index.d.ts

@@ -2,10 +2,199 @@ import { RegisterOptions, RouteRegistrar } from "@ubean/routes";
 import { CacheStore } from "@ubean/server/cache";
 import { DataCacheMiddlewareOptions } from "@ubean/server/middleware";
 import { CsrfOptions, SecurityHeadersOptions } from "@ubean/server/security";
-import { ComposedHandler, ComposedHandler as ComposedHandler$1, RouteMeta, RouteMeta as RouteMeta$1, RouteRule, RouteRule as RouteRule$1, UbeanEnv, UbeanEnv as UbeanEnv$1, UbeanMiddleware, UbeanMiddleware as UbeanMiddleware$1 } from "@ubean/shared";
+import { ComposedHandler, ComposedHandler as ComposedHandler$1, RouteMeta, RouteMeta as RouteMeta$1, RouteRule, RouteRule as RouteRule$1, UbeanEnv, UbeanEnv as UbeanEnv$1, UbeanMiddleware, UbeanMiddleware as UbeanMiddleware$1, UbeanMiddlewareStep } from "@ubean/shared";
 import { Context, Hono, MiddlewareHandler } from "hono";
 import { Hookable } from "hookable";
 import { ScannedApiRoute, ScannedApiRoute as ScannedApiRoute$1, ScannedCronTask, ScannedLayout, ScannedLayout as ScannedLayout$1, ScannedMiddleware, ScannedMiddleware as ScannedMiddleware$1, ScannedPageRoute, ScannedPageRoute as ScannedPageRoute$1 } from "@ubean/scan";
+//#region src/app.d.ts
+interface UbeanRuntimeHooks {
+  'app:created': (app: Hono<UbeanEnv$1>) => void | Promise<void>;
+  'app:before:register': (app: Hono<UbeanEnv$1>) => void | Promise<void>;
+  'app:after:register': (app: Hono<UbeanEnv$1>) => void | Promise<void>;
+  'request:start': (c: Context<UbeanEnv$1>) => void | Promise<void>;
+  'request:end': (c: Context<UbeanEnv$1>, res: Response) => void | Promise<void>;
+  'request:error': (c: Context<UbeanEnv$1>, err: Error) => void | Promise<void>;
+  'route:register': (route: {
+    method: string;
+    path: string;
+    handler: MiddlewareHandler[] | ComposedHandler$1 | Function;
+    meta?: RouteMeta$1;
+  }) => void | Promise<void>;
+  'middleware:register': (mw: ScannedMiddleware$1) => void | Promise<void>;
+  error: (err: Error, c: Context<UbeanEnv$1>) => void | Promise<void>;
+}
+/**
+ * Page renderer shape (satisfied by `@ubean/client/ssr`'s `PageRenderer`).
+ * Declared as a type alias to the actual `@ubean/pages`'s `PageRenderer`
+ * interface so consumers don't need to install `@ubean/pages` separately
+ * to type-check against `UbeanAppOptions.pageRenderer`.
+ *
+ * Type-only import works even when `@ubean/pages` is an optional peerDep —
+ * only runtime imports would fail. Consumers without `@ubean/pages` will
+ * see this type fall back to `any` (TS' default for missing modules under
+ * `skipLibCheck`).
+ */
+type PageRenderer = import('@ubean/pages').PageRenderer;
+interface PageAssetTags {
+  head?: string;
+  bodyAttrs?: string;
+  htmlAttrs?: string;
+  /** Favicon HREF (如 `/favicon.ico`),自动注入 `<link rel="icon">` 到 `<head>` */
+  favicon?: string;
+}
+interface UbeanAppOptions {
+  rootDir?: string;
+  routes?: ScannedApiRoute$1[];
+  middleware?: ScannedMiddleware$1[];
+  pages?: ScannedPageRoute$1[];
+  layouts?: ScannedLayout$1[];
+  crons?: ScannedCronTask[];
+  routeRules?: Record<string, RouteRule$1>;
+  plugins?: UbeanAppPlugin[];
+  routeLoaders?: Record<string, () => Promise<{
+    default?: ComposedHandler$1 | MiddlewareHandler[];
+  } | Record<string, ComposedHandler$1 | MiddlewareHandler[]>>>;
+  middlewareLoaders?: Record<string, () => Promise<{
+    default: UbeanMiddleware$1;
+  }>>;
+  pageLoaders?: Record<string, () => Promise<unknown>>;
+  pageRenderer?: PageRenderer | null;
+  pageAssetTags?: PageAssetTags;
+  /** 不进行 SSR 的路由模式列表(glob),匹配的页面走 CSR */
+  ssrExclude?: string[];
+  /**
+   * 启用流式 SSR。`true` 时页面响应以 `ReadableStream` 分块输出
+   * (头部先发送,app HTML 边渲染边输出),改善 TTFB/LCP。
+   * renderer 不支持流式时自动降级为缓冲渲染。
+   */
+  streaming?: boolean;
+  /**
+   * 爬虫降级(P9-24):当 `streaming` 启用且检测到爬虫/社交预览 UA 时,
+   * 自动降级为缓冲渲染以保证 metadata 出现在初始 `<head>`。
+   * 默认 `true`。设为 `false` 可禁用爬虫检测(不推荐)。
+   */
+  botFallback?: boolean;
+  publicDir?: string;
+  healthEndpoint?: boolean;
+  openAPI?: boolean | {
+    title?: string;
+    version?: string;
+    description?: string;
+    scalarPath?: string;
+    openAPIPath?: string;
+  };
+  i18nConfig?: {
+    enabled?: boolean;
+    strategy?: 'prefix' | 'prefix_except_default' | 'prefix_and_default' | 'no_prefix';
+    defaultLocale?: string;
+    locales?: string[] | Array<{
+      code: string;
+    }>;
+    detectBrowserLanguage?: false | {
+      cookieName?: string;
+      redirectOn?: 'root' | 'all';
+      alwaysRedirect?: boolean;
+    };
+    fallbackLocale?: string;
+    baseUrl?: string;
+  };
+  /** `pages/404.vue` 自动检测的 404 页面,注册为 Hono 兜底处理器 */
+  notFoundPage?: ScannedPageRoute$1;
+  /**
+   * Pre-rendered no-FOUC color-mode script (from `getColorModeScript`).
+   * Injected into `<head>` of every SSR/prerendered HTML response. Covers
+   * the SSG/prerender path that bypasses Vite's `transformIndexHtml`.
+   */
+  colorModeScript?: string;
+  /**
+   * CSRF protection. Default `true` (origin check). `false` disables.
+   * Pass `CsrfOptions` to override (e.g. token mode).
+   */
+  csrf?: boolean | CsrfOptions;
+  /**
+   * Security response headers. Default `true`. `false` disables.
+   */
+  securityHeaders?: boolean | SecurityHeadersOptions;
+  /**
+   * Cross-request fetch Data Cache (`next: { revalidate, tags }`).
+   * Default `true`. Dev still skips cache unless `forceDevCache`.
+   */
+  dataCache?: boolean | DataCacheMiddlewareOptions;
+  /**
+   * HTTP / ISR cache store. Default is in-process memory (not shared
+   * across instances). Pass `loadFsCacheStore(dir)`（Node fs 后端，动态加载）for a Node backend.
+   */
+  cacheStore?: CacheStore;
+  /** Declarative cache backend. `store: 'fs'` 走 `loadFsCacheStore()`（Node-only，动态加载）。 */
+  cache?: {
+    store?: 'memory' | 'fs';
+    dir?: string;
+  };
+  /**
+   * File-convention SEO (`src/sitemap.ts`, `robots.ts`, …). Default: on when
+   * `rootDir` or `seoConventions.srcDir` is set. `false` disables.
+   */
+  seoConventions?: boolean | {
+    srcDir?: string;
+  };
+  /**
+   * Preloaded SEO convention modules (production `import.meta.glob`). When
+   * set, disk discovery is skipped — required on serverless.
+   */
+  seoConventionModules?: Record<string, {
+    default?: unknown;
+  }>;
+  /**
+   * Production `/_ipx` handler (from `@ubean/image` when `image` is enabled).
+   * Dev still uses the Vite middleware.
+   */
+  ipxHandler?: MiddlewareHandler<UbeanEnv$1>;
+}
+interface UbeanAppPlugin {
+  name: string;
+  /** Called after app is created but before routes are registered */
+  setup?: (app: UbeanApp) => void | Promise<void>;
+  /** Called after all routes are registered */
+  ready?: (app: UbeanApp) => void | Promise<void>;
+}
+export declare class UbeanApp {
+  readonly hono: Hono<UbeanEnv$1>;
+  readonly hooks: Hookable<UbeanRuntimeHooks>;
+  readonly plugins: UbeanAppPlugin[];
+  readonly options: UbeanAppOptions;
+  private _ready;
+  /**
+   * Scalar 文档页（`/_scalar`）专用的 CSP：生效 CSP + `{@link SCALAR_SCRIPT_ORIGIN}`。
+   *
+   * 该页面从 CDN 取脚本，而 CSP 是全局的一份 —— 只在这一条响应上追加它需要的来源，不放宽应用
+   * 其余部分的策略。CSP 被关闭时为 `undefined`（不重加头）。构造期算好，`init()` 注册路由时用。
+   */
+  private _scalarCsp;
+  constructor(options?: UbeanAppOptions);
+  private _setupBaseMiddleware;
+  init(): Promise<this>;
+  private _registerSeoConventions;
+  private _lazyInitPromise;
+  lazyInit(): Promise<this>;
+  resetInit(): void;
+  private _setupFallback;
+  use(path: string, ...handlers: MiddlewareHandler<UbeanEnv$1>[]): this;
+  use(...handlers: MiddlewareHandler<UbeanEnv$1>[]): this;
+  on(method: string | string[], path: string, ...handlers: MiddlewareHandler<UbeanEnv$1>[]): this;
+  get(path: string, ...handlers: MiddlewareHandler<UbeanEnv$1>[]): this;
+  post(path: string, ...handlers: MiddlewareHandler<UbeanEnv$1>[]): this;
+  put(path: string, ...handlers: MiddlewareHandler<UbeanEnv$1>[]): this;
+  patch(path: string, ...handlers: MiddlewareHandler<UbeanEnv$1>[]): this;
+  delete(path: string, ...handlers: MiddlewareHandler<UbeanEnv$1>[]): this;
+  fetch: Hono<UbeanEnv$1>['fetch'];
+  request: Hono<UbeanEnv$1>['request'];
+}
+interface AppPlugin {
+  name: string;
+  setup?: (app: Hono<UbeanEnv$1>) => void | Promise<void>;
+}
+export declare function createUbeanApp(options?: UbeanAppOptions): UbeanApp;
+//#endregion
 //#region src/hooks.d.ts
 /**
  * 请求事件 —— 传递给 `handle` 和 `handleError` 的上下文对象。
@@ -285,193 +474,4 @@ export declare function createDefaultServerConfig(): ResolvedServerConfig;
  */
 export declare function mergeServerConfigs(base: ResolvedServerConfig, ...configs: (ResolvedServerConfig | null | undefined)[]): ResolvedServerConfig;
 //#endregion
-//#region src/app.d.ts
-interface UbeanRuntimeHooks {
-  'app:created': (app: Hono<UbeanEnv$1>) => void | Promise<void>;
-  'app:before:register': (app: Hono<UbeanEnv$1>) => void | Promise<void>;
-  'app:after:register': (app: Hono<UbeanEnv$1>) => void | Promise<void>;
-  'request:start': (c: Context<UbeanEnv$1>) => void | Promise<void>;
-  'request:end': (c: Context<UbeanEnv$1>, res: Response) => void | Promise<void>;
-  'request:error': (c: Context<UbeanEnv$1>, err: Error) => void | Promise<void>;
-  'route:register': (route: {
-    method: string;
-    path: string;
-    handler: MiddlewareHandler[] | ComposedHandler$1 | Function;
-    meta?: RouteMeta$1;
-  }) => void | Promise<void>;
-  'middleware:register': (mw: ScannedMiddleware$1) => void | Promise<void>;
-  error: (err: Error, c: Context<UbeanEnv$1>) => void | Promise<void>;
-}
-/**
- * Page renderer shape (satisfied by `@ubean/client/ssr`'s `PageRenderer`).
- * Declared as a type alias to the actual `@ubean/pages`'s `PageRenderer`
- * interface so consumers don't need to install `@ubean/pages` separately
- * to type-check against `UbeanAppOptions.pageRenderer`.
- *
- * Type-only import works even when `@ubean/pages` is an optional peerDep —
- * only runtime imports would fail. Consumers without `@ubean/pages` will
- * see this type fall back to `any` (TS' default for missing modules under
- * `skipLibCheck`).
- */
-type PageRenderer = import('@ubean/pages').PageRenderer;
-interface PageAssetTags {
-  head?: string;
-  bodyAttrs?: string;
-  htmlAttrs?: string;
-  /** Favicon HREF (如 `/favicon.ico`),自动注入 `<link rel="icon">` 到 `<head>` */
-  favicon?: string;
-}
-interface UbeanAppOptions {
-  rootDir?: string;
-  routes?: ScannedApiRoute$1[];
-  middleware?: ScannedMiddleware$1[];
-  pages?: ScannedPageRoute$1[];
-  layouts?: ScannedLayout$1[];
-  crons?: ScannedCronTask[];
-  routeRules?: Record<string, RouteRule$1>;
-  plugins?: UbeanAppPlugin[];
-  routeLoaders?: Record<string, () => Promise<{
-    default?: ComposedHandler$1 | MiddlewareHandler[];
-  } | Record<string, ComposedHandler$1 | MiddlewareHandler[]>>>;
-  middlewareLoaders?: Record<string, () => Promise<{
-    default: UbeanMiddleware$1;
-  }>>;
-  pageLoaders?: Record<string, () => Promise<unknown>>;
-  pageRenderer?: PageRenderer | null;
-  pageAssetTags?: PageAssetTags;
-  /** 不进行 SSR 的路由模式列表(glob),匹配的页面走 CSR */
-  ssrExclude?: string[];
-  /**
-   * 启用流式 SSR。`true` 时页面响应以 `ReadableStream` 分块输出
-   * (头部先发送,app HTML 边渲染边输出),改善 TTFB/LCP。
-   * renderer 不支持流式时自动降级为缓冲渲染。
-   */
-  streaming?: boolean;
-  /**
-   * 爬虫降级(P9-24):当 `streaming` 启用且检测到爬虫/社交预览 UA 时,
-   * 自动降级为缓冲渲染以保证 metadata 出现在初始 `<head>`。
-   * 默认 `true`。设为 `false` 可禁用爬虫检测(不推荐)。
-   */
-  botFallback?: boolean;
-  publicDir?: string;
-  healthEndpoint?: boolean;
-  openAPI?: boolean | {
-    title?: string;
-    version?: string;
-    description?: string;
-    scalarPath?: string;
-    openAPIPath?: string;
-  };
-  i18nConfig?: {
-    enabled?: boolean;
-    strategy?: 'prefix' | 'prefix_except_default' | 'prefix_and_default' | 'no_prefix';
-    defaultLocale?: string;
-    locales?: string[] | Array<{
-      code: string;
-    }>;
-    detectBrowserLanguage?: false | {
-      cookieName?: string;
-      redirectOn?: 'root' | 'all';
-      alwaysRedirect?: boolean;
-    };
-    fallbackLocale?: string;
-    baseUrl?: string;
-  };
-  /** `pages/404.vue` 自动检测的 404 页面,注册为 Hono 兜底处理器 */
-  notFoundPage?: ScannedPageRoute$1;
-  /**
-   * Pre-rendered no-FOUC color-mode script (from `getColorModeScript`).
-   * Injected into `<head>` of every SSR/prerendered HTML response. Covers
-   * the SSG/prerender path that bypasses Vite's `transformIndexHtml`.
-   */
-  colorModeScript?: string;
-  /**
-   * CSRF protection. Default `true` (origin check). `false` disables.
-   * Pass `CsrfOptions` to override (e.g. token mode).
-   */
-  csrf?: boolean | CsrfOptions;
-  /**
-   * Security response headers. Default `true`. `false` disables.
-   */
-  securityHeaders?: boolean | SecurityHeadersOptions;
-  /**
-   * Cross-request fetch Data Cache (`next: { revalidate, tags }`).
-   * Default `true`. Dev still skips cache unless `forceDevCache`.
-   */
-  dataCache?: boolean | DataCacheMiddlewareOptions;
-  /**
-   * HTTP / ISR cache store. Default is in-process memory (not shared
-   * across instances). Pass `loadFsCacheStore(dir)`（Node fs 后端，动态加载）for a Node backend.
-   */
-  cacheStore?: CacheStore;
-  /** Declarative cache backend. `store: 'fs'` 走 `loadFsCacheStore()`（Node-only，动态加载）。 */
-  cache?: {
-    store?: 'memory' | 'fs';
-    dir?: string;
-  };
-  /**
-   * File-convention SEO (`src/sitemap.ts`, `robots.ts`, …). Default: on when
-   * `rootDir` or `seoConventions.srcDir` is set. `false` disables.
-   */
-  seoConventions?: boolean | {
-    srcDir?: string;
-  };
-  /**
-   * Preloaded SEO convention modules (production `import.meta.glob`). When
-   * set, disk discovery is skipped — required on serverless.
-   */
-  seoConventionModules?: Record<string, {
-    default?: unknown;
-  }>;
-  /**
-   * Production `/_ipx` handler (from `@ubean/image` when `image` is enabled).
-   * Dev still uses the Vite middleware.
-   */
-  ipxHandler?: MiddlewareHandler<UbeanEnv$1>;
-}
-interface UbeanAppPlugin {
-  name: string;
-  /** Called after app is created but before routes are registered */
-  setup?: (app: UbeanApp) => void | Promise<void>;
-  /** Called after all routes are registered */
-  ready?: (app: UbeanApp) => void | Promise<void>;
-}
-export declare class UbeanApp {
-  readonly hono: Hono<UbeanEnv$1>;
-  readonly hooks: Hookable<UbeanRuntimeHooks>;
-  readonly plugins: UbeanAppPlugin[];
-  readonly options: UbeanAppOptions;
-  private _ready;
-  /**
-   * Scalar 文档页（`/_scalar`）专用的 CSP：生效 CSP + `{@link SCALAR_SCRIPT_ORIGIN}`。
-   *
-   * 该页面从 CDN 取脚本，而 CSP 是全局的一份 —— 只在这一条响应上追加它需要的来源，不放宽应用
-   * 其余部分的策略。CSP 被关闭时为 `undefined`（不重加头）。构造期算好，`init()` 注册路由时用。
-   */
-  private _scalarCsp;
-  constructor(options?: UbeanAppOptions);
-  private _setupBaseMiddleware;
-  init(): Promise<this>;
-  private _registerSeoConventions;
-  private _lazyInitPromise;
-  lazyInit(): Promise<this>;
-  resetInit(): void;
-  private _setupFallback;
-  use(path: string, ...handlers: MiddlewareHandler<UbeanEnv$1>[]): this;
-  use(...handlers: MiddlewareHandler<UbeanEnv$1>[]): this;
-  on(method: string | string[], path: string, ...handlers: MiddlewareHandler<UbeanEnv$1>[]): this;
-  get(path: string, ...handlers: MiddlewareHandler<UbeanEnv$1>[]): this;
-  post(path: string, ...handlers: MiddlewareHandler<UbeanEnv$1>[]): this;
-  put(path: string, ...handlers: MiddlewareHandler<UbeanEnv$1>[]): this;
-  patch(path: string, ...handlers: MiddlewareHandler<UbeanEnv$1>[]): this;
-  delete(path: string, ...handlers: MiddlewareHandler<UbeanEnv$1>[]): this;
-  fetch: Hono<UbeanEnv$1>['fetch'];
-  request: Hono<UbeanEnv$1>['request'];
-}
-interface AppPlugin {
-  name: string;
-  setup?: (app: Hono<UbeanEnv$1>) => void | Promise<void>;
-}
-export declare function createUbeanApp(options?: UbeanAppOptions): UbeanApp;
-//#endregion
-export type { AppPlugin, ComposedHandler, DefineServerOptions, GlobalHooks, Handle, HandleError, HandleErrorInput, HandleEvent, HandleFetch, HandleFetchInput, HandleInput, PageAssetTags, PageRenderer, RegisterOptions, ResolvedServerConfig, RouteMeta, RouteRegistrar, RouteRule, ScannedApiRoute, ScannedLayout, ScannedMiddleware, ScannedPageRoute, ServerHooks, UbeanAppOptions, UbeanAppPlugin, UbeanEnv, UbeanMiddleware, UbeanRuntimeHooks };
+export type { AppPlugin, ComposedHandler, DefineServerOptions, GlobalHooks, Handle, HandleError, HandleErrorInput, HandleEvent, HandleFetch, HandleFetchInput, HandleInput, PageAssetTags, PageRenderer, RegisterOptions, ResolvedServerConfig, RouteMeta, RouteRegistrar, RouteRule, ScannedApiRoute, ScannedLayout, ScannedMiddleware, ScannedPageRoute, ServerHooks, UbeanAppOptions, UbeanAppPlugin, UbeanEnv, UbeanMiddleware, UbeanMiddlewareStep, UbeanRuntimeHooks };

package/dist/index.js

@@ -113,109 +113,6 @@ async function applyHandleErrorHook(c, error, status) {
 	});
 }
 //#endregion
-//#region src/define-server.ts
-/**
-* Apply a resolved server config to a `UbeanApp` instance.
-*
-* This must be called BEFORE `app.init()` so that:
-* - `plugins` are available when `init()` calls `setup` / `ready`
-* - `hooks` are registered before `init()` fires `app:created` etc.
-* - `onAppCreate` runs before route registration
-* - `globalHooks` (handle/handleFetch/handleError) are set before any request
-*
-* `onServerReady` is NOT called here — the caller must invoke it after
-* `app.init()` completes.
-*/
-async function applyServerConfig(app, config) {
-	if (config.plugins.length > 0) app.plugins.push(...config.plugins);
-	for (const [name, handler] of Object.entries(config.hooks)) if (handler) app.hooks.hook(name, handler);
-	if (config.globalHooks) setGlobalHooks(config.globalHooks);
-	if (config.onAppCreate) await config.onAppCreate(app);
-}
-/**
-* Define the backend server configuration.
-*
-* This is the server-side counterpart of `defineApp`. It allows users to
-* inject plugins, register runtime hooks, and run startup/ready logic
-* from a simple entry file (`src/server.ts`).
-*
-* @example
-* ```ts
-* // src/server.ts
-* import { defineServer } from '@ubean/app';
-*
-* export default defineServer({
-*   plugins: [
-*     {
-*       name: 'my-plugin',
-*       setup(app) { app.use('/api/custom', handler); },
-*       ready(app) { /* routes registered *\/ }
-*     }
-*   ],
-*   hooks: {
-*     'request:start': (c) => { console.log(c.req.method, c.req.path); }
-*   },
-*   globalHooks: {
-*     handle: async ({ event, resolve }) => {
-*       const response = await resolve(event);
-*       response.headers.set('X-Custom', 'ubean');
-*       return response;
-*     },
-*     handleError: async ({ error, status }) => {
-*       console.error(`[${status}]`, error);
-*     }
-*   },
-*   onAppCreate: async (app) => { /* init db *\/ },
-*   onServerReady: async (app) => { /* start workers *\/ }
-* });
-* ```
-*/
-function defineServer(options) {
-	return {
-		plugins: options.plugins || [],
-		hooks: options.hooks || {},
-		globalHooks: options.globalHooks,
-		onAppCreate: options.onAppCreate,
-		onServerReady: options.onServerReady
-	};
-}
-/**
-* Create an empty server config — used as the fallback when no
-* `src/server.ts` file exists.
-*/
-function createDefaultServerConfig() {
-	return {
-		plugins: [],
-		hooks: {}
-	};
-}
-/**
-* Merge multiple server configs (shared + mode-specific) into one.
-* Plugins are concatenated; hooks are merged; mode-specific callbacks
-* override shared ones.
-*/
-function mergeServerConfigs(base, ...configs) {
-	const result = {
-		plugins: [...base.plugins],
-		hooks: { ...base.hooks },
-		globalHooks: base.globalHooks ? { ...base.globalHooks } : void 0,
-		onAppCreate: base.onAppCreate,
-		onServerReady: base.onServerReady
-	};
-	for (const cfg of configs) {
-		if (!cfg) continue;
-		if (cfg.plugins) result.plugins.push(...cfg.plugins);
-		if (cfg.hooks) Object.assign(result.hooks, cfg.hooks);
-		if (cfg.globalHooks) result.globalHooks = {
-			...result.globalHooks,
-			...cfg.globalHooks
-		};
-		if (cfg.onAppCreate) result.onAppCreate = cfg.onAppCreate;
-		if (cfg.onServerReady) result.onServerReady = cfg.onServerReady;
-	}
-	return result;
-}
-//#endregion
 //#region src/app.ts
 const actionContextAls = new AsyncLocalStorage();
 bindActionContextStorage(actionContextAls);
@@ -261,6 +158,35 @@ function resolveToggle(value, defaultOn) {
 	if (value === true) return {};
 	return value;
 }
+/**
+* TS-07：把中间件链的每一步按**注册/执行顺序**记进请求级变量。
+*
+* 顺序是结构性事实 —— 13 步表（见 `_setupBaseMiddleware()` 与本包 middleware-order 测试）把它
+* 固定下来，改动注册顺序即破坏契约。记录值只用于可观测性断言（`GET /_health` 回读），不参与任何请求处理逻辑。
+*/
+function markMiddlewareStep(c, step) {
+	const recorded = c.get("__ubean_mw_order__");
+	c.set("__ubean_mw_order__", recorded ? [...recorded, step] : [step]);
+}
+/** 给中间件套一层「记录步骤名」外壳；注册顺序与不套壳时完全一致。 */
+function withStep(step, handler) {
+	return async (c, next) => {
+		markMiddlewareStep(c, step);
+		return handler(c, next);
+	};
+}
+/**
+* TS-07：链上存在「不是中间件、但有固定位置」的步骤（如 ⑦ cacheStore 初始化）。
+*
+* 为了让 13 步全序可观测，这里在该位置插一个**纯记录、纯透传**的空壳：它不读不写请求、
+* 不改响应，只把步骤名按注册位置记进请求级序列。
+*/
+function recordOnlyStep(step) {
+	return async (c, next) => {
+		markMiddlewareStep(c, step);
+		return next();
+	};
+}
 var UbeanApp = class {
 	hono;
 	hooks;
@@ -283,55 +209,56 @@ var UbeanApp = class {
 		this._setupFallback();
 	}
 	_setupBaseMiddleware() {
-		this.hono.use("*", async (c, next) => {
+		this.hono.use("*", withStep("handle", async (c, next) => {
 			if (!await applyHandleHook(c, next)) await next();
-		});
-		this.hono.use("*", requestId());
-		this.hono.use("*", async (c, next) => {
+		}));
+		this.hono.use("*", withStep("requestId", requestId()));
+		this.hono.use("*", withStep("actionContext", async (c, next) => {
 			await actionContextAls.run(buildActionContext(c), () => next());
-		});
+		}));
 		const securityHeaders = resolveToggle(this.options.securityHeaders, true);
 		if (securityHeaders !== false) {
 			const mergedSecurity = mergeSecurityHeadersOptions(DEFAULT_SECURITY_HEADERS, securityHeaders);
-			this.hono.use("*", createSecurityHeadersMiddleware(mergedSecurity));
+			this.hono.use("*", withStep("securityHeaders", createSecurityHeadersMiddleware(mergedSecurity)));
 			const effectiveCsp = mergedSecurity.contentSecurityPolicy;
 			if (effectiveCsp && typeof effectiveCsp === "object") this._scalarCsp = serializeCsp(extendCspScriptSrc(effectiveCsp, [SCALAR_SCRIPT_ORIGIN]));
 		}
 		const csrf = resolveToggle(this.options.csrf, true);
-		if (csrf !== false) this.hono.use("*", createCsrfMiddleware({
+		if (csrf !== false) this.hono.use("*", withStep("csrf", createCsrfMiddleware({
 			mode: "origin",
 			...csrf,
 			exclude: [...DEFAULT_CSRF_EXCLUDE, ...csrf.exclude ?? []]
-		}));
+		})));
 		const dataCache = resolveToggle(this.options.dataCache, true);
-		if (dataCache !== false) this.hono.use("*", createDataCacheMiddleware(dataCache));
+		if (dataCache !== false) this.hono.use("*", withStep("dataCache", createDataCacheMiddleware(dataCache)));
 		if (this.options.cacheStore) useCacheStore(this.options.cacheStore);
 		else if (this.options.cache?.store === "fs") {
 			const fsDir = this.options.cache.dir || ".ubean/cache";
 			useCacheStore(createLazyCacheStore(() => loadFsCacheStore(fsDir)));
 		}
+		if (this.options.cacheStore || this.options.cache?.store === "fs") this.hono.use("*", recordOnlyStep("cacheStore"));
 		const i18nCfg = this.options.i18nConfig;
 		if (i18nCfg?.enabled !== false && (i18nCfg?.locales?.length ?? 0) > 0 && i18nCfg) {
 			const locales = (i18nCfg.locales || []).map((l) => typeof l === "string" ? l : l.code);
-			this.hono.use("*", createI18nMiddleware({
+			this.hono.use("*", withStep("i18n", createI18nMiddleware({
 				defaultLocale: i18nCfg.defaultLocale || "en",
 				locales,
 				strategy: i18nCfg.strategy || "prefix_except_default",
 				detectBrowserLanguage: i18nCfg.detectBrowserLanguage,
 				loadMessages: (locale, fallback) => ensureLocaleMessages(locale, fallback)
-			}));
+			})));
 		}
 		if (this.options.routeRules && Object.keys(this.options.routeRules).length > 0) {
-			this.hono.use("*", createRouteRulesMiddleware(this.options.routeRules, { dispatch: (req) => Promise.resolve(this.hono.fetch(req)) }));
+			this.hono.use("*", withStep("routeRules", createRouteRulesMiddleware(this.options.routeRules, { dispatch: (req) => Promise.resolve(this.hono.fetch(req)) })));
 			const cacheRules = resolveRouteCacheRules(this.options.routeRules);
 			const hasIsrRules = Object.values(this.options.routeRules).some((r) => r?.isr !== void 0);
 			if (Object.keys(cacheRules).length > 0 || hasIsrRules) {
 				if (!this.options.cacheStore && this.options.cache?.store !== "fs") useCacheStore(createMemoryStore());
-				if (Object.keys(cacheRules).length > 0) this.hono.use("*", createCacheMiddleware({ rules: cacheRules }));
+				if (Object.keys(cacheRules).length > 0) this.hono.use("*", withStep("routeCache", createCacheMiddleware({ rules: cacheRules })));
 			}
 		}
-		this.hono.use("*", createWebSocketMiddleware());
-		this.hono.use("*", async (c, next) => {
+		this.hono.use("*", withStep("websocket", createWebSocketMiddleware()));
+		this.hono.use("*", withStep("lifecycle", async (c, next) => {
 			c.set("route", {
 				meta: { requiresAuth: true },
 				path: c.req.path,
@@ -345,13 +272,17 @@ var UbeanApp = class {
 				await this.hooks.callHook("request:error", c, err);
 				throw err;
 			}
-		});
-		if (this.options.healthEndpoint !== false) this.hono.get("/_health", (c) => {
-			return c.json({
-				status: "ok",
-				timestamp: Date.now()
+		}));
+		if (this.options.healthEndpoint !== false) {
+			this.hono.use("*", recordOnlyStep("healthEndpoint"));
+			this.hono.get("/_health", (c) => {
+				return c.json({
+					status: "ok",
+					timestamp: Date.now(),
+					mwOrder: c.get("__ubean_mw_order__") ?? []
+				});
 			});
-		});
+		}
 	}
 	async init() {
 		if (this._ready) return this;
@@ -491,4 +422,107 @@ function createUbeanApp(options = {}) {
 	return new UbeanApp(options);
 }
 //#endregion
+//#region src/define-server.ts
+/**
+* Apply a resolved server config to a `UbeanApp` instance.
+*
+* This must be called BEFORE `app.init()` so that:
+* - `plugins` are available when `init()` calls `setup` / `ready`
+* - `hooks` are registered before `init()` fires `app:created` etc.
+* - `onAppCreate` runs before route registration
+* - `globalHooks` (handle/handleFetch/handleError) are set before any request
+*
+* `onServerReady` is NOT called here — the caller must invoke it after
+* `app.init()` completes.
+*/
+async function applyServerConfig(app, config) {
+	if (config.plugins.length > 0) app.plugins.push(...config.plugins);
+	for (const [name, handler] of Object.entries(config.hooks)) if (handler) app.hooks.hook(name, handler);
+	if (config.globalHooks) setGlobalHooks(config.globalHooks);
+	if (config.onAppCreate) await config.onAppCreate(app);
+}
+/**
+* Define the backend server configuration.
+*
+* This is the server-side counterpart of `defineApp`. It allows users to
+* inject plugins, register runtime hooks, and run startup/ready logic
+* from a simple entry file (`src/server.ts`).
+*
+* @example
+* ```ts
+* // src/server.ts
+* import { defineServer } from '@ubean/app';
+*
+* export default defineServer({
+*   plugins: [
+*     {
+*       name: 'my-plugin',
+*       setup(app) { app.use('/api/custom', handler); },
+*       ready(app) { /* routes registered *\/ }
+*     }
+*   ],
+*   hooks: {
+*     'request:start': (c) => { console.log(c.req.method, c.req.path); }
+*   },
+*   globalHooks: {
+*     handle: async ({ event, resolve }) => {
+*       const response = await resolve(event);
+*       response.headers.set('X-Custom', 'ubean');
+*       return response;
+*     },
+*     handleError: async ({ error, status }) => {
+*       console.error(`[${status}]`, error);
+*     }
+*   },
+*   onAppCreate: async (app) => { /* init db *\/ },
+*   onServerReady: async (app) => { /* start workers *\/ }
+* });
+* ```
+*/
+function defineServer(options) {
+	return {
+		plugins: options.plugins || [],
+		hooks: options.hooks || {},
+		globalHooks: options.globalHooks,
+		onAppCreate: options.onAppCreate,
+		onServerReady: options.onServerReady
+	};
+}
+/**
+* Create an empty server config — used as the fallback when no
+* `src/server.ts` file exists.
+*/
+function createDefaultServerConfig() {
+	return {
+		plugins: [],
+		hooks: {}
+	};
+}
+/**
+* Merge multiple server configs (shared + mode-specific) into one.
+* Plugins are concatenated; hooks are merged; mode-specific callbacks
+* override shared ones.
+*/
+function mergeServerConfigs(base, ...configs) {
+	const result = {
+		plugins: [...base.plugins],
+		hooks: { ...base.hooks },
+		globalHooks: base.globalHooks ? { ...base.globalHooks } : void 0,
+		onAppCreate: base.onAppCreate,
+		onServerReady: base.onServerReady
+	};
+	for (const cfg of configs) {
+		if (!cfg) continue;
+		if (cfg.plugins) result.plugins.push(...cfg.plugins);
+		if (cfg.hooks) Object.assign(result.hooks, cfg.hooks);
+		if (cfg.globalHooks) result.globalHooks = {
+			...result.globalHooks,
+			...cfg.globalHooks
+		};
+		if (cfg.onAppCreate) result.onAppCreate = cfg.onAppCreate;
+		if (cfg.onServerReady) result.onServerReady = cfg.onServerReady;
+	}
+	return result;
+}
+//#endregion
 export { UbeanApp, applyHandleErrorHook, applyHandleFetchHook, applyHandleHook, applyServerConfig, clearGlobalHooks, createDefaultServerConfig, createHandleEvent, createUbeanApp, defineServer, extractErrorMessage, getGlobalHooks, mergeServerConfigs, setGlobalHooks, wrapResolve };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ubean/app",
-  "version": "0.6.0",
+  "version": "0.6.1-beta.3",
   "description": "Hono app factory and server config for ubean (createUbeanApp, defineServer)",
   "files": [
     "dist"
@@ -16,26 +16,26 @@
     }
   },
   "dependencies": {
-    "@ubean/i18n": "0.6.0",
-    "@ubean/islands": "0.6.0",
-    "@ubean/routes": "0.6.0",
-    "@ubean/scan": "0.6.0",
-    "@ubean/server": "0.6.0",
-    "@ubean/shared": "0.6.0",
-    "hono": "4.13.12",
+    "@ubean/i18n": "0.6.1-beta.3",
+    "@ubean/islands": "0.6.1-beta.3",
+    "@ubean/routes": "0.6.1-beta.3",
+    "@ubean/scan": "0.6.1-beta.3",
+    "@ubean/server": "0.6.1-beta.3",
+    "@ubean/shared": "0.6.1-beta.3",
+    "hono": "4.13.13",
     "hookable": "^6.1.2",
     "pathe": "^2.0.3"
   },
   "devDependencies": {
     "@types/node": "^26.6.4",
-    "@ubean/pages": "0.6.0",
-    "@ubean/seo": "0.6.0",
+    "@ubean/pages": "0.6.1-beta.3",
+    "@ubean/seo": "0.6.1-beta.3",
     "typescript": "npm:typescript-native-bridge@latest",
-    "vite-plus": "1.0.0"
+    "vite-plus": "1.1.0"
   },
   "peerDependencies": {
-    "@ubean/pages": "0.6.0",
-    "@ubean/seo": "0.6.0"
+    "@ubean/pages": "0.6.1-beta.3",
+    "@ubean/seo": "0.6.1-beta.3"
   },
   "peerDependenciesMeta": {
     "@ubean/pages": {