Vite renderer 开发

命令

npm ci
npm run dev

• dev 先执行现有增量构建，再启动 Vite 8.3.4 和 Electron。
• 开发服务仅监听 127.0.0.1，使用自动分配的端口。
• 保存 renderer 源码后由 Vite 按需转译，不需要重新运行完整构建。
• Vite 保存时不执行完整类型检查；提交前仍需运行 npm run typecheck。
• 修改主进程、preload、开发工具配置或依赖后，退出应用并重新运行 npm run dev。
• 关闭 Electron 后自动关闭开发服务；终端中断通过父子进程 IPC 请求正常退出，使用既有恢复稿保存流程。
• npm start 继续复用静态构建，不启用开发服务器。
• npm run build:dev 仍只执行增量构建。
• 完整构建、生产打包和静态页面加载链路保留，Vite 仅作为开发依赖。

ESM 模块结构

• 主窗口、片段窗口、Quick Cmd Form 和发布渲染页均通过模块脚本加载。
• Renderer 源码使用 .mts，静态构建输出 .mjs。
• renderer/dependencies.mts 显式导出共用工具和 UI 对象，并在入口调用时挂载对话框及界面。
• renderer/runtime/state.mts 为每个窗口提供一个有类型的共享状态对象。
  • 各模块通过对象属性读写同一份状态，不复制可变值。
  • 状态字段由初始化函数按原有顺序填充；模块求值期间不读取尚未初始化的字段。
• renderer.mts 显式导入并按依赖顺序调用业务模块的初始化函数；当前入口及覆盖检查分别见 src/renderer.mts 和 test/module-extraction.test.ts。
  • 函数和共享类型通过命名导入连接，不再依赖全局词法变量或动态 classic script 加载。
  • 事件注册和状态初始化只在启动时执行一次。
  • 加载状态与异步笔记库恢复完成信号继续供自动化和开发刷新使用。
• 日志序列化由 shared/log-values.mts 共用；已启用日志的页面入口先安装日志镜像，再初始化业务。
• 主进程与 preload 保留现有模块制和权限接口，发布渲染页的受控窗口函数继续提供给导出流程。
• 完整构建清理旧的 .js runtime、日志和 Quick Cmd Form 产物。迁移后重新构建并重启 Electron；开发模式重新运行 npm run dev。

热更新边界

原地更新，保留编辑器实例

• CSS 使用 Vite 热更新。
• 无状态 ESM 函数模块使用稳定的转发函数接受 HMR。
  • 已被其他模块或共享运行时捕获的函数引用继续调用新的实现。
  • 模块只允许函数、导入和无初始化求值的常量。
  • 可变状态、对象或数组缓存、类、回调工厂及初始化副作用不进入此边界。
• renderer/runtime/**/*.mts 中的业务函数修改使用 ESM 稳定转发函数热替换。
  • 热替换只执行函数实现赋值，不重复执行变量初始化和事件注册。
  • 修改导入、函数签名、初始化函数、函数之外的代码，或增加和删除函数时改用安全刷新。
  • Vite 在重新求值之前检查该边界，避免先替换部分实现再发现需要刷新。
• 原地更新保留未保存内容、标签、CodeMirror 实例、选区、滚动位置及撤销历史。
• 更新函数后，在下一次调用该函数时使用新实现；已经生成的静态 DOM 不会自动重绘。

安全刷新，恢复窗口内容

• 初始化代码、状态类、模块导出结构、回调工厂和 HTML 修改可能需要刷新。
• 主笔记窗口先等待初始化完成，再保存恢复稿和当前窗口的 sessionStorage 快照。
  • 快照包含未命名笔记、标签、未保存内容、活动标签及选区/视图状态。
  • 当前笔记库通过现有受控 API 恢复。
  • 恢复成功后才删除快照。
• 打开的对话框关闭前推迟刷新，避免打断录音或丢弃对话框草稿。
• 恢复稿写入失败或快照超过存储配额时取消刷新，显示应用内提示并保留当前编辑器。
• 刷新会重建编辑器，因此不保留撤销历史或临时对话框状态。
• 代码片段和 Quick Cmd Form 页面也连接 Vite；焦点位于可编辑控件或对话框打开时推迟页面刷新。
  • 这两个辅助窗口没有主笔记窗口的完整快照恢复能力。

Electron 加载与安全边界

• Electron 开发入口是 scripts/dev-electron.mts；生产主入口不变。
• 页面仍通过 file:// 加载，保持本地图片、音频、日志和麦克风权限的原有 URL 校验。
• 仅将开发页面 HTML 中的脚本和样式指向回环开发服务。
• CSP 仅增加当前开发服务的 HTTP/WebSocket 地址，没有启用 unsafe-eval 或关闭 webSecurity。
• 保留 contextIsolation: true、sandbox: true 和 nodeIntegration: false。
• 开发专用 preload 仅提供刷新请求；主进程验证发送者是已知开发页面的主帧后才刷新。
• 原有生产 preload 和 Markdown API 不增加开发权限。
• .mjs 导入在开发模式下解析到维护的 .mts 源码；业务初始化仍按原有顺序执行。
• 开发模式将编辑器 bundle 的导入解析到维护的 CodeMirror 源码入口，适配器修改也参与安全刷新。
• ignore 浏览器包装复用 .build 产物；生产编辑器打包和许可证生成链路保留。

验证

npm run typecheck
npm run lint
npm run test:dev

• test/renderer-hmr.test.mts 验证稳定函数引用、ESM 共享状态、初始化只执行一次、安全模块边界和开发 CSP。
• test/renderer-access.test.ts 验证测试访问使用真实 ESM 状态，保留局部变量遮蔽和对象属性含义。
• Electron 场景夹具显式导入 runtime 导出；内联断言由测试专用适配器连接相同模块，不向生产页面恢复旧全局变量。
• test:dev 使用独立用户数据目录和临时探针文件，运行真实 Electron 窗口。
  • 验证 ESM、共享运行时和 CSS 更新。
  • 验证编辑器实例、选区、撤销历史保持不变。
  • 验证恢复写入失败时取消刷新，以及安全刷新后恢复未保存内容和选区。
  • 探针通过独占创建，结束时清理，不修改已有 renderer 文件。
• npm test 包含该开发模式冒烟测试。
• 迁移前 Windows 基线：类型检查、lint、684 项单元测试、完整构建回归和 Vite Electron 冒烟测试通过。
• ESM 迁移的 Windows 验证：687 项单元测试、42 项 Electron 冒烟、Vite HMR、构建回归和目录包检查通过；详情见测试结果。
• 未验证 macOS/Linux 真机、真实麦克风设备和发布安装包。
• 参考：Vite HMR API、Electron protocol。