# Техническая спецификация
## Windows Keyboard Layout Transliteration Tool v1.0

> Конвертировано из `KeyboardTransliterator_Specification_v1.0.docx`. Источник `.docx` остаётся авторитетным оригиналом; этот файл - его читаемая Markdown-версия.

---

## 1. Обзор системы

Приложение для Windows, предоставляющее возможность транслитерации текста между раскладками клавиатуры (EN ↔ RU/UK) посредством глобального перехвата клавиатурных комбинаций и минималистичного UI-курсора с индикатором текущей раскладки.

### 1.1 Назначение

- Быстрая коррекция текста, набранного на неправильной раскладке.
- Минимальный UI - только кастомный курсор с индикатором текущей раскладки.
- Работает в фоне, активируется горячей клавишей.

---

## 2. Функциональные требования

### 2.1 Мониторинг клавиатуры

- Глобальный перехват клавиш (`SetWindowsHookEx`, `WH_KEYBOARD_LL`).
- Заданная горячая клавиша (по умолчанию: **Ctrl+Shift+T**).
- Работает во всех приложениях без исключений.

### 2.2 Обработка текста

- Получение активного окна Windows.
- Копирование выделенного текста (Ctrl+C).
- Транслитерация: QWERTY ↔ ЙЦУКЕН (обратная раскладка).
- Вставка результата вместо исходного текста (Ctrl+V).

### 2.3 UI - Кастомный курсор

- Две буквы текущей раскладки (EN, RU, UK) в углу курсора.
- Динамическое обновление при смене системной раскладки.
- Минимум пикселей, не загораживает видимый контент.

> 🛠 **Реализация v1.** Это **главная функция**. Системный текстовый курсор (I-beam, `OCR_IBEAM`) во время набора заменяется на каретку с маркером текущей раскладки (EN/RU/UK) через `SetSystemCursor`; маркер обновляется в реальном времени. Поскольку `SetSystemCursor` действует глобально, курсоры по умолчанию восстанавливаются при выходе/сбое (`SystemParametersInfo(SPI_SETCURSORS)`); единственный неперехватываемый случай - жёсткое завершение процесса (kill). Та же метка дублируется на значке в трее. Приложение - обычное приложение в интерактивном сеансе (не служба Windows), автозапуск - через `HKCU\..\Run`. Транслитерация (раздел 2.2) - **вторичная** функция.

---

## 3. Технические требования

| Критерий       | Значение                                          |
| -------------- | ------------------------------------------------- |
| ОС             | Windows 10, 11 (x64)                              |
| Runtime        | .NET 6+ или .NET Framework 4.8+                   |
| Язык           | C# 11+                                             |
| Раскладки      | EN (QWERTY), RU (ЙЦУКЕН), UK (опционально)         |
| Память         | < 50 MB в покое                                   |
| Распространение| Standalone `.exe` (zero dependencies)             |

---

## 4. Системная архитектура

### 4.1 Модули

#### `Program.cs`
Точка входа. Инициализация хука, UI курсора, event loop.

#### `KeyboardHook.cs`
- `SetWindowsHookEx` wrapper (`WH_KEYBOARD_LL`).
- Callback handler для перехваченных клавиш.
- Детектирование горячей клавиши (Ctrl+Shift+T).

#### `CursorIndicator.cs`
- Мониторинг системной раскладки (`GetKeyboardLayout`).
- Создание курсора (`CreateCursor` WinAPI).
- Рендеринг текста (GDI: `Graphics`, `Font`).
- Установка курсора (`SetCursor` WinAPI).

#### `TransliterationEngine.cs`
- `Dictionary<char, char>` для QWERTY → ЙЦУКЕН.
- Би-направленное преобразование.
- Обработка спецсимволов и пунктуации.

#### `ClipboardHandler.cs`
- Копирование выделения (Ctrl+C через WinAPI).
- Чтение из Clipboard.
- Вставка (Ctrl+V через WinAPI).

#### `WindowInterop.cs`
- `[DllImport]` для `SetWindowsHookEx`, `CreateCursor`, `SetCursor`, `GetForegroundWindow` и т.д.
- Структуры: `KBDLLHOOKSTRUCT`, `POINT`, `CURSORINFO`.

---

## 5. Детали реализации

### 5.1 Таблица транслитерации

