docs: update file inventory and module header contracts

Refresh both AGENTS guides and clarify module purpose, usage, ownership, threading, return values and wire formats in headers. Remove the unused timeout_heap freed_count field and unimplemented getter.
2026-10-04 13:10:01 +02:00
1 parent c19eff67f6
commit a97e8bcc1f
@@ -19,8 +19,12 @@ tools/chatgui-android/
 │   ├── instance_lite.h/c     # жизненный цикл (старт/стоп/рестарт, ключи)
 │   ├── utun_config_api.h/c   # конфиг-провайдер (Kotlin → C)
 │   ├── invite_link_c.h/c     # старая копия парсера; .c не входит в UTUN_SOURCES
-│   ├── voice_recorder.h/c    # запись голосовых (PCM→Opus→канал)
-│   └── attachment_sender.h/c # отправка файлов в канал
+│   ├── voice_recorder.h/c    # накопление PCM; voice/file подготовка через общий attachment_send
+│   ├── attachment_sender.h/c # отправка обычных файлов в канал
+│   ├── photo_sender.h/c      # отправка готовых изображений в канал
+│   ├── video_sender.h/c      # готовый MP4 → attachment_send (канал/PM)
+│   ├── standby.h/c           # фоновые ACTIVE/SLEEP интервалы и отменяемое ожидание
+│   └── tests/test_standby.c   # тесты duty-cycle
 │
 ├── headless/                # CLI для Linux (тестирование без Android)
 │   ├── CMakeLists.txt
@@ -28,7 +32,8 @@ tools/chatgui-android/
 │   └── headless_control.c/h  # управляющий TCP-сокет (JSON/text протокол)
 │
 ├── jni_bridge/              # JNI прослойка C ↔ Kotlin
-│   └── android_jni_bridge.c/h  # C API + JNI-функции (компилятся только для Android)
+│   ├── android_jni_bridge.c/h  # C API; JNI-функции — только Android
+│   └── android_udp_log.c/h     # UDP-лог: общий буфер, flush в uasync
 │
 ├── app/                     # Android приложение (Gradle + NDK + Compose)
 │   ├── build.gradle.kts
@@ -45,20 +50,24 @@ tools/chatgui-android/
 │       │   │   ├── InviteLink.kt      # парсер utun://base64blob
 │       │   │   ├── ConfigProvider.kt  # конфиг из DataStore
 │       │   │   ├── LogManager.kt      # лог-менеджер
-│       │   │   └── ServerEntry.kt     # модели данных
+│       │   │   ├── ServerEntry.kt     # модель listen-сокета
+│       │   │   ├── CallAudioEngine.kt # capture/playback звонка через native voice stack
+│       │   │   ├── RadioAudioEngine.kt # capture/playback и PTT рации
+│       │   │   └── UtunConnectionService.kt # Android Telecom ConnectionService для P2P-звонков
 │       │   ├── viewmodel/
 │       │   │   └── ChatViewModel.kt   # StateFlow для UI
 │       │   ├── ui/screens/
 │       │   │   ├── ChannelListScreen.kt  # список каналов + join/create
 │       │   │   ├── ChatScreen.kt         # сообщения + ввод
 │       │   │   ├── JoinChannelDialog.kt  # диалог подключения по invite
-│       │   │   ├── QrScanScreen.kt       # CameraX + ML Kit QR-сканер
+│       │   │   ├── QrScannerPreview.kt   # CameraX + ML Kit QR-сканер
 │       │   │   ├── SettingsScreen.kt     # настройки
 │       │   │   └── LogScreen.kt          # лог-просмотр
 │       │   ├── ui/components/
 │       │   │   └── MessageBubble.kt      # бабблы сообщений + InputBar
 │       │   └── headless/
-│       │       └── HeadlessService.kt    # фоновый сервис
+│       │       ├── HeadlessService.kt    # foreground-service фонового ядра
+│       │       └── BootReceiver.kt       # запуск фонового сервиса после загрузки устройства
 │       └── res/
 │
 └── doc/                     # документация
