# SHiNE ESP32 Homeserver UI Nav Minimal Spec

Легаси-спецификация старого навигационного теста для `Waveshare ESP32-S3-Touch-AMOLED-2.16`.
Актуальный основной скетч теперь находится в `../main-device/shine_homeserver_main/`; этот документ оставлен только как историческая справка по старому тестовому UI.

## Цель

Этот прототип проверяет базовую механику экранов, крупных кнопок, свайпов, первичную настройку Wi-Fi и настройку серверных адресов через общий экран редактирования текста.

На этом этапе отсутствуют:
- логин/пароль учётной записи SHiNE;
- PIN;
- кошелёк;
- QR;
- регистрация;
- PDA update/create транзакции;
- входящие запросы.

## Экраны

Прототип содержит 10 экранов:
- `HOME`
- `SETTINGS_MENU`
- `WIFI_SCREEN`
- `SERVER_SCREEN`
- `ACCOUNT_SCREEN`
- `ACCOUNT_HOMESERVER_SCREEN`
- `ACCOUNT_SECRET_SCREEN`
- `SECRET_SHOW_SCREEN`
- `SECRET_GENERATE_*`
- `TEXT_EDIT_SCREEN`
- `REGISTER_ACCOUNT_PLACEHOLDER`

## HOME

Показывает:
- сверху слева значение homeserver или `homeserver not set`;
- ниже значение логина или `login not set`;
- справа от строки логина индикатор статуса Solana-аккаунта:
  - зелёный — все ключи совпадают;
  - красный — есть mismatch;
  - белый контур — пользователь не найден в Solana PDA;
- рядом с индикатором краткий текст ошибки, если статус не зелёный;
- третьей строкой `secret not set`, если секрет ещё не помечен как установленный;
- сверху справа один ряд индикаторов:
  - процент батареи;
  - иконка батареи;
  - индикатор Wi-Fi уровня сигнала;
- по центру крупный текст `STATUS`;
- одна строка Wi-Fi вида `Wi-Fi (<ssid>) connected/disconnected`;
- кнопка баланса вида `Balance: <value SOL>` или `Balance: failed to load`, по нажатию выполняет повторный запрос;
- строка `SHiNE: <server> connected/account not configured/unavailable`;
- при отсутствии пользователя в Solana PDA слева снизу появляется кнопка `REGISTER ACCOUNT`;
- снизу кнопку `SETTINGS`, уменьшенную примерно до половины ширины экрана и сдвинутую к правому краю.
- внизу на тёмной полосе подпись `SHiNE homeserver (v.0.18)`.

Строка Wi-Fi на `HOME`:
- `Wi-Fi (not configured) not configured`
- `Wi-Fi (<saved_ssid>) disconnected`
- `Wi-Fi (<current_ssid>) connected`

Переходы:
- кнопка `REGISTER ACCOUNT` -> `REGISTER_ACCOUNT_PLACEHOLDER`, только если пользователь не найден;
- кнопка `SETTINGS` -> `SETTINGS_MENU`;
- свайп влево -> `SETTINGS_MENU`.

Примечание:
- поведение `REGISTER ACCOUNT -> REGISTER_ACCOUNT_PLACEHOLDER` относится к старой тестовой версии и не является актуальным для основного скетча.

Фоновая логика:
- пока открыт `HOME`, экран сам обновляется примерно раз в секунду;
- при наличии `login + secret + homeserver` и Wi-Fi устройство читает Solana `user_pda` напрямую через RPC;
- сравниваются `root key`, `blockchain key`, `device key` и `homeserver` session-запись типа `100`;
- для строки `SHiNE:` устройство держит отдельную WebSocket-сессию с сервером SHiNE:
  - авторизация через `AuthChallenge/CreateAuthSession` или `SessionChallenge/SessionLogin`;
  - session key = публичный `homeserver key`;
  - подтверждение создания сессии подписывается `device key`;
  - heartbeat выполняется `Ping` раз в минуту.

## SETTINGS_MENU

Показывает вертикальное меню из 3 пунктов:
- `Wi-Fi`
- `Server`
- `Account`

Одновременно видны только 2 пункта.

Начальное состояние:
- `Wi-Fi`
- `Server`

После свайпа вверх:
- `Server`
- `Account`

После свайпа вниз:
- `Wi-Fi`
- `Server`

Обе видимые карточки меню имеют одинаковый цвет.

Переходы:
- нажатие `Wi-Fi` -> `WIFI_SCREEN`;
- нажатие `Server` -> `SERVER_SCREEN`;
- нажатие `Account` -> `ACCOUNT_SCREEN`;
- свайп вправо -> `HOME`.

## WIFI_SCREEN

Экран содержит 2 внутренних режима.

### 1. Overview

