@djangocfg/centrifugo 2.1.66 → 2.1.68

package/README.md

@@ -14,6 +14,7 @@ Professional Centrifugo WebSocket client with React integration, composable UI c
 ## Features
 
 - 🔌 **Robust WebSocket Connection** - Auto-reconnect, error handling, and connection state management
+- 👁️ **Page Visibility Handling** - Auto-reconnect when tab becomes active, pause reconnects when hidden (saves battery)
 - 🔄 **RPC Pattern Support** - Request-response via correlation ID for synchronous-like communication
 - 📊 **Advanced Logging System** - Circular buffer with dual output (consola + in-memory accumulation)
 - 🧩 **Composable UI Components** - Flexible, reusable components for any use case
@@ -47,7 +48,9 @@ src/
 │   └── LogsProvider/        # Logs accumulation provider
 ├── hooks/                   # React hooks
 │   ├── useSubscription.ts   # Channel subscription hook
-│   └── useRPC.ts            # RPC request-response hook
+│   ├── useRPC.ts            # RPC request-response hook
+│   ├── useNamedRPC.ts       # Native Centrifugo RPC hook
+│   └── usePageVisibility.ts # Browser tab visibility tracking
 └── components/              # Composable UI components
     ├── ConnectionStatus/    # Connection status display
     │   ├── ConnectionStatus.tsx        # Badge/inline/detailed variants
