Crate ftui_layout 

Layout primitives and solvers.

This crate provides layout components for terminal UIs:

• Flex - 1D constraint-based layout (rows or columns)
• Grid - 2D constraint-based layout with cell spanning
• Constraint - Size constraints (Fixed, Percentage, Min, Max, Ratio, FitContent)
• debug - Layout constraint debugging and introspection
• cache - Layout result caching for memoization

Role in FrankenTUI

ftui-layout is the geometry solver for widgets and screens. It converts constraints into concrete rectangles, with support for intrinsic sizing and caching to keep layout deterministic and fast.

How it fits in the system

The runtime and widgets call into this crate to split a Rect into nested regions. Those regions are then passed to widgets or custom renderers, which ultimately draw into ftui-render frames.

Intrinsic Sizing

The layout system supports content-aware sizing via LayoutSizeHint and Flex::split_with_measurer:

use ftui_layout::{Flex, Constraint, LayoutSizeHint};

let flex = Flex::horizontal()
    .constraints([Constraint::FitContent, Constraint::Fill]);

let rects = flex.split_with_measurer(area, |idx, available| {
    match idx {
        0 => LayoutSizeHint { min: 5, preferred: 20, max: None },
        _ => LayoutSizeHint::ZERO,
    }
});

Re-exports

pub use cache::CoherenceCache;

pub use cache::CoherenceId;

pub use cache::LayoutCache;

pub use cache::LayoutCacheKey;

pub use cache::LayoutCacheStats;

pub use cache::S3FifoLayoutCache;

pub use direction::FlowDirection;

pub use direction::LogicalAlignment;

pub use direction::LogicalSides;

pub use direction::mirror_rects_horizontal;

pub use grid::Grid;

pub use grid::GridArea;

pub use grid::GridLayout;

pub use pane::PANE_AFFORDANCE_EMPHASIS_FULL_BPS;

pub use pane::PANE_DEFAULT_MARGIN_CELLS;

pub use pane::PANE_DEFAULT_PADDING_CELLS;

pub use pane::PANE_DRAG_RESIZE_DEFAULT_HYSTERESIS;

pub use pane::PANE_DRAG_RESIZE_DEFAULT_THRESHOLD;

pub use pane::PANE_EDGE_GRIP_INSET_CELLS;

pub use pane::PANE_MAGNETIC_FIELD_CELLS;

pub use pane::PANE_SEMANTIC_INPUT_EVENT_SCHEMA_VERSION;

pub use pane::PANE_SEMANTIC_INPUT_TRACE_SCHEMA_VERSION;

pub use pane::PANE_SNAP_DEFAULT_HYSTERESIS_BPS;

pub use pane::PANE_SNAP_DEFAULT_STEP_BPS;

pub use pane::PANE_TREE_SCHEMA_VERSION;

pub use pane::PaneAffordanceMotion;

pub use pane::PaneCancelReason;

pub use pane::PaneConstraints;

pub use pane::PaneCoordinateNormalizationError;

pub use pane::PaneCoordinateNormalizer;

pub use pane::PaneCoordinateRoundingPolicy;

pub use pane::PaneDockPreview;

pub use pane::PaneDockZone;

pub use pane::PaneDragBehaviorTuning;

pub use pane::PaneDragResizeEffect;

pub use pane::PaneDragResizeMachine;

pub use pane::PaneDragResizeMachineError;

pub use pane::PaneDragResizeNoopReason;

pub use pane::PaneDragResizeState;

pub use pane::PaneDragResizeTransition;

pub use pane::PaneEdgeResizePlan;

pub use pane::PaneEdgeResizePlanError;

pub use pane::PaneGroupTransformPlan;

pub use pane::PaneId;

pub use pane::PaneIdAllocator;

pub use pane::PaneInertialThrow;

pub use pane::PaneInputCoordinate;

pub use pane::PaneInteractionPolicyError;

pub use pane::PaneInteractionTimeline;

pub use pane::PaneInteractionTimelineCheckpointDecision;

pub use pane::PaneInteractionTimelineEntry;

pub use pane::PaneInteractionTimelineError;

pub use pane::PaneInteractionTimelineReplayDiagnostics;

pub use pane::PaneInteractionTimelineRetentionDiagnostics;

pub use pane::PaneInvariantCode;

pub use pane::PaneInvariantIssue;

