feat(recommendations): implement contextual recommendation engine (#76)

Resolves #75

### Description
This pull request implements a smart, Native AOT-compliant contextual recommendation engine for the desktop dashboard to drive user retention and cross-book monetization.

### Key Changes
1. **Application Layer**:
   - Declared `IUserReadingStateStore` interface to decouple reading state discovery.
   - Added `IVectorSearchStore.SearchGlobalExcludeAsync(...)` to abstract semantic similarity searches with exclusions.
   - Defined `GetContextualRecommendationsQuery` and response DTOs (`ContextualRecommendationResponse`, `RecommendationDto`).
2. **Infrastructure Layer**:
   - Implemented `UserReadingStateStore` using EF Core with DbContext pooling.
   - Implemented `SearchGlobalExcludeAsync` in `VectorSearchStore` to construct gRPC Qdrant filters (excluding the active book ID) and fetch `bookTitle` and `chapterTitle` from point payloads.
   - Implemented `GetContextualRecommendationsQueryHandler` using clean abstractions.
3. **Web & Serialization Layer**:
   - Mapped `GET /api/recommendations` endpoint.
   - Registered types in `AppJsonContext.cs` for AOT-compliant JSON serialization.
4. **Verification**:
   - Added complete unit test coverage in `GetContextualRecommendationsQueryTests.cs`. All 30 unit tests pass.

---------

Co-authored-by: Marek Jasiński <jasins.marek@gmail.com>
Reviewed-on: #76
Co-authored-by: Antigravity <antigravity@google.com>
Co-committed-by: Antigravity <antigravity@google.com>

src/NexusReader.UI.Shared/Services/ILibraryStateService.cs

@@ -0,0 +1,12 @@
+using System;
+using System.Collections.Generic;
+using NexusReader.Application.DTOs.User;
+
+namespace NexusReader.UI.Shared.Services;
+
+public interface ILibraryStateService
+{
+    List<LastReadBookDto>? OwnedBooks { get; set; }
+    event Action? OnBooksChanged;
+    void NotifyBooksChanged();
+}

src/NexusReader.UI.Shared/Services/IRecommendationService.cs

@@ -0,0 +1,23 @@
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+using NexusReader.Application.Queries.Recommendations;
+
+namespace NexusReader.UI.Shared.Services;
+
+/// <summary>
+/// Provides contextual book recommendations based on the user's active reading state.
+/// Abstracts the HTTP transport layer from Blazor UI components.
+/// </summary>
+public interface IRecommendationService
+{
+    /// <summary>
+    /// Fetches contextual recommendations for the authenticated user.
+    /// </summary>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>
+    /// A list of <see cref="RecommendationDto"/> on success, or an empty list when none are available.
+    /// Returns <c>null</c> if the request fails due to a transport or server error.
+    /// </returns>
+    Task<List<RecommendationDto>?> GetRecommendationsAsync(CancellationToken cancellationToken = default);
+}

src/NexusReader.UI.Shared/Services/LibraryStateService.cs

@@ -0,0 +1,27 @@
+using System;
+using System.Collections.Generic;
+using NexusReader.Application.DTOs.User;
+
+namespace NexusReader.UI.Shared.Services;
+
+public class LibraryStateService : ILibraryStateService
+{
+    private List<LastReadBookDto>? _ownedBooks;
+
+    public List<LastReadBookDto>? OwnedBooks
+    {
+        get => _ownedBooks;
+        set
+        {
+            _ownedBooks = value;
+            NotifyBooksChanged();
+        }
+    }
+
+    public event Action? OnBooksChanged;
+
+    public void NotifyBooksChanged()
+    {
+        OnBooksChanged?.Invoke();
+    }
+}

src/NexusReader.UI.Shared/Services/PaywallParser.cs

@@ -0,0 +1,72 @@
+using System;
+
+namespace NexusReader.UI.Shared.Services;
+
+/// <summary>
+/// AOT-safe string parsing utility to isolate paywall teaser details without regex overhead.
+/// </summary>
+public static class PaywallParser
+{
+    public static bool TryParsePaywallTrigger(
+        string rawText,
+        out string displayTeaserText,
+        out Guid lockedBookId,
+        out string lockedBookTitle,
+        out int localScore,
+        out int globalScore)
+    {
+        displayTeaserText = rawText;
+        lockedBookId = Guid.Empty;
+        lockedBookTitle = string.Empty;
+        localScore = 0;
+        globalScore = 0;
+
+        if (string.IsNullOrEmpty(rawText))
+            return false;
+
+        ReadOnlySpan<char> span = rawText.AsSpan();
+        int tokenStartIndex = span.IndexOf("[PAYWALL_TRIGGER:");
+        if (tokenStartIndex == -1)
+            return false;
+
+        displayTeaserText = span.Slice(0, tokenStartIndex).Trim().ToString();
+
+        ReadOnlySpan<char> tokenContent = span.Slice(tokenStartIndex + "[PAYWALL_TRIGGER:".Length);
+        int tokenEndIndex = tokenContent.IndexOf(']');
+        if (tokenEndIndex == -1)
+            return false;
+
+        tokenContent = tokenContent.Slice(0, tokenEndIndex);
+
+        int firstColonIdx = tokenContent.IndexOf(':');
+        if (firstColonIdx == -1)
+            return false;
+
+        ReadOnlySpan<char> guidSpan = tokenContent.Slice(0, firstColonIdx);
+        if (!Guid.TryParse(guidSpan, out lockedBookId))
+            return false;
+
+        ReadOnlySpan<char> remaining = tokenContent.Slice(firstColonIdx + 1);
+
+        int lastColonIdx = remaining.LastIndexOf(':');
+        if (lastColonIdx == -1)
+            return false;
+
+        ReadOnlySpan<char> globalScoreSpan = remaining.Slice(lastColonIdx + 1);
+        if (!int.TryParse(globalScoreSpan, out globalScore))
+            return false;
+
+        remaining = remaining.Slice(0, lastColonIdx);
+
+        int secondLastColonIdx = remaining.LastIndexOf(':');
+        if (secondLastColonIdx == -1)
+            return false;
+
+        ReadOnlySpan<char> localScoreSpan = remaining.Slice(secondLastColonIdx + 1);
+        if (!int.TryParse(localScoreSpan, out localScore))
+            return false;
+
+        lockedBookTitle = remaining.Slice(0, secondLastColonIdx).ToString();
+        return true;
+    }
+}