termpulse/lib.rs
1//! # termpulse
2//!
3//! Native terminal progress indicators via OSC 9;4 — with smart terminal
4//! detection, graceful fallback, throttling, and stall detection.
5//!
6//! ## Quick Start
7//!
8//! ```no_run
9//! use termpulse::Controller;
10//!
11//! let mut ctrl = Controller::auto();
12//! ctrl.set(50, "Building");
13//! // ... do work ...
14//! ctrl.done("Complete");
15//! ```
16//!
17//! ## Architecture
18//!
19//! ```text
20//! termpulse (this crate)
21//! ├── Controller — stateful progress management
22//! ├── detect — terminal capability detection
23//! ├── backend/ — output strategy (osc, ascii, silent)
24//! ├── throttle — rate limiting & deduplication
25//! └── estimate — ETA & throughput calculation
26//!
27//! termpulse-core (dependency)
28//! └── OSC 9;4 sequence build/parse/sanitize
29//! ```
30//!
31//! ## Design Principles
32//!
33//! 1. **Zero-config**: `Controller::auto()` detects the best backend
34//! 2. **Safe by default**: Labels are sanitized, percentages clamped
35//! 3. **Graceful degradation**: OSC → ASCII → Silent (three-tier fallback)
36//! 4. **No panic**: All operations are infallible from the caller's perspective
37//! 5. **Dependency injection**: All I/O is injectable for testing
38
39#![forbid(unsafe_code)]
40#![warn(missing_docs)]
41#![doc(html_root_url = "https://docs.rs/termpulse/0.1.0")]
42
43pub mod backend;
44mod controller;
45pub mod detect;
46pub mod estimate;
47pub mod throttle;
48
49pub use controller::Controller;
50pub use detect::{Multiplexer, TerminalCapability};
51
52// Re-export core types for convenience
53pub use termpulse_core::{
54 OscSequence, ProgressState, Terminator, find_sequences, is_clean, sanitize_label,
55 strip_sequences,
56};