# Тех-задание: Android-клавиатура для эрзянского языка (новая латиница)

Краткий бриф для исполнителя (фрилансер / разработчик из сообщества). English version available on
request. Все упомянутые файлы — в папке `keyboard/` этого репозитория.

## Контекст
Проект Valks — словарь и инфраструктура эрзянского языка. Для языка принята новая латинская
орфография (Назаренко) с 16 особыми буквами (диакритика: `ä ö ü ë ï · š č ž ľ ť ď · ń ŕ ś ź ć`).
Десктоп-раскладки и макрос уже сделаны. Нужна **мобильная клавиатура для Android**.

## Главная идея (важно понять до старта)
Ценность клавиатуры — не в ряду диакритических клавиш, а в **восстановлении диакритики по словарю**:
пользователь печатает быстро ПЛОСКИМИ латинскими буквами, клавиатура подставляет правильное
написание (`melse` → `meľsë`). Это уже измерено на корпусе: **85%** слов восстанавливаются
однозначно (ноль выбора), остальное — лента из 2–3 кандидатов (98.6% укладываются в 3). Алгоритм
готов (см. `kbd_restore.py`), словарь готов (34k форм).

## Что предоставляется (вход)
- `keymap.json` — раскладка и инвентарь букв (источник истины).
- `data/kbd_dict.json` — индекс «скелет (плоский ASCII) → кандидаты (орфография)», ядро восстановления.
- `kbd_restore.py` — РЕФЕРЕНСНЫЙ алгоритм восстановления (Python) для порта на Kotlin: слово → скелет →
  словарь → top-1 + кандидаты; перенос регистра; OOV = как есть.
- `export/erzya_wordlist.tsv` — `слово<TAB>частота`, 34k форм (вход для словарного движка).
- `export/spike_testset.tsv` — пары `плоский ввод → ожидаемая орфография` для приёмки.
- `MOBILE-PLAN.md`, `export/SPIKE.md` — проектное обоснование и процедура спайка.

## Объём работ

### Фаза 0 — спайк (1–3 дня), ОПЛАЧИВАЕТСЯ ОТДЕЛЬНО, делается ПЕРВЫМ
Определить подход: загрузить `erzya_wordlist.tsv` в **FlorisBoard** (Apache-2.0) или
**AnySoftKeyboard** и проверить, складывает ли движок диакритику в подсказках (по `spike_testset.tsv`).
- Если ДА (фолдинг есть) → путь «упаковка»: раскладка + словарь, без своего движка.
- Если НЕТ → нужен свой провайдер подсказок поверх `kbd_dict.json`.
**Результат фазы 0:** короткий отчёт (складывается ли диакритика, доля пройденных тест-слов) и выбор пути.

### Фаза 1 — клавиатура v1 (оценка 1–4 недели, зависит от фазы 0)
- Эрзянская раскладка (база US/латиница + ввод 16 особых букв: прямые клавиши и/или долгое нажатие
  по `keymap.json`).
- **Восстановление диакритики по словарю** (порт `kbd_restore.py`): плоский ввод → орфография.
- **Лента кандидатов** для неоднозначных (тап заменяет слово), ранжирование по частоте из словаря.
- Базовый функционал клавиатуры: Shift/Caps, Backspace с автоповтором, переключение клавиатур,
  цифры/пунктуация, тёмная тема.
- Сборка APK, публикация в Google Play (аккаунт заказчика).

**Критерий приёмки фазы 1:** на `spike_testset.tsv` плоский ввод даёт корректную орфографию —
однозначные слова подставляются в top-1, неоднозначные присутствуют в ленте кандидатов; базовый
ввод (буквы/цифры/пунктуация/Shift/Backspace) работает; APK устанавливается и работает офлайн.

### Фаза 2 — опционально, позже
- **Скользящий ввод (glide/свайп)** по базовым буквам (словарь восстанавливает диакритику). На
  Android реализуемо через открытый glide-движок; на iOS невозможно (ограничение Apple).
- Обновление словаря (заказчик пришлёт расширенный `kbd_dict.json` — без изменения кода).
- iOS keyboard extension (отдельный бриф).

## Технические заметки
- Стек: Kotlin, Android `InputMethodService`. Рекомендация — форк/расширение **FlorisBoard**
  (Apache-2.0), чтобы переиспользовать клавиатурный каркас (и glide во Фазе 2). Альтернатива — свой IME.
- Восстановление — это словарный lookup по «скелету» (плоское написание), НЕ ML: детерминированно,
  быстро, офлайн. Логика полностью описана в `kbd_restore.py`.
- Лицензия результата — открытая (Apache-2.0/GPL), исходники в репозиторий заказчика.
- Свайп с нуля НЕ писать (это ядро Gboard); только через готовый открытый движок.

## Требуемые навыки
Android/Kotlin; желателен опыт с IME/клавиатурами или с FlorisBoard. Понимание словарных подсказок
(suggestions/autocorrect) — плюс.

## Оценка сроков (ориентир)
Фаза 0: 1–3 дня. Фаза 1: 1–2 недели, если путь «упаковка»; 3–4 недели, если нужен свой провайдер.
Публикация в Play: +несколько дней (настройка + ревью).