pub use pane::PaneInvariantReport;

pub use pane::PaneInvariantSeverity;

pub use pane::PaneLayout;

pub use pane::PaneLayoutIntelligenceMode;

pub use pane::PaneLeaf;

pub use pane::PaneModelError;

pub use pane::PaneModifierSnapshot;

pub use pane::PaneMotionVector;

pub use pane::PaneNodeKind;

pub use pane::PaneNodeRecord;

pub use pane::PaneNormalizedCoordinate;

pub use pane::PaneOperation;

pub use pane::PaneOperationError;

pub use pane::PaneOperationFailure;

pub use pane::PaneOperationFamily;

pub use pane::PaneOperationJournalEntry;

pub use pane::PaneOperationJournalResult;

pub use pane::PaneOperationKind;

pub use pane::PaneOperationOutcome;

pub use pane::PanePlacement;

pub use pane::PanePointerButton;

pub use pane::PanePointerPosition;

pub use pane::PanePrecisionMode;

pub use pane::PanePrecisionPolicy;

pub use pane::PanePressureSnapProfile;

pub use pane::PaneReflowMovePlan;

pub use pane::PaneReflowPlanError;

pub use pane::PaneRepairAction;

pub use pane::PaneRepairError;

pub use pane::PaneRepairFailure;

pub use pane::PaneRepairOutcome;

pub use pane::PaneResizeDirection;

pub use pane::PaneResizeGrip;

pub use pane::PaneResizeTarget;

pub use pane::PaneScaleFactor;

pub use pane::PaneSelectionState;

pub use pane::PaneSemanticInputEvent;

pub use pane::PaneSemanticInputEventError;

pub use pane::PaneSemanticInputEventKind;

pub use pane::PaneSemanticInputTrace;

pub use pane::PaneSemanticInputTraceError;

pub use pane::PaneSemanticInputTraceMetadata;

pub use pane::PaneSemanticReplayConformanceArtifact;

pub use pane::PaneSemanticReplayDiffArtifact;

pub use pane::PaneSemanticReplayDiffKind;

pub use pane::PaneSemanticReplayError;

pub use pane::PaneSemanticReplayFixture;

pub use pane::PaneSemanticReplayOutcome;

pub use pane::PaneSnapDecision;

pub use pane::PaneSnapReason;

pub use pane::PaneSnapTuning;

pub use pane::PaneSplit;

pub use pane::PaneSplitRatio;

pub use pane::PaneTransaction;

pub use pane::PaneTransactionOutcome;

pub use pane::PaneTree;

pub use pane::PaneTreeSnapshot;

pub use pane::SplitAxis;

pub use pane_command::PaneAccessibilityPreferences;

pub use pane_command::PaneAnnouncement;

pub use pane_command::PaneAnnouncementCategory;

pub use pane_command::PaneAnnouncer;

pub use pane_command::PaneCardinalDirection;

pub use pane_command::PaneCommand;

pub use pane_command::PaneCommandAcceleration;

pub use pane_command::PaneCommandEffect;

pub use pane_command::PaneCommandNoopReason;

pub use pane_command::PaneCommandResolution;

pub use pane_command::PaneFocusContext;

pub use pane_command::PaneFocusOrdinal;

pub use pane_command::PaneKeymapOwner;

pub use pane_command::PaneKeymapPrecedence;

pub use pane_command::announce_command;

pub use pane_command::focus_cyclic;

pub use pane_command::focus_directional;

pub use pane_command::focus_edge;

pub use pane_command::focus_order;

pub use pane_command::resolve as resolve_pane_command;

pub use pane_execution::PaneExecutionDecision;

pub use pane_execution::PaneExecutionPolicy;

pub use pane_execution::PaneStrategyReason;

pub use pane_execution::PaneWorkloadProfile;

pub use pane_memory::PANE_MEMORY_TELEMETRY_SCHEMA_VERSION;

pub use pane_memory::PaneMemoryComparison;

pub use pane_memory::PaneMemoryDriver;

pub use pane_memory::PaneMemoryStrategy;

pub use pane_memory::PaneMemoryStrategyFootprint;

pub use pane_memory::pane_memory_comparison;

pub use pane_monitors::PaneAssumption;

pub use pane_monitors::PaneMonitorReport;

pub use pane_monitors::PaneMonitorStatus;

