feat: add --watch live-reload preview for the TUI

CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+- **Live reload (`--watch` / `-w`).** `termdown --watch FILE` watches the file
+  and re-renders the TUI preview whenever it changes on disk — built for a
+  two-pane "edit on one side, preview on the other" workflow. Scroll position,
+  Table-of-Contents and metadata fold state, and any active search are
+  preserved across reloads, and a `[watch]` marker shows in the status bar.
+  Editor atomic saves (write-temp-then-rename) are handled by watching the
+  parent directory. Also configurable via `watch = true` in
+  `~/.config/termdown/config.toml` (default off; TUI only).
+- **Heading-image cache.** Rasterized H1–H3 heading PNGs are memoized by
+  `(level, theme, text)`, so a live reload re-rasterizes only headings whose
+  text actually changed — a body-only edit re-renders near-instantly.
+
 ## [0.6.1] - 2026-06-08
 
 ### Fixed

Cargo.toml

@@ -27,6 +27,7 @@ base64 = "0.22"
 crossterm = "0.28"
 font-kit = "0.14"
 image = { version = "0.25", default-features = false, features = ["png"] }
+notify = "8"
 pulldown-cmark = "0.13"
 ratatui = "0.29"
 rayon = "1"

README.md

@@ -101,6 +101,9 @@ cat notes.md | termdown
 # Pick a theme; show help
 termdown --theme light README.md
 termdown --help
+
+# Live preview: re-render on every save (edit in your editor, watch here)
+termdown --watch notes.md
 ```
 
 The full CLI reference, TUI key bindings, configuration, and known issues live in the **[Usage Guide](docs/USAGE.md)**. Configuration is optional and lives at `~/.config/termdown/config.toml` -- see [`config.example.toml`](config.example.toml) for every default.

README_CN.md

@@ -95,6 +95,9 @@ cat notes.md | termdown
 # 指定主题；查看帮助
 termdown --theme light README.md
 termdown --help
+
+# 实时预览：保存即重新渲染（在编辑器里改，在这里看）
+termdown --watch notes.md
 ```
 
 完整的命令行参数、TUI 快捷键、配置项和已知问题都在 **[使用指南](docs/USAGE_CN.md)**。配置是可选的，位于 `~/.config/termdown/config.toml` —— 全部默认值见 [`config.example.toml`](config.example.toml)。

config.example.toml

@@ -24,6 +24,11 @@ bell = true
 # (it is still parsed, so it never leaks into body content).
 metadata = true
 
+# Watch the file and live-reload the preview when it changes on disk. Default
+# false. Useful for "edit in your editor, preview in termdown" side by side.
+# Only applies to the interactive TUI. CLI override: --watch / -w.
+watch = false
+
 [font.heading]
 # Fonts for image-rendered headings (H1–H3). When unset, termdown uses
 # platform defaults and falls back to an embedded SourceSerif4 font. Body

docs/USAGE.md

@@ -15,6 +15,7 @@ termdown [OPTIONS] [FILE]
 | `--cat` | Force non-interactive cat-style output (pipe-friendly). |
 | `--theme <auto\|dark\|light>` | Color theme. Default `auto` detects the terminal background via OSC 11. |
 | `--no-bell` | Disable the edge-scroll terminal bell (also `bell = false` in config). |
+| `-w`, `--watch` | Watch the file and live-reload the TUI on save (also `watch = true` in config). TUI only. |
 | `-h`, `--help` | Show help. |
 | `-V`, `--version` | Show version. |
 
@@ -41,13 +42,27 @@ termdown --theme light README.md
 
 # Disable the edge-scroll bell
 termdown --no-bell README.md
+
+# Live preview: edit in your editor, watch it re-render on save
+termdown --watch notes.md
 ```
 
 ## TUI mode
 
 The TUI launches automatically whenever you pass a file and stdout is a real
 terminal. It requires a file path; stdin input is not supported.
 
+### Live reload (`--watch`)
+
+`termdown --watch FILE` re-renders the preview whenever the file changes on
+disk — ideal for a two-pane workflow: edit the Markdown in your editor (e.g.
+vim) on one side, keep `termdown --watch` open on the other. Scroll position,
+the open/closed Table of Contents, the metadata fold state, and any active
+search are preserved across reloads. A `[watch]` marker appears in the status
+bar. Editor atomic saves (write-temp-then-rename) are handled. Rasterized
+headings are cached, so a save that only touches body text re-renders almost
+instantly; only headings whose text actually changed are re-rasterized.
+
 | Key | Action |
 |---|---|
 | `j` / `↓` | Scroll down one line |
@@ -91,6 +106,10 @@ bell = true
 # into body content).
 metadata = true
 
+# Watch the file and live-reload the preview on save. Default false. TUI only.
+# CLI: `--watch` / `-w`.
+watch = false
+
 [font.heading]
 # English heading font (sans-serif recommended)
 latin = "Inter"