@@ -263,15 +272,27 @@ port=9999
 - `../../src/chat/invite_link.c/h` — Общий C-код формата invite-ссылок; Android разбирает ссылки в `data/InviteLink.kt`.
  Старый `libutun_lite/invite_link_c.c` не компилируется текущим списком источников
 - `libutun_lite/utun_config_api.h/c` — Поставщик конфигурации из Kotlin в C-ядро через callback-интерфейс (get_string, get_int64, get_int)
- `libutun_lite/voice_recorder.h/c` — Запись голосовых сообщений: накопление PCM-сэмплов с компрессором, кодирование в Opus-файл, отправка в канал через chat_core
+- `libutun_lite/voice_recorder.h/c` — Накопление PCM 48 kHz mono с компрессором; stop передаёт запись в общий attachment_send для фонового кодирования и публикации в канал/PM
 - `src/call/call_audio.h/c` (+ `voice_jitter.cpp`, `call_tones.c`, SoundTouch) — единый голосовой стек звонка (`libutun_voice`), собирается через `src/call/voice_sources.cmake`; Opus encode (PCM→peer) и decode + адаптивный джиттер-буфер + time-stretch (PCM отдаётся через `nativeCallAudioPull`). Аудио I/O в Kotlin (AudioRecord/AudioTrack)
 - `libutun_lite/attachment_sender.h/c` — Отправка файлов в канал: копирование в media-директорию и регистрация через chat_core (media_index → db_sync)
+- `libutun_lite/photo_sender.h/c` — Отправка готового изображения в канал с MIME-типом и размерами; подготовка картинки выполняется в Android
+- `libutun_lite/video_sender.h/c` — Отправка подготовленного MP4 в канал/PM через attachment_send; задача владеет временным cache-файлом
+- `libutun_lite/standby.h/c` — ACTIVE/SLEEP интервалы фонового режима, callbacks смены фазы и отменяемые wait handles
+- `jni_bridge/android_udp_log.h/c` — Потокобезопасный буфер логов; timer flush привязан к текущему uasync и снимается при restart
 - `libutun_lite/utun_sources.cmake` — Общий список источников: `lib/*.c` и рекурсивный `src/*.c` подхватываются автоматически;
  файлы самой обёртки перечислены в `_cfg_src`, исключения — через `list(FILTER/REMOVE_ITEM)`

 ### Kotlin-слой
 - `data/NativeLib.kt` — Kotlin-обёртка над C-библиотекой: все вызовы из Kotlin транслируются в JNI-функции
 - `data/CallAudioEngine.kt` — Аудио-движок звонка: AudioRecord/AudioTrack, audio-focus, потоки захвата (feed) / воспроизведения (pull из C-стека)
+- `data/RadioAudioEngine.kt` — Аудио-движок рации: AudioRecord/AudioTrack, feed/pull native-стека и управление capture/PTT
+- `data/RadioPttHolds.kt` — Отдельные владельцы ручного PTT: кнопка, overlay и volume-клавиши; отпускание одного не снимает остальные
+- `data/RadioOverlayService.kt` — Плавающее окно PTT поверх других приложений
+- `data/ConversationTarget.kt` — Типизированный target канала/PM для асинхронных операций
+- `data/AudioRecorderManager.kt` — Android-захват PCM голосового сообщения и управление native voice_recorder
+- `data/CallController.kt` / `CallState.kt` — Управление состоянием и действиями P2P-звонка
+- `data/CallAudioRouter.kt` — Выбор аудиомаршрута звонка: earpiece/speaker/headset
+- `data/TelecomCallManager.kt` / `UtunConnection.kt` / `UtunConnectionService.kt` — Интеграция P2P-звонков с Android Telecom
 - `data/ChatRepository.kt` — Хранилище данных: буферизация сообщений и каналов между C-ядром и UI через StateFlow
 - `data/InviteLink.kt` — Разбор invite-ссылок: извлекает ID канала, публичный ключ, адреса для подключения
 - `data/ConfigProvider.kt` — Настройки DataStore и генерация INI-текста для запуска C-ядра
@@ -279,8 +300,15 @@ port=9999
 - `viewmodel/ChatViewModel.kt` — ViewModel: StateFlow-состояние для UI (список каналов, сообщения, статус)
 - `ui/screens/ChannelListScreen.kt` — Главный экран: список каналов, кнопки Join (по invite-ссылке) и Create
 - `ui/screens/ChatScreen.kt` — Экран чата: список сообщений + поле ввода
