feat(01-02): implement terminal init/restore and panic hook

- init_terminal() enables raw mode and clears main screen via Viewport::Fullscreen
- No alternate screen buffer used (deliberate BBS immersive approach)
- restore_terminal() disables raw mode and shows cursor using let _ for all calls
- install_panic_hook() restores terminal, prints BBS-themed message, delegates to original hook
- Use ratatui::crossterm re-export (crossterm is transitive dep only)
- All panic hook operations use let _ or eprintln! — no unwrap() or ? inside hook

src/terminal.rs

@@ -0,0 +1,93 @@
+//! Terminal initialization, restoration, and panic hook for bbs-md.
+//!
+//! # Design
+//!
+//! This module uses the main screen buffer (no alternate screen) for the immersive BBS feel.
+//! On exit, TUI output remains visible in the terminal scroll history — the user can scroll
+//! up to review what they read, and the goodbye message persists after the process exits.
+//!
+//! # Broken Pipe Safety (LIFE-04)
+//!
+//! All write operations in the TUI must use `let _ =` or handle `ErrorKind::BrokenPipe`.
+//! SSH connections can close mid-write; Rust propagates this as `ErrorKind::BrokenPipe`.
+//! The actual enforcement happens in the event loop (Plan 03), but `restore_terminal()`
+//! already follows this pattern with `let _ =` on every call.
+//!
+//! # Important
+//!
+//! Do NOT call `ratatui::restore()` — it enters alternate screen via `LeaveAlternateScreen`,
+//! which we never entered. Use `restore_terminal()` from this module instead.
+
+use std::io::stdout;
+use ratatui::crossterm::{
+    execute,
+    terminal::{enable_raw_mode, disable_raw_mode, Clear, ClearType},
+    cursor::{MoveTo, Show},
+};
+use ratatui::{backend::CrosstermBackend, Terminal, TerminalOptions, Viewport};
+
+/// Type alias for the terminal used throughout the application.
+pub type Term = Terminal<CrosstermBackend<std::io::Stdout>>;
+
+/// Initialize the terminal on the main screen buffer with raw mode enabled.
+///
+/// This does NOT enter the alternate screen buffer. Instead it clears the main screen
+/// so the TUI occupies the user's actual terminal. On exit, TUI output remains in
+/// scroll history.
+///
+/// # Errors
+///
+/// Returns an error if raw mode cannot be enabled or if the screen cannot be cleared.
+pub fn init_terminal() -> std::io::Result<Term> {
+    enable_raw_mode()?;
+    execute!(stdout(), Clear(ClearType::All), MoveTo(0, 0))?;
+    let backend = CrosstermBackend::new(stdout());
+    Terminal::with_options(backend, TerminalOptions {
+        viewport: Viewport::Fullscreen,
+    })
+}
+
+/// Restore the terminal to a usable state.
+///
+/// Disables raw mode and shows the cursor. Every operation uses `let _ =` to suppress
+/// errors — this function is called from cleanup paths including the panic hook, where
+/// panicking would hide the original error.
+///
+/// Do NOT call `ratatui::restore()` — it unconditionally calls `LeaveAlternateScreen`,
+/// which corrupts the terminal since we never entered the alternate screen.
+pub fn restore_terminal() {
+    let _ = disable_raw_mode();
+    let _ = execute!(std::io::stdout(), Show);
+}
+
+/// Install the custom panic hook with BBS-friendly user messaging.
+///
+/// The hook:
+/// 1. Restores the terminal (disables raw mode, shows cursor)
+/// 2. Prints a friendly BBS-themed message to stderr (visible to the user)
+/// 3. Delegates to the original panic hook for technical details (captured by systemd/SSH log)
+///
+/// Install this before terminal initialization so any panic during init also triggers cleanup.
+pub fn install_panic_hook() {
+    let original_hook = std::panic::take_hook();
+    std::panic::set_hook(Box::new(move |panic_info| {
+        // Restore terminal — use let _ to avoid double-panic if cleanup itself fails
+        let _ = ratatui::crossterm::terminal::disable_raw_mode();
+        let _ = ratatui::crossterm::execute!(
+            std::io::stdout(),
+            ratatui::crossterm::cursor::Show
+        );
+
+        // Friendly message visible to the user in their terminal.
+        // Use \r\n because we may still be in raw mode if disable_raw_mode failed.
+        eprintln!("\r\n+----------------------------------------------+");
+        eprintln!("| SYSTEM ERROR: An unexpected fault occurred.  |");
+        eprintln!("| The BBS has exited safely.                   |");
+        eprintln!("| SysOp has been notified.                     |");
+        eprintln!("+----------------------------------------------+\r");
+
+        // Delegate to the original hook — prints backtrace to stderr,
+        // captured by journald or available in the SSH session log.
+        original_hook(panic_info);
+    }));
+}