---
name: blazor-hybrid-bridge
description: 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.