Skip to main content

ftui_runtime/
lib.rs

1#![cfg_attr(unix, feature(unix_send_signal))]
2#![cfg_attr(unix, feature(process_setsid))]
3#![cfg_attr(target_os = "linux", feature(linux_pidfd))]
4#![forbid(unsafe_code)]
5
6//! FrankenTUI Runtime
7//!
8//! This crate provides the runtime components that tie together the core,
9//! render, and layout crates into a complete terminal application framework.
10//!
11//! # Key Components
12//!
13//! - [`TerminalWriter`] - Unified terminal output coordinator with inline mode support
14//! - [`LogSink`] - Line-buffered writer for sanitized log output
15//! - [`Program`] - Bubbletea/Elm-style runtime for terminal applications
16//! - [`Model`] - Trait for application state and behavior
17//! - [`Cmd`] - Commands for side effects
18//! - [`Subscription`] - Trait for continuous event sources
19//! - [`Every`] - Built-in tick subscription
20//!
21//! # Role in FrankenTUI
22//! `ftui-runtime` is the orchestrator. It consumes input events from
23//! `ftui-core`, drives your `Model::update`, calls `Model::view` to render
24//! frames, and delegates rendering to `ftui-render` via `TerminalWriter`.
25//!
26//! # How it fits in the system
27//! The runtime is the center of the architecture: it is the bridge between
28//! input (`ftui-core`) and output (`ftui-render`). Widgets and layout are
29//! optional layers used by your `view()` to construct UI output.
30
31#[cfg(feature = "experimental")]
32pub mod alpha_investing;
33pub mod asciicast;
34pub mod bocpd;
35pub mod cancellation;
36
37#[cfg(feature = "experimental")]
38pub mod conformal_alert;
39#[cfg(feature = "experimental")]
40pub mod conformal_frame_guard;
41pub mod conformal_predictor;
42#[cfg(feature = "experimental")]
43pub mod conformal_stages;
44#[cfg(feature = "experimental")]
45pub mod cost_model;
46#[cfg(feature = "experimental")]
47pub mod countmin_sketch;
48pub mod debug_trace;
49pub mod decision_core;
50#[cfg(feature = "experimental")]
51pub mod degradation_cascade;
52pub mod demo;
53pub mod effect_system;
54#[cfg(feature = "experimental")]
55pub mod eprocess_throttle;
56#[cfg(feature = "event-trace")]
57pub mod event_trace;
58#[cfg(feature = "experimental")]
59pub mod evidence_bridges;
60pub mod evidence_sink;
61pub mod evidence_telemetry;
62#[cfg(feature = "experimental")]
63pub mod flake_detector;
64#[cfg(feature = "experimental")]
65pub mod flat_combine;
66pub mod input_fairness;
67pub mod input_macro;
68#[cfg(feature = "experimental")]
69pub mod ivm;
70#[cfg(feature = "experimental")]
71pub mod lens;
72pub mod locale;
73pub mod log_sink;
74pub mod metrics_registry;
75pub mod pane_keymap;
76#[cfg(feature = "experimental")]
77pub mod policy_config;
78#[cfg(feature = "experimental")]
79pub mod policy_registry;
80pub mod process_subscription;
81pub mod program;
82pub mod queueing_scheduler;
83#[cfg(feature = "render-thread")]
84pub mod render_thread;
85pub mod render_trace;
86pub mod resize_coalescer;
87#[cfg(feature = "experimental")]
88pub mod resize_sla;
89pub mod retry;
90#[cfg(feature = "experimental")]
91pub mod reversible;
92#[cfg(feature = "experimental")]
93pub mod rough_path;
94pub mod schema_compat;
95pub mod simulator;
96#[cfg(feature = "experimental")]
97pub mod slo;
98#[cfg(feature = "experimental")]
99pub mod sos_barrier;
100pub mod state_persistence;
101#[cfg(feature = "stdio-capture")]
102pub mod stdio_capture;
103pub mod string_model;
104pub mod subscription;
105pub mod telemetry_schema;
106pub mod terminal_presenter;
107pub mod terminal_writer;
108pub mod tick_strategy;
109#[cfg(feature = "experimental")]
110pub mod timeline_aggregator;
111pub mod transparency;
112pub mod undo;
113pub mod unified_evidence;
114#[cfg(feature = "experimental")]
115pub mod validation_pipeline;
116pub mod voi_sampling;
117#[cfg(feature = "experimental")]
118pub mod wasm_runner;
119
120pub mod reactive;
121#[cfg(feature = "experimental")]
122pub mod schedule_trace;
123#[cfg(feature = "telemetry")]
124pub mod telemetry;
125pub mod voi_telemetry;
126
127pub use asciicast::{AsciicastRecorder, AsciicastWriter};
128pub use cancellation::{CancellationSource, CancellationToken};
129pub use evidence_sink::{EvidenceSink, EvidenceSinkConfig, EvidenceSinkDestination};
130pub use evidence_telemetry::{
131    BudgetDecisionSnapshot, ConformalSnapshot, DiffDecisionSnapshot, ResizeDecisionSnapshot,
132    budget_snapshot, clear_budget_snapshot, clear_diff_snapshot, clear_resize_snapshot,
133    diff_snapshot, resize_snapshot, set_budget_snapshot, set_diff_snapshot, set_resize_snapshot,
134};
135pub use ftui_a11y::tree::{A11yTree, ScreenReaderAnnouncement, ScreenReaderPolicy};
136pub use ftui_backend::{BackendEventSource, BackendFeatures};
137#[cfg(all(feature = "native-backend", unix))]
138pub use ftui_tty::TtyBackend;
139pub use input_macro::{
140    EventRecorder, FilteredEventRecorder, InputMacro, MacroPlayback, MacroPlayer, MacroRecorder,
141    RecordingFilter, RecordingState, TimedEvent,
142};
143pub use locale::{
144    Date, DateFormatStyle, DateTime, DateTimeError, DateTimeFormatter, FormattingError, Locale,
145    LocaleContext, LocaleOverride, NumberFormat, NumberFormatter, NumberStyle, NumberingSystem,
146    RoundingMode, TextDirection, Time, TimeFormatStyle, current_locale, detect_system_locale,
147    direction, format_date, format_datetime, format_int, format_number, set_direction, set_locale,
148};
149pub use log_sink::LogSink;
150pub use process_subscription::{
151    ProcessControl, ProcessControlError, ProcessControlStatus, ProcessEvent, ProcessInput,
152    ProcessInputError, ProcessInterruptStatus, ProcessSubscription,
153};
154#[cfg(feature = "crossterm-compat")]
155pub use program::CrosstermEventSource;
156#[cfg(any(all(feature = "native-backend", unix), feature = "crossterm-compat"))]
157pub use program::DefaultProgram;
158pub use program::{
159    AccessibilityFrame, App, AppBuilder, BatchController, Cmd, DEFAULT_TASK_BACKEND,
160    EffectQueueConfig, FrameTiming, FrameTimingConfig, FrameTimingSink, HeadlessEventSource,
161    InlineAutoRemeasureConfig, LoadGovernorConfig, Model, MouseCapturePolicy, PaneTerminalAdapter,
162    PaneTerminalAdapterConfig, PaneTerminalDispatch, PaneTerminalIgnoredReason,
163    PaneTerminalLifecyclePhase, PaneTerminalLogEntry, PaneTerminalLogOutcome,
164    PaneTerminalSplitterHandle, PersistenceConfig, Program, ProgramConfig, ResizeBehavior,
165    RolloutPolicy, RuntimeLane, TaskExecutorBackend, TaskSpec, WidgetRefreshConfig,
166    pane_terminal_resolve_splitter_target, pane_terminal_splitter_handles,
167    pane_terminal_target_from_hit, register_pane_terminal_splitter_hits,
168    signal_termination_from_error,
169};
170pub use program::{
171    DEFAULT_BACKEND, NO_BACKEND_MESSAGE, NOT_A_CONSOLE_MESSAGE, console_available, exit_after_env,
172    parse_exit_after_ms, validate_console_available,
173};
174pub use render_trace::{
175    RENDER_TRACE_SCHEMA_VERSION, RenderTraceConfig, RenderTraceContext, RenderTraceFrame,
176    RenderTraceRecorder,
177};
178pub use retry::{BackoffStrategy, RetryPolicy, task_with_retry, task_with_timeout};
179pub use simulator::{ProgramSimulator, SimulatorError};
180pub use string_model::{StringModel, StringModelAdapter};
181pub use subscription::{
182    Every, FileEvent, FileWatcher, StopSignal, SubId, Subscription, SubscriptionSender,
183    file_watcher, tick_every,
184};
185pub use terminal_presenter::TerminalPresenter;
186pub use terminal_writer::{
187    PresentTimings, ScreenMode, TerminalWriter, UiAnchor, inline_active_widgets,
188};
189pub use tick_strategy::{
190    ActiveOnly, ActivePlusAdjacent, AllocationCurve, Custom, DecayConfig, MarkovPredictor,
191    Predictive, PredictiveConfig, PredictiveStrategyConfig, ScreenPrediction, ScreenTickDispatch,
192    TickAllocation, TickDecision, TickStrategy, TickStrategyKind, TransitionCounter,
193    TransitionEntry, TransitionHistory, Uniform,
194};
195#[cfg(feature = "state-persistence")]
196pub use tick_strategy::{load_transitions, save_transitions};
197pub use voi_telemetry::{
198    clear_inline_auto_voi_snapshot, inline_auto_voi_snapshot, set_inline_auto_voi_snapshot,
199};
200
201#[cfg(feature = "render-thread")]
202pub use render_thread::{OutMsg, RenderThread};
203
204#[cfg(feature = "stdio-capture")]
205pub use stdio_capture::{CapturedWriter, StdioCapture, StdioCaptureError};
206
207#[cfg(feature = "experimental")]
208pub use conformal_alert::{
209    AlertConfig, AlertDecision, AlertEvidence, AlertReason, AlertStats, ConformalAlert,
210};
211#[cfg(feature = "experimental")]
212pub use conformal_frame_guard::{
213    ConformalFrameGuard, ConformalFrameGuardConfig, ConformalFrameGuardTelemetry, GuardState,
214    NonconformitySummary, P99Prediction,
215};
216pub use conformal_predictor::{
217    BucketKey, ConformalConfig, ConformalConfigError, ConformalPrediction, ConformalPredictor,
218    ConformalStatus, ConformalUpdate, DiffBucket, ModeBucket,
219};
220#[cfg(feature = "experimental")]
221pub use cost_model::{
222    BatchCostParams, BatchCostResult, CacheCostParams, CacheCostResult, PipelineCostParams,
223    PipelineCostResult, StageStats,
224};
225#[cfg(feature = "experimental")]
226pub use countmin_sketch::{CountMinSketch, ErrorEvidence, SketchConfig, SketchStats};
227pub use decision_core::{
228    Action as DecisionAction, Decision, DecisionCore, Outcome as DecisionOutcome, Posterior,
229    State as DecisionState, argmin_expected_loss, second_best_loss,
230};
231#[cfg(feature = "experimental")]
232pub use degradation_cascade::{
233    CascadeConfig, CascadeDecision, CascadeEvidence, CascadeTelemetry, DegradationCascade,
234    PreRenderResult,
235};
236pub use demo::{DemoDefinition, DemoParseError, DemoStep, parse_demo_yaml, validate_demos};
237pub use effect_system::{
238    QueueTelemetry, effects_command_total, effects_executed_total, effects_queue_dropped,
239    effects_queue_enqueued, effects_queue_high_water, effects_queue_processed,
240    effects_subscription_total, queue_telemetry, record_command_effect, record_subscription_start,
241    record_subscription_stop, trace_command_effect,
242};
243#[cfg(feature = "experimental")]
244pub use eprocess_throttle::{
245    EProcessThrottle, ThrottleConfig, ThrottleDecision, ThrottleLog, ThrottleStats,
246    eprocess_rejections_total,
247};
248#[cfg(feature = "event-trace")]
249pub use event_trace::{
250    EventReplayer, EventTraceReader, EventTraceWriter, EvidenceMismatch, EvidenceVerifier,
251    SerDecisionDomain, SerEvidenceEntry, SerEvidenceTerm, TraceFile, TraceRecord,
252};
253#[cfg(feature = "experimental")]
254pub use flake_detector::{EvidenceLog, FlakeConfig, FlakeDecision, FlakeDetector, FlakeSummary};
255#[cfg(feature = "experimental")]
256pub use flat_combine::{CombinerStats, FlatCombiner};
257#[cfg(feature = "experimental")]
258pub use lens::{AtIndex, Composed, Fst, Identity, Lens, Prism, Snd, SomePrism, at_index, compose};
259pub use metrics_registry::{
260    BuiltinCounter, BuiltinGauge, BuiltinHistogram, Counter as MetricsCounter,
261    Gauge as MetricsGauge, Histogram as MetricsHistogram, METRICS, MetricsRegistry,
262};
263#[cfg(feature = "experimental")]
264pub use policy_config::{
265    BocpdPolicyConfig, CascadePolicyConfig, ConformalPolicyConfig, EProcessBudgetPolicyConfig,
266    EProcessThrottlePolicyConfig, EvidencePolicyConfig, FrameGuardPolicyConfig, PidPolicyConfig,
267    PolicyConfig, PolicyConfigError, VoiPolicyConfig,
268};
269#[cfg(feature = "experimental")]
270pub use policy_registry::{PolicyRegistry, PolicyRegistryError, PolicySwitchEvent};
271pub use reactive::{BatchScope, Binding, BindingScope, Computed, Observable, TwoWayBinding};
272pub use resize_coalescer::{
273    CoalesceAction, CoalescerConfig, CoalescerStats, CycleTimePercentiles, DecisionLog,
274    DecisionSummary, DetectorDecisions, Regime, RegimeDetector, ResizeCoalescer,
275};
276#[cfg(feature = "experimental")]
277pub use resize_sla::{
278    ResizeEvidence, ResizeSlaMonitor, SlaConfig, SlaLogEntry, SlaSummary, make_sla_hooks,
279};
280#[cfg(feature = "experimental")]
281pub use reversible::{
282    AddOp, InsertOp, Journal, MulOp, PushOp, RemoveOp, Reversible, Sequence, SetOp, SwapOp, XorOp,
283};
284pub use schema_compat::{
285    CompatCheckResult, Compatibility, MatrixEntry, SchemaKind, check_event_trace_compat,
286    check_evidence_compat, check_golden_trace_compat, check_render_trace_compat,
287    check_schema_compat, default_compatibility_matrix, run_compatibility_matrix,
288};
289#[cfg(feature = "experimental")]
290pub use slo::{
291    BreachResult, BreachSeverity, MetricSlo, MetricType, SafeModeDecision, SloSchema,
292    SloSchemaError, check_breach, check_safe_mode, emit_slo_check, parse_slo_yaml, run_slo_check,
293};
294#[cfg(feature = "experimental")]
295pub use timeline_aggregator::{
296    AggregationEvidence, AggregatorConfig, AggregatorStats, TimelineAggregator,
297};
298pub use undo::{
299    CommandBatch, CommandError, CommandMetadata, CommandResult, CommandSource, HistoryConfig,
300    HistoryManager, MergeConfig, TextDeleteCmd, TextInsertCmd, TextReplaceCmd, Transaction,
301    TransactionScope, UndoableCmd, WidgetId,
302};
303pub use unified_evidence::{
304    DecisionDomain, DomainSummary, EmitsEvidence, EvidenceEntry, EvidenceEntryBuilder,
305    EvidenceTerm, LedgerSummary, UnifiedEvidenceLedger,
306};
307#[cfg(feature = "experimental")]
308pub use validation_pipeline::{
309    LedgerEntry, PipelineConfig, PipelineResult, PipelineSummary, ValidationOutcome,
310    ValidationPipeline, ValidatorStats,
311};
312pub use voi_sampling::{
313    DeferredRefinementConfig, DeferredRefinementPlan, DeferredRefinementScheduler,
314    RefinementCandidate, RefinementSelection, VoiConfig, VoiDecision, VoiLogEntry, VoiObservation,
315    VoiSampler, VoiSamplerSnapshot, VoiSummary, voi_samples_skipped_total, voi_samples_taken_total,
316};
317
318// State persistence
319#[cfg(feature = "state-persistence")]
320pub use state_persistence::FileStorage;
321pub use state_persistence::{
322    MemoryStorage, RegistryStats, StateRegistry, StorageBackend, StorageError, StorageResult,
323    StoredEntry,
324};
325
326#[cfg(feature = "experimental")]
327pub use schedule_trace::{
328    CancelReason, GoldenCompareResult, IsomorphismProof, ScheduleTrace, SchedulerPolicy, TaskEvent,
329    TraceConfig, TraceEntry, TraceSummary, WakeupReason, compare_golden,
330};
331
332// Diff strategy (re-exports from ftui-render)
333pub use ftui_render::diff_strategy::{
334    DiffStrategy, DiffStrategyConfig, DiffStrategySelector, StrategyEvidence,
335};
336pub use terminal_writer::RuntimeDiffConfig;
337#[cfg(feature = "experimental")]
338pub use wasm_runner::{RenderedFrame, StepResult, WasmRunner};
339
340#[cfg(feature = "telemetry")]
341pub use telemetry::{
342    DecisionEvidence, EnabledReason, EndpointSource, EvidenceLedger, Protocol, SCHEMA_VERSION,
343    SpanId, TelemetryConfig, TelemetryError, TelemetryGuard, TraceContextSource, TraceId,
344    is_safe_env_var, redact,
345};
346
347#[cfg(all(test, feature = "experimental"))]
348mod experimental_smoke {
349    use crate::countmin_sketch::CountMinSketch;
350    use crate::timeline_aggregator::{AggregatorConfig, TimelineAggregator};
351
352    #[test]
353    fn timeline_aggregator_and_cms_compile() {
354        let mut agg = TimelineAggregator::new(AggregatorConfig::default());
355        for _ in 0..60 {
356            agg.observe(&"a", 1);
357        }
358        for _ in 0..40 {
359            agg.observe(&"b", 1);
360        }
361        assert!(agg.estimate(&"a") >= 60);
362
363        let mut cms = CountMinSketch::with_dimensions(64, 4);
364        for i in 0..100 {
365            cms.add(&i, 1);
366        }
367        for i in 0..100 {
368            assert!(cms.estimate(&i) >= 1);
369        }
370    }
371}