Показывает:
- текущий Wi-Fi статус;
- сохранённый SSID и число известных сетей;
- статусное сообщение;
- кнопку `SELECT NETWORK`;
- кнопку `CLEAR SAVED WI-FI`;
- кнопку `BACK`.

### 2. Scan Results

После `SELECT NETWORK` выполняется скан доступных Wi-Fi сетей.

Показывает:
- заголовок `SELECT NETWORK`;
- количество или результат сканирования;
- список найденных SSID как крупные кнопки;
- кнопку `SCAN AGAIN`;
- кнопку `BACK`.

Нажатие на SSID открывает `TEXT_EDIT_SCREEN` для ввода пароля.

Поведение:
- если для выбранного SSID пароль уже был сохранён раньше, он сразу подставляется в поле ввода;
- если пароль меняют для другого SSID, старые сохранённые пароли других сетей не теряются;
- после успешного подключения выбранная сеть становится текущей `wifi_ssid/wifi_pass`;
- одновременно хранится до `8` известных сетей `SSID -> password`;
- `CLEAR SAVED WI-FI` очищает все сохранённые сети и текущую сеть.

Переходы:
- свайп вправо из любого режима `WIFI_SCREEN` -> `SETTINGS_MENU`
- кнопка `BACK` -> `SETTINGS_MENU`

## SERVER_SCREEN

Показывает:
- статусное сообщение;
- текущий `Solana RPC` адрес;
- кнопку `SOLANA RPC`;
- текущий `Shine server` адрес;
- кнопку `SHINE SERVER`.

Значения по умолчанию:
- Solana RPC: `https://api.devnet.solana.com`
- Shine server: `https://shineup.me`

Нажатие на любую из двух кнопок открывает `TEXT_EDIT_SCREEN`.

Переходы:
- свайп вправо -> `SETTINGS_MENU`

## ACCOUNT_SCREEN

Показывает:
- заголовок `ACCOUNT`;
- статусное сообщение;
- кнопку `Login (<value|not set>)`;
- кнопку `Homeserver (<value|not set>)`;
- кнопку `Secret (<*****|not set>)`.

Переходы:
- свайп вправо -> `SETTINGS_MENU`
- `Login` -> `TEXT_EDIT_SCREEN`
- `Homeserver` -> `ACCOUNT_HOMESERVER_SCREEN`
- `Secret` -> `ACCOUNT_SECRET_SCREEN`

## ACCOUNT_HOMESERVER_SCREEN

Показывает:
- текущий `homeserver`;
- рекомендацию оставить `homeserver1`, если устройство одно;
- кнопку `USE HOMESERVER1`;
- кнопку `EDIT MANUALLY`;
- кнопку `BACK`.

Переходы:
- `USE HOMESERVER1` -> сохраняет `homeserver1` и возвращает в `ACCOUNT_SCREEN`
- `EDIT MANUALLY` -> `TEXT_EDIT_SCREEN`
- свайп вправо -> `ACCOUNT_SCREEN`

## ACCOUNT_SECRET_SCREEN

Показывает:
- кнопку `SHOW SECRET` или серую `SECRET NOT SET`, если секрета ещё нет;
- кнопку `ENTER SECRET MANUALLY (NOT RECOMMENDED)`;
- кнопку `GENERATE SECRET`.

Переходы:
- свайп вправо -> `ACCOUNT_SCREEN`
- `SHOW SECRET` -> экран просмотра секрета
- `ENTER SECRET MANUALLY (NOT RECOMMENDED)` -> `TEXT_EDIT_SCREEN`
- `GENERATE SECRET` -> экран подтверждения генерации

## SECRET_SHOW_SCREEN

Показывает:
- заголовок `SECRET`;
- вертикально прокручиваемый список ключей;
- `Secret (base58)`;
- `Root key (base58)`;
- `Root key priv (base58)`;
- `Blockchain key (base58)`;
- `Blockchain key priv (base58)`;
- `Device key (base58)`;
- `Device key priv (base58)`;
- `Homeserver key (base58)`;
- `Homeserver key priv (base58)`;
- для каждого поля показывается формула derivation;
- значения ключей показываются полными строками увеличенным шрифтом;
- кнопку `BACK`.

## TEXT_EDIT_SCREEN

Общий экран редактирования строковых значений.

Используется для:
- пароля Wi-Fi;
- Solana RPC;
- Shine server.

Показывает:
- заголовок;
- поле ввода, уже заполненное старым значением;
- новые символы всегда добавляются только в конец текста;
- визуальный курсор не показывается;
- пароль Wi-Fi показывается открыто, без маскировки точками;
- кнопки `SAVE`, `CANCEL`, `DEL`, `CLR`;
- большую экранную клавиатуру.

## REGISTER_ACCOUNT_PLACEHOLDER

Временный экран-заглушка регистрации.

