Nexus.Reader/.agents/skills/blazor-hybrid-bridge.md

name, description

name	description
blazor-hybrid-bridge	Standards for cross-platform compatibility (Web & MAUI Hybrid)

Cross-Platform Integration

• Abstraction Layer:

  • Define all platform-specific logic in NexusReader.Application/Abstractions/Services.
  • Use IPlatformService for device hardware (Haptics, Orientation).
  • Use INativeStorageService for persistent key-value storage.

• Implementation Strategy:

  • MAUI: Implement in NexusReader.Infrastructure.Mobile using Microsoft.Maui.* APIs.
  • Web: Implement in NexusReader.Web.Client using IJSRuntime to access Browser APIs (e.g., navigator.vibrate, localStorage).

• UI Compatibility:

  • Notch Support: Use env(safe-area-inset-top) and other safe-area variables in CSS to prevent content from being hidden by hardware notches or home indicators.
  • Touch Optimization:
    • Use user-select: none for non-text interactive elements.
    • Ensure touch targets are at least 44x44px.
    • Handle active states for immediate feedback on mobile.

• Platform Detection:

  • Use IPlatformService.GetDeviceContext() to determine DeviceType (Phone, Tablet, Desktop).
  • Adapt UI layout dynamically based on the context (e.g., sidebars on Tablet/Desktop, bottom navigation on Phone).

• Real-time & Events (SignalR / UI):

  • Debouncing: Implement trailing-edge debouncing using CancellationTokenSource and Task.Delay for high-frequency UI events (like scrolling). Do not just drop events inside a time window, as the final state might be lost.
  • Dependency Isolation: Blazor WebAssembly (Web.Client) cannot reference projects that require Microsoft.AspNetCore.App (like SignalR Hubs). Keep SignalR abstractions in UI.Shared and the Hub implementation strictly on the server (Infrastructure or Web.New).

• Dependency Injection:

  • Register implementations in MauiProgram.cs for mobile and Program.cs for web.
  • Components in NexusReader.UI.Shared must only depend on the interfaces.

• JS Interop Standards:

  • Keep JS Interop calls isolated within service implementations.
  • Use IJSObjectReference for module-based scripts to avoid global namespace pollution.
  • Always provide a fallback or graceful failure for browsers that don't support specific APIs.