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

package/dist/index.d.mts

@@ -1,570 +1,921 @@
-import { createRequire } from "node:module";
 import { FSWatcher } from "chokidar";
 import { Logger, Plugin, ViteDevServer } from "vite";
-import fs from "node:fs";
 import Debug from "debug";
 import { LoadConfigSource } from "unconfig";
-import babelGenerator from "@babel/generator";
-import * as t from "@babel/types";
+import fs from "node:fs";
+import { CallExpression } from "@babel/types";
 import { SFCDescriptor, SFCParseOptions } from "@vue/compiler-sfc";
-import { DefinePage, ExcludeIndexSignature, MaybeCallable, MaybePromise, MaybePromiseCallable, PageMetaDatum, SubPageMetaDatum, UserPageMeta, UserPagesConfig, UserTabBarItem, definePage } from "@uni-helper/uni-pages-types";
-export * from "@uni-helper/uni-pages-types";
-
-//#region \0rolldown/runtime.js
-declare namespace index_d_exports$1 {
-  export { defineUniPages };
-}
-import * as import__uni_helper_uni_pages_types from "@uni-helper/uni-pages-types";
+import { PageItem, PagesConfig, SubPackages, TabBar, TabBarItem, UserPagesConfig } from "@uni-helper/uni-pages-types";
+export type * from "@uni-helper/uni-pages-types";
+//#region src/condition.d.ts
 /**
- * Define uni-pages configuration
- * Used in pages.config.ts configuration file to provide type hints and validation
+ * 按平台写不同页面配置的小工具
  *
- * @param config - Page configuration object
- * @returns Configuration object
+ * 用法来自 @uni-ku/pages-json：define().ifdef().ifndef()。用户在
+ * 函数式 definePage 里调用 define() 拿到可链式写的定义对象，先写
+ * 所有平台共用的配置，再按平台加不同的部分。插件在宏求值完就立刻
+ * 按当前平台算出最终结果，后面的步骤只会看到普通对象。
  */
-declare function defineUniPages(config: UserPagesConfig): UserPagesConfig;
-//#endregion
-//#region src/page.d.ts
 /**
- * Page class representing a Vue page file
+ * 可以链式调用的"按平台写配置"对象
  *
- * Responsibilities:
- * 1. Read page file content
- * 2. Parse page metadata defined by definePage macro
- * 3. Provide tabBar configuration information
- * 4. Track page file change status
+ * 用户在函数式 definePage 里通过 define() 创建。分支按写的顺序生效，
+ * 后写的同名键会盖掉先写的。
  */