pub use pane_monitors::PaneMonitorThresholds;

pub use pane_monitors::PaneMonitorVerdict;

pub use pane_monitors::monitor_fallback_frequency;

pub use pane_monitors::monitor_latency_envelope;

pub use pane_monitors::monitor_replay_depth;

pub use pane_monitors::monitor_retention_pressure;

pub use pane_monitors::monitor_selector_churn;

pub use pane_persistent::PaneVersionRetention;

pub use pane_persistent::PaneVersionStore;

pub use pane_persistent::PaneVersioningReport;

pub use pane_persistent::PersistentApplyError;

pub use pane_persistent::PersistentApplyStrategy;

pub use pane_persistent::PersistentNode;

pub use pane_persistent::VersionedPaneTree;

pub use pane_retention::PaneRetentionBudget;

pub use pane_retention::PaneRetentionDecision;

pub use pane_retention::PaneRetentionOutcome;

pub use pane_retention::PaneRetentionPolicy;

pub use pane_retention::apply_to_timeline as apply_retention_to_timeline;

pub use pane_retention::apply_to_version_store as apply_retention_to_version_store;

pub use responsive::Responsive;

pub use responsive_layout::ResponsiveLayout;

pub use responsive_layout::ResponsiveSplit;

pub use visibility::Visibility;

pub use workspace::MigrationResult;

pub use workspace::WORKSPACE_SCHEMA_VERSION;

pub use workspace::WorkspaceMetadata;

pub use workspace::WorkspaceMigrationError;

pub use workspace::WorkspaceSnapshot;

pub use workspace::WorkspaceSnapshotJsonError;

pub use workspace::WorkspaceValidationError;

pub use workspace::canonicalize_workspace_snapshot;

pub use workspace::decode_workspace_snapshot_json;

pub use workspace::migrate_workspace;

pub use workspace::needs_migration;

pub use workspace::to_canonical_workspace_snapshot_json;

pub use smallvec;

Modules

cache

Layout cache for memoizing layout computation results.

debug

Layout constraint debugging utilities.

dep_graph

Dependency graph for incremental layout invalidation (bd-3p4y1.1).

direction

RTL layout mirroring and logical direction support (bd-ic6i.3).

egraph

E-graph encoding for layout constraint optimization.

grid

2D Grid layout system for dashboard-style positioning.

incremental

Incremental layout engine (bd-3p4y1.3).

pane

Canonical pane split-tree schema and validation.

pane_command

Canonical keyboard command model and focus-graph semantics for panes (bd-21pbi.1).

pane_execution

Deterministic execution-policy selector for pane-history strategies (bd-1k7ek.6).

pane_memory

Cross-strategy pane-memory telemetry (bd-25wj7.1).

pane_monitors

Latency-envelope and assumption monitors for advanced pane strategies (bd-1pvzq.2).

pane_persistent

Prototype: persistent / versioned PaneTree with structural sharing.

pane_retention

Bounded retention & pruning policy for pane history (bd-25wj7.2).

responsive

Responsive value mapping: apply different values based on breakpoint.

responsive_layout

Responsive layout switching: different Flex configurations per breakpoint.

veb_tree

Cache-oblivious van Emde Boas tree layout for widget traversal (bd-xwkon).

visibility

Breakpoint-based visibility helpers.

workspace

Persisted workspace schema v1 with versioning and migration scaffolding.

Structs

Breakpoints

Breakpoint thresholds for responsive layouts.

Flex

A flexible layout container.

LayoutSizeHint

Size hint returned by measurer callbacks for intrinsic sizing.

Measurement

Size negotiation hints for layout.

Rect

A rectangle for scissor regions, layout bounds, and hit testing.

Sides

Sides for padding/margin.

Size

A 2D size in terminal cells.

Enums

Alignment

Alignment of items within the layout.

Breakpoint

Responsive breakpoint tiers for terminal widths.

Constraint

A constraint on the size of a layout area.

Direction

The direction to layout items.

OverflowBehavior

How a layout container handles content that exceeds available space.

Functions

round_layout_stable

Round real-valued layout targets to integer cells with exact sum conservation.

Type Aliases

PreviousAllocation

Previous frame’s allocation, used as tie-breaker for temporal stability.

Rects

Stack-inlined vector of rectangles returned by layout split operations.