本地目录树与滚动稳定性

文档归档

原 D:\github\md\mds\Vex 中的九篇入门文档及 assets/logo.png 已迁入仓库 docs，相对 Markdown 和图片链接检查通过。README 新增入门入口，文档中的仓库结构及换机说明一并更新。用户配置、个人笔记和发行密钥仍不属于这些学习资料。

打开文件与目录树

• 打开有真实路径的文件时，自动枚举其所在目录及子目录，保留树形层级。
• 已在当前树内的文件不重置根目录，不重复枚举；未打开的文件只枚举路径，不预读正文。
• 从其他目录的已打开文件切回时恢复相应目录树，保留内存修改与撤销历史，不重读磁盘覆盖编辑。
• 正文解析完成即可激活，目录扫描不作为正文显示的前提。晚返回的扫描、手动选择新目录、新建草稿和工作区关闭均有请求有效性保护。
• 枚举失败不妨碍读取已选文件。手机系统选择器只有缓存副本时不扫描缓存目录，仍需用户授权可访问的文件夹。

回归覆盖真实临时目录、层级与空目录、树形缩进与折叠、切回其他根目录、单文件选择器、无路径副本、扫描竞争、权限失败和释放后的请求完成。

“文字跳出来”的原因

这不是正文入场效果，也不主要是磁盘慢。用户明确反馈场景是滚动或章节跳转，检查中复现了两类问题：

1. 章节定位原先先跳到估算位置附近，再用 200 毫秒动画持续重新计算目标。高低不一的块导致章节已经可见后仍继续移动。新增逐帧测试在旧逻辑下失败。
2. Windows 原生截图中，远处阅读块的标题已绘出，部分正文区域仍空白。旧正文和代码采用逐段 SelectableText，每段都有编辑型内部视口；改为直接绘制文本并由 Flutter SelectionArea 处理选择后，此场景恢复正常。

修改后的行为

验证方法

测试源码：

• apps/vex/test/file_open_workflow_test.dart
• apps/vex/test/workspace_sidebar_test.dart
• apps/vex/test/render_stability_test.dart
• apps/vex/integration_test/render_stability_test.dart
• packages/vex_editor/test/list_navigation_test.dart
• packages/vex_editor/test/reader_selection_test.dart

使用 220 节、变长正文、列表和代码块，分别检查 1024 / 390 逻辑像素宽度、明暗主题、即时编辑 / 阅读，共八种组合。多次远近跳转及正反向滚动后逐帧断言文字位置；同时确认正文未被修改、没有撤销记录、构建量受视口与缓存约束。

Windows 原生集成测试额外采集到达帧和 256 毫秒后的帧，检查正文区域的实际像素而不只检查 Widget 是否存在：正文必须确实绘出，前后内容像素必须一致。比较排除右侧 16 像素滚动条区域；虚拟列表测量屏外内容时，滚动条滑块仍可能有少量估算修正，不能将其称为全窗口像素不变。

本轮应用 197 项测试、编辑器 203 项测试与 Windows 原生集成测试通过。原生验证包含上述八种组合及带代码块的远处章节；首帧正文非空与前后内容像素一致的断言通过，并人工抽查手机宽度正文和代码截图。

Set-Location apps/vex
flutter test --no-pub test/render_stability_test.dart
$env:VEX_CAPTURE_DIR = 'D:\temp\vex-scroll-captures'
flutter test --no-pub -d windows integration_test/render_stability_test.dart

本机截图与日志保留在仓库外的 D:\github\temp_files\vex-experience-review\native-scroll-stability-final 及 D:\github\temp_files\vex-native-scroll-stability-final.log。这些是可重新生成的验证产物，不提交进 Git。

边界

此处的手机检查是 Windows 原生窗口中的手机宽度模拟，不替代 Android / iOS 真机验证。网络图片和本地图片解码仍可能异步完成，本轮没有宣称所有媒体加载都与纯文字一样零延迟，也没有全量预解码图片增加低配电脑负担。超大文件仍保留隔离解析与虚拟列表，未据此宣称任意设备或任意文档都无卡顿。