# Aletheia production roadmap

Дата аудита: 2026-06-06.

## Проверенный внешний baseline

- Google Play для ЛитРес указывает онлайн/офлайн чтение и прослушивание, синхронизацию между устройствами и каталог на 800 000+ книг: https://play.google.com/store/apps/details?id=ru.litres.android&hl=ru
- Справка Яндекс Книг указывает синхронизацию библиотеки, закладок и прогресса чтения при использовании одного аккаунта: https://yandex.ru/support/books/ru/books-account/account
- App Store для Яндекс Книг указывает офлайн-чтение, переключение текст/аудио с сохранением позиции, настройки ридера, заметки, цитаты и рекомендации: https://apps.apple.com/ru/app/%D1%8F%D0%BD%D0%B4%D0%B5%D0%BA%D1%81-%D0%BA%D0%BD%D0%B8%D0%B3%D0%B8/id6443391664

## Текущий локальный baseline Aletheia

- Android Kotlin app, `versionName = "2.26"`, `versionCode = 37`.
- Локальная библиотека поддерживает EPUB и FB2, импорт с устройства, хранение обложек и прогресса.
- Онлайн-каталог подключён к QBooks.
- Обновления приложения подключены через Argus.
- Ридер использует WebView с EPUB.js/JSZip, поддерживает темы, размер шрифта, яркость, оглавление, сохранение позиции.
- В этом срезе добавлены локальные закладки с сохранением CFI/progress/page/chapter и переходом к закладке.

## P0: production readiness

- WebView hardening first pass: done. Reader shell HTML is served through `WebViewAssetLoader` appassets origin; direct WebView file/content access is disabled; Safe Browsing is enabled on Android O+.
- Cleartext hardening first pass: done. Base network config now denies cleartext by default and permits HTTP only for explicit local QBooks hosts (`localhost`, `127.0.0.1`, `10.0.2.2`, `192.168.0.185`, `*.local`); QBooks URL validation enforces the same rule before connecting.
- Repository hygiene first pass: done. `.gitignore` now excludes Android/Gradle build outputs, local machine properties, generated APK/AAB files, and `.codex-temp`; previously tracked generated artifacts were removed from the Git index.
- CI first pass: done. Gradle wrapper and GitHub Actions workflow are in place for lint, unit tests, Argus manifest smoke, debug build, and release build; local `testDebugUnitTest`, `lintDebug`, `assembleDebug`, `assembleRelease`, and `scripts/test-argus-manifest.ps1` pass.
- Import smoke tests first pass: done. JVM unit tests generate minimal EPUB/FB2 files and exercise the real file-based `BookParserService.parseAndStoreBook` path for metadata extraction and stored-file creation.
- QBooks naming normalization first pass: done. UI package/classes/layouts/navigation/settings ids now use QBooks names; books store active remote source ids as `remote_id`/`remoteId`, with database migration copying existing `calibre_id` values for compatibility.
- Backup privacy hardening first pass: done. Android Auto Backup and data extraction rules exclude the SQLite database, imported book files under `filesDir/Books`, and SharedPreferences so book text, notes, covers, file paths, and stored connection credentials are not exported by platform backup rules.
- Privacy-safe diagnostics first pass: done. The application installs a local uncaught-exception reporter, stores only sanitized technical reports under `noBackupFilesDir/diagnostics`, and exposes copy/clear controls in Settings. Reports omit exception messages, book text, file paths, URLs, credentials, and selected text.
- Settings control center first pass: done. Settings now starts with a unified status card for QBooks, Argus updates, and local diagnostics before the detailed connection, reading, update, and diagnostic controls.
- Argus publication contract alignment: done. Update checks follow `G:\Repos\Marketplace\ARGUS_PUBLICATION.md` by using the public manifest, comparing installed `versionName` to `release.version`, treating manifest `404` as no available update, verifying downloaded APK SHA-256 before install, and keeping publication SSH-only through `scripts/publish-argus-release.ps1` with uppercase SQLite GUIDs.
- Settings viewport density first pass: done. The top settings status card now uses compact status rows, and the QBooks connection form fits its URL, login, and password fields into the first settings viewport without being visually cut by bottom navigation.
- Release shrink/minify first pass: done. Release builds now run R8 minification and resource shrinking, with explicit keep rules for WebView JavaScript bridge methods and the Argus installer status receiver.
- Emulator launch smoke first pass: done on local `pixel_7_-_api_36` AVD. Debug APK installed and launched; `dumpsys window` reported `com.aletheia.app.kotlin/com.aletheia.app.ui.main.MainActivity` as focused; UIAutomator dump contained the Aletheia library screen; logcat did not contain Aletheia crash markers in the checked window.

- Очистить репозиторий от tracked build artifacts и настроить `.gitignore` так, чтобы `.gradle`, `app/build`, временные APK и compile caches не попадали в рабочие изменения.
- Убрать глобальный cleartext traffic или ограничить HTTP только явно разрешёнными локальными сценариями.
- Провести WebView hardening: минимальные permissions, запрет ненужного file/content access, изоляция book HTML от Android bridge.

## P1: reader parity

