Merge pull request #96 from ynqa/feat/terminal-session

Add configurable terminal session lifecycle management

Author: ynqa

Cargo.toml

@@ -12,13 +12,13 @@ members = [
 [workspace.dependencies]
 anyhow = "1.0.102"
 async-trait = "0.1.89"
+bitflags = "2.9.0"
 crossbeam-skiplist = "0.1.3"
 crossterm = { version = "0.29.0", features = ["use-dev-tty", "event-stream", "serde"] }
 csv = "1.3.1"
 futures = "0.3.32"
 radix_trie = "0.3.0"
 rayon = "1.11.0"
-scopeguard = "1.2.0"
 serde = "1.0.228"
 serde_json = { version = "1.0.149", features = ["preserve_order"] }
 serde_yaml = "0.9.34"

Concept.md

@@ -42,9 +42,10 @@ promkit is organized around four responsibilities with clear boundaries:
 1. **Prompt lifecycle runtime (`promkit`)**
    - [`Prompt`](./promkit/src/runtime.rs) defines lifecycle hooks:
      `initialize -> evaluate -> finalize`
-   - [`Prompt::run`](./promkit/src/runtime.rs) manages terminal setup/teardown
-     (raw mode, cursor visibility) and drives input events from a singleton
-     `EVENT_STREAM`.
+   - [`Prompt::run`](./promkit/src/runtime.rs) drives input events from a
+     singleton `EVENT_STREAM`.
+   - `TerminalSession` manages opt-in terminal setup/teardown separately from
+     the prompt lifecycle.
    - Events are processed sequentially.
 
 2. **Application event policy (`examples` and downstream applications)**
@@ -83,7 +84,8 @@ promkit is organized around four responsibilities with clear boundaries:
      after layout is complete.
 
 This keeps responsibilities explicit:
-- runtime = lifecycle and terminal event stream
+- runtime = prompt lifecycle and terminal event stream
+- terminal session = terminal mode lifecycle
 - application prompt = event and focus policy
 - widgets = state to graphemes
 - core renderer = terminal output

examples/async_task/Cargo.toml

@@ -8,6 +8,7 @@ publish = false
 promkit = { path = "../../promkit", features = [
     "runtime",
     "spinner",
+    "terminal-session",
     "texteditor",
 ] }
 tokio = { workspace = true }

examples/async_task/src/async_task.rs

@@ -27,7 +27,7 @@ use promkit::{
         spinner::{self, State},
         text_editor,
     },
-    Prompt, Signal,
+    Prompt, Signal, TerminalModes, TerminalSession,
 };
 use tokio::{
     sync::{mpsc, RwLock},
@@ -427,5 +427,8 @@ impl AsyncTaskPrompt {
 
 #[tokio::main]
 async fn main() -> anyhow::Result<()> {
+    let modes =
+        TerminalModes::RAW_MODE | TerminalModes::HIDDEN_CURSOR | TerminalModes::MOUSE_CAPTURE;
+    let _terminal_session = TerminalSession::try_new(modes)?;
     AsyncTaskPrompt::try_default().await?.spawn().await
 }

examples/checkbox/Cargo.toml

@@ -6,7 +6,7 @@ publish = false
 
 [dependencies]
 anyhow = { workspace = true }
-promkit = { path = "../../promkit", features = ["runtime", "checkbox", "text"] }
+promkit = { path = "../../promkit", features = ["runtime", "terminal-session", "checkbox", "text"] }
 tokio = { workspace = true }
 
 [[bin]]

examples/checkbox/src/checkbox.rs

@@ -14,7 +14,7 @@ use promkit::{
         checkbox::{self, Checkbox, CheckboxHit},
         text::{self, Text},
     },
-    Prompt, Signal,
+    Prompt, Signal, TerminalModes, TerminalSession,
 };
 
 #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
@@ -185,20 +185,25 @@ impl Prompt for CheckboxPrompt {
 
 #[tokio::main]
 async fn main() -> anyhow::Result<()> {
-    let ret = CheckboxPrompt::new([
-        "Apple",
-        "Banana",
-        "Orange",
-        "Mango",
-        "Strawberry",
-        "Pineapple",
-        "Grape",
-        "Watermelon",
-        "Kiwi",
-        "Pear",
-    ])
-    .run()
-    .await?;
+    let ret = {
+        let modes =
+            TerminalModes::RAW_MODE | TerminalModes::HIDDEN_CURSOR | TerminalModes::MOUSE_CAPTURE;
+        let _terminal_session = TerminalSession::try_new(modes)?;
+        CheckboxPrompt::new([
+            "Apple",
+            "Banana",
+            "Orange",
+            "Mango",
+            "Strawberry",
+            "Pineapple",
+            "Grape",
+            "Watermelon",
+            "Kiwi",
+            "Pear",
+        ])
+        .run()
+        .await?
+    };
     println!("result: {:?}", ret);
     Ok(())
 }

examples/confirm/Cargo.toml

@@ -6,7 +6,7 @@ publish = false
 
 [dependencies]
 anyhow = { workspace = true }
-promkit = { path = "../../promkit", features = ["runtime", "validate"] }
+promkit = { path = "../../promkit", features = ["runtime", "terminal-session", "validate"] }
 readline-example = { package = "readline", path = "../readline" }
 tokio = { workspace = true }
 

examples/confirm/src/confirm.rs

@@ -1,4 +1,4 @@
-use promkit::{validate::ValidatorManager, Prompt};
+use promkit::{validate::ValidatorManager, Prompt, TerminalModes, TerminalSession};
 use readline_example::Readline;
 
 #[tokio::main]
@@ -10,7 +10,12 @@ async fn main() -> anyhow::Result<()> {
         |_| "Please type 'y' or 'n' as an answer".into(),
     ));
 
-    let ret = prompt.run().await?;
+    let ret = {
+        let modes =
+            TerminalModes::RAW_MODE | TerminalModes::HIDDEN_CURSOR | TerminalModes::MOUSE_CAPTURE;
+        let _terminal_session = TerminalSession::try_new(modes)?;
+        prompt.run().await?
+    };
     println!("result: {:?}", ret);
     Ok(())
 }

