weapp-vite 7.4.0 → 7.5.0

package/dist/docs/vite-plugin.md

@@ -0,0 +1,171 @@
+# 标准 Vite 插件与 Vite+
+
+`weapp-vite/vite` 提供实验性的生产构建、classic 与 stateful 开发入口。当前阶段支持六平台单目标原生 JS/TS、Wevu Vue SFC 编译；微信另已验收 React、自动路由、自动组件、普通分包、独立分包、worker、微信插件双产物与 lib mode。主产物由宿主 Vite 的编译管线生成。
+
+## 配置
+
+项目使用 ESM（`package.json` 设置 `"type": "module"`），或将配置命名为 `vite.config.mts`：
+
+```ts
+import { defineConfig } from 'vite'
+import { weapp } from 'weapp-vite/vite'
+
+export default defineConfig({
+  plugins: [weapp()],
+  weapp: {
+    platform: 'weapp',
+    srcRoot: 'src',
+    hmr: { runtime: 'classic' },
+  },
+})
+```
+
+插件没有第二套配置参数。配置文件由宿主加载，插件不会自动发现或合并另一份 `weapp-vite.config.*`。迁移时把配置收敛到一个入口；需要拆文件时，在该入口显式导入。不要重复调用 `weapp()`，也不要把同一插件实例共享给两个活动宿主。
+
+```sh
+vite build
+vite dev
+```
+
+`mode: 'test'` 仍可用于生产构建。测试识别依赖实际 Vitest 宿主标识，不根据 mode 猜测。只读取配置不会扫描小程序入口、生成支持文件或启动 IDE/MCP；`wv prepare` 继续负责类型支持文件。
+
+## Vite+
+
+配置中的 `defineConfig` 改为从 `vite-plus` 导入，然后使用 `vp build` / `vp dev`。Vite+ 消费项目须按官方迁移规则把 `vite` 指向配套 core，并确保 weapp-vite 的依赖也解析到同一宿主。例如 npm 项目：
+
+```json
+{
+  "type": "module",
+  "devDependencies": {
+    "vite-plus": "1.0.0",
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.0.0"
+  },
+  "overrides": {
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.0.0"
+  }
+}
+```
+
+pnpm 使用项目级 `pnpm-workspace.yaml` 的 `overrides` 完成同样的 alias；不要只修改顶层依赖而留下 weapp-vite 内嵌的另一套 Vite。该组合对应 Vite 8.3.1 / Rolldown 1.2.11；Vite+ 项目验证线为 Node 24.11+，普通 weapp-vite 的 Node 范围不变。
+
+## 当前命令边界
+
+| 命令 | 当前行为 |
+| --- | --- |
+| `vite build` / `vp build` | 实验性单目标小程序生产构建 |
+| `wv dev` / `wv build` | 保留原有能力；显式插件不会重复安装编译器 |
+| `vite dev` / `vp dev` | 实验性 classic / stateful 开发；由宿主管理启动、重启与关闭 |
+| `vite build --watch` / `vp build --watch` | 实验性生产 watch：完整目标产物、入口增删与失败恢复 |
+| `vp test` | 插件不启动小程序编译；mpcore 测试继续显式使用 artifact API |
+| `wv prepare/open/upload/mcp` | 继续使用小程序专属命令 |
+| `vp preview` | Vite 的 Web 预览，不是小程序二维码预览 |
+| `vp pack` | 通用库打包，不替代小程序 lib mode |
+
+每次调用选择一个目标。纯 Web 使用 `weapp.platform: 'web'`；Web/小程序同宿主混合开发仍未开放。
+
+生产构建、build watch、classic 与实验性 stateful dev 已接入。脚手架支持与业务模板独立的 `--toolchain=wv|vite|vite-plus`，生成对应宿主脚本、显式配置入口和 Vite+ core alias；小程序专属命令继续使用 `wv`。任务缓存、Dashboard/MCP 会话复用和完整跨平台发布矩阵仍属于后续阶段。完整编译能力对齐继续由 #1097 追踪；高级目标限制是阶段边界。
+
+## classic 开发
+
+`vite dev` / `vp dev` 由宿主负责服务器和配置重载，小程序会话复用现有增量编译调度，产物经 Vite/Rolldown 原生 write 落盘。首次完整产物就绪后才打印小程序就绪日志。脚本、模板、样式和页面增删会更新产物；语法错误修正后继续编译。宿主 `server.close()`（包括 middleware mode）会等待正在执行的构建再释放自有资源。
+
+classic 模式不支持宿主 `experimental.bundledDev: true`，开启时会在启动前报错。classic 更新遵循完整重载语义，不承诺实例状态保持。`wv dev` 保留原有 HMR 选择和全部目标能力。
+
+同一宿主目前只编译一个小程序目标，暂不支持同时开发 Web。插件不会自动打开 IDE、启动 MCP 或上传。
+
+## 检查与排障
+
+- 缺少入口：核对 `weapp.srcRoot`、`app.json`/`app.vue` 和宿主的 `root`。
+- ESM 配置加载失败：使用 `type: module` 或 `.mts`，不依赖旧 CLI 的 runner 回退。
+- 引擎加载失败：核对 Vite+ core alias 和实际解析路径；配套引擎缺失时会报错，不静默切换到其他 Rolldown。
+- 类型检查：继续使用 `wv prepare`、`vue-tsc`/`tsc`、ESLint 与 stylelint；`vp check` 不能替代全部小程序规则。
+- 缓存：开发服务、IDE、上传、MCP 与 runtime E2E 不应配置任务缓存。生产缓存的完整恢复与输入失效矩阵尚未验收。
+
+跟踪：[标准插件与 Vite+ 集成 #1097](https://github.com/weapp-vite/weapp-vite/issues/1097)。
+
+## 生产 watch
+
+`vite build --watch` 与 `vp build --watch` 复用生产配置，每轮通过宿主 emit/write 发布当前目标的完整产物。支持脚本、模板、样式更新，页面增删和语法错误恢复；删除页面时清理对应的已拥有产物及 sourcemap。`emptyOutDir: false` 时保留其他工具写入的文件。关闭 watcher 会等待本轮写出和会话资源释放。
+
+这一路径不提供状态保持 HMR，也不自动重启配置文件。修改 Vite 配置或配置依赖后，按宿主 build watch 的语义重新启动命令；需要配置自动重启时使用 classic `vite dev` / `vp dev`。目标能力限制与插件生产构建一致。
+
+## 实验性 stateful 开发
+
+在同一顶层配置中设置 `weapp.hmr.runtime: 'stateful-experimental'`，继续使用 `vite dev` / `vp dev`。适配器安装在宿主的 client 环境，使用其配套 Rolldown DevEngine；不会另起一个 Vite 服务。无需手工开启 `experimental.bundledDev`，但宿主必须提供所需私有 API，能力检查失败会明确报错。
+
+该模式面向微信 WebView，需开启微信开发者工具热重载。当前宿主遇到 Skyline 或缺失私有 API 时明确报错，需显式改用 classic；独立 CLI 的自动降级行为保留。JS 安全补丁、模板与样式更新复用现有 stateful 协议；页面入口拓扑变化由宿主重新创建会话，配置依赖变化由宿主重新加载配置。关闭会等待本会话拥有的任务和引擎；不会关闭其他宿主实例。
+
+普通 Vite 与 Vite+ 均已验证原生 Page/Component 脚本补丁、样式更新、模板往返及 Wevu 本地/store 状态保持，包含 headless 可观察语义与真实微信 IDE。Vite+ 验收在严格安装的独立发布包依赖图中使用原生 `vp dev`；独立 `wv` 同时通过同组 headless 与真实微信 IDE 回归。当前结果覆盖这些定向场景，完整跨平台发布矩阵仍需持续验证。
+
+middleware mode 支持构建与可等待关闭。运行小程序的 stateful 通信还需要消费方把 Vite middleware 挂载到可访问的 HTTP 服务，并配置对应端口；只创建 middleware 服务不会自动提供监听端点。
+
+## React
+
+注册同一个 `weapp()`，继续使用顶层 `weapp.react` 配置和既有 `@weapp-vite/react` 运行时。生产构建、classic、生产 watch 与实验性 stateful 共用 React 编译器；静态 TSX 在 stateful 下按既有规则重建会话，不承诺 React hooks 状态跨此类重载保持。
+
+`renderMode: 'auto'` 可组合静态 WXML、动态模板与原生/Wevu 组件 bridge；`dynamic` 仍不支持原生组件 bridge。React Compiler 继续是可选 SWC 能力，其安装与降级规则不随宿主改变。模板输出使用共享的源码根与输出路径映射，支持自定义 `srcRoot` 和符号链接项目路径。
+
+## 独立分包
+
+`app.json` 或 `app.vue` 中的 `subPackages[].independent`，以及顶层 `weapp.subPackages` 的配置沿用独立 CLI 语义。三入口共享独立子构建；子构建直接复用本次已加载的配置、CLI 覆盖与用户插件，不再次执行配置文件。
+
+每个子构建只生成内存产物，最终由主构建的 Vite/Rolldown 发布。classic、stateful 和原生生产 watch 由宿主调度子包更新，不为独立分包另外创建 watcher。生产 watch 支持独立脚本与模板依赖、语法错误恢复，以及删除分包后的陈旧产物清理。
+
+stateful 下独立分包源码由宿主 watcher 驱动完整更新批次，不承诺子包 JS 状态保持；子包的 Vue、脚本和伴随资产无需进入主 DevEngine 模块图也能触发更新。
+
+## worker
+
+沿用 `app.json` 的 `workers` 与顶层 `weapp.worker.entry`，三入口使用同一子目标编译。原生 app builder 纳入 worker 环境，子目标复用已加载的配置和用户插件，返回内存产物；最终由主应用原生 emit/write 一次发布。
+
+classic、stateful 和生产 watch 不为 worker 额外启动构建 watcher。输入归属主会话，包含 worker 依赖修改、错误恢复、新增导入以及关闭等待；从 app 配置移除 worker 后，生产 watch 清理旧输出。stateful 中 worker 变化触发完整更新，不承诺保留 worker 线程状态。
+
+## 微信插件项目
+
+三入口共用顶层 `weapp.pluginRoot` 与 `project.config.json` 的插件输出配置。生产构建通过 app builder 登记 `weapp_plugin` 环境，在主应用落盘后构建插件，复用本次已加载配置与用户转换插件。主应用、插件和插件 npm 全部完成后才报告成功。
+
+插件输出可放在主应用输出内部或同级目录，但不能等于或包含主应用输出目录。classic 与 stateful 宿主都保留独立的插件编译会话，由父会话负责关闭；插件 watcher 负责增量更新与入口拓扑重建，不承诺插件 JS 状态保持。生产 watch 支持共享依赖、编译失败恢复和插件页面移除。
+
+当前阶段不支持双产物的 `build.write: false`，会提前报错。npm 自定义回调和手工映射共用上述输出归属规则；真实插件 runtime 仍需按目标平台验收。
+
+手工 npm 关联从主 `packageJsonPath` 所在目录解析依赖，再按 Node 规则向上查找；递归依赖从所属父包解析。CLI 缓存跟踪所选 manifest 的依赖变化，回调的工程 `root` 和相对输出基准保持不变。外部父子映射迁移时，按整轮绝对文件归属差集删除旧文件，不会误删当前产物或用户文件。
+
+## 小程序组件库
+
+顶层 `weapp.lib` 直接用于 `wv build`、`vite build` 和 `vp build`。原生组件、Vue SFC、纯脚本入口及 `fileName` 输出映射沿用同一编译器，声明文件与 JS、JSON、模板和样式一起进入原生 bundle；`build.write: false` 返回包含声明的内存产物。
+
+生产 watch 追踪声明编译器发现的类型依赖，类型变更会重新生成声明。每轮声明编译使用独立 TypeScript 缓存，避免旧类型跨轮复用。classic `dev` 可用于组件库源码更新，开发模式沿用独立 CLI 不生成声明的规则；组件交互在消费它的小程序应用中验证。
+
+`vp pack` 继续使用通用库打包语义；小程序库的模板、样式、JSON 和专属声明仍通过 `weapp.lib` 构建。
+
+
+## 六平台目标选择
+
+三入口共用顶层 `weapp.platform`，可选择 `weapp`、`alipay`、`tt`、`swan`、`jd`、`xhs`。启用 `weapp.multiPlatform` 时也可通过该字段指定本次目标，独立 CLI 继续接受 `--platform`。普通 Vite/Vite+ 命令不接受 `wv` 专属的 `--platform` 参数；多目标使用不同配置文件或任务，并确保输出目录独立。
+
+```ts
+import { defineConfig } from 'vite'
+import { weapp } from 'weapp-vite/vite'
+
+export default defineConfig({
+  plugins: [weapp()],
+  weapp: {
+    platform: 'alipay',
+    srcRoot: 'src',
+    multiPlatform: true,
+    hmr: { runtime: 'classic' },
+  },
+})
+```
+
+目录式平台项目配置从 `config/<platform>/` 读取，默认发布到 `dist/<platform>/`，小程序产物位于其 `dist/` 子目录。项目配置同样通过配套原生引擎写出，生产 watch 更新并清理本会话已拥有的文件；拒绝覆盖小程序编译输出的配置目录内容。目录式配置暂不支持 `build.write: false`，内联 `multiPlatform.projectConfigs` 可随主 bundle 返回内存产物。配置目录中的符号链接尚未开放。
+
+原生 TS 和 Vue SFC 的六平台生产构建、classic 更新，以及普通 Vite/Vite+ 的生产 watch 使用同一消费矩阵。stateful 仅开放微信；其他平台明确使用 classic。微信运行时使用 headless 与真实 IDE 验收；其他平台的构建/增量检查不代表各自真实 IDE runtime 均已通过，高级能力仍按平台分别验收。
+
+
+## 纯 Web 目标
+
+三入口都可在顶层设置 `weapp.platform: 'web'`，沿用 `weapp.web` 的源码根、输出目录和 runtime 配置；未指定 `weapp.web` 时使用 Web 默认值。普通 Vite 与 Vite+ 继续注册同一个 `weapp()`，独立 `wv` 无需注册插件，也无需再传 `--platform web`。显式 CLI `--platform` 覆盖配置目标。
+
+项目需保留既有 Web `index.html`，通过 `/@weapp-vite/web/entry` 启动 runtime。纯 Web 不要求小程序 `project.config.json`，默认输出 `dist/web`，不会同时生成小程序 bundle。原生生产构建、开发服务和插件生产 watch 使用宿主生命周期；Web 的浏览器 HMR 不启用微信 stateful 引擎。
+
+生产产物与 dev 服务均使用浏览器验证 Vue SFC、原生组件语义和交互。Web 测试只证明浏览器目标，不替代六个平台真实 IDE 验收。Web/小程序混合宿主仍会明确报错，后续需独立环境隔离后再开放。

package/dist/docs/vue-sfc.md

@@ -124,6 +124,18 @@ defineOptions({ behaviors: [i18n.behavior] })
 <view class="br" />
 ```
 
+## 原生插槽与 `provide` / `inject`
+
+`weapp.vue.template.scopedSlotsRequireProps` 默认 `false`，普通插槽仍使用增强方案。设为 `true` 时，无 scoped props 的内容保留原生 `<slot>`。
+
+微信目标下，编译后的 Wevu Provider 和 Leaf 使用默认 `setupLifecycle: 'attached'` 时，`<Provider><Leaf /></Provider>` 中的 Leaf 会在 setup 前同步关联最近的插槽承载者。Leaf 的 `inject()` 能取得 Provider 提供的原始对象、ref 和方法；点击调用 action 会更新双方共享状态。具名、普通节点包裹、嵌套和多实例场景遵循同一规则，卸载重建不会沿用旧上下文。
+
+这条协议不新增包装节点，不复制注入值，不修改原生 `Component.export` / `selectOwnerComponent()`。显式 `setupLifecycle: 'created'` 或 attached 前的公开实例恢复仍按原时机执行 setup，不提供该保证；未经 Wevu 编译的原生/第三方组件也不自动成为注入承载者。
+
+内层 Wevu Provider 即使使用过滤后的 `export()` / `expose()`，其普通模板子组件（含 Options API 局部注册别名）和原生插槽子组件仍共享内层上下文；外部选择器只看到该 Provider 的公开导出，内部父链不依赖公开导出对象。
+
+已验证环境：微信 DevTools Stable `2.02.2608080`（基础库 `3.17.2`、`3.13.2`）和 `2.02.2608060`（基础库 `3.17.2`），并保留 mpcore 回归；这些结果不代替其他版本组合或真机验证。其他小程序平台及 Web 目标不启用此协议，构建时裁剪其声明属性、事件接收与清理代码，不能由微信或 headless 结果推断支持。`false` / augmented 和实际 scoped props 继续使用既有增强插槽路径。
+
 ## 具名插槽透传 wrapper
 
 当你把当前组件的 `<slot />` 转发到子组件的具名插槽时：
@@ -350,3 +362,10 @@ defineOptions({ behaviors: [i18n.behavior] })
 - 需要更完整的编辑器提示说明：[`../volar.md`](../volar.md)
 - 需要运行时页面/组件/store 约束：[`wevu-authoring.md`](./wevu-authoring.md)
 - 需要项目级 `weapp` 配置：[`weapp-config.md`](./weapp-config.md)
+
+
+## JSON 合并读取页面声明
+
+`weapp.json.mergeStrategy(target, source, ctx)` 可读取当前 SFC 页面的 `ctx.routeConfig`（`definePage` 的静态 `{ name, meta }`）和 `ctx.pageMeta`（`definePageMeta` 的完整静态对象）。元信息支持内联、外部脚本与规范导入别名，并贯穿编译阶段、`emit`、`merge-existing` 和 JSON-only HMR。
+
+可按 `typeof ctx.routeConfig?.meta?.title === 'string'` 映射 `navigationBarTitleText`。`pageMeta` 含动态变量、调用、展开或访问器时整个字段为 `undefined`；编译器不会执行表达式或返回部分对象。无声明以及非页面组件不提供这些字段。已有非法路由声明诊断保持有效。

package/dist/docs/weapp-config.md

@@ -14,6 +14,12 @@ export default defineConfig({
 })
 ```
 
+## 构建语法目标
+
+顶层 `build.target` 沿用 Vite 标准语义。若关闭 IDE 的 ES6 转 ES5 和增强编译后，真机调试上传在可选链（`?.`）处报 `Unexpected token .`，可设置 `build: { target: 'es2019' }` 并重新构建，由 Vite 降级语法。IDE 模拟器可运行不代表上传解析器支持相同语法；生成二维码也不代替目标设备上的功能验证。
+
+`build.target` 不补齐运行时 API。完整配置边界见[构建与产物配置](https://vite.weapp.dev/config/build-and-output.html)。
+
 ## 高频配置项
 
 ### `srcRoot`
@@ -24,6 +30,8 @@ export default defineConfig({
 
 适合希望用约定生成页面路由的项目。启用后要保持 pages 目录与输出约定稳定。
 
+`autoRoutes: { extensions: ['vue', 'tsx'] }` 只选择允许后缀的页面入口，声明提取、构建与增量更新使用同一选择；未配置或空数组保持原行为。`include` 仍匹配无扩展名 base。多个允许源码沿用 `ts/js/tsx/jsx/vue` 优先级；同名模板、JSON、样式和显式业务导入不会被过滤。
+
 ### `multiPlatform.projectConfigs`
 
 在一份配置中按 `weapp` / `alipay` / `tt` / `xhs` / `jd` / `swan` 提供原生项目字段，公共项用普通对象展开。没有显式 `targets` 时从映射键推导；完整示例见[上传速查](./upload.md#多平台与输出校验)。
@@ -160,6 +168,10 @@ const moduleExport = await import('../../packages/order/modules/price.ts')
 
 适合用目录扫描自动注册组件的项目。组件重名时要先解决命名冲突，不要让自动引入规则长期处于歧义状态。
 
+开发态下，目录扫描与文件监听使用一致的组件路径标识，Windows 路径分隔符不同不会形成两份注册记录。删除组件会移除注册；恢复文件或修改组件声明后，会重新判断是否满足注册条件。重建页面配置时，会重新计算自动生成的 `usingComponents`，移除失效的自动绑定，同时保留源码中显式声明的绑定。
+
+派生配置变化后，增量构建也会发布新的页面 JSON，包括清空配置时的 `{}`，不依赖变更文件是否为 JSON。
+
 ### `i18n`
 
 微信项目可以通过 `weapp.i18n` 启用由 `@weapp-vite/i18n` 提供核心语义的 locale 编译与运行时切换：
@@ -232,6 +244,8 @@ export default defineConfig({
 
 provider 的状态由 provider 自己维护，host 负责插件顺序、源码所有权冲突、依赖监听和产物生命周期。`weapp.tailwindcss` 仍然是内置 Tailwind adapter 的兼容门面；UnoCSS 等实现可以独立包的形式提供同一协议。
 
+源码转换的 `dependencies` 与该次转换内的 `context.addWatchFile(id)` 共同声明依赖；成功转换后替换该源码的依赖集合，由 Vite 的模块图传播失效。开发快照写出结束不会提前释放 controller，所属开发会话结束时只调用一次 `dispose`。状态保持 HMR 将已声明依赖的新增、修改、删除纳入冻结输入，provider 应读取 `request.sources`，不能读取后续保存的可变文件。
+
 微信状态保持 HMR 使用可选的 `controller.prepareHmr(request)` 协作：输入提供 `revision`、`changedFiles` 与固定的 `sources` 内容视图，返回本批次的 `assets`、`transformJavaScript`、依赖信息和资源释放方法。资产路径相对于输出目录；所有 Patch 共用该批次的编译状态。宿主通过 Vite/Rolldown 提交资产后才发布补丁，并在客户端执行回报后通知 DevEngine。开启 sourcemap 时，修改代码的转换必须同时返回映射。没有批次接口的内容 provider 使用完整构建回退。
 
 共享协议由实验包 `@weapp-vite/hmr` 提供，Tailwind 控制器委托 `@weapp-vite/tailwindcss` 和 `weapp-tailwindcss/core`。两个包均不创建 DevEngine、watcher 或直接写出产物，框架与宿主运行时仍由适配器拥有；现有配置和 `prepareHmr` 类型兼容。Taro 的实验适配保留其持久发布与应用确认两阶段，不改变 weapp-vite 在应用确认后通知 DevEngine 的语义。
@@ -288,6 +302,12 @@ export default defineConfig({
 
 微信构建会把 `preload` 合成为 `app.json.preloadRule`；手写的同一路由规则优先，其他平台不会生成微信专属字段。多条 glob 命中时选择具体程度最高的一条。需要检查静态跨分包跳转时，运行 `wv analyze --preload`；它只输出建议，不修改源码，并按触发页所属包汇总实际分包体积与共享的 2 MB 额度。
 
+### `wevu.preset`
+
+`weapp.wevu.preset: 'performance'` 默认开启 patch、隐藏时暂停、`setData.diagnostics: 'fallback'`、开发态高频告警和自动 `setData.pick`。`weapp.wevu.defaults` 的同名字段优先；内建诊断没有 `devOnly` 限制，可显式设为 `'off'`。
+
+首次快照收集也可能记录 `needsFullSnapshot`；阶段日志不等于独立回退或物理调用。配置覆盖与计数边界见 [`wevu-authoring.md`](./wevu-authoring.md)。
+
 ### `vue.template.htmlTagToWxml`
 
 适合从 Web/Vue 模板迁移到小程序 `.vue` 的项目。开启后，会把常见 HTML 标签映射成小程序内置标签，例如 `div -> view`、`span -> text`、`img -> image`、`a -> navigator`，也包含 `br/hr` 这类容易在迁移时“消失”的标签。
@@ -514,6 +534,10 @@ export default defineConfig({
 
 不要在 `srcRoot`、路由来源、分包边界都没确认前就先调 chunk 策略。
 
+### `web`
+
+Web 重新扫描项目期间，已扫描 Vue SFC 的模板、样式与脚本继续使用上一次成功扫描的完整快照。扫描成功后才切换到新版本；扫描失败会保留旧快照并报告错误，修复后可继续更新。同一文件的正斜杠与反斜杠路径共用缓存，不会混入尚未发布的磁盘内容。
+
 ### `hmr.runtime`
 
 默认值为 `auto`。微信项目会在 `wv dev` 启动时根据开发者工具设置自动选择 HMR 运行时，也可显式锁定状态保持型热更新：
@@ -530,6 +554,16 @@ export default defineConfig({
 
 安全的 JavaScript/Vue 更新会保留当前 Page/Component 实例、route/query、输入和可序列化 data/setup ref，并替换原生 Page、原生 Component 与 wevu 方法。CSS、资源、JSON/配置、不兼容模块图或补丁失败会回退完整构建与当前路由重载。
 
+入口拓扑更新先验证完整快照，再把仍符合源目录和声明依赖内容版本的快照一次性交给新宿主，避免重复编译。输入变化、依赖覆盖不足或固定输入批次无法验证时重新构建；快照失败时保留旧宿主，修复尚未进入旧图的新文件也能触发重试。会话关闭会取消未交接的候选。
+
+Vue `<style module>` 会生成脚本中的类名映射，因此其内容、模块名称、`src` 及块增删都按脚本与样式共同更新处理，避免后续补丁引用未交付的样式模块。独立的普通 `<style>` 变化仍按纯样式处理；产物更新和真实 DevTools 已应用计算样式需要分别验收。
+
+样式合并按真实文件身份判断所有权：已由模块图处理的样式，即使又通过符号链接、目录连接或 Windows 路径别名被发现，也不会作为独立原生样式重复读取并合并。固定输入批次保持该批次的样式内容，不混入同一文件较新的磁盘保存；真正独立的原生同名样式仍参与输出，移除显式样式导入后仍保留原生样式回退。
+
+回退时，同一输出当前收集到的多个 sidecar 按收集顺序合并后一次发布，不会相互覆盖；指向同一真实文件的重复路径只保留一份。常规 HMR 更新按完整合并内容去重，而不是分别缓存每个片段。
+
+上述保证不涵盖原生样式文件删除事件对历史登记集合的清理；本次修复没有验证或改变该上游生命周期。
+
 `auto` 在 `project.private.config.json` 的 `setting.compileHotReLoad` 严格为 `true` 时选择 `stateful-experimental`，否则选择 `classic`；非微信平台也会回退到 `classic`。该判断只在启动时执行，修改开发者工具设置后需要重启 `wv dev`。启动日志会以 `HMR 模式` 和 `HMR 切换` 两行显示最终模式、选择来源，以及通过 DevTools 热重载开关或 `weapp.hmr.runtime` 切换模式的方法。显式配置通常优先，但 Skyline 兼容降级不受显式配置覆盖。
 
 状态保持模式目前只支持微信小程序 WebView，需要微信开发者工具开启服务端口和热重载。微信开发者工具暂不支持 Skyline 热重载；首次编译检测到任意生成的应用或页面 JSON 使用 `renderer: 'skyline'` 时，`wv dev` 会输出带官方兼容文档链接的警告，将当前项目私有配置中的 `setting.compileHotReLoad` 持久化为 `false`，并强制使用 `classic`，包括显式配置 `stateful-experimental` 的场景。其他私有配置字段不会改变，切回 WebView 后也不会自动重新开启热重载。需要既有写盘/刷新行为时显式配置 `classic`。
@@ -557,6 +591,10 @@ export default defineConfig({
 
 - `logLevel: 'default' | 'concise' | 'verbose'` 控制终端诊断详细程度。
 - `profileJson: boolean | string` 控制是否输出 JSONL profile，字符串表示自定义输出路径。
+- JSONL v1 保留旧字段，增加 `sessionId` / `buildId` / `batchId` / `sourceEvents` 与时钟来源；按来源精确匹配编辑。失败记录只有 `elapsedMs`；无受影响入口的批次以 `incomplete` / `reason: no-affected-entries` 结束观测，不污染后续构建。未知版本、未完成或缺失阶段不能按零耗时统计。`buildCoreMs` 是残差估算，阶段可能重叠。
+- `analyze --hmr-profile --json` 的 `inputCoverage` 提供输入覆盖计数；旧版无版本记录仍兼容，未关联样本不归给当前编辑。
+- stateful JSONL 以 `pipeline: 'stateful'` 区分，记录源通知到批次接收、准备、提交等待、提交及发布阶段。`completionBoundary` 区分客户端交付确认与产物发布；缺失来源、失败或取消不能计为成功耗时。`timelines` 只累加互不重叠的外层时段，未知阶段及负残差保持 `null`，不把嵌套 hook 重复累加。
+- 模板 benchmark 的预算使用外部 `wallMs`，缺失 profile 不再填充 `totalMs`。仓库 `verify:edit-sequence --engine weapp-classic|weapp-stateful` 默认以 512 个真实 SFC 页面比较长期编译宿主和逐步新进程基线，同时记录进程树 RSS、强制 GC 后 heap、GC 开销及资源/转换范围。完整页面 JS 由 mpcore 执行，此结果不能替代真实 IDE 验收；profile 开关语义与开销比较入口为 `scripts/editSequence/compareProfiles.ts`。
 
 ### `mcp`
 
@@ -875,3 +913,19 @@ export default defineConfig({
 `wxml-policy.json` 例如 `["debug-panel"]`。同一文件跨模板或阶段登记会去重；修改、删除、恢复触发完整模板重建与校验。局部构建保留未触及模板的依赖，成功完整构建清理失效登记。不要监听输出目录，也不要把一次读取的结果永久缓存而忽略规则更新。
 
 “最终”指框架管理的输出链完成后的模板，不保证覆盖任意排在该阶段之后的第三方 Vite 插件修改。不保证跨文件／分包回调顺序，不追踪任意文件读取、环境变量或网络响应；第一版不提供内置业务规则、跨文件全局校验、独立 CLI 或报告文件，也不能替代宿主完整语法和运行时检查。
+
+## Analyze 产物消费与预算
+
+小程序 `wv analyze --json --budget-check` 输出 schema v2 的 `artifacts.files`、`build` 与 `budgetChecks`，日志进入 stderr。每个物理文件保留路径、包归属、字节和 SHA-256；runtime 依据模块所属包分类，不依赖 chunk 名称。分包复制的 JS asset 仍保留原模块来源。
+
+`weapp.analyze.budgets.runtimeBytes` 限制包含 runtime 模块的文件字节上界（包含混合 chunk 的业务部分）；`packageBytes` 按分包 root 覆盖单包预算，主包键为 `__main__`。超限或缺少归因时 `--budget-check` 返回非零。
+
+`estimatedBytes` 是按打包器长度分摊的模块估算，`unattributedBytes` 显式保留未知部分。单份共享文件计一次，真正的分包副本分别计入总包；runtime 和重复模块估算不能再加到总包上。旧的无版本报告仍保留兼容读取，但不能作为新 runtime 预算通过证据。
+
+## 构建目录与外部缓存
+
+默认清理策略适合构建器独占的输出目录。共享目录使用 `build.emptyOutDir: false` 时，构建上下文只清理它已登记的旧产物，不能删除新进程开始前由其他工具或外部缓存写入的未知文件。
+
+推荐 dev 输出到独立目录，Turbo 只缓存生产目录，dev 任务设置 `cache: false`、`persistent: true`。必须共用目录时，由缓存集成持久记录成功构建的 emitted 文件清单与内容摘要，恢复及清理仅针对该任务拥有的文件；用户改写或同名冲突必须保留并报告。不要把无条件清空输出目录加入 HMR 兜底逻辑。最终构建产物仍由 Vite/Rolldown emit/write 持久化。
+
+仓库组合回归入口为 `pnpm verify:edit-sequence --engine weapp-modes --require-clean --report .tmp/output-mode-sequence.json`，运行前重建 weapp-vite。它逐步比较模式切换、组件/页面/分包拓扑变化和旧缓存恢复后的完整生产文件，与独立进程基线按字节核对；共享目录额外检查用户文件保护。此项不是真实 IDE runtime 验收。

package/dist/docs/wevu-authoring.md

@@ -37,6 +37,16 @@ else if (import.meta.env.PLATFORM === 'web') {
 
 这类写法通常会导致时序错误或生命周期不触发。
 
+## performance 预设与 setData 诊断
+
+`weapp.wevu.preset: 'performance'` 为 app/component 注入 `setData.strategy: 'patch'`、`suspendWhenHidden: true`、`diagnostics: 'fallback'` 和开发态 `highFrequencyWarning`，并默认启用 `autoSetDataPick`。`weapp.wevu.defaults` 的同名字段覆盖预设；`autoSetDataPick` 的显式布尔值也优先。
+
+内建 `diagnostics` 默认关闭，预设开启后没有 `devOnly` 限制，生产构建也可能输出日志。将 app/component 的 `setData.diagnostics` 设为 `'off'` 只关闭内建日志，自定义 `debug` 回调仍有效。
+
+`needsFullSnapshot` 可能来自 patch 首次收集快照、变更路径无法定位，或此前提交失败后的恢复。首次收集仍可只下发差异，单条 reason 不证明失败或完整 payload；恢复须结合 `commitFailure`、revision 和成功结算判断。
+
+显式开启 `debugPhases: true` 后，同一 revision 会增加 prepare、dispatch、commit 记录，内建日志也会打印这些记录。按同一会话内的 `(phase.observerId, revision)` 关联更新，按 `phase.dispatch.id` 去重调用；将初始化与计时区间分开，不能从 warning 条数推导回退率或预设收益。宿主 heap 缺失时保留未完成的内存验收，不用 Node worker RSS 替代。
+
 ## 事件与双向绑定
 
 复杂表单或可复用字段组件优先使用 `bindModel` / `useBindModel`，不要让事件细节分散在大量不一致的自定义协议里。

package/dist/doctor-worker.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/doctor-worker.mjs

@@ -0,0 +1,59 @@
+import { t as createCompilerContext } from "./createContext-BqYzHhY9.mjs";
+import { r as resolveAnalyzeBudgets, t as terminateStaleSassEmbeddedProcess } from "./processCleanup-B6KA30Zc.mjs";
+import { r as readDoctorFiles } from "./files-BqxFIPRp.mjs";
+import process from "node:process";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+//#region src/doctor/buildWorker.ts
+process.once("message", async (options) => {
+	try {
+		const outputRoot = path.join(options.cwd, ".weapp-vite", "doctor", options.target, randomUUID());
+		const limitations = /* @__PURE__ */ new Set();
+		const ctx = await createCompilerContext({
+			cwd: options.cwd,
+			configFile: options.configFile,
+			cliPlatform: options.target,
+			isDev: false,
+			mode: "production",
+			outputRoot,
+			inlineConfig: {
+				build: {
+					outDir: outputRoot,
+					emptyOutDir: true
+				},
+				plugins: [{
+					name: "weapp-vite-doctor-output-scope",
+					enforce: "post",
+					writeBundle(output) {
+						const relative = path.relative(outputRoot, path.resolve(output.dir ?? path.dirname(output.file ?? outputRoot)));
+						if (relative.startsWith("..") || path.isAbsolute(relative)) limitations.add("构建器输出包含快照根目录外的路径；不能证明产物覆盖完整。");
+					}
+				}]
+			},
+			syncSupportFiles: false,
+			preloadAppEntry: false,
+			emitDefaultAutoImportOutputs: false
+		});
+		if (path.resolve(ctx.configService.outDir) !== outputRoot || ctx.configService.platform !== options.target) throw new Error("实际编译目标或产物目录与 Doctor 请求不一致");
+		await ctx.buildService.build();
+		if (ctx.configService.weappViteConfig.npm?.buildOptions) limitations.add("自定义 npm.buildOptions 可改变输出目录；当前快照不证明目录外 npm 产物完整。");
+		const snapshot = {
+			files: await readDoctorFiles(outputRoot),
+			origin: "build",
+			freshness: "current-build",
+			capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			budgets: resolveAnalyzeBudgets(ctx.configService),
+			sourceRoot: path.relative(options.cwd, ctx.configService.absoluteSrcRoot).split(path.sep).join("/"),
+			outputRoot: path.relative(options.cwd, outputRoot).split(path.sep).join("/"),
+			limitations: [...limitations]
+		};
+		terminateStaleSassEmbeddedProcess();
+		process.send?.({ snapshot }, () => process.exit(0));
+	} catch (error) {
+		process.stderr.write(`${error instanceof Error ? error.stack : String(error)}\n`);
+		terminateStaleSassEmbeddedProcess();
+		process.exit(2);
+	}
+});
+//#endregion
+export {};

package/dist/doctor.d.mts

@@ -0,0 +1,144 @@
+import { Xn as MpPlatform } from "./config-V0L-IAJf.mjs";
+import { i as AnalyzeBudgetConfig } from "./budget-BD7VqLCl.mjs";
+import { OperationDiagnostics } from "@weapp-vite/miniprogram-automator";
+//#region src/doctor/types.d.ts
+type DoctorLayer = 'project' | 'source' | 'artifact' | 'runtime';
+interface DoctorCoverage {
+  target: string;
+  layer: DoctorLayer;
+  check: string;
+  status: 'complete' | 'incomplete' | 'not-requested';
+  reason?: string;
+}
+interface DoctorDiagnostic {
+  ruleId: string;
+  target: string;
+  layer: DoctorLayer;
+  severity: 'error' | 'warning';
+  message: string;
+  location?: {
+    file: string;
+    line?: number;
+    column?: number;
+  };
+  evidence: {
+    expected: string;
+    actual: string;
+  };
+  responsibility: {
+    owner: 'project' | 'framework' | 'platform' | 'unknown';
+    confidence: 'confirmed' | 'suspected';
+  };
+  suggestion: string;
+  fingerprint: string;
+}
+interface DoctorFile {
+  path: string;
+  size: number;
+  sha256: string;
+  text?: string;
+}
+interface DoctorArtifactSnapshot {
+  files: readonly DoctorFile[];
+  origin: 'build' | 'existing';
+  capturedAt: string;
+  /** 既有目录只证明当前字节，不证明来自当前源码。 */
+  freshness: 'current-build' | 'unverified';
+  budgets?: AnalyzeBudgetConfig;
+  /** 相对项目目录的实际编译源码目录。 */
+  sourceRoot?: string;
+  /** 相对项目目录的本轮输出目录。 */
+  outputRoot?: string;
+  limitations?: readonly string[];
+}
+interface DoctorRuntimeEvidence {
+  host: string;
+  deviceSystem?: string;
+  route: string;
+  provider: string;
+  checks: readonly string[];
+  /** false 表示已有部分事实，但请求的运行时探针没有全部完成。 */
+  complete?: boolean;
+  facts?: readonly DoctorRuntimeFact[];
+  bundle?: DoctorRuntimeBundle;
+}
+type DoctorRuntimeStage = 'cli-executable' | 'service-listener' | 'login-query' | 'login-state' | 'project-connection' | 'tool-info' | 'host-version' | 'sdk-version' | 'current-page' | 'session-release';
+interface DoctorRuntimeFact {
+  stage: DoctorRuntimeStage;
+  status: 'passed' | 'failed' | 'unknown' | 'not-run';
+  code: string;
+}
+interface DoctorRuntimeProbeOptions {
+  /** 所有已请求探针的总预算，包含本次连接清理。 */
+  timeout?: number;
+  signal?: AbortSignal;
+  /** 只读检查的显式 CLI；仅 login 为 true 时执行原生查询。 */
+  cliPath?: string;
+  /** 显式允许原生 islogin，可能启动 IDE，必须同时指定 cliPath。 */
+  login?: boolean;
+  /** 只检查指定回环 TCP 端口，不据此认定监听者是微信 IDE。 */
+  servicePort?: number;
+}
+interface DoctorRuntimeBundle {
+  /** 仅含固定阶段、预算与资源类别，不包含原始错误文本。 */
+  operation?: OperationDiagnostics;
+  frameworkVersion: string;
+  nodeVersion: string;
+  versions: {
+    ide?: string;
+    sdk?: string;
+  };
+  configuration: {
+    target: string;
+    provider: string;
+    explicitCli: boolean;
+    explicitAutomatorPort: boolean;
+    explicitServicePort: boolean;
+    loginRequested: boolean;
+  };
+  lastSuccessfulStage?: DoctorRuntimeStage;
+  /** 只记录固定阶段与分类，不包含宿主原始输出、凭据或源码。 */
+  events: readonly DoctorRuntimeFact[];
+  reproduction: string;
+}
+interface DoctorReport {
+  schemaVersion: 1;
+  generatedAt: string;
+  targets: string[];
+  coverage: DoctorCoverage[];
+  diagnostics: DoctorDiagnostic[];
+  artifacts: Record<string, Omit<DoctorArtifactSnapshot, 'files'> & {
+    files: Array<Omit<DoctorFile, 'text'>>;
+  }>;
+  runtime: Record<string, DoctorRuntimeEvidence>;
+  exitCode: 0 | 1 | 2;
+}
+interface DoctorOptions {
+  cwd?: string;
+  targets?: readonly string[];
+  /** 静态检查的显式源码目录；不执行配置推断。 */
+  source?: string;
+  artifact?: string;
+  build?: boolean;
+  runtime?: boolean;
+  /** 连接已有 automator 会话的端口；省略时使用项目派生端口。 */
+  runtimePort?: number;
+  runtimeCliPath?: string;
+  runtimeLogin?: boolean;
+  runtimeServicePort?: number;
+  configFile?: string;
+  onBuildLog?: (text: string) => void;
+}
+interface DoctorAdapters {
+  build: (options: DoctorOptions, target: MpPlatform) => Promise<DoctorArtifactSnapshot>;
+  runtime: (cwd: string, target: MpPlatform, port?: number, options?: DoctorRuntimeProbeOptions) => Promise<DoctorRuntimeEvidence>;
+}
+//#endregion
+//#region src/doctor/report.d.ts
+export declare function formatDoctorReport(report: DoctorReport, format?: 'terminal' | 'json' | 'sarif'): string;
+//#endregion
+//#region src/doctor/index.d.ts
+/** 分层收集事实；静态路径永不调用配置加载器、构建或宿主连接。 */
+export declare function runDoctor(options?: DoctorOptions, adapters?: Partial<DoctorAdapters>): Promise<DoctorReport>;
+//#endregion
+export type { DoctorAdapters, DoctorArtifactSnapshot, DoctorCoverage, DoctorDiagnostic, DoctorFile, DoctorLayer, DoctorOptions, DoctorReport, DoctorRuntimeBundle, DoctorRuntimeEvidence, DoctorRuntimeFact, DoctorRuntimeProbeOptions, DoctorRuntimeStage };