@ubean/build 0.5.2 → 0.6.0-beta.1

package/dist/vite.d.ts

@@ -1,40 +1,631 @@
+import { i as VirtualModuleResolver, o as createVirtualRegistry, r as VirtualModuleRegistry } from "./virtual-registry-CaU8k-YP.js";
 import { ResolvedConfig } from "@ubean/config";
-import { Plugin } from "vite";
-//#region src/vite.d.ts
-export interface UbeanPluginOptions {
+import { ScanResult, ScannedLayout, ScannedPageRoute } from "@ubean/scan";
+import { Connect, DevEnvironment, DevEnvironmentContext, HotChannel, Logger, Plugin, ResolvedConfig as ResolvedConfig$1, ViteDevServer } from "vite";
+import { PageRenderer, PageRenderer as PageRenderer$1 } from "@ubean/pages";
+import { UbeanApp } from "@ubean/app";
+import { IncomingMessage, ServerResponse } from "node:http";
+//#region src/dev/dev-worker.d.ts
+/** 生成到 `.ubean/` 下的文件名。 */
+export declare const DEV_WORKER_FILE = "dev-worker.mjs";
+interface DevWorkerEntryOptions {
+  /** 与宿主 `UbeanDevEnvironment` 的环境名一致（env-runner 按它做命名空间过滤）。 */
+  envName: string;
+  /** worker 要加载的服务端入口模块 id（dev 下由宿主转换）。 */
+  entryId: string;
   /**
-   * 已解析的 ubean 配置。如果未提供,插件会按以下顺序获取:
-   * 1. 尝试从全局缓存读取(`loadUbeanConfig` 已被 CLI 调用时会有缓存)
-   * 2. 在 `buildStart` 中异步调用 `loadUbeanConfig()` 加载
+   * `env-runner/vite` 的定位符。默认是裸 specifier —— 只有当入口所在项目能解析到 env-runner
+   * 时才可用；入口被生成到项目 `.ubean/` 下时，由调用方（cli，它才有 env-runner 依赖）传入
+   * 解析后的绝对 `file://` URL，避免「worker 里 import 不到包」。
+   */
+  envRunnerVite?: string;
+  /** `vite/module-runner` 的定位符，同上。 */
+  moduleRunner?: string;
+}
+/**
+ * worker 入口源码。刻意保持纯 ESM、无类型语法 —— worker 直接由 Node 加载，不经过转换。
+ */
+export declare function getDevWorkerEntrySource(options: DevWorkerEntryOptions): string;
+/** 把 worker 入口写到 `<dir>/dev-worker.mjs`，返回其绝对路径（供 env-runner 的 `data.entry`）。 */
+export declare function writeDevWorkerEntry(dir: string, options: DevWorkerEntryOptions): Promise<string>;
+/**
+ * 失效指定文件对应的模块（RM-V13 的 watcher 会用它）。
+ *
+ * **宿主侧失效是充分且必须的一步**：`invalidateModule` 会清掉 `transformResult` 并沿 importer
+ * 链传播，于是 worker 下次取模块时拿到的是新代码（且 `fetchModule` 带回 `invalidate: true`），
+ * 未被命中的模块仍返回 `{ cache: true }`，实例（单例）保留 —— 这正是 R3 要求的语义。
+ *
+ * 难点在于**文件键**：Vite 的模块图按 `cleanUrl(resolvedId)` 建索引，而 resolvedId 是解析
+ * 符号链接后的真实路径。macOS 上 `os.tmpdir()` 返回 `/var/folders/...`，而 realpath 是
+ * `/private/var/folders/...`，watcher 给出的原始路径直接查表必然落空（RM-V09 实测）。
+ * 因此这里对每个文件同时尝试原始路径与 realpath 两种候选键。
+ *
+ * 返回值用于诊断：`urls` 为空即表示这次失效**什么都没命中**（多半是路径键不一致或模块尚未
+ * 被加载），调用方据此可以给出比「静默无操作」更有用的信息。
+ */
+interface DevWorkerInvalidation {
+  /** 实际命中模块图的键（去重）。 */
+  keys: string[];
+  /** 被失效的模块 URL（宿主侧唯一的稳定标识）。 */
+  urls: string[];
+}
+export declare function invalidateDevWorkerModules(environment: {
+  moduleGraph: {
+    getModulesByFile(file: string): Iterable<{
+      url?: string | null;
+    }> | undefined;
+    invalidateModule(mod: never): void;
+  };
+}, runner: {
+  sendMessage(message: unknown): void;
+}, files: readonly string[]): DevWorkerInvalidation;
+//#endregion
+//#region src/dev/dev-environment.d.ts
+/**
+ * env-runner runner 在本模块用到的最小面。
+ *
+ * 只声明用到的成员而不是 `import type { EnvRunner } from 'env-runner'`：builder 包不必为了
+ * dev 环境把 env-runner 拉进类型依赖，任何满足该形状的 runner 都能用。
+ */
+interface EnvRunnerLike {
+  sendMessage(message: unknown): void;
+  onMessage(listener: (message: unknown) => void): void;
+  /** 把请求交给 worker 内的 handler（env-runner 的 `FetchHandler` 直接接受 `Request`）。 */
+  fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
+}
+/** 与 worker 侧 `createViteTransport(sendMessage, onMessage, envName)` 必须一致。 */
+export declare const UBEAN_DEV_ENV_NAME = "ubean";
+/**
+ * 宿主 → worker 的 transport 适配器。
+ *
+ * 只实现 Vite `HotChannel` 里能实现的部分：`send` 把 payload 送到 worker，`on`/`off` 维护
+ * 本地监听表。`skipFsCheck` 置真 —— 同进程 IPC 不是网络通道，无需 fs 访问检查。
+ * Vite 会在 `DevEnvironment` 构造时把它规范化（补 `setInvokeHandler` / `handleInvoke`）。
+ */
+export declare function createEnvRunnerTransport(runner: EnvRunnerLike, envName?: string): HotChannel;
+/**
+ * 把 worker 发来的 `vite:invoke` 交给 Vite 计算并回发。
+ *
+ * 回发结构照抄 vite-plus 自己的实现（`dist/vite/node/chunks/node.js:32291-32313`）：
+ * 应答 id 由 `send*` 改成 `response*`，`data` 为 `handleInvoke()` 的 `{ result }` / `{ error }`。
+ * **必须在 `DevEnvironment` 构造之后调用** —— 那时 `environment.hot` 才存在。
+ */
+export declare function bridgeEnvRunnerInvokes(environment: DevEnvironment, runner: EnvRunnerLike, envName?: string): void;
+export declare class UbeanDevEnvironment extends DevEnvironment {
+  #private;
+  constructor(name: string, config: ResolvedConfig$1, context: DevEnvironmentContext, runner: EnvRunnerLike);
+  /**
+   * ADR-0012 §3：框架请求入口把 Web `Request` 转发进 worker 内的 Hono app。
+   * 宿主进程不再执行服务端代码，因此服务端崩溃不会带走 dev server。
+   */
+  dispatchFetch(request: Request): Promise<Response>;
+}
+/**
+ * 生成 `environments.<name>.dev.createEnvironment` 需要的工厂（RM-V09 的能力，**尚未接线** ——
+ * 全仓没有 `createEnvironment` 的注册点，原因见文件头「当前状态」）。
+ */
+export declare function createUbeanDevEnvironmentFactory(runner: EnvRunnerLike): (name: string, config: ResolvedConfig$1, context: DevEnvironmentContext) => UbeanDevEnvironment;
+//#endregion
+//#region src/dev/dev-request-router.d.ts
+/**
+ * DevTools 相关、**必须交给 Vite** 的命名空间前缀（DTK 外壳 + ubean DevTools SPA）。
+ *
+ * 它们全落在 `_` / `__` 保留命名空间里，判据默认会判给 ubean → 应用 404，因此调用方要把这份
+ * 前缀整体传给 `passThrough`。两个条目覆盖了 DTK 实际使用的四个名字：
+ * - `/__devtools` → `/__devtools/`（外壳 HTML、RPC、WS）、`/__devtools-assets/`（DTK 自带 UI
+ *   的静态资源，dock 图标的 `vite-plus.svg` 就在这里）、`/__devtools-client-imports.js`
+ *   （dock 客户端模块的虚拟模块）；
+ * - `/_devtools` → `/_devtools/index.html`（DTK 以 iframe 载入的 SPA）及其 `assets/*` 与
+ *   `/_devtools/__connection.json`。裸 `/_devtools` 由 `devtoolsRedirect` 抢先 302，不受影响。
+ *
+ * 2026-09-17 实测：`/__devtools-assets/vite-plus.svg`（应用页控制台报 404）与
+ * `/_devtools/index.html`（DevTools 面板空白的真凶）此前都落进了应用 404。
+ */
+export declare const DEVTOOLS_PASS_THROUGH_PREFIXES: string[];
+/** 该 URL 是否指向框架内置的 HTML 页面（见 {@link FRAMEWORK_HTML_PAGES}）。 */
+export declare function isFrameworkHtmlPage(url: string): boolean;
+/**
+ * 这个请求是不是「Vite 的资源请求」？`true` → 交给 Vite；`false` → 归 ubean。
+ *
+ * 纯函数（只读 URL 与请求头），便于单测钉住判据 —— 这是 RM-V10 最容易出错的部分。
+ */
+export declare function isViteResourceRequest(url: string, headers?: IncomingMessage['headers']): boolean;
+/**
+ * 从客户端模块图收集 render-blocking CSS 链接。
+ *
+ * dev 下由 JS 引入的 CSS（虚拟 uno.css 入口、全局样式、字体 css）要等客户端模块图执行完才生效，
+ * SSR HTML 在这段间隙是**无样式**的（FOUC）。把同一批 CSS 以阻塞 `<link>` 注入，浏览器可与 JS
+ * 并行抓取，首屏即有样式。
+ *
+ * `?direct` 让 Vite 的 transform 中间件返回原始 CSS（`Content-Type: text/css`）而不是注入式 JS
+ * 包装；URL 自带查询串的模块（SFC `<style>` 块形如 `*.vue?vue&type=style`）无法这样服务，跳过。
+ */
+export declare function collectDevCssLinks(moduleGraph: ViteDevServer['environments']['client']['moduleGraph']): string[];
+/** 在 `</head>` 前插入阻塞样式链接。 */
+export declare function injectStylesheetLinks(html: string, hrefs: string[]): string;
+interface DevRequestRouterOptions {
+  /**
+   * 处理归属 ubean 的请求。省略时插件**自举**宿主 dev app（`vite dev` / `vp dev` 场景）：
+   * 首个应用请求时才扫盘、加载配置与 SSR 图 —— 启动期不做这些工作，`vite dev` 的冷启动
+   * 不受框架影响。
+   *
+   * `ubean dev` 传入 CLI 造好的 app 的 handler（它需要在 Vite server 起来之前就把 app
+   * 交给 DevTools / runner），因此两条路径共用同一层路由判据与 outbound 处理。
+   */
+  handler?: (request: Request, context: {
+    url: string;
+  }) => Promise<Response>;
+  /** `handler` 省略时的自举参数。 */
+  bootstrap?: DevBootstrapOptions;
+  /**
+   * 额外**必须交给 Vite** 的路径前缀（按字符串前缀匹配，不要求后随 `/`）。
+   *
+   * 有些由其他 Vite 插件挂载的路径也落在 `_` / `__` 保留命名空间里（例如 DevTools 外壳挂在
+   * `/__devtools/`）。判据把保留命名空间一律判给 ubean，于是这些路径会被交给应用 → 404。
+   * 由调用方显式声明，避免把某个插件的路径写死进通用判据。
+   *
+   * **匹配是裸前缀**：`/__devtools` 同时覆盖 `/__devtools/`、`/__devtools-assets/`、
+   * `/__devtools-client-imports.js` 这类同名前缀的兄弟路径 —— 插件的命名空间往往不止一个以
+   * `/` 结尾的挂载点（DTK 就是三处），按路径段匹配会漏掉它们。声明者只需给出命名空间本身。
+   */
+  passThrough?: string[];
+  /**
+   * 把 `/_devtools`（含尾斜杠）302 到 `/__devtools/`，让用户从 CLI banner 进到带 dock 侧栏的
+   * DevTools 外壳而不是单独的 SPA。`/_devtools/` **下**的静态资源保持直接可达（外壳以 iframe
+   * 载入 `/_devtools/index.html#/route`），因此只重定向这两个空路径。
+   *
+   * 由本插件自己挂载（而不是让调用方另注册一个插件）就是为了顺序：重定向必须先于请求判据。
+   */
+  devtoolsRedirect?: boolean;
+  /**
+   * 跳过 HTML transform 的路径判定。预构建 SPA（如 `/_devtools`）的产物自带模块引用，
+   * 经 `transformIndexHtml` 重写会被破坏。
+   */
+  skipHtmlTransform?: (url: string) => boolean;
+  /** 错误回调（默认走 Vite logger 的 error）。 */
+  onError?: (error: unknown, context: {
+    url: string;
+  }) => void;
+}
+interface DevBootstrapOptions {
+  /** 项目根目录，默认取 `server.config.root`。 */
+  rootDir?: string;
+  /** 覆盖配置加载（默认 `loadUbeanConfig(rootDir)`，会命中 CLI 已设置的缓存）。 */
+  loadConfig?: (rootDir: string) => Promise<ResolvedConfig>;
+  /** crons 加载完后的启动钩子；缺省动态加载 `@ubean/server/cron`。 */
+  startCronScheduler?: () => unknown;
+}
+/** 取该 dev server 上自举出的 app（还没自举时返回 undefined）。 */
+export declare function getDevApp(server: ViteDevServer): {
+  fetch: (request: Request) => Response | Promise<Response>;
+} | undefined;
+interface DevRequestHandlers {
+  /** `configureServer` 钩子体内使用：排在 Vite transform/静态中间件之前。 */
+  pre: Connect.NextHandleFunction;
+  /** 钩子返回的函数内使用：排在 Vite 静态中间件之后，兜底。 */
+  post: Connect.NextHandleFunction;
+}
+/**
+ * 构造 pre / post 两个 connect 中间件。
+ *
+ * 需要 Vite dev server 实例：一是拿不到它就调不了 `transformIndexHtml`（客户端入口注入），
+ * 二是 CSS 链接要从**客户端**环境的模块图里收集。
+ */
+export declare function createUbeanRequestHandlers(server: ViteDevServer, options: DevRequestRouterOptions): DevRequestHandlers;
+/**
+ * 把请求路由注册进 Vite 插件生命周期（RM-V10 的插件形态）。
+ *
+ * `appType: 'custom'` 是**必须**的：默认的 `spa`/`mpa` 会在静态中间件之后挂
+ * `htmlFallbackMiddleware` + `indexHtmlMiddleware`，把未知路径一律改写成 `index.html`
+ * 并用 Vite 自己的 HTML 服务 —— 那样页面请求就轮不到 ubean 了。设为 `custom` 后这两层被摘掉，
+ * 未匹配请求正好落到我们的 post 中间件。
+ */
+export declare function ubeanDevRequestPlugin(options: DevRequestRouterOptions): Plugin;
+//#endregion
+//#region src/dev/node-web.d.ts
+/**
+ * `node:http` 请求 → Web `Request`。
+ *
+ * 非 GET/HEAD 时直接把 `IncomingMessage`（可读流）作为 body；undici 要求流式 body 显式
+ * 声明 `duplex: 'half'`，否则构造 `Request` 会抛错。
+ */
+export declare function toWebRequest(req: IncomingMessage, host: string, protocol: string): Promise<Request>;
+/** Web `Response` → `node:http` 响应：写入状态与头，再流式转发 body（不整体缓冲）。 */
+export declare function sendWebResponse(res: ServerResponse, webRes: Response): Promise<void>;
+//#endregion
+//#region src/vite/cloudflare-preview.d.ts
+/** miniflare 实例的最小面（只声明用到的部分，避免把可选依赖的类型带进公共类型）。 */
+interface MiniflareInstanceLike {
+  ready: Promise<unknown>;
+  dispatchFetch(input: string, init?: {
+    method?: string;
+    headers?: Headers | Record<string, string>;
+    body?: BodyInit;
+  }): Promise<Response>;
+  dispose(): Promise<void>;
+}
+type MiniflareConstructorLike = new (options: Record<string, unknown>) => MiniflareInstanceLike;
+interface CloudflarePreviewOptions {
+  /** 产物里的 worker 入口（`<outputDir>/server/worker.mjs`）。 */
+  workerPath: string;
+  /** 兼容性日期（来自 preset；缺省用 wrangler.toml 同款默认值）。 */
+  compatibilityDate?: string;
+  /** 兼容性标志（来自 wrangler.toml；缺省为 `['nodejs_compat']`，与生成的配置一致）。 */
+  compatibilityFlags?: string[];
+  /** 测试注入点：默认动态 import `miniflare`。 */
+  loadMiniflare?: () => Promise<MiniflareConstructorLike | null>;
+}
+interface CloudflarePreviewRunner {
+  /** 把 Web `Request` 派发进 worker（静态层由调用方先行处理）。 */
+  fetch: (request: Request) => Promise<Response>;
+  dispose: () => Promise<void>;
+}
+type CloudflarePreviewResult = {
+  ok: true;
+  runner: CloudflarePreviewRunner;
+} | {
+  ok: false;
+  reason: 'miniflare-not-installed' | 'worker-missing' | 'worker-failed-to-start';
+  message: string;
+};
+export declare const MINIFLARE_INSTALL_HINT = "Install it with `pnpm add -D miniflare`, or preview with `wrangler dev` instead.";
+/**
+ * 默认加载器：动态 import `miniflare`。
+ *
+ * 规格字符串放进变量是**故意的** —— 让打包器无法静态解析这个可选依赖（否则构建会尝试解析一个
+ * 未安装的包）。
+ */
+export declare function defaultLoadMiniflare(): Promise<MiniflareConstructorLike | null>;
+/**
+ * 创建 Cloudflare 预览 runner。
+ *
+ * 失败不抛错：返回带 `reason` 的结果，让调用方决定是降级提示还是继续（与可选依赖的整体策略一致）。
+ */
+export declare function createCloudflarePreviewRunner(options: CloudflarePreviewOptions): Promise<CloudflarePreviewResult>;
+/** 从 wrangler.toml 里取兼容性日期（preset 生成的文件就是它的产物契约）。 */
+export declare function readCompatibilityDate(wranglerToml: string): string | undefined;
+//#endregion
+//#region src/vite/preview.d.ts
+/** 静态文件的 MIME 推断（CLI 的静态服务器与本插件共用）。 */
+export declare function previewMimeType(filePath: string): string;
+/**
+ * 解析结果三态：命中文件 / 越界（400）/ 未命中（404）。
+ *
+ * 「越界」必须与「未命中」分开 —— 它们对应不同的状态码与语义，混成一个 404 会把路径穿越
+ * 攻击伪装成普通未命中。
+ */
+type PreviewFileResolution = {
+  kind: 'file';
+  path: string;
+} | {
+  kind: 'forbidden';
+} | {
+  kind: 'missing';
+};
+/**
+ * 把请求路径解析为静态文件（spa / ssg 的规则，单一实现）。
+ *
+ * 不能用 `pathname.includes('..')` 判穿越：文件名里合法的 `...` 会被误伤（SSG 动态路由产物
+ * `_...slug_-Bqlu_Muj.js` 实测踩过）。判据只能是**规范化后的路径是否仍在 root 内**。
+ */
+export declare function resolvePreviewFile(root: string, pathname: string, mode: 'spa' | 'ssg'): PreviewFileResolution;
+/** 把解析结果写成响应；命中文件时流式返回内容。 */
+export declare function sendPreviewFile(res: ServerResponse, path: string): Promise<void>;
+export declare function sendPreviewStatus(res: ServerResponse, status: 400 | 404 | 500 | 501, text: string): void;
+type PreviewNext = (err?: unknown) => void;
+interface UbeanPreviewMiddlewareOptions {
+  /** 项目根目录。 */
+  rootDir: string;
+  /** 产物根目录（`config.build.outputDir`）。 */
+  outputDir: string;
+  mode: ResolvedConfig['mode'];
+  /**
+   * 平台 preset 名。`cloudflare` 走 miniflare runner（RM-V26）—— 产物是 worker，Node 进程内
+   * import 不出来；其余 preset 一律用 `entry.mjs`（所有 preset 共同的真实产物）。
    */
+  presetName?: string;
+  /** 监听地址，用于把请求 URL 补全为绝对地址。 */
+  host?: string;
+  /** 测试注入点：覆盖 miniflare 加载器。 */
+  loadMiniflare?: CloudflarePreviewOptions['loadMiniflare'];
+}
+type PreviewMiddleware = (req: IncomingMessage, res: ServerResponse, next: PreviewNext) => void;
+/**
+ * 预览中间件：按 mode 选择「生产 handler」或「静态文件」。
+ *
+ * 生产 handler 只加载一次（`entry.mjs` 的模块级单例因此保留，与生产行为一致），失败时把
+ * 错误写进响应而不是让 `vite preview` 挂住 —— 预览最常见的失败就是「忘了先构建」。
+ */
+export declare function createPreviewMiddleware(options: UbeanPreviewMiddlewareOptions): PreviewMiddleware;
+interface UbeanPreviewPluginOptions {
   config?: ResolvedConfig;
+  /** 覆盖监听地址（用于补全请求 URL）。 */
+  host?: string;
+}
+/** Connect 中间件栈的最小接口（Vite dev / preview server 都满足）。 */
+interface PreviewMiddlewareHost {
+  middlewares: {
+    use: (fn: PreviewMiddleware) => void;
+  };
+}
+/**
+ * 把预览中间件挂到 server 上。
+ *
+ * 由**核心插件**调用（同 dev 的请求路由）：「哪条路径都必然注册的那一个插件」才拿得到两端
+ * 共用的配置；独立插件从别的插件的 `config` 钩子里注入，在环境化构建下到不了每个环境
+ * （RM-V21 踩过同一个坑）。
+ */
+export declare function attachPreviewMiddleware(server: PreviewMiddlewareHost, config: ResolvedConfig, host?: string): void;
+/**
+ * 独立的预览插件（`vite preview` 的显式形态）。
+ *
+ * 核心插件已内置同一份接线（`attachPreviewMiddleware`），这里保留独立导出便于测试与
+ * 「不走 `ubeanPlugin()`」的场景。
+ */
+export declare function ubeanPreviewPlugin(options?: UbeanPreviewPluginOptions): Plugin;
+//#endregion
+//#region src/dev/dev-ssr-routes.d.ts
+/** 扫描器方言 `**:slug`（catch-all）→ vue-router 的 `:slug(.*)*`。 */
+export declare function toVueRouterPagePath(route: string): string;
+/** vue-router 路由记录的运行期形状（只声明 dev 侧真正用到的字段）。 */
+interface DevSsrRoute {
+  path: string;
+  name: string;
+  /** 普通路由用 `component`；并行路由（`@slot/`）用 `components` 命名视图，二者互斥。 */
+  component?: () => Promise<unknown>;
+  components?: Record<string, () => Promise<unknown>>;
+  meta: {
+    /** 单层布局名、多层嵌套数组（P9-17）或 `false`（禁用）。 */
+    layout: string | string[] | false | null;
+    pageName: string;
+    cache?: true;
+  };
+}
+interface DevSsrRoutesOptions {
+  pages: readonly ScannedPageRoute[];
+  layouts: readonly ScannedLayout[];
+  /**
+   * 组件加载器。dev 下必须是「经 Vite SSR 图加载」（`ssrLoadModule`），否则 SSR 会用到
+   * 另一份 vue/vue-router 实例，注入键（实例级 Symbol）不一致 → 渲染直接崩。
+   */
+  loadComponent: (fullPath: string) => Promise<unknown>;
+  /** 与客户端 `virtual:ubean-pages` 相同的 locale param（如 `:locale(zh)?`）。 */
+  localeVueParam?: string;
+  /** `pages/404.vue` 经扫描得到的条目；缺省则不注册 catch-all。 */
+  notFoundPage?: ScannedPageRoute;
+}
+/**
+ * 构建 SSR 路由表。
+ *
+ * 顺序与形状刻意对齐客户端：页面按扫描顺序、reuse 路由复用目标页面的组件、
+ * 最后是 404 catch-all。catch-all 用 `/:locale?/:pathMatch(.*)*` —— SSR 渲染的是
+ * **请求 URL 本身**（不像 SSG 渲染静态产物、可以用 `/404`），必须与客户端同形才能
+ * 让两侧 `useRoute()` 解析出同一份 matched 结构。
+ */
+export declare function buildDevSsrRoutes(options: DevSsrRoutesOptions): DevSsrRoute[];
+//#endregion
+//#region src/dev/dev-host-app.d.ts
+/** `@ubean/app` 的 `UbeanApp` 在本模块用到的最小面。 */
+interface DevHostAppLike {
+  options: {
+    layouts?: ScannedLayout[];
+    routes?: Array<{
+      relativePath: string;
+      fullPath: string;
+    }>;
+    pages?: ScannedPageRoute[];
+    middleware?: Array<{
+      relativePath: string;
+      fullPath: string;
+    }>;
+    crons?: Array<{
+      fullPath: string;
+    }>;
+    notFoundPage?: ScannedPageRoute;
+    routeLoaders?: Record<string, () => Promise<unknown>>;
+    pageLoaders?: Record<string, () => Promise<unknown>>;
+    middlewareLoaders?: Record<string, () => Promise<unknown>>;
+    pageRenderer?: PageRenderer$1 | null;
+  };
+  resetInit(): void;
+}
+/** 渲染器工厂的入参（与 `@ubean/client/ssr` 的 `createVueRenderer` 同形）。 */
+interface DevRendererOptions {
+  routes: ReturnType<typeof buildDevSsrRoutes>;
+  resolveLayoutComponent: (name: string | false | null | undefined) => Promise<unknown>;
+  defaultLayout: string | null;
+  resolveAppConfig: () => Promise<unknown>;
+}
+interface EnhanceDevAppOptions {
+  app: DevHostAppLike;
+  layouts?: ScannedLayout[];
+  /** 经 Vite SSR 图加载模块；dev 下必须是 `server.ssrLoadModule`。 */
+  loadModule: (id: string) => Promise<unknown>;
+  /**
+   * 渲染器工厂。**必须**取自 Vite SSR 图
+   * （`(await server.ssrLoadModule('@ubean/client/ssr')).createVueRenderer`）：
+   * 静态 import 会让 `@ubean/client` 用自身嵌套的 vue-router 副本创建 router（provide 侧），
+   * 而组件在 Vite SSR 图里解析到另一副本（inject 侧），注入键是实例级 Symbol，不一致即崩。
+   * 每次 enhance 都会调用它 —— 路由表与会话内的配置缓存都随之刷新。
+   */
+  createRenderer: (options: DevRendererOptions) => PageRenderer$1;
+  /** 与客户端 `virtual:ubean-pages` 相同的 locale param（`:locale(zh)?`）。 */
+  localeVueParam?: string;
+  /** `backend` 模式无页面与 SSR，跳过 pageRenderer 创建。 */
+  backend?: boolean;
+  /** crons 加载完后的启动钩子（CLI 传 `@ubean/server/cron` 的 `startCronScheduler`）。 */
+  startCronScheduler?: () => unknown;
+  /** 诊断用日志（默认 `console.error`，与原先行为一致）。 */
+  onCronError?: (error: unknown) => void;
+}
+/**
+ * 把 Vite SSR 图的加载器与 SSR 渲染器接到 host app 上。
+ *
+ * 必须在**每次** app 实例更新后调用（CLI 的 `updateApp`）：闭包持有模块加载器，
+ * HMR 后需要重新指向新的扫描结果与 Vite 模块图。
+ */
+export declare function enhanceDevApp(options: EnhanceDevAppOptions): DevHostAppLike;
+//#endregion
+//#region src/dev/dev-scan.d.ts
+/** `server.watcher` 用到的最小面（测试可传假实现）。 */
+interface DevScanSource {
+  add(target: string): void;
+  on(event: 'add' | 'unlink' | 'change', handler: (file: string) => void): void;
+  off?(event: 'add' | 'unlink' | 'change', handler: (file: string) => void): void;
+}
+type DevScanSubscriber = (result: ScanResult, changed: string[]) => void | Promise<void>;
+/** 触发扫描的目录名（相对 `srcDir`）。并集来自 core 与 vue 两个插件此前的清单。 */
+export declare const DEV_SCAN_DIRS: readonly ["routes", "middleware", "pages", "layouts", "plugins", "app", "api", "locales"];
+interface DevScanCoordinatorOptions {
+  /** 项目根目录（绝对）。 */
+  rootDir: string;
+  /** `srcDir`（绝对或相对 rootDir）。 */
+  srcDir: string;
+  dirs?: ResolvedConfig['dir'];
+  ignore?: string[];
+  source: DevScanSource;
+  /** 扫描实现；默认 `scanProject`（调用方一般不需要覆盖）。 */
+  scan?: () => Promise<ScanResult>;
+  /** 扫描结束后、重载前的用户回调（`full-reload` 由协调器统一发）。 */
+  reload?: () => void;
+  debounceMs?: number;
+  /** 扫描失败回调；默认打到 console.error。 */
+  onError?: (error: unknown) => void;
 }
+interface DevScanCoordinator {
+  /** 注册订阅者，返回取消订阅。 */
+  subscribe(fn: DevScanSubscriber): () => void;
+  /** 建立监听（幂等）。 */
+  start(): void;
+  /** 手动触发一次扫描（DevTools CRUD 后、测试）。 */
+  rescan(changed?: string[]): Promise<ScanResult>;
+  /** 是否已有订阅者（供调用方判断「框架是否接管了 dev 重载」）。 */
+  subscriberCount(): number;
+  stop(): void;
+}
+export declare function createDevScanCoordinator(options: DevScanCoordinatorOptions): DevScanCoordinator;
 /**
- * ubean 核心 Vite 插件(框架无关部分)。
+ * 取（或建立）该 dev server 的协调器。
  *
- * 提供:
- * - 虚拟模块(`ubean:routes`、`ubean:pages`、`ubean:meta`、`ubean:app-config`、`ubean:locales`)
- * - 宏转换(`definePage` / `defineMeta` 在 `.ts` / `.vue` 中被剥离)
- * - 文件监听(dev 模式下扫描 `routes` / `middleware` / `pages` / `layouts` / `plugins` / `locales`)
- * - 实体路由文件生成(当 `routing.mode` 为 `'file'` 或 `'both'` 时触发 `@ubean/vue/generator`)
+ * core 与 vue 插件都调用它，因此**先到的那个**负责建实例；后到的拿同一个。
+ * `init` 只在首次调用时执行。
+ */
+export declare function getDevScanCoordinator(server: ViteDevServer, init: (source: DevScanSource) => DevScanCoordinatorOptions): DevScanCoordinator;
+/**
+ * 取该 dev server **已存在**的协调器（不存在返回 undefined）。
  *
- * Vue 专属的虚拟模块(`virtual:ubean-pages`、`virtual:ubean-app` 等)由 `@ubean/build/vue` 的
- * `ubeanVite` 提供,二者共用 `useVirtualRegistry()` 注册表。
+ * 给「只想触发一次扫描」的调用方用（CLI 的 `rescan()`）：`getDevScanCoordinator` 需要 init
+ * 参数、会在缺失时建实例，不适合这里。
+ */
+export declare function peekDevScanCoordinator(server: ViteDevServer): DevScanCoordinator | undefined;
+/**
+ * 订阅 dev 扫描（CLI 用：每次扫描后重建 Hono app 并让浏览器重载）。
  *
- * @example 在 vite.config.ts 中使用(自动加载 ubean.config)
- * ```typescript
- * import { defineConfig } from 'vite';
- * import { ubeanPlugin } from '@ubean/build/vite';
+ * 允许在协调器建立之前订阅：`getDevScanCoordinator` 会把已登记的订阅转交给新实例。
+ */
+export declare function onDevScan(server: ViteDevServer, handler: DevScanSubscriber): () => void;
+//#endregion
+//#region src/dev/dev-app.d.ts
+/** 本模块用到的最小 logger 面（与 Vite 的 `Logger` 兼容，便于直接传 `server.config.logger`）。 */
+type BootstrapLogger = Pick<Logger, 'warn' | 'error' | 'info'>;
+interface CreateDevAppOptions {
+  rootDir: string;
+  config: ResolvedConfig;
+  /**
+   * 已扫描的结果。调用方若为其它目的（如 codegen）已经扫过盘，传进来即可避免二次扫描。
+   */
+  scanResult?: ScanResult;
+  /** dev 安全头配置（CLI 会按 `--no-security` 等命令行覆盖）。缺省按 `config.security` 推导。 */
+  securityHeaders?: boolean | Record<string, unknown>;
+  /** 额外的 app 装配（调用方插入自己的中间件/hook）。 */
+  configureApp?: (app: UbeanApp) => void;
+  /** 诊断日志（请求日志、cron 加载失败等）。 */
+  logger?: BootstrapLogger;
+}
+interface DevApp {
+  app: UbeanApp;
+  scanResult: ScanResult;
+  layouts: ScannedLayout[];
+}
+/** 扫描（可选）并创建 dev 用的宿主 app —— 不需要 Vite server。 */
+export declare function createDevApp(options: CreateDevAppOptions): Promise<DevApp>;
+interface DevAppReadyOptions {
+  app: UbeanApp;
+  /** 经 Vite SSR 图加载模块（`server.ssrLoadModule`）。 */
+  loadModule: (id: string) => Promise<unknown>;
+  logger?: BootstrapLogger;
+}
+interface DevAppReady {
+  /** 幂等：同一个 app 实例内只做一次真正的初始化，后续请求复用同一个 promise。 */
+  (): Promise<void>;
+  /** ready 之后可读到用户的 server 配置（`onServerReady` 等）。 */
+  serverConfig(): {
+    onServerReady?: (app: UbeanApp) => unknown;
+  } | null;
+}
+/**
+ * 首次处理请求前的初始化：加载 locales、应用用户 `defineServer` 配置、`app.init()`、
+ * 调一次 `onServerReady`。
  *
- * export default defineConfig({
- *   plugins: [ubeanPlugin()]
- * });
- * ```
+ * 每次 app 实例更换后都要重新建一个（CLI 的 `updateApp` / HMR 之后）：新实例需要重新应用
+ * 配置并重新走 init，旧实例的 ready 缓存不能复用。
+ */
+export declare function createDevAppReady(options: DevAppReadyOptions): DevAppReady;
+interface BootstrapDevAppOptions extends CreateDevAppOptions {
+  /** 经 Vite SSR 图加载模块（`server.ssrLoadModule`）。 */
+  loadModule: (id: string) => Promise<unknown>;
+  /** 渲染器工厂，必须取自 Vite SSR 图（见 `DevRendererOptions`）。 */
+  createRenderer: (options: DevRendererOptions) => PageRenderer;
+  /** crons 加载完后的启动钩子。 */
+  startCronScheduler?: () => unknown;
+  logger?: BootstrapLogger;
+}
+interface DevAppBootstrap extends DevApp {
+  ready: DevAppReady;
+  /**
+   * 扫描结果变化后重建 app（新页面 / 新路由文件必须被注册）。
+   *
+   * 插件自举路径（`vite dev`）靠它保持 dev 行为与 CLI 一致：CLI 路径有自己的 `onScan`
+   * 订阅者重建 app，插件路径则在自举 handler 里订阅同一次扫描 —— 两条路径各自只重建一次。
+   */
+  rebuild(scanResult: ScanResult): Promise<void>;
+}
+/**
+ * 插件自举入口：创建 app → 接上 Vite SSR 图 → 准备好 ready。
  *
- * @example 显式传入配置(ubean dev/build 内部使用)
- * ```typescript
- * ubeanPlugin({ config: resolvedConfig })
- * ```
+ * `vite dev` 场景下由框架插件调用（无 CLI 参与）；`ubean dev` 目前分两步调用
+ * （`createDevApp` 在 CLI、`createDevAppReady` 在 dev server），因为 CLI 需要在 Vite server
+ * 建起来之前就把 app 交给 DevTools/runner。RM-V12 摘除 CLI 的 server 层后两者会合并。
  */
+export declare function bootstrapDevApp(options: BootstrapDevAppOptions): Promise<DevAppBootstrap>;
+/**
+ * `config.security` → dev 安全头默认值。
+ *
+ * ssg 模式默认关闭：静态产物没有框架运行时的安全头，dev 下也没有需要保护的服务端渲染面。
+ */
+export declare function resolveDevSecurityHeaders(config: ResolvedConfig): boolean | Record<string, unknown>;
+/**
+ * locale param 必须与客户端 `virtual:ubean-pages` 的路由表一致，否则 `/zh/xxx` 在服务端
+ * 落不到对应路由（会掉进 404 catch-all），而客户端渲染的是真实页面 → 水合不一致。
+ * i18n 未启用或不需要前缀时返回空串。
+ */
+export declare function resolveLocaleVueParam(config: ResolvedConfig): string;
+//#endregion
+//#region src/vite.d.ts
+export interface UbeanPluginOptions {
+  /**
+   * 已解析的 ubean 配置。如果未提供,插件会按以下顺序获取:
+   * 1. 尝试从全局缓存读取(`loadUbeanConfig` 已被 CLI 调用时会有缓存)
+   * 2. 在 `buildStart` 中异步调用 `loadUbeanConfig()` 加载
+   */
+  config?: ResolvedConfig;
+  /**
+   * 虚拟模块注册表（RM-V02）。框架路径（build / dev / 主包 vite 入口）**显式注入**一个
+   * 由 scan 结果构建的实例；未注入时本插件自建一个实例级注册表，不再使用模块级单例 ——
+   * 插件因此不持有跨构建的可变状态。
+   */
+  registry?: VirtualModuleRegistry;
+}
 export declare function ubeanPlugin(options?: UbeanPluginOptions): Plugin;
-//#endregion
+//#endregion
+export { type BootstrapDevAppOptions, type BootstrapLogger, type CloudflarePreviewOptions, type CloudflarePreviewResult, type CloudflarePreviewRunner, type CreateDevAppOptions, type DevApp, type DevAppBootstrap, type DevAppReady, type DevAppReadyOptions, type DevHostAppLike, type DevRendererOptions, type DevRequestHandlers, type DevRequestRouterOptions, type DevScanCoordinator, type DevScanCoordinatorOptions, type DevScanSource, type DevScanSubscriber, type DevSsrRoute, type DevSsrRoutesOptions, type DevWorkerEntryOptions, type EnhanceDevAppOptions, type EnvRunnerLike, type MiniflareConstructorLike, type MiniflareInstanceLike, type PreviewFileResolution, type PreviewMiddleware, type PreviewMiddlewareHost, type UbeanPreviewMiddlewareOptions, type UbeanPreviewPluginOptions, type VirtualModuleRegistry, type VirtualModuleResolver, createVirtualRegistry };

package/dist/vite.js

@@ -1,2 +1,4 @@
-import { t as ubeanPlugin } from "./vite-D2EZl_6P.js";
-export { ubeanPlugin };
+import { m as createVirtualRegistry } from "./ssr-singleton-DPTawJSx.js";
+import { C as buildDevSsrRoutes, D as getDevScanCoordinator, E as createDevScanCoordinator, O as onDevScan, S as enhanceDevApp, T as DEV_SCAN_DIRS, _ as bootstrapDevApp, b as resolveDevSecurityHeaders, c as collectDevCssLinks, d as injectStylesheetLinks, f as isFrameworkHtmlPage, g as toWebRequest, h as sendWebResponse, k as peekDevScanCoordinator, l as createUbeanRequestHandlers, m as ubeanDevRequestPlugin, p as isViteResourceRequest, s as DEVTOOLS_PASS_THROUGH_PREFIXES, u as getDevApp, v as createDevApp, w as toVueRouterPagePath, x as resolveLocaleVueParam, y as createDevAppReady } from "./vue-BrbbaXTC.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-DvHEv7Op.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, getDevApp, getDevScanCoordinator, getDevWorkerEntrySource, injectStylesheetLinks, invalidateDevWorkerModules, isFrameworkHtmlPage, isViteResourceRequest, onDevScan, peekDevScanCoordinator, previewMimeType, readCompatibilityDate, resolveDevSecurityHeaders, resolveLocaleVueParam, resolvePreviewFile, sendPreviewFile, sendPreviewStatus, sendWebResponse, toVueRouterPagePath, toWebRequest, ubeanDevRequestPlugin, ubeanPlugin, ubeanPreviewPlugin, writeDevWorkerEntry };