Module state_persistence 

Widget state persistence for save/restore across sessions.

This module provides the StateRegistry and StorageBackend infrastructure for persisting widget state. It works with the Stateful trait from ftui-widgets.

Architecture

┌──────────────────────────────────────────────────────────────┐
│                      StateRegistry                            │
│   - In-memory cache of widget states                          │
│   - Delegates to StorageBackend for persistence               │
│   - Provides load/save/clear operations                       │
└──────────────────────────────────────────────────────────────┘
                             │
                             ▼
┌──────────────────────────────────────────────────────────────┐
│                     StorageBackend                            │
│   - MemoryStorage: in-memory (testing, ephemeral)             │
│   - FileStorage: JSON file (requires state-persistence)       │
└──────────────────────────────────────────────────────────────┘

Design Invariants

1. Graceful degradation: Storage failures never panic; operations return Result.
2. Atomic writes: File storage uses write-rename pattern to prevent corruption.
3. Partial load tolerance: Missing or corrupt entries use Default::default().
4. Type safety: Registry is type-erased internally but type-safe at boundaries.

Failure Modes

Failure	Cause	Behavior
StorageError::Io	File I/O failure	Returns error, cache unaffected
StorageError::Serialization	JSON encode/decode	Entry skipped, logged
StorageError::Corruption	Invalid file format	Load returns partial data
Missing entry	First run, key changed	Default::default() used

Feature Gates

• state-persistence: Enables FileStorage with JSON serialization. Without this feature, only MemoryStorage is available.

Structs

MemoryStorage

In-memory storage backend for testing and ephemeral state.

RegistryStats

Statistics about the state registry.

StateRegistry

Central registry for widget state persistence.

StoredEntry

A serialized state entry with version metadata.

Enums

StorageError

Errors that can occur during state storage operations.

Traits

StorageBackend

Trait for pluggable state storage backends.

Type Aliases

StorageResult

Result type for storage operations.