`ProgramConfig`

ProgramConfig is the runtime’s single configuration struct. You build one with ProgramConfig::default() (or a convenience constructor like fullscreen() / inline(u16)), chain with_* methods, and hand it to Program::with_config.

File: crates/ftui-runtime/src/program.rs:2360.

The struct (abbreviated)

crates/ftui-runtime/src/program.rs


pub struct ProgramConfig {
    pub screen_mode: ScreenMode,
    pub ui_anchor: UiAnchor,
    pub budget: FrameBudgetConfig,
    pub diff_config: RuntimeDiffConfig,
    pub evidence_sink: EvidenceSinkConfig,
    pub render_trace: RenderTraceConfig,
    pub frame_timing: Option<FrameTimingConfig>,
    pub conformal_config: Option<ConformalConfig>,
    pub locale_context: LocaleContext,
    pub poll_timeout: Duration,
    pub immediate_drain: ImmediateDrainConfig,
    pub resize_coalescer: CoalescerConfig,
    pub resize_behavior: ResizeBehavior,
    pub forced_size: Option<(u16, u16)>,
    pub mouse_capture_policy: MouseCapturePolicy,
    pub bracketed_paste: bool,
    pub focus_reporting: bool,
    pub kitty_keyboard: bool,
    pub persistence: PersistenceConfig,
    pub inline_auto_remeasure: Option<InlineAutoRemeasureConfig>,
    pub widget_refresh: WidgetRefreshConfig,
    pub effect_queue: EffectQueueConfig,
    pub guardrails: GuardrailsConfig,
    pub intercept_signals: bool,
    pub tick_strategy: Option<TickStrategyKind>,
    pub runtime_lane: RuntimeLane,
    pub rollout_policy: RolloutPolicy,
}

All fields are pub — you can poke them directly — but the idiomatic path is the builder. Each with_* below returns Self, so the chain reads left to right.

Constructors

Constructor	Shape	Notes
`ProgramConfig::default()`	Inline mode, 4 UI rows, bottom anchor, mouse-auto, bracketed paste on.	Safe default.
`ProgramConfig::fullscreen()`	Alt-screen, all else default.	For traditional TUI apps.
`ProgramConfig::inline(h)`	Inline mode with fixed UI height `h`.	Shell-embedded mode.
`ProgramConfig::inline_auto(min, max)`	Inline with auto-remeasure between `min..=max`.	Height responds to content.

Builder reference

Method names and signatures come straight from program.rs. Types elided are from the runtime’s public re-exports.

Method	Sets	Typical value
`with_mouse()`	`MouseCapturePolicy::On`	Force mouse on.
`with_mouse_enabled(bool)`	`On` or `Off`	Explicit toggle.
`with_mouse_capture_policy(policy)`	`MouseCapturePolicy`	`Auto` / `On` / `Off`.
`with_budget(cfg)`	`FrameBudgetConfig`	Per-frame p99 cap.
`with_diff_config(cfg)`	`RuntimeDiffConfig`	Diff strategy config.
`with_evidence_sink(cfg)`	`EvidenceSinkConfig`	JSONL diagnostics.
`with_render_trace(cfg)`	`RenderTraceConfig`	Per-frame trace recorder.
`with_frame_timing(cfg)`	`Option<FrameTimingConfig>`	Attach a timing sink.
`with_conformal_config(cfg)`	`ConformalConfig`	Frame-time risk gating.
`without_conformal()`	`None`	Disable risk gating.
`with_locale_context(ctx)`	`LocaleContext`	Explicit locale bundle.
`with_locale(locale)`	Wraps a `Locale` into context.	Convenience.
`with_widget_refresh(cfg)`	`WidgetRefreshConfig`	Budgeted widget selection.
`with_effect_queue(cfg)`	`EffectQueueConfig`	Task backend + queue depth.
`with_resize_coalescer(cfg)`	`CoalescerConfig`	BOCPD-backed resize policy.
`with_resize_behavior(behavior)`	`ResizeBehavior`	`Throttled` (default) or `Immediate`.
`with_forced_size(w, h)`	`Option<(u16, u16)>`	Ignore real resize events.
`without_forced_size()`	Clear override.
`with_legacy_resize(bool)`	Sets `Immediate` when `true`.	Migration toggle.
`with_persistence(cfg)`	`PersistenceConfig`	State registry + auto-save.
`with_registry(arc)`	`Arc<StateRegistry>`	Shortcut for an existing registry.
`with_inline_auto_remeasure(cfg)`	`InlineAutoRemeasureConfig`	VoI-driven height updates.
`without_inline_auto_remeasure()`	Clear.
`with_signal_interception(bool)`	`intercept_signals`	SIGINT/SIGTERM/SIGHUP handling.
`with_guardrails(cfg)`	`GuardrailsConfig`	Memory + queue safety limits.
`with_immediate_drain(cfg)`	`ImmediateDrainConfig`	Event-burst drain policy.
`with_tick_strategy(kind)`	`TickStrategyKind`	`Uniform`, `Predictive`, `Custom`…
`with_lane(lane)`	`RuntimeLane`	See lanes.
`with_rollout_policy(policy)`	`RolloutPolicy`	Off / Shadow / Enabled.
`with_env_overrides()`	Reads `FTUI_RUNTIME_LANE` and `FTUI_ROLLOUT_POLICY`.	Apply last in a chain.

with_env_overrides (at program.rs:2728) calls RuntimeLane::from_env and RolloutPolicy::from_env; unrecognized values emit a tracing::warn! and leave the current value alone.

Typical setups

Inline tool

main.rs


use ftui::prelude::*;
 
let config = ProgramConfig::default()
    .with_mouse_capture_policy(MouseCapturePolicy::Auto)
    .with_tick_strategy(
        ftui_runtime::tick_strategy::TickStrategyKind::Uniform { divisor: 5 }
    );
 
Program::with_config(model, config)?.run()

Fullscreen app

main.rs


use ftui::prelude::*;
 
let config = ProgramConfig::fullscreen()
    .with_mouse()
    .with_resize_behavior(ResizeBehavior::Throttled);
 
Program::with_config(model, config)?.run()

Production with evidence

main.rs


use ftui::prelude::*;
use ftui_runtime::{EvidenceSinkConfig, PersistenceConfig};
use ftui_runtime::state_persistence::StateRegistry;
use std::sync::Arc;
 
let registry = Arc::new(StateRegistry::with_file("~/.cache/app/state.json"));
let _ = registry.load();
 
let config = ProgramConfig::fullscreen()
    .with_evidence_sink(EvidenceSinkConfig::enabled_file("evidence.jsonl"))
    .with_persistence(
        PersistenceConfig::with_registry(registry)
            .checkpoint_every(std::time::Duration::from_secs(30)),
    )
    .with_lane(RuntimeLane::Structured)
    .with_rollout_policy(RolloutPolicy::Shadow)
    .with_env_overrides();
 
Program::with_config(model, config)?.run()

Environment variables

Several fields are overridable from the environment so operators can change behaviour without a rebuild. Apply them by ending your chain with .with_env_overrides().

Variable	Field overridden
`FTUI_RUNTIME_LANE`	`runtime_lane` (`legacy`/`structured`/`asupersync`) — read by `RuntimeLane::from_env`.
`FTUI_ROLLOUT_POLICY`	`rollout_policy` (`off`/`shadow`/`enabled`) — read by `RolloutPolicy::from_env`.
`OTEL_*` / `FTUI_OTEL_HTTP_ENDPOINT`	OTLP export — see telemetry.

Defaults table

Defaults live at program.rs:2433 and are worth remembering when you are reading a config diff:

Field	Default
`screen_mode`	`Inline { ui_height: 4 }`
`ui_anchor`	`UiAnchor::Bottom`
`poll_timeout`	`100 ms`
`resize_behavior`	`Throttled`
`mouse_capture_policy`	`Auto` (off inline, on alt-screen)
`bracketed_paste`	`true`
`focus_reporting`	`false`
`kitty_keyboard`	`false`
`intercept_signals`	`true`
`runtime_lane`	`Structured`
`rollout_policy`	`Off`

Pitfalls

Call with_env_overrides() last. It mutates already-built state. If you call it early and then set .with_lane(...) afterwards, your programmatic value wins — exactly the opposite of what operators usually expect.

forced_size ignores real resizes. Useful in tests and headless demos; disastrous in a real terminal, because the UI will not reflow when the window is resized. Do not set it in production paths.

Cross-references

Model trait Commands Evidence sink Telemetry Persistence Lanes Effect queue

How this piece fits in runtime.

Runtime overview