fix: hydrate state for options-based WithPersistence and surface hydration errors (fixes #11)

- Add PersistenceMiddleware.TryLoadStateSync() that handles wrapper format,
  signature verification, validation, and TransformOnLoad in one place
- StoreBuilder.WithPersistence(provider, options) and WithPersistence(provider, key)
  now perform sync hydration via the middleware when the provider supports it,
  so WithSecurePersistence() and PersistenceOptions users get state restoration
- Replace silent Debug.WriteLine fallback with ILogger + Console.Error so
  deserialization failures are visible in Release WASM builds
- Remove duplicated TryHydrateStateSync in StoreBuilderExtensions; unified path

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

Author: mashrulhaque

src/EasyAppDev.Blazor.Store/Blazor/StoreBuilderExtensions.cs

@@ -1,4 +1,3 @@
-using System.Text.Json;
 using EasyAppDev.Blazor.Store.Core;
 using EasyAppDev.Blazor.Store.Diagnostics;
 using EasyAppDev.Blazor.Store.Persistence;
@@ -98,76 +97,13 @@ public static StoreBuilder<TState> WithPersistence<TState>(
 
         var provider = new LocalStorageProvider(jsRuntime);
 
-        // In WebAssembly mode, synchronous JS interop is available
-        // Load persisted state before building the store
-        if (provider.SupportsSyncOperations)
-        {
-            builder = TryHydrateStateSync(builder, provider, key);
-        }
-
+        // Hydration is now performed inside StoreBuilder.WithPersistence via the middleware
+        // when the provider supports sync operations (WebAssembly). This unifies the
+        // hydration path so wrapper handling, signature verification, validation, and
+        // transforms apply consistently regardless of which WithPersistence overload is used.
         return builder.WithPersistence(provider, key);
     }
 
-    /// <summary>
-    /// Attempts to hydrate state synchronously from localStorage (WebAssembly only).
-    /// </summary>
-    private static StoreBuilder<TState> TryHydrateStateSync<TState>(
-        StoreBuilder<TState> builder,
-        LocalStorageProvider provider,
-        string key)
-        where TState : notnull
-    {
-        try
-        {
-            var json = provider.LoadSync(key);
-            if (string.IsNullOrEmpty(json))
-            {
-                return builder;
-            }
-
-            var jsonOptions = new JsonSerializerOptions
-            {
-                PropertyNamingPolicy = JsonNamingPolicy.CamelCase
-            };
-
-            // Try to deserialize as new format (with wrapper)
-            string stateJson;
-            try
-            {
-                var wrapper = JsonSerializer.Deserialize<PersistedStateWrapper>(json, jsonOptions);
-                if (wrapper != null && !string.IsNullOrEmpty(wrapper.State))
-                {
-                    stateJson = wrapper.State;
-                }
-                else
-                {
-                    // Legacy format - plain JSON state
-                    stateJson = json;
-                }
-            }
-            catch
-            {
-                // Deserialization failed, try legacy format
-                stateJson = json;
-            }
-
-            var loadedState = JsonSerializer.Deserialize<TState>(stateJson, jsonOptions);
-            if (loadedState != null)
-            {
-                // Create new builder with hydrated state, preserving configuration
-                return builder.WithInitialState(loadedState);
-            }
-        }
-        catch (Exception ex)
-        {
-            // Log but don't fail - fall back to initial state
-            System.Diagnostics.Debug.WriteLine(
-                $"[EasyAppDev.Store] Failed to hydrate state for {typeof(TState).Name} from key '{key}': {ex.Message}");
-        }
-
-        return builder;
-    }
-
     /// <summary>
     /// Adds diagnostics middleware if IDiagnosticsService is registered.
     /// </summary>

src/EasyAppDev.Blazor.Store/Core/StoreBuilder.cs

@@ -285,14 +285,13 @@ public StoreBuilder<TState> WithPersistence(
         JsonSerializerOptions? jsonOptions = null,
         int debounceMs = 0)
     {
-        var hydratedBuilder = TryLoadPersistedState(key, jsonOptions);
-
         var middleware = new PersistenceMiddleware<TState>(
             provider,
             key,
             jsonOptions,
             debounceMs);
 
+        var hydratedBuilder = TryHydrateFromMiddleware(middleware);
         return hydratedBuilder.WithMiddleware(middleware);
     }
 
@@ -322,7 +321,25 @@ public StoreBuilder<TState> WithPersistence(
         ArgumentNullException.ThrowIfNull(options);
 
         var middleware = new PersistenceMiddleware<TState>(provider, options);
-        return WithMiddleware(middleware);
+        var hydratedBuilder = options.HydrateOnInit
+            ? TryHydrateFromMiddleware(middleware)
+            : this;
+        return hydratedBuilder.WithMiddleware(middleware);
+    }
+
+    /// <summary>
+    /// Attempts sync hydration through the middleware. Returns a builder with the hydrated
+    /// initial state if the provider supports sync operations (WebAssembly) and a persisted
+    /// state was successfully loaded. Otherwise returns <c>this</c> unchanged.
+    /// </summary>
+    private StoreBuilder<TState> TryHydrateFromMiddleware(PersistenceMiddleware<TState> middleware)
+    {
+        var (supported, state) = middleware.TryLoadStateSync();
+        if (supported && state is not null)
+        {
+            return WithInitialState(state);
+        }
+        return this;
     }
 
     /// <summary>

src/EasyAppDev.Blazor.Store/Persistence/PersistenceMiddleware.cs

@@ -384,4 +384,140 @@ private static bool IsStorageQuotaException(Exception ex)
     /// Gets whether hydration should occur on initialization.
     /// </summary>
     public bool HydrateOnInit => _options?.HydrateOnInit ?? true;
+
+    /// <summary>
+    /// Synchronously loads the persisted state if the provider supports sync operations
+    /// (i.e., WebAssembly mode via Microsoft.JSInterop.IJSInProcessRuntime).
+    /// </summary>
+    /// <returns>
+    /// A tuple of (supported, state). If <c>supported</c> is false, sync loading is not
+    /// available on this provider and the caller should fall back to async hydration.
+    /// If <c>supported</c> is true but <c>state</c> is default, no persisted state was found
+    /// or it failed validation/integrity checks.
+    /// </returns>
+    public (bool Supported, TState? State) TryLoadStateSync()
+    {
+        if (_provider is not LocalStorageProvider lsp || !lsp.SupportsSyncOperations)
+        {
+            return (false, default);
+        }
+
+        try
+        {
+            var json = lsp.LoadSync(_key);
+            if (string.IsNullOrEmpty(json))
+            {
+                _options?.OnHydrationSkipped?.Invoke();
+                return (true, default);
+            }
+
+            var loaded = ParsePersistedJson(json);
+            return (true, loaded);
+        }
+        catch (StateIntegrityException)
+        {
+            throw;
+        }
+        catch (Exception ex)
+        {
+            _logger?.LogError(ex, "Error loading persisted state synchronously from key: {Key}", _key);
+            // Surface to the browser console as well, since Debug.WriteLine is silent in Release WASM.
+            Console.Error.WriteLine(
+                $"[EasyAppDev.Store] Sync hydration failed for {typeof(TState).Name} (key '{_key}'): {ex.GetType().Name}: {ex.Message}");
+            _options?.OnHydrationFailure?.Invoke(ex);
+            return (true, default);
+        }
+    }
+
+    /// <summary>
+    /// Shared JSON parsing logic for both sync and async hydration paths.
+    /// Handles wrapper unwrapping, signature verification, validation, and transformation.
+    /// </summary>
+    private TState? ParsePersistedJson(string json)
+    {
+        string stateJson;
+        PersistedStateWrapper? wrapper = null;
+
+        try
+        {
+            wrapper = JsonSerializer.Deserialize<PersistedStateWrapper>(json, _jsonOptions);
+        }
+        catch
+        {
+            // Ignore - will fall back to legacy plain-JSON format below.
+        }
+
+        if (wrapper != null && !string.IsNullOrEmpty(wrapper.State))
+        {
+            stateJson = wrapper.State;
+
+            if (_messageSigner != null && !string.IsNullOrEmpty(wrapper.Signature))
+            {
+                if (!_messageSigner.Verify(stateJson, wrapper.Signature))
+                {
+                    var integrityEx = new StateIntegrityException(
+                        $"State integrity verification failed for key '{_key}'. The persisted state may have been tampered with.");
+                    _logger?.LogError(integrityEx, "Integrity check failed for key: {Key}", _key);
+                    _options?.OnHydrationFailure?.Invoke(integrityEx);
+                    return default;
+                }
+            }
+            else if (_messageSigner != null && string.IsNullOrEmpty(wrapper.Signature))
+            {
+                _logger?.LogWarning(
+                    "State loaded without signature for key: {Key}. RequireSignature: {Required}",
+                    _key,
+                    _options?.RequireSignature ?? false);
+
+                if (_options?.RequireSignature == true)
+                {
+                    var integrityEx = new StateIntegrityException(
+                        $"Unsigned state rejected for key '{_key}'. Integrity signing is required but no signature found.");
+                    _logger?.LogError(integrityEx, "Unsigned state rejected for key: {Key}", _key);
+                    _options.OnHydrationFailure?.Invoke(integrityEx);
+                    return default;
+                }
+            }
+        }
+        else
+        {
+            // Legacy plain-JSON format (pre-wrapper).
+            stateJson = json;
+        }
+
+        var loadedState = JsonSerializer.Deserialize<TState>(stateJson, _jsonOptions);
+        if (loadedState == null)
+        {
+            _options?.OnHydrationSkipped?.Invoke();
+            return default;
+        }
+
+        if (_options?.StateValidator != null)
+        {
+            var validationResult = _options.StateValidator.Validate(loadedState);
+            if (!validationResult.IsValid)
+            {
+                _logger?.LogWarning(
+                    "State validation failed for key {Key}: {Errors}",
+                    _key,
+                    string.Join(", ", validationResult.Errors));
+                _options.OnValidationFailed?.Invoke(validationResult with { Source = "Persistence" });
+
+                if (_options.RejectInvalidState)
+                {
+                    _options.OnHydrationFailure?.Invoke(
+                        new InvalidOperationException(
+                            $"State validation failed: {string.Join(", ", validationResult.Errors)}"));
+                    return default;
+                }
+            }
+        }
+
+        var transformedState = _options?.TransformOnLoad != null
+            ? _options.TransformOnLoad(loadedState)
+            : loadedState;
+
+        _options?.OnHydrationSuccess?.Invoke(transformedState);
+        return transformedState;
+    }
 }