Skip to main content

ftui_runtime/
lib.rs

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