- Book search: done for EPUB/FB2 first pass. Reader menu has a book search card; EPUB search navigates by CFI; FB2 search navigates to the calculated page.
- Notes and quotes: done for local storage first pass. Reader menu can save a note at the current position, preserve selected text when WebView reports it, list notes, jump to note position, and delete notes.
- Notes and quotes export: done first pass. Reader menu can export current book notes and selected quotes to a user-chosen TXT file through Android's system document picker.
- Text selection UX: done first pass. The reader no longer uses permanent overlay tap zones over book text; quick tap/swipe navigation is handled by document and EPUB content listeners so long-press selection can reach the text layer.
- Accessibility labels first pass: done. Main shelf, QBooks catalog, reader controls, chapter/bookmark/note lists, and dynamic book/list items now expose TalkBack-oriented labels or hide decorative cover images from separate focus.
- Accessibility layout guardrail first pass: done. Tonal buttons now use 48dp minimum height, note/bookmark delete actions no longer reset MaterialButton minimum width, and CI runs a layout smoke test for dp text sizes, MaterialButton touch-target regressions, and fixed-size ImageButtons below 48dp.
- Pagination stability first pass: done. The reader now debounces viewport/safe-area/orientation relayouts, restores EPUB to the current CFI after resize/font changes, recalculates FB2 pages by current progress instead of resetting to page 1, and waits for FB2 page calculation before restoring the saved position.
- TOC and chapter transitions first pass: done. EPUB chapter matching now normalizes hrefs instead of using raw substring checks; FB2 current/search chapters are resolved from the target column offset; FB2 chapter navigation no longer builds a CSS selector from an unescaped href.
- Reader HUD first pass: done. Hidden-menu reading mode now has a bottom status rail with the current chapter, page/progress label, progress bar, and tap-to-open reading menu behavior; WebView bottom safe-area is expanded while the rail is visible so book text is not covered by the HUD.
- Reader HUD compact polish first pass: done. The runtime HUD is now narrower, lower, less visually heavy, and reserves a smaller WebView bottom inset while keeping the chapter label, page chip, progress bar, and tap-to-open menu behavior.
- Reader HUD auto-hide first pass: done. The reading status rail now appears on load, menu close, and page navigation, fades out after a short delay, and releases the WebView bottom safe-area while hidden so reading mode is quieter.
- Reader loading polish first pass: done. The WebView loading state now uses Russian user-facing copy, a softer book-like loading panel, and keeps the native HUD hidden until book content is ready.
- Reader quick actions density first pass: done. The reader settings sheet now shows all four quick actions in one row without wrapping or truncating Russian labels.
- Reader font controls polish first pass: done. Font step buttons in the reader sheet now stay on one line, use a dedicated compact style, and show the current font size as a concise value instead of a long system-like phrase.

- Закладки: done for local storage.
- Заметки и цитаты: проверить runtime-flow выделения/экспорта на устройстве и добавить форматированный экспорт, если TXT недостаточно.
- Поиск внутри книги по текущему EPUB/FB2.
- Оглавление и переходы: проверить runtime-flow EPUB/FB2 на устройстве с реальными книгами.
- Pagination: проверить runtime-flow на устройстве после смены шрифта, ориентации и размера экрана.
- Улучшить accessibility: проверить TalkBack runtime-flow on device, contrast, dynamic text scale, touch targets.

## P2: cloud/library parity

- Library search UX first pass: done. The local bookshelf now separates an empty library from an empty search result, keeps actions available, shows search result counts against total library size, and clears search through the Material text-field action or the empty-search card.
- QBooks catalog status first pass: done. The remote catalog now has a unified status card that shows loading state, active query, loaded item count, end-of-results hints, and query-specific empty-state detail without implying an unverified total server count.
- QBooks download-to-read first pass: done. After a catalog download/import succeeds, the success dialog offers a direct `Open` action that launches the downloaded local book in `ReaderActivity`, while keeping `OK` as a dismiss-only path.
- QBooks connection error polish first pass: done. The catalog now maps DNS, timeout, connection, SSL, and HTTP failures to short Russian user-facing guidance instead of exposing raw system exception text.
- Bookshelf shelf-first layout first pass: done. The library screen now places the scrollable shelf before summary cards and import/catalog actions when books are present, so the home screen reads as a bookshelf rather than a dashboard.
- Bookshelf horizontal rail first pass: done. The main shelf now uses a horizontal rail with fixed-width book cards and a continuous shelf line, so multiple books can be browsed by swiping sideways instead of appearing as a static grid.
- Bookshelf inline add action first pass: done. The shelf rail now ends with an `Add book` card that launches the same Android file picker as the primary import action, turning empty one-book shelf space into a useful, discoverable next step.
- Main chrome density first pass: done. The bottom navigation is more compact, the shelf card is shorter, and the home screen now leaves visible breathing room between primary actions and navigation chrome.
- Bookshelf rail polish second pass: done. Book cards are more cover-led and compact, the rail exposes horizontal fading, and the inline add card participates in adapter diffing as a stable shelf item.
- Main bottom navigation polish second pass: done. The app chrome now uses a lighter floating bottom navigation capsule above the system gesture area instead of a full-width dark slab, reducing visual weight on library, QBooks, and settings screens.
- Bookshelf right-edge polish first pass: done. The shelf panel now uses symmetric inner padding, removes the horizontal fade that clipped the right edge, and avoids extra trailing spacing after the last shelf card.
- Bookshelf focus cleanup first pass: done. The lower library/progress statistic cards and duplicate `Add file`/`QBooks catalog` action buttons were removed from the home screen so the page centers on the shelf itself.
- Night bookshelf redesign first pass: done. The home library now follows the approved dark bookshelf concept, uses the selected top `A` mark as the app/header icon, keeps local books on a horizontal shelf, and adds a live QBooks preview shelf below it.
- Аккаунт и синхронизация библиотеки, прогресса, закладок, заметок.
- Конфликт-резолюция между устройствами.
- Серверные статусы скачивания и офлайн-доступа.
- История чтения и восстановление после переустановки.

## P3: platform parity

- Рекомендации и подборки на базе QBooks/каталога.
- Аудиокниги: отдельный player, speed, sleep timer, background playback.
- Текст/аудио handoff с общей позицией, если у книги есть аудиоверсия.
- Комиксы/манга/PDF только после стабилизации EPUB/FB2.
