Rout: A Rust UI Layout Engine

A high-performance, immediate-mode UI layout library inspired by Clay. Built for microsecond layout performance with zero-allocation hot paths.

Design Philosophy

Rout preserves Clay's core strengths while leveraging Rust's type system and safety guarantees:

• Zero-allocation hot path - all allocations happen upfront during initialization
• Immediate mode semantics - complete UI rebuilt each frame for simplicity and correctness
• Microsecond performance - matching or exceeding the original C implementation
• Single crate distribution - minimal dependencies, maximum portability
• Renderer agnostic - clean separation of layout calculation from rendering
• Memory safe - leveraging Rust's ownership system instead of manual memory management

Architecture Overview

Memory Model

Instead of Clay's manual arena allocation, Rout uses Rust's type system for compile-time memory management:

// Pre-allocated pools with compile-time sizing
pub struct LayoutArena<const MAX_ELEMENTS: usize = 8192> {
    elements: Vec<LayoutElement>,         // Pre-allocated capacity
    render_commands: Vec<RenderCommand>,  // Pre-allocated capacity
    text_cache: HashMap<TextCacheKey, Dimensions>, // Bounded size
}

Benefits:

• Compile-time memory bounds checking
• Zero allocations during layout (just indexing)
• Memory safety without runtime cost
• Configurable limits via const generics

API Design

Clay's macro-heavy C API maps to Rust's builder pattern for better ergonomics:

// Instead of Clay's: CLAY({ .id = CLAY_ID("Button"), .layout = {...} }) { ... }
ui.container()
    .id("Button")
    .padding(16)
    .child_gap(8)
    .children(|ui| {
        ui.text("Click me")
            .font_size(16)
            .color(Color::RED);
    });

Performance Strategy

1. SIMD layout calculations - Rust's portable SIMD for vectorized operations
2. Branch-free hot paths - leverage Rust's pattern matching optimization
3. Cache-friendly data layout - struct-of-arrays where beneficial
4. Compile-time optimization - const evaluation and zero-cost abstractions

Error Handling

Replace Clay's callback-based error handling with Rust's Result types:

pub type LayoutResult<T> = Result<T, LayoutError>;

#[derive(Debug, Clone)]
pub enum LayoutError {
    ElementLimitExceeded { current: usize, max: usize },
    InvalidElementId(String),
    TextMeasurementFailed(String),
    InvalidDimensions { width: f32, height: f32 },
}

Text Measurement Abstraction

Support multiple text backends through a trait:

pub trait TextMeasurer: Send + Sync {
    fn measure(&self, text: &str, config: &TextConfig) -> Dimensions;
    fn cache_key(&self, text: &str, config: &TextConfig) -> u64;
}

// Example implementations
impl TextMeasurer for FontkitMeasurer { ... }
impl TextMeasurer for CosmicTextMeasurer { ... }
impl TextMeasurer for CustomMeasurer { ... }

WASM Compatibility

Rust's excellent WASM support enables:

• Compile to WASM with minimal size using wee_alloc
• Export C-compatible API via extern "C" functions
• Provide high-level JS bindings via wasm-bindgen
• Single codebase targeting both web and native platforms

Implementation Plan

Phase 1: Core Layout Engine

• [X] Memory arena and element management
• [X] Basic layout calculation (sizing, positioning)
• [X] Flexbox-style layout algorithms
• [X] Text measurement integration

Phase 2: Element System

• [X] Element declaration and configuration
• [X] Layout containers (padding, gaps, alignment)
• [X] Text elements with wrapping
• [X] Image and custom elements

Phase 3: Advanced Features

• [X] Scrolling containers with momentum
• [X] Floating/absolute positioned elements
• [X] Pointer interaction system
• [X] Clipping and overflow handling

Phase 4: Platform Integration

• [X] WASM compilation and JS bindings
• [X] C FFI compatibility layer
• [X] Multiple text rendering backends
• [X] Debug visualization tools

Phase 5: Optimization & Polish

• [X] SIMD optimizations
• [X] Benchmark suite vs Clay
• [X] Memory usage analysis
• [X] API ergonomics refinement

Target Performance

• Layout calculation: < 100μs for 1000+ elements
• Memory usage: < 4MB for 8192 elements
• WASM size: < 20KB compressed
• Zero allocations during layout hot path
• Thread safety for multi-context usage

License

Licensed under the MIT License (LICENSE).

Acknowledgments

Inspired by Clay by Nic Barker. This project aims to bring Clay's excellent immediate-mode layout philosophy to the Rust ecosystem while maintaining its performance characteristics.