Skip to content

feat: yazi-style File Browser with async live preview#20

Draft
rrbe wants to merge 1 commit into
masterfrom
feat/file-browser
Draft

feat: yazi-style File Browser with async live preview#20
rrbe wants to merge 1 commit into
masterfrom
feat/file-browser

Conversation

@rrbe
Copy link
Copy Markdown
Owner

@rrbe rrbe commented Jun 1, 2026

这是什么

termdown <dir> 进入 File Browser(仿 yazi):左侧列出目录里的 Markdown 文件,右侧实时预览高亮的文件,按 Enter 提交进全屏阅读器。

┌ Files ─────┬─────────────────────────┐
│ > start.md │   ▒▒ Getting Started ▒▒  │
│   arch.md  │   body text…            │
│   api/     │   (大标题图片实时渲染)   │
└────────────┴─────────────────────────┘
 j/k 移动 · Enter 打开 · q 退出

设计决策(grilling 结论)

  • 形态:左侧文件面板 + 右侧预览共存(不是全屏选择器,也不是 miller 三栏)。
  • 交互:yazi 式——面板持有焦点,移动光标即实时预览,Enter 提交。
  • 性能:预览构建放到后台 worker 线程,主循环永不阻塞;去抖 ~120ms、合并积压请求;用 generation 号作废划走后的过期结果;构建期间显示 ⟳ 加载中… 且不放图片。
  • 历史:提交(Enter)才压入现有 o/i 历史栈,等同跟随链接;划过的预览是临时的,不进历史。
  • 图片回收:划过某文件后用 d=I 释放其缓存图片数据,避免长时间浏览在终端里攒下孤儿 PNG。
  • 术语CONTEXT.md 钉死 File Browser(文件系统) vs Contents/ToC(标题大纲),消除「目录」一词歧义。

⚠️ Known issues(先记着,后面再改)

  • 按 Enter 提交进入全屏阅读器后,渲染有多个问题待排查修复。 本 PR 暂为 draft,主要验证浏览/实时预览这条链路;阅读器侧的问题在后续提交里处理。

故意留到后续(HALF 2,见 TODO.md)

  • 阅读器内按键唤回浏览器(提交后目前回不去)
  • 子目录进入 / 递归、隐藏文件、.gitignore
  • 构建缓存(path+mtime,重访秒开)
  • File Browser 与 ToC 面板共存规则
  • 预览态可滚动 / 更轻的「安静模式」纯文本预览

测试

  • make check 全绿(fmt-check + clippy -D warnings + 全部测试)。
  • 新增单测:browser::is_markdownkitty::forget_frees_data_and_drops_tracking
  • 交互部分(实时预览流畅度、卡顿)在 Ghostty 手动验证;非 TTY 路径优雅降级。

🤖 Generated with Claude Code

`termdown <dir>` opens a File Browser: a left panel lists Markdown
files, the right pane live-previews the highlighted file, and Enter
commits it to the full-screen reader.

- Live preview is built off-thread (PreviewWorker) so the event loop
  never blocks on heading-image rasterization; cursor moves stay
  instant. Builds are debounced (~120ms settle) and coalesced, and a
  generation counter discards results whose selection has moved on.
- While a build is in flight the pane shows a spinner and places no
  images (no stale art).
- Committing pushes onto the existing o/i history stack like a followed
  link; ephemeral previews never enter history.
- Ephemeral preview image data is reclaimed (`d=I`) when the user
  scrolls past a file, so a long browse session doesn't accumulate
  orphaned PNGs in the terminal.
- CONTEXT.md pins the "File Browser" (filesystem) vs "Contents/ToC"
  (headings) terminology to avoid the 目录 collision.

Known issue (tracked in TODO.md): after Enter, the full-screen reader
path has several rendering problems still to be fixed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant