feat: markdown preview with mermaid diagram rendering (v0.7.0)

Press "p" to toggle between raw diff and rendered markdown preview for .md files.
Works from both sidebar and diff pane focus.

Markdown rendering (via pulldown-cmark):
- Headings (H1-H6) with color-coded bold text
- Tables with box-drawing characters (┌┬┐│┼├┤└┴┘)
- Fenced code blocks with language labels
- Ordered/unordered lists with nesting
- Inline formatting (bold, italic, strikethrough, inline code)
- Links, blockquotes, horizontal rules, task lists

Mermaid diagram rendering:
- Auto-detects terminal: iTerm2, Kitty, Ghostty → inline images via native
  protocol (OSC 1337 / Kitty graphics); tmux/screen → styled source fallback
- Async mmdc subprocess with 15s timeout and blake3 content-hash caching
  in .git/semantic-diff-cache/mermaid/ (skip re-render if unchanged)
- Images scale to diff pane width with aspect-ratio-correct height
- Stale images cleared on file switch (terminal.clear + immediate redraw)
- Graceful degradation: no mmdc → styled source code, no images

UI changes:
- Footer shows Raw/Preview mode indicator
- Help overlay includes "p" shortcut
- Preview scroll: j/k/g/G/Ctrl-d/u navigate within preview content

Also:
- Removed cmux hook script and Claude Code integration setup
  (cmux now uses socket-based control)
- Updated README: removed cmux setup section, added markdown preview
  and mermaid features, updated keybindings and requirements
- 11 new E2E tests for preview mode

New dependencies: pulldown-cmark, blake3, image, base64

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Alan Shum

.claude/hooks.example/refresh-semantic-diff.sh

@@ -1,2 +1,3 @@
 target/
 ai-plans/
+.claude/logs/

.gitignore

@@ -2,7 +2,7 @@
 
 ## What This Is
 
-A Rust terminal application (built with ratatui) that displays git diffs in a rich, collapsible, semantically-grouped view. Runs as a cmux split pane triggered by Claude Code hooks, giving real-time visibility into what files Claude is changing and why — grouped by meaning, not just by file path. Published on crates.io and Homebrew.
+A Rust terminal application (built with ratatui) that displays git diffs in a rich, collapsible, semantically-grouped view. Triggered by Claude Code hooks, giving real-time visibility into what files Claude is changing and why — grouped by meaning, not just by file path. Published on crates.io and Homebrew.
 
 ## Core Value
 
@@ -23,7 +23,6 @@ Show Claude's code changes in real-time with AI-powered semantic grouping, so th
 - ✓ AI semantic grouping via Claude CLI with progressive enhancement — v0.2.3
 - ✓ Collapsible semantic group tree nodes with summaries — v0.2.3
 - ✓ SIGUSR1-triggered refresh from Claude Code hooks — v0.2.3
-- ✓ cmux auto-split pane lifecycle — v0.2.3
 - ✓ PID file management (/tmp/semantic-diff.pid) — v0.2.3
 - ✓ PostToolUse hook for Edit/Write tools — v0.2.3
 - ✓ Panic hook terminal restoration — v0.2.3
@@ -35,15 +34,13 @@ Show Claude's code changes in real-time with AI-powered semantic grouping, so th
 
 ### Active
 
-- [ ] Security audit: command injection in shell invocations (git diff, claude CLI)
-- [ ] Security audit: signal handling race conditions (SIGUSR1, PID file)
-- [ ] Security audit: LLM output parsing safety (untrusted Claude CLI JSON)
-- [ ] Security audit: file path traversal and symlink safety in diff parsing
-- [ ] Fix all identified security vulnerabilities
-- [ ] E2E test: live diff rendering (syntax highlighting, line numbers, word-level diff)
-- [ ] E2E test: real-time refresh via Claude Code hooks in cmux pane
-- [ ] E2E test: semantic grouping (AI clustering, sidebar, progressive enhancement)
-- [ ] E2E test: graceful edge cases (empty repos, huge diffs, binary files, no clauded)
+- [ ] "p" key toggles between raw diff and rendered markdown preview for .md files
+- [ ] Preview mode renders markdown (headings, tables, links, lists) via mdcat
+- [ ] Preview mode renders mermaid diagrams via mmdc → PNG → Kitty graphics protocol
+- [ ] Mermaid image caching: content-hash mermaid code blocks, reuse PNG if unchanged
+- [ ] Cache directory gitignored
+- [ ] Footer displays current mode (Raw / Preview)
+- [ ] Shortcut menu updated with "p" key
 
 ### Out of Scope
 
