Skip to main content

Crate ftui_runtime

Crate ftui_runtime 

Source
Expand description

FrankenTUI Runtime

This crate provides the runtime components that tie together the core, render, and layout crates into a complete terminal application framework.

§Key Components

  • TerminalWriter - Unified terminal output coordinator with inline mode support
  • LogSink - Line-buffered writer for sanitized log output
  • Program - Bubbletea/Elm-style runtime for terminal applications
  • Model - Trait for application state and behavior
  • Cmd - Commands for side effects
  • Subscription - Trait for continuous event sources
  • Every - Built-in tick subscription

§Role in FrankenTUI

ftui-runtime is the orchestrator. It consumes input events from ftui-core, drives your Model::update, calls Model::view to render frames, and delegates rendering to ftui-render via TerminalWriter.

§How it fits in the system

The runtime is the center of the architecture: it is the bridge between input (ftui-core) and output (ftui-render). Widgets and layout are optional layers used by your view() to construct UI output.

Re-exports§

pub use asciicast::AsciicastRecorder;
pub use asciicast::AsciicastWriter;
pub use cancellation::CancellationSource;
pub use cancellation::CancellationToken;
pub use evidence_sink::EvidenceSink;
pub use evidence_sink::EvidenceSinkConfig;
pub use evidence_sink::EvidenceSinkDestination;
pub use evidence_telemetry::BudgetDecisionSnapshot;
pub use evidence_telemetry::ConformalSnapshot;
pub use evidence_telemetry::DiffDecisionSnapshot;
pub use evidence_telemetry::ResizeDecisionSnapshot;
pub use evidence_telemetry::budget_snapshot;
pub use evidence_telemetry::clear_budget_snapshot;
pub use evidence_telemetry::clear_diff_snapshot;
pub use evidence_telemetry::clear_resize_snapshot;
pub use evidence_telemetry::diff_snapshot;
pub use evidence_telemetry::resize_snapshot;
pub use evidence_telemetry::set_budget_snapshot;
pub use evidence_telemetry::set_diff_snapshot;
pub use evidence_telemetry::set_resize_snapshot;
pub use input_macro::EventRecorder;
pub use input_macro::FilteredEventRecorder;
pub use input_macro::InputMacro;
pub use input_macro::MacroPlayback;
pub use input_macro::MacroPlayer;
pub use input_macro::MacroRecorder;
pub use input_macro::RecordingFilter;
pub use input_macro::RecordingState;
pub use input_macro::TimedEvent;
pub use locale::LocaleContext;
pub use locale::LocaleOverride;
pub use locale::TextDirection;
pub use locale::current_locale;
pub use locale::detect_system_locale;
pub use locale::direction;
pub use locale::format_date;
pub use locale::format_datetime;
pub use locale::format_int;
pub use locale::format_number;
pub use locale::set_direction;
pub use locale::set_locale;
pub use log_sink::LogSink;
pub use process_subscription::ProcessControl;
pub use process_subscription::ProcessControlError;
pub use process_subscription::ProcessControlStatus;
pub use process_subscription::ProcessEvent;
pub use process_subscription::ProcessInput;
pub use process_subscription::ProcessInputError;
pub use process_subscription::ProcessInterruptStatus;
pub use process_subscription::ProcessSubscription;
pub use program::AccessibilityFrame;
pub use program::App;
pub use program::AppBuilder;
pub use program::BatchController;
pub use program::Cmd;
pub use program::EffectQueueConfig;
pub use program::FrameTiming;
pub use program::FrameTimingConfig;
pub use program::FrameTimingSink;
pub use program::HeadlessEventSource;
pub use program::InlineAutoRemeasureConfig;
pub use program::LoadGovernorConfig;
pub use program::Model;
pub use program::MouseCapturePolicy;
pub use program::PaneTerminalAdapter;
pub use program::PaneTerminalAdapterConfig;
pub use program::PaneTerminalDispatch;
pub use program::PaneTerminalIgnoredReason;
pub use program::PaneTerminalLifecyclePhase;
pub use program::PaneTerminalLogEntry;
pub use program::PaneTerminalLogOutcome;
pub use program::PaneTerminalSplitterHandle;
pub use program::PersistenceConfig;
pub use program::Program;
pub use program::ProgramConfig;
pub use program::ResizeBehavior;
pub use program::RolloutPolicy;
pub use program::RuntimeLane;
pub use program::TaskExecutorBackend;
pub use program::TaskSpec;
pub use program::WidgetRefreshConfig;
pub use program::pane_terminal_resolve_splitter_target;
pub use program::pane_terminal_splitter_handles;
pub use program::pane_terminal_target_from_hit;
pub use program::register_pane_terminal_splitter_hits;
pub use program::signal_termination_from_error;
pub use program::DEFAULT_BACKEND;
pub use program::NO_BACKEND_MESSAGE;
pub use render_trace::RENDER_TRACE_SCHEMA_VERSION;
pub use render_trace::RenderTraceConfig;
pub use render_trace::RenderTraceContext;
pub use render_trace::RenderTraceFrame;
pub use render_trace::RenderTraceRecorder;
pub use retry::BackoffStrategy;
pub use retry::RetryPolicy;
pub use retry::task_with_retry;
pub use retry::task_with_timeout;
pub use simulator::ProgramSimulator;
pub use simulator::SimulatorError;
pub use string_model::StringModel;
pub use string_model::StringModelAdapter;
pub use subscription::Every;
pub use subscription::FileEvent;
pub use subscription::FileWatcher;
pub use subscription::StopSignal;
pub use subscription::SubId;
pub use subscription::Subscription;
pub use subscription::SubscriptionSender;
pub use subscription::file_watcher;
pub use subscription::tick_every;
pub use terminal_presenter::TerminalPresenter;
pub use terminal_writer::TerminalWriter;
pub use terminal_writer::inline_active_widgets;
pub use tick_strategy::ActiveOnly;
pub use tick_strategy::ActivePlusAdjacent;
pub use tick_strategy::AllocationCurve;
pub use tick_strategy::Custom;
pub use tick_strategy::DecayConfig;
pub use tick_strategy::MarkovPredictor;
pub use tick_strategy::Predictive;
pub use tick_strategy::PredictiveConfig;
pub use tick_strategy::PredictiveStrategyConfig;
pub use tick_strategy::ScreenPrediction;
pub use tick_strategy::ScreenTickDispatch;
pub use tick_strategy::TickAllocation;
pub use tick_strategy::TickDecision;
pub use tick_strategy::TickStrategy;
pub use tick_strategy::TickStrategyKind;
pub use tick_strategy::TransitionCounter;
pub use tick_strategy::TransitionEntry;
pub use tick_strategy::TransitionHistory;
pub use tick_strategy::Uniform;
pub use voi_telemetry::clear_inline_auto_voi_snapshot;
pub use voi_telemetry::inline_auto_voi_snapshot;
pub use voi_telemetry::set_inline_auto_voi_snapshot;
pub use conformal_predictor::BucketKey;
pub use conformal_predictor::ConformalConfig;
pub use conformal_predictor::ConformalConfigError;
pub use conformal_predictor::ConformalPrediction;
pub use conformal_predictor::ConformalPredictor;
pub use conformal_predictor::ConformalStatus;
pub use conformal_predictor::ConformalUpdate;
pub use conformal_predictor::DiffBucket;
pub use conformal_predictor::ModeBucket;
pub use decision_core::Action as DecisionAction;
pub use decision_core::Decision;
pub use decision_core::DecisionCore;
pub use decision_core::Outcome as DecisionOutcome;
pub use decision_core::Posterior;
pub use decision_core::State as DecisionState;
pub use decision_core::argmin_expected_loss;
pub use decision_core::second_best_loss;
pub use demo::DemoDefinition;
pub use demo::DemoParseError;
pub use demo::DemoStep;
pub use demo::parse_demo_yaml;
pub use demo::validate_demos;
pub use effect_system::QueueTelemetry;
pub use effect_system::effects_command_total;
pub use effect_system::effects_executed_total;
pub use effect_system::effects_queue_dropped;
pub use effect_system::effects_queue_enqueued;
pub use effect_system::effects_queue_high_water;
pub use effect_system::effects_queue_processed;
pub use effect_system::effects_subscription_total;
pub use effect_system::queue_telemetry;
pub use effect_system::record_command_effect;
pub use effect_system::record_subscription_start;
pub use effect_system::record_subscription_stop;
pub use effect_system::trace_command_effect;
pub use metrics_registry::BuiltinCounter;
pub use metrics_registry::BuiltinGauge;
pub use metrics_registry::BuiltinHistogram;
pub use metrics_registry::Counter as MetricsCounter;
pub use metrics_registry::Gauge as MetricsGauge;
pub use metrics_registry::Histogram as MetricsHistogram;
pub use metrics_registry::METRICS;
pub use metrics_registry::MetricsRegistry;
pub use reactive::BatchScope;
pub use reactive::Binding;
pub use reactive::BindingScope;
pub use reactive::Computed;
pub use reactive::Observable;
pub use reactive::TwoWayBinding;
pub use resize_coalescer::CoalesceAction;
pub use resize_coalescer::CoalescerConfig;
pub use resize_coalescer::CoalescerStats;
pub use resize_coalescer::CycleTimePercentiles;
pub use resize_coalescer::DecisionLog;
pub use resize_coalescer::DecisionSummary;
pub use resize_coalescer::DetectorDecisions;
pub use resize_coalescer::Regime;
pub use resize_coalescer::RegimeDetector;
pub use resize_coalescer::ResizeCoalescer;
pub use schema_compat::CompatCheckResult;
pub use schema_compat::Compatibility;
pub use schema_compat::MatrixEntry;
pub use schema_compat::SchemaKind;
pub use schema_compat::check_event_trace_compat;
pub use schema_compat::check_evidence_compat;
pub use schema_compat::check_golden_trace_compat;
pub use schema_compat::check_render_trace_compat;
pub use schema_compat::check_schema_compat;
pub use schema_compat::default_compatibility_matrix;
pub use schema_compat::run_compatibility_matrix;
pub use undo::CommandBatch;
pub use undo::CommandError;
pub use undo::CommandMetadata;
pub use undo::CommandResult;
pub use undo::CommandSource;
pub use undo::HistoryConfig;
pub use undo::HistoryManager;
pub use undo::MergeConfig;
pub use undo::TextDeleteCmd;
pub use undo::TextInsertCmd;
pub use undo::TextReplaceCmd;
pub use undo::Transaction;
pub use undo::TransactionScope;
pub use undo::UndoableCmd;
pub use undo::WidgetId;
pub use unified_evidence::DecisionDomain;
pub use unified_evidence::DomainSummary;
pub use unified_evidence::EmitsEvidence;
pub use unified_evidence::EvidenceEntry;
pub use unified_evidence::EvidenceEntryBuilder;
pub use unified_evidence::EvidenceTerm;
pub use unified_evidence::LedgerSummary;
pub use unified_evidence::UnifiedEvidenceLedger;
pub use voi_sampling::DeferredRefinementConfig;
pub use voi_sampling::DeferredRefinementPlan;
pub use voi_sampling::DeferredRefinementScheduler;
pub use voi_sampling::RefinementCandidate;
pub use voi_sampling::RefinementSelection;
pub use voi_sampling::VoiConfig;
pub use voi_sampling::VoiDecision;
pub use voi_sampling::VoiLogEntry;
pub use voi_sampling::VoiObservation;
pub use voi_sampling::VoiSampler;
pub use voi_sampling::VoiSamplerSnapshot;
pub use voi_sampling::VoiSummary;
pub use voi_sampling::voi_samples_skipped_total;
pub use voi_sampling::voi_samples_taken_total;
pub use state_persistence::MemoryStorage;
pub use state_persistence::RegistryStats;
pub use state_persistence::StateRegistry;
pub use state_persistence::StorageBackend;
pub use state_persistence::StorageError;
pub use state_persistence::StorageResult;
pub use state_persistence::StoredEntry;
pub use terminal_writer::RuntimeDiffConfig;

