SATCN v0.4.0 - Diff Viewer Release

🎉 SATCN v0.4.0 - Diff Viewer Release

Release Date: October 31, 2025
Codename: Visual Corrections

🌟 Headline Feature: Interactive Diff Viewer

SATCN v0.4.0 introduces a comprehensive diff viewer system that lets you visually review all corrections made by the pipeline before accepting them. No more blind trust—see exactly what changed and why!

---

✨ New Features

📊 Success Dialog with Statistics

• Professional modal dialog appears after pipeline completion
• Shows detailed correction statistics:
  • Number of corrections made
  • Processing time
  • Input/output file sizes
  • Estimated breakdown of changes (grammar, spelling, punctuation)
• Three action buttons:
  • View Full Diff - Launch the detailed diff viewer
  • Open Output - Open corrected file in your default editor
  • Close - Dismiss and continue
• Keyboard shortcuts: Enter (view diff), Esc (close)

🔍 GitHub-Style Diff Viewer

• Side-by-side comparison of original vs. corrected text
• Color-coded changes:
  • Red highlighting for removed/original text
  • Green highlighting for added/corrected text
• Paragraph-level diffing with word-level precision
• Navigation controls:
  • Previous/Next buttons to jump between changes
  • Arrow key navigation (↑/↓ or ←/→)
  • Esc to close
• Export functionality: Save diff to text file for documentation
• Scrollable interface handles documents of any length
• Multiple diff viewers can be open simultaneously

🏗️ Foundation Components

• DiffEngine: Paragraph-level text diffing with word-level highlights
  • Optimized for SATCN's chunking architecture
  • Uses Python's difflib.SequenceMatcher for efficient comparison
  • Handles complex formatting and special characters
• CorrectionStats: Pipeline statistics extraction and formatting
  • Parses pipeline output for meaningful metrics
  • Human-readable size formatting (bytes → KB → MB)
  • Smart change categorization

---

🛠️ Improvements

GUI Enhancements

• Compact Layout Optimization (from previous sprint):
  • No-scroll design—everything fits on screen
  • Tighter spacing without sacrificing readability
  • Professional CustomTkinter dark theme throughout
• Better Error Handling:
  • Graceful fallbacks when features fail
  • Enhanced error messages with full tracebacks
  • Non-blocking warnings for non-critical issues

Architecture Improvements

• Robust Type Handling:
  • Handles both dict and string returns from PipelineRunner
  • Extracts output_filepath with intelligent fallbacks
  • Backward compatible with older pipeline versions
• Modal Dialog System:
  • Dialogs don't block main GUI
  • Proper focus management
  • Professional window positioning

---

🐛 Bug Fixes

• Critical Fix: Success dialog now appears correctly after pipeline completion
  • Issue: PipelineRunner returned dict instead of string path
  • Solution: Extract output_filepath from result dict with fallback logic
• Path Handling: Convert Path objects to strings before os.startfile() calls
• Stats Creation: Graceful fallback when statistics extraction fails
• Type Safety: Tuple type checking for backward compatibility

---

🧪 Testing

• 29 new unit tests (100% pass rate):
  • 13 tests for DiffEngine
  • 16 tests for CorrectionStats
• Interactive test suite for visual component verification
• Full integration testing with real documents and GRMR-V3 corrections
• Real-world validation with 15K+ word documents

---

📦 What's Included

New Files:

• diff_engine.py - Core diffing logic
• correction_stats.py - Statistics parser
• success_dialog.py - Success modal dialog
• diff_viewer.py - Main diff viewer window
• test_diff_engine.py - DiffEngine tests
• test_correction_stats.py - CorrectionStats tests
• test_diff_viewer_components.py - Interactive test suite

Documentation:

• DIFF_VIEWER_DESIGN.md - Architecture and design decisions
• DIFF_VIEWER_PROGRESS.md - Development progress tracker
• GUI_COMPACT_LAYOUT.md - GUI optimization notes
• SPRINT3_TESTING_SUMMARY.md - Testing checklist and results

---

🚀 How to Use

1. Run your pipeline as usual (CLI or GUI)
2. Wait for completion - processing happens in background
3. Success dialog appears showing correction statistics
4. Click "View Full Diff" to see detailed changes
5. Navigate through changes using Previous/Next or arrow keys
6. Export diff (optional) to save for your records
7. Open output file when satisfied with corrections

