@uni-helper/vite-plugin-uni-pages 0.5.0 → 0.6.0

package/dist/index.d.mts

@@ -1,9 +1,9 @@
+import fs from "node:fs";
 import { FSWatcher } from "chokidar";
 import { Logger, Plugin, ViteDevServer } from "vite";
-import Debug from "debug";
 import { LoadConfigSource } from "unconfig";
-import fs from "node:fs";
 import { CallExpression } from "@babel/types";
+import Debug from "debug";
 import { SFCDescriptor, SFCParseOptions } from "@vue/compiler-sfc";
 import { PageItem, PagesConfig, SubPackages, TabBar, TabBarItem, UserPagesConfig } from "@uni-helper/uni-pages-types";
 export type * from "@uni-helper/uni-pages-types";
@@ -22,7 +22,7 @@ export type * from "@uni-helper/uni-pages-types";
  * 用户在函数式 definePage 里通过 define() 创建。分支按写的顺序生效，
  * 后写的同名键会盖掉先写的。
  */
-declare class DefineConditional {
+export declare class DefineConditional {
   /** 所有平台共用的基础配置 */
   private readonly base;
   /** 按写的顺序记下的条件分支 */
@@ -40,14 +40,14 @@ declare class DefineConditional {
   resolve(platform: string): Record<string, any>;
 }
 /** 判断宏求值的结果是不是一个条件定义 */
-declare function isConditional(obj: unknown): obj is DefineConditional;
+export declare function isConditional(obj: unknown): obj is DefineConditional;
 /**
  * 把条件定义算成某个平台的普通配置
  *
  * 简单包了一层 {@link DefineConditional.resolve}，调用方不用导入
  * 这个类。
  */
-declare function resolveConditional(cond: DefineConditional, platform: string): Record<string, any>;
+export declare function resolveConditional(cond: DefineConditional, platform: string): Record<string, any>;
 //#endregion
 //#region src/logger.d.ts
 /**
@@ -55,14 +55,14 @@ declare function resolveConditional(cond: DefineConditional, platform: string):
  * 基于 debug 包做分级日志输出
  * 通过环境变量 DEBUG=vite-plugin-uni-pages:* 开启
  */
-declare const debug: {
+export declare const debug: {
   /** HMR 相关日志 */
   hmr: Debug.Debugger;
   /** 配置项相关日志 */
   options: Debug.Debugger;
   /** 主包页面扫描日志 */
   pages: Debug.Debugger;
-  /** 子包页面扫描日志 */
+  /** 分包页面扫描日志 */
   subPages: Debug.Debugger;
   /** 错误日志 */
   error: Debug.Debugger;
@@ -74,260 +74,121 @@ declare const debug: {
   definePage: Debug.Debugger;
 };
 //#endregion
-//#region src/context.d.ts
-/**
- * 页面上下文：负责扫描页面、加载配置、合并页面信息、生成 pages.json
- *
- * 做的事情按固定顺序是：加载用户配置 → 扫描页面文件 → 合并页面
- * 信息 → 写入 pages.json。这个顺序由 {@link updatePagesJSON}（完整
- * 流程）或 {@link scanAndMerge}（只算不写）管理，调用方不用关心
- * 内部步骤。
- */
-declare class PageContext {
-  private _server;
-  /** 从用户配置文件（pages.config.ts）解析出的配置对象 */
-  pagesGlobConfig: PagesConfig | undefined;
-  /** 用户配置文件的来源路径列表 */
-  pagesConfigSourcePaths: string[];
-  /** 主包页面映射，键为页面文件的绝对路径 */
-  pages: Map<string, Page>;
-  /** 子包页面映射，键为子包根目录，值为该子包下的页面映射 */
-  subPages: Map<string, Map<string, Page>>;
-  /** 主包页面配置数组，用于生成 pages.json 的 pages 字段 */
-  pageMetaData: InternalPages;
-  /** 子包页面配置数组，用于生成 pages.json 的 subPackages 字段 */
-  subPageMetaData: SubPackages;
-  /**
-   * 最近一次合并出的 tabBar（配置文件与 definePage 声明的合体）。
-   * 类型声明生成 tab 页列表时用它，definePage 声明的 tabBar 页才能
-   * 一起从 navigateTo 的 url 类型里排除
-   */
-  tabBar: TabBar | undefined;
-  /** 生成的 pages.json 文件路径 */
-  resolvedPagesJSONPath: string;
-  /** 项目根目录 */
-  root: string;
-  /** 解析后的配置项 */
-  options: ResolvedOptions;
-  /** 当前平台标识，如 'mp-weixin'；由调用方传入，不依赖模块加载时冻结的环境 */
-  readonly platform: string;
-  logger?: Logger;
-  /** 是否与 vite-plugin-uni-platform 插件协同工作 */
-  withUniPlatform: boolean;
-  /** pages.json 中页面路径的解析基准路径 */
-  private get basePath();
-  /**
-   * 创建 PageContext 实例
-   * @param userOptions - 用户配置项
-   * @param viteRoot - Vite 项目根目录，默认为当前工作目录
-   * @param platform - 当前平台标识，默认取 uni-env 的平台
-   */
-  constructor(userOptions: UserOptions, viteRoot?: string, platform?: string);
-  /**
-   * 设置 Vite logger
-   * @param logger - Vite logger 实例
-   */
-  setLogger(logger: Logger): void;
-  /**
-   * 加载用户页面配置文件（如 pages.config.ts）
-   * 使用 unconfig 加载配置，支持多种配置文件格式
-   */
-  loadUserPagesConfig(): Promise<void>;
-  /**
-   * 按顺序跑完扫描与合并：先扫描主包和子包的页面，再合并它们的
-   * 信息。步骤顺序只维护在这里，调用方和测试都不用关心。
-   */
-  scanAndMerge(): Promise<void>;
-  /**
-   * 设置 Vite 开发服务器，用于 HMR 与文件监听
-   * @param server - Vite 开发服务器实例
-   */
-  setupViteServer(server: ViteDevServer): void;
-  /**
-   * 设置文件监听器，监听页面文件与配置文件变更
-   * 页面文件或配置文件变化时自动更新 pages.json
-   * @param watcher - chokidar 文件监听器实例
-   */
-  setupWatcher(watcher: FSWatcher): Promise<void>;
-  /**
-   * 页面更新回调，页面文件或配置变化时触发
-   * 负责使虚拟模块失效并通知浏览器整页刷新
-   */
-  onUpdate(): void;
-  /**
-   * 更新 pages.json 文件
-   * 这是负责协调整个页面配置生成流程的核心方法：
-   * 1. 检查文件变更（指定 filepath 时）
-   * 2. 加载用户配置
-   * 3. 扫描页面文件
-   * 4. 合并页面配置
-   * 5. 生成并写入 pages.json
-   * @param filepath - 发生变更的文件路径，用于增量更新判断
-   * @returns pages.json 是否成功更新
-   */
-  updatePagesJSON(filepath?: string): Promise<boolean>;
-  /**
-   * 生成虚拟模块内容
-   * 返回包含 pages 与 subPackages 导出的 JavaScript 代码
-   * @returns 虚拟模块代码字符串
-   */
-  virtualModule(): string;
-  /**
-   * 将主包路由数据解析为 JSON 字符串
-   * @returns 主包页面配置的 JSON 字符串
-   */
-  resolveRoutes(): string;
-  /**
-   * 将子包路由数据解析为 JSON 字符串
-   * @returns 子包页面配置的 JSON 字符串
-   */
-  resolveSubRoutes(): string;
-  /**
-   * 解析 tabBar 配置
-   * 将页面定义的 tabBar 项与配置文件定义的 tabBar 合并
-   * @returns 合并后的 tabBar 配置对象，无 tabBar 时为 undefined
-   */
-  resolveTabBar(): Promise<TabBar | undefined>;
-  /**
-   * 生成 TypeScript 声明文件
-   * 为页面路径生成类型定义，导航时提供类型提示
-   */
-  generateDeclaration(): Promise<void> | undefined;
-  /**
-   * 扫描主包页面目录并收集所有页面文件路径
-   * 根据配置的 dirs 选项扫描对应目录
-   */
-  private scanPages;
-  /**
-   * 按页面文件绝对路径查找被跟踪的页面（主包或任一子包）
-   * @param filepath - 页面文件的绝对路径
-   * @returns 被跟踪的页面，文件未被跟踪时为 undefined
-   */
-  private findPage;
-  /**
-   * 扫描子包页面目录并收集所有子包页面文件路径
-   * 根据配置的 subPackages 选项扫描对应目录
-   */
-  private scanSubPages;
-  /**
-   * 解析 pages 规则并设置页面类型
-   * @param pages 页面路径映射
-   * @param packageType 页面包类型（主包或子包）
-   * @param overrides 自定义页面配置
-   * @returns pages 规则
-   */
-  private parsePages;
-  /**
-   * 设置首页
-   * @param result pages 规则数组
-   * @returns pages 规则
-   */
-  private setHomePage;
-  /**
-   * 合并主包页面配置
-   * 过滤掉属于子包的页面，再解析页面配置并与用户配置合并
-   */
-  private mergePageMetaData;
-  /**
-   * 合并子包页面配置
-   * 为每个子包解析页面配置并处理子包配置继承
-   * 保留用户配置中子包级别的属性（如 plugins）
-   */
-  private mergeSubPageMetaData;
-}
-/**
- * 应用 vite-plugin-uni-platform 的页面文件名后缀规则（如 `index.h5.vue`
- * 对应页面 `index`）：丢弃其他平台的后缀页面，保留当前平台的并把文件名
- * 里的后缀剥掉。
- *
- * 带点的判断只看路径最后一段（文件名），和 vite-plugin-uni-platform
- * 自己的规则一致（它也只在文件名上判断后缀），目录名里的点（如
- * `pages/v1.2/detail`）不算平台后缀。
- *
- * 注意后缀匹配仍是原始的 `path.includes(platform)`，没有做 definePage
- * 那边 h5/web 的别名换算（见 condition.ts 的 platformMatches）：
- * UNI_PLATFORM=web 时，`.h5` 后缀的页面会被过滤掉。这是一直以来的
- * 行为，为了和 vite-plugin-uni-platform 自己的命名规则保持一致而保留。
- *
- * @param pages - 合并后的主包页面配置
- * @param platform - 当前平台标识
- * @returns 过滤并剥掉后缀的新数组，入参不被修改
- */
-declare function filterPlatformSuffixPages(pages: InternalPages, platform: string): InternalPages;
-//#endregion
 //#region src/page.d.ts
+/** Page 读取页面内容所需的环境；不再依赖整个 PageContext */
+export interface PageEnvironment {
+  platform: string;
+  /** 读取时取得当前 logger，覆盖 setLogger 在 Page 创建之后才发生的情况 */
+  getLogger?: () => Logger | undefined;
+}
+/** 一次页面读取的结果；缓存和变更检测都留在 Page 内部 */
+export interface PageSnapshot {
+  /** 用于合并的页面元数据，path 已按 uri 补齐 */
+  meta: InternalPageItem;
+  /** definePage 声明的 tabBar 项，已补齐 pagePath 和 index */
+  tabBar?: TabBarItem & {
+    index: number;
+  };
+  /** 页面在当前平台通过 definePage(null) 退出 */
+  skipped: boolean;
+  /** 与上一次成功读取相比内容或跳过状态是否变化 */
+  changed: boolean;
+}
 /**
- * 表示一个 Vue 页面文件的 Page 类
+ * 表示一个 Vue 页面文件的读取适配器
  *
- * 职责：
- * 1. 读取页面文件内容
- * 2. 解析 definePage 宏定义的页面配置
- * 3. 提供 tabBar 配置信息
- * 4. 跟踪页面文件变更状态
+ * 调用方只需要 `load()`：文件读取、宏求值、跳过状态、tabBar 补全和
+ * 变更检测都在快照里返回。`getPageMeta` / `getTabBar` 保留为兼容入口。
  */
-declare class Page {
-  /** 页面上下文实例 */
-  ctx: PageContext;
+export declare class Page {
+  private readonly environment;
   /** 页面路径信息，包含相对路径与绝对路径 */
   path: PagePath;
   /** 页面 URI，用于 pages.json 的 path 字段 */
   uri: string;
-  /** 页面是否发生变化，用于增量更新判断 */
-  changed: boolean;
-  /**
-   * 页面是否通过 `definePage(null)` 或函数式宏在当前平台返回 null 而
-   * 退出了 pages.json
-   */
-  skipped: boolean;
-  /** 页面文件是否至少被读取过一次 */
+  private snapshot;
+  /** 当前读取缓存是否有效 */
   private loaded;
-  /** 页面配置的原始 JSON 字符串，用于变更检测 */
+  /** 当前缓存是否已尝试读取；失败后等下次失效再重试 */
+  private readAttempted;
+  /** 上一次成功读取的配置，用于变更检测 */
   private raw;
-  /** 解析后的页面配置 */
-  private meta;
+  constructor(environment: PageEnvironment, path: PagePath);
+  /** 页面是否通过 definePage(null) 退出 */
+  get skipped(): boolean;
+  /** 页面内容是否相对上次成功读取发生变化 */
+  get changed(): boolean;
   /**
-   * 创建页面实例
-   * @param ctx - 页面上下文实例
-   * @param path - 页面路径信息
-   */
-  constructor(ctx: PageContext, path: PagePath);
-  /**
-   * 获取页面配置
-   * 解析 definePage 宏定义的配置并返回用于 pages.json 的配置
+   * 读取页面并返回快照
    *
-   * @param forceUpdate - 是否强制更新，忽略缓存
-   * @returns 页面配置对象
+   * @param forceUpdate - 忽略缓存强制重读
    */
-  getPageMeta(forceUpdate?: boolean): Promise<InternalPageItem>;
+  load(forceUpdate?: boolean): Promise<PageSnapshot>;
   /**
-   * 获取页面 tabBar 配置
-   * 从 definePage 宏中提取 tabBar 相关配置
+   * 获取页面配置，保留给既有调用方
    *
-   * @param forceUpdate - 是否强制更新，忽略缓存
-   * @returns tabBar 配置对象，页面未定义 tabBar 时返回 undefined
+   * 返回副本：合并阶段会原地写 `type: 'home'`，不能让首页标记留在
+   * 读取快照里，否则增量更新会继续把旧首页当成首页。
    */
+  getPageMeta(forceUpdate?: boolean): Promise<InternalPageItem>;
+  /** 获取 tabBar 项，保留给既有调用方 */
   getTabBar(forceUpdate?: boolean): Promise<TabBarItem & {
     index: number;
   } | undefined>;
-  /**
-   * 确保页面文件至少被读取过一次，使 `skipped` 与缓存的配置反映
-   * 当前文件内容
-   */
+  /** 加载尚未读取的页面配置，缓存失效前不重复尝试失败的读取 */
   ensureLoaded(): Promise<void>;
   /**
-   * 检查页面是否发生变化
-   * @returns 页面是否发生变化
+   * 使页面读取缓存失效
+   *
+   * @description 下次访问时重新读取，保留上次成功快照作为读取失败时的回退
    */
+  invalidate(): void;
+  /** 检查页面是否发生变化 */
   hasChanged(): boolean;
   /**
    * 读取页面文件并解析配置
-   * 从 Vue SFC 中提取 definePage 宏定义的配置
+   *
+   * @description 成功后替换快照；失败时保留上次成功快照，只记录警告
    */
   read(): Promise<void>;
+  private createSnapshot;
+  /** 读取失败且从未成功时的默认快照，保持页面仍以 uri 参与生成 */
+  private fallbackSnapshot;
   private readPageMetaFromFile;
 }
 //#endregion
 //#region src/types.d.ts
+/** 提前生成页面配置所需的运行环境 */
+interface PrepareOptions {
+  /**
+   * Vite 项目根目录，相对路径以当前工作目录为基准
+   *
+   * @default process.env.VITE_ROOT_DIR || process.cwd()
+   */
+  root?: string;
+  /** 是否采用 UniPlatform 文件名后缀规则，必须与最终插件列表一致 */
+  platformSuffix: boolean;
+}
+/**
+ * 支持提前生成页面配置的 Vite 插件实例
+ *
+ * @description 同一实例可在构建或开发服务器关闭后顺序复用；重叠运行的构建和服务器须各自创建实例
+ */
+interface UniPagesPlugin extends Plugin {
+  /**
+   * 等待页面配置与已启用的声明文件生成，返回当前插件实例
+   *
+   * @description
+   * - 在创建需要读取 pages.json 的下游插件之前等待此方法完成
+   * - 使用调用时的 UNI_PLATFORM；根目录、平台和后缀规则必须与 Vite 初始化一致
+   * - 当前准备期间相同参数的并发或重复调用共享结果，首次 Vite 接管复用该结果
+   * - Vite 会话关闭后再次调用会重新生成；成功准备过的根目录、平台和后缀约束持续有效
+   * - 生成失败后可重试
+   *
+   * @throws 参数冲突、编译平台缺失、实例正在关闭或生成失败时拒绝 Promise
+   */
+  prepare: (options: PrepareOptions) => Promise<UniPagesPlugin>;
+}
 /**
  * 从对象类型中排除索引签名键，仅保留显式键
  */
@@ -442,7 +303,7 @@ interface Options {
   /**
    * 页面配置文件的加载来源
    *
-   * 基于 unconfig，支持合并多个配置来源
+   * @description 基于 unconfig，按来源顺序加载首个有效配置
    *
    * @default 'pages.config'
    * @since 0.2.7
@@ -478,9 +339,11 @@ interface Options {
    */
   dir: string;
   /**
-   * uni-app 分包加载的子包页面目录
+   * uni-app 分包加载的页面目录
    *
-   * 支持字符串形式（目录路径）或对象形式（pages.json 中的自定义 root）
+   * @description
+   * 支持字符串或对象形式的目录 glob，开发期间自动发现新增、删除和重命名的目录
+   * 对象的 root 可用同步回调根据匹配目录计算
    *
    * monorepo 项目中页面可能位于项目根目录之外。使用对象形式指定
    * 出现在 pages.json 中的自定义 root，避免生成的 root 路径含 '..'。
@@ -500,11 +363,15 @@ interface Options {
    */
   outDir: string;
   /**
-   * 排除的文件/目录模式
+   * 页面排除的文件或目录模式
    *
-   * 基于 [tinyglobby 的 ignore 选项](https://superchupu.dev/tinyglobby/documentation#ignore)
+   * @description
+   * - 相对模式基于 Vite root，绝对模式直接匹配对应路径；命中目录时排除整个子树
+   * - 主包、分包的扫描与页面事件使用相同规则
+   * - 自定义数组替换默认值，空数组禁用默认页面排除，空字符串忽略
+   * - 不接受 `!foo` 否定规则，`!(keep).vue` 等 extglob 有效
    *
-   * @default ['node_modules', '.git', '**\/__*__/**']
+   * @default ['**\/node_modules/**', '**\/.git/**', '**\/__*__/**']
    * @since 0.0.4
    */
   exclude: string[];
@@ -566,9 +433,9 @@ interface Options {
 type UserOptions = Partial<Options>;
 /**
  * 解析后的配置项接口
- * 经 resolveOptions 处理的配置，所有路径均解析为绝对路径
+ * 保留原始扫描规则、展开后的目录和生成选项
  */
-interface ResolvedOptions extends Omit<Options, 'dir' | 'homePage' | 'configSource' | 'dts' | 'subPackages'> {
+interface ResolvedOptions extends Omit<Options, 'homePage' | 'configSource' | 'dts' | 'subPackages'> {
   /**
    * 解析为 Vite 配置中的 `root` 值。
    * @default config.root
@@ -585,17 +452,20 @@ interface ResolvedOptions extends Omit<Options, 'dir' | 'homePage' | 'configSour
   homePage: string[];
   configSource: LoadConfigSource<PagesConfig>[];
   /**
-   * 解析后的子包目录列表
+   * 解析后的分包目录列表
    */
   subPackages: string[];
+  /** 原始分包目录规则，用于重新发现目录 */
+  subPackagePatterns: (string | SubPackageConfig)[];
   /**
-   * 子包的自定义 root 映射（目录 -> root）
-   * 用于 monorepo 支持，指定 pages.json 中的自定义 root 路径
+   * 分包目录的 root 映射（目录 -> 最终 root）
+   *
+   * @description 未登记的目录继续使用相对 outDir 的默认 root
    */
   subPackageRootMap: Map<string, string>;
 }
 /**
- * 子包配置接口
+ * 分包配置接口
  * 为 monorepo 支持，允许自定义 pages.json 中的 root 路径
  *
  * monorepo 项目中页面可能位于项目根目录之外（如 ../../packages/login/src/pages）。
@@ -613,10 +483,38 @@ interface ResolvedOptions extends Omit<Options, 'dir' | 'homePage' | 'configSour
  * ```
  */
 interface SubPackageConfig {
-  /** 扫描页面文件的实际物理目录路径 */
+  /** 扫描页面文件的物理目录或 glob，相对 Vite root 解析 */
   dir: string;
-  /** 出现在 pages.json subPackages.root 中的自定义根路径 */
-  root: string;
+  /**
+   * 出现在 pages.json subPackages.root 中的自定义根路径
+   *
+   * @description
+   * 回调同步接收相对 Vite root、使用 `/` 分隔且无末尾斜杠的匹配目录
+   * 返回值须为非空相对路径，不能包含 `..`；每次重新发现目录时会再次调用
+   */
+  root: string | ((dir: string) => string);
+}
+/** 最终分包 root 的决议来源 */
+interface ScanSourceOrigin {
+  /** 提供 root 的词法目录，与对应分包目录来源的 dir 一致 */
+  dir: string;
+  /** 提供 root 的声明在 subPackagePatterns 中的索引，从 0 开始 */
+  ruleIndex: number;
+  /** 提供 root 的声明是否为显式来源 */
+  explicitRoot: boolean;
+}
+/** 扫描来源的词法目录及声明位置 */
+interface ScanSourceCoordinate {
+  /** 扫描目录的词法路径，保留符号链接别名；相对路径以 Vite root 为基准 */
+  dir: string;
+  /** 当前声明是否显式提供 root，与是否继承其他声明的显式 root 无关 */
+  explicitRoot: boolean;
+  /** 主包为 0，分包为 subPackagePatterns 中的从零索引；hook 页面未关联声明时为 -1 */
+  ruleIndex: number;
+  /** 声明内从零开始的目录匹配索引；glob 按路径排序，无匹配记录时为 0 */
+  matchIndex: number;
+  /** 最终分包 root 的决议来源，可能来自另一声明；主包及未关联声明的 hook 页面无此值 */
+  rootSource?: ScanSourceOrigin;
 }
 /**
  * 页面路径信息接口
@@ -637,23 +535,460 @@ interface PagePath {
  * @param config - 页面配置对象
  * @returns 配置对象
  */
-declare function defineUniPages(config: UserPagesConfig): UserPagesConfig;
+export declare function defineUniPages(config: UserPagesConfig): UserPagesConfig;
 //#endregion
 //#region src/constant.d.ts
 /** Vite 模块解析用的虚拟模块标识 */
-declare const MODULE_ID_VIRTUAL = "virtual:uni-pages";
+export declare const MODULE_ID_VIRTUAL = "virtual:uni-pages";
 /** 加 \0 前缀解析后的虚拟模块标识，避免与其他模块冲突 */
-declare const RESOLVED_MODULE_ID_VIRTUAL = "\0virtual:uni-pages";
+export declare const RESOLVED_MODULE_ID_VIRTUAL = "\0virtual:uni-pages";
 /** 输出文件名，即 uni-app 的页面配置文件 */
-declare const OUTPUT_NAME = "pages.json";
+export declare const OUTPUT_NAME = "pages.json";
 /** 支持的页面文件扩展名 */
-declare const FILE_EXTENSIONS: string[];
+export declare const FILE_EXTENSIONS: string[];
+//#endregion
+//#region src/pages-snapshot.d.ts
+/**
+ * 一次生成的完整路由快照。
+ *
+ * 虚拟模块、路由字符串和声明文件都从这里取值。生成过程本身仍可以使用
+ * 可变的工作字段；创建快照时复制容器，后续工作字段的增删不会改变这次的结果，便于测试与虚拟模块读取保持一致。
+ */
+interface PagesSnapshot {
+  pages: InternalPages;
+  subPackages: SubPackages;
+  tabBar?: TabBar;
+  globConfig?: PagesConfig;
+  homePath?: string;
+}
+//#endregion
+//#region src/context.d.ts
+/**
+ * 页面上下文：负责扫描页面、加载配置、合并页面信息、生成 pages.json
+ *
+ * 做的事情按固定顺序是：加载用户配置 → 扫描页面文件 → 合并页面
+ * 信息 → 写入 pages.json。这个顺序由 {@link updatePagesJSON}（完整
+ * 流程）或 {@link scanAndMerge}（只算不写）管理，调用方不用关心
+ * 内部步骤。
+ */
+export declare class PageContext {
+  private _server;
+  private readonly configLoader;
+  private readonly watchers;
+  private readonly watchedConfigPaths;
+  /** 当前配置依赖与恢复范围；事件判定和路径展开都从这里取 */
+  private readonly configWatch;
+  /** 生成物（pages.json、d.ts）的绝对路径，只在首次事件时算一次 */
+  private generatedPathsCache;
+  private pendingUpdate;
+  private disposed;
+  private disposal;
+  /** 本轮扫描的目录、分包来源与规则；扫描和监听共用 */
+  private scanPlan;
+  /** 最近一次生成的完整快照；虚拟模块、路由与声明都读它 */
+  private generatedSnapshot;
+  /** 随扫描更新的 Page 来源，用于复用检查和冲突诊断 */
+  private readonly pageSources;
+  /** 扫描候选独立于归属裁剪后的输出映射，保留非代表来源的内容缓存 */
+  private mainPageCandidates;
+  private subPageCandidates;
+  private readonly pageWatcher;
+  /** 待处理的页面更新：生成期间到达的事件合并到下一轮 */
+  private pendingPageUpdate;
+  /** 当前事件更新循环；dispose 时等待它排空 */
+  private pendingPageFlush;
+  /** 页面监听启动参数；初始化失败时保留，后续生成会重试 */
+  private pageWatcherStart;
+  /** 当前配置本地依赖及加载失败后仍需监听的恢复路径 */
+  pagesConfigDependencyPaths: string[];
+  /** 从用户配置文件（pages.config.ts）解析出的配置对象 */
+  pagesGlobConfig: PagesConfig | undefined;
+  /** 用户配置文件的来源路径列表 */
+  pagesConfigSourcePaths: string[];
+  /** 主包页面映射，键为页面文件的词法绝对路径 */
+  pages: Map<string, Page>;
+  /** 分包页面映射，外层键为词法扫描目录，内层键为页面文件的词法绝对路径 */
+  subPages: Map<string, Map<string, Page>>;
+  /** 主包页面配置数组，用于生成 pages.json 的 pages 字段 */
+  pageMetaData: InternalPages;
+  /** 分包页面配置数组，用于生成 pages.json 的 subPackages 字段 */
+  subPageMetaData: SubPackages;
+  /**
+   * 最近一次合并出的 tabBar（配置文件与 definePage 声明的合体）。
+   * 类型声明生成 tab 页列表时用它，definePage 声明的 tabBar 页才能
+   * 一起从 navigateTo 的 url 类型里排除
+   */
+  tabBar: TabBar | undefined;
+  /** 生成的 pages.json 文件路径 */
+  resolvedPagesJSONPath: string;
+  /** 项目根目录 */
+  root: string;
+  /** 解析后的配置项 */
+  options: ResolvedOptions;
+  /** 当前平台标识，如 'mp-weixin'；由调用方传入，不依赖模块加载时冻结的环境 */
+  readonly platform: string;
+  logger?: Logger;
+  /** 是否与 vite-plugin-uni-platform 插件协同工作 */
+  withUniPlatform: boolean;
+  /** pages.json 中页面路径的解析基准路径 */
+  private get basePath();
+  /**
+   * 创建 PageContext 实例
+   * @param userOptions - 用户配置项
+   * @param viteRoot - Vite 项目根目录，默认为当前工作目录
+   * @param platform - 当前平台标识，默认取 uni-env 的平台
+   */
+  constructor(userOptions: UserOptions, viteRoot?: string, platform?: string);
+  /**
+   * 设置 Vite logger
+   * @param logger - Vite logger 实例
+   */
+  setLogger(logger: Logger): void;
+  /**
+   * 加载用户页面配置文件（如 pages.config.ts）
+   * 使用 unconfig 加载配置，支持多种配置文件格式
+   */
+  loadUserPagesConfig(): Promise<void>;
+  /**
+   * 按顺序跑完扫描与合并：先扫描主包和分包的页面，再合并它们的
+   * 信息。步骤顺序只维护在这里，调用方和测试都不用关心。
+   */
+  scanAndMerge(): Promise<void>;
+  /** 刷新本轮扫描计划，并同步兼容投影供既有调用方读取 */
+  private refreshScanPlan;
+  /** 扫描与监听阶段读取本轮计划；计划在 refreshScanPlan 之后必定存在 */
+  private requireScanPlan;
+  /**
+   * 设置 Vite 开发服务器，用于 HMR 与文件监听
+   * @param server - Vite 开发服务器实例
+   */
+  setupViteServer(server: ViteDevServer): void;
+  /**
+   * 生成物（pages.json 与 d.ts）的绝对路径
+   *
+   * 只依赖构造后不再变化的 `options` 与 `resolvedPagesJSONPath`，
+   * 算一次缓存即可，不必每个事件重新解析
+   */
+  private generatedFilePaths;
+  /** 按当前词法规则识别页面事件，真实路径只用于关联已收录来源 */
+  private pageFileForEvent;
+  private pageDirectoryForEvent;
+  /**
+   * 注册配置文件与页面目录结构监听，并启动页面内容监听
+   *
+   * @param watcher - 配置文件及目录结构事件使用的 chokidar 监听器
+   */
+  setupWatcher(watcher: FSWatcher): Promise<void>;
+  /**
+   * 启动页面监听
+   *
+   * @description 初始化失败只记录并保留启动参数，后续生成会重新尝试；监听属于辅助
+   * 能力，不能阻断页面生成，也不能留下未处理的拒绝
+   */
+  private startPageWatcher;
+  /**
+   * 释放本上下文的监听与待处理更新
+   *
+   * @description 关闭后不再接受监听注册或更新；已开始的生成会完成，重复调用等待同一次释放
+   * 共享 watcher 的关闭仍由 Vite 负责
+   */
+  disposeWatchers(): Promise<void>;
+  /** 补充未覆盖的监听路径，注册成功后记账，失败时保留重试机会 */
+  private addWatchPaths;
+  /**
+   * 让监听路径与当前配置依赖保持一致
+   *
+   * 只新增路径，从不 unwatch：chokidar 对文件调用 unwatch 会连带
+   * 拆掉父目录监听，新建文件就再也发现不了。因此监听集合是并集，
+   * 会随着会话累积；每次刷新都按当前依赖重建配置监听计划，
+   * 真正决定是否触发的始终是计划里的依赖集合（恢复目录除外，那是
+   * 故意留的兜底）。
+   */
+  private refreshConfigWatchers;
+  /** 配置变化的完整更新：失败只记录，不让 Promise 拒绝 */
+  private updatePagesAndNotify;
+  /** 记录 watcher 更新失败，避免未处理的拒绝终止进程 */
+  private logUpdateFailure;
+  /**
+   * 登记页面事件触发的更新：生成期间到达的事件合并到下一轮
+   *
+   * @description 连续删除、重建会一次性派发大量事件，逐个生成会反复
+   * 重读全部页面；内容变更合并待刷新文件，结构变更执行完整刷新
+   * @param filepath - 只读取该页面；省略时执行完整扫描
+   */
+  private queuePageUpdate;
+  /**
+   * 排空页面事件队列；失败只记录，不让 Promise 拒绝
+   *
+   * 页面事件的回调走这里而不是直接调 {@link updatePagesJSON}：一旦
+   * 它拒绝（拿不到文件锁、声明文件写不进去），就成了未处理的拒绝，
+   * Node 默认直接终止进程。开发时正在编辑文件，一次偶发的锁冲突
+   * 不该把 dev server 打死。用户改一次文件就会再触发一次事件，
+   * 所以这里报错即可。
+   */
+  private flushPageUpdates;
+  /**
+   * 页面更新回调，页面文件或配置变化时触发
+   * 负责使虚拟模块失效并通知浏览器整页刷新
+   */
+  onUpdate(): void;
+  /**
+   * 刷新页面配置并更新 pages.json
+   *
+   * @description 同一实例的调用按顺序执行；指定页面时尝试增量读取，页面尚未收录或物理身份变化时执行完整刷新
+   *
+   * @param filepath 变更页面的绝对路径或相对 root 的路径；省略时执行完整刷新
+   * @returns pages.json 写入新内容时为 `true`，内容未变、上下文已关闭或跳过生成时为 `false`
+   * @throws 生成、写入或声明输出失败时拒绝；声明输出失败前 pages.json 可能已更新
+   */
+  updatePagesJSON(filepath?: string): Promise<boolean>;
+  private enqueuePagesUpdate;
+  private generatePagesJSON;
+  /** 最近一次生成的路由快照；未写入文件时由当前工作字段合成 */
+  get snapshot(): PagesSnapshot;
+  /**
+   * 生成虚拟模块内容
+   * 返回包含 pages 与 subPackages 导出的 JavaScript 代码
+   * @returns 虚拟模块代码字符串
+   */
+  virtualModule(): string;
+  /**
+   * 将主包路由数据解析为 JSON 字符串
+   * @returns 主包页面配置的 JSON 字符串
+   */
+  resolveRoutes(): string;
+  /**
+   * 将分包路由数据解析为 JSON 字符串
+   * @returns 分包页面配置的 JSON 字符串
+   */
+  resolveSubRoutes(): string;
+  /**
+   * 解析 tabBar 配置
+   * 将页面定义的 tabBar 项与配置文件定义的 tabBar 合并
+   * @returns 合并后的 tabBar 配置对象，无 tabBar 时为 undefined
+   */
+  resolveTabBar(): Promise<TabBar | undefined>;
+  /**
+   * 生成 TypeScript 声明文件
+   * 为页面路径生成类型定义，导航时提供类型提示
+   */
+  generateDeclaration(): Promise<void> | undefined;
+  /**
+   * 按词法目录扫描主包页面
+   *
+   * @description 各目录分别执行文件排除，物理别名保留到页面有效性与归属决议阶段
+   */
+  private scanPages;
+  /**
+   * 登记本轮来源并复用身份与输出基准均未变化的 Page
+   *
+   * @description 整轮更新使读取缓存失效，增量更新复用目标页的预读结果与其他页面缓存
+   * @returns 路径仍存在时返回页面实例，扫描期间已消失时为 undefined
+   */
+  private trackPage;
+  private pageEnvironment;
+  /** 页面来源的原始声明规则，用于冲突诊断；hook 页面可能没有 */
+  private configuredRule;
+  /**
+   * 按词法路径或物理身份查找全部缓存候选
+   * @param filepath - 页面文件的绝对路径
+   * @returns 主包和分包中属于同一文件的页面实例，每个实例只返回一次
+   */
+  private findPages;
+  /**
+   * 按词法来源扫描分包页面
+   *
+   * @description 同一物理目录的不同别名仍分别执行文件排除，避免某个别名被排除后漏页
+   */
+  private scanSubPages;
+  /**
+   * 为每个物理扫描目录选取声明来源
+   *
+   * @description 同一路径的不同写法只扫描一次，定位信息按显式优先选择；
+   * 符号链接别名是不同的 absolute，仍分别保留各自的词法路径
+   */
+  private subPackageSourcesByDir;
+  /** 获取目录的最终分包 root，未登记时相对 outDir 计算默认值 */
+  private subPackageRoot;
+  /**
+   * 决议有效页面的归属并校验生成路由
+   *
+   * @description 先读取宏并应用既有平台规则，再选择代表；冲突校验通过后才裁剪页面映射，
+   * 配置覆盖与输出去重在此之后执行
+   */
+  private resolveScanSources;
+  /**
+   * 解析 pages 规则并设置页面类型
+   * @param pages 页面路径映射
+   * @param packageType 页面包类型（主包或分包）
+   * @param overrides 自定义页面配置
+   * @returns pages 规则
+   */
+  private parsePages;
+  /**
+   * 设置首页
+   * @param result pages 规则数组
+   * @returns pages 规则
+   */
+  private setHomePage;
+  /**
+   * 决议扫描来源后合并主包页面配置
+   *
+   * @description 有效分包优先认领物理页面，生成来源冲突在用户配置覆盖前检查
+   */
+  private mergePageMetaData;
+  /**
+   * 合并分包页面配置
+   *
+   * @description 静态、glob 和回调来源先按最终 root 汇集，再对整组应用一次配置覆盖，
+   * 保留手工页面和分包 plugins 配置
+   */
+  private mergeSubPageMetaData;
+}
+/**
+ * 应用 vite-plugin-uni-platform 的页面文件名后缀规则（如 `index.h5.vue`
+ * 对应页面 `index`）：丢弃其他平台的后缀页面，保留当前平台的并把文件名
+ * 里的后缀剥掉。
+ *
+ * 带点的判断只看路径最后一段（文件名），和 vite-plugin-uni-platform
+ * 自己的规则一致（它也只在文件名上判断后缀），目录名里的点（如
+ * `pages/v1.2/detail`）不算平台后缀。
+ *
+ * 注意后缀匹配仍是原始的 `path.includes(platform)`，没有做 definePage
+ * 那边 h5/web 的别名换算（见 condition.ts 的 platformMatches）：
+ * UNI_PLATFORM=web 时，`.h5` 后缀的页面会被过滤掉。这是一直以来的
+ * 行为，为了和 vite-plugin-uni-platform 自己的命名规则保持一致而保留。
+ *
+ * @param pages - 合并后的主包页面配置
+ * @param platform - 当前平台标识
+ * @returns 过滤并剥掉后缀的新数组，入参不被修改
+ */
+export declare function filterPlatformSuffixPages(pages: InternalPages, platform: string): InternalPages;
+//#endregion
+//#region src/directories.d.ts
+/**
+ * 规范化页面目录选择器中的路径分隔符
+ *
+ * @description 在 Windows 上将反斜杠路径分隔符转换为 `/`，保留 `\[`、`\(` 等 glob 转义
+ *
+ * @param pattern 页面目录路径或 glob 表达式
+ * @returns Windows 返回规范化后的选择器，其他平台返回原字符串
+ *
+ * @example
+ * ```ts
+ * normalizePagePattern('src\\pages') // Windows: 'src/pages'
+ * ```
+ */
+export declare function normalizePagePattern(pattern: string): string;
+/**
+ * 将目录选择器中的 glob 转义还原为字面字符
+ *
+ * @description 用于已经确定的固定路径部分，还原后的字符串可传给 `path.resolve` 等路径 API
+ *
+ * @param pattern 以 `/` 分隔、可包含 glob 转义的固定目录路径
+ * @returns 去除 glob 特殊字符前转义反斜杠的路径字符串
+ *
+ * @example
+ * ```ts
+ * unescapePagePattern('src/\\[demo\\]') // 'src/[demo]'
+ * ```
+ */
+export declare function unescapePagePattern(pattern: string): string;
+/**
+ * 查找当前可扫描的页面目录
+ *
+ * @description 应用目录排除后，返回相对 root、按路径排序的匹配结果；空规则或否定规则返回空数组
+ *
+ * @param dir 页面目录 glob，可使用绝对路径
+ * @param root 相对目录和相对 exclude 的解析基准
+ * @param exclude 目录及页面排除规则
+ */
+export declare function resolvePageDirs(dir: string, root: string, exclude: string[]): string[];
+/** 单次分包目录发现保留的来源记录 */
+export interface SubPackageDirectorySource extends ScanSourceCoordinate {
+  /**
+   * 扫描目录的词法路径，与 subPackages 的目录投影一致
+   *
+   * @description glob 或回调来源相对 Vite root，静态来源保留声明的绝对或相对写法
+   */
+  dir: string;
+  /** 相对 Vite root 解析的绝对路径，保留符号链接别名 */
+  absolute: string;
+  /** 目录的 realpath 身份；缺失、非目录或解析期间消失时为 undefined */
+  identity?: string;
+  /** 同一物理目录完成显式／默认来源决议后的最终分包 root */
+  root: string;
+  /** 最终 root 的选择来源，可能与当前声明不同 */
+  rootSource: ScanSourceOrigin;
+}
+type SubPackageDirectoryProjection = Pick<ResolvedOptions, 'subPackages' | 'subPackageRootMap'>;
+/** 展开分包声明，返回逐条来源记录和扫描目录投影 */
+export declare function discoverSubPackageDirectories(patterns: (string | SubPackageConfig)[], root: string, outDir: string, exclude: string[]): {
+  sources: SubPackageDirectorySource[];
+  projection: SubPackageDirectoryProjection;
+};
+/**
+ * 展开分包目录并确定各目录的最终 root
+ *
+ * @description 每次调用重新发现目录并求值回调；按声明顺序排列，glob 内按路径排序
+ * 同一物理目录的显式 root 优先于默认值，词法别名分别保留，重复目录投影只登记一次
+ *
+ * @param patterns 原始分包目录声明
+ * @param root 相对目录和相对 exclude 的解析基准
+ * @param outDir 默认分包 root 的换算基准，相对 root 解析
+ * @param exclude 目录及页面排除规则
+ * @returns 目录列表及最终 root 映射
+ * @throws 目录规则无效、root 回调失败、显式 root 冲突或非缺失类目录访问错误
+ */
+export declare function resolveSubPackageDirs(patterns: (string | SubPackageConfig)[], root: string, outDir: string, exclude: string[]): SubPackageDirectoryProjection;
+/**
+ * 读取当前分包目录来源
+ *
+ * @description 每次调用重新发现目录并求值回调；需要与扫描共用同一份结果时，
+ * 使用 ScanPlan 而不是在扫描中途再次调用
+ *
+ * @returns 按声明及匹配顺序排列的来源，调用方应只读使用记录
+ * @throws 目录规则、root 决议或目录访问错误
+ */
+export declare function getSubPackageDirectorySources(options: ResolvedOptions): readonly SubPackageDirectorySource[];
+/**
+ * 刷新扫描目录与分包 root 投影
+ *
+ * @description 仅用于兼容仍读取 `ResolvedOptions` 的调用方；内部扫描走
+ * `createScanPlan()`，每次重新发现目录来源与物理身份，不保留上一轮快照
+ *
+ * @throws 目录规则、root 决议或目录访问失败时抛出，应中止本轮扫描
+ */
+export declare function refreshPageDirectories(options: ResolvedOptions): void;
+/**
+ * 判断目录事件是否可能改变扫描目录集合
+ *
+ * @description directory 相对 options.root 解析，允许目录已删除；关闭 mergePages 时返回 false
+ */
+export declare function isPageDirectoryEvent(directory: string, options: ResolvedOptions): boolean;
+/**
+ * 判断文件路径是否位于当前页面规则内
+ *
+ * @description file 相对 options.root 解析，按原始规则与 exclude 判断，不要求文件存在或目录已展开
+ * 关闭 mergePages 时返回 false，文件扩展名由调用方校验
+ */
+export declare function isPageFileInDirectories(file: string, options: ResolvedOptions): boolean;
 //#endregion
 //#region src/files.d.ts
 /**
- * 解析给定上下文下可作为有效页面的文件列表。
+ * 判断是否为路径缺失或中间路径不是目录的文件系统错误
+ *
+ * @returns 错误码为 ENOENT 或 ENOTDIR 时返回 true，其他错误及空输入返回 false
+ */
+export declare function isMissingFsError(error: unknown): boolean;
+/**
+ * 获取扫描目录中未被排除的页面文件
+ *
+ * @param directory - 绝对扫描目录，或相对项目根的目录
+ * @param options - 已解析的页面选项，排除规则以其中的项目根为基准
+ * @returns 相对扫描目录、使用 `/` 分隔的文件路径
  */
-declare function getPageFiles(path: string, options: ResolvedOptions): string[];
+export declare function getPageFiles(directory: string, options: ResolvedOptions): string[];
 /**
  * 检查文件是否为目标页面文件
  * 判断文件扩展名是否在支持的页面文件类型列表中
@@ -661,7 +996,7 @@ declare function getPageFiles(path: string, options: ResolvedOptions): string[];
  * @param path - 文件路径
  * @returns 是否为目标文件
  */
-declare function isTargetFile(path: string): boolean;
+export declare function isTargetFile(path: string): boolean;
 /**
  * 根据项目根目录与输出目录解析 pages.json 文件路径
  *
@@ -669,7 +1004,7 @@ declare function isTargetFile(path: string): boolean;
  * @param outDir - 相对 root 的 pages.json 输出目录
  * @returns pages.json 绝对路径
  */
-declare function resolvePagesJsonPath(root: string, outDir: string): string;
+export declare function resolvePagesJsonPath(root: string, outDir: string): string;
 /**
  * 确保这个路径上有一个能用的 pages.json 文件。
  *
@@ -683,7 +1018,7 @@ declare function resolvePagesJsonPath(root: string, outDir: string): string;
  * @throws 路径存在但不是普通文件、缺少读写权限，或占位文件创建失败时
  *          抛出
  */
-declare function checkPagesJsonFileSync(path: fs.PathLike): void;
+export declare function checkPagesJsonFileSync(path: fs.PathLike): void;
 /**
  * 拿到文件的独占锁后运行任务，运行完自动放锁。
  *
@@ -699,8 +1034,9 @@ declare function checkPagesJsonFileSync(path: fs.PathLike): void;
  * @param task - 在锁内运行的异步任务；返回值原样返回给调用方
  * @param retry - 锁被别人拿着时的重试次数，默认 3
  * @returns `task` 的结果；一直拿不到锁时为 `undefined`
+ * @throws 权限不足、路径缺失等非竞争错误原样抛出，不重试
  */
-declare function withFileLock<T>(path: string, task: () => Promise<T>, retry?: number): Promise<T | undefined>;
+export declare function withFileLock<T>(path: string, task: () => Promise<T>, retry?: number): Promise<T | undefined>;
 //#endregion
 //#region src/macro.d.ts
 /**
@@ -722,7 +1058,7 @@ declare function withFileLock<T>(path: string, task: () => Promise<T>, retry?: n
  * @param options - 解析选项
  * @returns SFC descriptor 对象
  */
-declare function parseSFC(code: string, options?: SFCParseOptions): SFCDescriptor;
+export declare function parseSFC(code: string, options?: SFCParseOptions): SFCDescriptor;
 /**
  * 求值 Vue SFC 里的 definePage 宏，返回页面信息
  *
@@ -735,7 +1071,7 @@ declare function parseSFC(code: string, options?: SFCParseOptions): SFCDescripto
  * @returns 页面信息对象；宏明确退出（definePage(null) 或函数返回
  * null）时为 `null`；没找到 definePage 时为 undefined
  */
-declare function evaluateDefinePage(code: string, filename: string, platform?: string): Promise<UserPageItem | null | undefined>;
+export declare function evaluateDefinePage(code: string, filename: string, platform?: string): Promise<UserPageItem | null | undefined>;
 /**
  * 在 Vue SFC 中定位 definePage 宏调用但不求值
  *
@@ -748,7 +1084,7 @@ declare function evaluateDefinePage(code: string, filename: string, platform?: s
  * @param options.onParseError - 以失败的 script 块名与错误对象调用
  * @returns definePage 调用表达式，未找到时为 undefined
  */
-declare function findDefinePageMacro(code: string, filename: string, options?: {
+export declare function findDefinePageMacro(code: string, filename: string, options?: {
   onParseError?: (block: string, error: unknown) => void;
 }): CallExpression | undefined;
 //#endregion
@@ -761,15 +1097,7 @@ declare function findDefinePageMacro(code: string, filename: string, options?: {
  * @param viteRoot - Vite 项目根目录
  * @returns 解析后的配置项
  */
-declare function resolveOptions(userOptions: UserOptions, viteRoot?: string): ResolvedOptions;
-/**
- * 根据给定的 glob 模式解析页面目录
- * @param dir - 页面目录 glob 模式
- * @param root - 项目根目录
- * @param exclude - 需要排除的 glob 模式
- * @returns 匹配到的目录路径
- */
-declare function resolvePageDirs(dir: string, root: string, exclude: string[]): string[];
+export declare function resolveOptions(userOptions: UserOptions, viteRoot?: string): ResolvedOptions;
 //#endregion
 //#region src/pages-json.d.ts
 /**
@@ -779,6 +1107,8 @@ declare function resolvePageDirs(dir: string, root: string, exclude: string[]):
  * - 多个平台共用一个文件时，用 #ifdef 注释区分各自的条目（合并规则
  *   的核心在 platform-variants.ts，数组侧的适配在这里，对象侧
  *   tabBar 属性的适配在 tab-bar.ts）
+ * - tabBar list 的条目顺序：配置覆盖全部既有条目时按配置顺序输出，
+ *   否则新增条目落到声明位置、既有条目保持磁盘序（规则 6）
  * - 合并时保持首页排最前
  * - 写入"由插件生成"的标记，靠它识别哪些条目是插件写的
  * - 序列化格式（缩进、换行）
@@ -789,13 +1119,13 @@ declare function resolvePageDirs(dir: string, root: string, exclude: string[]):
  *
  * 当前平台用不到的区块怎么处理，分两种情况：
  * - tabBar 的外观属性：uni-app 条件编译能把整段剥掉，保留并包上 #ifdef
- * - 没有任何页面的子包：构建产物里会留下指向不存在目录的空壳，直接删掉
+ * - 没有任何页面的分包：构建产物里会留下指向不存在目录的空壳，直接删掉
  */
 /** 由扫描/合并流水线组装出的路由数据 */
-interface PagesJsonData {
+export interface PagesJsonData {
   /** 主包页面配置 */
   pages: InternalPages;
-  /** 子包页面配置 */
+  /** 分包页面配置 */
   subPackages: SubPackages;
   /** 解析后的 tabBar 配置 */
   tabBar?: TabBar;
@@ -807,7 +1137,7 @@ interface PagesJsonData {
   homePath?: string;
 }
 /** 生成 pages.json 时怎么排版 */
-interface PagesJsonFormatOptions {
+export interface PagesJsonFormatOptions {
   /**
    * 压缩成一行输出，优先级高于 `indent`。单行 JSON 放不下注释，
    * 生成标记、用户注释、所有 `#ifdef` 块都会丢失：只属于其他平台的
@@ -823,7 +1153,7 @@ interface PagesJsonFormatOptions {
   /** 是否在末尾追加换行符 */
   insertFinalNewline?: boolean;
 }
-interface WritePagesJsonOptions {
+export interface WritePagesJsonOptions {
   /** 当前平台标识，如 'mp-weixin' 或 'h5' */
   platform: string;
   /** 来自 pages.config.ts 的用户配置；pages/subPackages/tabBar 之外的字段原样写进输出 */
@@ -832,7 +1162,7 @@ interface WritePagesJsonOptions {
   format?: PagesJsonFormatOptions;
 }
 /** 纯合并步骤的选项：{@link WritePagesJsonOptions} 中与文件无关的部分 */
-type MergePagesJsonOptions = Pick<WritePagesJsonOptions, 'platform' | 'globConfig' | 'format'>;
+export type MergePagesJsonOptions = Pick<WritePagesJsonOptions, 'platform' | 'globConfig' | 'format'>;
 /**
  * 把路由数据合并进 pages.json 并写回
  *
@@ -846,13 +1176,22 @@ type MergePagesJsonOptions = Pick<WritePagesJsonOptions, 'platform' | 'globConfi
  * @param options - 平台、用户配置与序列化格式
  * @returns 写入结果；获取不到文件锁时为 undefined
  */
-declare function writePagesJson(jsonPath: string, data: PagesJsonData, options: WritePagesJsonOptions): Promise<{
+export declare function writePagesJson(jsonPath: string, data: PagesJsonData, options: WritePagesJsonOptions): Promise<{
   updated: boolean;
   content: string;
 } | undefined>;
+/**
+ * Retries an async operation up to 3 times on EPERM, waiting 50ms between
+ * attempts. Other errors propagate immediately.
+ *
+ * Windows file rename (used by write-file-atomic) can fail with EPERM when
+ * another process holds the destination open with a sharing mode that excludes
+ * rename (e.g. chokidar's watcher). The lock clears in under a frame.
+ */
+export declare function retryOnEperm(operation: () => Promise<unknown>): Promise<void>;
 /**
  * 不碰文件系统，只做计算：把路由数据合并进现有 pages.json 文本
- * （多平台 `#ifdef` 块、首页重排、生成标记、过期子包清理）并序列化
+ * （多平台 `#ifdef` 块、首页重排、生成标记、过期分包清理）并序列化
  * 成字符串。文件锁、变更检测和原子写入都在 {@link writePagesJson}
  * 里；测试直接用字符串检查这个函数。
  *
@@ -861,7 +1200,7 @@ declare function writePagesJson(jsonPath: string, data: PagesJsonData, options:
  * @param options - 平台、用户配置与序列化格式
  * @returns 序列化后的 pages.json 内容
  */
-declare function mergePagesJson(existingContent: string, data: PagesJsonData, options: MergePagesJsonOptions): string;
+export declare function mergePagesJson(existingContent: string, data: PagesJsonData, options: MergePagesJsonOptions): string;
 //#endregion
 //#region src/pipeline.d.ts
 /**
@@ -873,7 +1212,7 @@ declare function mergePagesJson(existingContent: string, data: PagesJsonData, op
  * 也是这里的调用方；测试通过这个入口跑完整流程，不去碰内部步骤。
  */
 /** 可以从外面传进来的流水线输入 */
-interface PipelineOverrides {
+export interface PipelineOverrides {
   /** 项目根目录，默认为当前工作目录 */
   root?: string;
   /** 当前平台标识，如 'mp-weixin'；默认取 uni-env 的平台 */
@@ -889,7 +1228,7 @@ interface PipelineOverrides {
  * @param overrides - 从外面传入的 root 与 platform
  * @returns 完成扫描与合并的 PageContext
  */
-declare function createPages(userOptions?: UserOptions, overrides?: PipelineOverrides): Promise<PageContext>;
+export declare function createPages(userOptions?: UserOptions, overrides?: PipelineOverrides): Promise<PageContext>;
 /**
  * 运行完整流水线：加载用户配置、扫描、合并并写入 pages.json
  * （以及 TypeScript 声明文件）
@@ -898,7 +1237,7 @@ declare function createPages(userOptions?: UserOptions, overrides?: PipelineOver
  * @param overrides - 从外面传入的 root 与 platform
  * @returns pages.json 是否有更新，以及产出它的上下文
  */
-declare function generateAll(userOptions?: UserOptions, overrides?: PipelineOverrides): Promise<{
+export declare function generateAll(userOptions?: UserOptions, overrides?: PipelineOverrides): Promise<{
   updated: boolean;
   ctx: PageContext;
 }>;
@@ -916,6 +1255,6 @@ declare function generateAll(userOptions?: UserOptions, overrides?: PipelineOver
  * @param userOptions - 用户配置项
  * @returns Vite 插件实例
  */
-declare function VitePluginUniPages(userOptions?: UserOptions): Plugin;
+export declare function VitePluginUniPages(userOptions?: UserOptions): UniPagesPlugin;
 //#endregion
-export { type ConfigSource, type DebugType, DefineConditional, type DefinePage, type DefinePageContext, type ExcludeIndexSignature, FILE_EXTENSIONS, type InternalPageItem, type InternalPages, MODULE_ID_VIRTUAL, type MaybeCallable, type MaybePromise, type MaybePromiseCallable, MergePagesJsonOptions, OUTPUT_NAME, type Options, Page, PageContext, type PagePath, PagesJsonData, PagesJsonFormatOptions, PipelineOverrides, RESOLVED_MODULE_ID_VIRTUAL, type ResolvedOptions, type SubPackageConfig, type UserOptions, type UserPageItem, type UserTabBarItem, VitePluginUniPages, VitePluginUniPages as default, WritePagesJsonOptions, checkPagesJsonFileSync, createPages, debug, type debugType, type definePage, defineUniPages, evaluateDefinePage, filterPlatformSuffixPages, findDefinePageMacro, generateAll, getPageFiles, isConditional, isTargetFile, mergePagesJson, parseSFC, resolveConditional, resolveOptions, resolvePageDirs, resolvePagesJsonPath, withFileLock, writePagesJson };
+export { type ConfigSource, type DebugType, type DefinePage, type DefinePageContext, type ExcludeIndexSignature, type InternalPageItem, type InternalPages, type MaybeCallable, type MaybePromise, type MaybePromiseCallable, type Options, type PagePath, type PrepareOptions, type ResolvedOptions, type ScanSourceCoordinate, type ScanSourceOrigin, type SubPackageConfig, type UniPagesPlugin, type UserOptions, type UserPageItem, type UserTabBarItem, VitePluginUniPages as default, type debugType, type definePage };