@@ -451,6 +454,82 @@ interface UseNamedRPCResult {
 
 > **Note:** `useNamedRPC` uses native Centrifugo RPC which requires RPC proxy to be configured in Centrifugo server. See the [Setup Guide](https://djangocfg.com/docs/features/integrations/centrifugo/client-generation/) for configuration details.
 
+### usePageVisibility()
+
+Hook for tracking browser tab visibility. Built into `CentrifugoProvider` for automatic reconnection handling.
+
+**Built-in Behavior (CentrifugoProvider):**
+
+The provider automatically handles visibility changes:
+- **Tab hidden**: Pauses reconnect attempts (saves battery)
+- **Tab visible**: Triggers reconnect if connection was lost
+
+**Standalone Usage:**
+
+```tsx
+import { usePageVisibility } from '@djangocfg/centrifugo';
+
+function MyComponent() {
+  const { isVisible, wasHidden, hiddenDuration } = usePageVisibility({
+    onVisible: () => {
+      console.log('Tab is now visible');
+      // Refresh data, resume animations, etc.
+    },
+    onHidden: () => {
+      console.log('Tab is now hidden');
+      // Pause expensive operations
+    },
+    onChange: (isVisible) => {
+      console.log('Visibility changed:', isVisible);
+    },
+  });
+
+  return (
+    <div>
+      <p>Tab visible: {isVisible ? 'Yes' : 'No'}</p>
+      <p>Was hidden: {wasHidden ? 'Yes' : 'No'}</p>
+      {hiddenDuration > 0 && (
+        <p>Was hidden for: {Math.round(hiddenDuration / 1000)}s</p>
+      )}
+    </div>
+  );
+}
+```
+
+**Return Value:**
+```typescript
+interface UsePageVisibilityResult {
+  /** Whether the page is currently visible */
+  isVisible: boolean;
+  /** Whether the page was ever hidden during this session */
+  wasHidden: boolean;
+  /** Timestamp when page became visible */
+  visibleSince: number | null;
+  /** How long the page was hidden (ms) */
+  hiddenDuration: number;
+  /** Force check visibility state */
+  checkVisibility: () => boolean;
+}
+```
+
+**Options:**
+```typescript
+interface UsePageVisibilityOptions {
+  /** Callback when page becomes visible */
+  onVisible?: () => void;
+  /** Callback when page becomes hidden */
+  onHidden?: () => void;
+  /** Callback with visibility state change */
+  onChange?: (isVisible: boolean) => void;
+}
+```
+
+**Use Cases:**
+- Pause/resume WebSocket reconnection attempts
+- Refresh stale data when tab becomes active
+- Pause expensive animations or timers
+- Track user engagement metrics
+
 ### namedRPCNoWait() - Fire-and-Forget RPC
 
 For latency-sensitive operations (like terminal input), use the fire-and-forget variant that returns immediately without waiting for a response.
@@ -1032,6 +1111,9 @@ import type {
   // Hooks
   UseSubscriptionOptions,
   UseSubscriptionResult,
+  UsePageVisibilityOptions,
+  UsePageVisibilityResult,
+  PageVisibilityState,
 
   // Components
   ConnectionStatusProps,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/centrifugo",
-  "version": "2.1.66",
+  "version": "2.1.68",
   "description": "Production-ready Centrifugo WebSocket client for React with real-time subscriptions, RPC patterns, and connection state management",
   "keywords": [
     "centrifugo",
@@ -51,9 +51,9 @@
     "centrifuge": "^5.2.2"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^2.1.66",
-    "@djangocfg/ui-nextjs": "^2.1.66",
-    "@djangocfg/layouts": "^2.1.66",
+    "@djangocfg/api": "^2.1.68",
+    "@djangocfg/ui-nextjs": "^2.1.68",
+    "@djangocfg/layouts": "^2.1.68",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
@@ -61,7 +61,7 @@
     "react-dom": "^19.1.0"
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^2.1.66",
+    "@djangocfg/typescript-config": "^2.1.68",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",
     "moment": "^2.30.1",

package/src/hooks/index.ts

@@ -10,3 +10,10 @@ export type { UseRPCOptions, UseRPCResult } from './useRPC';
 
 export { useNamedRPC } from './useNamedRPC';
 export type { UseNamedRPCOptions, UseNamedRPCResult } from './useNamedRPC';
+
+export { usePageVisibility } from './usePageVisibility';
+export type {
+  PageVisibilityState,
+  UsePageVisibilityOptions,
+  UsePageVisibilityResult,
+} from './usePageVisibility';

package/src/hooks/usePageVisibility.ts

@@ -0,0 +1,140 @@
+/**
+ * usePageVisibility Hook
+ *
+ * Tracks browser tab visibility state using the Page Visibility API.
+ * Returns true when the page is visible, false when hidden.
+ *
+ * Use cases:
+ * - Pause/resume WebSocket connections
+ * - Pause expensive operations when tab is inactive
+ * - Trigger data sync when tab becomes visible
+ */
+
+'use client';
+
+import { useEffect, useState, useCallback, useRef } from 'react';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface PageVisibilityState {
+  /** Whether the page is currently visible */
+  isVisible: boolean;
+  /** Whether the page was ever hidden during this session */
+  wasHidden: boolean;
+  /** Timestamp when page became visible (for uptime tracking) */
+  visibleSince: number | null;
+  /** How long the page was hidden (ms), reset when visible */
+  hiddenDuration: number;
+}
+
+export interface UsePageVisibilityOptions {
+  /** Callback when page becomes visible */
+  onVisible?: () => void;
+  /** Callback when page becomes hidden */
+  onHidden?: () => void;
+  /** Callback with visibility state change */
+  onChange?: (isVisible: boolean) => void;
+}
+
+export interface UsePageVisibilityResult extends PageVisibilityState {
+  /** Force check visibility state */
+  checkVisibility: () => boolean;
+}
+
+// =============================================================================
+// HELPERS
+// =============================================================================
+
+/**
+ * Get current visibility state
+ * SSR-safe: returns true on server
+ */
+function getVisibilityState(): boolean {
+  if (typeof document === 'undefined') return true;
+  return document.visibilityState === 'visible';
+}
+
+// =============================================================================
+// HOOK
+// =============================================================================
+
+export function usePageVisibility(
+  options: UsePageVisibilityOptions = {}
+): UsePageVisibilityResult {
+  const { onVisible, onHidden, onChange } = options;
+
+  const [state, setState] = useState<PageVisibilityState>(() => ({
+    isVisible: getVisibilityState(),
+    wasHidden: false,
+    visibleSince: getVisibilityState() ? Date.now() : null,
+    hiddenDuration: 0,
+  }));
+
+  // Refs to avoid stale closures in callbacks
+  const onVisibleRef = useRef(onVisible);
+  const onHiddenRef = useRef(onHidden);
+  const onChangeRef = useRef(onChange);
+  const hiddenAtRef = useRef<number | null>(null);
+
+  // Keep refs updated
+  onVisibleRef.current = onVisible;
+  onHiddenRef.current = onHidden;
+  onChangeRef.current = onChange;
+
+  const checkVisibility = useCallback((): boolean => {
+    return getVisibilityState();
+  }, []);
+
+  useEffect(() => {
+    if (typeof document === 'undefined') return;
+
+    const handleVisibilityChange = () => {
+      const isNowVisible = getVisibilityState();
+
+      setState((prev) => {
+        // Calculate hidden duration if becoming visible
+        let hiddenDuration = prev.hiddenDuration;
+        if (isNowVisible && hiddenAtRef.current !== null) {
+          hiddenDuration = Date.now() - hiddenAtRef.current;
+          hiddenAtRef.current = null;
+        }
+
+        // Track when we became hidden
+        if (!isNowVisible) {
+          hiddenAtRef.current = Date.now();
+        }
+
+        return {
+          isVisible: isNowVisible,
+          wasHidden: prev.wasHidden || !isNowVisible,
+          visibleSince: isNowVisible ? (prev.visibleSince ?? Date.now()) : null,
+          hiddenDuration,
+        };
+      });
+
+      // Trigger callbacks
+      onChangeRef.current?.(isNowVisible);
+
+      if (isNowVisible) {
+        onVisibleRef.current?.();
+      } else {
+        onHiddenRef.current?.();
+      }
+    };
+
+    document.addEventListener('visibilitychange', handleVisibilityChange);
+
+    return () => {
+      document.removeEventListener('visibilitychange', handleVisibilityChange);
+    };
+  }, []);
+
+  return {
+    ...state,
+    checkVisibility,
+  };
+}
+
+export default usePageVisibility;

package/src/index.ts

@@ -92,6 +92,19 @@ export type {
   UseSubscriptionResult,
 } from './hooks/useSubscription';
 
+export { useRPC } from './hooks/useRPC';
+export type { UseRPCOptions, UseRPCResult } from './hooks/useRPC';
+
+export { useNamedRPC } from './hooks/useNamedRPC';
+export type { UseNamedRPCOptions, UseNamedRPCResult } from './hooks/useNamedRPC';
+
+export { usePageVisibility } from './hooks/usePageVisibility';
+export type {
+  PageVisibilityState,
+  UsePageVisibilityOptions,
+  UsePageVisibilityResult,
+} from './hooks/usePageVisibility';
+
 export { useCodegenTip } from './hooks/useCodegenTip';
 
 // ─────────────────────────────────────────────────────────────────────────

package/src/providers/CentrifugoProvider/CentrifugoProvider.tsx

@@ -20,6 +20,7 @@ import { isDevelopment, isStaticBuild, reconnectConfig } from '../../config';
 import { CentrifugoRPCClient } from '../../core/client';
 import { getConsolaLogger } from '../../core/logger/consolaLogger';
 import { useCodegenTip } from '../../hooks/useCodegenTip';
+import { usePageVisibility } from '../../hooks/usePageVisibility';
 import { LogsProvider } from '../LogsProvider';
 
 import type { ConnectionState, CentrifugoToken, ActiveSubscription } from '../../core/types';
@@ -113,6 +114,7 @@ function CentrifugoProviderInner({
   const devWarningShownRef = useRef(false); // Track if server unavailable warning was shown
   const connectRef = useRef<(() => Promise<void>) | null>(null);
   const disconnectRef = useRef<(() => void) | null>(null);
+  const wasConnectedBeforeHiddenRef = useRef(false); // Track connection state before page hidden
 
   const centrifugoToken: CentrifugoToken | undefined = user?.centrifugo;
   const hasCentrifugoToken = !!centrifugoToken?.token;
@@ -413,6 +415,50 @@ function CentrifugoProviderInner({
     };
   }, [autoConnect]); // Only depend on autoConnect, not on connect/disconnect
 
+  // ==========================================================================
+  // PAGE VISIBILITY HANDLING
+  // ==========================================================================
+  // When tab becomes hidden: pause reconnect attempts (save battery)
+  // When tab becomes visible: trigger reconnect if needed
+
+  usePageVisibility({
+    onHidden: () => {
+      // Save connection state before hiding
+      wasConnectedBeforeHiddenRef.current = isConnected;
+
+      // Pause reconnect attempts while tab is hidden (save battery)
+      if (reconnectTimeoutRef.current) {
+        clearTimeout(reconnectTimeoutRef.current);
+        reconnectTimeoutRef.current = null;
+        logger.debug('Paused reconnect attempts (tab hidden)');
+      }
+    },
+    onVisible: () => {
+      // Only attempt reconnect if:
+      // 1. We should auto-connect
+      // 2. We're not already connected or connecting
+      // 3. We haven't stopped reconnecting
+      // 4. We were previously connected (or never connected yet)
+      const shouldReconnect =
+        autoConnect &&
+        !isConnected &&
+        !isConnectingRef.current &&
+        !reconnectStoppedRef.current &&
+        (wasConnectedBeforeHiddenRef.current || !hasConnectedRef.current);
+
+      if (shouldReconnect) {
+        // Reset reconnect attempts for fresh start
+        reconnectAttemptRef.current = 0;
+        devWarningShownRef.current = false;
+
+        logger.info('Tab visible - attempting reconnect...');
+        connectRef.current?.();
+      } else if (isConnected) {
+        logger.debug('Tab visible - connection still active');
+      }
+    },
+  });
+
   const connectionState: ConnectionState = isConnected
     ? 'connected'
     : isConnecting