@djangocfg/layouts 2.1.35 → 2.1.37

package/src/snippets/PWA/@refactoring/REFACTORING_PROPOSALS.md

@@ -0,0 +1,1109 @@
+# PWA Snippets: Конкретные предложения по рефакторингу
+
+**Дата:** 2025-12-15
+**Статус:** Предложения для обсуждения
+
+---
+
+## Содержание
+
+1. [Proposal #1: Унификация isStandalone()](#proposal-1-унификация-isstandalone)
+2. [Proposal #2: Улучшенный isPWA с кешированием](#proposal-2-улучшенный-ispwa-с-кешированием)
+3. [Proposal #3: Production-ready логирование](#proposal-3-production-ready-логирование)
+4. [Proposal #4: Валидация VAPID ключа](#proposal-4-валидация-vapid-ключа)
+5. [Proposal #5: Разделение ответственности хуков](#proposal-5-разделение-ответственности-хуков)
+6. [Proposal #6: Упрощение контекстов](#proposal-6-упрощение-контекстов)
+
+---
+
+## Proposal #1: Унификация isStandalone()
+
+### Проблема
+
+Функция `isStandalone()` дублируется в двух местах:
+- `hooks/useIsPWA.ts:14-24`
+- `hooks/useInstallPrompt.ts:19-29`
+
+### Решение
+
+Создать единую утилиту в `utils/platform.ts`
+
+### Код
+
+```typescript
+// utils/platform.ts
+
+/**
+ * Проверяет, запущено ли приложение в standalone режиме (PWA)
+ *
+ * Проверяет:
+ * 1. Modern: matchMedia display-mode (все современные браузеры)
+ * 2. Legacy: navigator.standalone (iOS Safari)
+ * 3. Fallback: для старых браузеров без matchMedia
+ *
+ * @returns true если приложение запущено как PWA
+ */
+export function isStandalone(): boolean {
+  if (typeof window === 'undefined') return false;
+
+  // Fallback для старых браузеров без matchMedia
+  if (!window.matchMedia) {
+    // Только legacy iOS check
+    const nav = navigator as Navigator & { standalone?: boolean };
+    return nav.standalone === true;
+  }
+
+  // Modern approach: display-mode media query
+  const isStandaloneDisplay = window.matchMedia('(display-mode: standalone)').matches;
+
+  // Legacy iOS check
+  const nav = navigator as Navigator & { standalone?: boolean };
+  const isStandaloneNavigator = nav.standalone === true;
+
+  return isStandaloneDisplay || isStandaloneNavigator;
+}
+
+/**
+ * Проверяет, является ли устройство мобильным
+ */
+export function isMobileDevice(): boolean {
+  if (typeof window === 'undefined') return false;
+  return /iPhone|iPad|iPod|Android/i.test(navigator.userAgent);
+}
+
+/**
+ * Проверяет валидность манифеста
+ */
+export function hasValidManifest(): boolean {
+  if (typeof document === 'undefined') return false;
+  const manifestLink = document.querySelector('link[rel="manifest"]');
+  return !!manifestLink;
+}
+
+/**
+ * Надежная проверка PWA режима с учетом edge cases
+ *
+ * Дополнительно проверяет:
+ * - Наличие манифеста для desktop браузеров
+ * - Является ли устройство мобильным
+ *
+ * @returns true если приложение запущено как настоящий PWA
+ */
+export function isStandaloneReliable(): boolean {
+  const standalone = isStandalone();
+  if (!standalone) return false;
+
+  // Для мобильных устройств достаточно standalone
+  if (isMobileDevice()) return true;
+
+  // Для desktop дополнительно проверяем манифест
+  // (Safari на Mac может открывать в standalone через "Add to Dock")
+  return hasValidManifest();
+}
+```
+
+### Миграция
+
+```typescript
+// hooks/useIsPWA.ts
+import { isStandalone } from '../utils/platform';
+
+export function useIsPWA(): boolean {
+  const [isPWA, setIsPWA] = useState(isStandalone);
+  // ... rest of the code
+}
+
+// hooks/useInstallPrompt.ts
+import { isStandalone } from '../utils/platform';
+
+export function useInstallPrompt() {
+  const [state, setState] = useState<InstallPromptState>(() => {
+    // ...
+    return {
+      // ...
+      isInstalled: isStandalone(),
+      // ...
+    };
+  });
+  // ... rest of the code
+}
+```
+
+---
+
+## Proposal #2: Улучшенный isPWA с кешированием
+
+### Проблема
+
+Текущая реализация `useIsPWA`:
+- Пересчитывает при каждом рендере
+- Нет кеширования между перезагрузками страницы
+- Не обрабатывает edge cases
+
+### Решение
+
+Добавить кеширование в sessionStorage и улучшить логику
+
+### Код
+
+```typescript
+// hooks/useIsPWA.ts
+'use client';
+
+import { useState, useEffect } from 'react';
+import { isStandalone, isStandaloneReliable } from '../utils/platform';
+
+const CACHE_KEY = 'pwa_is_standalone';
+
+/**
+ * Hook для определения PWA режима
+ *
+ * Возвращает true если приложение запущено в standalone режиме (PWA).
+ * Результат кешируется в sessionStorage для быстрой инициализации.
+ *
+ * @param options.reliable - использовать надежную проверку (с проверкой манифеста для desktop)
+ * @returns true если приложение запущено как PWA
+ */
+export function useIsPWA(options?: { reliable?: boolean }): boolean {
+  const checkFunction = options?.reliable ? isStandaloneReliable : isStandalone;
+
+  const [isPWA, setIsPWA] = useState<boolean>(() => {
+    // Попытка восстановить из кеша
+    if (typeof window !== 'undefined') {
+      try {
+        const cached = sessionStorage.getItem(CACHE_KEY);
+        if (cached !== null) {
+          return cached === 'true';
+        }
+      } catch {
+        // Игнорируем ошибки доступа к sessionStorage
+      }
+    }
+
+    // Первичная проверка
+    return checkFunction();
+  });
+
+  useEffect(() => {
+    // Проверка после монтирования (может отличаться от SSR)
+    const isStandaloneMode = checkFunction();
+    setIsPWA(isStandaloneMode);
+
+    // Сохранение в кеш
+    if (typeof window !== 'undefined') {
+      try {
+        sessionStorage.setItem(CACHE_KEY, String(isStandaloneMode));
+      } catch {
+        // Игнорируем ошибки доступа к sessionStorage
+      }
+    }
+
+    // Отслеживание изменений display-mode
+    if (typeof window === 'undefined' || !window.matchMedia) return;
+
+    const mediaQuery = window.matchMedia('(display-mode: standalone)');
+
+    const handleChange = (e: MediaQueryListEvent) => {
+      const newValue = e.matches;
+      setIsPWA(newValue);
+
+      // Обновление кеша
+      try {
+        sessionStorage.setItem(CACHE_KEY, String(newValue));
+      } catch {
+        // Игнорируем ошибки
+      }
+    };
+
+    // Современные браузеры
+    mediaQuery.addEventListener('change', handleChange);
+
+    return () => {
+      mediaQuery.removeEventListener('change', handleChange);
+    };
+  }, [checkFunction]);
+
+  return isPWA;
+}
+
+/**
+ * Сбросить кеш isPWA
+ * Полезно для тестирования
+ */
+export function clearIsPWACache(): void {
+  if (typeof window === 'undefined') return;
+  try {
+    sessionStorage.removeItem(CACHE_KEY);
+  } catch {
+    // Игнорируем ошибки
+  }
+}
+```
+
+### Использование
+
+```typescript
+// Базовая проверка (текущее поведение)
+const isPWA = useIsPWA();
+
+// Надежная проверка (с проверкой манифеста)
+const isPWA = useIsPWA({ reliable: true });
+
+// Очистка кеша (для тестирования)
+import { clearIsPWACache } from '@djangocfg/layouts/snippets';
+clearIsPWACache();
+```
+
+---
+
+## Proposal #3: Production-ready логирование
+
+### Проблема
+
+`usePushNotifications.ts` содержит ~20 `consola` логов, которые загрязняют production консоль и могут раскрывать чувствительные данные.
+
+### Решение
+
+Создать условный логгер, который работает только в development режиме
+
+### Код
+
+```typescript
+// utils/logger.ts
+
+import { consola } from 'consola';
+
+const isDevelopment = process.env.NODE_ENV === 'development';
+const isDebugEnabled = typeof window !== 'undefined' && localStorage.getItem('pwa_debug') === 'true';
+
+/**
+ * PWA Logger с условным логированием
+ *
+ * В production логирует только ошибки
+ * В development логирует все уровни
+ *
+ * Для включения debug режима в production:
+ * localStorage.setItem('pwa_debug', 'true')
+ */
+export const pwaLogger = {
+  /**
+   * Info level - только development или debug режим
+   */
+  info: (...args: any[]): void => {
+    if (isDevelopment || isDebugEnabled) {
+      consola.info(...args);
+    }
+  },
+
+  /**
+   * Warn level - только development или debug режим
+   */
+  warn: (...args: any[]): void => {
+    if (isDevelopment || isDebugEnabled) {
+      consola.warn(...args);
+    }
+  },
+
+  /**
+   * Error level - всегда логируется
+   */
+  error: (...args: any[]): void => {
+    consola.error(...args);
+  },
+
+  /**
+   * Debug level - только при явном включении
+   */
+  debug: (...args: any[]): void => {
+    if (isDebugEnabled) {
+      consola.debug(...args);
+    }
+  },
+};
+
+/**
+ * Включить debug режим
+ */
+export function enablePWADebug(): void {
+  if (typeof window !== 'undefined') {
+    localStorage.setItem('pwa_debug', 'true');
+    consola.info('[PWA] Debug mode enabled. Reload page to see debug logs.');
+  }
+}
+
+/**
+ * Выключить debug режим
+ */
+export function disablePWADebug(): void {
+  if (typeof window !== 'undefined') {
+    localStorage.removeItem('pwa_debug');
+    consola.info('[PWA] Debug mode disabled.');
+  }
+}
+```
+
+### Миграция
+
+```typescript
+// hooks/usePushNotifications.ts
+
+// До:
+import { consola } from 'consola';
+consola.info('[usePushNotifications] VAPID Key length:', options.vapidPublicKey?.length);
+
+// После:
+import { pwaLogger } from '../utils/logger';
+pwaLogger.info('[usePushNotifications] VAPID Key length:', options.vapidPublicKey?.length);
+
+// Ошибки всегда логируются:
+pwaLogger.error('[usePushNotifications] Subscribe failed:', error);
+```
+
+### Debug в production
+
+```javascript
+// В консоли браузера:
+localStorage.setItem('pwa_debug', 'true');
+location.reload();
+
+// Или через helper:
+import { enablePWADebug } from '@djangocfg/layouts/snippets';
+enablePWADebug();
+```
+
+---
+
+## Proposal #4: Валидация VAPID ключа
+
+### Проблема
+
+Текущее преобразование VAPID ключа:
+- Не валидирует формат входного ключа
+- Не проверяет длину (должна быть 65 байт для P-256)
+- Неинформативные ошибки
+
+### Решение
+
+Добавить полную валидацию с понятными ошибками
+
+### Код
+
+```typescript
+// utils/vapid.ts
+
+/**
+ * Ошибки валидации VAPID ключа
+ */
+export class VapidKeyError extends Error {
+  constructor(message: string, public readonly code: string) {
+    super(message);
+    this.name = 'VapidKeyError';
+  }
+}
+
+/**
+ * Валидирует и преобразует VAPID public key из base64url в Uint8Array
+ *
+ * VAPID ключ должен быть:
+ * - Base64url encoded строкой
+ * - 65 байт после декодирования (P-256 uncompressed key)
+ * - Начинаться с 0x04 (uncompressed point indicator)
+ *
+ * @param base64String - VAPID public key в base64url формате
+ * @returns Uint8Array для использования в pushManager.subscribe()
+ * @throws VapidKeyError если ключ невалиден
+ */
+export function urlBase64ToUint8Array(base64String: string): Uint8Array {
+  // 1. Валидация входа
+  if (!base64String) {
+    throw new VapidKeyError(
+      'VAPID public key is required',
+      'VAPID_EMPTY'
+    );
+  }
+
+  if (typeof base64String !== 'string') {
+    throw new VapidKeyError(
+      'VAPID public key must be a string',
+      'VAPID_INVALID_TYPE'
+    );
+  }
+
+  // 2. Преобразование base64url в base64
+  const padding = '='.repeat((4 - (base64String.length % 4)) % 4);
+  const base64 = (base64String + padding)
+    .replace(/-/g, '+')
+    .replace(/_/g, '/');
+
+  // 3. Декодирование base64
+  let rawData: string;
+  try {
+    rawData = window.atob(base64);
+  } catch (e) {
+    throw new VapidKeyError(
+      `Invalid base64url format: ${e instanceof Error ? e.message : String(e)}`,
+      'VAPID_INVALID_BASE64'
+    );
+  }
+
+  // 4. Преобразование в Uint8Array
+  const outputArray = new Uint8Array(rawData.length);
+  for (let i = 0; i < rawData.length; i++) {
+    outputArray[i] = rawData.charCodeAt(i);
+  }
+
+  // 5. Валидация длины (P-256 uncompressed = 65 bytes)
+  if (outputArray.length !== 65) {
+    throw new VapidKeyError(
+      `Invalid key length: expected 65 bytes (P-256 uncompressed), got ${outputArray.length} bytes`,
+      'VAPID_INVALID_LENGTH'
+    );
+  }
+
+  // 6. Валидация формата (должен начинаться с 0x04)
+  if (outputArray[0] !== 0x04) {
+    throw new VapidKeyError(
+      `Invalid key format: must start with 0x04 (uncompressed P-256 point), got 0x${outputArray[0].toString(16).padStart(2, '0')}`,
+      'VAPID_INVALID_FORMAT'
+    );
+  }
+
+  return outputArray;
+}
+
+/**
+ * Валидирует VAPID ключ без преобразования
+ *
+ * @param base64String - VAPID public key
+ * @returns true если ключ валиден
+ */
+export function isValidVapidKey(base64String: string): boolean {
+  try {
+    urlBase64ToUint8Array(base64String);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Получает информацию о VAPID ключе для отладки
+ */
+export function getVapidKeyInfo(base64String: string): {
+  valid: boolean;
+  length?: number;
+  firstByte?: string;
+  error?: string;
+} {
+  try {
+    const key = urlBase64ToUint8Array(base64String);
+    return {
+      valid: true,
+      length: key.length,
+      firstByte: `0x${key[0].toString(16).padStart(2, '0')}`,
+    };
+  } catch (e) {
+    return {
+      valid: false,
+      error: e instanceof VapidKeyError ? e.message : String(e),
+    };
+  }
+}
+```
+
+### Миграция
+
+```typescript
+// hooks/usePushNotifications.ts
+
+// До:
+const urlBase64ToUint8Array = (base64String: string) => {
+  // ... inline implementation
+};
+
+// После:
+import { urlBase64ToUint8Array, VapidKeyError, pwaLogger } from '../utils';
+
+try {
+  applicationServerKey = urlBase64ToUint8Array(options.vapidPublicKey);
+  pwaLogger.info('[usePushNotifications] VAPID key validated successfully');
+} catch (e) {
+  if (e instanceof VapidKeyError) {
+    pwaLogger.error(`[usePushNotifications] Invalid VAPID key: ${e.message} (code: ${e.code})`);
+    return false;
+  }
+  throw e;
+}
+```
+
+### Использование для отладки
+
+```typescript
+import { getVapidKeyInfo } from '@djangocfg/layouts/snippets';
+
+const info = getVapidKeyInfo(process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY);
+console.log('VAPID Key Info:', info);
+// {
+//   valid: true,
+//   length: 65,
+//   firstByte: '0x04'
+// }
+```
+
+---
+
+## Proposal #5: Разделение ответственности хуков
+
+### Проблема
+
+`useInstallPrompt` делает слишком много:
+- Детекция платформы
+- Управление состоянием установки
+- Обработка событий
+- Определение standalone режима
+
+### Решение
+
+Разделить на отдельные специализированные хуки
+
+### Код
+
+#### 5.1 usePlatform - Платформенная детекция
+
+```typescript
+// hooks/usePlatform.ts
+'use client';
+
+import { useState, useEffect } from 'react';
+import { useBrowserDetect, useDeviceDetect } from '@djangocfg/ui-nextjs';
+
+export interface PlatformInfo {
+  // OS
+  isIOS: boolean;
+  isAndroid: boolean;
+  isMobile: boolean;
+
+  // Browser
+  isSafari: boolean;
+  isChrome: boolean;
+  isChromium: boolean;
+
+  // Capabilities
+  supportsBeforeInstallPrompt: boolean;
+  supportsNotifications: boolean;
+  supportsPushManager: boolean;
+}
+
+/**
+ * Hook для детекции платформы и возможностей браузера
+ *
+ * Кеширует результат для производительности
+ */
+export function usePlatform(): PlatformInfo {
+  const browser = useBrowserDetect();
+  const device = useDeviceDetect();
+
+  const [platform] = useState<PlatformInfo>(() => {
+    if (typeof window === 'undefined') {
+      return {
+        isIOS: false,
+        isAndroid: false,
+        isMobile: false,
+        isSafari: false,
+        isChrome: false,
+        isChromium: false,
+        supportsBeforeInstallPrompt: false,
+        supportsNotifications: false,
+        supportsPushManager: false,
+      };
+    }
+
+    // Real Safari = Safari && NOT Chromium
+    const isSafari = browser.isSafari && !browser.isChromium;
+
+    return {
+      isIOS: device.isIOS,
+      isAndroid: device.isAndroid,
+      isMobile: device.isMobile,
+      isSafari,
+      isChrome: browser.isChrome,
+      isChromium: browser.isChromium,
+      supportsBeforeInstallPrompt: 'onbeforeinstallprompt' in window,
+      supportsNotifications: 'Notification' in window,
+      supportsPushManager: 'serviceWorker' in navigator && 'PushManager' in window,
+    };
+  });
+
+  return platform;
+}
+```
+
+#### 5.2 useInstallState - Состояние установки
+
+```typescript
+// hooks/useInstallState.ts
+'use client';
+
+import { useState, useEffect } from 'react';
+import { isStandalone } from '../utils/platform';
+import type { BeforeInstallPromptEvent } from '../types';
+
+export interface InstallState {
+  isInstalled: boolean;
+  canPrompt: boolean;
+  deferredPrompt: BeforeInstallPromptEvent | null;
+}
+
+/**
+ * Hook для управления состоянием установки PWA
+ */
+export function useInstallState(): InstallState {
+  const [state, setState] = useState<InstallState>({
+    isInstalled: false,
+    canPrompt: false,
+    deferredPrompt: null,
+  });
+
+  useEffect(() => {
+    // Initial check
+    setState((prev) => ({
+      ...prev,
+      isInstalled: isStandalone(),
+    }));
+
+    if (typeof window === 'undefined') return;
+
+    // Listen for beforeinstallprompt (Android Chrome)
+    const handleBeforeInstallPrompt = (e: Event) => {
+      e.preventDefault();
+      const event = e as BeforeInstallPromptEvent;
+
+      setState((prev) => ({
+        ...prev,
+        canPrompt: true,
+        deferredPrompt: event,
+      }));
+    };
+
+    // Listen for appinstalled (Android Chrome)
+    const handleAppInstalled = () => {
+      setState((prev) => ({
+        ...prev,
+        canPrompt: false,
+        deferredPrompt: null,
+        isInstalled: true,
+      }));
+    };
+
+    // Listen for display-mode changes
+    const mediaQuery = window.matchMedia('(display-mode: standalone)');
+    const handleDisplayModeChange = (e: MediaQueryListEvent) => {
+      if (e.matches) {
+        setState((prev) => ({
+          ...prev,
+          isInstalled: true,
+          canPrompt: false,
+          deferredPrompt: null,
+        }));
+      }
+    };
+
+    window.addEventListener('beforeinstallprompt', handleBeforeInstallPrompt);
+    window.addEventListener('appinstalled', handleAppInstalled);
+    mediaQuery.addEventListener('change', handleDisplayModeChange);
+
+    return () => {
+      window.removeEventListener('beforeinstallprompt', handleBeforeInstallPrompt);
+      window.removeEventListener('appinstalled', handleAppInstalled);
+      mediaQuery.removeEventListener('change', handleDisplayModeChange);
+    };
+  }, []);
+
+  return state;
+}
+```
+
+#### 5.3 useInstallActions - Действия установки
+
+```typescript
+// hooks/useInstallActions.ts
+'use client';
+
+import { useCallback } from 'react';
+import { markAppInstalled } from '../utils/localStorage';
+import { pwaLogger } from '../utils/logger';
+import type { BeforeInstallPromptEvent, InstallOutcome } from '../types';
+
+export interface InstallActions {
+  promptInstall: () => Promise<InstallOutcome>;
+}
+
+/**
+ * Hook для действий установки PWA
+ */
+export function useInstallActions(deferredPrompt: BeforeInstallPromptEvent | null): InstallActions {
+  const promptInstall = useCallback(async (): Promise<InstallOutcome> => {
+    if (!deferredPrompt) {
+      pwaLogger.warn('[useInstallActions] No deferred prompt available');
+      return null;
+    }
+
+    try {
+      // Show native prompt
+      await deferredPrompt.prompt();
+
+      // Wait for user response
+      const { outcome } = await deferredPrompt.userChoice;
+
+      pwaLogger.info('[useInstallActions] Install outcome:', outcome);
+
+      // Mark as installed if accepted
+      if (outcome === 'accepted') {
+        markAppInstalled();
+      }
+
+      return outcome;
+    } catch (error) {
+      pwaLogger.error('[useInstallActions] Error showing install prompt:', error);
+      return null;
+    }
+  }, [deferredPrompt]);
+
+  return {
+    promptInstall,
+  };
+}
+```
+
+#### 5.4 useInstallPrompt - Композиция хуков
+
+```typescript
+// hooks/useInstallPrompt.ts
+'use client';
+
+import { usePlatform } from './usePlatform';
+import { useInstallState } from './useInstallState';
+import { useInstallActions } from './useInstallActions';
+
+/**
+ * Hook для управления PWA установкой
+ *
+ * Композиция специализированных хуков:
+ * - usePlatform: детекция платформы
+ * - useInstallState: состояние установки
+ * - useInstallActions: действия установки
+ */
+export function useInstallPrompt() {
+  const platform = usePlatform();
+  const state = useInstallState();
+  const actions = useInstallActions(state.deferredPrompt);
+
+  return {
+    // Platform info
+    ...platform,
+
+    // Install state
+    ...state,
+
+    // Install actions
+    ...actions,
+  };
+}
+```
+
+### Преимущества
+
+- ✅ Четкое разделение ответственности
+- ✅ Каждый хук легко тестировать отдельно
+- ✅ Можно использовать хуки независимо
+- ✅ Улучшенная читаемость кода
+
+### Использование
+
+```typescript
+// Полная функциональность (как раньше)
+const install = useInstallPrompt();
+
+// Или использовать отдельно:
+const platform = usePlatform();
+const state = useInstallState();
+const { promptInstall } = useInstallActions(state.deferredPrompt);
+```
+
+---
+
+## Proposal #6: Упрощение контекстов
+
+### Проблема
+
+Текущая архитектура:
+```typescript
+<PwaProvider>
+  {/* PushProvider динамически оборачивает внутри */}
+  {children}
+</PwaProvider>
+```
+
+Проблемы:
+- Неочевидная вложенность
+- Трудно отлаживать
+- Нарушает принцип прозрачности
+
+### Решение
+
+Явная композиция провайдеров
+
+### Код
+
+#### 6.1 Упрощенный PwaInstallProvider
+
+```typescript
+// context/PwaInstallProvider.tsx
+'use client';
+
+import React, { createContext, useContext } from 'react';
+import { useInstallPrompt } from '../hooks/useInstallPrompt';
+import type { InstallOutcome } from '../types';
+
+export interface PwaInstallContextValue {
+  // Platform
+  isIOS: boolean;
+  isAndroid: boolean;
+  isMobile: boolean;
+  isSafari: boolean;
+  isChrome: boolean;
+
+  // State
+  isInstalled: boolean;
+  canPrompt: boolean;
+
+  // Actions
+  install: () => Promise<InstallOutcome>;
+}
+
+const PwaInstallContext = createContext<PwaInstallContextValue | undefined>(undefined);
+
+export interface PwaInstallConfig {
+  enabled?: boolean;
+}
+
+export function PwaInstallProvider({
+  children,
+  enabled = true,
+}: PwaInstallConfig & { children: React.ReactNode }) {
+  const prompt = useInstallPrompt();
+
+  // If not enabled, pass-through
+  if (!enabled) {
+    return <>{children}</>;
+  }
+
+  const value: PwaInstallContextValue = {
+    isIOS: prompt.isIOS,
+    isAndroid: prompt.isAndroid,
+    isMobile: prompt.isMobile,
+    isSafari: prompt.isSafari,
+    isChrome: prompt.isChrome,
+    isInstalled: prompt.isInstalled,
+    canPrompt: prompt.canPrompt,
+    install: prompt.promptInstall,
+  };
+
+  return (
+    <PwaInstallContext.Provider value={value}>
+      {children}
+    </PwaInstallContext.Provider>
+  );
+}
+
+export function useInstall(): PwaInstallContextValue {
+  const context = useContext(PwaInstallContext);
+
+  if (context === undefined) {
+    throw new Error('useInstall must be used within <PwaInstallProvider>');
+  }
+
+  return context;
+}
+```
+
+#### 6.2 Композитный PwaProvider (обратная совместимость)
+
+```typescript
+// context/PwaProvider.tsx
+'use client';
+
+import React from 'react';
+import { PwaInstallProvider, type PwaInstallConfig } from './PwaInstallProvider';
+import { PushProvider } from './PushContext';
+import { A2HSHint } from '../components/A2HSHint';
+import type { PushNotificationOptions } from '../types';
+
+export interface PwaConfig extends PwaInstallConfig {
+  showInstallHint?: boolean;
+  resetAfterDays?: number | null;
+  delayMs?: number;
+  logo?: string;
+  pushNotifications?: PushNotificationOptions & {
+    delayMs?: number;
+    resetAfterDays?: number;
+  };
+}
+
+/**
+ * Композитный PWA Provider
+ *
+ * Комбинирует:
+ * - PwaInstallProvider (установка PWA)
+ * - PushProvider (push уведомления)
+ * - A2HSHint (UI подсказка)
+ *
+ * @deprecated Используйте явную композицию для лучшего контроля
+ */
+export function PwaProvider({
+  children,
+  enabled = true,
+  showInstallHint = true,
+  resetAfterDays,
+  delayMs,
+  logo,
+  pushNotifications,
+}: PwaConfig & { children: React.ReactNode }) {
+  // Deprecation warning
+  if (process.env.NODE_ENV === 'development') {
+    console.warn(
+      '[PwaProvider] This component will be deprecated in v3.0. ' +
+      'Use explicit composition with PwaInstallProvider and PwaPushProvider instead. ' +
+      'See: https://docs.djangocfg.com/pwa/migration'
+    );
+  }
+
+  if (!enabled) {
+    return <>{children}</>;
+  }
+
+  // Explicit composition
+  let content = (
+    <PwaInstallProvider enabled={enabled}>
+      {children}
+      {showInstallHint && (
+        <A2HSHint
+          resetAfterDays={resetAfterDays}
+          delayMs={delayMs}
+          logo={logo}
+          pushNotifications={pushNotifications}
+        />
+      )}
+    </PwaInstallProvider>
+  );
+
+  // Wrap with PushProvider if needed
+  if (pushNotifications) {
+    content = <PushProvider {...pushNotifications}>{content}</PushProvider>;
+  }
+
+  return content;
+}
+
+// Re-export для обратной совместимости
+export { useInstall } from './PwaInstallProvider';
+export { usePush } from './PushContext';
+```
+
+#### 6.3 Рекомендуемое использование
+
+```typescript
+// app/layout.tsx
+
+// Новый способ (явная композиция)
+import { PwaInstallProvider, PwaPushProvider, A2HSHint } from '@djangocfg/layouts/snippets';
+
+<PwaInstallProvider enabled={true}>
+  <PwaPushProvider vapidPublicKey={process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY}>
+    {children}
+    <A2HSHint />
+  </PwaPushProvider>
+</PwaInstallProvider>
+
+// Старый способ (обратная совместимость)
+import { PwaProvider } from '@djangocfg/layouts/snippets';
+
+<PwaProvider
+  enabled={true}
+  pushNotifications={{
+    vapidPublicKey: process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY,
+  }}
+>
+  {children}
+</PwaProvider>
+```
+
+### Преимущества
+
+- ✅ Явная и прозрачная структура
+- ✅ Легче отлаживать
+- ✅ Можно использовать только нужные провайдеры
+- ✅ Обратная совместимость сохранена
+
+---
+
+## Сравнительная таблица
+
+| Аспект | До рефакторинга | После рефакторинга |
+|--------|-----------------|-------------------|
+| **isStandalone()** | Дублируется в 2 местах | Единая утилита |
+| **isPWA кеширование** | Нет | sessionStorage |
+| **Логирование** | Всегда активно | Условное (dev only) |
+| **VAPID валидация** | Базовая | Полная с понятными ошибками |
+| **Разделение хуков** | Монолитный useInstallPrompt | Композиция специализированных хуков |
+| **Архитектура контекстов** | Неявная вложенность | Явная композиция |
+| **Производительность** | Пересчет при каждом рендере | Мемоизация и кеш |
+| **Тестируемость** | Сложно | Легко (unit tests) |
+| **Обратная совместимость** | N/A | Сохранена |
+
+---
+
+## Roadmap внедрения
+
+### Фаза 1: Критические улучшения (неделя 1)
+
+1. ✅ Создать `utils/platform.ts` с `isStandalone()`
+2. ✅ Мигрировать `useIsPWA` и `useInstallPrompt`
+3. ✅ Создать `utils/logger.ts`
+4. ✅ Заменить все `consola` на `pwaLogger`
+5. ✅ Создать `utils/vapid.ts` с валидацией
+6. ✅ Обновить `usePushNotifications`
+
+### Фаза 2: Рефакторинг архитектуры (неделя 2-3)
+
+1. ✅ Разделить useInstallPrompt на:
+   - usePlatform
+   - useInstallState
+   - useInstallActions
+2. ✅ Обновить тесты
+3. ✅ Создать PwaInstallProvider
+4. ✅ Обновить PwaProvider с deprecation warnings
+
+### Фаза 3: Документация и миграция (неделя 4)
+
+1. ✅ Обновить README.md
+2. ✅ Создать MIGRATION.md
+3. ✅ Добавить примеры
+4. ✅ Обновить TypeScript типы
+
+---
+
+## Контрольный список для ревью
+
+- [ ] Код соответствует TypeScript best practices
+- [ ] Все функции имеют JSDoc комментарии
+- [ ] Добавлены unit тесты
+- [ ] Обратная совместимость проверена
+- [ ] Производительность не ухудшилась
+- [ ] Документация обновлена
+- [ ] Примеры работают
+- [ ] Нет breaking changes (или они документированы)
+
+---
+
+**Конец документа**