# PWA Demo Dashboard Implementation Plan

> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Сделать приложение installable PWA и добавить на дашборд панель, которая объясняет PWA и офлайн-работу demo-режима.

**Architecture:** PWA-слой реализуется вручную поверх текущего Vite-приложения: `public/manifest.webmanifest`, `public/service-worker.js` и регистрация service worker в `src/main.jsx`. Отдельный клиентский хук инкапсулирует онлайн-статус, установку и готовность PWA, а UI-панель на обзорном дашборде читает этот статус и показывает объяснение ограничений офлайн-demo.

**Tech Stack:** React 18, Vite 6, Vitest, existing UI kit, browser Service Worker / PWA APIs.

---

## Chunk 1: PWA Infrastructure

### Task 1: Зафиксировать требования к PWA-статусу в тестах

**Files:**
- Create: `src/hooks/usePwaStatus.test.jsx`
- Create: `src/test/pwaTestUtils.js`

- [ ] Написать падающие тесты для хука `usePwaStatus` на:
  - начальный онлайн-статус из `navigator.onLine`
  - переключение при событиях `online` / `offline`
  - появление install prompt после `beforeinstallprompt`
  - определение standalone-режима через `matchMedia("(display-mode: standalone)")`
- [ ] Прогнать только новый набор тестов.
  - Run: `npm test -- src/hooks/usePwaStatus.test.jsx`
  - Expected: FAIL из-за отсутствующего хука и/или test utils
- [ ] Добавить минимальные test utils для стабов `matchMedia`, `BeforeInstallPromptEvent`-подобного объекта и очистки listeners.
- [ ] Повторно прогнать тесты и убедиться, что они всё ещё падают уже по ожидаемой причине, связанной с отсутствием реализации.

### Task 2: Реализовать PWA runtime state

**Files:**
- Create: `src/hooks/usePwaStatus.js`
- Modify: `src/main.jsx`

- [ ] Реализовать `usePwaStatus` с полями:
  - `isOnline`
  - `isInstallAvailable`
  - `isInstalled`
  - `isServiceWorkerSupported`
  - `isOfflineReady`
  - `installApp`
- [ ] Добавить регистрацию `service-worker.js` в `src/main.jsx` только в production/browser-контексте.
- [ ] Передать в хук признак готовности service worker через событие `controllerchange`, `message` или локальное состояние регистрации.
- [ ] Прогнать таргетированные тесты.
  - Run: `npm test -- src/hooks/usePwaStatus.test.jsx`
  - Expected: PASS

### Task 3: Добавить manifest, service worker и статические PWA-ресурсы

**Files:**
- Create: `public/manifest.webmanifest`
- Create: `public/service-worker.js`
- Create: `public/icons/icon-192.svg`
- Create: `public/icons/icon-512.svg`
- Modify: `index.html`

- [ ] Добавить manifest с русскими именами приложения, `display: "standalone"`, theme/background colors и иконками.
- [ ] Подключить manifest и базовые meta tags в `index.html`.
- [ ] Реализовать `public/service-worker.js` с:
  - версионированным cache name
  - precache app shell (`/`, `/index.html`, manifest, icons)
  - navigation fallback на `/index.html`
  - cache-first для same-origin статических ассетов
  - сообщением клиенту о готовности офлайн-оболочки
- [ ] Добавить простые SVG-иконки, чтобы build/install не зависели от внешних файлов.
- [ ] Прогнать сборку.
  - Run: `npm run build`
  - Expected: PASS, в `dist/` появляются manifest и service worker

## Chunk 2: Dashboard Demo Panel

### Task 4: Зафиксировать UI-поведение панели в тестах

**Files:**
- Create: `src/components/dashboard/PwaDemoPanel.test.jsx`
- Create: `src/components/dashboard/PwaDemoPanel.jsx`

- [ ] Написать падающие тесты для панели на сценарии:
  - показывает объяснение PWA и demo-режима на русском
  - показывает online/offline badge
  - показывает install CTA только когда установка доступна
  - показывает ограничения для backend-интеграций
- [ ] Прогнать только тест панели.
  - Run: `npm test -- src/components/dashboard/PwaDemoPanel.test.jsx`
  - Expected: FAIL из-за отсутствующего компонента
- [ ] Реализовать минимальный `PwaDemoPanel` на `Panel`, `Badge`, `Button`.
- [ ] Повторно прогнать тест панели.
  - Run: `npm test -- src/components/dashboard/PwaDemoPanel.test.jsx`
  - Expected: PASS

### Task 5: Встроить панель в обзор дашборда

**Files:**
- Modify: `src/pages/DashboardPage.jsx`
- Optionally Modify: `src/components/UI/Badge.jsx` if понадобится новый tone

- [ ] Подключить `usePwaStatus` в `DashboardPage`.
- [ ] Разместить `PwaDemoPanel` в обзорной секции рядом с KPI/оперативными блоками без поломки существующей сетки.
- [ ] Убедиться, что панель рендерится только для авторизованного пользователя и не влияет на другие разделы.
- [ ] При необходимости добавить новый тон badge для позитивного статуса вместо инлайновых классов.
- [ ] Прогнать таргетированные тесты хука и панели вместе.
  - Run: `npm test -- src/hooks/usePwaStatus.test.jsx src/components/dashboard/PwaDemoPanel.test.jsx`
  - Expected: PASS

## Chunk 3: Verification and Hardening

### Task 6: Проверить интеграцию вручную и автоматикой

**Files:**
- Modify: `README.md`
- Optionally Modify: `docs/architecture.md`

- [ ] Обновить README кратким описанием PWA/demo offline behavior.
- [ ] При необходимости добавить в `docs/architecture.md` модуль `usePwaStatus` и описание PWA-оболочки.
- [ ] Запустить полный тестовый набор.
  - Run: `npm test`
  - Expected: PASS
- [ ] Запустить линтер.
  - Run: `npm run lint`
  - Expected: PASS
- [ ] Запустить production build.
  - Run: `npm run build`
  - Expected: PASS
- [ ] Выполнить ручную проверку:
  - открыть приложение онлайн
  - войти в demo-режиме
  - убедиться, что сервис-воркер зарегистрирован
  - перевести браузер offline
  - перезагрузить `/dashboard` и убедиться, что оболочка и demo-данные остаются доступны
  - проверить install CTA в поддерживаемом браузере
- [ ] Зафиксировать итог коротким комментарием в ответе пользователю: что работает офлайн, а что остаётся сетевым ограничением.