@@ -59,15 +56,15 @@ Show Claude's code changes in real-time with AI-powered semantic grouping, so th
 Shipped MVP with 3,050 LOC Rust across 3 phases in 3 days.
 Tech stack: Rust, ratatui, syntect, tokio, tui-tree-widget.
 Latest release: v0.3.0 on crates.io and Homebrew.
-User runs Claude Code in cmux terminal multiplexer on macOS.
+User runs Claude Code in a terminal on macOS.
 No existing terminal tool combines collapse/expand with AI-driven semantic grouping.
 
 ## Constraints
 
 - **Tech stack**: Rust with ratatui — single binary, fast startup
 - **LLM integration**: Claude CLI (clauded) — no external API keys
 - **Refresh model**: Hook-triggered only (PostToolUse on Edit/Write)
-- **Platform**: macOS with cmux
+- **Platform**: macOS
 - **Performance**: Diff parsing <100ms; LLM grouping async (progressive enhancement)
 
 ## Key Decisions
@@ -78,14 +75,25 @@ No existing terminal tool combines collapse/expand with AI-driven semantic group
 | clauded for semantic grouping | No permission prompts, local daemon, no API key management | ✓ Good |
 | Hook-triggered refresh over file watch | Less CPU, integrates naturally with Claude Code workflow | ✓ Good |
 | Async semantic grouping | Show diff immediately, regroup when LLM responds — no blocking | ✓ Good |
-| cmux right-split pane | Natural side-by-side with Claude Code conversation on the left | ✓ Good |
 | 3-phase quick depth | Diff viewer first, then hooks, then semantic grouping — each builds on prior | ✓ Good |
 | tui-tree-widget for sidebar | Purpose-built tree rendering, less custom code than manual approach | ✓ Good |
 
+## Current Milestone: v0.7.0 Markdown Preview
+
+**Goal:** Add a toggle preview mode for .md files that renders markdown and mermaid diagrams inline in the diff pane.
+
+**Target features:**
+- "p" key toggle between raw diff and rendered preview
+- Markdown rendering via mdcat (headings, tables, links, lists, code blocks)
+- Mermaid diagram rendering via mmdc → PNG → Kitty graphics protocol
+- Content-hashed mermaid caching (skip re-render if code unchanged)
+- Footer mode indicator (Raw / Preview)
+- Updated shortcut menu
+
 ## Completed Milestones
 
 1. **MVP** (v0.1.0–v0.2.3) — Diff viewer, hook integration, semantic grouping
 2. **Security & Demo Readiness** (v0.3.0) — Red/purple/blue team audit, hardening, E2E tests
 
 ---
-*Last updated: 2026-03-15 after v0.3.0 release*
+*Last updated: 2026-03-16 after v0.7.0 milestone start*

.planning/PROJECT.md