Modules§

asciicast
Asciicast v2 recorder for capturing terminal sessions.
bocpd
Bayesian Online Change-Point Detection (BOCPD) for Resize Regime Detection.
cancellation
Cooperative cancellation tokens for commands and tasks.
conformal_predictor
Conformal predictor for frame-time risk (bd-3e1t.3.2).
debug_trace
Zero-cost debug tracing controlled by environment variable.
decision_core
Generic expected-loss decision framework (bd-2uv9c, bd-3rss7).
demo
Demo definition parser and runner (bd-2xj.3).
effect_system
Effect system observability and Cx-aware execution helpers.
evidence_sink
JSONL evidence sink for deterministic diagnostics.
evidence_telemetry
Evidence telemetry snapshots for runtime explainability overlays.
input_fairness
Input Fairness Guard (bd-1rz0.17)
input_macro
Input macro recording and playback.
locale
Locale context provider for runtime-wide internationalization.
log_sink
Log sink for in-process output routing.
metrics_registry
Prometheus-compatible metrics registry (bd-xox.3).
pane_keymap
Terminal keyboard bindings for the pane workspace (bd-21pbi.2).
process_subscription
Process subscription for spawning and monitoring external processes.
program
Bubbletea/Elm-style runtime for terminal applications.
queueing_scheduler
Queueing Theory Scheduler with SRPT/Smith-Rule Style Scheduling (bd-13pq.7).
reactive
Reactive data bindings for FrankenTUI.
render_trace
Render-trace recorder for deterministic replay (bd-3e1t.4.13).
resize_coalescer
Adaptive resize stream coalescer.
retry
Retry policies and timeout-enforced task helpers.
schema_compat
Suite-wide trace and evidence schema compatibility (bd-ehk.3).
simulator
Deterministic program simulator for testing.
state_persistence
Widget state persistence for save/restore across sessions.
string_model
Easy-mode adapter for string-based views.
subscription
Subscription system for continuous event sources.
telemetry_schema
Canonical telemetry schema for the FrankenTUI runtime (bd-17ar5).
terminal_presenter
Terminal presenter implementation wrapping TerminalWriter.
terminal_writer
Terminal output coordinator with inline mode support.
tick_strategy
Tick strategy primitives for selective background ticking.
transparency
Galaxy-brain transparency layer with progressive disclosure (bd-xox.5).
undo
Undo/Redo command history framework.
unified_evidence
Unified Evidence Ledger for all Bayesian decision points (bd-fp38v).
voi_sampling
Value-of-Information (VOI) Sampling Policy for expensive measurements.
voi_telemetry
VOI debug telemetry snapshots for runtime introspection.

