feat(notifications): implement WebSocket reconnection for notification system (#405)

[GEEKYFOCUS]

Summary

Closes #405

This PR implements production-ready WebSocket reconnection for the real-time Notification System. The socket logic is extracted from NotificationProvider into a dedicated, testable NotificationSocketService module.

Key changes

• New NotificationSocketService (src/lib/notifications/socket.ts)

  • Exponential backoff with configurable jitter to prevent reconnect storms
  • Automatic reconnect on unexpected disconnects and connection errors
  • Outbound message queue so notification_read / notification_clear actions are not lost while disconnected
  • Browser lifecycle hooks (online, visibilitychange) for faster recovery when connectivity returns
  • Graceful shutdown that clears timers, listeners, and pending reconnect attempts

• NotificationProvider refactor

  • Uses the shared socket service from @/lib/notifications/socket
  • Exposes connectionState via context so UI can reflect connection health (e.g. reconnecting indicator)

• Test coverage

  • Unit tests for backoff, reconnect, message queueing, max-attempt limits, and lifecycle recovery
  • Provider integration tests for connection state and live notification delivery

• Documentation

  • Added WebSocket reconnection section to docs/NOTIFICATION_SYSTEM_REFACTORING.md

Motivation

The previous inline WebSocket implementation had basic reconnect logic but lacked:

• Timer de-duplication safeguards
• Outbound message persistence during disconnects
• Browser lifecycle-aware recovery
• Observable connection state for the UI
• Dedicated test coverage

This change improves reliability in production environments where network interruptions are common.

Acceptance criteria

• Notification System properly implements WebSocket Reconnection
• All related tests pass (pnpm test src/lib/notifications/__tests__/socket.test.ts src/providers/__tests__/Notificationprovider.test.tsx)
• No regression in existing functionality (provider API is backward-compatible; adds connectionState)
• Code follows project coding standards
• Documentation updated
• Minimal performance impact (lightweight timers/listeners only)
• Security considerations addressed (no credential handling changes; reconnects only to configured wsUrl)

Test plan

• Run unit tests: pnpm test src/lib/notifications/__tests__/socket.test.ts
• Run provider tests: pnpm test src/providers/__tests__/Notificationprovider.test.tsx
• Verify notification bell/UI still renders inside <NotificationProvider>
• Simulate network drop in browser DevTools → confirm reconnect and notification delivery resume
• Confirm connectionState.status transitions: connecting → connected → reconnecting → connected

Notes for reviewers

• connectionState is a new field on the provider context; existing consumers are unaffected unless they opt in.
• Default maxReconnectAttempts is 0 (unlimited), matching resilient production behavior. Callers can cap attempts via NotificationSocketOptions if needed.

[drips-wave]

@GEEKYFOCUS Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[RUKAYAT-CODER]

Thank you for contributing to the project