---

📊 Statistics

• Total Changes: 2,913 insertions, 180 deletions across 14 files
• New Components: 4 core modules, 2 test suites, 4 documentation files
• Test Coverage: 29 new unit tests, all passing
• Development Sprints: 3 (Foundation → GUI → Polish)

---

🔧 Technical Details

Dependencies:

• CustomTkinter 5.2.2 (GUI framework)
• Python 3.11+ (or 3.13 for CPU-only)
• All existing SATCN dependencies

Compatibility:

• ✅ Works with GRMR-V3 (GPU/CPU)
• ✅ Works with T5 transformer mode
• ✅ Works with LanguageTool fallback
• ✅ Supports both Markdown and EPUB formats
• ✅ Windows 10/11 (primary), Linux compatible

---

🎯 Use Cases

• Quality Assurance: Review corrections before accepting them
• Learning Tool: See how GRMR-V3 improves your writing
• Documentation: Export diffs for proofreading records
• Debugging: Verify pipeline behavior on edge cases
• Confidence Building: Trust but verify the AI's corrections

---

🙏 Acknowledgments

This release represents a major UX improvement, making SATCN more transparent and trustworthy for preprocessing manuscripts and novels before TTS playback.

---

📝 Upgrade Notes

From v0.3.x:

• No breaking changes
• Existing CLI workflows unchanged
• GUI automatically includes new diff viewer
• No additional dependencies required (if GUI extras already installed)

Installation:

pip install -e ".[gui]"  # Includes all diff viewer dependencies

---

🐛 Known Issues

• Deep Markdown nesting (e.g., **bold _italic_ bold**) may have formatting quirks (existing limitation)
• EPUB processing only handles <p> tags currently (existing limitation)
• Diff viewer requires CustomTkinter (GUI-only feature)

---

🔮 What's Next?

Future enhancements being considered:

• Inline editing from diff viewer
• Accept/reject individual changes
• Side-by-side view mode option
• Syntax highlighting for Markdown
• EPUB diff support with HTML preservation

---

Full Changelog: v0.3.0...v0.4.0

Download: SATCN v0.4.0

---

v0.3.0

Modern CustomTkinter UI with dark mode
Complete grammar engine selection:
LanguageTool (rule-based)
GRMR-V3 GGUF (GPU, recommended)
T5 Transformer (experimental)
None (skip grammar correction)
Contextual mode dropdown (enabled only for GRMR-V3/T5)
File selector with format validation (.txt, .md, .epub)
File statistics display (size, word count, estimated processing time)
Pipeline options (fail-fast checkbox)
Grayed-out advanced settings placeholder (for future features)
Threaded processing with progress bar
Real-time output log with auto-scroll
Config persistence (saves to ~/.config/satcn/gui_config.json)
Entry point command: satcn-gui or python -m satcn.gui.satcn_gui
📁 Files Created
satcn_gui.py (563 lines) - Main GUI application
config.py (162 lines) - Configuration state management
init.py - Package init
Updated pyproject.toml with CustomTkinter dependency and satcn-gui entry point
🎨 Design Highlights
MVC-inspired architecture: Config state separated from UI
Responsive layout: Grid-based with proper weight distribution
Progressive disclosure: Advanced settings grayed out, mode dropdown contextually enabled
Non-blocking: Threading prevents UI freeze during processing
Persistent preferences: Remembers last file and settings

v0.2.0

What's Changed

• Add GUI utility for testing SATCN pipeline by @hebbihebb in #15
• Test gui by @hebbihebb in #16
• Add GUI session logging and runtime tracking by @hebbihebb in #17
• Add GRMR-V3 GGUF integration plan and smoke test harness by @hebbihebb in #18
• Fix README formatting duplication by @hebbihebb in #19

Full Changelog: v0.1.0...v0.2.0

v0.1.0 – Initial Prototype

What's Changed

• Add FLAN-T5 grammar correction integration by @hebbihebb in #11
• Integrate FLAN-T5 Grammar Correction (GPU-accelerated) – Confirmed Working, Formatting Guardrails Needed by @hebbihebb in #12
• Integrate T5 text correction into SATCN pipeline by @hebbihebb in #13
• Revise README for T5 pipeline rollout by @hebbihebb in #14

Full Changelog: https://github.com/hebbihebb/SATCN/commits/v0.1.0