@@ -0,0 +1,94 @@
+# Requirements: Semantic Diff TUI
+
+**Defined:** 2026-03-16
+**Core Value:** Show Claude's code changes in real-time with AI-powered semantic grouping, so the user always knows what's being changed and can mentally track the work without leaving the terminal.
+
+## v0.7.0 Requirements
+
+Requirements for markdown preview milestone. Each maps to roadmap phases.
+
+### Preview Toggle
+
+- [x] **PREV-01**: User can press "p" to toggle between raw diff and rendered preview mode
+- [x] **PREV-02**: Toggle is global -- all .md files switch mode together
+- [x] **PREV-03**: Toggle is no-op when viewing non-.md files
+- [x] **PREV-04**: Footer displays current mode indicator (Raw / Preview)
+- [x] **PREV-05**: Shortcut menu updated to show "p" key binding
+- [x] **PREV-06**: Scroll position preserved across mode toggles
+
+### Markdown Rendering
+
+- [x] **MKDN-01**: Preview renders headings with visual weight (size/bold/color differentiation)
+- [x] **MKDN-02**: Preview renders tables with aligned columns
+- [x] **MKDN-03**: Preview renders fenced code blocks with syntax highlighting
+- [x] **MKDN-04**: Preview renders ordered and unordered lists
+- [x] **MKDN-05**: Preview renders inline formatting (bold, italic, inline code)
+- [x] **MKDN-06**: Preview renders links with visible URLs
+- [x] **MKDN-07**: Preview renders blockquotes with visual distinction
+- [x] **MKDN-08**: Preview shows post-change file content (reads from working tree)
+
+### Mermaid Diagrams
+
+- [x] **MERM-01**: Mermaid fenced code blocks extracted and identified from markdown
+- [x] **MERM-02**: Mermaid code rendered to PNG via mmdc subprocess (async, non-blocking)
+- [x] **MERM-03**: Rendered PNG displayed inline via Kitty graphics protocol (ratatui-image)
+- [x] **MERM-04**: Placeholder text shown while mermaid diagram is rendering
+- [x] **MERM-05**: Content-hash caching via blake3 -- skip re-render if mermaid code unchanged
+- [x] **MERM-06**: Cache stored in .git/semantic-diff-cache/mermaid/
+- [x] **MERM-07**: Graceful degradation when mmdc not installed -- show styled mermaid source
+- [x] **MERM-08**: Three-tier terminal support: Kitty images, halfblock fallback, code block fallback
+
+## Future Requirements
+
+### Preview Enhancements
+
+- **PREV-F01**: Per-file mode memory (remember raw/preview per file)
+- **PREV-F02**: Side-by-side raw + preview split view
+- **PREV-F03**: Preview for other file types (JSON, YAML, TOML)
+
+## Out of Scope
+
+| Feature | Reason |
+|---------|--------|
+| Side-by-side raw+preview | Diff pane too narrow for split view |
+| Diff-within-preview | Too complex -- preview shows post-change content only |
+| Generic image rendering | Only mermaid diagrams, not arbitrary images in markdown |
+| Edit/write in preview mode | Read-only viewer |
+| mdcat integration | mdcat archived Jan 2025; using pulldown-cmark instead |
+
+## Traceability
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| PREV-01 | Phase 7 | Complete |
+| PREV-02 | Phase 7 | Complete |
+| PREV-03 | Phase 7 | Complete |
+| PREV-04 | Phase 7 | Complete |
+| PREV-05 | Phase 7 | Complete |
+| PREV-06 | Phase 7 | Complete |
+| MKDN-01 | Phase 7 | Complete |
+| MKDN-02 | Phase 7 | Complete |
+| MKDN-03 | Phase 7 | Complete |
+| MKDN-04 | Phase 7 | Complete |
+| MKDN-05 | Phase 7 | Complete |
+| MKDN-06 | Phase 7 | Complete |
+| MKDN-07 | Phase 7 | Complete |
+| MKDN-08 | Phase 7 | Complete |
+| MERM-01 | Phase 8 | Complete |
+| MERM-02 | Phase 8 | Complete |
+| MERM-03 | Phase 8 | Complete |
+| MERM-04 | Phase 8 | Complete |
+| MERM-05 | Phase 8 | Complete |
+| MERM-06 | Phase 8 | Complete |
+| MERM-07 | Phase 9 | Complete |
+| MERM-08 | Phase 9 | Complete |
+
+**Coverage:**
+- v0.7.0 requirements: 22 total
+- Mapped to phases: 22
+- Complete: 22
+- Unmapped: 0
+
+---
+*Requirements defined: 2026-03-16*
+*Last updated: 2026-03-16 after all phases complete*

.planning/REQUIREMENTS.md

@@ -4,6 +4,7 @@
 
 - ✅ **Milestone 1: MVP** -- Phases 1-3 (shipped 2026-03-15, v0.1.0-v0.2.3)
 - ✅ **Milestone 2: Security & Demo Readiness** -- Phases 4-6 (shipped 2026-03-15, v0.3.0)
+- ✅ **v0.7.0: Markdown Preview** -- Phases 7-9 (shipped 2026-03-16)
 
 ## Phases
 