+- `ui/screens/DmChatScreen.kt` — Экран личной беседы
+- `ui/screens/MemberListScreen.kt` — Участники канала и действия над выбранным участником
+- `ui/screens/CallScreen.kt` / `IncomingCallDialog.kt` — Активный и входящий звонок
+- `ui/screens/PhotoRecordScreen.kt` / `VideoRecordScreen.kt` — Съёмка и подготовка media через CameraX
+- `ui/screens/PhotoViewerScreen.kt` / `VideoPlayerScreen.kt` — Просмотр локальных изображений и видео
+- `ui/screens/InviteLinkDialog.kt` — Выдача invite-ссылки и QR
+- `ui/screens/FirstLaunchScreen.kt` — Первичная настройка приложения
 - `ui/screens/JoinChannelDialog.kt` — Диалог подключения к каналу: ввод/вставка invite-ссылки, предпросмотр, кнопка Connect
- `ui/screens/QrScanScreen.kt` — QR-сканер для invite-ссылок (CameraX + ML Kit)
+- `ui/screens/QrScannerPreview.kt` — QR-сканер для invite-ссылок (CameraX + ML Kit)
 - `MainActivity.kt` — Точка входа Android-приложения: навигация между экранами, QrScan → JoinDialog flow

 ### Headless
@@ -1,32 +1,9 @@
-/*
- * headless_control.h — JSON control socket for uTun headless mode
- *
- * JSON line protocol:
- *   Request:  {"id":N,"cmd":"<command>",...params}
- *   Response: {"id":N,"ok":true,"data":{...}} | {"id":N,"ok":false,"error":"..."}
- *   Event:    {"event":"<type>",...}
- *
- * Commands:
- *   ping           — alive check
- *   status         — node info, uptime, connections
- *   connect        — STCP connect to peer
- *   disconnect     — STCP disconnect
- *   connections    — list active connections
- *   create_channel — create chat channel
- *   channels       — list channels
- *   send           — send message to channel
- *   messages       — get messages from channel
- *   debug_level    — get/set debug levels
- *   subscribe      — subscribe to events
- *   join           — join channel via invite link
- *   quit           — disconnect client
- *
- * Events (after subscribe):
- *   log      — {"event":"log","level":"info","cat":"ETCP","msg":"..."}
- *   msg      — {"event":"msg","ch":"id","author":"hex","ts":123}
- *   peer_online/offline
- *   channel_created/joined
- */
+/* Каркас TCP-управления Android headless: init → регулярный poll → destroy в одном потоке.
+ * ua сейчас не используется; основной рабочий API чата — src/chat/chat_headless_control.h.
+ * JSON line: {"id":N,"cmd":"..."} → {"id":N,"ok":true,"data":...} либо error.
+ * ping/status/connections/debug_level возвращают заглушки; subscribe/quit управляют клиентом.
+ * join/chat_setting обращаются к запущенному instance_lite; прочие команды дают not implemented.
+ * event/broadcast_log отправляют JSON подписанным клиентам. Этот модуль сам ядро не запускает. */
 #ifndef HEADLESS_CONTROL_H
 #define HEADLESS_CONTROL_H

@@ -2,7 +2,8 @@
 * android_jni_bridge.h — JNI bridge API (C side)
 *
 * Provides lifecycle management and callbacks between C core and Kotlin.
- * For Android, compiled via NDK into libutun_lite.so.
+ * NDK собирает bridge вместе с ядром в libutun.so. Действия передаются в uasync;
+ * callbacks логов/событий вызываются из native-потоков, UI переносит их в свой поток.
 */
 #ifndef ANDROID_JNI_BRIDGE_H
 #define ANDROID_JNI_BRIDGE_H
