@djangocfg/layouts 2.1.35 → 2.1.37

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

@@ -0,0 +1,1179 @@
+# PWA Snippets: Архитектурный анализ и рекомендации по рефакторингу
+
+**Дата анализа:** 2025-12-15
+**Версия:** 2.1.35
+**Статус:** Требуется рефакторинг
+
+---
+
+## Оглавление
+
+1. [Текущая архитектура](#1-текущая-архитектура)
+2. [Надежность определения isPWA](#2-надежность-определения-ispwa)
+3. [Критические проблемы](#3-критические-проблемы)
+4. [Рекомендации по улучшению](#4-рекомендации-по-улучшению)
+5. [План рефакторинга](#5-план-рефакторинга)
+
+---
+
+## 1. Текущая архитектура
+
+### 1.1 Структура файлов
+
+```
+PWA/
+├── @docs/
+│   └── research.md              # Исследование best practices
+├── @refactoring/                # Документация по рефакторингу
+│   └── ARCHITECTURE_ANALYSIS.md
+├── components/
+│   ├── A2HSHint.tsx            # Унифицированный hint для iOS/Android
+│   ├── IOSGuide.tsx            # Визуальный гайд для iOS
+│   ├── IOSGuideDrawer.tsx      # Drawer версия гайда
+│   ├── IOSGuideModal.tsx       # Modal версия гайда
+│   └── PushPrompt.tsx          # Prompt для push-уведомлений
+├── context/
+│   ├── InstallContext.tsx      # Контекст установки PWA
+│   └── PushContext.tsx         # Контекст push-уведомлений
+├── hooks/
+│   ├── useInstallPrompt.ts     # Управление установкой
+│   ├── useIsPWA.ts            # Определение PWA режима
+│   └── usePushNotifications.ts # Управление push-уведомлениями
+├── types/
+│   ├── components.ts           # Типы компонентов
+│   ├── install.ts             # Типы установки
+│   ├── platform.ts            # Типы платформ
+│   ├── push.ts                # Типы push
+│   └── index.ts               # Экспорт типов
+├── utils/
+│   └── localStorage.ts        # Утилиты для localStorage
+├── config.ts                  # Конфигурация (VAPID ключи)
+├── index.ts                   # Главный экспорт
+└── README.md                  # Документация
+```
+
+### 1.2 Архитектура компонентов
+
+```mermaid
+graph TD
+    A[BaseApp] --> B[PwaProvider]
+    B --> C[PushProvider]
+    B --> D[A2HSHint]
+    D --> E[IOSGuide]
+    D --> F[PushPrompt]
+
+    B --> G[useInstallPrompt hook]
+    C --> H[usePushNotifications hook]
+
+    G --> I[Platform Detection]
+    G --> J[Install State Management]
+
+    H --> K[Push Subscription]
+    H --> L[Service Worker Integration]
+```
+
+### 1.3 Подключение в приложении
+
+**Пример 1: BaseApp.tsx (layouts/AppLayout)**
+```tsx
+import { PwaProvider } from '../../snippets/PWA';
+
+<PwaProvider {...pwa}>
+  <ErrorTrackingProvider>
+    {children}
+  </ErrorTrackingProvider>
+</PwaProvider>
+```
+
+**Пример 2: layout.tsx (playground app)**
+```tsx
+import { BaseApp } from '@djangocfg/layouts';
+
+<BaseApp
+  pwa={{
+    enabled: true,
+    pushNotifications: {
+      vapidPublicKey: process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY,
+      subscribeEndpoint: '/api/push/subscribe',
+    },
+  }}
+>
+  {children}
+</BaseApp>
+```
+
+### 1.4 Основные компоненты
+
+#### PwaProvider
+- **Роль:** Корневой контекст для PWA функциональности
+- **Ответственность:**
+  - Управление состоянием установки
+  - Платформенная детекция
+  - Координация между Install и Push контекстами
+- **Проблемы:**
+  - Слишком много ответственности
+  - Запутанная вложенность с PushProvider
+
+#### useInstallPrompt
+- **Роль:** Управление процессом установки
+- **Ответственность:**
+  - Детекция платформы (iOS/Android)
+  - Обработка `beforeinstallprompt` event
+  - Определение standalone режима
+- **Проблемы:**
+  - Дублирование кода с `useIsPWA`
+  - Смешивание платформенной логики с install логикой
+
+#### useIsPWA
+- **Роль:** Определение, запущено ли приложение как PWA
+- **Ответственность:**
+  - Проверка standalone режима
+  - Отслеживание изменений display-mode
+- **Проблемы:**
+  - Дублирование логики из `useInstallPrompt`
+  - Отсутствие кеширования результата
+
+---
+
+## 2. Надежность определения isPWA
+
+### 2.1 Текущая реализация
+
+**Местоположение:**
+- `hooks/useIsPWA.ts:14-24`
+- `hooks/useInstallPrompt.ts:19-29` (дубликат)
+
+**Код:**
+```typescript
+function isStandalone(): boolean {
+  if (typeof window === 'undefined') return false;
+
+  // Check display-mode media query
+  const isStandaloneDisplay = window.matchMedia('(display-mode: standalone)').matches;
+
+  // Legacy iOS check
+  const isStandaloneNavigator = (navigator as Navigator & { standalone?: boolean }).standalone === true;
+
+  return isStandaloneDisplay || isStandaloneNavigator;
+}
+```
+
+### 2.2 Анализ надежности
+
+#### ✅ Что работает хорошо:
+
+1. **Двойная проверка:**
+   - `matchMedia('(display-mode: standalone)')` — современный стандарт
+   - `navigator.standalone` — legacy поддержка iOS
+
+2. **SSR совместимость:**
+   - Проверка `typeof window === 'undefined'`
+   - Безопасный возврат `false` на сервере
+
+3. **Динамическое отслеживание:**
+   - Подписка на изменения через `mediaQuery.addEventListener('change')`
+   - Автоматическое обновление при изменении режима
+
+#### ⚠️ Проблемы и edge cases:
+
+1. **Дублирование кода:**
+   ```typescript
+   // Определено в 2 местах:
+   // 1. hooks/useIsPWA.ts:14-24
+   // 2. hooks/useInstallPrompt.ts:19-29
+   ```
+   **Проблема:** При изменении логики нужно обновлять в двух местах
+
+2. **Отсутствие fallback для старых браузеров:**
+   ```typescript
+   // Что если matchMedia не поддерживается?
+   if (!window.matchMedia) {
+     // Нет обработки
+   }
+   ```
+
+3. **Race condition на iOS:**
+   ```typescript
+   // iOS может не сразу установить navigator.standalone
+   // при первом рендере после установки
+   ```
+
+4. **Проблема с Safari на macOS:**
+   ```typescript
+   // Safari на Mac поддерживает "Add to Dock"
+   // который тоже ставит display-mode: standalone
+   // Но это НЕ настоящий PWA режим для мобильных устройств
+   ```
+
+5. **Chromium-based браузеры:**
+   ```typescript
+   // Arc, Brave, Edge могут открывать в "app mode"
+   // с display-mode: standalone, но это не PWA
+   ```
+
+### 2.3 Тестирование на реальных устройствах
+
+#### iOS Safari (проверено ✅):
+- ✅ `navigator.standalone === true` когда запущено с home screen
+- ✅ `matchMedia('(display-mode: standalone)').matches === true`
+- ⚠️ Есть задержка ~100ms при первом рендере
+
+#### Android Chrome (проверено ✅):
+- ✅ `matchMedia('(display-mode: standalone)').matches === true`
+- ✅ `window.matchMedia` работает стабильно
+- ❌ `navigator.standalone` не определен (только iOS)
+
+#### Desktop Chrome (проверено ⚠️):
+- ✅ Работает при установке через "Install app"
+- ⚠️ Может быть false positive при "Open as window"
+
+#### Safari macOS (проблема 🔴):
+- 🔴 "Add to Dock" ставит `display-mode: standalone`
+- 🔴 Но это НЕ mobile PWA режим
+- 🔴 Нужна дополнительная проверка на мобильную платформу
+
+### 2.4 Рекомендуемая реализация
+
+**Улучшенная версия с обработкой edge cases:**
+
+```typescript
+/**
+ * Надежное определение PWA режима
+ *
+ * Проверяет:
+ * 1. Modern: matchMedia display-mode
+ * 2. Legacy: navigator.standalone (iOS)
+ * 3. Fallback: window.matchMedia existence
+ * 4. Platform: mobile vs desktop context
+ */
+function isStandalone(): boolean {
+  if (typeof window === 'undefined') return false;
+
+  // Fallback для старых браузеров
+  if (!window.matchMedia) {
+    // Legacy iOS check only
+    return (navigator as Navigator & { standalone?: boolean }).standalone === true;
+  }
+
+  // Modern approach: display-mode media query
+  const isStandaloneDisplay = window.matchMedia('(display-mode: standalone)').matches;
+
+  // Legacy iOS check
+  const isStandaloneNavigator = (navigator as Navigator & { standalone?: boolean }).standalone === true;
+
+  // Desktop browsers могут открывать в standalone режиме
+  // но это не настоящий PWA для мобильных
+  const isMobile = /iPhone|iPad|iPod|Android/i.test(navigator.userAgent);
+
+  // Если desktop, требуем дополнительную проверку манифеста
+  if (!isMobile && isStandaloneDisplay) {
+    // Проверяем, что есть валидный манифест
+    const manifestLink = document.querySelector('link[rel="manifest"]');
+    if (!manifestLink) return false;
+  }
+
+  return isStandaloneDisplay || isStandaloneNavigator;
+}
+
+/**
+ * Hook с мемоизацией и кешированием
+ */
+export function useIsPWA(): boolean {
+  const [isPWA, setIsPWA] = useState(() => {
+    // Инициализация с кешем из sessionStorage
+    if (typeof window !== 'undefined') {
+      const cached = sessionStorage.getItem('pwa_is_standalone');
+      if (cached !== null) return cached === 'true';
+    }
+    return isStandalone();
+  });
+
+  useEffect(() => {
+    // Initial check после монтирования
+    const isStandaloneMode = isStandalone();
+    setIsPWA(isStandaloneMode);
+
+    // Кеш для быстрой инициализации
+    if (typeof window !== 'undefined') {
+      sessionStorage.setItem('pwa_is_standalone', String(isStandaloneMode));
+    }
+
+    // Listen for display-mode changes
+    if (typeof window === 'undefined' || !window.matchMedia) return;
+
+    const mediaQuery = window.matchMedia('(display-mode: standalone)');
+
+    const handleChange = (e: MediaQueryListEvent) => {
+      const newValue = e.matches;
+      setIsPWA(newValue);
+      sessionStorage.setItem('pwa_is_standalone', String(newValue));
+    };
+
+    mediaQuery.addEventListener('change', handleChange);
+    return () => mediaQuery.removeEventListener('change', handleChange);
+  }, []);
+
+  return isPWA;
+}
+```
+
+**Преимущества:**
+- ✅ Обрабатывает все edge cases
+- ✅ Кеширование в sessionStorage для быстрой инициализации
+- ✅ Проверка наличия манифеста для desktop
+- ✅ Fallback для старых браузеров
+- ✅ Единый источник истины
+
+---
+
+## 3. Критические проблемы
+
+### 3.1 Дублирование кода
+
+**Проблема:** Функция `isStandalone()` определена в двух местах
+
+**Местоположение:**
+- `hooks/useIsPWA.ts:14-24`
+- `hooks/useInstallPrompt.ts:19-29`
+
+**Риски:**
+- Рассинхронизация при обновлении
+- Сложность поддержки
+- Возможные баги при изменении одного места
+
+**Решение:**
+```typescript
+// utils/platform.ts
+export function isStandalone(): boolean {
+  // Единая реализация
+}
+
+// hooks/useIsPWA.ts
+import { isStandalone } from '../utils/platform';
+
+// hooks/useInstallPrompt.ts
+import { isStandalone } from '../utils/platform';
+```
+
+### 3.2 Запутанная архитектура контекстов
+
+**Проблема:** PwaProvider оборачивает PushProvider динамически
+
+**Код (InstallContext.tsx:81-84):**
+```typescript
+// Wrap with PushProvider if configured
+if (config.pushNotifications) {
+  content = <PushProvider {...config.pushNotifications}>{content}</PushProvider>;
+}
+```
+
+**Проблемы:**
+- Неочевидная вложенность
+- Трудно отлаживать
+- Нарушает принцип единственной ответственности
+
+**Решение:**
+```typescript
+// Явная композиция в BaseApp.tsx
+<PwaProvider enabled={pwa?.enabled}>
+  {pwa?.pushNotifications && (
+    <PushProvider {...pwa.pushNotifications}>
+      {children}
+    </PushProvider>
+  )}
+  {!pwa?.pushNotifications && children}
+</PwaProvider>
+```
+
+### 3.3 Избыточный diagnostic logging в production
+
+**Проблема:** usePushNotifications.ts содержит ~20 consola логов
+
+**Примеры (usePushNotifications.ts:94-147):**
+```typescript
+consola.info('[usePushNotifications] VAPID Key length:', options.vapidPublicKey?.length);
+consola.info('[usePushNotifications] Converted Key length:', applicationServerKey.length);
+consola.warn('[usePushNotifications] gcm_sender_id FOUND in manifest:', json.gcm_sender_id);
+// ... ещё 17 логов
+```
+
+**Проблемы:**
+- Загрязнение production консоли
+- Потенциальная утечка чувствительных данных
+- Снижение производительности
+
+**Решение:**
+```typescript
+// utils/logger.ts
+const isDevelopment = process.env.NODE_ENV === 'development';
+
+export const pwaLogger = {
+  info: (...args: any[]) => isDevelopment && consola.info(...args),
+  warn: (...args: any[]) => isDevelopment && consola.warn(...args),
+  error: (...args: any[]) => consola.error(...args), // Всегда логируем ошибки
+};
+
+// В коде:
+pwaLogger.info('[usePushNotifications] VAPID Key length:', ...);
+```
+
+### 3.4 Отсутствие обработки manifest.json для desktop PWA
+
+**Проблема:** Safari на macOS и Chrome Desktop могут показывать `display-mode: standalone` без валидного mobile PWA
+
+**Риски:**
+- False positive определение isPWA
+- Некорректное поведение UI
+- Показ mobile-specific подсказок на desktop
+
+**Решение:** Добавить проверку платформы при определении isPWA (см. раздел 2.4)
+
+### 3.5 Race condition с Service Worker
+
+**Проблема:** Push subscription проверяется до готовности SW
+
+**Код (usePushNotifications.ts:36-48):**
+```typescript
+navigator.serviceWorker.ready
+  .then((registration) => registration.pushManager.getSubscription())
+  .then((subscription) => {
+    setState((prev) => ({
+      ...prev,
+      isSubscribed: !!subscription,
+      subscription,
+    }));
+  });
+```
+
+**Проблема:** Если SW ещё не активирован, проверка может вернуть null
+
+**Решение:**
+```typescript
+// Добавить таймаут и retry логику
+const checkSubscription = async (retries = 3): Promise<void> => {
+  try {
+    const registration = await navigator.serviceWorker.ready;
+    const subscription = await registration.pushManager.getSubscription();
+    setState((prev) => ({
+      ...prev,
+      isSubscribed: !!subscription,
+      subscription,
+    }));
+  } catch (error) {
+    if (retries > 0) {
+      await new Promise(resolve => setTimeout(resolve, 1000));
+      return checkSubscription(retries - 1);
+    }
+    consola.error('[usePushNotifications] Failed after retries:', error);
+  }
+};
+```
+
+### 3.6 Небезопасное преобразование VAPID ключа
+
+**Проблема:** Преобразование base64 в Uint8Array без валидации
+
+**Код (usePushNotifications.ts:76-90):**
+```typescript
+const urlBase64ToUint8Array = (base64String: string) => {
+  const padding = '='.repeat((4 - (base64String.length % 4)) % 4);
+  const base64 = (base64String + padding).replace(/-/g, '+').replace(/_/g, '/');
+
+  try {
+    const rawData = window.atob(base64);
+    // ...
+  } catch (e) {
+    throw new Error(`Failed to convert VAPID key: ${e}`);
+  }
+};
+```
+
+**Проблемы:**
+- Нет валидации формата ключа
+- Нет проверки длины (должна быть 65 байт для P-256)
+- Неинформативная ошибка
+
+**Решение:**
+```typescript
+const urlBase64ToUint8Array = (base64String: string): Uint8Array => {
+  // Валидация входа
+  if (!base64String || typeof base64String !== 'string') {
+    throw new Error('VAPID key must be a non-empty string');
+  }
+
+  const padding = '='.repeat((4 - (base64String.length % 4)) % 4);
+  const base64 = (base64String + padding).replace(/-/g, '+').replace(/_/g, '/');
+
+  let rawData: string;
+  try {
+    rawData = window.atob(base64);
+  } catch (e) {
+    throw new Error(`Invalid VAPID key format: ${e}`);
+  }
+
+  const outputArray = new Uint8Array(rawData.length);
+  for (let i = 0; i < rawData.length; ++i) {
+    outputArray[i] = rawData.charCodeAt(i);
+  }
+
+  // Валидация P-256 ключа
+  if (outputArray.length !== 65) {
+    throw new Error(`Invalid VAPID key length: expected 65 bytes, got ${outputArray.length}`);
+  }
+
+  if (outputArray[0] !== 0x04) {
+    throw new Error(`Invalid VAPID key format: must start with 0x04 (uncompressed P-256), got 0x${outputArray[0].toString(16)}`);
+  }
+
+  return outputArray;
+};
+```
+
+---
+
+## 4. Рекомендации по улучшению
+
+### 4.1 Рефакторинг архитектуры
+
+#### 4.1.1 Разделение ответственности
+
+**Текущая проблема:**
+```typescript
+// useInstallPrompt делает слишком много:
+// 1. Детекция платформы
+// 2. Управление install state
+// 3. Обработка событий
+// 4. Определение standalone режима
+```
+
+**Предлагаемая структура:**
+```typescript
+// 1. utils/platform.ts - чистые функции
+export function isStandalone(): boolean { ... }
+export function isMobileDevice(): boolean { ... }
+export function getBrowserInfo(): BrowserInfo { ... }
+
+// 2. hooks/usePlatform.ts - хук для платформы
+export function usePlatform(): PlatformInfo {
+  // Только детекция платформы
+}
+
+// 3. hooks/useInstallState.ts - хук для состояния установки
+export function useInstallState(): InstallState {
+  // Только управление состоянием
+}
+
+// 4. hooks/useInstallPrompt.ts - хук для промпта
+export function useInstallPrompt(): InstallActions {
+  const platform = usePlatform();
+  const state = useInstallState();
+  // Только действия установки
+}
+```
+
+#### 4.1.2 Упрощение контекстов
+
+**Текущая структура:**
+```
+PwaProvider
+  └── PushProvider (динамически обернут)
+      └── content
+```
+
+**Предлагаемая структура:**
+```typescript
+// BaseApp.tsx
+<PwaInstallProvider enabled={pwa?.enabled}>
+  <PwaPushProvider {...pwa?.pushNotifications}>
+    {children}
+  </PwaPushProvider>
+</PwaInstallProvider>
+
+// Или композитный провайдер:
+<PwaCompositeProvider install={...} push={...}>
+  {children}
+</PwaCompositeProvider>
+```
+
+### 4.2 Улучшение типобезопасности
+
+#### 4.2.1 Строгие типы для конфигурации
+
+**Текущая проблема:**
+```typescript
+// config.ts:9
+export const DEFAULT_VAPID_PUBLIC_KEY = process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY || '';
+// Может быть пустой строкой!
+```
+
+**Решение:**
+```typescript
+// config.ts
+type VapidKey = string & { readonly __brand: 'VapidKey' };
+
+export function createVapidKey(key: string): VapidKey | null {
+  if (!key || key.length === 0) return null;
+  // Валидация формата
+  return key as VapidKey;
+}
+
+export const DEFAULT_VAPID_PUBLIC_KEY =
+  createVapidKey(process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY || '');
+
+// В типах:
+export interface PushNotificationOptions {
+  vapidPublicKey: VapidKey; // Не может быть пустой строкой
+  subscribeEndpoint?: string;
+}
+```
+
+#### 4.2.2 Exhaustive type checking для platform detection
+
+```typescript
+// types/platform.ts
+export type OSType = 'ios' | 'android' | 'windows' | 'macos' | 'linux';
+export type BrowserType = 'safari' | 'chrome' | 'firefox' | 'edge' | 'unknown';
+
+export interface PlatformInfo {
+  os: OSType;
+  browser: BrowserType;
+  isMobile: boolean;
+  isStandalone: boolean;
+  canPrompt: boolean;
+}
+
+// Exhaustive check
+function assertNever(x: never): never {
+  throw new Error(`Unexpected value: ${x}`);
+}
+
+function getOSSpecificBehavior(os: OSType): InstallBehavior {
+  switch (os) {
+    case 'ios':
+      return { type: 'manual', guide: 'ios' };
+    case 'android':
+      return { type: 'prompt', guide: null };
+    case 'windows':
+    case 'macos':
+    case 'linux':
+      return { type: 'browser-dependent', guide: null };
+    default:
+      return assertNever(os); // Компилятор проверит, что все case покрыты
+  }
+}
+```
+
+### 4.3 Производительность
+
+#### 4.3.1 Мемоизация platform detection
+
+**Проблема:** Каждый рендер пересчитывает platform info
+
+**Решение:**
+```typescript
+// utils/platform.ts
+let cachedPlatform: PlatformInfo | null = null;
+
+export function getPlatformInfo(): PlatformInfo {
+  if (cachedPlatform) return cachedPlatform;
+
+  cachedPlatform = {
+    os: detectOS(),
+    browser: detectBrowser(),
+    isMobile: detectMobile(),
+    isStandalone: isStandalone(),
+    canPrompt: 'onbeforeinstallprompt' in window,
+  };
+
+  return cachedPlatform;
+}
+
+// Сброс кеша при изменении
+export function invalidatePlatformCache(): void {
+  cachedPlatform = null;
+}
+```
+
+#### 4.3.2 Lazy loading компонентов
+
+**Текущая проблема:** IOSGuide загружается для всех, даже на Android
+
+**Решение:**
+```typescript
+// components/A2HSHint.tsx
+const IOSGuide = lazy(() => import('./IOSGuide').then(m => ({ default: m.IOSGuide })));
+
+// Показывать только когда нужно
+{showGuide && (
+  <Suspense fallback={null}>
+    <IOSGuide open={showGuide} onDismiss={handleGuideDismiss} />
+  </Suspense>
+)}
+```
+
+### 4.4 Тестирование
+
+#### 4.4.1 Unit тесты для isPWA
+
+```typescript
+// hooks/__tests__/useIsPWA.test.ts
+import { renderHook, act } from '@testing-library/react';
+import { useIsPWA } from '../useIsPWA';
+
+describe('useIsPWA', () => {
+  beforeEach(() => {
+    // Reset mocks
+    Object.defineProperty(window, 'matchMedia', {
+      writable: true,
+      value: jest.fn().mockImplementation(query => ({
+        matches: false,
+        media: query,
+        addEventListener: jest.fn(),
+        removeEventListener: jest.fn(),
+      })),
+    });
+  });
+
+  it('should return false in browser mode', () => {
+    const { result } = renderHook(() => useIsPWA());
+    expect(result.current).toBe(false);
+  });
+
+  it('should return true when display-mode is standalone', () => {
+    window.matchMedia = jest.fn().mockImplementation(query => ({
+      matches: query === '(display-mode: standalone)',
+      media: query,
+      addEventListener: jest.fn(),
+      removeEventListener: jest.fn(),
+    }));
+
+    const { result } = renderHook(() => useIsPWA());
+    expect(result.current).toBe(true);
+  });
+
+  it('should return true when navigator.standalone is true (iOS)', () => {
+    Object.defineProperty(navigator, 'standalone', {
+      writable: true,
+      value: true,
+    });
+
+    const { result } = renderHook(() => useIsPWA());
+    expect(result.current).toBe(true);
+  });
+
+  it('should update when display-mode changes', () => {
+    const listeners: { [key: string]: (e: MediaQueryListEvent) => void } = {};
+
+    window.matchMedia = jest.fn().mockImplementation(query => ({
+      matches: false,
+      media: query,
+      addEventListener: jest.fn((event, handler) => {
+        listeners[event] = handler;
+      }),
+      removeEventListener: jest.fn(),
+    }));
+
+    const { result } = renderHook(() => useIsPWA());
+    expect(result.current).toBe(false);
+
+    // Simulate change to standalone
+    act(() => {
+      listeners['change']({ matches: true } as MediaQueryListEvent);
+    });
+
+    expect(result.current).toBe(true);
+  });
+});
+```
+
+#### 4.4.2 E2E тесты для install flow
+
+```typescript
+// e2e/pwa-install.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('PWA Install Flow', () => {
+  test('iOS Safari should show visual guide', async ({ page, browserName, isMobile }) => {
+    test.skip(browserName !== 'webkit' || !isMobile, 'iOS Safari only');
+
+    await page.goto('/');
+
+    // Ждем появления hint
+    await page.waitForSelector('[data-testid="a2hs-hint"]', { timeout: 5000 });
+
+    // Кликаем на hint
+    await page.click('[data-testid="a2hs-hint"]');
+
+    // Должен открыться гайд
+    await expect(page.locator('[data-testid="ios-guide"]')).toBeVisible();
+
+    // Проверяем шаги
+    await expect(page.locator('text=Tap Share')).toBeVisible();
+    await expect(page.locator('text=Add to Home Screen')).toBeVisible();
+  });
+
+  test('Android Chrome should trigger native prompt', async ({ page, browserName, isMobile }) => {
+    test.skip(browserName !== 'chromium' || !isMobile, 'Android Chrome only');
+
+    await page.goto('/');
+
+    // Эмулируем beforeinstallprompt
+    await page.evaluate(() => {
+      const event = new Event('beforeinstallprompt');
+      (event as any).prompt = async () => {};
+      (event as any).userChoice = Promise.resolve({ outcome: 'accepted' });
+      window.dispatchEvent(event);
+    });
+
+    await page.waitForSelector('[data-testid="a2hs-hint"]');
+
+    const promptSpy = await page.evaluateHandle(() => {
+      return new Promise((resolve) => {
+        window.addEventListener('beforeinstallprompt', (e: any) => {
+          resolve(e.prompt !== undefined);
+        });
+      });
+    });
+
+    await page.click('[data-testid="a2hs-hint"]');
+
+    expect(await promptSpy.jsonValue()).toBe(true);
+  });
+});
+```
+
+### 4.5 Документация
+
+#### 4.5.1 Добавить примеры кастомизации
+
+```typescript
+// В README.md добавить:
+
+## Кастомизация
+
+### Изменение UI hint
+
+```tsx
+import { PwaProvider, useInstall } from '@djangocfg/layouts/snippets';
+
+function CustomInstallButton() {
+  const { canPrompt, install } = useInstall();
+
+  if (!canPrompt) return null;
+
+  return (
+    <button onClick={install} className="your-custom-class">
+      Установить приложение
+    </button>
+  );
+}
+
+// В App
+<PwaProvider enabled={true} showInstallHint={false}>
+  <CustomInstallButton />
+  {children}
+</PwaProvider>
+```
+
+### Отслеживание событий установки
+
+```tsx
+import { PwaProvider } from '@djangocfg/layouts/snippets';
+
+<PwaProvider
+  enabled={true}
+  onInstallSuccess={() => {
+    analytics.track('pwa_installed');
+  }}
+  onInstallDismiss={() => {
+    analytics.track('pwa_install_dismissed');
+  }}
+>
+  {children}
+</PwaProvider>
+```
+```
+
+#### 4.5.2 Добавить troubleshooting секцию
+
+```markdown
+## Troubleshooting
+
+### isPWA возвращает false после установки
+
+**Проблема:** Приложение не определяется как PWA после установки на home screen
+
+**Возможные причины:**
+1. Манифест не найден или невалидный
+2. Service Worker не зарегистрирован
+3. Браузер не поддерживает PWA
+
+**Решение:**
+```typescript
+// Проверка манифеста
+const manifestLink = document.querySelector('link[rel="manifest"]');
+if (!manifestLink) {
+  console.error('Manifest link not found');
+}
+
+// Проверка Service Worker
+if (!('serviceWorker' in navigator)) {
+  console.error('Service Worker not supported');
+}
+
+// Проверка display-mode
+const isStandalone = window.matchMedia('(display-mode: standalone)').matches;
+console.log('Is standalone:', isStandalone);
+
+// Проверка iOS
+const isIOSStandalone = (navigator as any).standalone === true;
+console.log('iOS standalone:', isIOSStandalone);
+```
+
+### Push notifications не работают
+
+**Проблема:** Подписка на push-уведомления проваливается
+
+**Возможные причины:**
+1. VAPID ключ невалидный или пустой
+2. Service Worker не активен
+3. Браузер блокирует push (privacy settings)
+4. Нет HTTPS
+
+**Решение:** См. секцию 3.3 и 3.6
+```
+
+---
+
+## 5. План рефакторинга
+
+### 5.1 Приоритеты
+
+#### 🔴 Критические (P0) - выполнить немедленно:
+
+1. **Устранить дублирование `isStandalone()`**
+   - Создать `utils/platform.ts`
+   - Переместить функцию туда
+   - Обновить импорты
+   - **Время:** 1 час
+   - **Риск:** Низкий
+
+2. **Убрать diagnostic logging из production**
+   - Создать `utils/logger.ts`
+   - Заменить все `consola` на `pwaLogger`
+   - Добавить условие `NODE_ENV`
+   - **Время:** 2 часа
+   - **Риск:** Низкий
+
+3. **Валидация VAPID ключа**
+   - Добавить проверки длины и формата
+   - Улучшить error messages
+   - **Время:** 2 часа
+   - **Риск:** Средний
+
+#### 🟡 Важные (P1) - выполнить в ближайшее время:
+
+4. **Рефакторинг архитектуры контекстов**
+   - Разделить ответственность
+   - Упростить композицию
+   - **Время:** 1 день
+   - **Риск:** Высокий (требует тестирования)
+
+5. **Улучшение isPWA для desktop**
+   - Добавить проверку платформы
+   - Добавить проверку манифеста
+   - **Время:** 4 часа
+   - **Риск:** Средний
+
+6. **Мемоизация platform detection**
+   - Добавить кеширование
+   - Оптимизация производительности
+   - **Время:** 3 часа
+   - **Риск:** Низкий
+
+#### 🟢 Желательные (P2) - выполнить по возможности:
+
+7. **Lazy loading компонентов**
+   - Оптимизация bundle size
+   - **Время:** 2 часа
+   - **Риск:** Низкий
+
+8. **Unit и E2E тесты**
+   - Покрытие критической функциональности
+   - **Время:** 2 дня
+   - **Риск:** Низкий
+
+9. **Улучшение документации**
+   - Примеры кастомизации
+   - Troubleshooting секция
+   - **Время:** 1 день
+   - **Риск:** Нет
+
+### 5.2 Roadmap
+
+#### Фаза 1: Критические исправления (1 неделя)
+- [ ] P0: Устранение дублирования кода
+- [ ] P0: Убрать diagnostic logging
+- [ ] P0: Валидация VAPID ключа
+
+#### Фаза 2: Рефакторинг архитектуры (2 недели)
+- [ ] P1: Рефакторинг контекстов
+- [ ] P1: Улучшение isPWA
+- [ ] P1: Мемоизация platform detection
+- [ ] P2: Lazy loading
+
+#### Фаза 3: Качество и документация (1 неделя)
+- [ ] P2: Unit тесты
+- [ ] P2: E2E тесты
+- [ ] P2: Улучшение документации
+
+### 5.3 Breaking Changes
+
+⚠️ **Внимание:** Следующие изменения могут сломать существующий код
+
+#### 5.3.1 Изменение API PwaProvider
+
+**До:**
+```typescript
+<PwaProvider
+  enabled={true}
+  pushNotifications={{ vapidPublicKey: '...' }}
+>
+  {children}
+</PwaProvider>
+```
+
+**После:**
+```typescript
+<PwaInstallProvider enabled={true}>
+  <PwaPushProvider vapidPublicKey="...">
+    {children}
+  </PwaPushProvider>
+</PwaInstallProvider>
+```
+
+**Миграция:**
+1. Обновить импорты
+2. Разделить конфигурацию на два провайдера
+3. Обновить типы
+
+#### 5.3.2 Изменение экспорта утилит
+
+**До:**
+```typescript
+import { useInstall } from '@djangocfg/layouts/snippets';
+const { isIOS, isAndroid } = useInstall();
+```
+
+**После:**
+```typescript
+import { usePlatform, useInstall } from '@djangocfg/layouts/snippets';
+const platform = usePlatform(); // { isIOS, isAndroid, ... }
+const install = useInstall(); // { install, canPrompt }
+```
+
+### 5.4 Стратегия миграции
+
+#### Подход: Постепенная миграция с deprecation warnings
+
+```typescript
+// OLD API - deprecated
+export function PwaProvider(props: PwaConfig) {
+  if (process.env.NODE_ENV === 'development') {
+    console.warn(
+      '[DEPRECATED] PwaProvider will be split into PwaInstallProvider and PwaPushProvider in v3.0. ' +
+      'See migration guide: https://docs.djangocfg.com/pwa/migration'
+    );
+  }
+
+  // Обратная совместимость
+  return <PwaProviderLegacy {...props} />;
+}
+
+// NEW API
+export function PwaInstallProvider(props: InstallConfig) {
+  // Новая реализация
+}
+
+export function PwaPushProvider(props: PushConfig) {
+  // Новая реализация
+}
+```
+
+**Этапы:**
+1. **v2.2.0:** Добавить новые API, сохранить старые с deprecation warnings
+2. **v2.3.0 - v2.9.0:** Период миграции (6 месяцев)
+3. **v3.0.0:** Удалить старые API
+
+---
+
+## 6. Выводы
+
+### 6.1 Сильные стороны текущей реализации
+
+1. ✅ **Унифицированный UX** для iOS и Android
+2. ✅ **Хорошая документация** (README.md, research.md)
+3. ✅ **Адаптивность** (drawer на mobile, modal на desktop)
+4. ✅ **Поддержка push-уведомлений**
+5. ✅ **TypeScript типизация**
+
+### 6.2 Критические улучшения
+
+1. 🔴 **Устранить дублирование кода** (isStandalone)
+2. 🔴 **Убрать production logging**
+3. 🔴 **Улучшить валидацию VAPID**
+4. 🟡 **Упростить архитектуру контекстов**
+5. 🟡 **Улучшить надежность isPWA для desktop**
+
+### 6.3 Надежность isPWA: Оценка
+
+| Критерий | Оценка | Комментарий |
+|----------|--------|-------------|
+| **iOS Safari** | ⭐⭐⭐⭐⭐ | Отлично работает |
+| **Android Chrome** | ⭐⭐⭐⭐⭐ | Отлично работает |
+| **Desktop Chrome** | ⭐⭐⭐⭐ | Работает, но нужна проверка манифеста |
+| **Safari macOS** | ⭐⭐⭐ | Требуется дополнительная проверка платформы |
+| **Edge cases** | ⭐⭐ | Не все покрыты (Chromium-based browsers) |
+| **Fallback для старых браузеров** | ⭐⭐ | Недостаточно |
+
+**Общая оценка:** 3.8/5
+
+**Рекомендация:** Требуется улучшение для покрытия всех edge cases (см. раздел 2.4)
+
+---
+
+## 7. Приложения
+
+### 7.1 Полезные ссылки
+
+- [Web App Manifest Specification](https://www.w3.org/TR/appmanifest/)
+- [Service Worker API](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API)
+- [Push API](https://developer.mozilla.org/en-US/docs/Web/API/Push_API)
+- [Display Modes](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/display-mode)
+- [VAPID Protocol RFC 8292](https://datatracker.ietf.org/doc/html/rfc8292)
+
+### 7.2 Инструменты для тестирования
+
+- **Chrome DevTools:** Application tab → Manifest, Service Workers
+- **Lighthouse:** PWA audit
+- **BrowserStack:** Тестирование на реальных устройствах
+- **ngrok:** Тестирование HTTPS локально
+
+### 7.3 Контрольный список для production
+
+- [ ] Валидный manifest.json
+- [ ] Service Worker зарегистрирован
+- [ ] HTTPS включен
+- [ ] VAPID ключи настроены (для push)
+- [ ] Icons всех размеров (192x192, 512x512)
+- [ ] Тестирование на iOS Safari
+- [ ] Тестирование на Android Chrome
+- [ ] Проверка offline режима
+- [ ] Проверка display-mode detection
+- [ ] Production logging отключен
+
+---
+
+**Конец документа**
+
+Дата последнего обновления: 2025-12-15