Skip to main content

ftui_widgets/
stateful.rs

1//! Opt-in trait for widgets with persistable state.
2//!
3//! The [`Stateful`] trait defines a contract for widgets that can save and
4//! restore their state across sessions or configuration changes. It is
5//! orthogonal to [`StatefulWidget`] — a widget can
6//! implement both (render-time state mutation + persistence) or just one.
7//!
8//! # Design Invariants
9//!
10//! 1. **Round-trip fidelity**: `restore_state(save_state())` must produce an
11//!    equivalent observable state. Fields that are purely derived (e.g., cached
12//!    layout) may differ, but user-facing state (scroll position, selection,
13//!    expanded nodes) must survive the round trip.
14//!
15//! 2. **Graceful version mismatch**: When [`VersionedState`] detects a version
16//!    mismatch (`stored.version != T::state_version()`), the caller should fall
17//!    back to `T::State::default()` rather than panic. Migration logic belongs
18//!    in the downstream state migration system (bd-30g1.5).
19//!
20//! 3. **Key uniqueness**: Two distinct widget instances must never produce the
21//!    same [`StateKey`]. The `(widget_type, instance_id)` pair is the primary
22//!    uniqueness invariant. An instance with no stable identity returns `None`
23//!    from [`Stateful::state_key`] and is not persisted: the library widgets
24//!    return a key only once given a `persistence_id`, because deriving one
25//!    for them made every unnamed instance of a type share `"default"`.
26//!
27//! 4. **No side effects**: `save_state` must be a pure read; `restore_state`
28//!    must only mutate `self` (no I/O, no global state).
29//!
30//! # Failure Modes
31//!
32//! | Failure | Cause | Fallback |
33//! |---------|-------|----------|
34//! | Deserialization error | Schema drift, corrupt data | Use `Default::default()` |
35//! | Version mismatch | Widget upgraded | Use `Default::default()` |
36//! | Missing state | First run, key changed | Use `Default::default()` |
37//! | Duplicate key | Bug in `state_key()` impl | Last-write-wins (logged) |
38//!
39//! # Feature Gate
40//!
41//! This module is always available, but the serde-based [`VersionedState`]
42//! wrapper requires the `state-persistence` feature for serialization support.
43
44use core::fmt;
45use core::hash::{Hash, Hasher};
46
47/// Unique identifier for a widget's persisted state.
48///
49/// A `StateKey` is the `(widget_type, instance_id)` pair that maps a widget
50/// instance to its stored state blob. Widget type is a `&'static str` (cheap
51/// to copy, no allocation) while instance id is an owned `String` to support
52/// dynamic widget trees.
53///
54/// # Construction
55///
56/// ```
57/// # use ftui_widgets::stateful::StateKey;
58/// // Explicit
59/// let key = StateKey::new("ScrollView", "main-content");
60///
61/// // From a widget-tree path
62/// let key = StateKey::from_path(&["app", "sidebar", "tree"]);
63/// assert_eq!(key.instance_id, "app/sidebar/tree");
64/// ```
65#[derive(Clone, Debug, Eq, PartialEq)]
66pub struct StateKey {
67    /// The widget type name (e.g., `"ScrollView"`, `"TreeView"`).
68    pub widget_type: &'static str,
69    /// Instance-unique identifier within a widget tree.
70    pub instance_id: String,
71}
72
73impl StateKey {
74    /// Create a new state key from a widget type and instance id.
75    #[must_use]
76    pub fn new(widget_type: &'static str, id: impl Into<String>) -> Self {
77        Self {
78            widget_type,
79            instance_id: id.into(),
80        }
81    }
82
83    /// Build a state key from a path of widget-tree segments.
84    ///
85    /// Segments are joined with `/` to form the instance id.
86    /// The widget type is derived from the last segment.
87    ///
88    /// # Panics
89    ///
90    /// Panics if `path` is empty.
91    #[must_use]
92    pub fn from_path(path: &[&str]) -> Self {
93        assert!(
94            !path.is_empty(),
95            "StateKey::from_path requires a non-empty path"
96        );
97        let widget_type_str = path.last().expect("checked non-empty");
98        // We need a &'static str for widget_type. Since the caller passes &str
99        // slices that may or may not be 'static, we leak a copy. This is fine
100        // because state keys are created once and live for the program lifetime.
101        let widget_type: &'static str = Box::leak((*widget_type_str).to_owned().into_boxed_str());
102        Self {
103            widget_type,
104            instance_id: path.join("/"),
105        }
106    }
107
108    /// Canonical string representation: `"widget_type::instance_id"`.
109    #[must_use]
110    pub fn canonical(&self) -> String {
111        format!("{}::{}", self.widget_type, self.instance_id)
112    }
113}
114
115impl Hash for StateKey {
116    fn hash<H: Hasher>(&self, state: &mut H) {
117        self.widget_type.hash(state);
118        self.instance_id.hash(state);
119    }
120}
121
122impl fmt::Display for StateKey {
123    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
124        write!(f, "{}::{}", self.widget_type, self.instance_id)
125    }
126}
127
128/// Opt-in trait for widgets with persistable state.
129///
130/// Implementing this trait signals that a widget's user-facing state can be
131/// serialized, stored, and later restored. This is used by the state registry
132/// (bd-30g1.2) to persist widget state across sessions.
133///
134/// # Relationship to `StatefulWidget`
135///
136/// - [`StatefulWidget`](super::StatefulWidget): render-time mutable state (scroll clamping, layout cache).
137/// - [`Stateful`]: persistence contract (save/restore across sessions).
138///
139/// A widget can implement both when its render-time state is also worth persisting.
140///
141/// # Example
142///
143/// ```ignore
144/// use serde::{Serialize, Deserialize};
145/// use ftui_widgets::stateful::{Stateful, StateKey};
146///
147/// #[derive(Serialize, Deserialize, Default)]
148/// struct ScrollViewPersist {
149///     scroll_offset: u16,
150/// }
151///
152/// impl Stateful for ScrollView {
153///     type State = ScrollViewPersist;
154///
155///     fn state_key(&self) -> Option<StateKey> {
156///         Some(StateKey::new("ScrollView", &self.id))
157///     }
158///
159///     fn save_state(&self) -> Self::State {
160///         ScrollViewPersist { scroll_offset: self.offset }
161///     }
162///
163///     fn restore_state(&mut self, state: Self::State) {
164///         self.offset = state.scroll_offset.min(self.max_offset());
165///     }
166/// }
167/// ```
168pub trait Stateful: Sized {
169    /// The state type that gets persisted.
170    ///
171    /// Must implement `Default` so missing/corrupt state degrades gracefully.
172    type State: Default;
173
174    /// Unique key identifying this widget instance, or `None` if it has no
175    /// stable identity and must not be persisted.
176    ///
177    /// Two distinct widget instances **must not** return the same key.
178    /// Return `None` rather than a shared fallback id: a shared id makes a
179    /// registry keyed on it restore every such instance to one state.
180    fn state_key(&self) -> Option<StateKey>;
181
182    /// Extract current state for persistence.
183    ///
184    /// This must be a pure read — no side effects, no I/O.
185    fn save_state(&self) -> Self::State;
186
187    /// Restore state from persistence.
188    ///
189    /// Implementations should clamp restored values to valid ranges
190    /// (e.g., scroll offset ≤ max offset) rather than trusting stored data.
191    fn restore_state(&mut self, state: Self::State);
192
193    /// State schema version for forward-compatible migrations.
194    ///
195    /// Bump this when the `State` type's serialized form changes in a
196    /// backwards-incompatible way. The state registry will discard stored
197    /// state with a mismatched version and fall back to `Default`.
198    fn state_version() -> u32 {
199        1
200    }
201}
202
203/// Version-tagged wrapper for serialized widget state.
204///
205/// When persisting state, the registry wraps the raw state in this envelope
206/// so it can detect schema version mismatches on restore.
207///
208/// # Serialization
209///
210/// With the `state-persistence` feature enabled, `VersionedState` derives
211/// `Serialize` and `Deserialize`. Without the feature, it is a plain struct
212/// usable for in-memory versioning.
213#[derive(Clone, Debug)]
214#[cfg_attr(
215    feature = "state-persistence",
216    derive(serde::Serialize, serde::Deserialize)
217)]
218pub struct VersionedState<S> {
219    /// Schema version (from `Stateful::state_version()`).
220    pub version: u32,
221    /// The actual state payload.
222    pub data: S,
223}
224
225impl<S> VersionedState<S> {
226    /// Wrap state with its current version tag.
227    #[must_use]
228    pub fn new(version: u32, data: S) -> Self {
229        Self { version, data }
230    }
231
232    /// Pack a widget's state into a versioned envelope.
233    pub fn pack<W: Stateful<State = S>>(widget: &W) -> Self {
234        Self {
235            version: W::state_version(),
236            data: widget.save_state(),
237        }
238    }
239
240    /// Attempt to unpack, returning `None` if the version does not match
241    /// the widget's current `state_version()`.
242    #[must_use = "use the unpacked state (if any)"]
243    pub fn unpack<W: Stateful<State = S>>(self) -> Option<S> {
244        if self.version == W::state_version() {
245            Some(self.data)
246        } else {
247            None
248        }
249    }
250
251    /// Unpack with fallback: returns the stored data if versions match,
252    /// otherwise returns `S::default()`.
253    pub fn unpack_or_default<W: Stateful<State = S>>(self) -> S
254    where
255        S: Default,
256    {
257        if self.version == W::state_version() {
258            self.data
259        } else {
260            S::default()
261        }
262    }
263}
264
265impl<S: Default> Default for VersionedState<S> {
266    fn default() -> Self {
267        Self {
268            version: 1,
269            data: S::default(),
270        }
271    }
272}
273
274// ============================================================================
275// State Migration System (bd-30g1.5)
276// ============================================================================
277
278/// Error that can occur during state migration.
279#[derive(Debug, Clone)]
280pub enum MigrationError {
281    /// No migration path exists from source to target version.
282    NoPathFound { from: u32, to: u32 },
283    /// A migration function returned an error.
284    MigrationFailed { from: u32, to: u32, message: String },
285    /// Version numbers are invalid (e.g., target < source).
286    InvalidVersionRange { from: u32, to: u32 },
287}
288
289impl core::fmt::Display for MigrationError {
290    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
291        match self {
292            Self::NoPathFound { from, to } => {
293                write!(f, "no migration path from version {} to {}", from, to)
294            }
295            Self::MigrationFailed { from, to, message } => {
296                write!(f, "migration from {} to {} failed: {}", from, to, message)
297            }
298            Self::InvalidVersionRange { from, to } => {
299                write!(f, "invalid version range: {} to {}", from, to)
300            }
301        }
302    }
303}
304
305/// A single-step migration from version N to version N+1.
306///
307/// Migrations are always forward-only and increment by exactly one version.
308/// This ensures a clear, auditable upgrade path.
309///
310/// # Example
311///
312/// ```ignore
313/// // Migration from v1 ScrollState to v2 ScrollState (adds new field)
314/// struct ScrollStateV1ToV2;
315///
316/// impl StateMigration for ScrollStateV1ToV2 {
317///     type OldState = ScrollStateV1;
318///     type NewState = ScrollStateV2;
319///
320///     fn from_version(&self) -> u32 { 1 }
321///     fn to_version(&self) -> u32 { 2 }
322///
323///     fn migrate(&self, old: ScrollStateV1) -> Result<ScrollStateV2, String> {
324///         Ok(ScrollStateV2 {
325///             scroll_offset: old.scroll_offset,
326///             scroll_velocity: 0.0, // New field, default value
327///         })
328///     }
329/// }
330/// ```
331#[allow(clippy::wrong_self_convention)]
332pub trait StateMigration {
333    /// The state type before migration.
334    type OldState;
335    /// The state type after migration.
336    type NewState;
337
338    /// Source version this migration transforms from.
339    fn from_version(&self) -> u32;
340
341    /// Target version this migration produces.
342    /// Must equal `from_version() + 1`.
343    fn to_version(&self) -> u32;
344
345    /// Perform the migration.
346    ///
347    /// Returns `Err` with a message if the migration cannot be performed.
348    fn migrate(&self, old: Self::OldState) -> Result<Self::NewState, String>;
349}
350
351/// A type-erased migration step for use in migration chains.
352///
353/// This allows storing migrations with different types in a single collection.
354#[allow(clippy::wrong_self_convention)]
355pub trait ErasedMigration<S>: Send + Sync {
356    /// Source version.
357    fn from_version(&self) -> u32;
358    /// Target version.
359    fn to_version(&self) -> u32;
360    /// Perform migration on boxed state, returning boxed result.
361    fn migrate_erased(
362        &self,
363        old: Box<dyn core::any::Any + Send>,
364    ) -> Result<Box<dyn core::any::Any + Send>, String>;
365}
366
367/// A chain of migrations that can upgrade state through multiple versions.
368///
369/// # Design
370///
371/// The migration chain executes migrations in sequence, starting from the
372/// stored version and ending at the current version. Each step increments
373/// the version by exactly one.
374///
375/// # Example
376///
377/// ```ignore
378/// let mut chain = MigrationChain::<FinalState>::new();
379/// chain.register(Box::new(V1ToV2Migration));
380/// chain.register(Box::new(V2ToV3Migration));
381///
382/// // Migrate from v1 to v3 (current)
383/// let result = chain.migrate_to_current(v1_state, 1, 3);
384/// ```
385pub struct MigrationChain<S> {
386    /// Migrations indexed by their `from_version`.
387    migrations: std::collections::HashMap<u32, Box<dyn ErasedMigration<S>>>,
388}
389
390impl<S: 'static> MigrationChain<S> {
391    /// Create an empty migration chain.
392    #[must_use]
393    pub fn new() -> Self {
394        Self {
395            migrations: std::collections::HashMap::new(),
396        }
397    }
398
399    /// Register a migration step.
400    ///
401    /// # Panics
402    ///
403    /// Panics if a migration for the same `from_version` is already registered.
404    pub fn register(&mut self, migration: Box<dyn ErasedMigration<S>>) {
405        let from = migration.from_version();
406        let to = migration.to_version();
407        assert_eq!(
408            to,
409            from + 1,
410            "migration must increment version by exactly 1 (got {} -> {})",
411            from,
412            to
413        );
414        assert!(
415            !self.migrations.contains_key(&from),
416            "migration for version {} already registered",
417            from
418        );
419        self.migrations.insert(from, migration);
420    }
421
422    /// Check if a migration path exists from `from_version` to `to_version`.
423    #[must_use]
424    pub fn has_path(&self, from_version: u32, to_version: u32) -> bool {
425        if from_version >= to_version {
426            return from_version == to_version;
427        }
428        let mut current = from_version;
429        while current < to_version {
430            if !self.migrations.contains_key(&current) {
431                return false;
432            }
433            current += 1;
434        }
435        true
436    }
437
438    /// Attempt to migrate state from `from_version` to `to_version`.
439    ///
440    /// Returns `Ok(migrated_state)` on success, or `Err` if migration fails.
441    pub fn migrate(
442        &self,
443        state: Box<dyn core::any::Any + Send>,
444        from_version: u32,
445        to_version: u32,
446    ) -> Result<Box<dyn core::any::Any + Send>, MigrationError> {
447        if from_version > to_version {
448            return Err(MigrationError::InvalidVersionRange {
449                from: from_version,
450                to: to_version,
451            });
452        }
453        if from_version == to_version {
454            return Ok(state);
455        }
456
457        let mut current_state = state;
458        let mut current_version = from_version;
459
460        while current_version < to_version {
461            let migration =
462                self.migrations
463                    .get(&current_version)
464                    .ok_or(MigrationError::NoPathFound {
465                        from: current_version,
466                        to: to_version,
467                    })?;
468
469            current_state = migration.migrate_erased(current_state).map_err(|msg| {
470                MigrationError::MigrationFailed {
471                    from: current_version,
472                    to: current_version + 1,
473                    message: msg,
474                }
475            })?;
476
477            current_version += 1;
478        }
479
480        Ok(current_state)
481    }
482}
483
484impl<S: 'static> Default for MigrationChain<S> {
485    fn default() -> Self {
486        Self::new()
487    }
488}
489
490/// Result of attempting state restoration with migration.
491#[derive(Debug)]
492pub enum RestoreResult<S> {
493    /// State was restored directly (versions matched).
494    Direct(S),
495    /// State was successfully migrated from an older version.
496    Migrated { state: S, from_version: u32 },
497    /// Migration failed; falling back to default state.
498    DefaultFallback { error: MigrationError, default: S },
499}
500
501impl<S> RestoreResult<S> {
502    /// Extract the state value, regardless of how it was obtained.
503    pub fn into_state(self) -> S {
504        match self {
505            Self::Direct(s) | Self::Migrated { state: s, .. } => s,
506            Self::DefaultFallback { default, .. } => default,
507        }
508    }
509
510    /// Returns `true` if the state was migrated.
511    #[must_use]
512    pub fn was_migrated(&self) -> bool {
513        matches!(self, Self::Migrated { .. })
514    }
515
516    /// Returns `true` if we fell back to default.
517    #[must_use]
518    pub fn is_fallback(&self) -> bool {
519        matches!(self, Self::DefaultFallback { .. })
520    }
521}
522
523impl<S> VersionedState<S> {
524    /// Attempt to unpack with migration support.
525    ///
526    /// If the stored version doesn't match the current version, attempts to
527    /// migrate through the provided chain. Falls back to default on failure.
528    ///
529    /// # Type Parameters
530    ///
531    /// - `W`: The widget type that implements `Stateful<State = S>`.
532    ///
533    /// # Example
534    ///
535    /// ```ignore
536    /// let chain = MigrationChain::new();
537    /// // ... register migrations ...
538    ///
539    /// let versioned = load_state_from_disk();
540    /// let result = versioned.unpack_with_migration::<MyWidget>(&chain);
541    /// let state = result.into_state();
542    /// ```
543    pub fn unpack_with_migration<W>(self, chain: &MigrationChain<S>) -> RestoreResult<S>
544    where
545        W: Stateful<State = S>,
546        S: Default + 'static + Send,
547    {
548        let current_version = W::state_version();
549
550        if self.version == current_version {
551            return RestoreResult::Direct(self.data);
552        }
553
554        // Try migration
555        let boxed: Box<dyn core::any::Any + Send> = Box::new(self.data);
556        match chain.migrate(boxed, self.version, current_version) {
557            Ok(migrated) => {
558                if let Ok(state) = migrated.downcast::<S>() {
559                    RestoreResult::Migrated {
560                        state: *state,
561                        from_version: self.version,
562                    }
563                } else {
564                    // Type mismatch after migration (shouldn't happen with correct chain)
565                    RestoreResult::DefaultFallback {
566                        error: MigrationError::MigrationFailed {
567                            from: self.version,
568                            to: current_version,
569                            message: "type mismatch after migration".to_string(),
570                        },
571                        default: S::default(),
572                    }
573                }
574            }
575            Err(e) => RestoreResult::DefaultFallback {
576                error: e,
577                default: S::default(),
578            },
579        }
580    }
581}
582
583#[cfg(test)]
584mod tests {
585    use super::*;
586
587    // ── Test widget ─────────────────────────────────────────────────
588
589    #[derive(Default)]
590    struct TestScrollView {
591        id: String,
592        offset: u16,
593        max: u16,
594    }
595
596    #[derive(Clone, Debug, Default, PartialEq)]
597    struct ScrollState {
598        scroll_offset: u16,
599    }
600
601    impl Stateful for TestScrollView {
602        type State = ScrollState;
603
604        fn state_key(&self) -> Option<StateKey> {
605            Some(StateKey::new("ScrollView", &self.id))
606        }
607
608        fn save_state(&self) -> ScrollState {
609            ScrollState {
610                scroll_offset: self.offset,
611            }
612        }
613
614        fn restore_state(&mut self, state: ScrollState) {
615            self.offset = state.scroll_offset.min(self.max);
616        }
617    }
618
619    // ── Another test widget with version 2 ──────────────────────────
620
621    #[derive(Default)]
622    struct TestTreeView {
623        id: String,
624        expanded: Vec<u32>,
625    }
626
627    #[derive(Clone, Debug, Default, PartialEq)]
628    struct TreeState {
629        expanded_nodes: Vec<u32>,
630        collapse_all_on_blur: bool, // added in v2
631    }
632
633    impl Stateful for TestTreeView {
634        type State = TreeState;
635
636        fn state_key(&self) -> Option<StateKey> {
637            Some(StateKey::new("TreeView", &self.id))
638        }
639
640        fn save_state(&self) -> TreeState {
641            TreeState {
642                expanded_nodes: self.expanded.clone(),
643                collapse_all_on_blur: false,
644            }
645        }
646
647        fn restore_state(&mut self, state: TreeState) {
648            self.expanded = state.expanded_nodes;
649        }
650
651        fn state_version() -> u32 {
652            2
653        }
654    }
655
656    // ── StateKey tests ──────────────────────────────────────────────
657
658    #[test]
659    fn state_key_new() {
660        let key = StateKey::new("ScrollView", "main");
661        assert_eq!(key.widget_type, "ScrollView");
662        assert_eq!(key.instance_id, "main");
663    }
664
665    #[test]
666    fn state_key_from_path() {
667        let key = StateKey::from_path(&["app", "sidebar", "tree"]);
668        assert_eq!(key.instance_id, "app/sidebar/tree");
669        assert_eq!(key.widget_type, "tree");
670    }
671
672    #[test]
673    #[should_panic(expected = "non-empty path")]
674    fn state_key_from_empty_path_panics() {
675        let _ = StateKey::from_path(&[]);
676    }
677
678    #[test]
679    fn state_key_uniqueness() {
680        let a = StateKey::new("ScrollView", "main");
681        let b = StateKey::new("ScrollView", "sidebar");
682        let c = StateKey::new("TreeView", "main");
683        assert_ne!(a, b);
684        assert_ne!(a, c);
685        assert_ne!(b, c);
686    }
687
688    #[test]
689    fn state_key_equality() {
690        let a = StateKey::new("ScrollView", "main");
691        let b = StateKey::new("ScrollView", "main");
692        assert_eq!(a, b);
693    }
694
695    #[test]
696    fn state_key_hash_consistency() {
697        use std::collections::hash_map::DefaultHasher;
698
699        let a = StateKey::new("ScrollView", "main");
700        let b = StateKey::new("ScrollView", "main");
701
702        let hash = |key: &StateKey| {
703            let mut h = DefaultHasher::new();
704            key.hash(&mut h);
705            h.finish()
706        };
707        assert_eq!(hash(&a), hash(&b));
708    }
709
710    #[test]
711    fn state_key_display() {
712        let key = StateKey::new("ScrollView", "main");
713        assert_eq!(key.to_string(), "ScrollView::main");
714    }
715
716    #[test]
717    fn state_key_canonical() {
718        let key = StateKey::new("ScrollView", "main");
719        assert_eq!(key.canonical(), "ScrollView::main");
720    }
721
722    // ── Save/restore round-trip tests ───────────────────────────────
723
724    #[test]
725    fn save_restore_round_trip() {
726        let mut widget = TestScrollView {
727            id: "content".into(),
728            offset: 42,
729            max: 100,
730        };
731
732        let saved = widget.save_state();
733        assert_eq!(saved.scroll_offset, 42);
734
735        widget.offset = 0; // reset
736        widget.restore_state(saved);
737        assert_eq!(widget.offset, 42);
738    }
739
740    #[test]
741    fn restore_clamps_to_valid_range() {
742        let mut widget = TestScrollView {
743            id: "content".into(),
744            offset: 0,
745            max: 10,
746        };
747
748        // Stored state exceeds current max
749        widget.restore_state(ScrollState { scroll_offset: 999 });
750        assert_eq!(widget.offset, 10);
751    }
752
753    #[test]
754    fn default_state_on_missing() {
755        let mut widget = TestScrollView {
756            id: "new".into(),
757            offset: 5,
758            max: 100,
759        };
760
761        widget.restore_state(ScrollState::default());
762        assert_eq!(widget.offset, 0);
763    }
764
765    // ── Version tests ───────────────────────────────────────────────
766
767    #[test]
768    fn default_state_version_is_one() {
769        assert_eq!(TestScrollView::state_version(), 1);
770    }
771
772    #[test]
773    fn custom_state_version() {
774        assert_eq!(TestTreeView::state_version(), 2);
775    }
776
777    // ── VersionedState tests ────────────────────────────────────────
778
779    #[test]
780    fn versioned_state_pack_unpack() {
781        let widget = TestScrollView {
782            id: "main".into(),
783            offset: 77,
784            max: 100,
785        };
786
787        let packed = VersionedState::pack(&widget);
788        assert_eq!(packed.version, 1);
789        assert_eq!(packed.data.scroll_offset, 77);
790
791        let unpacked = packed.unpack::<TestScrollView>();
792        assert!(unpacked.is_some());
793        assert_eq!(unpacked.unwrap().scroll_offset, 77);
794    }
795
796    #[test]
797    fn versioned_state_version_mismatch_returns_none() {
798        // Simulate stored state from version 1, but widget expects version 2
799        let stored = VersionedState::<TreeState> {
800            version: 1,
801            data: TreeState::default(),
802        };
803
804        let result = stored.unpack::<TestTreeView>();
805        assert!(result.is_none());
806    }
807
808    #[test]
809    fn versioned_state_unpack_or_default_on_mismatch() {
810        let stored = VersionedState::<TreeState> {
811            version: 1,
812            data: TreeState {
813                expanded_nodes: vec![1, 2, 3],
814                collapse_all_on_blur: true,
815            },
816        };
817
818        let result = stored.unpack_or_default::<TestTreeView>();
819        // Should return default because version 1 != expected 2
820        assert_eq!(result, TreeState::default());
821    }
822
823    #[test]
824    fn versioned_state_unpack_or_default_on_match() {
825        let stored = VersionedState::<ScrollState> {
826            version: 1,
827            data: ScrollState { scroll_offset: 55 },
828        };
829
830        let result = stored.unpack_or_default::<TestScrollView>();
831        assert_eq!(result.scroll_offset, 55);
832    }
833
834    #[test]
835    fn versioned_state_default() {
836        let vs = VersionedState::<ScrollState>::default();
837        assert_eq!(vs.version, 1);
838        assert_eq!(vs.data, ScrollState::default());
839    }
840
841    // ── Migration System tests ─────────────────────────────────────────
842
843    #[test]
844    fn migration_error_display() {
845        let err = MigrationError::NoPathFound { from: 1, to: 3 };
846        assert_eq!(err.to_string(), "no migration path from version 1 to 3");
847
848        let err = MigrationError::MigrationFailed {
849            from: 2,
850            to: 3,
851            message: "data corrupt".into(),
852        };
853        assert_eq!(
854            err.to_string(),
855            "migration from 2 to 3 failed: data corrupt"
856        );
857
858        let err = MigrationError::InvalidVersionRange { from: 5, to: 2 };
859        assert_eq!(err.to_string(), "invalid version range: 5 to 2");
860    }
861
862    #[test]
863    fn migration_chain_new_is_empty() {
864        let chain = MigrationChain::<ScrollState>::new();
865        assert!(!chain.has_path(1, 2));
866    }
867
868    // Test migration from v1 ScrollState (just offset) to v2 (with hypothetical field)
869    #[derive(Debug, Clone, Default)]
870    struct ScrollStateV1 {
871        scroll_offset: u16,
872    }
873
874    #[derive(Debug, Clone, Default)]
875    struct ScrollStateV2 {
876        scroll_offset: u16,
877        velocity: f32, // Added in v2
878    }
879
880    struct V1ToV2Migration;
881
882    impl ErasedMigration<ScrollStateV2> for V1ToV2Migration {
883        fn from_version(&self) -> u32 {
884            1
885        }
886        fn to_version(&self) -> u32 {
887            2
888        }
889        fn migrate_erased(
890            &self,
891            old: Box<dyn core::any::Any + Send>,
892        ) -> Result<Box<dyn core::any::Any + Send>, String> {
893            let v1 = old
894                .downcast::<ScrollStateV1>()
895                .map_err(|_| "invalid state type")?;
896            Ok(Box::new(ScrollStateV2 {
897                scroll_offset: v1.scroll_offset,
898                velocity: 0.0,
899            }))
900        }
901    }
902
903    #[test]
904    fn migration_chain_register_and_has_path() {
905        let mut chain = MigrationChain::<ScrollStateV2>::new();
906        chain.register(Box::new(V1ToV2Migration));
907
908        assert!(chain.has_path(1, 2));
909        assert!(chain.has_path(1, 1)); // Same version is valid
910        assert!(chain.has_path(2, 2)); // Same version is valid
911        assert!(!chain.has_path(1, 3)); // No migration to v3
912    }
913
914    #[test]
915    #[should_panic(expected = "migration must increment version by exactly 1")]
916    fn migration_chain_rejects_non_sequential_migration() {
917        struct BadMigration;
918        impl ErasedMigration<ScrollStateV2> for BadMigration {
919            fn from_version(&self) -> u32 {
920                1
921            }
922            fn to_version(&self) -> u32 {
923                3
924            } // Skips v2!
925            fn migrate_erased(
926                &self,
927                _: Box<dyn core::any::Any + Send>,
928            ) -> Result<Box<dyn core::any::Any + Send>, String> {
929                unreachable!()
930            }
931        }
932
933        let mut chain = MigrationChain::<ScrollStateV2>::new();
934        chain.register(Box::new(BadMigration));
935    }
936
937    #[test]
938    #[should_panic(expected = "migration for version 1 already registered")]
939    fn migration_chain_rejects_duplicate_registration() {
940        let mut chain = MigrationChain::<ScrollStateV2>::new();
941        chain.register(Box::new(V1ToV2Migration));
942        chain.register(Box::new(V1ToV2Migration)); // Duplicate!
943    }
944
945    #[test]
946    fn migration_chain_migrate_success() {
947        let mut chain = MigrationChain::<ScrollStateV2>::new();
948        chain.register(Box::new(V1ToV2Migration));
949
950        let old_state = Box::new(ScrollStateV1 { scroll_offset: 42 });
951        let result = chain.migrate(old_state, 1, 2);
952
953        assert!(result.is_ok());
954        let migrated = result
955            .unwrap()
956            .downcast::<ScrollStateV2>()
957            .expect("should be ScrollStateV2");
958        assert_eq!(migrated.scroll_offset, 42);
959        assert_eq!(migrated.velocity, 0.0);
960    }
961
962    #[test]
963    fn migration_chain_migrate_same_version() {
964        let chain = MigrationChain::<ScrollStateV2>::new();
965        let state = Box::new(ScrollStateV2 {
966            scroll_offset: 10,
967            velocity: 1.5,
968        });
969
970        let result = chain.migrate(state, 2, 2);
971        assert!(result.is_ok());
972    }
973
974    #[test]
975    fn migration_chain_migrate_no_path() {
976        let chain = MigrationChain::<ScrollStateV2>::new();
977        let state: Box<dyn core::any::Any + Send> = Box::new(ScrollStateV1 { scroll_offset: 0 });
978
979        let result = chain.migrate(state, 1, 2);
980        assert!(matches!(
981            result,
982            Err(MigrationError::NoPathFound { from: 1, to: 2 })
983        ));
984    }
985
986    #[test]
987    fn migration_chain_migrate_invalid_range() {
988        let chain = MigrationChain::<ScrollStateV2>::new();
989        let state: Box<dyn core::any::Any + Send> = Box::new(ScrollStateV2::default());
990
991        let result = chain.migrate(state, 3, 1);
992        assert!(matches!(
993            result,
994            Err(MigrationError::InvalidVersionRange { from: 3, to: 1 })
995        ));
996    }
997
998    #[test]
999    fn restore_result_into_state() {
1000        let direct = RestoreResult::Direct(ScrollState { scroll_offset: 10 });
1001        assert_eq!(direct.into_state().scroll_offset, 10);
1002
1003        let migrated = RestoreResult::Migrated {
1004            state: ScrollState { scroll_offset: 20 },
1005            from_version: 1,
1006        };
1007        assert_eq!(migrated.into_state().scroll_offset, 20);
1008
1009        let fallback = RestoreResult::DefaultFallback {
1010            error: MigrationError::NoPathFound { from: 1, to: 2 },
1011            default: ScrollState { scroll_offset: 0 },
1012        };
1013        assert_eq!(fallback.into_state().scroll_offset, 0);
1014    }
1015
1016    #[test]
1017    fn restore_result_was_migrated() {
1018        let direct = RestoreResult::Direct(ScrollState::default());
1019        assert!(!direct.was_migrated());
1020
1021        let migrated = RestoreResult::Migrated::<ScrollState> {
1022            state: ScrollState::default(),
1023            from_version: 1,
1024        };
1025        assert!(migrated.was_migrated());
1026
1027        let fallback = RestoreResult::DefaultFallback::<ScrollState> {
1028            error: MigrationError::NoPathFound { from: 1, to: 2 },
1029            default: ScrollState::default(),
1030        };
1031        assert!(!fallback.was_migrated());
1032    }
1033
1034    #[test]
1035    fn restore_result_is_fallback() {
1036        let direct = RestoreResult::Direct(ScrollState::default());
1037        assert!(!direct.is_fallback());
1038
1039        let migrated = RestoreResult::Migrated::<ScrollState> {
1040            state: ScrollState::default(),
1041            from_version: 1,
1042        };
1043        assert!(!migrated.is_fallback());
1044
1045        let fallback = RestoreResult::DefaultFallback::<ScrollState> {
1046            error: MigrationError::NoPathFound { from: 1, to: 2 },
1047            default: ScrollState::default(),
1048        };
1049        assert!(fallback.is_fallback());
1050    }
1051
1052    // ── Edge-case: StateKey ──────────────────────────────────────────
1053
1054    #[test]
1055    fn state_key_from_path_single_segment() {
1056        let key = StateKey::from_path(&["widget"]);
1057        assert_eq!(key.widget_type, "widget");
1058        assert_eq!(key.instance_id, "widget");
1059    }
1060
1061    #[test]
1062    fn state_key_from_path_two_segments() {
1063        let key = StateKey::from_path(&["parent", "child"]);
1064        assert_eq!(key.widget_type, "child");
1065        assert_eq!(key.instance_id, "parent/child");
1066    }
1067
1068    #[test]
1069    fn state_key_empty_instance_id() {
1070        let key = StateKey::new("Widget", "");
1071        assert_eq!(key.instance_id, "");
1072        assert_eq!(key.canonical(), "Widget::");
1073        assert_eq!(key.to_string(), "Widget::");
1074    }
1075
1076    #[test]
1077    fn state_key_canonical_matches_display() {
1078        let key = StateKey::new("TreeView", "sidebar/nav");
1079        assert_eq!(key.canonical(), key.to_string());
1080    }
1081
1082    #[test]
1083    fn state_key_clone() {
1084        let key = StateKey::new("Scroll", "main");
1085        let cloned = key.clone();
1086        assert_eq!(key, cloned);
1087        assert_eq!(key.widget_type, cloned.widget_type);
1088        assert_eq!(key.instance_id, cloned.instance_id);
1089    }
1090
1091    #[test]
1092    fn state_key_debug_format() {
1093        let key = StateKey::new("Foo", "bar");
1094        let dbg = format!("{:?}", key);
1095        assert!(dbg.contains("Foo"));
1096        assert!(dbg.contains("bar"));
1097    }
1098
1099    #[test]
1100    fn state_key_hash_differs_for_different_keys() {
1101        use std::collections::hash_map::DefaultHasher;
1102
1103        let hash = |key: &StateKey| {
1104            let mut h = DefaultHasher::new();
1105            key.hash(&mut h);
1106            h.finish()
1107        };
1108
1109        let a = StateKey::new("ScrollView", "main");
1110        let b = StateKey::new("ScrollView", "sidebar");
1111        let c = StateKey::new("TreeView", "main");
1112
1113        // Different instance_id → different hash (overwhelmingly likely)
1114        assert_ne!(hash(&a), hash(&b));
1115        // Different widget_type → different hash
1116        assert_ne!(hash(&a), hash(&c));
1117    }
1118
1119    #[test]
1120    fn state_key_usable_as_hashmap_key() {
1121        use std::collections::HashMap;
1122
1123        let mut map = HashMap::new();
1124        let key1 = StateKey::new("Scroll", "a");
1125        let key2 = StateKey::new("Scroll", "b");
1126
1127        map.insert(key1.clone(), 1);
1128        map.insert(key2.clone(), 2);
1129
1130        assert_eq!(map.get(&key1), Some(&1));
1131        assert_eq!(map.get(&key2), Some(&2));
1132        assert_eq!(map.len(), 2);
1133    }
1134
1135    #[test]
1136    fn state_key_from_path_with_empty_segments() {
1137        let key = StateKey::from_path(&["", "child"]);
1138        assert_eq!(key.instance_id, "/child");
1139        assert_eq!(key.widget_type, "child");
1140    }
1141
1142    // ── Edge-case: Stateful trait ────────────────────────────────────
1143
1144    #[test]
1145    fn save_state_on_default_widget() {
1146        let widget = TestScrollView::default();
1147        let state = widget.save_state();
1148        assert_eq!(state.scroll_offset, 0);
1149    }
1150
1151    #[test]
1152    fn restore_state_to_zero_max() {
1153        let mut widget = TestScrollView {
1154            id: "x".into(),
1155            offset: 0,
1156            max: 0,
1157        };
1158        widget.restore_state(ScrollState { scroll_offset: 100 });
1159        // Should clamp to max=0
1160        assert_eq!(widget.offset, 0);
1161    }
1162
1163    #[test]
1164    fn save_restore_preserves_max_u16() {
1165        let mut widget = TestScrollView {
1166            id: "w".into(),
1167            offset: u16::MAX,
1168            max: u16::MAX,
1169        };
1170        let saved = widget.save_state();
1171        assert_eq!(saved.scroll_offset, u16::MAX);
1172
1173        widget.offset = 0;
1174        widget.restore_state(saved);
1175        assert_eq!(widget.offset, u16::MAX);
1176    }
1177
1178    #[test]
1179    fn multiple_save_restore_cycles() {
1180        let mut widget = TestScrollView {
1181            id: "cycle".into(),
1182            offset: 10,
1183            max: 100,
1184        };
1185
1186        for i in 0..5 {
1187            widget.offset = i * 10;
1188            let saved = widget.save_state();
1189            widget.offset = 0;
1190            widget.restore_state(saved);
1191            assert_eq!(widget.offset, i * 10);
1192        }
1193    }
1194
1195    #[test]
1196    fn state_key_from_widget() {
1197        let widget = TestScrollView {
1198            id: "content-panel".into(),
1199            offset: 0,
1200            max: 50,
1201        };
1202        let key = widget.state_key().expect("an identified widget has a key");
1203        assert_eq!(key.widget_type, "ScrollView");
1204        assert_eq!(key.instance_id, "content-panel");
1205    }
1206
1207    #[test]
1208    fn tree_view_save_restore_round_trip() {
1209        let mut widget = TestTreeView {
1210            id: "files".into(),
1211            expanded: vec![1, 3, 5],
1212        };
1213        let saved = widget.save_state();
1214        assert_eq!(saved.expanded_nodes, vec![1, 3, 5]);
1215        assert!(!saved.collapse_all_on_blur);
1216
1217        widget.expanded = vec![];
1218        widget.restore_state(saved);
1219        assert_eq!(widget.expanded, vec![1, 3, 5]);
1220    }
1221
1222    // ── Edge-case: VersionedState ────────────────────────────────────
1223
1224    #[test]
1225    fn versioned_state_new_constructor() {
1226        let vs = VersionedState::new(42, ScrollState { scroll_offset: 7 });
1227        assert_eq!(vs.version, 42);
1228        assert_eq!(vs.data.scroll_offset, 7);
1229    }
1230
1231    #[test]
1232    fn versioned_state_clone() {
1233        let vs = VersionedState::new(1, ScrollState { scroll_offset: 5 });
1234        let cloned = vs.clone();
1235        assert_eq!(cloned.version, 1);
1236        assert_eq!(cloned.data.scroll_offset, 5);
1237    }
1238
1239    #[test]
1240    fn versioned_state_debug() {
1241        let vs = VersionedState::new(3, ScrollState { scroll_offset: 10 });
1242        let dbg = format!("{:?}", vs);
1243        assert!(dbg.contains("3"));
1244        assert!(dbg.contains("10"));
1245    }
1246
1247    #[test]
1248    fn versioned_state_unpack_version_match() {
1249        let vs = VersionedState::new(1, ScrollState { scroll_offset: 42 });
1250        let result = vs.unpack::<TestScrollView>();
1251        assert!(result.is_some());
1252        assert_eq!(result.unwrap().scroll_offset, 42);
1253    }
1254
1255    #[test]
1256    fn versioned_state_unpack_version_zero_mismatch() {
1257        // Version 0 doesn't match TestScrollView's version 1
1258        let vs = VersionedState::new(0, ScrollState { scroll_offset: 99 });
1259        assert!(vs.unpack::<TestScrollView>().is_none());
1260    }
1261
1262    #[test]
1263    fn versioned_state_unpack_future_version() {
1264        // Version 999 doesn't match TestScrollView's version 1
1265        let vs = VersionedState::new(999, ScrollState { scroll_offset: 1 });
1266        assert!(vs.unpack::<TestScrollView>().is_none());
1267    }
1268
1269    #[test]
1270    fn versioned_state_unpack_or_default_version_zero() {
1271        let vs = VersionedState::new(0, ScrollState { scroll_offset: 50 });
1272        let result = vs.unpack_or_default::<TestScrollView>();
1273        assert_eq!(result, ScrollState::default());
1274    }
1275
1276    #[test]
1277    fn versioned_state_default_for_tree_state() {
1278        let vs = VersionedState::<TreeState>::default();
1279        assert_eq!(vs.version, 1);
1280        assert!(vs.data.expanded_nodes.is_empty());
1281        assert!(!vs.data.collapse_all_on_blur);
1282    }
1283
1284    // ── Edge-case: MigrationError ────────────────────────────────────
1285
1286    #[test]
1287    fn migration_error_clone() {
1288        let err = MigrationError::NoPathFound { from: 1, to: 5 };
1289        let cloned = err.clone();
1290        assert_eq!(cloned.to_string(), "no migration path from version 1 to 5");
1291
1292        let err2 = MigrationError::MigrationFailed {
1293            from: 2,
1294            to: 3,
1295            message: "oops".into(),
1296        };
1297        let cloned2 = err2.clone();
1298        assert_eq!(cloned2.to_string(), "migration from 2 to 3 failed: oops");
1299
1300        let err3 = MigrationError::InvalidVersionRange { from: 10, to: 1 };
1301        let cloned3 = err3.clone();
1302        assert_eq!(cloned3.to_string(), "invalid version range: 10 to 1");
1303    }
1304
1305    #[test]
1306    fn migration_error_debug() {
1307        let err = MigrationError::NoPathFound { from: 1, to: 2 };
1308        let dbg = format!("{:?}", err);
1309        assert!(dbg.contains("NoPathFound"));
1310    }
1311
1312    // ── Edge-case: MigrationChain ────────────────────────────────────
1313
1314    #[test]
1315    fn migration_chain_default() {
1316        let chain = MigrationChain::<ScrollState>::default();
1317        assert!(!chain.has_path(1, 2));
1318    }
1319
1320    #[test]
1321    fn migration_chain_has_path_same_version() {
1322        let chain = MigrationChain::<ScrollState>::new();
1323        // Same version always returns true even with empty chain
1324        assert!(chain.has_path(0, 0));
1325        assert!(chain.has_path(5, 5));
1326        assert!(chain.has_path(u32::MAX, u32::MAX));
1327    }
1328
1329    #[test]
1330    fn migration_chain_has_path_from_greater_than_to() {
1331        let chain = MigrationChain::<ScrollState>::new();
1332        // from > to returns false (not equal)
1333        assert!(!chain.has_path(3, 1));
1334        assert!(!chain.has_path(2, 1));
1335    }
1336
1337    #[test]
1338    fn migration_chain_has_path_gap_in_chain() {
1339        // Register v1→v2, but not v2→v3, then check v1→v3
1340        let mut chain = MigrationChain::<ScrollStateV2>::new();
1341        chain.register(Box::new(V1ToV2Migration));
1342        assert!(chain.has_path(1, 2));
1343        assert!(!chain.has_path(1, 3)); // gap at v2→v3
1344    }
1345
1346    #[test]
1347    fn migration_chain_migrate_same_version_empty_chain() {
1348        let chain = MigrationChain::<ScrollState>::new();
1349        let state: Box<dyn core::any::Any + Send> = Box::new(ScrollState { scroll_offset: 77 });
1350        let result = chain.migrate(state, 5, 5);
1351        assert!(result.is_ok());
1352        let out = result.unwrap().downcast::<ScrollState>().unwrap();
1353        assert_eq!(out.scroll_offset, 77);
1354    }
1355
1356    #[test]
1357    fn migration_chain_migrate_invalid_range_adjacent() {
1358        let chain = MigrationChain::<ScrollState>::new();
1359        let state: Box<dyn core::any::Any + Send> = Box::new(ScrollState::default());
1360        let result = chain.migrate(state, 2, 1);
1361        assert!(matches!(
1362            result,
1363            Err(MigrationError::InvalidVersionRange { from: 2, to: 1 })
1364        ));
1365    }
1366
1367    // Multi-step migration v1→v2→v3
1368    #[derive(Debug, Clone, Default)]
1369    struct ScrollStateV3 {
1370        scroll_offset: u16,
1371        velocity: f32,
1372        smooth_scroll: bool, // Added in v3
1373    }
1374
1375    struct V2ToV3Migration;
1376
1377    impl ErasedMigration<ScrollStateV3> for V2ToV3Migration {
1378        fn from_version(&self) -> u32 {
1379            2
1380        }
1381        fn to_version(&self) -> u32 {
1382            3
1383        }
1384        fn migrate_erased(
1385            &self,
1386            old: Box<dyn core::any::Any + Send>,
1387        ) -> Result<Box<dyn core::any::Any + Send>, String> {
1388            let v2 = old
1389                .downcast::<ScrollStateV2>()
1390                .map_err(|_| "invalid state type")?;
1391            Ok(Box::new(ScrollStateV3 {
1392                scroll_offset: v2.scroll_offset,
1393                velocity: v2.velocity,
1394                smooth_scroll: true, // default for new field
1395            }))
1396        }
1397    }
1398
1399    struct V1ToV2ForV3Migration;
1400
1401    impl ErasedMigration<ScrollStateV3> for V1ToV2ForV3Migration {
1402        fn from_version(&self) -> u32 {
1403            1
1404        }
1405        fn to_version(&self) -> u32 {
1406            2
1407        }
1408        fn migrate_erased(
1409            &self,
1410            old: Box<dyn core::any::Any + Send>,
1411        ) -> Result<Box<dyn core::any::Any + Send>, String> {
1412            let v1 = old
1413                .downcast::<ScrollStateV1>()
1414                .map_err(|_| "invalid state type")?;
1415            Ok(Box::new(ScrollStateV2 {
1416                scroll_offset: v1.scroll_offset,
1417                velocity: 0.0,
1418            }))
1419        }
1420    }
1421
1422    #[test]
1423    fn migration_chain_multi_step_v1_to_v3() {
1424        let mut chain = MigrationChain::<ScrollStateV3>::new();
1425        chain.register(Box::new(V1ToV2ForV3Migration));
1426        chain.register(Box::new(V2ToV3Migration));
1427
1428        assert!(chain.has_path(1, 3));
1429        assert!(chain.has_path(1, 2));
1430        assert!(chain.has_path(2, 3));
1431
1432        let old = Box::new(ScrollStateV1 { scroll_offset: 55 });
1433        let result = chain.migrate(old, 1, 3);
1434        assert!(result.is_ok());
1435
1436        let migrated = result.unwrap().downcast::<ScrollStateV3>().unwrap();
1437        assert_eq!(migrated.scroll_offset, 55);
1438        assert_eq!(migrated.velocity, 0.0);
1439        assert!(migrated.smooth_scroll);
1440    }
1441
1442    // Failing migration
1443    struct FailingMigration;
1444
1445    impl ErasedMigration<ScrollStateV2> for FailingMigration {
1446        fn from_version(&self) -> u32 {
1447            1
1448        }
1449        fn to_version(&self) -> u32 {
1450            2
1451        }
1452        fn migrate_erased(
1453            &self,
1454            _: Box<dyn core::any::Any + Send>,
1455        ) -> Result<Box<dyn core::any::Any + Send>, String> {
1456            Err("data corruption detected".into())
1457        }
1458    }
1459
1460    #[test]
1461    fn migration_chain_migrate_failure() {
1462        let mut chain = MigrationChain::<ScrollStateV2>::new();
1463        chain.register(Box::new(FailingMigration));
1464
1465        let state: Box<dyn core::any::Any + Send> = Box::new(ScrollStateV1 { scroll_offset: 1 });
1466        let result = chain.migrate(state, 1, 2);
1467        assert!(result.is_err());
1468        match result.unwrap_err() {
1469            MigrationError::MigrationFailed { from, to, message } => {
1470                assert_eq!(from, 1);
1471                assert_eq!(to, 2);
1472                assert_eq!(message, "data corruption detected");
1473            }
1474            other => panic!("expected MigrationFailed, got {:?}", other),
1475        }
1476    }
1477
1478    #[test]
1479    fn migration_chain_type_mismatch_in_migrate_erased() {
1480        let mut chain = MigrationChain::<ScrollStateV2>::new();
1481        chain.register(Box::new(V1ToV2Migration));
1482
1483        // Pass wrong type (String instead of ScrollStateV1)
1484        let wrong: Box<dyn core::any::Any + Send> = Box::new("not a state".to_string());
1485        let result = chain.migrate(wrong, 1, 2);
1486        assert!(result.is_err());
1487        match result.unwrap_err() {
1488            MigrationError::MigrationFailed { from: 1, to: 2, .. } => {}
1489            other => panic!("expected MigrationFailed, got {:?}", other),
1490        }
1491    }
1492
1493    // ── Edge-case: RestoreResult ─────────────────────────────────────
1494
1495    #[test]
1496    fn restore_result_debug() {
1497        let direct = RestoreResult::Direct(ScrollState { scroll_offset: 1 });
1498        let dbg = format!("{:?}", direct);
1499        assert!(dbg.contains("Direct"));
1500
1501        let migrated = RestoreResult::Migrated {
1502            state: ScrollState { scroll_offset: 2 },
1503            from_version: 1,
1504        };
1505        let dbg = format!("{:?}", migrated);
1506        assert!(dbg.contains("Migrated"));
1507
1508        let fallback = RestoreResult::DefaultFallback {
1509            error: MigrationError::NoPathFound { from: 1, to: 2 },
1510            default: ScrollState::default(),
1511        };
1512        let dbg = format!("{:?}", fallback);
1513        assert!(dbg.contains("DefaultFallback"));
1514    }
1515
1516    #[test]
1517    fn restore_result_into_state_migrated_with_data() {
1518        let result = RestoreResult::Migrated {
1519            state: ScrollState { scroll_offset: 99 },
1520            from_version: 1,
1521        };
1522        assert_eq!(result.into_state().scroll_offset, 99);
1523    }
1524
1525    // ── Edge-case: unpack_with_migration ─────────────────────────────
1526
1527    // Widget for unpack_with_migration tests
1528    #[derive(Default)]
1529    struct WidgetV2 {
1530        data: ScrollStateV2,
1531    }
1532
1533    impl Stateful for WidgetV2 {
1534        type State = ScrollStateV2;
1535
1536        fn state_key(&self) -> Option<StateKey> {
1537            Some(StateKey::new("WidgetV2", "test"))
1538        }
1539
1540        fn save_state(&self) -> ScrollStateV2 {
1541            self.data.clone()
1542        }
1543
1544        fn restore_state(&mut self, state: ScrollStateV2) {
1545            self.data = state;
1546        }
1547
1548        fn state_version() -> u32 {
1549            2
1550        }
1551    }
1552
1553    #[test]
1554    fn unpack_with_migration_direct_match() {
1555        let vs = VersionedState::new(
1556            2,
1557            ScrollStateV2 {
1558                scroll_offset: 33,
1559                velocity: 1.5,
1560            },
1561        );
1562        let chain = MigrationChain::<ScrollStateV2>::new();
1563        let result = vs.unpack_with_migration::<WidgetV2>(&chain);
1564
1565        assert!(matches!(&result, RestoreResult::Direct(_)));
1566        assert!(!result.was_migrated());
1567        assert!(!result.is_fallback());
1568        let state = result.into_state();
1569        assert_eq!(state.scroll_offset, 33);
1570        assert_eq!(state.velocity, 1.5);
1571    }
1572
1573    #[test]
1574    fn unpack_with_migration_version_mismatch_type_mismatch_falls_back() {
1575        // VersionedState<S> requires S == Stateful::State (ScrollStateV2 for WidgetV2).
1576        // When version != current, migrate_erased receives Box<ScrollStateV2> but
1577        // the V1ToV2Migration expects Box<ScrollStateV1> → downcast fails → fallback.
1578        let vs = VersionedState::new(1, ScrollStateV2::default());
1579
1580        let mut chain = MigrationChain::<ScrollStateV2>::new();
1581        chain.register(Box::new(V1ToV2Migration));
1582
1583        let result = vs.unpack_with_migration::<WidgetV2>(&chain);
1584        assert!(result.is_fallback());
1585        assert!(!result.was_migrated());
1586    }
1587
1588    #[test]
1589    fn unpack_with_migration_no_path_falls_back() {
1590        let vs = VersionedState::new(
1591            1,
1592            ScrollStateV2 {
1593                scroll_offset: 10,
1594                velocity: 0.0,
1595            },
1596        );
1597        // Empty chain — no migration path from v1 to v2
1598        let chain = MigrationChain::<ScrollStateV2>::new();
1599        let result = vs.unpack_with_migration::<WidgetV2>(&chain);
1600
1601        assert!(result.is_fallback());
1602        let state = result.into_state();
1603        // Should be default
1604        assert_eq!(state.scroll_offset, 0);
1605        assert_eq!(state.velocity, 0.0);
1606    }
1607
1608    #[test]
1609    fn unpack_with_migration_failed_migration_falls_back() {
1610        let vs = VersionedState::new(1, ScrollStateV2::default());
1611
1612        let mut chain = MigrationChain::<ScrollStateV2>::new();
1613        chain.register(Box::new(FailingMigration));
1614
1615        let result = vs.unpack_with_migration::<WidgetV2>(&chain);
1616        assert!(result.is_fallback());
1617    }
1618
1619    #[test]
1620    fn unpack_with_migration_type_mismatch_after_chain() {
1621        // Migration succeeds but returns wrong type → DefaultFallback
1622        struct WrongTypeMigration;
1623
1624        impl ErasedMigration<ScrollStateV2> for WrongTypeMigration {
1625            fn from_version(&self) -> u32 {
1626                1
1627            }
1628            fn to_version(&self) -> u32 {
1629                2
1630            }
1631            fn migrate_erased(
1632                &self,
1633                _: Box<dyn core::any::Any + Send>,
1634            ) -> Result<Box<dyn core::any::Any + Send>, String> {
1635                // Return wrong type (String instead of ScrollStateV2)
1636                Ok(Box::new("wrong type".to_string()))
1637            }
1638        }
1639
1640        let vs = VersionedState::new(1, ScrollStateV2::default());
1641        let mut chain = MigrationChain::<ScrollStateV2>::new();
1642        chain.register(Box::new(WrongTypeMigration));
1643
1644        let result = vs.unpack_with_migration::<WidgetV2>(&chain);
1645        assert!(result.is_fallback());
1646    }
1647
1648    // ── Edge-case: VersionedState::pack ──────────────────────────────
1649
1650    #[test]
1651    fn versioned_state_pack_uses_state_version() {
1652        let widget = TestTreeView {
1653            id: "test".into(),
1654            expanded: vec![1, 2],
1655        };
1656        let packed = VersionedState::pack(&widget);
1657        assert_eq!(packed.version, 2); // TestTreeView::state_version() == 2
1658        assert_eq!(packed.data.expanded_nodes, vec![1, 2]);
1659    }
1660
1661    #[test]
1662    fn versioned_state_pack_default_version() {
1663        let widget = TestScrollView {
1664            id: "test".into(),
1665            offset: 0,
1666            max: 100,
1667        };
1668        let packed = VersionedState::pack(&widget);
1669        assert_eq!(packed.version, 1); // default state_version() == 1
1670    }
1671
1672    // ── Edge-case: ScrollState trait coverage ────────────────────────
1673
1674    #[test]
1675    fn scroll_state_clone() {
1676        let s = ScrollState { scroll_offset: 42 };
1677        let cloned = s.clone();
1678        assert_eq!(s, cloned);
1679    }
1680
1681    #[test]
1682    fn scroll_state_debug() {
1683        let s = ScrollState { scroll_offset: 10 };
1684        let dbg = format!("{:?}", s);
1685        assert!(dbg.contains("ScrollState"));
1686        assert!(dbg.contains("10"));
1687    }
1688
1689    #[test]
1690    fn tree_state_clone() {
1691        let s = TreeState {
1692            expanded_nodes: vec![1, 2, 3],
1693            collapse_all_on_blur: true,
1694        };
1695        let cloned = s.clone();
1696        assert_eq!(s, cloned);
1697    }
1698
1699    #[test]
1700    fn tree_state_debug() {
1701        let s = TreeState {
1702            expanded_nodes: vec![],
1703            collapse_all_on_blur: false,
1704        };
1705        let dbg = format!("{:?}", s);
1706        assert!(dbg.contains("TreeState"));
1707    }
1708}