-declare class Page {
-  /** Page context instance */
-  ctx: PageContext;
-  /** Page path information containing relative and absolute paths */
-  path: PagePath;
-  /** Page URI used for pages.json path field */
-  uri: string;
-  /** Whether the page has changed, used for incremental update judgment */
-  changed: boolean;
-  /** Raw JSON string of page metadata for change detection */
-  private raw;
-  /** Parsed page metadata */
-  private meta;
-  /**
-   * Create a page instance
-   * @param ctx - Page context instance
-   * @param path - Page path information
-   */
-  constructor(ctx: PageContext, path: PagePath);
-  /**
-   * Get page metadata
-   * Parse configuration defined by definePage macro and return metadata for pages.json
-   *
-   * @param forceUpdate - Whether to force update, ignoring cache
-   * @returns Page metadata object
-   */
-  getPageMeta(forceUpdate?: boolean): Promise<PageMetaDatum>;
-  /**
-   * Get page tabBar configuration
-   * Extract tabBar related configuration from definePage macro
-   *
-   * @param forceUpdate - Whether to force update, ignoring cache
-   * @returns tabBar configuration object, or undefined if page doesn't define tabBar
-   */
-  getTabBar(forceUpdate?: boolean): Promise<index_d_exports$1.TabBarItem & {
-    index: number;
-  } | undefined>;
-  /**
-   * Check if the page has changed
-   * @returns Whether the page has changed
-   */
-  hasChanged(): boolean;
-  /**
-   * Read page file and parse metadata
-   * Extract configuration defined by definePage macro from Vue SFC
-   */
-  read(): Promise<void>;
-  private readPageMetaFromFile;
+declare class DefineConditional {
+  /** 所有平台共用的基础配置 */
+  private readonly base;
+  /** 按写的顺序记下的条件分支 */
+  private readonly branches;
+  constructor(base: Record<string, any>);
+  /** 仅在给定平台应用 `partial` */
+  ifdef(platform: string | string[], partial: Record<string, any>): this;
+  /** 在除给定平台之外的所有平台应用 `partial` */
+  ifndef(platform: string | string[], partial: Record<string, any>): this;
+  /**
+   * 算出某个平台最终用的普通配置：从基础配置开始，按写的顺序把每个
+   * 匹配的分支合并进去。平台列表里 `h5` 和 `web` 互相通用（见
+   * platformMatches）。
+   */
+  resolve(platform: string): Record<string, any>;
 }
+/** 判断宏求值的结果是不是一个条件定义 */
+declare function isConditional(obj: unknown): obj is DefineConditional;
 /**
- * Parse Vue Single File Component (SFC)
- * Compatible with different versions of @vue/compiler-sfc
- *
- * @param code - Vue SFC source code
- * @param options - Parse options
- * @returns SFC descriptor object
- */
-declare function parseSFC(code: string, options?: SFCParseOptions): SFCDescriptor;
-/**
- * Try to extract page metadata defined by definePage macro from SFC
- * Support using definePage in script setup or regular script
- *
- * @param sfc - Vue SFC descriptor
- * @returns Page metadata object, or undefined if definePage is not found
- */
-declare function tryPageMetaFromMacro(sfc: SFCDescriptor): Promise<UserPageMeta | undefined>;
-/**
- * Find definePage macro call in AST
- * Support function expressions, arrow functions and object expressions as arguments
+ * 把条件定义算成某个平台的普通配置
  *
- * @param stmts - AST statement array
- * @param filename - Filename for error reporting
- * @returns definePage call expression, or undefined if not found
+ * 简单包了一层 {@link DefineConditional.resolve}，调用方不用导入
+ * 这个类。
  */
-declare function findMacro(stmts: t.Statement[], filename: string): t.CallExpression | undefined;
+declare function resolveConditional(cond: DefineConditional, platform: string): Record<string, any>;
+//#endregion
+//#region src/logger.d.ts
 /**
- * Extract all import declarations from AST
- * Used to provide necessary imports when executing definePage arguments
- *
- * @param stmts - AST statement array
- * @returns Import declaration array
+ * 调试日志工具
+ * 基于 debug 包做分级日志输出
+ * 通过环境变量 DEBUG=vite-plugin-uni-pages:* 开启
  */
-declare function findImports(stmts: t.Statement[]): t.ImportDeclaration[];
+declare const debug: {
+  /** HMR 相关日志 */
+  hmr: Debug.Debugger;
+  /** 配置项相关日志 */
+  options: Debug.Debugger;
+  /** 主包页面扫描日志 */
+  pages: Debug.Debugger;
+  /** 子包页面扫描日志 */
+  subPages: Debug.Debugger;
+  /** 错误日志 */
+  error: Debug.Debugger;
+  /** 缓存相关日志 */
+  cache: Debug.Debugger;
+  /** 声明文件生成日志 */
+  declaration: Debug.Debugger;
+  /** definePage 宏解析日志 */
+  definePage: Debug.Debugger;
+};
 //#endregion
 //#region src/context.d.ts
 /**
- * Page context class responsible for page scanning, config loading, page metadata merging and pages.json generation
+ * 页面上下文：负责扫描页面、加载配置、合并页面信息、生成 pages.json
  *
- * Core responsibilities:
- * 1. Scan page directories and collect page files
- * 2. Load user configuration files (pages.config.ts, etc.)
- * 3. Parse page metadata (definePage macro)
- * 4. Merge page configurations and generate pages.json
- * 5. Provide virtual module and HMR support
+ * 做的事情按固定顺序是：加载用户配置 → 扫描页面文件 → 合并页面
+ * 信息 → 写入 pages.json。这个顺序由 {@link updatePagesJSON}（完整
+ * 流程）或 {@link scanAndMerge}（只算不写）管理，调用方不用关心
+ * 内部步骤。
  */
 declare class PageContext {
   private _server;
-  /** Parsed configuration object from user config file (pages.config.ts) */
-  pagesGlobConfig: index_d_exports$1.PagesConfig | undefined;
-  /** Source path list of user configuration files */
+  /** 从用户配置文件（pages.config.ts）解析出的配置对象 */
+  pagesGlobConfig: PagesConfig | undefined;
+  /** 用户配置文件的来源路径列表 */
   pagesConfigSourcePaths: string[];
-  /** Main package page map, key is the absolute path of the page file */
+  /** 主包页面映射，键为页面文件的绝对路径 */
   pages: Map<string, Page>;
-  /** Sub-package page map, key is the sub-package root directory, value is the page map under that sub-package */
+  /** 子包页面映射，键为子包根目录，值为该子包下的页面映射 */
   subPages: Map<string, Map<string, Page>>;
-  /** Main package page metadata array for generating pages.json pages field */
-  pageMetaData: PageMetaDatum[];
-  /** Sub-package page metadata array for generating pages.json subPackages field */
-  subPageMetaData: SubPageMetaDatum[];
-  /** Generated pages.json file path */
+  /** 主包页面配置数组，用于生成 pages.json 的 pages 字段 */
+  pageMetaData: InternalPages;
+  /** 子包页面配置数组，用于生成 pages.json 的 subPackages 字段 */
+  subPageMetaData: SubPackages;
+  /**
+   * 最近一次合并出的 tabBar（配置文件与 definePage 声明的合体）。
+   * 类型声明生成 tab 页列表时用它，definePage 声明的 tabBar 页才能
+   * 一起从 navigateTo 的 url 类型里排除
+   */
+  tabBar: TabBar | undefined;
+  /** 生成的 pages.json 文件路径 */
   resolvedPagesJSONPath: string;
-  private resolvedPagesJSONIndent?;
-  private resolvedPagesJSONNewline?;
-  private resolvedPagesJSONEofNewline?;
-  /** Original options passed by the user */
-  rawOptions: UserOptions;
-  /** Project root directory */
+  /** 项目根目录 */
   root: string;
-  /** Resolved configuration options */
+  /** 解析后的配置项 */
   options: ResolvedOptions;
+  /** 当前平台标识，如 'mp-weixin'；由调用方传入，不依赖模块加载时冻结的环境 */
+  readonly platform: string;
   logger?: Logger;
-  /** Whether to work with vite-plugin-uni-platform plugin */
+  /** 是否与 vite-plugin-uni-platform 插件协同工作 */
   withUniPlatform: boolean;
-  /** Cached previous pages.json content to avoid redundant writes */
-  private lastPagesJson;
+  /** pages.json 中页面路径的解析基准路径 */
+  private get basePath();
   /**
-   * Create a PageContext instance
-   * @param userOptions - User configuration options
-   * @param viteRoot - Vite project root directory, defaults to current working directory
+   * 创建 PageContext 实例
+   * @param userOptions - 用户配置项
+   * @param viteRoot - Vite 项目根目录，默认为当前工作目录
+   * @param platform - 当前平台标识，默认取 uni-env 的平台
    */
-  constructor(userOptions: UserOptions, viteRoot?: string);
+  constructor(userOptions: UserOptions, viteRoot?: string, platform?: string);
   /**
-   * Set the Vite logger
-   * @param logger - Vite logger instance
+   * 设置 Vite logger
+   * @param logger - Vite logger 实例
    */
   setLogger(logger: Logger): void;
   /**
-   * Load user page configuration file (e.g. pages.config.ts)
-   * Uses unconfig to load configuration, supporting multiple config file formats
+   * 加载用户页面配置文件（如 pages.config.ts）
+   * 使用 unconfig 加载配置，支持多种配置文件格式
    */
   loadUserPagesConfig(): Promise<void>;
   /**
-   * Scan main package page directories and collect all page file paths
-   * Scan corresponding directories based on the configured dirs option
+   * 按顺序跑完扫描与合并：先扫描主包和子包的页面，再合并它们的
+   * 信息。步骤顺序只维护在这里，调用方和测试都不用关心。
    */
-  scanPages(): Promise<void>;
+  scanAndMerge(): Promise<void>;
   /**
-   * Scan sub-package page directories and collect all sub-package page file paths
-   * Scan corresponding directories based on the configured subPackages option
-   */
-  scanSubPages(): Promise<void>;
-  /**
-   * Set up Vite dev server for HMR and file watching
-   * @param server - Vite dev server instance
+   * 设置 Vite 开发服务器，用于 HMR 与文件监听
+   * @param server - Vite 开发服务器实例
    */
   setupViteServer(server: ViteDevServer): void;
   /**
-   * Set up file watcher to monitor page file and config file changes
-   * Automatically update pages.json when page files or config files change
-   * @param watcher - chokidar file watcher instance
+   * 设置文件监听器，监听页面文件与配置文件变更
+   * 页面文件或配置文件变化时自动更新 pages.json
+   * @param watcher - chokidar 文件监听器实例
    */
   setupWatcher(watcher: FSWatcher): Promise<void>;
   /**
-   * Page update callback, triggered when page files or configuration changes
-   * Responsible for invalidating virtual modules and notifying the browser to do a full reload
+   * 页面更新回调，页面文件或配置变化时触发
+   * 负责使虚拟模块失效并通知浏览器整页刷新
    */
   onUpdate(): void;
   /**
-   * parse pages rules && set page type
-   * @param pages page path array
-   * @param type  page type
-   * @param overrides custom page config
-   * @returns pages rules
+   * 更新 pages.json 文件
+   * 这是负责协调整个页面配置生成流程的核心方法：
+   * 1. 检查文件变更（指定 filepath 时）
+   * 2. 加载用户配置
+   * 3. 扫描页面文件
+   * 4. 合并页面配置
+   * 5. 生成并写入 pages.json
+   * @param filepath - 发生变更的文件路径，用于增量更新判断
+   * @returns pages.json 是否成功更新
    */
-  parsePages(pages: Map<string, Page>, type: 'main' | 'sub', overrides?: PageMetaDatum[]): Promise<PageMetaDatum[]>;
+  updatePagesJSON(filepath?: string): Promise<boolean>;
   /**
-   * set home page
-   * @param result pages rules array
-   * @returns pages rules
+   * 生成虚拟模块内容
+   * 返回包含 pages 与 subPackages 导出的 JavaScript 代码
+   * @returns 虚拟模块代码字符串
    */
-  setHomePage(result: PageMetaDatum[]): PageMetaDatum[];
+  virtualModule(): string;
   /**
-   * Merge main package page metadata
-   * Filter out pages belonging to sub-packages, then parse page metadata and merge user configuration
+   * 将主包路由数据解析为 JSON 字符串
+   * @returns 主包页面配置的 JSON 字符串
    */
-  mergePageMetaData(): Promise<void>;
+  resolveRoutes(): string;
   /**
-   * Merge sub-package page metadata
-   * Parse page metadata for each sub-package and handle sub-package configuration inheritance
-   * Preserves sub-package level properties like plugins from user config
+   * 将子包路由数据解析为 JSON 字符串
+   * @returns 子包页面配置的 JSON 字符串
    */
-  mergeSubPageMetaData(): Promise<void>;
+  resolveSubRoutes(): string;
   /**
-   * Update pages.json file
-   * This is the core method responsible for coordinating the entire page configuration generation flow:
-   * 1. Check file changes (if filepath is specified)
-   * 2. Load user configuration
-   * 3. Scan page files
-   * 4. Merge page metadata
-   * 5. Generate and write pages.json
-   * @param filepath - Changed file path for incremental update judgment
-   * @returns Whether pages.json was successfully updated
+   * 解析 tabBar 配置
+   * 将页面定义的 tabBar 项与配置文件定义的 tabBar 合并
+   * @returns 合并后的 tabBar 配置对象，无 tabBar 时为 undefined
    */
-  updatePagesJSON(filepath?: string): Promise<boolean>;
+  resolveTabBar(): Promise<TabBar | undefined>;
   /**
-   * Generate virtual module content
-   * Returns JavaScript code containing pages and subPackages exports
-   * @returns Virtual module code string
+   * 生成 TypeScript 声明文件
+   * 为页面路径生成类型定义，导航时提供类型提示
    */
-  virtualModule(): string;
+  generateDeclaration(): Promise<void> | undefined;
   /**
-   * Resolve main package route data to JSON string
-   * @returns JSON string of main package page metadata
+   * 扫描主包页面目录并收集所有页面文件路径
+   * 根据配置的 dirs 选项扫描对应目录
    */
-  resolveRoutes(): string;
+  private scanPages;
   /**
-   * Resolve sub-package route data to JSON string
-   * @returns JSON string of sub-package page metadata
+   * 按页面文件绝对路径查找被跟踪的页面（主包或任一子包）
+   * @param filepath - 页面文件的绝对路径
+   * @returns 被跟踪的页面，文件未被跟踪时为 undefined
    */
-  resolveSubRoutes(): string;
+  private findPage;
   /**
-   * Resolve tabBar configuration
-   * Merges page-defined tabBar items with config-defined tabBar
-   * @returns Merged tabBar configuration object, or undefined if no tabBar exists
+   * 扫描子包页面目录并收集所有子包页面文件路径
+   * 根据配置的 subPackages 选项扫描对应目录
    */
-  resolveTabBar(): Promise<index_d_exports$1.TabBar | undefined>;
+  private scanSubPages;
   /**
-   * Generate TypeScript declaration file
-   * Generate type definitions for page paths to provide type hints during navigation
+   * 解析 pages 规则并设置页面类型
+   * @param pages 页面路径映射
+   * @param packageType 页面包类型（主包或子包）
+   * @param overrides 自定义页面配置
+   * @returns pages 规则
    */
-  generateDeclaration(): Promise<void> | undefined;
-  private genratePagesJSON;
-  private readInfoFromPagesJSON;
-  private getIndent;
-  private getNewline;
-  private getEndOfLine;
+  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/utils.d.ts
+//#region src/page.d.ts
 /**
- * Invalidate virtual module to trigger HMR update
- * When page configuration changes, the virtual module needs to be invalidated to regenerate content
+ * 表示一个 Vue 页面文件的 Page 类
  *
- * @param server - Vite dev server instance
+ * 职责：
+ * 1. 读取页面文件内容
+ * 2. 解析 definePage 宏定义的页面配置
+ * 3. 提供 tabBar 配置信息
+ * 4. 跟踪页面文件变更状态
  */
-declare function invalidatePagesModule(server: ViteDevServer): void;
+declare class Page {
+  /** 页面上下文实例 */
+  ctx: PageContext;
+  /** 页面路径信息，包含相对路径与绝对路径 */
+  path: PagePath;
+  /** 页面 URI，用于 pages.json 的 path 字段 */
+  uri: string;
+  /** 页面是否发生变化，用于增量更新判断 */
+  changed: boolean;
+  /**
+   * 页面是否通过 `definePage(null)` 或函数式宏在当前平台返回 null 而
+   * 退出了 pages.json
+   */
+  skipped: boolean;
+  /** 页面文件是否至少被读取过一次 */
+  private loaded;
+  /** 页面配置的原始 JSON 字符串，用于变更检测 */
+  private raw;
+  /** 解析后的页面配置 */
+  private meta;
+  /**
+   * 创建页面实例
+   * @param ctx - 页面上下文实例
+   * @param path - 页面路径信息
+   */
+  constructor(ctx: PageContext, path: PagePath);
+  /**
+   * 获取页面配置
+   * 解析 definePage 宏定义的配置并返回用于 pages.json 的配置
+   *
+   * @param forceUpdate - 是否强制更新，忽略缓存
+   * @returns 页面配置对象
+   */
+  getPageMeta(forceUpdate?: boolean): Promise<InternalPageItem>;
+  /**
+   * 获取页面 tabBar 配置
+   * 从 definePage 宏中提取 tabBar 相关配置
+   *
+   * @param forceUpdate - 是否强制更新，忽略缓存
+   * @returns tabBar 配置对象，页面未定义 tabBar 时返回 undefined
+   */
+  getTabBar(forceUpdate?: boolean): Promise<TabBarItem & {
+    index: number;
+  } | undefined>;
+  /**
+   * 确保页面文件至少被读取过一次，使 `skipped` 与缓存的配置反映
+   * 当前文件内容
+   */
+  ensureLoaded(): Promise<void>;
+  /**
+   * 检查页面是否发生变化
+   * @returns 页面是否发生变化
+   */
+  hasChanged(): boolean;
+  /**
+   * 读取页面文件并解析配置
+   * 从 Vue SFC 中提取 definePage 宏定义的配置
+   */
+  read(): Promise<void>;
+  private readPageMetaFromFile;
+}
+//#endregion
+//#region src/types.d.ts
 /**
- * Debug logging utility
- * Uses debug package for leveled log output
- * Enable via environment variable DEBUG=vite-plugin-uni-pages:*
+ * 从对象类型中排除索引签名键，仅保留显式键
  */
-declare const debug: {
-  /** HMR related logs */hmr: Debug.Debugger; /** Configuration options related logs */
-  options: Debug.Debugger; /** Main package page scanning logs */
-  pages: Debug.Debugger; /** Sub-package page scanning logs */
-  subPages: Debug.Debugger; /** Error logs */
-  error: Debug.Debugger; /** Cache related logs */
-  cache: Debug.Debugger; /** Declaration file generation logs */
-  declaration: Debug.Debugger; /** definePage macro parsing logs */
-  definePage: Debug.Debugger;
-};
+type ExcludeIndexSignature<T> = { [K in keyof T as string extends K ? never : number extends K ? never : symbol extends K ? never : K]: T[K]; };
 /**
- * Convert file extensions array to glob pattern
- * @param extensions - File extensions array
- * @returns Glob pattern string
+ * 插件内部的页面信息
+ * 在标准 PageItem 之上加了插件自己用的 `type` 标记。
+ * 插件写的条目会带着它进 pages.json（之后的运行靠它找回首页）；
+ * 只有比较两个条目相不相等时，会先把它去掉再比
  */
-declare function extsToGlob(extensions: string[]): string;
+interface InternalPageItem extends PageItem {
+  /** 插件用于识别首页的内部标记 */
+  type?: 'home' | 'page';
+}
+type InternalPages = InternalPageItem[];
 /**
- * Check if file is a target page file
- * Determine if the file extension is in the supported page file types list
- *
- * @param path - File path
- * @returns Whether it's a target file
+ * 用户可在 definePage 宏中定义的 tabBar 项
+ * 在文档级 TabBarItem 之上扩展插件专有字段
  */
-declare function isTargetFile(path: string): boolean;
+interface UserTabBarItem extends Partial<TabBarItem> {
+  /**
+   * 页面路径，省略时由插件自动填充
+   *
+   * @deprecated 改用 pages.json 的 pagePath
+   */
+  pagePath?: string;
+  /**
+   * 插件用于排序 tabBar 项的索引
+   *
+   * @default 0
+   */
+  index?: number;
+  [x: string]: any;
+}
 /**
- * merge page meta data array by path and assign style
- * @param pageMetaData  page meta data array
- * TODO: support merge middleware
+ * 用户可在 definePage 宏中定义的页面配置
+ * 在文档级 PageItem 之上扩展插件专有字段
  */
-declare function mergePageMetaDataArray(pageMetaData: PageMetaDatum[]): PageMetaDatum[];
+interface UserPageItem extends Partial<PageItem> {
+  /**
+   * @deprecated 改用 pages.json 的 path
+   */
+  path?: string;
+  /**
+   * 页面类型，设为 "home" 标记首页
+   */
+  type?: 'home' | 'page';
+  /**
+   * tabBar 项配置，插件收集它生成 pages.json 的 tabBar.list
+   */
+  tabBar?: UserTabBarItem;
+  [x: string]: any;
+}
+/** 值或值的 Promise */
+type MaybePromise<T> = T | Promise<T>;
+/** 值或返回该值的函数 */
+type MaybeCallable<T> = T | (() => T);
+/** 值、返回该值的函数，或返回该值 Promise 的函数 */
+type MaybePromiseCallable<T> = T | (() => T) | (() => Promise<T>);
 /**
- * Convert TypeScript / JavaScript script code to object/function
+ * 注入函数式 definePage 宏的上下文
+ */
+interface DefinePageContext {
+  /** 当前平台标识，如 'mp-weixin' */
+  platform: string;
+  /**
+   * 开始写"按平台不同"的页面配置
+   *
+   * 用法：`define(base).ifdef(platforms, partial).ifndef(platforms, partial)`。
+   * 匹配的分支按写的顺序合并进 `base`：对象一层层合并，数组和普通值
+   * 整个替换。`h5` 和 `web` 是同一个平台的两个名字，写哪个都算
+   * 两个都匹配。
+   */
+  define: (base: UserPageItem) => DefineConditional;
+}
+/**
+ * 在 Vue 页面文件中定义页面配置
+ * 宏调用会在构建时被插件移除
  *
- * @param options - Configuration required for script execution
- * @param options.imports - List of module import statements to include
- * @param options.code - TypeScript code content to execute
- * @param options.filename - Script filename for error location and context
- * @returns Script execution result, if export is a function then execute and return its return value
+ * 返回 `null`（或直接传 `null`）可把页面从当前平台的 pages.json 里
+ * 排除。用传进来的 `define` 就能按平台写不同配置，不用自己判断平台。
  */
-declare function parseCode(options: {
-  imports: string[];
-  code: string;
-  filename: string;
-}): Promise<any>;
+declare function definePage(options: UserPageItem | null | ((context: DefinePageContext) => MaybePromise<UserPageItem | DefineConditional | null>)): void;
+/** definePage 宏的类型 */
+type DefinePage = typeof definePage;
+/** 调试日志类型，对应 debug 对象中的方法 */
+type DebugType = keyof typeof debug;
 /**
- * Async sleep function
- * @param ms - Sleep duration in milliseconds
- * @returns Promise object
+ * @deprecated 改用 {@link DebugType}
  */
-declare function sleep(ms: number): Promise<unknown>;
-/** Babel code generator for converting AST back to code */
-declare const babelGenerate: typeof babelGenerator;
-//#endregion
-//#region src/types.d.ts
-/** Debug log type, corresponding to methods in the debug object */
-type debugType = keyof typeof debug;
-/** Configuration source type, supports string path or unconfig LoadConfigSource object */
-type ConfigSource = string | LoadConfigSource<index_d_exports$1.PagesConfig> | LoadConfigSource<index_d_exports$1.PagesConfig>[];
+type debugType = DebugType;
+/** 配置来源类型，支持字符串路径或 unconfig 的 LoadConfigSource 对象 */
+type ConfigSource = string | LoadConfigSource<PagesConfig> | LoadConfigSource<PagesConfig>[];
 /**
- * Plugin configuration options interface
- * Defines all configuration options that users can pass in
+ * 插件配置项接口
+ * 定义用户可传入的全部配置选项
+ *
+ * 内部流水线：加载用户配置 -> 扫描页面文件 -> 合并页面配置 ->
+ * 生成并写入 pages.json
  */
 interface Options {
   /**
-   * Generate TypeScript declaration for pages path
+   * 是否为页面路径生成 TypeScript 声明
    *
-   * Accept boolean or a path related to project root
+   * 为 `true` 时在项目根目录生成 `uni-pages.d.ts`；
+   * 为字符串时作为相对项目根目录的自定义输出路径。
    *
    * @default true
+   * @since 0.2.9
    */
   dts?: boolean | string;
   /**
-   * Load from configs files
+   * 页面配置文件的加载来源
+   *
+   * 基于 unconfig，支持合并多个配置来源
    *
-   * @default 'pages.config.(ts|mts|cts|js|cjs|mjs|json)',
+   * @default 'pages.config'
+   * @since 0.2.7
    */
   configSource: ConfigSource;
   /**
-   * The default application entry page is the home page
-   * @default 'pages/index' or 'pages/index/index'
+   * 默认应用入口页面（首页）
+   *
+   * 在没有页面通过 `definePage({ type: 'home' })` 标记为首页时使用。
+   * 支持多种路径写法，兼容不同的目录布局。
+   *
+   * @default ['pages/index', 'pages/index/index']
+   * @since 0.1.9
    */
-  homePage: string;
+  homePage: string | string[];
   /**
-   * Whether to merge pages in pages.json
+   * 是否自动扫描目录并把页面配置合并进 pages.json
+   *
+   * 关闭时只加载用户配置文件，不扫描文件系统
+   *
    * @default true
+   * @since 0.1.0
    */
   mergePages: boolean;
   /**
-   * Paths to the directory to search for page components.
+   * 主包页面的搜索目录
+   *
+   * 支持 glob 模式，如 'src/{pages,views}'。
+   * 最终结果由 tinyglobby 解析为匹配到的目录列表。
+   *
    * @default 'src/pages'
+   * @since 0.1.0
    */
   dir: string;
   /**
-   * Sub-package page directories for uni-app sub-package loading
+   * uni-app 分包加载的子包页面目录
    *
-   * Supports string format (directory path) or object format (custom root in pages.json)
+   * 支持字符串形式（目录路径）或对象形式（pages.json 中的自定义 root）
    *
-   * In monorepo projects, pages may be located outside the project root.
-   * Use object format to specify a custom root that appears in pages.json,
-   * avoiding '..' in the generated root path.
+   * monorepo 项目中页面可能位于项目根目录之外。使用对象形式指定
+   * 出现在 pages.json 中的自定义 root，避免生成的 root 路径含 '..'。
    *
    * @see https://github.com/uni-helper/vite-plugin-uni-pages/issues/271
    * @default []
+   * @since 0.1.8
    */
   subPackages: (string | SubPackageConfig)[];
   /**
-   * pages.json dir
-   * @default "src"
+   * pages.json 所在目录
+   *
+   * 相对项目根目录，也是计算页面相对路径的基准
+   *
+   * @default 'src'
+   * @since 0.0.1
    */
   outDir: string;
   /**
-   * pages to be excluded, based on [tinyglobby ignore option](https://superchupu.dev/tinyglobby/documentation#ignore)
-   * @default []
+   * 排除的文件/目录模式
+   *
+   * 基于 [tinyglobby 的 ignore 选项](https://superchupu.dev/tinyglobby/documentation#ignore)
+   *
+   * @default ['node_modules', '.git', '**\/__*__/**']
+   * @since 0.0.4
    */
   exclude: string[];
   /**
-   * minify the `pages.json`
+   * 压缩生成的 pages.json
    * @default false
+   * @since 0.1.6
    */
   minify: boolean;
   /**
-   * enable debug log
-   */
-  debug: boolean | debugType;
-  onBeforeLoadUserConfig: (ctx: PageContext) => void;
-  onAfterLoadUserConfig: (ctx: PageContext) => void;
-  onBeforeScanPages: (ctx: PageContext) => void;
-  onAfterScanPages: (ctx: PageContext) => void;
-  onBeforeMergePageMetaData: (ctx: PageContext) => void;
-  onAfterMergePageMetaData: (ctx: PageContext) => void;
-  onBeforeWriteFile: (ctx: PageContext) => void;
-  onAfterWriteFile: (ctx: PageContext) => void;
+   * 是否在生成的 pages.json 末尾追加换行符
+   * @default false
+   * @since 0.5.0
+   */
+  insertFinalNewline: boolean;
+  /**
+   * 生成的 pages.json 的缩进
+   *
+   * 接受空格数或字符串（如 `'\t'`）
+   *
+   * `minify` 为 `true` 时忽略
+   * @default 2
+   * @since 0.5.0
+   */
+  indent: number | string;
+  /**
+   * 生成的 pages.json 的换行符
+   * @default '\n'
+   * @since 0.5.0
+   */
+  eol: '\n' | '\r\n';
+  /**
+   * 启用调试日志
+   *
+   * 为 `true` 时启用所有分类；为字符串时只启用对应分类。可用分类：
+   * hmr | options | pages | subPages | error | cache | declaration | definePage。
+   * 也可通过 DEBUG=vite-plugin-uni-pages:* 环境变量控制。
+   *
+   * @default false
+   * @since 0.1.8
+   */
+  debug: boolean | DebugType;
+  /**
+   * 生命周期钩子，在各流水线阶段触发。钩子只接收该阶段的输入或输出
+   * 数据，绝不接收整个上下文。
+   *
+   * @since 0.0.3
+   */
+  onBeforeLoadUserConfig: () => void;
+  onAfterLoadUserConfig: (pagesGlobConfig: PagesConfig | undefined) => void;
+  onBeforeScanPages: () => void;
+  onAfterScanPages: (pages: Map<string, Page>, subPages: Map<string, Map<string, Page>>) => void;
+  onBeforeMergePageMetaData: (pages: Map<string, Page>, pagesGlobConfig: PagesConfig | undefined) => void;
+  onAfterMergePageMetaData: (pageMetaData: InternalPages, subPageMetaData: SubPackages) => void;
+  onBeforeWriteFile: (filePath: string) => void;
+  onAfterWriteFile: (filePath: string, content: string) => void;
 }
-/** User configuration options type, all options are optional */
+/** 用户配置项类型，所有选项均为可选 */
 type UserOptions = Partial<Options>;
 /**
- * Resolved configuration options interface
- * Configuration processed by resolveOptions, all paths resolved to absolute paths
+ * 解析后的配置项接口
+ * 经 resolveOptions 处理的配置，所有路径均解析为绝对路径
  */
 interface ResolvedOptions extends Omit<Options, 'dir' | 'homePage' | 'configSource' | 'dts' | 'subPackages'> {
   /**
-   * Resolves to the `root` value from Vite config.
+   * 解析为 Vite 配置中的 `root` 值。
    * @default config.root
    */
   root: string;
   dts: string | false;
   /**
-   * Resolved page dirs
+   * 解析后的页面目录列表
    */
   dirs: string[];
   /**
-   * Resolved entry page
+   * 解析后的入口页面
    */
   homePage: string[];
-  configSource: LoadConfigSource<index_d_exports$1.PagesConfig>[];
+  configSource: LoadConfigSource<PagesConfig>[];
   /**
-   * Resolved sub-package directories
+   * 解析后的子包目录列表
    */
   subPackages: string[];
   /**
-   * Custom root mapping for sub-packages (dir -> root)
-   * Used for monorepo support to specify custom root paths in pages.json
+   * 子包的自定义 root 映射（目录 -> root）
+   * 用于 monorepo 支持，指定 pages.json 中的自定义 root 路径
    */
   subPackageRootMap: Map<string, string>;
 }
 /**
- * Sub-package configuration interface
- * Allows customizing the root path in pages.json for monorepo support
+ * 子包配置接口
+ * 为 monorepo 支持，允许自定义 pages.json 中的 root 路径
  *
- * In monorepo projects, pages may be located outside the project root (e.g., ../../packages/login/src/pages).
- * By default, the plugin generates root paths with '..', which uni-app does not support.
- * Use this config to specify a custom root that appears in pages.json instead.
+ * monorepo 项目中页面可能位于项目根目录之外（如 ../../packages/login/src/pages）。
+ * 默认情况下插件会生成含 '..' 的 root 路径，而 uni-app 不支持。
+ * 通过该配置指定出现在 pages.json 中的自定义 root。
  *
  * @example
  * ```ts
  * subPackages: [
  *   {
- *     dir: '../../packages/login/src/pages',  // Physical directory to scan
- *     root: 'packages/login/src/pages',       // Custom root in pages.json
+ *     dir: '../../packages/login/src/pages',  // 实际扫描的物理目录
+ *     root: 'packages/login/src/pages',       // pages.json 中的自定义 root
  *   }
  * ]
  * ```
  */
 interface SubPackageConfig {
-  /** Physical directory path to scan for page files */
+  /** 扫描页面文件的实际物理目录路径 */
   dir: string;
-  /** Custom root path that appears in pages.json subPackages.root */
+  /** 出现在 pages.json subPackages.root 中的自定义根路径 */
   root: string;
 }
 /**
- * Page path information interface
- * Contains relative and absolute paths of page files
+ * 页面路径信息接口
+ * 包含页面文件的相对路径与绝对路径
  */
 interface PagePath {
-  /** Path relative to the output directory */
+  /** 相对输出目录的路径 */
   relativePath: string;
-  /** Absolute path of the page file */
+  /** 页面文件的绝对路径 */
   absolutePath: string;
 }
 //#endregion
+//#region src/config.d.ts
+/**
+ * 定义 uni-pages 配置
+ * 在 pages.config.ts 配置文件中使用，提供类型提示与校验
+ *
+ * @param config - 页面配置对象
+ * @returns 配置对象
+ */
+declare function defineUniPages(config: UserPagesConfig): UserPagesConfig;
+//#endregion
 //#region src/constant.d.ts
-/** Virtual module identifier for Vite module resolution */
+/** Vite 模块解析用的虚拟模块标识 */
 declare const MODULE_ID_VIRTUAL = "virtual:uni-pages";
-/** Resolved virtual module identifier with \0 prefix to avoid conflicts with other modules */
+/** 加 \0 前缀解析后的虚拟模块标识，避免与其他模块冲突 */
 declare const RESOLVED_MODULE_ID_VIRTUAL = "\0virtual:uni-pages";
-/** Output filename, the uni-app page configuration file */
+/** 输出文件名，即 uni-app 的页面配置文件 */
 declare const OUTPUT_NAME = "pages.json";
-/** Supported page file extensions */
+/** 支持的页面文件扩展名 */
 declare const FILE_EXTENSIONS: string[];
 //#endregion
 //#region src/files.d.ts
 /**
- * Resolves the files that are valid pages for the given context.
+ * 解析给定上下文下可作为有效页面的文件列表。
  */
 declare function getPageFiles(path: string, options: ResolvedOptions): string[];
 /**
- * Check the pages.json file at the specified path, create an empty pages.json file if it doesn't exist or is not a valid file
- * @param path - File path to check
- * @returns boolean - Whether the operation was successful
+ * 检查文件是否为目标页面文件
+ * 判断文件扩展名是否在支持的页面文件类型列表中
+ *
+ * @param path - 文件路径
+ * @returns 是否为目标文件
+ */
+declare function isTargetFile(path: string): boolean;
+/**
+ * 根据项目根目录与输出目录解析 pages.json 文件路径
+ *
+ * @param root - 项目根目录
+ * @param outDir - 相对 root 的 pages.json 输出目录
+ * @returns pages.json 绝对路径
+ */
+declare function resolvePagesJsonPath(root: string, outDir: string): string;
+/**
+ * 确保这个路径上有一个能用的 pages.json 文件。
+ *
+ * 文件不存在时创建一个占位文件，占位内容很快会被下一次生成覆盖。
+ * 已存在的文件绝不删除重建：删它会悄悄弄丢手写的内容（只读的文件
+ * 也能被删除，只要它所在的目录可写），所以"路径存在但不是普通文件、
+ * 或者读不了也写不了"都算必须由用户自己修的硬错误（例如
+ * `chmod u+w`）。
+ *
+ * @param path - 待检查的文件路径
+ * @throws 路径存在但不是普通文件、缺少读写权限，或占位文件创建失败时
+ *          抛出
  */
-declare function checkPagesJsonFileSync(path: fs.PathLike): boolean;
+declare function checkPagesJsonFileSync(path: fs.PathLike): void;
 /**
- * Run a task while holding an exclusive file lock.
+ * 拿到文件的独占锁后运行任务，运行完自动放锁。
+ *
+ * 它保护"读文件 → 算新内容 → 写回"的整个过程：锁从 `task` 开始
+ * 一直拿到它结束，别的进程看不到、也覆盖不了写了一半的文件。
+ * pages.json 的生成靠这一点：新内容要根据当前文件来算（里面有其他
+ * 平台的 `#ifdef` 块）。
  *
- * Unlike {@link writeFileWithLock}, this protects the whole read-modify-write
- * critical section. The lock is held from the moment `task` starts until it
- * resolves, so concurrent processes cannot observe or overwrite a half-written
- * state. This is required by pages.json generation, where the new content
- * depends on the current content (other platforms' `#ifdef` blocks).
+ * 同进程的调用方先在上面那条按路径的队列里排队，再碰 OS 锁；下面的
+ * 重试只用来等其他进程放锁。
  *
- * @param path - File path used as the lock target
- * @param task - Async work to run inside the lock; return value is forwarded
- * @param retry - Number of retries when lock acquisition fails, defaults to 3
- * @returns The value resolved by `task`, or `undefined` if the lock could not be acquired
+ * @param path - 要加锁的文件路径
+ * @param task - 在锁内运行的异步任务；返回值原样返回给调用方
+ * @param retry - 锁被别人拿着时的重试次数，默认 3
+ * @returns `task` 的结果；一直拿不到锁时为 `undefined`
  */
 declare function withFileLock<T>(path: string, task: () => Promise<T>, retry?: number): Promise<T | undefined>;
+//#endregion
+//#region src/macro.d.ts
 /**
- * Safely write file using file lock
- * Avoid data corruption caused by concurrent writes through file lock
- * Use atomic write to ensure file write integrity
+ * definePage 宏的解析与求值
  *
- * Note: this only makes the *write* atomic. Callers that need to read the
- * current content before computing the new one must use {@link withFileLock}
- * so the read and write belong to the same critical section.
+ * 这个文件负责看懂一个 definePage 宏要的全部步骤：解析 Vue 单文件
+ * 组件、逐个 script 块解析（单个块失败不影响别的块）、找到宏调用、
+ * 收集 import 语句、放进沙箱求值。外部只用两个函数：
+ * evaluateDefinePage（扫描时用）和 findDefinePageMacro（转换时用）。
  *
- * @param path - File path
- * @param content - File content
- * @param retry - Number of retries when lock acquisition fails, defaults to 3
+ * 两个入口都从 {@link parseSfcBlocks} 的块模型取宏：「两边按同一套
+ * 规则找到同一个宏」由这个共享模型保证，不靠两边各自实现再对齐。
  */
-declare function writeFileWithLock(path: string, content: string, retry?: number): Promise<void | undefined>;
+/**
+ * 解析 Vue 单文件组件（SFC）
+ * 兼容不同版本的 @vue/compiler-sfc
+ *
+ * @param code - Vue SFC 源码
+ * @param options - 解析选项
+ * @returns SFC descriptor 对象
+ */
+declare function parseSFC(code: string, options?: SFCParseOptions): SFCDescriptor;
+/**
+ * 求值 Vue SFC 里的 definePage 宏，返回页面信息
+ *
+ * 扫描时用。解析或求值出错时，错误会交给调用方（Page.read），它会把
+ * 这个页面退回成只含路径的简单信息。
+ *
+ * @param code - Vue SFC 源码
+ * @param filename - SFC 文件名，用于错误提示和模块解析
+ * @param platform - 当前平台标识，传给函数式宏；默认取 uni-env 的平台
+ * @returns 页面信息对象；宏明确退出（definePage(null) 或函数返回
+ * null）时为 `null`；没找到 definePage 时为 undefined
+ */
+declare function evaluateDefinePage(code: string, filename: string, platform?: string): Promise<UserPageItem | null | undefined>;
+/**
+ * 在 Vue SFC 中定位 definePage 宏调用但不求值
+ *
+ * 转换插件用它找到宏再删掉，不求值。块解析失败通过 `onParseError`
+ * 报出来，不抛错。
+ *
+ * @param code - Vue SFC 源码
+ * @param filename - 用于错误上报的 SFC 文件名
+ * @param options - 可选的按块解析失败钩子
+ * @param options.onParseError - 以失败的 script 块名与错误对象调用
+ * @returns definePage 调用表达式，未找到时为 undefined
+ */
+declare function findDefinePageMacro(code: string, filename: string, options?: {
+  onParseError?: (block: string, error: unknown) => void;
+}): CallExpression | undefined;
 //#endregion
 //#region src/options.d.ts
 /**
- * Resolve user configuration options
- * Merge user-provided configuration with default values and handle path resolution
+ * 解析用户配置项
+ * 将用户提供的配置与默认值合并，并处理路径解析
  *
- * @param userOptions - User configuration options
- * @param viteRoot - Vite project root directory
- * @returns Resolved configuration options
+ * @param userOptions - 用户配置项
+ * @param viteRoot - Vite 项目根目录
+ * @returns 解析后的配置项
  */
 declare function resolveOptions(userOptions: UserOptions, viteRoot?: string): ResolvedOptions;
 /**
- * Resolves the page dirs for its for its given globs
+ * 根据给定的 glob 模式解析页面目录
+ * @param dir - 页面目录 glob 模式
+ * @param root - 项目根目录
+ * @param exclude - 需要排除的 glob 模式
+ * @returns 匹配到的目录路径
  */
 declare function resolvePageDirs(dir: string, root: string, exclude: string[]): string[];
-declare namespace index_d_exports {
-  export { ConfigSource, DefinePage, ExcludeIndexSignature, FILE_EXTENSIONS, MODULE_ID_VIRTUAL, MaybeCallable, MaybePromise, MaybePromiseCallable, OUTPUT_NAME, Options, Page, PageContext, PageMetaDatum, PagePath, RESOLVED_MODULE_ID_VIRTUAL, ResolvedOptions, SubPackageConfig, SubPageMetaDatum, UserOptions, UserPageMeta, UserTabBarItem, VitePluginUniPages, babelGenerate, checkPagesJsonFileSync, debug, debugType, VitePluginUniPages as default, definePage, defineUniPages, extsToGlob, findImports, findMacro, getPageFiles, invalidatePagesModule, isTargetFile, mergePageMetaDataArray, parseCode, parseSFC, resolveOptions, resolvePageDirs, sleep, tryPageMetaFromMacro, withFileLock, writeFileWithLock };
+//#endregion
+//#region src/pages-json.d.ts
+/**
+ * pages.json 的读取、合并、写回
+ *
+ * 这个文件负责 pages.json 的主流程：
+ * - 多个平台共用一个文件时，用 #ifdef 注释区分各自的条目（合并规则
+ *   的核心在 platform-variants.ts，数组侧的适配在这里，对象侧
+ *   tabBar 属性的适配在 tab-bar.ts）
+ * - 合并时保持首页排最前
+ * - 写入"由插件生成"的标记，靠它识别哪些条目是插件写的
+ * - 序列化格式（缩进、换行）
+ * - 文件锁和原子写入，防止并发写坏文件
+ *
+ * 外部只需要用 writePagesJson（写文件）和 mergePagesJson（纯计算），
+ * 不用接触 comment-json 的内部结构。
+ *
+ * 当前平台用不到的区块怎么处理，分两种情况：
+ * - tabBar 的外观属性：uni-app 条件编译能把整段剥掉，保留并包上 #ifdef
+ * - 没有任何页面的子包：构建产物里会留下指向不存在目录的空壳，直接删掉
+ */
+/** 由扫描/合并流水线组装出的路由数据 */
+interface PagesJsonData {
+  /** 主包页面配置 */
+  pages: InternalPages;
+  /** 子包页面配置 */
+  subPackages: SubPackages;
+  /** 解析后的 tabBar 配置 */
+  tabBar?: TabBar;
+  /**
+   * 从扫描出的配置解析出的首页路径。从 pages.json 合并而来的条目
+   * 可能缺少内部 `type` 标记（手写条目从不携带它），因此首页条目主要
+   * 按路径重新定位；未设置时退回到 `type` 标记。
+   */
+  homePath?: string;
+}
+/** 生成 pages.json 时怎么排版 */
+interface PagesJsonFormatOptions {
+  /**
+   * 压缩成一行输出，优先级高于 `indent`。单行 JSON 放不下注释，
+   * 生成标记、用户注释、所有 `#ifdef` 块都会丢失：只属于其他平台的
+   * 条目和区块会直接暴露在本平台的构建产物里（如外来的 tabBar
+   * list），tabBar 外观属性也变成"谁最后写谁说了算"。所以同一个
+   * 项目的所有平台要保持这个配置一致
+   */
+  minify?: boolean;
+  /** 缩进，空格数或字符串（如 '\t'） */
+  indent?: number | string;
+  /** 换行符 */
+  eol?: '\n' | '\r\n';
+  /** 是否在末尾追加换行符 */
+  insertFinalNewline?: boolean;
+}
+interface WritePagesJsonOptions {
+  /** 当前平台标识，如 'mp-weixin' 或 'h5' */
+  platform: string;
+  /** 来自 pages.config.ts 的用户配置；pages/subPackages/tabBar 之外的字段原样写进输出 */
+  globConfig?: PagesConfig;
+  /** 序列化格式 */
+  format?: PagesJsonFormatOptions;
+}
+/** 纯合并步骤的选项：{@link WritePagesJsonOptions} 中与文件无关的部分 */
+type MergePagesJsonOptions = Pick<WritePagesJsonOptions, 'platform' | 'globConfig' | 'format'>;
+/**
+ * 把路由数据合并进 pages.json 并写回
+ *
+ * 整个"读取 → 合并 → 写回"都锁在同一把文件锁里：因为新内容要参考
+ * 当前文件里其他平台的 `#ifdef` 块，两个终端同时跑（比如
+ * dev:mp-weixin + dev:mp-alipay）时才不会互相覆盖或读到写了一半的
+ * 内容。写入用临时文件 + rename，中途崩溃也不会留下截断的文件。
+ *
+ * @param jsonPath - pages.json 文件路径
+ * @param data - 由扫描/合并流水线组装的路由数据
+ * @param options - 平台、用户配置与序列化格式
+ * @returns 写入结果；获取不到文件锁时为 undefined
+ */
+declare function writePagesJson(jsonPath: string, data: PagesJsonData, options: WritePagesJsonOptions): Promise<{
+  updated: boolean;
+  content: string;
+} | undefined>;
+/**
+ * 不碰文件系统，只做计算：把路由数据合并进现有 pages.json 文本
+ * （多平台 `#ifdef` 块、首页重排、生成标记、过期子包清理）并序列化
+ * 成字符串。文件锁、变更检测和原子写入都在 {@link writePagesJson}
+ * 里；测试直接用字符串检查这个函数。
+ *
+ * @param existingContent - 当前 pages.json 文本，没有时传空字符串
+ * @param data - 由扫描/合并流水线组装的路由数据
+ * @param options - 平台、用户配置与序列化格式
+ * @returns 序列化后的 pages.json 内容
+ */
+declare function mergePagesJson(existingContent: string, data: PagesJsonData, options: MergePagesJsonOptions): string;
+//#endregion
+//#region src/pipeline.d.ts
+/**
+ * 插件对外的主要入口
+ *
+ * "扫描 → 合并 → 写入"这一整套流程，在这里包成一次调用就能跑的
+ * 函数。`root` 和 `platform` 可以从外面传进来，调用方和测试就不用
+ * 受制于进程启动时定死的工作目录和环境变量。Vite 插件和 PageContext
+ * 也是这里的调用方；测试通过这个入口跑完整流程，不去碰内部步骤。
+ */
+/** 可以从外面传进来的流水线输入 */
+interface PipelineOverrides {
+  /** 项目根目录，默认为当前工作目录 */
+  root?: string;
+  /** 当前平台标识，如 'mp-weixin'；默认取 uni-env 的平台 */
+  platform?: string;
 }
 /**
- * vite-plugin-uni-pages plugin main entry
+ * 创建 PageContext，并在内存里跑完「扫描/合并」
+ *
+ * 不写任何文件；路由数据通过 `resolveRoutes`、`resolveSubRoutes`、
+ * `resolveTabBar` 和 `virtualModule` 取。
+ *
+ * @param userOptions - 用户配置项
+ * @param overrides - 从外面传入的 root 与 platform
+ * @returns 完成扫描与合并的 PageContext
+ */
+declare function createPages(userOptions?: UserOptions, overrides?: PipelineOverrides): Promise<PageContext>;
+/**
+ * 运行完整流水线：加载用户配置、扫描、合并并写入 pages.json
+ * （以及 TypeScript 声明文件）
+ *
+ * @param userOptions - 用户配置项
+ * @param overrides - 从外面传入的 root 与 platform
+ * @returns pages.json 是否有更新，以及产出它的上下文
+ */
+declare function generateAll(userOptions?: UserOptions, overrides?: PipelineOverrides): Promise<{
+  updated: boolean;
+  ctx: PageContext;
+}>;
+//#endregion
+//#region src/index.d.ts
+/**
+ * vite-plugin-uni-pages 插件主入口
  *
- * Automatically scan page directories and generate pages.json configuration file
- * Support definePage macro for defining page metadata
- * Support multi-platform conditional compilation
- * Support sub-package configuration
- * Support TypeScript declaration file generation
+ * 自动扫描页面目录并生成 pages.json 配置文件
+ * 支持 definePage 宏定义页面配置
+ * 支持多平台条件编译
+ * 支持分包配置
+ * 支持 TypeScript 声明文件生成
  *
- * @param userOptions - User configuration options
- * @returns Vite plugin instance
+ * @param userOptions - 用户配置项
+ * @returns Vite 插件实例
  */
 declare function VitePluginUniPages(userOptions?: UserOptions): Plugin;
 //#endregion
-export { ConfigSource, type DefinePage, type ExcludeIndexSignature, FILE_EXTENSIONS, MODULE_ID_VIRTUAL, type MaybeCallable, type MaybePromise, type MaybePromiseCallable, OUTPUT_NAME, Options, Page, PageContext, type PageMetaDatum, PagePath, RESOLVED_MODULE_ID_VIRTUAL, ResolvedOptions, SubPackageConfig, type SubPageMetaDatum, UserOptions, type UserPageMeta, type UserTabBarItem, VitePluginUniPages, VitePluginUniPages as default, babelGenerate, checkPagesJsonFileSync, debug, debugType, type definePage, defineUniPages, extsToGlob, findImports, findMacro, getPageFiles, invalidatePagesModule, isTargetFile, mergePageMetaDataArray, parseCode, parseSFC, resolveOptions, resolvePageDirs, sleep, tryPageMetaFromMacro, withFileLock, writeFileWithLock };
+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 };