Показывает:
- заголовок `REGISTER ACCOUNT`;
- сообщение, что регистрационный flow пока не реализован;
- кнопку `BACK`.

## Клавиатура

Клавиатура единая для всех текстовых вводов.

Особенности:
- занимает нижнюю часть экрана;
- разбита на 2 страницы;
- переключение страниц выполняется свайпом влево/вправо внутри `TEXT_EDIT_SCREEN`;
- страница 1 содержит в основном буквы и базовые URL-символы;
- страница 2 содержит цифры и дополнительные URL/символьные кнопки;
- переключение `ABC/123` и `SHIFT` не должно очищать уже введённый текст;
- переключение страниц клавиатуры свайпом тоже не должно очищать уже введённый текст, включая цифры, символы и уже набранные заглавные буквы;
- есть специальные действия `DEL` и `CLR`.

## Хранение Wi-Fi

Используется `Preferences` (NVS памяти ESP32):
- `wifi_ssid`
- `wifi_pass`
- `wifi_known_good`
- до `8` сохранённых пар `SSID -> password`

При старте устройства, если сохранён SSID, выполняется попытка подключения к текущей сохранённой сети.

Если пользователь уже вводил пароль для сети раньше:
- при повторном выборе этого SSID старый пароль сразу подставляется в editor screen;
- сохранение пароля для другой сети не удаляет уже сохранённые пароли остальных сетей.

Если сеть раньше уже была успешно подключена и помечена как валидная:
- после потери связи устройство автоматически пытается переподключиться;
- первые повторные попытки идут раз в `10` секунд;
- если связи нет долго, интервал увеличивается до `30` секунд.
- пока открыт `HOME`, экран сам обновляется примерно раз в секунду и подтягивает актуальные:
  - статус Wi-Fi;
  - SSID;
  - уровень сигнала;
  - процент батареи.

## Хранение серверов

Используется `Preferences` (NVS памяти ESP32):
- `solana_rpc`
- `shine_server`

## Хранение аккаунта

Используется `Preferences` (NVS памяти ESP32):
- `login`
- `homeserver`
- `secret_set`

## Детали клавиатуры

- клавиатура занимает примерно `2/3`-`3/4` высоты экрана;
- сверху остаются только заголовок и поле ввода;
- буквы занимают 3 ряда;
- половина букв находится на левой странице, половина на правой;
- на правой странице кнопки тоже стоят в ровных колонках, без сдвига рядов вправо;
- отдельный режим `symbols` тоже разделён на 2 страницы;
- 3 основных ряда клавиш и нижний служебный ряд увеличены по высоте;
- клавиши дополнительно увеличены по высоте по сравнению с предыдущим промежуточным вариантом;
- четвёртый ряд содержит:
  - переключение `ABC/123`
  - `SHIFT`
  - `DEL`
  - `SAVE`
  - `CANCEL`
- ниже рамки клавиатурного блока остаётся отдельная тёмная полоса с версией `SHiNE homeserver (v.0.18)`.

## Жесты

Поддерживаются направления:
- `SWIPE_LEFT`
- `SWIPE_RIGHT`
- `SWIPE_UP`
- `SWIPE_DOWN`

Маршруты:
- `HOME`: свайп влево -> `SETTINGS_MENU`
- `SETTINGS_MENU`: свайп вправо -> `HOME`
- `SETTINGS_MENU`: свайп вверх/вниз -> прокрутка списка
- `WIFI_SCREEN`: свайп вправо -> `SETTINGS_MENU`
- `SERVER_SCREEN`: свайп вправо -> `SETTINGS_MENU`
- `ACCOUNT_SCREEN`: свайп вправо -> `SETTINGS_MENU`
- `ACCOUNT_HOMESERVER_SCREEN`: свайп вправо -> `ACCOUNT_SCREEN`
- `ACCOUNT_SECRET_SCREEN`: свайп вправо -> `ACCOUNT_SCREEN`
- `TEXT_EDIT_SCREEN`: свайп влево/вправо -> переключение страниц клавиатуры
- переключение страниц клавиатуры срабатывает только если свайп начался в зоне самой клавиатуры, а не по всему экрану редактора

## Особенность обработки жестов

- если палец ушёл из зоны обычного тапа и жест определяется как свайп, случайное попадание на кнопку по пути не должно превращать свайп в нажатие;
- приоритет у свайпа, а не у `click`.
- одно непрерывное касание может вызвать не более одного действия кнопки;
- скольжение пальцем по экранной клавиатуре не должно вызывать цепочку из нескольких нажатий;
- периодический refresh на `HOME` не должен срабатывать во время активного касания.

## Язык

Пока интерфейс отображается в ASCII/English, чтобы использовать подтверждённый рабочий шрифтовой путь на устройстве.
