Skip to main content

ftui_runtime/
lib.rs

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