@@ -51,7 +52,8 @@ void utun_bridge_create_channel(const char* name, const char* channel_id);
 void utun_bridge_connect_node(const char* address, int port, const char* pubkey_hex);

 /* Join channel via invite link.
-   addr_data format: family(1) + socketId(1) + address(4|16) + port(2 BE) per addr */
+   addrs_data — результат invite_serialize_addrs: Reality-префикс и
+   family(1) + socketId(1) + proto(1) + address(4|16) + port(2 BE) для каждого адреса. */
 void utun_bridge_join_channel(uint64_t channel_id, uint64_t node_id,
                               const uint8_t* pubkey_bin,
                               const uint8_t* addrs_data, int addr_count,
@@ -1,3 +1,6 @@
+/* Android-обёртка отправки обычного файла в канал через chat_core_submit_trampoline.
+ * Строит имя назначения в db_path/media/channel_id, копирование/индексацию выполняет media_index.
+ * 0 = запрос поставлен в uasync, -1 = отказ подготовки. Исходный файл нужен до завершения media-задачи. */
 #ifndef ATTACHMENT_SENDER_H
 #define ATTACHMENT_SENDER_H

@@ -1,9 +1,7 @@
 /*
- * instance_lite.h — lightweight uTun instance lifecycle for Android
- *
- * Kotlin generates INI config text, passes to instance_lite_start().
- * C side parses it, creates uasync+ETCP+bgp+chat stack, runs in a pthread.
- * Mirrors UtunNode::runLoop() from tools/chatgui/transport/utun_node.cpp.
+ * Android-владелец одного ядра: INI из Kotlin → pthread с uasync → core_start + chat_service_start.
+ * UTUN-сервис не запускается. Поток владеет instance/ua; UI передаёт работу через uasync.
+ * Полученные handles заимствованы и могут смениться при restart; сохранять их между рестартами нельзя.
 */
 #ifndef INSTANCE_LITE_H
 #define INSTANCE_LITE_H
@@ -17,14 +15,12 @@ extern "C" {
 struct UASYNC;
 struct UTUN_INSTANCE;

-/* Start full uTun stack from INI config text.
- * Creates a pthread for uasync event loop.
- * Returns 0 on success, -1 on error.
- * Config format: same as utun INI (see node_config.cpp saveFull). */
+/* Копирует INI и запускает поток. 0 = поток создан либо уже запущен, -1 = ошибка запуска.
+ * Готовность самого ядра появляется позже: проверять is_running и события инициализации. */
 int instance_lite_start(const char* config_text);

-/* Signal stop and wait for thread to exit.
- * Calls chat_sync_destroy, chat_core_destroy, utun_instance_destroy, uasync_destroy. */
+/* Сигнализировать stop и дождаться потока; поток уничтожает instance, затем uasync.
+ * Вызывать с управляющего потока при существующем instance, не из callback ядра. */
 void instance_lite_stop(void);

 /* Returns non-zero if instance is running. */
@@ -44,9 +40,8 @@ void instance_lite_set_event_handler(instance_lite_event_fn handler);
 * Call from any thread. Keys are regenerated asynchronously. */
 void instance_lite_regenerate_keys(void);

-/* Restart the instance internally (no thread kill). Stops chat_sync/chat_core,
- * re-parses config, regenerates keys if needed, reopens DB, re-inits.
- * Posts to uasync thread — restart happens asynchronously. */
+/* Копирует INI, будит poll-loop и пересоздаёт instance и uasync внутри worker.
+ * Если ядро не работает, выполняет stop/start. Обновление асинхронное; старые handles утрачивают силу. */
 void instance_lite_restart(const char* new_config_text);

 /* Лёгкое обновление сокетов (auto_sockets=android): перечитывает [server] секции
@@ -1,3 +1,6 @@
+/* Старая отдельная копия C-кодека utun://; invite_link_c.c исключён из текущего UTUN_SOURCES.
+ * Рабочее общее API — src/chat/invite_link.h, Qt/Kotlin используют тот же формат версии 0x03.
+ * Эти структуры не следует смешивать с InviteData общего API. */
 #ifndef INVITE_LINK_C_H
 #define INVITE_LINK_C_H

@@ -48,17 +51,17 @@ struct InviteDataC {
 };

 /* decode utun://base64 link string, returns 0 on success, -1 on error.
-   error buffer must be at least 256 bytes */
+   error_buf необязателен, текст ошибки ограничивается error_buf_size. */
 int invite_link_decode(const char* link, size_t link_len, struct InviteDataC* out,
                       char* error_buf, size_t error_buf_size);

 /* encode invite data to utun://base64 string.
-   password may be NULL (v1 format, no password).
-   out buffer must be large enough (~512 bytes safe).
-   returns written length (excluding null), or -1 on error */
+   password=NULL означает пустой пароль в версии 0x03.
+   out_size включает utun://, base64 и NUL; недостаточная ёмкость даёт -1.
+   returns base64 length (excluding prefix and null), or -1 on error */
 int invite_link_encode(const struct InviteDataC* data, const char* password, char* out, size_t out_size);

-/* serialize per-addr format for chat_sync_connect_from_invite():
+/* serialize for chat_sync_connect_from_invite(): Reality-префикс + адреса:
   family(1) + socketId(1) + proto(1) + address(4|16) + port(2 BE)
   returns total bytes written, or -1 if buf too small */
 int invite_serialize_addrs(const struct InviteDataC* data, uint8_t* buf, size_t buf_size);
@@ -1,3 +1,6 @@
+/* Отправка уже подготовленного изображения в канал: MIME выбирается по расширению, width/height даёт caller.
+ * Не декодирует и не масштабирует изображение; ставит копирование/индексацию в chat_core/media_index.
+ * 0 = запрос поставлен в uasync, -1 = отказ. src_file_path должен существовать до завершения задачи. */
 #ifndef PHOTO_SENDER_H
 #define PHOTO_SENDER_H

@@ -1,9 +1,8 @@
 /*
- * utun_config_api.h — configuration provider API for Android
- *
- * C core requests config values from Kotlin via callbacks.
- * For headless, a stub provider reads from environment variables.
- * For Android, JNI bridge sets callbacks that query Kotlin DataStore.
+ * Callback-провайдер отдельных настроек native-обёртки. Без провайдера/accessor возвращает default.
+ * Основной конфиг ядра передаётся INI-текстом в instance_lite_start, а не через этот интерфейс.
+ * set_provider заимствует таблицу callbacks; она и возвращаемые строки должны жить во время вызовов.
+ * Провайдер установить до запуска потребителей: синхронизации внутри модуля нет.
 */
 #ifndef UTUN_CONFIG_API_H
 #define UTUN_CONFIG_API_H
@@ -1,3 +1,7 @@
+/* Отправка подготовленного MP4 в канал или dm:conv_id через общий attachment_send.
+ * Android передаёт duration_ms/width/height; повторного транскодирования здесь нет. db_path не используется.
+ * 0 = запрос поставлен в uasync, -1 = отказ. Передаётся владение временным cache-файлом:
+ * задача удаляет src_file_path после подготовки. Результат публикации приходит событием ядра. */
 #ifndef VIDEO_SENDER_H
 #define VIDEO_SENDER_H

@@ -1,3 +1,8 @@
+/* Android-накопитель голосового: init → start(target,48000,1) → feed PCM int16 → stop либо cancel.
+ * target — channel_id либо dm:conv_id. feed копирует count mono-сэмплов; управление защищено mutex.
+ * stop отсоединяет PCM/компрессор и ставит attachment_send в uasync: encode/file работа идёт в worker.
+ * stop=0 означает постановку подготовки либо отбрасывание записи короче 500мс, не доставку сообщения.
+ * deinit освобождает текущую запись; завершение сетевой отправки отслеживается событиями ядра. */
 #ifndef VOICE_RECORDER_H
 #define VOICE_RECORDER_H

@@ -1,3 +1,7 @@
+/* SQLite-представление данных для desktop UI: каналы/сообщения/узлы, локальные имена и диагностика БД.
+ * setDb заимствует handle ядра, destructor закрывает свои statement-курсоры, но не SQLite.
+ * Перед уничтожением БД закрыть курсоры и сбросить ссылку. Сетевые и подписанные изменения идут через chat_core;
+ * методы чтения возвращают самостоятельные Qt-значения. */
 #ifndef DB_MANAGER_H
 #define DB_MANAGER_H

@@ -120,7 +124,7 @@ public:
    QList<AccountRow> getAccounts(bool contactsOnly = false) const;
    AccountRow getAccount(quint64 nodeId) const;

-    /* ── UI state (read-only используем QSettings, оставлен для совместимости) ── */
+    /* ── Чтение UI state из SQLite ── */
    QString getUiState(const QString& key) const;
    int     getUiStateInt(const QString& key, int defaultVal) const;

@@ -1,3 +1,4 @@
+/* Отрисовка строки участника AccountList: аватар, имя, online и служебные значки. */
 #pragma once

 #include <QStyledItemDelegate>
@@ -1,3 +1,5 @@
+/* Панель участников выбранного канала и live-диагностика выбранного узла.
+ * Получает события bridge в GUI-потоке; запросы звонка и PM отдаёт через signals. */
 #pragma once

 #include <QWidget>
@@ -1,3 +1,5 @@
+/* Общий GUI-таймер анимированных emoji: регистрирует LottieIcon и выдаёт ticked.
+ * play запускает минимум PlaybackMs; shutdown останавливает таймер и очищает регистрацию. */
 #pragma once

 #include <QObject>
@@ -1,3 +1,5 @@
+/* Настройки capture/playback, Opus, компрессора, AEC и рации; тест микрофона и динамика.
+ * loadFromDb заполняет форму, applyAndSave применяет выбранные значения. */
 #pragma once
 #include <QWidget>
 #include <QComboBox>
@@ -1,3 +1,6 @@
+/* Запись голосового сообщения: capture 48 kHz mono → очередь → worker PCM/компрессора.
+ * GUI управляет init/start/stop/shutdown; meterOnly измеряет уровень без накопления записи.
+ * takeRecording передаёт остановленные PCM/компрессор в attachment_send_req для фоновой подготовки. */
 #pragma once

 #include <QObject>
@@ -1,3 +1,4 @@
+/* Роли модели и отрисовка ChannelList: канал/PM, последнее сообщение, unread и кнопки действий. */
 #pragma once

 #include <QStyledItemDelegate>
@@ -1,3 +1,5 @@
+/* Список каналов и PM с unread/online; загружает данные DbManager и принимает обновления bridge.
+ * Выбор и действия пользователя передаёт наружу signals; виджет используется в GUI-потоке. */
 #pragma once

 #include <QWidget>
@@ -1,3 +1,4 @@
+/* Локальные настройки выбранного канала: autoplay голосовых, звук сообщений и режим PTT. */
 #pragma once

 #include <QDialog>
@@ -1,3 +1,5 @@
+/* Вид истории сообщений: фон, выделение строк/текста, копирование и прокрутка вниз.
+ * MessageDelegate рисует содержимое; ChatView обрабатывает мышь и клавиатуру. */
 #pragma once

 #include <QListView>
@@ -1,3 +1,4 @@
+/* Диалог ввода имени нового канала. groupName возвращает имя для создания канала вызывающим кодом. */
 #pragma once

 #include <QDialog>
@@ -1,3 +1,4 @@
+/* Макросы логирования GUI через общий debug_config, категория GENERAL. */
 #pragma once

 extern "C" {
@@ -1,3 +1,5 @@
+/* Каталог Unicode/анимированных emoji и соответствие Unicode → ресурс анимации.
+ * detectEmojiOnly возвращает 1..3 для текста только из emoji/пробелов; иначе 0. */
 #pragma once

 #include <QString>
@@ -1,3 +1,4 @@
+/* Панель выбора emoji по категориям; выбранный Unicode передаётся в composer через emojiSelected. */
 #pragma once

 #include <QWidget>
@@ -1,3 +1,4 @@
+/* Отрисовка вкладок категорий EmojiPanel с собственным стилем выбранной вкладки. */
 #pragma once

 #include <QTabBar>
@@ -1,3 +1,4 @@
+/* Отрисовка флагов участника (supernode/admin/moder/deleted) и отдельного значка storage. */
 #ifndef FLAGPAINTER_H
 #define FLAGPAINTER_H

@@ -1,3 +1,5 @@
+/* Окно просмотра локального изображения: масштаб колесом, перенос мышью и fullscreen.
+ * loadFile загружает изображение; closed сообщает владельцу о закрытии окна. */
 #pragma once

 #include <QWidget>
@@ -1,3 +1,6 @@
+/* Composer канала/PM: текст, emoji, запись голосового и выбор вложений.
+ * Контекст target фиксируется в запросе вложения; подготовку и отправку выполняет ядро.
+ * Переданный submitAttachment request должен принять и освободить обработчик сигнала. */
 #pragma once

 #include <QWidget>
@@ -1,3 +1,5 @@
+/* Qt-кодек utun://: channelId/joinKey, пароль, Reality и адреса connection-узла.
+ * decodeInviteLink возвращает ошибку в InviteData.error; подключения выполняет UtunNode/chat_sync. */
 #pragma once

 #include <QString>
@@ -1,3 +1,4 @@
+/* Диалог приглашения узла по его utun:// ссылке в текущий канал; ждёт результата ядра через bridge. */
 #pragma once

 #include <QDialog>
@@ -1,3 +1,5 @@
+/* Диалог выдачи invite-ссылки и QR: запрашивает кандидатов и зарегистрированную ссылку у ядра.
+ * requestId связывает асинхронный ответ с текущим запросом; URL отображается после LINK_READY. */
 #pragma once

 #include <QDialog>
@@ -1,3 +1,5 @@
+/* Диалог входа в канал по utun://: проверяет ссылку, отправляет запрос ядру и ждёт CONNECT_RESULT.
+ * joined сообщает об успешном входе, а не только о создании транспорта к connection-узлу. */
 #pragma once

 #include <QDialog>
@@ -1,3 +1,5 @@
+/* Обёртка rlottie для TGS: распаковывает анимацию, хранит текущий кадр и рисует QImage.
+ * Воспроизведение координирует AnimTimer; объект освобождает свой animation handle. */
 #pragma once

 #include <QImage>
@@ -1,3 +1,5 @@
+/* Главное окно desktop-чата: связывает списки, bridge-события, UtunNode, media и звонки.
+ * Координирует запуск/остановку ядра, tray и отдельные окна; UI-обработчики работают в GUI-потоке. */
 #pragma once

 #include <QMainWindow>
@@ -1,3 +1,6 @@
+/* Локальное чтение медиа из целого файла или набора блоков по localAttrs.
+ * readRange/readAll читают доступные данные; assembleAndCleanup собирает файл и удаляет фрагменты.
+ * media_split_to_blocks по умолчанию удаляет исходник после разбиения; сетевую загрузку модуль не выполняет. */
 #pragma once

 #include <QString>
@@ -1,3 +1,5 @@
+/* Qt-модель участников канала: ленивый кэш строк, обновления CHAT_EVT_MEMBER_* и RTT.
+ * События bridge применяются в GUI-потоке; данные строки доступны через Qt roles. */
 #ifndef MEMBERLISTMODEL_H
 #define MEMBERLISTMODEL_H

@@ -1,3 +1,4 @@
+/* Диалог имени и прав участника канала; сохранение подписанных изменений и передача admin-ключа через ядро. */
 #pragma once

 #include <QDialog>
@@ -1,3 +1,5 @@
+/* Роли модели сообщений и отрисовка text/voice/file/image/video, статусов и progress.
+ * Рассчитывает геометрию для ChatView и обрабатывает действия по media-элементам строки. */
 #pragma once
 #include <cstdint>

@@ -1,3 +1,5 @@
+/* История и composer выбранного канала/PM: модель сообщений, позиция чтения, загрузки и воспроизведение.
+ * Применяет события bridge в GUI-потоке; сетевые операции передаёт ядру. */
 #pragma once

 #include <QWidget>
@@ -1,3 +1,4 @@
+/* Генерация QR и распознавание штрихкодов из QImage через ZXingQt. Ошибка генерации — пустой QImage. */
 #pragma once

 #include <QImage>
@@ -1,3 +1,4 @@
+/* Локальное переименование участника: сохраняет local_nick в таблице peers канала для этого UI. */
 #pragma once

 #include <QDialog>
@@ -1,3 +1,6 @@
+/* Общий miniaudio-контекст и выход desktop-приложения: звуки событий, PCM и голосовые потоки.
+ * GUI управляет устройствами и playback-сессиями; output смешивает звук и отдаёт reference для AEC.
+ * init/shutdown ограничивают время жизни контекста; зависимые capture devices закрываются перед его сбросом. */
 #pragma once

 #include <QObject>
@@ -1,3 +1,4 @@
+/* Форма звуков уведомлений: общий enable/volume и индивидуальные настройки событий SoundManager. */
 #pragma once

 #include <QWidget>
@@ -1,3 +1,5 @@
+/* Настройки media-хранилища: автозагрузка, лимит файла и общий размер.
+ * applyAndSave сохраняет значения и передаёт их chat_setting через uasync. */
 #pragma once

 #include <QWidget>
@@ -1,3 +1,5 @@
+/* GUI-настройка preset голосовых (0 Low, 1 Standard, 2 High) и создание media-каталога.
+ * Кодирование PCM в Opus выполняет общий voice_file через attachment_send. */
 #pragma once

 #include <QString>
@@ -1,3 +1,7 @@
+/* Воспроизведение собственного Opus-файла voice_file: worker декодирует PCM, SoundManager проигрывает.
+ * Управление — в GUI-потоке; ready(duration,id) вызывается там же, 0 означает ошибку/busy.
+ * cancelPending подавляет результат, не останавливая worker; уничтожение context также подавляет callback.
+ * decodeOpusFile синхронно возвращает число кадров или -1; это отдельный API для worker. */
 #pragma once

 #include <QString>
@@ -1,3 +1,7 @@
+/* Мост desktop GUI ↔ ядро: post копирует бинарное событие в Qt-очередь, callbacks работают в GUI.
+ * post_uasync_fn передаёт функцию и arg без копирования в сетевой поток; arg освобождает обработчик.
+ * Регистрация callbacks и UI-состояние принадлежат GUI. Полученный inst заимствован;
+ * чтение указателя не гарантирует время жизни объекта при stop/finalize. */
 #ifndef GUI_BRIDGE_H
 #define GUI_BRIDGE_H

@@ -71,13 +75,14 @@ void gui_bridge_set_uasync(struct UASYNC* ua);
   Читается GUI-потоком через gui_bridge_get_inst() для сборки trampoline-аргументов. */
 void gui_bridge_set_inst(struct UTUN_INSTANCE* inst);

-/* Текущий UTUN_INSTANCE (NULL пока не создан). Безопасно из любого потока. */
+/* Текущий заимствованный UTUN_INSTANCE (NULL пока не создан/после сброса моста). */
 struct UTUN_INSTANCE* gui_bridge_get_inst(void);

 /* uasync → GUI: уведомление (fire-and-forget, через Qt::QueuedConnection) */
 void gui_bridge_post(int event_type, const uint8_t* data, int data_len);

-/* GUI → uasync: выполнить функцию в uasync-потоке */
+/* GUI → uasync: передать fn(arg). Проверить готовность заранее: без ua запрос отбрасывается,
+ * функция не вызывается и arg не освобождается мостом. */
 void gui_bridge_post_uasync_fn(void (*fn)(void*), void* arg);

 /* Проверить готовность uasync (g_ua != NULL) */
@@ -1,4 +1,6 @@
-// node_config.h — Simplified INI config manager for embedded uTun node
+/* Desktop INI-конфиг узла: идентичность, listen/client-секции, control и GUI-настройки.
+ * load читает и проверяет значения; create генерирует конфиг/ключи; save обновляет известные поля
+ * существующего файла, saveFull перезаписывает файл из модели. Запуск ядра выполняет UtunNode. */
 #ifndef NODE_CONFIG_H
 #define NODE_CONFIG_H

@@ -1,4 +1,8 @@
-// utun_node.h — C++ wrapper for embedded uTun node (runs in dedicated thread)
+/* Desktop-владелец встроенного ядра: читает INI, создаёт uasync и запускает core/chat в std::thread.
+ * requestStop сигнализирует завершение, stop ждёт поток; worker уничтожает instance,
+ * finalize после завершения worker освобождает uasync и сбрасывает ссылку GUI-моста.
+ * instance возвращает заимствованный указатель: операции ядра отправлять в uasync через gui_bridge,
+ * согласовав время жизни с остановкой/перезапуском узла. */
 #ifndef UTUN_NODE_H
 #define UTUN_NODE_H