examples/csv/Cargo.toml

@@ -7,7 +7,7 @@ publish = false
 [dependencies]
 anyhow = { workspace = true }
 clap = { version = "4.5.60", features = ["derive"] }
-promkit = { path = "../../promkit", features = ["runtime", "table"] }
+promkit = { path = "../../promkit", features = ["runtime", "terminal-session", "table"] }
 tokio = { workspace = true }
 
 [[bin]]

examples/csv/src/csv.rs

@@ -5,16 +5,16 @@ use promkit::{
     core::{
         crossterm::{
             event::{
-                self, Event, KeyCode, KeyEvent, KeyEventKind, KeyEventState, KeyModifiers,
-                MouseEvent, MouseEventKind,
+                Event, KeyCode, KeyEvent, KeyEventKind, KeyEventState, KeyModifiers, MouseEvent,
+                MouseEventKind,
             },
-            execute, terminal,
+            terminal,
         },
         render::{Renderer, SharedRenderer},
         Widget,
     },
     widgets::table::{CsvOptions, Document, State},
-    Prompt, Signal,
+    Prompt, Signal, TerminalModes, TerminalSession,
 };
 
 /// Interactive CSV viewer powered by promkit.
@@ -202,30 +202,16 @@ fn parse_document(args: &Args) -> anyhow::Result<Document> {
     }
 }
 
-/// Ensure the terminal is restored to its original state when dropped.
-struct TerminalGuard;
-
-impl Drop for TerminalGuard {
-    fn drop(&mut self) {
-        let _ = execute!(
-            io::stdout(),
-            terminal::LeaveAlternateScreen,
-            event::DisableMouseCapture
-        );
-    }
-}
-
 #[tokio::main]
 async fn main() -> anyhow::Result<()> {
     let args = Args::parse();
     let document = parse_document(&args)?;
 
-    execute!(
-        io::stdout(),
-        terminal::EnterAlternateScreen,
-        event::EnableMouseCapture
-    )?;
-    let _terminal_guard = TerminalGuard;
+    let modes = TerminalModes::RAW_MODE
+        | TerminalModes::ALTERNATE_SCREEN
+        | TerminalModes::HIDDEN_CURSOR
+        | TerminalModes::MOUSE_CAPTURE;
+    let _terminal_session = TerminalSession::try_new(modes)?;
 
     CsvViewer::new(document).run().await
 }