Macros§

bind
Create a direct Binding to an observable.
bind_map
Create a mapped Binding from an observable with a transform function.
bind_map2
Create a mapped Binding from two observables.
debug_trace
Conditionally print debug trace output to stderr.

Structs§

A11yTree
Immutable snapshot of the accessibility tree after a render pass.
BackendFeatures
Terminal feature toggles that backends must support.
Date
A calendar date (year, month, day) in the Gregorian calendar.
DateTime
Combined calendar date, time, and optional timezone offset.
DateTimeFormatter
A locale-aware date and time formatter.
DiffStrategyConfig
Configuration for the diff strategy selector.
DiffStrategySelector
Bayesian diff strategy selector.
NumberFormat
Configuration for number formatting.
NumberFormatter
A locale-aware number formatter.
PresentTimings
Presentation phase timing measurements.
ScreenReaderAnnouncement
One screen-reader announcement derived from focus, control state, or live-region changes.
ScreenReaderPolicy
Bounded output policy for screen-reader mirrors and announcements.
StrategyEvidence
Evidence supporting a strategy decision.
Time
A wall-clock time representation (hours, minutes, seconds, milliseconds).

Enums§

DateFormatStyle
Date formatting style.
DateTimeError
Errors in date or time construction and validation.
DiffStrategy
The diff strategy to use for the current frame.
FormattingError
Errors that can occur during locale-aware formatting.
NumberStyle
Numerical display style.
NumberingSystem
Digit numbering system.
RoundingMode
Rounding strategy for numeric formatting.
ScreenMode
Screen mode determines whether we use alternate screen or inline mode.
TimeFormatStyle
Time formatting style.
UiAnchor
Where the UI region is anchored in inline mode.

Traits§

BackendEventSource
Event source abstraction: terminal size queries, feature toggles, and event I/O.

Type Aliases§

Locale
Locale identifier (e.g., "en", "en-US", "ru").