refactor: migrate agent configurations and skills to the .agent directory and add project documentation

2026-05-03 16:17:43 +02:00
parent afdfc31d1a
commit eac0e9057e
12 changed files with 37 additions and 33 deletions
@@ -0,0 +1,38 @@
+---
+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.