Bidirectional mapping (полностью основано на стандартной ЙЦУКЕН):

```
QWERTY:  q w e r t y u i o p a s d f g h j k l z x c v b n m
ЙЦУКЕН:  й ц у к е н г ш щ з ф ы в а п р о л д ж э я ч с м и т ь
```

> ⚠️ **Замечание (расхождение в таблице).** В строке выше **28** кириллических букв на **26** клавиш QWERTY: лишние `ж` и `э` - это клавиши `;` и `'` на ЙЦУКЕН, а не буквенные клавиши. При выравнивании 1:1 их нужно убрать, иначе сдвигается всё, начиная с `z`. Реализация в `TransliterationEngine` использует выровненную таблицу из 26 пар (`z→я .. m→ь`):
>
> ```
> QWERTY:  q w e r t y u i o p a s d f g h j k l z x c v b n m
> ЙЦУКЕН:  й ц у к е н г ш щ з ф ы в а п р о л д я ч с м и т ь
> ```

### 5.2 Горячая клавиша

- Default: **Ctrl+Shift+T**
- Конфигурируемая через `config.json`.

> 🛠 **Реализация v1.** Значение по умолчанию изменено на **Ctrl+Shift+F12**: исходное Ctrl+Shift+T конфликтует с «вернуть закрытую вкладку» в браузерах и с системными инструментами извлечения текста. Горячая клавиша по-прежнему настраивается через `config.json`.

### 5.3 Обработка ошибок

- Нет выделения → skip (no-op).
- Clipboard lock → retry (max 3 попытки).
- Смена активного окна → cancel operation.

### 5.4 Производительность

- Hook callback: < 1 ms (non-blocking).
- Транслитерация: O(n), где n = length(text).
- Рендер курсора: 60 FPS (ограничивается WinAPI scheduler).

---

## 6. Тестирование

### 6.1 Unit тесты

| Компонент              | Сценарии                                      |
| ---------------------- | --------------------------------------------- |
| `TransliterationEngine`| EN→RU, RU→EN; спецсимволы, пунктуация; empty string |
| `KeyboardHook`         | Hotkey detection (Ctrl+Shift+T); hook installation/cleanup |
| `CursorIndicator`      | Cursor creation and rendering; layout detection (EN/RU/UK) |

### 6.2 Integration тесты

- End-to-end: Hotkey → Copy → Transliterate → Paste.
- Проверка в разных приложениях (Notepad, Word, Chrome).
- Переключение раскладок в реальном времени.

### 6.3 Manual тесты

- Cursor отображение: видимость, не блокирует контент.
- Долгоживущий процесс: 1+ hour, memory stable.
- Edge cases: multiline, selection at boundaries.

---

## 7. Развертывание

### 7.1 Сборка

```powershell
dotnet publish -c Release -r win-x64 --self-contained false
```

Результат: ~500 KB `.exe` (зависит от версии .NET framework).

### 7.2 Распространение

- Standalone `.exe` (no installer).
- Требует: .NET 6+ или .NET Framework 4.8+.
- Опционально: AppData folder для `config.json`.

### 7.3 Конфигурация

`config.json`:

```json
{
  "hotkey": "Ctrl+Shift+T",
  "layouts": ["EN", "RU"],
  "cursorSize": 24
}
```

---

## 8. Заключение

Приложение реализуется на C# / .NET с прямым доступом к Windows API через P/Invoke. Минималистичная архитектура (5 основных классов) позволяет быстрое развитие и поддержку.

**Приоритет:** надёжная работа hook, корректная транслитерация; UI курсора не в фокусе.

Ожидаемая первая версия готова к тестированию через 3-5 дней разработки.

---

## 9. Завершение работ: документация и сайт

Финальный шаг любых работ по этой спецификации:

- обновить **документацию проекта** - `README.md`, при необходимости `CLAUDE.md` (архитектура/модули) и тексты в самом приложении (tray-меню, тосты, окно настроек), если они затронуты;
- обновить **страницы сайта проекта** в `docs/` на **всех трёх языках - EN / RU / UK** (GitHub Pages): описание функции и, при наличии, скриншоты;
- обновить тексты **«What's new»** для релиза (skill `release`) и описания `winget` / Microsoft Store / VS Code Marketplace, если функция выходит наружу.