book-reader/AGENTS.md

Book Reader — Episteme fork + bookshelf-api/ABS

Форк Aryan-Raj3112/episteme под bookshelf-api + Audiobookshelf + Material You 3 (Myne-style UI).

Stack

• Язык: Kotlin 100%
• UI: Jetpack Compose + Material3 (Myne-style: round cards, dynamic color, minimal)
• DI: Dagger Hilt
• БД: Room
• Настройки: DataStore
• Сеть: Retrofit + OkHttp + Kotlinx Serialization
• Аудио: ExoPlayer (Media3) + MediaSession
• Фоновые задачи: WorkManager
• Читалка: Episteme paginatedreader (CSS-движок, ContentBlock/Page модель)
• Форматы: EPUB, FB2, PDF, MOBI/AZW3, DOCX, ODT, TXT, Markdown, HTML, comics
• minSdk: 26 (Episteme default)
• compileSdk/targetSdk: 36

Origin

• upstream: https://github.com/Aryan-Raj3112/episteme.git (AGPL-3.0)
• origin: https://git.dueattendant149.org/Atte149/book-reader.git (Forgejo)
• Лицензия: AGPL-3.0 (наследуется от Episteme)

Goal

• Взять зрелый reader engine из Episteme (пагинация, все форматы, TTS, annotations)
• Redesign UI под Myne-стиль (Material You 3, round cards, dynamic color)
• Заменить backend (OPDS/Gutenberg/LocalFolder) на bookshelf-api + ABS
• Добавить фичи из Book's Story: audio player, RSVP, Librarr search, TTS jobs, cache, progress sync, upload

Layout

• app/src/main/ — Android app (после KMP→Android упрощения)
• app/src/oss/ — OSS flavor (без проприетарных ML Kit/cloud)
• app/src/releaseOffline/ — offline-only flavor
• desktopApp/ — удалён (Android-only)
• shared/ — слит в app/src/main/ (после Этапа 1)

Backend

• bookshelf-api: https://books.dueattendant149.org/api/v1/*
  • GET /api/v1/books/libraries
  • GET /api/v1/books/{item_id}
  • GET /api/v1/books/library/{id}/items
  • POST /api/v1/search
  • POST /api/v1/tts, GET /api/v1/tts/{job_id}
  • POST /api/v1/download, GET /api/v1/download/list
• Audiobookshelf (напрямую):
  • GET /api/items/{id}/file/{ino}
  • GET /api/items/{id}/cover
  • GET /api/items/{id}/download

WARNs

• Не пушить в upstream (Aryan-Raj3112/episteme). Только в origin (Forgejo).
• AGPL-3.0 — если публикуем, исходный код должен быть открыт (включая server-side modifications если есть network use).
• pro flavor содержит проприетарные компоненты (ML Kit OCR, cloud sync) — не использовать, только oss.
• Секреты (ABS token, API keys) — только в .env / DataStore, никогда в коде.

Build

# Required env on this server (proxy + Android SDK)
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
export ANDROID_HOME=/home/dueattendant149/android-sdk
export ANDROID_SDK_ROOT=/home/dueattendant149/android-sdk
./gradlew :app:assembleOssDebug

Known build workarounds (Phase 1 baseline):

• Gradle wrapper pinned to 8.13 (8.11.1 unavailable behind proxy; 9.5.1 incompatible with AGP 8.9).
• externalNativeBuild temporarily disabled because NDK 27.0.12077973 is requested but only NDK 28.2.x is installed.
• Network proxy is configured in gradle.properties (systemProp.http[s].proxyHost/Port).

Status

• Phase 0: clone + package rename — completed
• Phase 1: KMP → Android-only — completed
• Phase 2: backend swap (bookshelf-api + ABS) — completed
  • Phase 2.1: bookshelf-api + ABS API services/models, Hilt DI, Retrofit/OkHttp
  • Phase 2.2: BookshelfViewModel + BookshelfLibraryScreen + nav entry
  • Phase 2.3: ServerSettingsScreen (URL/token config)
  • Phase 2.4: download/open ebook from server in reader
  • Phase 2.5: removed OPDS/Gutenberg/LocalFolder/CloudSync code + stubs
• Phase 3: UI redesign (Myne-style) — completed
  • Material You 3 shape scheme (round cards 8-32dp)
  • Dynamic color (Android 12+ dynamicColorScheme + materialkolor seed)
  • BookshelfLibraryScreen + ServerSettingsScreen redesigned with round cards, CenterAlignedTopAppBar
• Phase 4: features from Book's Story (audio/RSVP/search/TTS/cache) — pending
• Phase 5: reader engine integration — pending
• Phase 6: build, test, deploy — pending