@@ -29,8 +30,52 @@ Full details: `milestones/v1.1-ROADMAP.md`
 
 </details>
 
+### ✅ v0.7.0: Markdown Preview (Shipped 2026-03-16)
+
+**Milestone Goal:** Add a toggle preview mode for .md files that renders markdown and mermaid diagrams inline in the diff pane.
+
+- [x] **Phase 7: Core Markdown Preview** - Toggle between raw diff and rendered markdown for .md files
+- [x] **Phase 8: Mermaid Diagram Rendering** - Inline mermaid diagrams via mmdc with content-hash caching
+- [x] **Phase 9: Graceful Degradation** - Terminal tier fallback and missing-tool resilience
+
+## Phase Details
+
+### Phase 7: Core Markdown Preview
+**Goal**: Users can toggle .md files between raw diff and a rendered markdown preview showing headings, tables, code blocks, lists, and formatting
+**Depends on**: Phase 6 (existing codebase)
+**Requirements**: PREV-01, PREV-02, PREV-03, PREV-04, PREV-05, PREV-06, MKDN-01, MKDN-02, MKDN-03, MKDN-04, MKDN-05, MKDN-06, MKDN-07, MKDN-08
+**Success Criteria** (what must be TRUE):
+  1. User presses "p" and the diff pane switches from raw diff to rendered markdown showing formatted headings, tables, lists, code blocks, links, and blockquotes
+  2. User presses "p" again and returns to the raw diff view with scroll position preserved
+  3. User navigates to a non-.md file and "p" does nothing (no error, no mode change)
+  4. Footer shows "Raw" or "Preview" to indicate current mode, and shortcut menu includes the "p" key
+  5. Preview displays the post-change working-tree version of the file (not the diff)
+**Plans**: TBD
+
+### Phase 8: Mermaid Diagram Rendering
+**Goal**: Mermaid code blocks in markdown files render as inline images in the preview pane, with caching so repeat views are instant
+**Depends on**: Phase 7
+**Requirements**: MERM-01, MERM-02, MERM-03, MERM-04, MERM-05, MERM-06
+**Success Criteria** (what must be TRUE):
+  1. User views a .md file with mermaid code blocks in preview mode and sees rendered diagram images inline where the code blocks were
+  2. User sees "[Rendering diagram...]" placeholder text immediately, replaced by the rendered image when mmdc completes (UI never blocks)
+  3. User views the same file again and diagrams appear instantly from cache (no mmdc re-invocation for unchanged mermaid code)
+  4. Cache directory exists under .git/semantic-diff-cache/mermaid/ and does not pollute the working tree
+**Plans**: TBD
+
+### Phase 9: Graceful Degradation
+**Goal**: Preview mode works gracefully across all terminal capabilities and when external tools are missing
+**Depends on**: Phase 8
+**Requirements**: MERM-07, MERM-08
+**Success Criteria** (what must be TRUE):
+  1. User without mmdc installed sees styled mermaid source code in place of diagrams (no errors, no blank space)
+  2. User in a terminal without Kitty graphics support sees mermaid diagrams as halfblock fallback or styled code block fallback, depending on terminal capability
+**Plans**: TBD
+
 ## Progress
 
+**Execution Order:** 7 → 8 → 9
+
 | Phase | Milestone | Plans Complete | Status | Completed |
 |-------|-----------|----------------|--------|-----------|
 | 1. Diff Viewer | MVP | 3/3 | Complete | 2026-03-13 |
@@ -39,3 +84,6 @@ Full details: `milestones/v1.1-ROADMAP.md`
 | 4. Red Team Audit | Security | 2/2 | Complete | 2026-03-15 |
 | 5. Purple Team Hardening | Security | 4/4 | Complete | 2026-03-15 |
 | 6. Blue Team E2E Testing | Security | 3/3 | Complete | 2026-03-15 |
+| 7. Core Markdown Preview | v0.7.0 | 1/1 | Complete | 2026-03-16 |
+| 8. Mermaid Diagram Rendering | v0.7.0 | 1/1 | Complete | 2026-03-16 |
+| 9. Graceful Degradation | v0.7.0 | 1/1 | Complete | 2026-03-16 |