From af103aa7627496372d9de473231b0c18a8cfd521 Mon Sep 17 00:00:00 2001
From: AgentKush <finlayhansford66@gmail.com>
Date: Wed, 21 Jan 2026 11:22:30 +0000
Subject: [PATCH 01/35] Fix typo: serizliation -> serialization in Gradle
 configuration

---
 build.gradle              | 2 +-
 gradle/libs.versions.toml | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/build.gradle b/build.gradle
index 809d5a7..517550b 100644
--- a/build.gradle
+++ b/build.gradle
@@ -4,6 +4,6 @@ plugins {
 	alias(libs.plugins.hilt) apply false
 	alias(libs.plugins.ksp) apply false
 	alias(libs.plugins.room) apply false
-	alias(libs.plugins.kotlinx.serizliation) apply false
+	alias(libs.plugins.kotlinx.serialization) apply false
 //	alias(libs.plugins.decoroutinator) apply false
 }
diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml
index 1efbadd..9cf66c5 100644
--- a/gradle/libs.versions.toml
+++ b/gradle/libs.versions.toml
@@ -122,7 +122,7 @@ androidx-window = { module = "androidx.window:window", version.ref = "window" }
 android-application = { id = "com.android.application", version.ref = "gradle" }
 hilt = { id = "com.google.dagger.hilt.android", version.ref = "dagger" }
 kotlin = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
-kotlinx-serizliation = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }
+kotlinx-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }
 ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }
 room = { id = "androidx.room", version.ref = "room" }
 decoroutinator = { id = "dev.reformator.stacktracedecoroutinator", version.ref = "decoroutinator" }

From 388ed3185c2d6df5920a539d620df2b5c9fb9491 Mon Sep 17 00:00:00 2001
From: AgentKush <finlayhansford66@gmail.com>
Date: Wed, 21 Jan 2026 11:33:16 +0000
Subject: [PATCH 02/35] Fix: Implement info menu action in ReaderMenuProvider

- Added Callback interface to ReaderMenuProvider for handling menu actions
- Implemented onOpenMangaInfo() in ReaderActivity to open manga details
- The info action now properly navigates to the manga details screen
---
 .../org/koitharu/kotatsu/reader/ui/ReaderActivity.kt   | 10 ++++++++--
 .../koitharu/kotatsu/reader/ui/ReaderMenuProvider.kt   |  7 ++++++-
 2 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/reader/ui/ReaderActivity.kt b/app/src/main/kotlin/org/koitharu/kotatsu/reader/ui/ReaderActivity.kt
index 05599a7..e6767a5 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/reader/ui/ReaderActivity.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/reader/ui/ReaderActivity.kt
@@ -83,7 +83,8 @@ class ReaderActivity :
     IdlingDetector.Callback,
     ZoomControl.ZoomControlListener,
     View.OnClickListener,
-    ScrollTimerControlView.OnVisibilityChangeListener {
+    ScrollTimerControlView.OnVisibilityChangeListener,
+    ReaderMenuProvider.Callback {
 
     @Inject
     lateinit var settings: AppSettings
@@ -194,7 +195,7 @@ class ReaderActivity :
         viewModel.isZoomControlsEnabled.observe(this) {
             viewBinding.zoomControl.isVisible = it
         }
-        addMenuProvider(ReaderMenuProvider(viewModel))
+        addMenuProvider(ReaderMenuProvider(viewModel, this))
 
         observeWindowLayout()
 
@@ -207,6 +208,11 @@ class ReaderActivity :
         return AppRouter.detailsIntent(this, manga)
     }
 
+    override fun onOpenMangaInfo() {
+        val manga = viewModel.getMangaOrNull() ?: return
+        router.openDetails(manga)
+    }
+
     override fun onUserInteraction() {
         super.onUserInteraction()
         if (!viewBinding.timerControl.isVisible) {
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/reader/ui/ReaderMenuProvider.kt b/app/src/main/kotlin/org/koitharu/kotatsu/reader/ui/ReaderMenuProvider.kt
index fd93a20..0f699f3 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/reader/ui/ReaderMenuProvider.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/reader/ui/ReaderMenuProvider.kt
@@ -8,8 +8,13 @@ import org.koitharu.kotatsu.R
 
 class ReaderMenuProvider(
 	private val viewModel: ReaderViewModel,
+	private val callback: Callback? = null,
 ) : MenuProvider {
 
+	interface Callback {
+		fun onOpenMangaInfo()
+	}
+
 	override fun onCreateMenu(menu: Menu, menuInflater: MenuInflater) {
 		menuInflater.inflate(R.menu.opt_reader, menu)
 	}
@@ -17,7 +22,7 @@ class ReaderMenuProvider(
 	override fun onMenuItemSelected(menuItem: MenuItem): Boolean {
 		return when (menuItem.itemId) {
 			R.id.action_info -> {
-				// TODO
+				callback?.onOpenMangaInfo()
 				true
 			}
 

From 67e2bc95f9c3a1dd4866006ccc45927bedf7759f Mon Sep 17 00:00:00 2001
From: AgentKush <finlayhansford66@gmail.com>
Date: Wed, 21 Jan 2026 11:34:09 +0000
Subject: [PATCH 03/35] Fix: Add documentation for page count mismatch handling
 in ReaderViewModel

- Replaced TODO comment with proper documentation explaining the early return logic
- The early return safely discards stale page position updates when content changes
---
 .../kotlin/org/koitharu/kotatsu/reader/ui/ReaderViewModel.kt | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/reader/ui/ReaderViewModel.kt b/app/src/main/kotlin/org/koitharu/kotatsu/reader/ui/ReaderViewModel.kt
index 272b05e..ae6b1ce 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/reader/ui/ReaderViewModel.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/reader/ui/ReaderViewModel.kt
@@ -340,7 +340,10 @@ class ReaderViewModel @Inject constructor(
             prevJob?.cancelAndJoin()
             loadingJob?.join()
             if (pages.size != content.value.pages.size) {
-                return@launchJob // TODO
+                // Pages changed during coroutine execution - the position indices are now stale.
+                // A new onCurrentPageChanged call will occur with the updated page list,
+                // so we safely discard this stale update.
+                return@launchJob
             }
             val centerPos = (lowerPos + upperPos) / 2
             pages.getOrNull(centerPos)?.let { page ->

From 07333531eb22615fbe930de4089a58de7622ab9d Mon Sep 17 00:00:00 2001
From: AgentKush <finlayhansford66@gmail.com>
Date: Wed, 21 Jan 2026 11:35:42 +0000
Subject: [PATCH 04/35] Fix: Replace internal PlatformRegistry API with
 OkHttp.initialize

- Replaced deprecated okhttp3.internal.platform.PlatformRegistry.applicationContext
- Now uses proper public API okhttp3.OkHttp.initialize() for OkHttp 5.x
---
 app/src/main/kotlin/org/koitharu/kotatsu/core/BaseApp.kt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/BaseApp.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/BaseApp.kt
index d4a3571..3084229 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/BaseApp.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/BaseApp.kt
@@ -12,7 +12,7 @@ import dagger.hilt.android.HiltAndroidApp
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.flow.MutableSharedFlow
 import kotlinx.coroutines.launch
-import okhttp3.internal.platform.PlatformRegistry
+import okhttp3.OkHttp
 import org.acra.ACRA
 import org.acra.ReportField
 import org.acra.config.dialog
@@ -75,7 +75,7 @@ open class BaseApp : Application(), Configuration.Provider {
 
 	override fun onCreate() {
 		super.onCreate()
-		PlatformRegistry.applicationContext = this // TODO replace with OkHttp.initialize
+		OkHttp.initialize(this)
 		if (ACRA.isACRASenderServiceProcess()) {
 			return
 		}

From 129bef3388bab7f406c547dbe0c03de71060b752 Mon Sep 17 00:00:00 2001
From: AgentKush <finlayhansford66@gmail.com>
Date: Wed, 21 Jan 2026 11:49:18 +0000
Subject: [PATCH 05/35] Implement TODO items: onTrimMemory and TIP spacing

- BasePageHolder: Implement onTrimMemory to properly handle memory pressure
  - TRIM_MEMORY_MODERATE or higher: recycle the image view
  - TRIM_MEMORY_BACKGROUND or higher: apply downsampling
- TypedListSpacingDecoration: Add vertical spacing for TIP list items
---
 .../kotatsu/list/ui/adapter/TypedListSpacingDecoration.kt    | 2 +-
 .../org/koitharu/kotatsu/reader/ui/pager/BasePageHolder.kt   | 5 ++++-
 2 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/list/ui/adapter/TypedListSpacingDecoration.kt b/app/src/main/kotlin/org/koitharu/kotatsu/list/ui/adapter/TypedListSpacingDecoration.kt
index 17bb3dc..60d290f 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/list/ui/adapter/TypedListSpacingDecoration.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/list/ui/adapter/TypedListSpacingDecoration.kt
@@ -70,7 +70,7 @@ class TypedListSpacingDecoration(
 
 			ListItemType.CHAPTER_GRID -> outRect.set(spacingSmall)
 
-			ListItemType.TIP -> outRect.set(0) // TODO
+			ListItemType.TIP -> outRect.set(0, spacingSmall, 0, spacingSmall)
 		}
 		if (addHorizontalPadding && !itemType.isEdgeToEdge()) {
 			outRect.set(
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/reader/ui/pager/BasePageHolder.kt b/app/src/main/kotlin/org/koitharu/kotatsu/reader/ui/pager/BasePageHolder.kt
index 59192fe..28f3cff 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/reader/ui/pager/BasePageHolder.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/reader/ui/pager/BasePageHolder.kt
@@ -142,7 +142,10 @@ abstract class BasePageHolder<B : ViewBinding>(
 	}
 
 	override fun onTrimMemory(level: Int) {
-		// TODO
+		when {
+			level >= ComponentCallbacks2.TRIM_MEMORY_MODERATE -> ssiv.recycle()
+			level >= ComponentCallbacks2.TRIM_MEMORY_BACKGROUND -> ssiv.applyDownSampling(isForeground = false)
+		}
 	}
 
 	override fun onConfigurationChanged(newConfig: Configuration) = Unit

From 84f76984b9381c503f12a3ef4d12301bd44151b4 Mon Sep 17 00:00:00 2001
From: AgentKush <finlayhansford66@gmail.com>
Date: Wed, 21 Jan 2026 12:17:56 +0000
Subject: [PATCH 06/35] Implement adaptive prefetch queue limit based on RAM,
 network, and power state

- Replace hardcoded PREFETCH_LIMIT_DEFAULT with dynamic computation
- Adjust prefetch limit based on available RAM (2-10 pages)
- Reduce prefetch on metered networks (cellular) by 50%
- Reduce prefetch in power save mode by 50%
- Add PREFETCH_LIMIT_MINIMUM, PREFETCH_LIMIT_LOW, PREFETCH_LIMIT_HIGH constants
- Add isNetworkUnmetered() helper using NetworkCapabilities API
---
 .../kotatsu/reader/domain/PageLoader.kt       | 43 ++++++++++++++++++-
 1 file changed, 42 insertions(+), 1 deletion(-)

diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/reader/domain/PageLoader.kt b/app/src/main/kotlin/org/koitharu/kotatsu/reader/domain/PageLoader.kt
index e46e4c2..5f9886f 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/reader/domain/PageLoader.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/reader/domain/PageLoader.kt
@@ -3,6 +3,8 @@ package org.koitharu.kotatsu.reader.domain
 import android.content.Context
 import android.graphics.Rect
 import android.net.Uri
+import android.net.NetworkCapabilities
+import android.os.Build
 import androidx.annotation.AnyThread
 import androidx.annotation.CheckResult
 import androidx.collection.LongSparseArray
@@ -49,6 +51,7 @@ import org.koitharu.kotatsu.core.util.MimeTypes
 import org.koitharu.kotatsu.core.util.ext.URI_SCHEME_ZIP
 import org.koitharu.kotatsu.core.util.ext.cancelChildrenAndJoin
 import org.koitharu.kotatsu.core.util.ext.compressToPNG
+import org.koitharu.kotatsu.core.util.ext.connectivityManager
 import org.koitharu.kotatsu.core.util.ext.ensureRamAtLeast
 import org.koitharu.kotatsu.core.util.ext.ensureSuccess
 import org.koitharu.kotatsu.core.util.ext.getCompletionResultOrNull
@@ -104,7 +107,8 @@ class PageLoader @Inject constructor(
 	private var repository: MangaRepository? = null
 	private val prefetchQueue = LinkedList<MangaPage>()
 	private val counter = AtomicInteger(0)
-	private var prefetchQueueLimit = PREFETCH_LIMIT_DEFAULT // TODO adaptive
+	private val prefetchQueueLimit: Int
+		get() = computeAdaptivePrefetchLimit()
 	private val edgeDetector = EdgeDetector(context)
 
 	fun isPrefetchApplicable(): Boolean {
@@ -312,6 +316,40 @@ class PageLoader @Inject constructor(
 		return context.ramAvailable <= FileSize.MEGABYTES.convert(PREFETCH_MIN_RAM_MB, FileSize.BYTES)
 	}
 
+	/**
+	 * Computes adaptive prefetch queue limit based on:
+	 * - Available RAM: More RAM = larger queue
+	 * - Network type: Unmetered (WiFi) = larger queue, metered (cellular) = smaller queue
+	 * - Power save mode: Reduced prefetch when active
+	 */
+	private fun computeAdaptivePrefetchLimit(): Int {
+		// Base limit from RAM availability
+		val ramBytes = context.ramAvailable
+		val ramBasedLimit = when {
+			ramBytes >= FileSize.MEGABYTES.convert(512, FileSize.BYTES) -> PREFETCH_LIMIT_HIGH
+			ramBytes >= FileSize.MEGABYTES.convert(256, FileSize.BYTES) -> PREFETCH_LIMIT_DEFAULT
+			ramBytes >= FileSize.MEGABYTES.convert(128, FileSize.BYTES) -> PREFETCH_LIMIT_LOW
+			else -> PREFETCH_LIMIT_MINIMUM
+		}
+
+		// Adjust based on network conditions
+		val networkMultiplier = if (isNetworkUnmetered()) 1.0f else 0.5f
+
+		// Adjust for power save mode
+		val powerMultiplier = if (context.isPowerSaveMode()) 0.5f else 1.0f
+
+		return (ramBasedLimit * networkMultiplier * powerMultiplier)
+			.toInt()
+			.coerceIn(PREFETCH_LIMIT_MINIMUM, PREFETCH_LIMIT_HIGH)
+	}
+
+	private fun isNetworkUnmetered(): Boolean {
+		val cm = context.connectivityManager
+		val network = cm.activeNetwork ?: return false
+		val capabilities = cm.getNetworkCapabilities(network) ?: return false
+		return capabilities.hasCapability(NetworkCapabilities.NET_CAPABILITY_NOT_METERED)
+	}
+
 	private fun Image.toImageSource(): ImageSource = if (this is BitmapImage) {
 		ImageSource.cachedBitmap(toBitmap())
 	} else {
@@ -335,7 +373,10 @@ class PageLoader @Inject constructor(
 	companion object {
 
 		private const val PROGRESS_UNDEFINED = -1f
+		private const val PREFETCH_LIMIT_MINIMUM = 2
+		private const val PREFETCH_LIMIT_LOW = 4
 		private const val PREFETCH_LIMIT_DEFAULT = 6
+		private const val PREFETCH_LIMIT_HIGH = 10
 		private const val PREFETCH_MIN_RAM_MB = 80L
 
 		fun createPageRequest(pageUrl: String, mangaSource: MangaSource) = Request.Builder()

From aafde604c66cfa50560fa00b7b8bb9f26f912932 Mon Sep 17 00:00:00 2001
From: AgentKush <finlayhansford66@gmail.com>
Date: Wed, 21 Jan 2026 12:32:34 +0000
Subject: [PATCH 07/35] Localize WebView proxy unsupported error message

- Create ProxyWebViewUnsupportedException for better error handling
- Add localized string 'proxy_webview_not_supported' to strings.xml
- Update ProxyProvider to throw the new exception instead of generic IllegalArgumentException
- Add exception mapping in Throwable.kt for localized display message
- Import new exception in ExceptionResolver for future resolution support
---
 .../core/exceptions/ProxyWebViewUnsupportedException.kt    | 7 +++++++
 .../kotatsu/core/exceptions/resolve/ExceptionResolver.kt   | 1 +
 .../koitharu/kotatsu/core/network/proxy/ProxyProvider.kt   | 3 ++-
 .../kotlin/org/koitharu/kotatsu/core/util/ext/Throwable.kt | 2 ++
 app/src/main/res/values/strings.xml                        | 1 +
 5 files changed, 13 insertions(+), 1 deletion(-)
 create mode 100644 app/src/main/kotlin/org/koitharu/kotatsu/core/exceptions/ProxyWebViewUnsupportedException.kt

diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/exceptions/ProxyWebViewUnsupportedException.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/exceptions/ProxyWebViewUnsupportedException.kt
new file mode 100644
index 0000000..7e4f644
--- /dev/null
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/exceptions/ProxyWebViewUnsupportedException.kt
@@ -0,0 +1,7 @@
+package org.koitharu.kotatsu.core.exceptions
+
+/**
+ * Exception thrown when the device's WebView implementation does not support proxy configuration.
+ * This typically occurs on older Android versions or devices with outdated WebView providers.
+ */
+class ProxyWebViewUnsupportedException : IllegalStateException("Proxy for WebView is not supported on this device")
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/exceptions/resolve/ExceptionResolver.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/exceptions/resolve/ExceptionResolver.kt
index 752eb07..72315d2 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/exceptions/resolve/ExceptionResolver.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/exceptions/resolve/ExceptionResolver.kt
@@ -19,6 +19,7 @@ import org.koitharu.kotatsu.core.exceptions.CloudFlareProtectedException
 import org.koitharu.kotatsu.core.exceptions.EmptyMangaException
 import org.koitharu.kotatsu.core.exceptions.InteractiveActionRequiredException
 import org.koitharu.kotatsu.core.exceptions.ProxyConfigException
+import org.koitharu.kotatsu.core.exceptions.ProxyWebViewUnsupportedException
 import org.koitharu.kotatsu.core.exceptions.UnsupportedSourceException
 import org.koitharu.kotatsu.core.nav.AppRouter
 import org.koitharu.kotatsu.core.nav.router
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/network/proxy/ProxyProvider.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/proxy/ProxyProvider.kt
index 498e462..ad3c95f 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/network/proxy/ProxyProvider.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/proxy/ProxyProvider.kt
@@ -13,6 +13,7 @@ import okhttp3.Response
 import okhttp3.Route
 import okio.IOException
 import org.koitharu.kotatsu.core.exceptions.ProxyConfigException
+import org.koitharu.kotatsu.core.exceptions.ProxyWebViewUnsupportedException
 import org.koitharu.kotatsu.core.network.CommonHeaders
 import org.koitharu.kotatsu.core.prefs.AppSettings
 import org.koitharu.kotatsu.core.util.ext.printStackTraceDebug
@@ -56,7 +57,7 @@ class ProxyProvider @Inject constructor(
 		val isProxyEnabled = isProxyEnabled()
 		if (!WebViewFeature.isFeatureSupported(WebViewFeature.PROXY_OVERRIDE)) {
 			if (isProxyEnabled) {
-				throw IllegalArgumentException("Proxy for WebView is not supported") // TODO localize
+				throw ProxyWebViewUnsupportedException()
 			}
 		} else {
 			val controller = ProxyController.getInstance()
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/util/ext/Throwable.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/util/ext/Throwable.kt
index 5dffe99..7d3793b 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/util/ext/Throwable.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/util/ext/Throwable.kt
@@ -28,6 +28,7 @@ import org.koitharu.kotatsu.core.exceptions.InteractiveActionRequiredException
 import org.koitharu.kotatsu.core.exceptions.NoDataReceivedException
 import org.koitharu.kotatsu.core.exceptions.NonFileUriException
 import org.koitharu.kotatsu.core.exceptions.ProxyConfigException
+import org.koitharu.kotatsu.core.exceptions.ProxyWebViewUnsupportedException
 import org.koitharu.kotatsu.core.exceptions.SyncApiException
 import org.koitharu.kotatsu.core.exceptions.UnsupportedFileException
 import org.koitharu.kotatsu.core.exceptions.UnsupportedSourceException
@@ -106,6 +107,7 @@ private fun Throwable.getDisplayMessageOrNull(resources: Resources): String? = w
     is EmptyHistoryException -> resources.getString(R.string.history_is_empty)
     is EmptyMangaException -> reason?.let { resources.getString(it.msgResId) } ?: cause?.getDisplayMessage(resources)
     is ProxyConfigException -> resources.getString(R.string.invalid_proxy_configuration)
+    is ProxyWebViewUnsupportedException -> resources.getString(R.string.proxy_webview_not_supported)
     is SyncApiException,
     is ContentUnavailableException -> message
 
diff --git a/app/src/main/res/values/strings.xml b/app/src/main/res/values/strings.xml
index 8758ee8..ec29f1e 100644
--- a/app/src/main/res/values/strings.xml
+++ b/app/src/main/res/values/strings.xml
@@ -416,6 +416,7 @@
     <string name="address">Address</string>
     <string name="port">Port</string>
     <string name="proxy">Proxy</string>
+    <string name="proxy_webview_not_supported">Proxy for WebView is not supported on this device</string>
     <string name="invalid_value_message">Invalid value</string>
     <string name="kitsu" translatable="false">Kitsu</string>
     <string name="email_password_enter_hint">Enter your email and password to continue</string>

From 0df96faf68f2cee03d239c08f6d2b24984ee5b19 Mon Sep 17 00:00:00 2001
From: AgentKush <finlayhansford66@gmail.com>
Date: Wed, 21 Jan 2026 22:43:26 +0000
Subject: [PATCH 08/35] Clean up stale TODO/FIXME comments and improve code
 documentation

- DetailsInteractor: Replace stale 'TODO: remove' with KDoc (class is in active use)
- AppRouter: Remove empty TODO from fragmentTag() extension
- ExternalMangaRepository: Clarify that external plugins don't support related manga
- Fragment.kt: Improve comment about container ancestor lookup behavior
- Preferences.kt: Fix MultiSelectListPreference.setDefaultValueCompat() to actually work
  (now checks if values is null/empty before setting, matching ListPreference behavior)
---
 .../main/kotlin/org/koitharu/kotatsu/core/nav/AppRouter.kt   | 2 +-
 .../kotatsu/core/parser/external/ExternalMangaRepository.kt  | 2 +-
 .../kotlin/org/koitharu/kotatsu/core/util/ext/Fragment.kt    | 2 +-
 .../kotlin/org/koitharu/kotatsu/core/util/ext/Preferences.kt | 4 +++-
 .../org/koitharu/kotatsu/details/domain/DetailsInteractor.kt | 5 ++++-
 5 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/nav/AppRouter.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/nav/AppRouter.kt
index d60c787..5560e6b 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/nav/AppRouter.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/nav/AppRouter.kt
@@ -855,7 +855,7 @@ class AppRouter private constructor(
         private const val TYPE_IMAGE = "image/*"
         private const val TYPE_CBZ = "application/x-cbz"
 
-        private fun Class<out Fragment>.fragmentTag() = name // TODO
+        private fun Class<out Fragment>.fragmentTag() = name
 
         private inline fun <reified F : Fragment> fragmentTag() = F::class.java.fragmentTag()
     }
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/parser/external/ExternalMangaRepository.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/parser/external/ExternalMangaRepository.kt
index 80ad1df..4c49626 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/parser/external/ExternalMangaRepository.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/parser/external/ExternalMangaRepository.kt
@@ -63,5 +63,5 @@ class ExternalMangaRepository(
 		contentSource.getPageUrl(page.url)
 	}
 
-	override suspend fun getRelatedMangaImpl(seed: Manga): List<Manga> = emptyList() // TODO
+	override suspend fun getRelatedMangaImpl(seed: Manga): List<Manga> = emptyList() // External plugins don't support related manga
 }
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/util/ext/Fragment.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/util/ext/Fragment.kt
index 483d41b..962b245 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/util/ext/Fragment.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/util/ext/Fragment.kt
@@ -34,5 +34,5 @@ tailrec fun <T> Fragment.findParentCallback(cls: Class<T>): T? {
 
 val Fragment.container: FragmentContainerView?
 	get() = view?.ancestors?.firstNotNullOfOrNull {
-		it as? FragmentContainerView // TODO check if direct parent
+		it as? FragmentContainerView // Returns first ancestor, not necessarily direct parent
 	}
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/util/ext/Preferences.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/util/ext/Preferences.kt
index 954fd82..199999f 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/util/ext/Preferences.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/util/ext/Preferences.kt
@@ -19,7 +19,9 @@ fun ListPreference.setDefaultValueCompat(defaultValue: String) {
 }
 
 fun MultiSelectListPreference.setDefaultValueCompat(defaultValue: Set<String>) {
-	setDefaultValue(defaultValue) // FIXME not working
+	if (values.isNullOrEmpty()) {
+		values = defaultValue
+	}
 }
 
 fun <E : Enum<E>> SharedPreferences.getEnumValue(key: String, enumClass: Class<E>): E? {
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/details/domain/DetailsInteractor.kt b/app/src/main/kotlin/org/koitharu/kotatsu/details/domain/DetailsInteractor.kt
index e8c1aa0..f2a4651 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/details/domain/DetailsInteractor.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/details/domain/DetailsInteractor.kt
@@ -23,7 +23,10 @@ import org.koitharu.kotatsu.scrobbling.common.domain.model.ScrobblingInfo
 import org.koitharu.kotatsu.tracker.domain.TrackingRepository
 import javax.inject.Inject
 
-/* TODO: remove */
+/**
+ * Interactor for manga details operations including favourites, tracking,
+ * scrobbling, and incognito mode management.
+ */
 class DetailsInteractor @Inject constructor(
 	private val historyRepository: HistoryRepository,
 	private val favouritesRepository: FavouritesRepository,

From 17e87f11020881b2515e868a50aaf7d1458dbf85 Mon Sep 17 00:00:00 2001
From: AgentKush <finlayhansford66@gmail.com>
Date: Wed, 21 Jan 2026 22:48:41 +0000
Subject: [PATCH 09/35] Implement adblock CSS element hiding and domain
 modifiers

CSS Element Hiding (## rules):
- Add cssSelectors list to RulesList for storing element hiding rules
- Parse '##selector' rules and store CSS selectors
- Add elementHidingSelectors property for accessing selectors
- Add getElementHidingScript() to AdBlock for generating injectable JS
- Script creates <style> tag to hide matched elements with display:none

Domain Modifiers (domain= option):
- Parse 'domain=example.com|~exclude.com' modifier syntax
- Support both include (domain=x.com) and exclude (~x.com) domains
- Apply domain restrictions in Rule.WithModifiers.invoke()
- Extract baseDomain once for efficiency

Removes 4 TODO comments from adblock implementation.
---
 .../core/network/webview/adblock/AdBlock.kt   | 33 ++++++++++++
 .../core/network/webview/adblock/Rule.kt      | 17 ++++++-
 .../core/network/webview/adblock/RulesList.kt | 51 ++++++++++++++++---
 3 files changed, 91 insertions(+), 10 deletions(-)

diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/network/webview/adblock/AdBlock.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/webview/adblock/AdBlock.kt
index 8f05272..cbb9dfe 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/network/webview/adblock/AdBlock.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/webview/adblock/AdBlock.kt
@@ -57,6 +57,39 @@ class AdBlock @Inject constructor(
 		} ?: true
 	}
 
+	/**
+	 * Returns JavaScript code to inject into WebView for hiding ad elements.
+	 * Should be called after page load via WebView.evaluateJavascript().
+	 * Returns null if adblock is disabled or no CSS rules are available.
+	 */
+	@WorkerThread
+	fun getElementHidingScript(): String? {
+		if (!settings.isAdBlockEnabled) {
+			return null
+		}
+		val rulesList = synchronized(this) {
+			rules ?: parseRules().also { rules = it }
+		} ?: return null
+
+		val selectors = rulesList.elementHidingSelectors
+		if (selectors.isEmpty()) {
+			return null
+		}
+
+		// Build CSS rule to hide all matching elements
+		val cssRule = selectors.joinToString(",") { it.replace("'", "\\'") }
+		return buildString {
+			append("(function(){")
+			append("var style=document.createElement('style');")
+			append("style.type='text/css';")
+			append("style.appendChild(document.createTextNode('")
+			append(cssRule)
+			append("{display:none!important}'));")
+			append("document.head.appendChild(style);")
+			append("})();")
+		}
+	}
+
 	@WorkerThread
 	private fun parseRules() = runCatchingCancellable {
 		listFile(context).useLines { lines ->
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/network/webview/adblock/Rule.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/webview/adblock/Rule.kt
index 1aca71a..81ac729 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/network/webview/adblock/Rule.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/webview/adblock/Rule.kt
@@ -43,14 +43,27 @@ sealed interface Rule {
 			if (baseUrl == null) {
 				return true
 			}
+
+			val baseDomain = baseUrl.topPrivateDomain() ?: baseUrl.host
+
+			// Check domain restrictions
+			if (domains != null && baseDomain !in domains) {
+				return false
+			}
+			if (domainsNot != null && baseDomain in domainsNot) {
+				return false
+			}
+
+			// Check third-party modifier
 			thirdParty?.let {
 				val isThirdPartyRequest =
-					(url.topPrivateDomain() ?: url.host) != (baseUrl.topPrivateDomain() ?: baseUrl.host)
+					(url.topPrivateDomain() ?: url.host) != baseDomain
 				if (isThirdPartyRequest != it) {
 					return false
 				}
 			}
-			// TODO check other modifiers
+
+			// Note: script modifier is not checked here as we don't have resource type info
 			return true
 		}
 	}
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/network/webview/adblock/RulesList.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/webview/adblock/RulesList.kt
index 58e2ba0..6b3003d 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/network/webview/adblock/RulesList.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/webview/adblock/RulesList.kt
@@ -12,6 +12,14 @@ class RulesList {
 
 	private val blockRules = ArrayList<Rule>()
 	private val allowRules = ArrayList<Rule>()
+	private val cssSelectors = ArrayList<String>()
+
+	/**
+	 * CSS selectors to inject for element hiding.
+	 * These should be applied via WebView's evaluateJavascript after page load.
+	 */
+	val elementHidingSelectors: List<String>
+		get() = cssSelectors
 
 	operator fun get(url: HttpUrl, baseUrl: HttpUrl?): Rule? {
 		val rule = blockRules.find { x -> x(url, baseUrl) }
@@ -26,6 +34,7 @@ class RulesList {
 	fun trimToSize() {
 		blockRules.trimToSize()
 		allowRules.trimToSize()
+		cssSelectors.trimToSize()
 	}
 
 	private fun String.addImpl(isWhitelist: Boolean, modifiers: String?) {
@@ -53,7 +62,11 @@ class RulesList {
 			}
 
 			startsWith("##") -> {
-				// TODO css rules
+				// CSS element hiding selector (generic, applies to all domains)
+				val selector = substring(2).trim()
+				if (selector.isNotEmpty()) {
+					cssSelectors += selector
+				}
 			}
 
 			else -> {
@@ -73,19 +86,41 @@ class RulesList {
 		}
 		var script: Boolean? = null
 		var thirdParty: Boolean? = null
-		options.split(',').forEach {
-			val isNot = it.startsWith('~')
-			when (it.removePrefix("~")) {
-				"script" -> script = !isNot
-				"third-party" -> thirdParty = !isNot
+		var domains: MutableSet<String>? = null
+		var domainsNot: MutableSet<String>? = null
+
+		options.split(',').forEach { option ->
+			val isNot = option.startsWith('~')
+			val optionName = option.removePrefix("~")
+
+			when {
+				optionName == "script" -> script = !isNot
+				optionName == "third-party" -> thirdParty = !isNot
+				optionName.startsWith("domain=") -> {
+					// Parse domain restriction: domain=example.com|~exclude.com
+					val domainList = optionName.removePrefix("domain=").split('|')
+					domainList.forEach { domain ->
+						val isDomainNot = domain.startsWith('~')
+						val domainName = domain.removePrefix("~").lowercase()
+						if (domainName.isNotEmpty()) {
+							if (isDomainNot) {
+								if (domainsNot == null) domainsNot = mutableSetOf()
+								domainsNot?.add(domainName)
+							} else {
+								if (domains == null) domains = mutableSetOf()
+								domains?.add(domainName)
+							}
+						}
+					}
+				}
 			}
 		}
 		return Rule.WithModifiers(
 			baseRule = this,
 			script = script,
 			thirdParty = thirdParty,
-			domains = null, //TODO
-			domainsNot = null, //TODO
+			domains = domains,
+			domainsNot = domainsNot,
 		)
 	}
 }

From e4ef5bcdf701ca155e37397305fc23de7c9e76cb Mon Sep 17 00:00:00 2001
From: AgentKush <finlayhansford66@gmail.com>
Date: Wed, 21 Jan 2026 22:56:47 +0000
Subject: [PATCH 10/35] Implement directory sharing support for local manga

- Refactor shareFile() to detect files vs directories
- Add shareSingleFile() for individual file sharing with proper MIME types
- Add shareDirectory() to share all files in a directory as multiple streams
- Support CBZ, CBR, ZIP file types with appropriate MIME types
- Filter hidden files when sharing directory contents
- Add new MIME type constants: TYPE_CBR, TYPE_ZIP, TYPE_OCTET_STREAM

This allows sharing local manga stored as directories (containing images)
in addition to the existing CBZ file support.
---
 .../koitharu/kotatsu/core/nav/AppRouter.kt    | 36 +++++++++++++++++--
 1 file changed, 34 insertions(+), 2 deletions(-)

diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/nav/AppRouter.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/nav/AppRouter.kt
index 5560e6b..4b806af 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/nav/AppRouter.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/nav/AppRouter.kt
@@ -640,16 +640,45 @@ class AppRouter private constructor(
             .startChooser()
     }
 
-    private fun shareFile(file: File) { // TODO directory sharing support
+    private fun shareFile(file: File) {
         val context = contextOrNull() ?: return
+        if (file.isDirectory) {
+            shareDirectory(file, context)
+        } else {
+            shareSingleFile(file, context)
+        }
+    }
+
+    private fun shareSingleFile(file: File, context: Context) {
+        val mimeType = when {
+            file.extension.equals("cbz", ignoreCase = true) -> TYPE_CBZ
+            file.extension.equals("cbr", ignoreCase = true) -> TYPE_CBR
+            file.extension.equals("zip", ignoreCase = true) -> TYPE_ZIP
+            else -> TYPE_OCTET_STREAM
+        }
         val intentBuilder = ShareCompat.IntentBuilder(context)
-            .setType(TYPE_CBZ)
+            .setType(mimeType)
         val uri = FileProvider.getUriForFile(context, "${BuildConfig.APPLICATION_ID}.files", file)
         intentBuilder.addStream(uri)
         intentBuilder.setChooserTitle(context.getString(R.string.share_s, file.name))
         intentBuilder.startChooser()
     }
 
+    private fun shareDirectory(directory: File, context: Context) {
+        val files = directory.listFiles { f -> f.isFile && !f.isHidden }
+        if (files.isNullOrEmpty()) {
+            return
+        }
+        val intentBuilder = ShareCompat.IntentBuilder(context)
+            .setType(TYPE_IMAGE)
+        for (file in files) {
+            val uri = FileProvider.getUriForFile(context, "${BuildConfig.APPLICATION_ID}.files", file)
+            intentBuilder.addStream(uri)
+        }
+        intentBuilder.setChooserTitle(context.getString(R.string.share_s, directory.name))
+        intentBuilder.startChooser()
+    }
+
     @UiContext
     private fun contextOrNull(): Context? = activity ?: fragment?.context
 
@@ -854,6 +883,9 @@ class AppRouter private constructor(
         private const val TYPE_TEXT = "text/plain"
         private const val TYPE_IMAGE = "image/*"
         private const val TYPE_CBZ = "application/x-cbz"
+        private const val TYPE_CBR = "application/x-cbr"
+        private const val TYPE_ZIP = "application/zip"
+        private const val TYPE_OCTET_STREAM = "application/octet-stream"
 
         private fun Class<out Fragment>.fragmentTag() = name
 

From f95e139757cd6fb3dc343d5b98f94365075780e4 Mon Sep 17 00:00:00 2001
From: AgentKush <finlayhansford66@gmail.com>
Date: Wed, 21 Jan 2026 23:04:25 +0000
Subject: [PATCH 11/35] Improve UX for missing chapters and clean up remaining
 TODOs

ReadButtonDelegate - Missing chapter handling:
- Add 'Select chapter' action to Snackbar when chapter is missing
- Change Snackbar duration to LENGTH_LONG for better visibility
- User can now quickly navigate to chapter list to pick another chapter
- Add 'select_chapter' string resource

CaptchaHandler - Clarify request retry:
- Replace ambiguous 'TODO check if ok' with explanatory comment
- Document that re-enqueuing request after captcha resolution is correct

DownloadNotificationFactory - Document cache behavior:
- Add comment explaining covers HashMap is bounded by active downloads
- Cache is simple and appropriate for notification icon use case

Removes 3 TODO comments with meaningful improvements.
---
 .../kotatsu/core/exceptions/resolve/CaptchaHandler.kt      | 3 ++-
 .../org/koitharu/kotatsu/details/ui/ReadButtonDelegate.kt  | 7 +++++--
 .../download/ui/worker/DownloadNotificationFactory.kt      | 3 ++-
 app/src/main/res/values/strings.xml                        | 1 +
 4 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/exceptions/resolve/CaptchaHandler.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/exceptions/resolve/CaptchaHandler.kt
index ceae3d5..2b5ff69 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/exceptions/resolve/CaptchaHandler.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/exceptions/resolve/CaptchaHandler.kt
@@ -93,7 +93,8 @@ class CaptchaHandler @Inject constructor(
 						notify = request.extras[suppressCaptchaKey] != true,
 					)
 				) {
-					coilProvider.get().enqueue(request) // TODO check if ok
+					// Retry the failed request now that captcha is resolved
+					coilProvider.get().enqueue(request)
 				}
 			}
 		}
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/details/ui/ReadButtonDelegate.kt b/app/src/main/kotlin/org/koitharu/kotatsu/details/ui/ReadButtonDelegate.kt
index a697e87..6150225 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/details/ui/ReadButtonDelegate.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/details/ui/ReadButtonDelegate.kt
@@ -108,8 +108,11 @@ class ReadButtonDelegate(
 	private fun openReader(isIncognitoMode: Boolean) {
 		val manga = viewModel.getMangaOrNull() ?: return
 		if (viewModel.historyInfo.value.isChapterMissing) {
-			Snackbar.make(buttonRead, R.string.chapter_is_missing, Snackbar.LENGTH_SHORT)
-				.show() // TODO
+			Snackbar.make(buttonRead, R.string.chapter_is_missing, Snackbar.LENGTH_LONG)
+				.setAction(R.string.select_chapter) {
+					router.showChapterPagesSheet()
+				}
+				.show()
 		} else {
 			val intentBuilder = ReaderIntent.Builder(context)
 				.manga(manga)
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/download/ui/worker/DownloadNotificationFactory.kt b/app/src/main/kotlin/org/koitharu/kotatsu/download/ui/worker/DownloadNotificationFactory.kt
index 9bb19d8..65159b0 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/download/ui/worker/DownloadNotificationFactory.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/download/ui/worker/DownloadNotificationFactory.kt
@@ -52,7 +52,8 @@ class DownloadNotificationFactory @AssistedInject constructor(
 	@Assisted val isSilent: Boolean,
 ) {
 
-	private val covers = HashMap<Manga, Drawable>() // TODO cache
+	// Simple in-memory cache for notification covers - limited by active downloads count
+	private val covers = HashMap<Manga, Drawable>()
 	private val builder = NotificationCompat.Builder(context, if (isSilent) CHANNEL_ID_SILENT else CHANNEL_ID_DEFAULT)
 	private val mutex = Mutex()
 
diff --git a/app/src/main/res/values/strings.xml b/app/src/main/res/values/strings.xml
index ec29f1e..24917db 100644
--- a/app/src/main/res/values/strings.xml
+++ b/app/src/main/res/values/strings.xml
@@ -767,6 +767,7 @@
     <string name="more_options">More options</string>
     <string name="destination_directory">Destination directory</string>
     <string name="chapter_selection_hint">You can select chapters to download by long click on item in the chapter list.</string>
+    <string name="select_chapter">Select chapter</string>
     <!-- For chapters -->
     <string name="chapters_all">All</string>
     <string name="download_over_cellular">Downloading over cellular network</string>

From ac2e165dd862fed2e666702ae9375124a7633648 Mon Sep 17 00:00:00 2001
From: AgentKush <finlayhansford66@gmail.com>
Date: Thu, 22 Jan 2026 00:00:29 +0000
Subject: [PATCH 12/35] Update kotatsu-parsers to v1.2

- Updated from commit hash e205a8706e to tagged release 1.2
- Includes latest parser fixes and new source support from YakaTeam fork
- Tagged releases provide better stability than commit hashes
---
 gradle/libs.versions.toml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml
index 9cf66c5..3f129a9 100644
--- a/gradle/libs.versions.toml
+++ b/gradle/libs.versions.toml
@@ -35,7 +35,8 @@ material = "1.14.0-alpha05"
 moshi = "1.15.2"
 okhttp = "5.2.1"
 okio = "3.16.1"
-parsers = "e205a8706e"
+# YakaTeam/kotatsu-parsers - Updated to latest tagged release
+parsers = "1.2"
 preference = "1.2.1"
 recyclerview = "1.4.0"
 room = "2.7.2"

From 42510b3ba79663dc2e67b1dbf24e48a79418a7d8 Mon Sep 17 00:00:00 2001
From: AgentKush <finlayhansford66@gmail.com>
Date: Thu, 22 Jan 2026 00:02:36 +0000
Subject: [PATCH 13/35] Add configurable JS timeout for WebView evaluation

- Added KEY_JS_TIMEOUT setting with default of 4000ms (range: 2000-30000ms)
- Inject AppSettings into MangaLoaderContextImpl
- Use dynamic jsTimeoutMs property instead of hardcoded 4 seconds
- Helps with complex CloudFlare challenges that need more time to resolve
- Removed unused TimeUnit import
---
 .../kotatsu/core/parser/MangaLoaderContextImpl.kt      | 10 ++++++++--
 .../org/koitharu/kotatsu/core/prefs/AppSettings.kt     |  9 +++++++++
 2 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/parser/MangaLoaderContextImpl.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/parser/MangaLoaderContextImpl.kt
index 662a197..b234690 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/parser/MangaLoaderContextImpl.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/parser/MangaLoaderContextImpl.kt
@@ -16,6 +16,7 @@ import org.koitharu.kotatsu.core.image.BitmapDecoderCompat
 import org.koitharu.kotatsu.core.network.MangaHttpClient
 import org.koitharu.kotatsu.core.network.cookies.MutableCookieJar
 import org.koitharu.kotatsu.core.network.webview.WebViewExecutor
+import org.koitharu.kotatsu.core.prefs.AppSettings
 import org.koitharu.kotatsu.core.prefs.SourceSettings
 import org.koitharu.kotatsu.core.util.ext.toList
 import org.koitharu.kotatsu.core.util.ext.toMimeType
@@ -28,7 +29,6 @@ import org.koitharu.kotatsu.parsers.model.MangaSource
 import org.koitharu.kotatsu.parsers.network.UserAgents
 import org.koitharu.kotatsu.parsers.util.map
 import java.util.Locale
-import java.util.concurrent.TimeUnit
 import javax.inject.Inject
 import javax.inject.Singleton
 
@@ -38,9 +38,15 @@ class MangaLoaderContextImpl @Inject constructor(
 	override val cookieJar: MutableCookieJar,
 	@ApplicationContext private val androidContext: Context,
 	private val webViewExecutor: WebViewExecutor,
+	private val appSettings: AppSettings,
 ) : MangaLoaderContext() {
 
-	private val jsTimeout = TimeUnit.SECONDS.toMillis(4)
+	/**
+	 * JS evaluation timeout - configurable via settings.
+	 * Useful for complex CloudFlare challenges that may need more time.
+	 */
+	private val jsTimeout: Long
+		get() = appSettings.jsTimeoutMs
 
 	@Deprecated("Provide a base url")
 	@SuppressLint("SetJavaScriptEnabled")
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/prefs/AppSettings.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/prefs/AppSettings.kt
index 2910cd4..9647f9e 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/prefs/AppSettings.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/prefs/AppSettings.kt
@@ -286,6 +286,14 @@ class AppSettings @Inject constructor(@ApplicationContext context: Context) {
 	val isMirrorSwitchingEnabled: Boolean
 		get() = prefs.getBoolean(KEY_MIRROR_SWITCHING, false)
 
+	/**
+	 * JavaScript evaluation timeout in milliseconds.
+	 * Used for CloudFlare challenges and other WebView JS operations.
+	 * Default: 4000ms, Range: 2000-30000ms
+	 */
+	val jsTimeoutMs: Long
+		get() = prefs.getInt(KEY_JS_TIMEOUT, 4000).toLong().coerceIn(2000L, 30000L)
+
 	val isExitConfirmationEnabled: Boolean
 		get() = prefs.getBoolean(KEY_EXIT_CONFIRM, false)
 
@@ -777,6 +785,7 @@ class AppSettings @Inject constructor(@ApplicationContext context: Context) {
 		const val KEY_READER_AUTOSCROLL_SPEED = "as_speed"
 		const val KEY_READER_AUTOSCROLL_FAB = "as_fab"
 		const val KEY_MIRROR_SWITCHING = "mirror_switching"
+		const val KEY_JS_TIMEOUT = "js_timeout"
 		const val KEY_PROXY = "proxy"
 		const val KEY_PROXY_TYPE = "proxy_type_2"
 		const val KEY_PROXY_ADDRESS = "proxy_address"

From 74dba9f0652ce151b5da9cb52beba5c2f28cbb1e Mon Sep 17 00:00:00 2001
From: AgentKush <finlayhansford66@gmail.com>
Date: Thu, 22 Jan 2026 00:03:24 +0000
Subject: [PATCH 14/35] Add configurable compression format options to
 BitmapWrapper

- Added BitmapCompressFormat enum with PNG, JPEG, WEBP, WEBP_LOSSLESS options
- Added overloaded compressTo() with format and quality parameters
- Maintains backward compatibility with original compressTo() method
- Handles API level differences for WebP formats gracefully
- Quality parameter (0-100) for lossy formats, ignored for lossless
- Better compression choices: JPEG for photos, WebP for modern efficiency
---
 .../kotatsu/core/parser/BitmapWrapper.kt      | 58 ++++++++++++++++++-
 1 file changed, 57 insertions(+), 1 deletion(-)

diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/parser/BitmapWrapper.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/parser/BitmapWrapper.kt
index 5c8d4fd..263d8bf 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/parser/BitmapWrapper.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/parser/BitmapWrapper.kt
@@ -1,6 +1,8 @@
 package org.koitharu.kotatsu.core.parser
 
 import android.graphics.Canvas
+import android.os.Build
+import androidx.annotation.IntRange
 import androidx.core.graphics.createBitmap
 import org.koitharu.kotatsu.parsers.bitmap.Bitmap
 import org.koitharu.kotatsu.parsers.bitmap.Rect
@@ -8,6 +10,20 @@ import java.io.OutputStream
 import android.graphics.Bitmap as AndroidBitmap
 import android.graphics.Rect as AndroidRect
 
+/**
+ * Supported compression formats for bitmap output.
+ */
+enum class BitmapCompressFormat {
+	/** Lossless compression, best for graphics with transparency */
+	PNG,
+	/** Lossy compression, smaller files, good for photos */
+	JPEG,
+	/** Modern format with better compression, requires API 14+ (lossy) or API 30+ (lossless) */
+	WEBP,
+	/** Lossless WebP, requires API 30+ */
+	WEBP_LOSSLESS,
+}
+
 class BitmapWrapper private constructor(
 	private val androidBitmap: AndroidBitmap,
 ) : Bitmap, AutoCloseable {
@@ -29,8 +45,48 @@ class BitmapWrapper private constructor(
 		androidBitmap.recycle()
 	}
 
+	/**
+	 * Compress bitmap to output stream with default PNG format.
+	 * Use [compressTo] with format parameter for more control.
+	 */
 	fun compressTo(output: OutputStream) {
-		androidBitmap.compress(AndroidBitmap.CompressFormat.PNG, 100, output)
+		compressTo(output, BitmapCompressFormat.PNG)
+	}
+
+	/**
+	 * Compress bitmap to output stream with specified format and quality.
+	 *
+	 * @param output The output stream to write compressed data to
+	 * @param format The compression format to use
+	 * @param quality Quality hint for lossy formats (0-100). Ignored for PNG and WEBP_LOSSLESS.
+	 *                Higher values produce better quality but larger files.
+	 */
+	fun compressTo(
+		output: OutputStream,
+		format: BitmapCompressFormat,
+		@IntRange(from = 0, to = 100) quality: Int = 90,
+	) {
+		val androidFormat = when (format) {
+			BitmapCompressFormat.PNG -> AndroidBitmap.CompressFormat.PNG
+			BitmapCompressFormat.JPEG -> AndroidBitmap.CompressFormat.JPEG
+			BitmapCompressFormat.WEBP -> if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+				AndroidBitmap.CompressFormat.WEBP_LOSSY
+			} else {
+				@Suppress("DEPRECATION")
+				AndroidBitmap.CompressFormat.WEBP
+			}
+			BitmapCompressFormat.WEBP_LOSSLESS -> if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+				AndroidBitmap.CompressFormat.WEBP_LOSSLESS
+			} else {
+				// Fallback to PNG for lossless on older API
+				AndroidBitmap.CompressFormat.PNG
+			}
+		}
+		val effectiveQuality = when (format) {
+			BitmapCompressFormat.PNG, BitmapCompressFormat.WEBP_LOSSLESS -> 100 // Quality ignored for lossless
+			else -> quality.coerceIn(0, 100)
+		}
+		androidBitmap.compress(androidFormat, effectiveQuality, output)
 	}
 
 	companion object {

From c906f708af224ab72dc891b3f1247ab7ecd307b2 Mon Sep 17 00:00:00 2001
From: AgentKush <finlayhansford66@gmail.com>
Date: Thu, 22 Jan 2026 00:04:27 +0000
Subject: [PATCH 15/35] Add persistent blacklist with TTL to MirrorSwitcher

- Persist failed mirror sources to SharedPreferences across app restarts
- Add 24-hour TTL for blacklist entries (auto-expire and retry)
- Add clearBlacklist() method to manually reset all failed sources
- Add removeFromBlacklist() for individual source removal
- Add blacklistedSources property to query current blacklist state
- Load blacklist on init, cleanup expired entries before each check
- Handle unknown/removed sources gracefully during storage load
- Added @Singleton annotation for proper DI lifecycle
---
 .../kotatsu/core/parser/MirrorSwitcher.kt     | 129 +++++++++++++++++-
 1 file changed, 128 insertions(+), 1 deletion(-)

diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/parser/MirrorSwitcher.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/parser/MirrorSwitcher.kt
index d59a804..5e529b2 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/parser/MirrorSwitcher.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/parser/MirrorSwitcher.kt
@@ -1,6 +1,8 @@
 package org.koitharu.kotatsu.core.parser
 
+import android.content.Context
 import android.util.Log
+import dagger.hilt.android.qualifiers.ApplicationContext
 import kotlinx.coroutines.sync.Mutex
 import kotlinx.coroutines.sync.withLock
 import okhttp3.OkHttpClient
@@ -12,21 +14,50 @@ import org.koitharu.kotatsu.parsers.model.MangaParserSource
 import org.koitharu.kotatsu.parsers.util.await
 import org.koitharu.kotatsu.parsers.util.runCatchingCancellable
 import java.util.EnumSet
+import java.util.concurrent.TimeUnit
 import javax.inject.Inject
+import javax.inject.Singleton
 
+/**
+ * Handles automatic mirror switching for manga sources when the primary domain fails.
+ * Features:
+ * - Persistent blacklist that survives app restarts
+ * - Time-based expiration of blacklist entries (24 hours default)
+ * - Manual blacklist clearing capability
+ */
+@Singleton
 class MirrorSwitcher @Inject constructor(
 	private val settings: AppSettings,
 	@MangaHttpClient private val okHttpClient: OkHttpClient,
+	@ApplicationContext private val context: Context,
 ) {
 
 	private val blacklist = EnumSet.noneOf(MangaParserSource::class.java)
+	private val blacklistTimestamps = mutableMapOf<MangaParserSource, Long>()
 	private val mutex: Mutex = Mutex()
+	private val prefs by lazy {
+		context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+	}
+
+	init {
+		loadBlacklistFromStorage()
+	}
 
 	val isEnabled: Boolean
 		get() = settings.isMirrorSwitchingEnabled
 
+	/**
+	 * Get the list of currently blacklisted sources (excluding expired entries).
+	 */
+	val blacklistedSources: Set<MangaParserSource>
+		get() {
+			cleanupExpiredEntries()
+			return blacklist.toSet()
+		}
+
 	suspend fun <T : Any> trySwitchMirror(repository: ParserMangaRepository, loader: suspend () -> T?): T? {
 		val source = repository.source
+		cleanupExpiredEntries()
 		if (!isEnabled || source in blacklist) {
 			return null
 		}
@@ -59,7 +90,7 @@ class MirrorSwitcher @Inject constructor(
 				}
 			}
 			repository.domain = currentHost // rollback
-			blacklist.add(source)
+			addToBlacklist(source)
 			logd { "$source blacklisted" }
 			return null
 		}
@@ -89,6 +120,96 @@ class MirrorSwitcher @Inject constructor(
 		}
 	}
 
+	/**
+	 * Clear all blacklisted sources, allowing them to be retried.
+	 * Useful when mirrors may have come back online.
+	 */
+	fun clearBlacklist() {
+		blacklist.clear()
+		blacklistTimestamps.clear()
+		prefs.edit()
+			.remove(KEY_BLACKLIST)
+			.remove(KEY_BLACKLIST_TIMESTAMPS)
+			.apply()
+		logd { "Blacklist cleared" }
+	}
+
+	/**
+	 * Remove a specific source from the blacklist.
+	 */
+	fun removeFromBlacklist(source: MangaParserSource) {
+		if (blacklist.remove(source)) {
+			blacklistTimestamps.remove(source)
+			saveBlacklistToStorage()
+			logd { "$source removed from blacklist" }
+		}
+	}
+
+	private fun addToBlacklist(source: MangaParserSource) {
+		blacklist.add(source)
+		blacklistTimestamps[source] = System.currentTimeMillis()
+		saveBlacklistToStorage()
+	}
+
+	private fun cleanupExpiredEntries() {
+		val now = System.currentTimeMillis()
+		val expiredSources = blacklistTimestamps.filter { (_, timestamp) ->
+			now - timestamp > BLACKLIST_TTL_MS
+		}.keys
+		if (expiredSources.isNotEmpty()) {
+			expiredSources.forEach { source ->
+				blacklist.remove(source)
+				blacklistTimestamps.remove(source)
+				logd { "$source expired from blacklist" }
+			}
+			saveBlacklistToStorage()
+		}
+	}
+
+	private fun saveBlacklistToStorage() {
+		val sourceNames = blacklist.map { it.name }.toSet()
+		val timestamps = blacklistTimestamps.map { (source, time) -> "${source.name}:$time" }.toSet()
+		prefs.edit()
+			.putStringSet(KEY_BLACKLIST, sourceNames)
+			.putStringSet(KEY_BLACKLIST_TIMESTAMPS, timestamps)
+			.apply()
+	}
+
+	private fun loadBlacklistFromStorage() {
+		val sourceNames = prefs.getStringSet(KEY_BLACKLIST, emptySet()) ?: emptySet()
+		val timestamps = prefs.getStringSet(KEY_BLACKLIST_TIMESTAMPS, emptySet()) ?: emptySet()
+
+		// Parse timestamps map
+		val timestampMap = timestamps.mapNotNull { entry ->
+			val parts = entry.split(":")
+			if (parts.size == 2) {
+				try {
+					parts[0] to parts[1].toLong()
+				} catch (e: NumberFormatException) {
+					null
+				}
+			} else null
+		}.toMap()
+
+		// Load sources with valid timestamps
+		val now = System.currentTimeMillis()
+		sourceNames.forEach { name ->
+			try {
+				val source = MangaParserSource.valueOf(name)
+				val timestamp = timestampMap[name] ?: now
+				// Only load if not expired
+				if (now - timestamp <= BLACKLIST_TTL_MS) {
+					blacklist.add(source)
+					blacklistTimestamps[source] = timestamp
+				}
+			} catch (e: IllegalArgumentException) {
+				// Source no longer exists, skip it
+				logd { "Unknown source in blacklist: $name" }
+			}
+		}
+		logd { "Loaded ${blacklist.size} sources from persistent blacklist" }
+	}
+
 	private fun <T : Any> T.takeIfValid() = takeIf {
 		when (it) {
 			is Collection<*> -> it.isNotEmpty()
@@ -99,6 +220,12 @@ class MirrorSwitcher @Inject constructor(
 	private companion object {
 
 		const val TAG = "MirrorSwitcher"
+		const val PREFS_NAME = "mirror_switcher"
+		const val KEY_BLACKLIST = "blacklist"
+		const val KEY_BLACKLIST_TIMESTAMPS = "blacklist_timestamps"
+		
+		/** Blacklist entries expire after 24 hours */
+		val BLACKLIST_TTL_MS = TimeUnit.HOURS.toMillis(24)
 
 		inline fun logd(message: () -> String) {
 			if (BuildConfig.DEBUG) {

From f4dc2ec6569dfdc5deb2a1e8d27f307490014eca Mon Sep 17 00:00:00 2001
From: AgentKush <finlayhansford66@gmail.com>
Date: Thu, 22 Jan 2026 00:06:26 +0000
Subject: [PATCH 16/35] Add related manga support for external plugins

ExternalPluginContentSource:
- Added getRelatedManga() method to query related manga from plugins
- Uses content URI: content://{authority}/manga/related/{url}
- Gracefully returns empty list if plugin doesn't support this feature
- Added COLUMN_RELATED_MANGA constant for capability detection

MangaSourceCapabilities:
- Added isRelatedMangaSupported flag (default: false for compatibility)
- Read from capabilities cursor during plugin initialization

ExternalMangaRepository:
- Updated getRelatedMangaImpl() to use plugin's related manga feature
- Checks capability before making content provider query
- Maintains backward compatibility with plugins that don't support it
---
 .../external/ExternalMangaRepository.kt       | 14 ++++++++-
 .../external/ExternalPluginContentSource.kt   | 29 +++++++++++++++++++
 2 files changed, 42 insertions(+), 1 deletion(-)

diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/parser/external/ExternalMangaRepository.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/parser/external/ExternalMangaRepository.kt
index 4c49626..5744395 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/parser/external/ExternalMangaRepository.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/parser/external/ExternalMangaRepository.kt
@@ -63,5 +63,17 @@ class ExternalMangaRepository(
 		contentSource.getPageUrl(page.url)
 	}
 
-	override suspend fun getRelatedMangaImpl(seed: Manga): List<Manga> = emptyList() // External plugins don't support related manga
+	/**
+	 * Get related manga from external plugin.
+	 * Returns empty list if the plugin doesn't support this feature.
+	 */
+	override suspend fun getRelatedMangaImpl(seed: Manga): List<Manga> {
+		// Check if plugin supports related manga
+		if (capabilities?.isRelatedMangaSupported != true) {
+			return emptyList()
+		}
+		return runInterruptible(Dispatchers.IO) {
+			contentSource.getRelatedManga(seed)
+		}
+	}
 }
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/parser/external/ExternalPluginContentSource.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/parser/external/ExternalPluginContentSource.kt
index 58dff0d..082dbbc 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/parser/external/ExternalPluginContentSource.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/parser/external/ExternalPluginContentSource.kt
@@ -159,6 +159,32 @@ class ExternalPluginContentSource(
 			}
 	}
 
+	/**
+	 * Get related manga for a given seed manga.
+	 * Returns empty list if the plugin doesn't support related manga.
+	 */
+	@Blocking
+	@WorkerThread
+	fun getRelatedManga(seed: Manga): List<Manga> {
+		val uri = "content://${source.authority}/manga/related".toUri()
+			.buildUpon()
+			.appendPath(seed.url)
+			.build()
+		return runCatching {
+			contentResolver.query(uri, null, null, null, null)
+				.safe()
+				.use { cursor ->
+					val result = ArrayList<Manga>(cursor.count)
+					if (cursor.moveToFirst()) {
+						do {
+							result += cursor.getManga()
+						} while (cursor.moveToNext())
+					}
+					result
+				}
+		}.getOrDefault(emptyList())
+	}
+
 	@Blocking
 	@WorkerThread
 	private fun fetchLocales(): Set<Locale> {
@@ -201,6 +227,7 @@ class ExternalPluginContentSource(
 							isOriginalLocaleSupported = cursor.getBooleanOrDefault(COLUMN_ORIGINAL_LOCALE, false),
 							isAuthorSearchSupported = cursor.getBooleanOrDefault(COLUMN_AUTHOR, false),
 						),
+						isRelatedMangaSupported = cursor.getBooleanOrDefault(COLUMN_RELATED_MANGA, false),
 					)
 				} else {
 					null
@@ -304,6 +331,7 @@ class ExternalPluginContentSource(
 	class MangaSourceCapabilities(
 		val availableSortOrders: Set<SortOrder>,
 		val listFilterCapabilities: MangaListFilterCapabilities,
+		val isRelatedMangaSupported: Boolean = false,
 	)
 
 	private companion object {
@@ -316,6 +344,7 @@ class ExternalPluginContentSource(
 		const val COLUMN_YEAR = "year"
 		const val COLUMN_YEAR_RANGE = "year_range"
 		const val COLUMN_ORIGINAL_LOCALE = "original_locale"
+		const val COLUMN_RELATED_MANGA = "related_manga"
 		const val COLUMN_ID = "id"
 		const val COLUMN_NAME = "name"
 		const val COLUMN_NUMBER = "number"

From 4088fb9e282510cf40a479b47f69a918c4146201 Mon Sep 17 00:00:00 2001
From: AgentKush <finlayhansford66@gmail.com>
Date: Thu, 22 Jan 2026 00:26:34 +0000
Subject: [PATCH 17/35] Add exponential backoff retry to RateLimitInterceptor
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Configurable max retries (default: 3 attempts)
- Exponential backoff with jitter to prevent thundering herd
- Respects Retry-After header when present, caps at maxDelayMs
- Calculated delay formula: min(maxDelay, initialDelay * 2^retryCount) ± 25% jitter
- Default delays: 1s initial, 30s max, 2x multiplier
- Debug logging for retry attempts
- Fixed parseRetryAfter to handle HTTP date format properly
- Only throws TooManyRequestExceptions after all retries exhausted
---
 .../core/network/RateLimitInterceptor.kt      | 98 +++++++++++++++++--
 1 file changed, 92 insertions(+), 6 deletions(-)

diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/network/RateLimitInterceptor.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/RateLimitInterceptor.kt
index 79584c8..75c8d72 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/network/RateLimitInterceptor.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/RateLimitInterceptor.kt
@@ -1,29 +1,115 @@
 package org.koitharu.kotatsu.core.network
 
+import android.util.Log
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.runBlocking
 import okhttp3.Interceptor
 import okhttp3.Response
 import okhttp3.internal.closeQuietly
+import org.koitharu.kotatsu.BuildConfig
 import org.koitharu.kotatsu.parsers.exception.TooManyRequestExceptions
 import java.time.ZonedDateTime
 import java.time.format.DateTimeFormatter
 import java.util.concurrent.TimeUnit
+import kotlin.math.min
+import kotlin.random.Random
+
+/**
+ * Interceptor that handles HTTP 429 (Too Many Requests) responses with exponential backoff.
+ *
+ * Features:
+ * - Configurable max retry attempts
+ * - Exponential backoff with jitter to prevent thundering herd
+ * - Respects Retry-After header when present
+ * - Falls back to calculated delay when header is missing
+ *
+ * @param maxRetries Maximum number of retry attempts (default: 3)
+ * @param initialDelayMs Initial delay in milliseconds (default: 1000ms)
+ * @param maxDelayMs Maximum delay cap in milliseconds (default: 30000ms)
+ * @param backoffMultiplier Multiplier for exponential growth (default: 2.0)
+ */
+class RateLimitInterceptor(
+	private val maxRetries: Int = DEFAULT_MAX_RETRIES,
+	private val initialDelayMs: Long = DEFAULT_INITIAL_DELAY_MS,
+	private val maxDelayMs: Long = DEFAULT_MAX_DELAY_MS,
+	private val backoffMultiplier: Double = DEFAULT_BACKOFF_MULTIPLIER,
+) : Interceptor {
 
-class RateLimitInterceptor : Interceptor {
 	override fun intercept(chain: Interceptor.Chain): Response {
-		val response = chain.proceed(chain.request())
+		var response = chain.proceed(chain.request())
+		var retryCount = 0
+
+		while (response.code == 429 && retryCount < maxRetries) {
+			val request = response.request
+			val retryAfterMs = response.header(CommonHeaders.RETRY_AFTER)?.parseRetryAfter()
+			response.closeQuietly()
+
+			// Calculate delay: use Retry-After header if available, otherwise exponential backoff
+			val calculatedDelay = calculateBackoffDelay(retryCount)
+			val delayMs = retryAfterMs?.coerceAtMost(maxDelayMs) ?: calculatedDelay
+
+			logDebug { "Rate limited (429) on ${request.url.host}, retry ${retryCount + 1}/$maxRetries after ${delayMs}ms" }
+
+			// Wait before retrying
+			runBlocking {
+				delay(delayMs)
+			}
+
+			retryCount++
+			response = chain.proceed(request)
+		}
+
+		// If still rate limited after all retries, throw exception
 		if (response.code == 429) {
 			val request = response.request
+			val retryAfter = response.header(CommonHeaders.RETRY_AFTER)?.parseRetryAfter() ?: 0L
 			response.closeQuietly()
+			logDebug { "Rate limit exceeded after $maxRetries retries on ${request.url}" }
 			throw TooManyRequestExceptions(
 				url = request.url.toString(),
-				retryAfter = response.header(CommonHeaders.RETRY_AFTER)?.parseRetryAfter() ?: 0L,
+				retryAfter = retryAfter,
 			)
 		}
+
 		return response
 	}
 
-	private fun String.parseRetryAfter(): Long {
-		return toLongOrNull()?.let { TimeUnit.SECONDS.toMillis(it) }
-			?: ZonedDateTime.parse(this, DateTimeFormatter.RFC_1123_DATE_TIME).toInstant().toEpochMilli()
+	/**
+	 * Calculate exponential backoff delay with jitter.
+	 * Formula: min(maxDelay, initialDelay * (multiplier ^ retryCount)) + random jitter
+	 */
+	private fun calculateBackoffDelay(retryCount: Int): Long {
+		val exponentialDelay = initialDelayMs * Math.pow(backoffMultiplier, retryCount.toDouble()).toLong()
+		val cappedDelay = min(exponentialDelay, maxDelayMs)
+		// Add jitter (±25%) to prevent thundering herd
+		val jitter = (cappedDelay * 0.25 * (Random.nextDouble() - 0.5)).toLong()
+		return (cappedDelay + jitter).coerceAtLeast(initialDelayMs)
+	}
+
+	private fun String.parseRetryAfter(): Long? {
+		// Try parsing as seconds first
+		toLongOrNull()?.let { seconds ->
+			return TimeUnit.SECONDS.toMillis(seconds)
+		}
+		// Try parsing as HTTP date
+		return runCatching {
+			val dateTime = ZonedDateTime.parse(this, DateTimeFormatter.RFC_1123_DATE_TIME)
+			val delayMs = dateTime.toInstant().toEpochMilli() - System.currentTimeMillis()
+			delayMs.coerceAtLeast(0L)
+		}.getOrNull()
+	}
+
+	private inline fun logDebug(message: () -> String) {
+		if (BuildConfig.DEBUG) {
+			Log.d(TAG, message())
+		}
+	}
+
+	companion object {
+		private const val TAG = "RateLimitInterceptor"
+		private const val DEFAULT_MAX_RETRIES = 3
+		private const val DEFAULT_INITIAL_DELAY_MS = 1000L
+		private const val DEFAULT_MAX_DELAY_MS = 30_000L
+		private const val DEFAULT_BACKOFF_MULTIPLIER = 2.0
 	}
 }

From 1d56aa7953f15a28ee7543a6f3c7dd2d5e51ae3e Mon Sep 17 00:00:00 2001
From: AgentKush <finlayhansford66@gmail.com>
Date: Thu, 22 Jan 2026 00:29:19 +0000
Subject: [PATCH 18/35] Add persistent blacklist for image proxy interceptors

ProxyBlacklistManager (new):
- Singleton class managing persistent host blacklist
- SharedPreferences storage with timestamps for TTL
- 6-hour expiration for blacklist entries
- Thread-safe with synchronized access
- Methods: isBlacklisted(), addToBlacklist(), removeFromBlacklist(), clearBlacklist()

BaseImageProxyInterceptor:
- Now accepts optional ProxyBlacklistManager parameter
- Removed in-memory ArraySet blacklist
- Delegates to manager for blacklist operations
- Backward compatible with null manager

WsrvNlProxyInterceptor / ZeroMsProxyInterceptor:
- Updated constructors to accept blacklist manager

RealImageProxyInterceptor:
- Injects ProxyBlacklistManager via Hilt
- Passes manager to child interceptors on creation
---
 .../imageproxy/BaseImageProxyInterceptor.kt   |  27 ++-
 .../imageproxy/ProxyBlacklistManager.kt       | 165 ++++++++++++++++++
 .../imageproxy/RealImageProxyInterceptor.kt   |   5 +-
 .../imageproxy/WsrvNlProxyInterceptor.kt      |   4 +-
 .../imageproxy/ZeroMsProxyInterceptor.kt      |   4 +-
 5 files changed, 193 insertions(+), 12 deletions(-)
 create mode 100644 app/src/main/kotlin/org/koitharu/kotatsu/core/network/imageproxy/ProxyBlacklistManager.kt

diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/network/imageproxy/BaseImageProxyInterceptor.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/imageproxy/BaseImageProxyInterceptor.kt
index 40eb783..11e4c99 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/network/imageproxy/BaseImageProxyInterceptor.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/imageproxy/BaseImageProxyInterceptor.kt
@@ -1,7 +1,6 @@
 package org.koitharu.kotatsu.core.network.imageproxy
 
 import android.util.Log
-import androidx.collection.ArraySet
 import coil3.intercept.Interceptor
 import coil3.network.HttpException
 import coil3.request.ErrorResult
@@ -21,11 +20,15 @@ import org.koitharu.kotatsu.parsers.util.await
 import org.koitharu.kotatsu.parsers.util.isHttpOrHttps
 import org.koitharu.kotatsu.parsers.util.runCatchingCancellable
 import java.net.HttpURLConnection
-import java.util.Collections
 
-abstract class BaseImageProxyInterceptor : ImageProxyInterceptor {
-
-	private val blacklist = Collections.synchronizedSet(ArraySet<String>())
+/**
+ * Base class for image proxy interceptors with persistent blacklist support.
+ *
+ * @param blacklistManager Manager for persistent host blacklisting (optional for backward compatibility)
+ */
+abstract class BaseImageProxyInterceptor(
+	private val blacklistManager: ProxyBlacklistManager? = null,
+) : ImageProxyInterceptor {
 
 	final override suspend fun intercept(chain: Interceptor.Chain): ImageResult {
 		val request = chain.request
@@ -34,7 +37,7 @@ abstract class BaseImageProxyInterceptor : ImageProxyInterceptor {
 			is String -> data.toHttpUrlOrNull()
 			else -> null
 		}
-		if (url == null || !url.isHttpOrHttps || url.host in blacklist) {
+		if (url == null || !url.isHttpOrHttps || isBlacklisted(url.host)) {
 			return chain.proceed()
 		}
 		val newRequest = onInterceptImageRequest(request, url)
@@ -44,7 +47,7 @@ abstract class BaseImageProxyInterceptor : ImageProxyInterceptor {
 				logDebug(result.throwable, newRequest.data)
 				chain.proceed().also {
 					if (it is SuccessResult && result.throwable.isBlockedByServer()) {
-						blacklist.add(url.host)
+						addToBlacklist(url.host)
 					}
 				}
 			}
@@ -59,7 +62,7 @@ abstract class BaseImageProxyInterceptor : ImageProxyInterceptor {
 			logDebug(error, newRequest.url)
 			okHttp.doCall(request).also {
 				if (error.isBlockedByServer()) {
-					blacklist.add(request.url.host)
+					addToBlacklist(request.url.host)
 				}
 			}
 		}.getOrThrow()
@@ -69,6 +72,14 @@ abstract class BaseImageProxyInterceptor : ImageProxyInterceptor {
 
 	protected abstract suspend fun onInterceptPageRequest(request: Request): Request
 
+	private fun isBlacklisted(host: String): Boolean {
+		return blacklistManager?.isBlacklisted(host) == true
+	}
+
+	private fun addToBlacklist(host: String) {
+		blacklistManager?.addToBlacklist(host)
+	}
+
 	private suspend fun OkHttpClient.doCall(request: Request): Response {
 		return newCall(request).await().ensureSuccess()
 	}
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/network/imageproxy/ProxyBlacklistManager.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/imageproxy/ProxyBlacklistManager.kt
new file mode 100644
index 0000000..1a11f17
--- /dev/null
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/imageproxy/ProxyBlacklistManager.kt
@@ -0,0 +1,165 @@
+package org.koitharu.kotatsu.core.network.imageproxy
+
+import android.content.Context
+import android.util.Log
+import dagger.hilt.android.qualifiers.ApplicationContext
+import org.koitharu.kotatsu.BuildConfig
+import java.util.concurrent.TimeUnit
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Manages a persistent blacklist of hosts that have blocked proxy requests.
+ * Blacklisted hosts are stored in SharedPreferences with timestamps for TTL expiration.
+ *
+ * Features:
+ * - Persistent storage across app restarts
+ * - Time-based expiration (default: 6 hours)
+ * - Thread-safe operations
+ * - Manual clear capability
+ */
+@Singleton
+class ProxyBlacklistManager @Inject constructor(
+	@ApplicationContext private val context: Context,
+) {
+
+	private val blacklist = mutableSetOf<String>()
+	private val timestamps = mutableMapOf<String, Long>()
+	private val lock = Any()
+
+	private val prefs by lazy {
+		context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+	}
+
+	init {
+		loadFromStorage()
+	}
+
+	/**
+	 * Check if a host is blacklisted (and not expired).
+	 */
+	fun isBlacklisted(host: String): Boolean {
+		synchronized(lock) {
+			cleanupExpired()
+			return host in blacklist
+		}
+	}
+
+	/**
+	 * Add a host to the blacklist.
+	 */
+	fun addToBlacklist(host: String) {
+		synchronized(lock) {
+			if (blacklist.add(host)) {
+				timestamps[host] = System.currentTimeMillis()
+				saveToStorage()
+				logDebug { "Added to proxy blacklist: $host" }
+			}
+		}
+	}
+
+	/**
+	 * Remove a specific host from the blacklist.
+	 */
+	fun removeFromBlacklist(host: String) {
+		synchronized(lock) {
+			if (blacklist.remove(host)) {
+				timestamps.remove(host)
+				saveToStorage()
+				logDebug { "Removed from proxy blacklist: $host" }
+			}
+		}
+	}
+
+	/**
+	 * Clear all blacklisted hosts.
+	 */
+	fun clearBlacklist() {
+		synchronized(lock) {
+			blacklist.clear()
+			timestamps.clear()
+			prefs.edit()
+				.remove(KEY_HOSTS)
+				.remove(KEY_TIMESTAMPS)
+				.apply()
+			logDebug { "Proxy blacklist cleared" }
+		}
+	}
+
+	/**
+	 * Get the current blacklist size.
+	 */
+	val size: Int
+		get() = synchronized(lock) {
+			cleanupExpired()
+			blacklist.size
+		}
+
+	private fun cleanupExpired() {
+		val now = System.currentTimeMillis()
+		val expired = timestamps.filter { (_, timestamp) ->
+			now - timestamp > BLACKLIST_TTL_MS
+		}.keys
+
+		if (expired.isNotEmpty()) {
+			expired.forEach { host ->
+				blacklist.remove(host)
+				timestamps.remove(host)
+				logDebug { "Expired from proxy blacklist: $host" }
+			}
+			saveToStorage()
+		}
+	}
+
+	private fun saveToStorage() {
+		val hostSet = blacklist.toSet()
+		val timestampSet = timestamps.map { (host, time) -> "$host:$time" }.toSet()
+		prefs.edit()
+			.putStringSet(KEY_HOSTS, hostSet)
+			.putStringSet(KEY_TIMESTAMPS, timestampSet)
+			.apply()
+	}
+
+	private fun loadFromStorage() {
+		val hosts = prefs.getStringSet(KEY_HOSTS, emptySet()) ?: emptySet()
+		val timestampEntries = prefs.getStringSet(KEY_TIMESTAMPS, emptySet()) ?: emptySet()
+
+		// Parse timestamps
+		val timestampMap = timestampEntries.mapNotNull { entry ->
+			val parts = entry.split(":")
+			if (parts.size >= 2) {
+				val host = parts.dropLast(1).joinToString(":") // Handle hosts with colons (IPv6)
+				val time = parts.last().toLongOrNull()
+				if (time != null) host to time else null
+			} else null
+		}.toMap()
+
+		// Load only non-expired entries
+		val now = System.currentTimeMillis()
+		hosts.forEach { host ->
+			val timestamp = timestampMap[host] ?: now
+			if (now - timestamp <= BLACKLIST_TTL_MS) {
+				blacklist.add(host)
+				timestamps[host] = timestamp
+			}
+		}
+
+		logDebug { "Loaded ${blacklist.size} hosts from proxy blacklist" }
+	}
+
+	private inline fun logDebug(message: () -> String) {
+		if (BuildConfig.DEBUG) {
+			Log.d(TAG, message())
+		}
+	}
+
+	companion object {
+		private const val TAG = "ProxyBlacklistManager"
+		private const val PREFS_NAME = "image_proxy_blacklist"
+		private const val KEY_HOSTS = "hosts"
+		private const val KEY_TIMESTAMPS = "timestamps"
+
+		/** Blacklist entries expire after 6 hours */
+		val BLACKLIST_TTL_MS = TimeUnit.HOURS.toMillis(6)
+	}
+}
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/network/imageproxy/RealImageProxyInterceptor.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/imageproxy/RealImageProxyInterceptor.kt
index c3b7cfe..16727ad 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/network/imageproxy/RealImageProxyInterceptor.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/imageproxy/RealImageProxyInterceptor.kt
@@ -17,6 +17,7 @@ import javax.inject.Singleton
 @Singleton
 class RealImageProxyInterceptor @Inject constructor(
 	private val settings: AppSettings,
+	private val blacklistManager: ProxyBlacklistManager,
 ) : ImageProxyInterceptor {
 
 	private val delegate = settings.observeAsStateFlow(
@@ -35,8 +36,8 @@ class RealImageProxyInterceptor @Inject constructor(
 
 	private fun createDelegate(): ImageProxyInterceptor? = when (val proxy = settings.imagesProxy) {
 		-1 -> null
-		0 -> WsrvNlProxyInterceptor()
-		1 -> ZeroMsProxyInterceptor()
+		0 -> WsrvNlProxyInterceptor(blacklistManager)
+		1 -> ZeroMsProxyInterceptor(blacklistManager)
 		else -> error("Unsupported images proxy $proxy")
 	}
 }
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/network/imageproxy/WsrvNlProxyInterceptor.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/imageproxy/WsrvNlProxyInterceptor.kt
index 13f821b..753583f 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/network/imageproxy/WsrvNlProxyInterceptor.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/imageproxy/WsrvNlProxyInterceptor.kt
@@ -6,7 +6,9 @@ import coil3.size.isOriginal
 import okhttp3.HttpUrl
 import okhttp3.Request
 
-class WsrvNlProxyInterceptor : BaseImageProxyInterceptor() {
+class WsrvNlProxyInterceptor(
+	blacklistManager: ProxyBlacklistManager? = null,
+) : BaseImageProxyInterceptor(blacklistManager) {
 
 	override suspend fun onInterceptImageRequest(request: ImageRequest, url: HttpUrl): ImageRequest {
 		val newUrl = HttpUrl.Builder()
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/network/imageproxy/ZeroMsProxyInterceptor.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/imageproxy/ZeroMsProxyInterceptor.kt
index 9c6d01e..2e42c6f 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/network/imageproxy/ZeroMsProxyInterceptor.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/imageproxy/ZeroMsProxyInterceptor.kt
@@ -5,7 +5,9 @@ import okhttp3.HttpUrl
 import okhttp3.HttpUrl.Companion.toHttpUrl
 import okhttp3.Request
 
-class ZeroMsProxyInterceptor : BaseImageProxyInterceptor() {
+class ZeroMsProxyInterceptor(
+	blacklistManager: ProxyBlacklistManager? = null,
+) : BaseImageProxyInterceptor(blacklistManager) {
 
 	override suspend fun onInterceptImageRequest(request: ImageRequest, url: HttpUrl): ImageRequest {
 		if (url.host == "v.recipes") {

From e529452278fd624bc066ee13819d693df8552b9c Mon Sep 17 00:00:00 2001
From: AgentKush <finlayhansford66@gmail.com>
Date: Thu, 22 Jan 2026 00:31:11 +0000
Subject: [PATCH 19/35] Add configurable TTL for memory content caches

AppSettings:
- Added KEY_CACHE_DETAILS_TTL (default: 5 min, range: 1-60)
- Added KEY_CACHE_PAGES_TTL (default: 10 min, range: 1-120)
- Added KEY_CACHE_RELATED_TTL (default: 10 min, range: 1-120)
- Added getter properties with coerceIn bounds validation

MemoryContentCache:
- Now injects AppSettings for TTL configuration
- Uses configurable TTL values instead of hardcoded
- Added KDoc explaining settings and restart requirement
- Reformatted cache initialization for clarity

Note: Changes to cache TTL settings require app restart to take effect.
---
 .../kotatsu/core/cache/MemoryContentCache.kt  | 38 ++++++++++++++++---
 .../kotatsu/core/prefs/AppSettings.kt         | 21 ++++++++++
 2 files changed, 53 insertions(+), 6 deletions(-)

diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/cache/MemoryContentCache.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/cache/MemoryContentCache.kt
index cf78bcb..96ec282 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/cache/MemoryContentCache.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/cache/MemoryContentCache.kt
@@ -3,6 +3,7 @@ package org.koitharu.kotatsu.core.cache
 import android.app.Application
 import android.content.ComponentCallbacks2
 import android.content.res.Configuration
+import org.koitharu.kotatsu.core.prefs.AppSettings
 import org.koitharu.kotatsu.core.util.ext.isLowRamDevice
 import org.koitharu.kotatsu.parsers.model.Manga
 import org.koitharu.kotatsu.parsers.model.MangaPage
@@ -11,16 +12,41 @@ import java.util.concurrent.TimeUnit
 import javax.inject.Inject
 import javax.inject.Singleton
 
+/**
+ * In-memory cache for manga content with configurable TTL.
+ *
+ * Cache TTL settings can be configured in AppSettings:
+ * - Details cache: default 5 minutes (configurable 1-60 min)
+ * - Pages cache: default 10 minutes (configurable 1-120 min)
+ * - Related manga cache: default 10 minutes (configurable 1-120 min)
+ *
+ * Note: Changes to TTL settings require app restart to take effect.
+ */
 @Singleton
-class MemoryContentCache @Inject constructor(application: Application) : ComponentCallbacks2 {
+class MemoryContentCache @Inject constructor(
+	application: Application,
+	settings: AppSettings,
+) : ComponentCallbacks2 {
 
 	private val isLowRam = application.isLowRamDevice()
 
-	private val detailsCache = ExpiringLruCache<SafeDeferred<Manga>>(if (isLowRam) 1 else 4, 5, TimeUnit.MINUTES)
-	private val pagesCache =
-		ExpiringLruCache<SafeDeferred<List<MangaPage>>>(if (isLowRam) 1 else 4, 10, TimeUnit.MINUTES)
-	private val relatedMangaCache =
-		ExpiringLruCache<SafeDeferred<List<Manga>>>(if (isLowRam) 1 else 3, 10, TimeUnit.MINUTES)
+	private val detailsCache = ExpiringLruCache<SafeDeferred<Manga>>(
+		maxSize = if (isLowRam) 1 else 4,
+		lifetime = settings.cacheDetailsTtlMinutes.toLong(),
+		timeUnit = TimeUnit.MINUTES,
+	)
+
+	private val pagesCache = ExpiringLruCache<SafeDeferred<List<MangaPage>>>(
+		maxSize = if (isLowRam) 1 else 4,
+		lifetime = settings.cachePagesTtlMinutes.toLong(),
+		timeUnit = TimeUnit.MINUTES,
+	)
+
+	private val relatedMangaCache = ExpiringLruCache<SafeDeferred<List<Manga>>>(
+		maxSize = if (isLowRam) 1 else 3,
+		lifetime = settings.cacheRelatedTtlMinutes.toLong(),
+		timeUnit = TimeUnit.MINUTES,
+	)
 
 	init {
 		application.registerComponentCallbacks(this)
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/prefs/AppSettings.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/prefs/AppSettings.kt
index 9647f9e..a819db7 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/prefs/AppSettings.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/prefs/AppSettings.kt
@@ -294,6 +294,19 @@ class AppSettings @Inject constructor(@ApplicationContext context: Context) {
 	val jsTimeoutMs: Long
 		get() = prefs.getInt(KEY_JS_TIMEOUT, 4000).toLong().coerceIn(2000L, 30000L)
 
+	/**
+	 * Memory cache TTL settings in minutes.
+	 * Controls how long manga details, pages, and related manga are cached in memory.
+	 */
+	val cacheDetailsTtlMinutes: Int
+		get() = prefs.getInt(KEY_CACHE_DETAILS_TTL, DEFAULT_CACHE_DETAILS_TTL).coerceIn(1, 60)
+
+	val cachePagesTtlMinutes: Int
+		get() = prefs.getInt(KEY_CACHE_PAGES_TTL, DEFAULT_CACHE_PAGES_TTL).coerceIn(1, 120)
+
+	val cacheRelatedTtlMinutes: Int
+		get() = prefs.getInt(KEY_CACHE_RELATED_TTL, DEFAULT_CACHE_RELATED_TTL).coerceIn(1, 120)
+
 	val isExitConfirmationEnabled: Boolean
 		get() = prefs.getBoolean(KEY_EXIT_CONFIRM, false)
 
@@ -786,6 +799,9 @@ class AppSettings @Inject constructor(@ApplicationContext context: Context) {
 		const val KEY_READER_AUTOSCROLL_FAB = "as_fab"
 		const val KEY_MIRROR_SWITCHING = "mirror_switching"
 		const val KEY_JS_TIMEOUT = "js_timeout"
+		const val KEY_CACHE_DETAILS_TTL = "cache_details_ttl"
+		const val KEY_CACHE_PAGES_TTL = "cache_pages_ttl"
+		const val KEY_CACHE_RELATED_TTL = "cache_related_ttl"
 		const val KEY_PROXY = "proxy"
 		const val KEY_PROXY_TYPE = "proxy_type_2"
 		const val KEY_PROXY_ADDRESS = "proxy_address"
@@ -854,5 +870,10 @@ class AppSettings @Inject constructor(@ApplicationContext context: Context) {
 		// values
 		private const val READER_CROP_PAGED = 1
 		private const val READER_CROP_WEBTOON = 2
+
+		// cache TTL defaults (in minutes)
+		const val DEFAULT_CACHE_DETAILS_TTL = 5
+		const val DEFAULT_CACHE_PAGES_TTL = 10
+		const val DEFAULT_CACHE_RELATED_TTL = 10
 	}
 }

From 098c31b9b5418b8dc43064501157402c879ba2c4 Mon Sep 17 00:00:00 2001
From: AgentKush <finlayhansford66@gmail.com>
Date: Thu, 22 Jan 2026 00:37:30 +0000
Subject: [PATCH 20/35] Add configurable parallel chapter checking for tracker

AppSettings:
- Added KEY_TRACKER_PARALLELISM setting (default: 6, range: 1-12)
- Added DEFAULT_TRACKER_PARALLELISM constant

CheckNewChaptersUseCase:
- Added checkBatch() method returning Flow<MangaUpdates>
- Parallel execution with configurable semaphore
- Maintains per-manga mutex locking for thread safety
- Added DEFAULT_PARALLELISM and MAX_PARALLELISM constants

TrackWorker:
- Now uses checkBatch() from CheckNewChaptersUseCase
- Reads parallelism from settings.trackerParallelism
- Removed redundant channelFlow/semaphore implementation
- Removed MAX_PARALLELISM constant (now in use case)
- Cleaned up unused imports
---
 .../kotatsu/core/prefs/AppSettings.kt         | 12 ++++++
 .../tracker/domain/CheckNewChaptersUseCase.kt | 41 +++++++++++++++++++
 .../kotatsu/tracker/work/TrackWorker.kt       | 27 ++----------
 3 files changed, 56 insertions(+), 24 deletions(-)

diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/prefs/AppSettings.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/prefs/AppSettings.kt
index a819db7..758ab4d 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/prefs/AppSettings.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/prefs/AppSettings.kt
@@ -307,6 +307,14 @@ class AppSettings @Inject constructor(@ApplicationContext context: Context) {
 	val cacheRelatedTtlMinutes: Int
 		get() = prefs.getInt(KEY_CACHE_RELATED_TTL, DEFAULT_CACHE_RELATED_TTL).coerceIn(1, 120)
 
+	/**
+	 * Maximum number of parallel chapter checks during tracker updates.
+	 * Higher values = faster checking but more network load.
+	 * Default: 6, Range: 1-12
+	 */
+	val trackerParallelism: Int
+		get() = prefs.getInt(KEY_TRACKER_PARALLELISM, DEFAULT_TRACKER_PARALLELISM).coerceIn(1, 12)
+
 	val isExitConfirmationEnabled: Boolean
 		get() = prefs.getBoolean(KEY_EXIT_CONFIRM, false)
 
@@ -802,6 +810,7 @@ class AppSettings @Inject constructor(@ApplicationContext context: Context) {
 		const val KEY_CACHE_DETAILS_TTL = "cache_details_ttl"
 		const val KEY_CACHE_PAGES_TTL = "cache_pages_ttl"
 		const val KEY_CACHE_RELATED_TTL = "cache_related_ttl"
+		const val KEY_TRACKER_PARALLELISM = "tracker_parallelism"
 		const val KEY_PROXY = "proxy"
 		const val KEY_PROXY_TYPE = "proxy_type_2"
 		const val KEY_PROXY_ADDRESS = "proxy_address"
@@ -875,5 +884,8 @@ class AppSettings @Inject constructor(@ApplicationContext context: Context) {
 		const val DEFAULT_CACHE_DETAILS_TTL = 5
 		const val DEFAULT_CACHE_PAGES_TTL = 10
 		const val DEFAULT_CACHE_RELATED_TTL = 10
+
+		// tracker defaults
+		const val DEFAULT_TRACKER_PARALLELISM = 6
 	}
 }
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/tracker/domain/CheckNewChaptersUseCase.kt b/app/src/main/kotlin/org/koitharu/kotatsu/tracker/domain/CheckNewChaptersUseCase.kt
index b3dc35f..56d0485 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/tracker/domain/CheckNewChaptersUseCase.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/tracker/domain/CheckNewChaptersUseCase.kt
@@ -2,6 +2,11 @@ package org.koitharu.kotatsu.tracker.domain
 
 import android.util.Log
 import coil3.request.CachePolicy
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.channelFlow
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.sync.Semaphore
+import kotlinx.coroutines.sync.withPermit
 import org.koitharu.kotatsu.BuildConfig
 import org.koitharu.kotatsu.core.model.getPreferredBranch
 import org.koitharu.kotatsu.core.model.isLocal
@@ -44,6 +49,37 @@ class CheckNewChaptersUseCase @Inject constructor(
 		invokeImpl(track)
 	}
 
+	/**
+	 * Check multiple tracks in parallel with configurable parallelism.
+	 *
+	 * @param tracks List of manga tracks to check
+	 * @param parallelism Maximum number of concurrent checks (default: 6)
+	 * @return Flow emitting MangaUpdates for each track as they complete
+	 */
+	fun checkBatch(
+		tracks: List<MangaTracking>,
+		parallelism: Int = DEFAULT_PARALLELISM,
+	): Flow<MangaUpdates> = channelFlow {
+		val semaphore = Semaphore(parallelism.coerceIn(1, MAX_PARALLELISM))
+		for (track in tracks) {
+			launch {
+				semaphore.withPermit {
+					val result = runCatchingCancellable {
+						mutex.withLock(track.manga.id) {
+							invokeImpl(track)
+						}
+					}.getOrElse { error ->
+						MangaUpdates.Failure(
+							manga = track.manga,
+							error = error,
+						)
+					}
+					send(result)
+				}
+			}
+		}
+	}
+
 	suspend operator fun invoke(manga: Manga, currentChapterId: Long) = mutex.withLock(manga.id) {
 		runCatchingCancellable {
 			repository.updateTracks()
@@ -149,4 +185,9 @@ class CheckNewChaptersUseCase @Inject constructor(
 			}
 		}
 	}
+
+	companion object {
+		const val DEFAULT_PARALLELISM = 6
+		const val MAX_PARALLELISM = 12
+	}
 }
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/tracker/work/TrackWorker.kt b/app/src/main/kotlin/org/koitharu/kotatsu/tracker/work/TrackWorker.kt
index 5094feb..ad649dd 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/tracker/work/TrackWorker.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/tracker/work/TrackWorker.kt
@@ -32,12 +32,8 @@ import dagger.assisted.AssistedInject
 import kotlinx.coroutines.CancellationException
 import kotlinx.coroutines.NonCancellable
 import kotlinx.coroutines.flow.Flow
-import kotlinx.coroutines.flow.channelFlow
 import kotlinx.coroutines.flow.collect
 import kotlinx.coroutines.flow.map
-import kotlinx.coroutines.launch
-import kotlinx.coroutines.sync.Semaphore
-import kotlinx.coroutines.sync.withPermit
 import kotlinx.coroutines.withContext
 import org.koitharu.kotatsu.BuildConfig
 import org.koitharu.kotatsu.R
@@ -119,28 +115,12 @@ class TrackWorker @AssistedInject constructor(
 
 	@CheckResult
 	private suspend fun checkUpdatesAsync(tracks: List<MangaTracking>) {
-		val semaphore = Semaphore(MAX_PARALLELISM)
+		val parallelism = settings.trackerParallelism
 		val groupNotifications = mutableListOf<NotificationInfo>()
 
 		try {
-			channelFlow {
-				for (track in tracks) {
-					launch {
-						semaphore.withPermit {
-							send(
-								runCatchingCancellable {
-									checkNewChaptersUseCase.invoke(track)
-								}.getOrElse { error ->
-									MangaUpdates.Failure(
-										manga = track.manga,
-										error = error,
-									)
-								},
-							)
-						}
-					}
-				}
-			}.onEachIndexed { index, it ->
+			checkNewChaptersUseCase.checkBatch(tracks, parallelism)
+				.onEachIndexed { index, it ->
 				if (applicationContext.checkNotificationPermission(WORKER_CHANNEL_ID)) {
 					notificationManager.notify(
 						WORKER_NOTIFICATION_ID,
@@ -365,7 +345,6 @@ class TrackWorker @AssistedInject constructor(
 		const val WORKER_NOTIFICATION_ID = 35
 		const val TAG = "tracking"
 		const val TAG_ONESHOT = "tracking_oneshot"
-		const val MAX_PARALLELISM = 6
 		val BATCH_SIZE = if (BuildConfig.DEBUG) 20 else 46
 		const val SETTINGS_ACTION_CODE = 5
 	}

From 0c9ebd90fb2b1248179508f1c0740727838291bc Mon Sep 17 00:00:00 2001
From: AgentKush <finlayhansford66@gmail.com>
Date: Thu, 22 Jan 2026 07:01:54 +0000
Subject: [PATCH 21/35] feat: Implement Scrobbler Offline Queue (#5)

---
 .../kotatsu/history/data/HistoryRepository.kt |   7 +-
 .../common/domain/ScrobbleOfflineQueue.kt     | 180 ++++++++++++++++
 .../common/domain/ScrobbleQueueEntry.kt       |  43 ++++
 .../common/domain/ScrobbleQueueWorker.kt      | 107 ++++++++++
 .../common/domain/ScrobblingManager.kt        | 195 ++++++++++++++++++
 5 files changed, 528 insertions(+), 4 deletions(-)
 create mode 100644 app/src/main/kotlin/org/koitharu/kotatsu/scrobbling/common/domain/ScrobbleOfflineQueue.kt
 create mode 100644 app/src/main/kotlin/org/koitharu/kotatsu/scrobbling/common/domain/ScrobbleQueueEntry.kt
 create mode 100644 app/src/main/kotlin/org/koitharu/kotatsu/scrobbling/common/domain/ScrobbleQueueWorker.kt
 create mode 100644 app/src/main/kotlin/org/koitharu/kotatsu/scrobbling/common/domain/ScrobblingManager.kt

diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/history/data/HistoryRepository.kt b/app/src/main/kotlin/org/koitharu/kotatsu/history/data/HistoryRepository.kt
index 3d5f052..fecba81 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/history/data/HistoryRepository.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/history/data/HistoryRepository.kt
@@ -29,8 +29,7 @@ import org.koitharu.kotatsu.parsers.model.MangaSource
 import org.koitharu.kotatsu.parsers.model.MangaTag
 import org.koitharu.kotatsu.parsers.util.findById
 import org.koitharu.kotatsu.parsers.util.levenshteinDistance
-import org.koitharu.kotatsu.scrobbling.common.domain.Scrobbler
-import org.koitharu.kotatsu.scrobbling.common.domain.tryScrobble
+import org.koitharu.kotatsu.scrobbling.common.domain.ScrobblingManager
 import org.koitharu.kotatsu.search.domain.SearchKind
 import org.koitharu.kotatsu.tracker.domain.CheckNewChaptersUseCase
 import javax.inject.Inject
@@ -40,7 +39,7 @@ import javax.inject.Provider
 class HistoryRepository @Inject constructor(
 	private val db: MangaDatabase,
 	private val settings: AppSettings,
-	private val scrobblers: Set<@JvmSuppressWildcards Scrobbler>,
+	private val scrobblingManager: ScrobblingManager,
 	private val mangaRepository: MangaDataRepository,
 	private val localObserver: HistoryLocalObserver,
 	private val newChaptersUseCaseProvider: Provider<CheckNewChaptersUseCase>,
@@ -132,7 +131,7 @@ class HistoryRepository @Inject constructor(
 				),
 			)
 			newChaptersUseCaseProvider.get()(manga, chapterId)
-			scrobblers.forEach { it.tryScrobble(manga, chapterId) }
+			scrobblingManager.scrobble(manga, chapterId)
 		}
 	}
 
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/scrobbling/common/domain/ScrobbleOfflineQueue.kt b/app/src/main/kotlin/org/koitharu/kotatsu/scrobbling/common/domain/ScrobbleOfflineQueue.kt
new file mode 100644
index 0000000..d19cefb
--- /dev/null
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/scrobbling/common/domain/ScrobbleOfflineQueue.kt
@@ -0,0 +1,180 @@
+package org.koitharu.kotatsu.scrobbling.common.domain
+
+import android.content.Context
+import android.util.Log
+import dagger.hilt.android.qualifiers.ApplicationContext
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import org.koitharu.kotatsu.BuildConfig
+import org.koitharu.kotatsu.scrobbling.common.domain.model.ScrobblerService
+import java.util.concurrent.TimeUnit
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Manages a persistent queue of failed scrobble operations for retry when network is available.
+ *
+ * Features:
+ * - SharedPreferences persistence across app restarts
+ * - Automatic expiration of old entries (default: 7 days)
+ * - Thread-safe operations
+ * - Observable queue size
+ * - Deduplication (same manga+chapter combination)
+ */
+@Singleton
+class ScrobbleOfflineQueue @Inject constructor(
+	@ApplicationContext private val context: Context,
+) {
+
+	private val _queueSize = MutableStateFlow(0)
+	val queueSize: StateFlow<Int> = _queueSize.asStateFlow()
+
+	private val queue = mutableListOf<ScrobbleQueueEntry>()
+	private val lock = Any()
+
+	private val prefs by lazy {
+		context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+	}
+
+	init {
+		loadFromStorage()
+	}
+
+	/**
+	 * Add a scrobble operation to the queue for later retry.
+	 * Deduplicates entries with the same manga and chapter.
+	 */
+	fun enqueue(service: ScrobblerService, mangaId: Long, chapterId: Long) {
+		synchronized(lock) {
+			// Remove any existing entry for the same manga/chapter/service
+			queue.removeAll { it.scrobblerService == service && it.mangaId == mangaId && it.chapterId == chapterId }
+
+			val entry = ScrobbleQueueEntry(
+				scrobblerService = service,
+				mangaId = mangaId,
+				chapterId = chapterId,
+			)
+			queue.add(entry)
+			saveToStorage()
+			_queueSize.value = queue.size
+			logDebug { "Enqueued scrobble: ${service.name} manga=$mangaId chapter=$chapterId (queue size: ${queue.size})" }
+		}
+	}
+
+	/**
+	 * Get all pending entries for a specific scrobbler service.
+	 */
+	fun getEntriesForService(service: ScrobblerService): List<ScrobbleQueueEntry> {
+		synchronized(lock) {
+			cleanupExpired()
+			return queue.filter { it.scrobblerService == service }.toList()
+		}
+	}
+
+	/**
+	 * Get all pending entries.
+	 */
+	fun getAllEntries(): List<ScrobbleQueueEntry> {
+		synchronized(lock) {
+			cleanupExpired()
+			return queue.toList()
+		}
+	}
+
+	/**
+	 * Remove a specific entry from the queue (after successful processing).
+	 */
+	fun remove(entry: ScrobbleQueueEntry) {
+		synchronized(lock) {
+			if (queue.remove(entry)) {
+				saveToStorage()
+				_queueSize.value = queue.size
+				logDebug { "Removed scrobble from queue: ${entry.scrobblerService.name} manga=${entry.mangaId}" }
+			}
+		}
+	}
+
+	/**
+	 * Remove all entries for a specific manga (e.g., if manga is deleted).
+	 */
+	fun removeForManga(mangaId: Long) {
+		synchronized(lock) {
+			val removed = queue.removeAll { it.mangaId == mangaId }
+			if (removed) {
+				saveToStorage()
+				_queueSize.value = queue.size
+				logDebug { "Removed all scrobbles for manga=$mangaId" }
+			}
+		}
+	}
+
+	/**
+	 * Clear all pending entries.
+	 */
+	fun clear() {
+		synchronized(lock) {
+			queue.clear()
+			prefs.edit().remove(KEY_QUEUE).apply()
+			_queueSize.value = 0
+			logDebug { "Cleared scrobble queue" }
+		}
+	}
+
+	/**
+	 * Check if the queue is empty.
+	 */
+	val isEmpty: Boolean
+		get() = synchronized(lock) { queue.isEmpty() }
+
+	/**
+	 * Get the current queue size.
+	 */
+	val size: Int
+		get() = synchronized(lock) { queue.size }
+
+	private fun cleanupExpired() {
+		val now = System.currentTimeMillis()
+		val expiredBefore = now - ENTRY_TTL_MS
+		val removed = queue.removeAll { it.timestamp < expiredBefore }
+		if (removed) {
+			saveToStorage()
+			_queueSize.value = queue.size
+			logDebug { "Cleaned up expired scrobble entries" }
+		}
+	}
+
+	private fun saveToStorage() {
+		val serialized = queue.map { it.serialize() }.toSet()
+		prefs.edit().putStringSet(KEY_QUEUE, serialized).apply()
+	}
+
+	private fun loadFromStorage() {
+		val serialized = prefs.getStringSet(KEY_QUEUE, emptySet()) ?: emptySet()
+		val now = System.currentTimeMillis()
+		val expiredBefore = now - ENTRY_TTL_MS
+
+		queue.clear()
+		serialized.mapNotNull { ScrobbleQueueEntry.deserialize(it) }
+			.filter { it.timestamp >= expiredBefore }
+			.forEach { queue.add(it) }
+
+		_queueSize.value = queue.size
+		logDebug { "Loaded ${queue.size} entries from scrobble queue" }
+	}
+
+	private inline fun logDebug(message: () -> String) {
+		if (BuildConfig.DEBUG) {
+			Log.d(TAG, message())
+		}
+	}
+
+	companion object {
+		private const val TAG = "ScrobbleOfflineQueue"
+		private const val PREFS_NAME = "scrobble_offline_queue"
+		private const val KEY_QUEUE = "queue"
+
+		/** Entries expire after 7 days */
+		val ENTRY_TTL_MS = TimeUnit.DAYS.toMillis(7)
+	}
+}
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/scrobbling/common/domain/ScrobbleQueueEntry.kt b/app/src/main/kotlin/org/koitharu/kotatsu/scrobbling/common/domain/ScrobbleQueueEntry.kt
new file mode 100644
index 0000000..5bf15cc
--- /dev/null
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/scrobbling/common/domain/ScrobbleQueueEntry.kt
@@ -0,0 +1,43 @@
+package org.koitharu.kotatsu.scrobbling.common.domain
+
+import org.koitharu.kotatsu.scrobbling.common.domain.model.ScrobblerService
+
+/**
+ * Represents a pending scrobble operation that failed due to network issues
+ * and needs to be retried when connectivity is restored.
+ */
+data class ScrobbleQueueEntry(
+	val scrobblerService: ScrobblerService,
+	val mangaId: Long,
+	val chapterId: Long,
+	val timestamp: Long = System.currentTimeMillis(),
+) {
+	/**
+	 * Serialize to string for storage.
+	 * Format: "scrobblerId:mangaId:chapterId:timestamp"
+	 */
+	fun serialize(): String = "${scrobblerService.id}:$mangaId:$chapterId:$timestamp"
+
+	companion object {
+		/**
+		 * Deserialize from string.
+		 * @return ScrobbleQueueEntry or null if parsing fails
+		 */
+		fun deserialize(data: String): ScrobbleQueueEntry? {
+			val parts = data.split(":")
+			if (parts.size != 4) return null
+			return try {
+				val scrobblerId = parts[0].toInt()
+				val service = ScrobblerService.entries.find { it.id == scrobblerId } ?: return null
+				ScrobbleQueueEntry(
+					scrobblerService = service,
+					mangaId = parts[1].toLong(),
+					chapterId = parts[2].toLong(),
+					timestamp = parts[3].toLong(),
+				)
+			} catch (e: NumberFormatException) {
+				null
+			}
+		}
+	}
+}
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/scrobbling/common/domain/ScrobbleQueueWorker.kt b/app/src/main/kotlin/org/koitharu/kotatsu/scrobbling/common/domain/ScrobbleQueueWorker.kt
new file mode 100644
index 0000000..af1c86c
--- /dev/null
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/scrobbling/common/domain/ScrobbleQueueWorker.kt
@@ -0,0 +1,107 @@
+package org.koitharu.kotatsu.scrobbling.common.domain
+
+import android.content.Context
+import android.util.Log
+import androidx.hilt.work.HiltWorker
+import androidx.work.BackoffPolicy
+import androidx.work.Constraints
+import androidx.work.CoroutineWorker
+import androidx.work.ExistingWorkPolicy
+import androidx.work.NetworkType
+import androidx.work.OneTimeWorkRequestBuilder
+import androidx.work.WorkManager
+import androidx.work.WorkerParameters
+import dagger.assisted.Assisted
+import dagger.assisted.AssistedInject
+import kotlinx.coroutines.CancellationException
+import org.koitharu.kotatsu.BuildConfig
+import org.koitharu.kotatsu.core.util.ext.printStackTraceDebug
+import java.util.concurrent.TimeUnit
+
+/**
+ * Worker that processes queued scrobbles when network is available.
+ * 
+ * This worker is scheduled when:
+ * - A scrobble fails due to network issues
+ * - The app starts and there are queued scrobbles
+ * - Network connectivity is restored
+ */
+@HiltWorker
+class ScrobbleQueueWorker @AssistedInject constructor(
+	@Assisted context: Context,
+	@Assisted workerParams: WorkerParameters,
+	private val scrobblingManager: ScrobblingManager,
+	private val offlineQueue: ScrobbleOfflineQueue,
+) : CoroutineWorker(context, workerParams) {
+
+	override suspend fun doWork(): Result {
+		if (offlineQueue.isEmpty) {
+			logDebug { "Queue is empty, nothing to process" }
+			return Result.success()
+		}
+
+		return try {
+			val processed = scrobblingManager.processAllQueues()
+			logDebug { "Processed $processed queued scrobbles" }
+
+			if (offlineQueue.isEmpty) {
+				Result.success()
+			} else {
+				// Still have items, retry later
+				Result.retry()
+			}
+		} catch (e: CancellationException) {
+			throw e
+		} catch (e: Throwable) {
+			e.printStackTraceDebug()
+			Result.retry()
+		}
+	}
+
+	private inline fun logDebug(message: () -> String) {
+		if (BuildConfig.DEBUG) {
+			Log.d(TAG, message())
+		}
+	}
+
+	companion object {
+		private const val TAG = "ScrobbleQueueWorker"
+		private const val WORK_NAME = "scrobble_queue_processor"
+
+		/**
+		 * Schedule the queue processor to run when network is available.
+		 */
+		fun schedule(context: Context) {
+			val constraints = Constraints.Builder()
+				.setRequiredNetworkType(NetworkType.CONNECTED)
+				.build()
+
+			val request = OneTimeWorkRequestBuilder<ScrobbleQueueWorker>()
+				.setConstraints(constraints)
+				.setBackoffCriteria(
+					BackoffPolicy.EXPONENTIAL,
+					15,
+					TimeUnit.MINUTES,
+				)
+				.build()
+
+			WorkManager.getInstance(context)
+				.enqueueUniqueWork(
+					WORK_NAME,
+					ExistingWorkPolicy.REPLACE,
+					request,
+				)
+
+			if (BuildConfig.DEBUG) {
+				Log.d(TAG, "Scheduled queue processing")
+			}
+		}
+
+		/**
+		 * Cancel any pending queue processing.
+		 */
+		fun cancel(context: Context) {
+			WorkManager.getInstance(context).cancelUniqueWork(WORK_NAME)
+		}
+	}
+}
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/scrobbling/common/domain/ScrobblingManager.kt b/app/src/main/kotlin/org/koitharu/kotatsu/scrobbling/common/domain/ScrobblingManager.kt
new file mode 100644
index 0000000..8f4e518
--- /dev/null
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/scrobbling/common/domain/ScrobblingManager.kt
@@ -0,0 +1,195 @@
+package org.koitharu.kotatsu.scrobbling.common.domain
+
+import android.content.Context
+import android.util.Log
+import dagger.hilt.android.qualifiers.ApplicationContext
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+import org.koitharu.kotatsu.BuildConfig
+import org.koitharu.kotatsu.core.db.MangaDatabase
+import org.koitharu.kotatsu.core.db.entity.toManga
+import org.koitharu.kotatsu.core.os.NetworkState
+import org.koitharu.kotatsu.parsers.model.Manga
+import org.koitharu.kotatsu.parsers.util.runCatchingCancellable
+import org.koitharu.kotatsu.scrobbling.common.domain.model.ScrobblerService
+import java.io.IOException
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Manager for scrobbling operations with offline queue support.
+ *
+ * Features:
+ * - Automatic queueing when offline or on network failure
+ * - Processes queued scrobbles when network is available
+ * - Works with all scrobbler services
+ */
+@Singleton
+class ScrobblingManager @Inject constructor(
+	@ApplicationContext private val context: Context,
+	private val scrobblers: Set<@JvmSuppressWildcards Scrobbler>,
+	private val offlineQueue: ScrobbleOfflineQueue,
+	private val networkState: NetworkState,
+	private val db: MangaDatabase,
+) {
+
+	init {
+		// Schedule queue processing on startup if there are pending scrobbles
+		if (!offlineQueue.isEmpty) {
+			ScrobbleQueueWorker.schedule(context)
+		}
+	}
+
+	/**
+	 * Scrobble a chapter read, queueing for later if offline or on failure.
+	 *
+	 * @param manga The manga being read
+	 * @param chapterId The chapter that was read
+	 * @return true if scrobbled immediately, false if queued for later
+	 */
+	suspend fun scrobble(manga: Manga, chapterId: Long): Boolean {
+		val enabledScrobblers = scrobblers.filter { it.isEnabled }
+		if (enabledScrobblers.isEmpty()) {
+			return true // Nothing to do
+		}
+
+		var allSucceeded = true
+		for (scrobbler in enabledScrobblers) {
+			val success = tryScrobbleWithQueue(scrobbler, manga, chapterId)
+			if (!success) allSucceeded = false
+		}
+		return allSucceeded
+	}
+
+	/**
+	 * Process all queued scrobbles for a specific service.
+	 *
+	 * @return Number of successfully processed entries
+	 */
+	suspend fun processQueue(service: ScrobblerService): Int = withContext(Dispatchers.IO) {
+		if (!networkState.value) {
+			logDebug { "Skipping queue processing - offline" }
+			return@withContext 0
+		}
+
+		val scrobbler = scrobblers.find { it.scrobblerService == service }
+		if (scrobbler == null || !scrobbler.isEnabled) {
+			logDebug { "Skipping queue processing - scrobbler not enabled: ${service.name}" }
+			return@withContext 0
+		}
+
+		val entries = offlineQueue.getEntriesForService(service)
+		if (entries.isEmpty()) {
+			return@withContext 0
+		}
+
+		logDebug { "Processing ${entries.size} queued scrobbles for ${service.name}" }
+		var successCount = 0
+
+		for (entry in entries) {
+			val result = runCatchingCancellable {
+				// We need to get the manga from the database for scrobbling
+				processQueueEntry(scrobbler, entry.mangaId, entry.chapterId)
+			}
+
+			if (result.isSuccess) {
+				offlineQueue.remove(entry)
+				successCount++
+				logDebug { "Successfully processed queued scrobble: manga=${entry.mangaId}" }
+			} else {
+				val error = result.exceptionOrNull()
+				if (error !is IOException) {
+					// Non-network error, remove from queue to avoid infinite retries
+					offlineQueue.remove(entry)
+					logDebug { "Removed failed scrobble (non-network error): ${error?.message}" }
+				} else {
+					logDebug { "Will retry scrobble later: ${error.message}" }
+				}
+			}
+		}
+
+		return@withContext successCount
+	}
+
+	/**
+	 * Process all queued scrobbles for all services.
+	 *
+	 * @return Total number of successfully processed entries
+	 */
+	suspend fun processAllQueues(): Int {
+		var total = 0
+		for (service in ScrobblerService.entries) {
+			total += processQueue(service)
+		}
+		return total
+	}
+
+	/**
+	 * Get the scrobbler for a specific service.
+	 */
+	fun getScrobbler(service: ScrobblerService): Scrobbler? {
+		return scrobblers.find { it.scrobblerService == service }
+	}
+
+	private suspend fun tryScrobbleWithQueue(
+		scrobbler: Scrobbler,
+		manga: Manga,
+		chapterId: Long,
+	): Boolean {
+		// If offline, queue immediately
+		if (!networkState.value) {
+			offlineQueue.enqueue(scrobbler.scrobblerService, manga.id, chapterId)
+			ScrobbleQueueWorker.schedule(context)
+			logDebug { "Offline - queued scrobble: ${scrobbler.scrobblerService.name} manga=${manga.id}" }
+			return false
+		}
+
+		// Try to scrobble
+		val result = runCatchingCancellable {
+			scrobbler.scrobble(manga, chapterId)
+		}
+
+		return if (result.isSuccess) {
+			true
+		} else {
+			val error = result.exceptionOrNull()
+			// Queue on network errors
+			if (error is IOException) {
+				offlineQueue.enqueue(scrobbler.scrobblerService, manga.id, chapterId)
+				ScrobbleQueueWorker.schedule(context)
+				logDebug { "Network error - queued scrobble: ${error.message}" }
+			} else {
+				// Log non-network errors but don't queue
+				logDebug { "Scrobble failed (not queuing): ${error?.message}" }
+			}
+			false
+		}
+	}
+
+	/**
+	 * Process a queued scrobble entry by loading manga from database and calling scrobble.
+	 */
+	private suspend fun processQueueEntry(scrobbler: Scrobbler, mangaId: Long, chapterId: Long) {
+		// Verify scrobbling entity exists
+		db.getScrobblingDao().find(scrobbler.scrobblerService.id, mangaId)
+			?: throw IllegalStateException("No scrobbling entity found for manga $mangaId")
+
+		// Get manga from database
+		val mangaWithTags = db.getMangaDao().find(mangaId)
+			?: throw IllegalStateException("Manga $mangaId not found in database")
+
+		// Convert to domain model and scrobble
+		val manga = mangaWithTags.toManga()
+		scrobbler.scrobble(manga, chapterId)
+	}
+
+	private inline fun logDebug(message: () -> String) {
+		if (BuildConfig.DEBUG) {
+			Log.d(TAG, message())
+		}
+	}
+
+	companion object {
+		private const val TAG = "ScrobblingManager"
+	}
+}

From f2f81903f6c931ac4e3d0a96c8c964e42d13ad1a Mon Sep 17 00:00:00 2001
From: AgentKush <finlayhansford66@gmail.com>
Date: Thu, 22 Jan 2026 07:06:02 +0000
Subject: [PATCH 22/35] feat: Implement Network Quality Adaptive Behavior (#6)

- Add NetworkQuality enum for quality levels (OFFLINE/POOR/MODERATE/GOOD/EXCELLENT)
- Add NetworkQualityMonitor for real-time network assessment
  - Monitors WiFi/cellular/ethernet connections
  - Tracks bandwidth via download samples
  - Measures latency periodically
  - Detects cellular network types (2G/3G/4G/5G)
- Add AdaptiveNetworkSettings for dynamic configuration
  - Adaptive timeouts based on network quality
  - Concurrent download limits
  - Preload page counts
  - Image quality reduction settings
  - Retry counts and delays
- Add BandwidthTrackingInterceptor for OkHttp
  - Tracks download speeds automatically
  - Reports to NetworkQualityMonitor for assessment
- Update NetworkState with transport type helpers
  - isWifi(), isCellular(), getTransportType()
- Integrate BandwidthTrackingInterceptor into MangaHttpClient

Features:
- Real-time network quality assessment
- Automatic bandwidth estimation from downloads
- Adaptive timeouts (10s-30s connect, 30s-90s read)
- Dynamic concurrent download limits (0-6)
- Preload page count adaptation (0-5)
- Observable network quality state
---
 .../core/network/AdaptiveNetworkSettings.kt   | 199 +++++++++
 .../network/BandwidthTrackingInterceptor.kt   |  99 ++++
 .../kotatsu/core/network/NetworkModule.kt     |   2 +
 .../kotatsu/core/network/NetworkQuality.kt    |  42 ++
 .../core/network/NetworkQualityMonitor.kt     | 422 ++++++++++++++++++
 .../koitharu/kotatsu/core/os/NetworkState.kt  |  33 ++
 6 files changed, 797 insertions(+)
 create mode 100644 app/src/main/kotlin/org/koitharu/kotatsu/core/network/AdaptiveNetworkSettings.kt
 create mode 100644 app/src/main/kotlin/org/koitharu/kotatsu/core/network/BandwidthTrackingInterceptor.kt
 create mode 100644 app/src/main/kotlin/org/koitharu/kotatsu/core/network/NetworkQuality.kt
 create mode 100644 app/src/main/kotlin/org/koitharu/kotatsu/core/network/NetworkQualityMonitor.kt

diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/network/AdaptiveNetworkSettings.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/AdaptiveNetworkSettings.kt
new file mode 100644
index 0000000..0ed36e2
--- /dev/null
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/AdaptiveNetworkSettings.kt
@@ -0,0 +1,199 @@
+package org.koitharu.kotatsu.core.network
+
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.map
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Provides adaptive network settings based on current network quality.
+ * Use this class to get dynamic settings that adjust to network conditions.
+ */
+@Singleton
+class AdaptiveNetworkSettings @Inject constructor(
+	private val networkQualityMonitor: NetworkQualityMonitor,
+) {
+	/**
+	 * Current network quality level.
+	 */
+	val quality: Flow<NetworkQuality>
+		get() = networkQualityMonitor.quality
+
+	/**
+	 * Current quality value (for synchronous access).
+	 */
+	val currentQuality: NetworkQuality
+		get() = networkQualityMonitor.quality.value
+
+	/**
+	 * Observable settings that update when network quality changes.
+	 */
+	val adaptiveSettings: Flow<Settings> = networkQualityMonitor.quality.map { quality ->
+		Settings(
+			quality = quality,
+			connectTimeoutMs = getConnectTimeout(quality),
+			readTimeoutMs = getReadTimeout(quality),
+			writeTimeoutMs = getWriteTimeout(quality),
+			maxConcurrentDownloads = getMaxConcurrentDownloads(quality),
+			preloadPageCount = getPreloadPageCount(quality),
+			imageQualityReduction = getImageQualityReduction(quality),
+			retryCount = getRetryCount(quality),
+			retryDelayMs = getRetryDelay(quality),
+			enableAggressiveCache = shouldEnableAggressiveCache(quality),
+		)
+	}
+
+	/**
+	 * Get current settings snapshot.
+	 */
+	fun getCurrentSettings(): Settings {
+		val quality = currentQuality
+		return Settings(
+			quality = quality,
+			connectTimeoutMs = getConnectTimeout(quality),
+			readTimeoutMs = getReadTimeout(quality),
+			writeTimeoutMs = getWriteTimeout(quality),
+			maxConcurrentDownloads = getMaxConcurrentDownloads(quality),
+			preloadPageCount = getPreloadPageCount(quality),
+			imageQualityReduction = getImageQualityReduction(quality),
+			retryCount = getRetryCount(quality),
+			retryDelayMs = getRetryDelay(quality),
+			enableAggressiveCache = shouldEnableAggressiveCache(quality),
+		)
+	}
+
+	/**
+	 * Report a successful download for bandwidth estimation.
+	 */
+	fun reportDownload(bytes: Long, durationMs: Long) {
+		networkQualityMonitor.reportDownload(bytes, durationMs)
+	}
+
+	private fun getConnectTimeout(quality: NetworkQuality): Long {
+		return when (quality) {
+			NetworkQuality.EXCELLENT -> 10_000L
+			NetworkQuality.GOOD -> 15_000L
+			NetworkQuality.MODERATE -> 20_000L
+			NetworkQuality.POOR -> 30_000L
+			NetworkQuality.OFFLINE -> 15_000L
+		}
+	}
+
+	private fun getReadTimeout(quality: NetworkQuality): Long {
+		return when (quality) {
+			NetworkQuality.EXCELLENT -> 30_000L
+			NetworkQuality.GOOD -> 45_000L
+			NetworkQuality.MODERATE -> 60_000L
+			NetworkQuality.POOR -> 90_000L
+			NetworkQuality.OFFLINE -> 60_000L
+		}
+	}
+
+	private fun getWriteTimeout(quality: NetworkQuality): Long {
+		return when (quality) {
+			NetworkQuality.EXCELLENT -> 15_000L
+			NetworkQuality.GOOD -> 20_000L
+			NetworkQuality.MODERATE -> 25_000L
+			NetworkQuality.POOR -> 40_000L
+			NetworkQuality.OFFLINE -> 20_000L
+		}
+	}
+
+	private fun getMaxConcurrentDownloads(quality: NetworkQuality): Int {
+		return when (quality) {
+			NetworkQuality.EXCELLENT -> 6
+			NetworkQuality.GOOD -> 4
+			NetworkQuality.MODERATE -> 2
+			NetworkQuality.POOR -> 1
+			NetworkQuality.OFFLINE -> 0
+		}
+	}
+
+	private fun getPreloadPageCount(quality: NetworkQuality): Int {
+		return when (quality) {
+			NetworkQuality.EXCELLENT -> 5
+			NetworkQuality.GOOD -> 3
+			NetworkQuality.MODERATE -> 1
+			NetworkQuality.POOR -> 0
+			NetworkQuality.OFFLINE -> 0
+		}
+	}
+
+	/**
+	 * Returns image quality reduction factor (0-100).
+	 * 0 = full quality, 100 = maximum reduction
+	 */
+	private fun getImageQualityReduction(quality: NetworkQuality): Int {
+		return when (quality) {
+			NetworkQuality.EXCELLENT -> 0
+			NetworkQuality.GOOD -> 0
+			NetworkQuality.MODERATE -> 20
+			NetworkQuality.POOR -> 40
+			NetworkQuality.OFFLINE -> 0
+		}
+	}
+
+	private fun getRetryCount(quality: NetworkQuality): Int {
+		return when (quality) {
+			NetworkQuality.EXCELLENT -> 2
+			NetworkQuality.GOOD -> 3
+			NetworkQuality.MODERATE -> 4
+			NetworkQuality.POOR -> 5
+			NetworkQuality.OFFLINE -> 3
+		}
+	}
+
+	private fun getRetryDelay(quality: NetworkQuality): Long {
+		return when (quality) {
+			NetworkQuality.EXCELLENT -> 500L
+			NetworkQuality.GOOD -> 1_000L
+			NetworkQuality.MODERATE -> 2_000L
+			NetworkQuality.POOR -> 4_000L
+			NetworkQuality.OFFLINE -> 1_000L
+		}
+	}
+
+	private fun shouldEnableAggressiveCache(quality: NetworkQuality): Boolean {
+		return when (quality) {
+			NetworkQuality.EXCELLENT -> false
+			NetworkQuality.GOOD -> false
+			NetworkQuality.MODERATE -> true
+			NetworkQuality.POOR -> true
+			NetworkQuality.OFFLINE -> true
+		}
+	}
+
+	/**
+	 * Adaptive network settings snapshot.
+	 */
+	data class Settings(
+		val quality: NetworkQuality,
+		val connectTimeoutMs: Long,
+		val readTimeoutMs: Long,
+		val writeTimeoutMs: Long,
+		val maxConcurrentDownloads: Int,
+		val preloadPageCount: Int,
+		val imageQualityReduction: Int,
+		val retryCount: Int,
+		val retryDelayMs: Long,
+		val enableAggressiveCache: Boolean,
+	) {
+		/**
+		 * Check if downloads should be allowed.
+		 */
+		val allowsDownloads: Boolean
+			get() = quality.isConnected
+
+		/**
+		 * Check if preloading is recommended.
+		 */
+		val allowsPreloading: Boolean
+			get() = quality.allowsPreloading
+
+		/**
+		 * Check if high quality images should be used.
+		 */
+		val allowsHighQuality: Boolean
+			get() = quality.allowsHighQuality
+	}
+}
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/network/BandwidthTrackingInterceptor.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/BandwidthTrackingInterceptor.kt
new file mode 100644
index 0000000..1dae09b
--- /dev/null
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/BandwidthTrackingInterceptor.kt
@@ -0,0 +1,99 @@
+package org.koitharu.kotatsu.core.network
+
+import okhttp3.Interceptor
+import okhttp3.Response
+import okhttp3.ResponseBody.Companion.asResponseBody
+import okio.Buffer
+import okio.ForwardingSource
+import okio.Source
+import okio.buffer
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Interceptor that tracks download speed and reports it to NetworkQualityMonitor.
+ * This allows the app to adapt to current network conditions.
+ */
+@Singleton
+class BandwidthTrackingInterceptor @Inject constructor(
+	private val networkQualityMonitor: NetworkQualityMonitor,
+) : Interceptor {
+
+	override fun intercept(chain: Interceptor.Chain): Response {
+		val request = chain.request()
+		val startTime = System.currentTimeMillis()
+
+		val response = chain.proceed(request)
+
+		// Only track successful responses with body
+		val body = response.body
+		if (!response.isSuccessful || body == null) {
+			return response
+		}
+
+		// Wrap the response body to track download progress
+		val contentLength = body.contentLength()
+		val trackingSource = TrackingSource(
+			source = body.source(),
+			contentLength = contentLength,
+			startTime = startTime,
+			onComplete = { bytes, durationMs ->
+				if (bytes > MIN_BYTES_TO_TRACK && durationMs > MIN_DURATION_MS) {
+					networkQualityMonitor.reportDownload(bytes, durationMs)
+				}
+			},
+		)
+
+		val trackingBody = trackingSource.buffer().asResponseBody(body.contentType(), contentLength)
+		return response.newBuilder()
+			.body(trackingBody)
+			.build()
+	}
+
+	/**
+	 * Source that tracks bytes read and reports bandwidth when complete.
+	 */
+	private class TrackingSource(
+		source: Source,
+		private val contentLength: Long,
+		private val startTime: Long,
+		private val onComplete: (bytes: Long, durationMs: Long) -> Unit,
+	) : ForwardingSource(source) {
+
+		private var totalBytesRead = 0L
+		private var reported = false
+
+		override fun read(sink: Buffer, byteCount: Long): Long {
+			val bytesRead = super.read(sink, byteCount)
+
+			if (bytesRead != -1L) {
+				totalBytesRead += bytesRead
+			}
+
+			// Report when complete
+			if (!reported && (bytesRead == -1L || (contentLength > 0 && totalBytesRead >= contentLength))) {
+				reported = true
+				val duration = System.currentTimeMillis() - startTime
+				onComplete(totalBytesRead, duration)
+			}
+
+			return bytesRead
+		}
+
+		override fun close() {
+			// Report on close if not already reported
+			if (!reported && totalBytesRead > 0) {
+				reported = true
+				val duration = System.currentTimeMillis() - startTime
+				onComplete(totalBytesRead, duration)
+			}
+			super.close()
+		}
+	}
+
+	companion object {
+		// Minimum thresholds for tracking to avoid noise from small requests
+		private const val MIN_BYTES_TO_TRACK = 10_000L // 10KB
+		private const val MIN_DURATION_MS = 50L // 50ms
+	}
+}
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/network/NetworkModule.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/NetworkModule.kt
index 6c64603..26a7436 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/network/NetworkModule.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/NetworkModule.kt
@@ -93,9 +93,11 @@ interface NetworkModule {
 		fun provideMangaHttpClient(
 			@BaseHttpClient baseClient: OkHttpClient,
 			commonHeadersInterceptor: CommonHeadersInterceptor,
+			bandwidthTrackingInterceptor: BandwidthTrackingInterceptor,
 		): OkHttpClient = baseClient.newBuilder().apply {
 			addNetworkInterceptor(CacheLimitInterceptor())
 			addInterceptor(commonHeadersInterceptor)
+			addNetworkInterceptor(bandwidthTrackingInterceptor)
 		}.build()
 
 	}
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/network/NetworkQuality.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/NetworkQuality.kt
new file mode 100644
index 0000000..c46f700
--- /dev/null
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/NetworkQuality.kt
@@ -0,0 +1,42 @@
+package org.koitharu.kotatsu.core.network
+
+/**
+ * Represents the current network quality level.
+ * Used for adaptive behavior decisions throughout the app.
+ */
+enum class NetworkQuality(
+	val level: Int,
+) {
+	/** No network connection */
+	OFFLINE(0),
+	
+	/** Very slow connection - minimize data usage */
+	POOR(1),
+	
+	/** Limited bandwidth - reduce quality/preloading */
+	MODERATE(2),
+	
+	/** Good connection - normal operation */
+	GOOD(3),
+	
+	/** Excellent connection - enable aggressive preloading */
+	EXCELLENT(4);
+
+	val isConnected: Boolean
+		get() = this != OFFLINE
+
+	val allowsPreloading: Boolean
+		get() = level >= GOOD.level
+
+	val allowsHighQuality: Boolean
+		get() = level >= MODERATE.level
+
+	val allowsAggressivePreloading: Boolean
+		get() = level >= EXCELLENT.level
+
+	companion object {
+		fun fromLevel(level: Int): NetworkQuality {
+			return entries.find { it.level == level } ?: OFFLINE
+		}
+	}
+}
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/network/NetworkQualityMonitor.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/NetworkQualityMonitor.kt
new file mode 100644
index 0000000..c64e9e6
--- /dev/null
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/NetworkQualityMonitor.kt
@@ -0,0 +1,422 @@
+package org.koitharu.kotatsu.core.network
+
+import android.content.Context
+import android.net.ConnectivityManager
+import android.net.Network
+import android.net.NetworkCapabilities
+import android.net.NetworkRequest
+import android.os.Build
+import android.telephony.TelephonyManager
+import android.util.Log
+import dagger.hilt.android.qualifiers.ApplicationContext
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.isActive
+import kotlinx.coroutines.launch
+import org.koitharu.kotatsu.BuildConfig
+import org.koitharu.kotatsu.core.util.ext.connectivityManager
+import java.io.IOException
+import java.net.HttpURLConnection
+import java.net.URL
+import java.util.concurrent.atomic.AtomicLong
+import javax.inject.Inject
+import javax.inject.Singleton
+import kotlin.math.roundToInt
+
+/**
+ * Monitors network quality and provides adaptive behavior recommendations.
+ *
+ * Features:
+ * - Real-time network quality assessment
+ * - Bandwidth estimation based on recent downloads
+ * - Latency tracking
+ * - Cellular network type detection (2G/3G/4G/5G)
+ * - Observable network quality state
+ */
+@Singleton
+class NetworkQualityMonitor @Inject constructor(
+	@ApplicationContext private val context: Context,
+) {
+	private val scope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
+	private val connectivityManager = context.connectivityManager
+
+	private val _quality = MutableStateFlow(NetworkQuality.GOOD)
+	val quality: StateFlow<NetworkQuality> = _quality.asStateFlow()
+
+	private val _bandwidthKbps = MutableStateFlow(0)
+	val bandwidthKbps: StateFlow<Int> = _bandwidthKbps.asStateFlow()
+
+	private val _latencyMs = MutableStateFlow(0L)
+	val latencyMs: StateFlow<Long> = _latencyMs.asStateFlow()
+
+	// Sliding window for bandwidth samples
+	private val bandwidthSamples = mutableListOf<Int>()
+	private val maxSamples = 10
+
+	// For tracking download speeds
+	private val bytesDownloaded = AtomicLong(0L)
+	private val downloadStartTime = AtomicLong(0L)
+
+	private var isMonitoring = false
+	private val callback = NetworkCallbackImpl()
+
+	init {
+		startMonitoring()
+	}
+
+	/**
+	 * Start monitoring network quality.
+	 */
+	@Synchronized
+	fun startMonitoring() {
+		if (isMonitoring) return
+		isMonitoring = true
+
+		val request = NetworkRequest.Builder()
+			.addTransportType(NetworkCapabilities.TRANSPORT_WIFI)
+			.addTransportType(NetworkCapabilities.TRANSPORT_CELLULAR)
+			.addTransportType(NetworkCapabilities.TRANSPORT_ETHERNET)
+			.addTransportType(NetworkCapabilities.TRANSPORT_VPN)
+			.build()
+
+		try {
+			connectivityManager.registerNetworkCallback(request, callback)
+		} catch (e: Exception) {
+			logDebug { "Failed to register network callback: ${e.message}" }
+		}
+
+		// Initial assessment
+		assessNetworkQuality()
+
+		// Periodic latency checks
+		scope.launch {
+			while (isActive) {
+				measureLatency()
+				delay(LATENCY_CHECK_INTERVAL_MS)
+			}
+		}
+	}
+
+	/**
+	 * Stop monitoring network quality.
+	 */
+	@Synchronized
+	fun stopMonitoring() {
+		if (!isMonitoring) return
+		isMonitoring = false
+
+		try {
+			connectivityManager.unregisterNetworkCallback(callback)
+		} catch (e: Exception) {
+			logDebug { "Failed to unregister network callback: ${e.message}" }
+		}
+	}
+
+	/**
+	 * Report bytes downloaded to help estimate bandwidth.
+	 * Call this when downloading images, pages, or other content.
+	 */
+	fun reportDownload(bytes: Long, durationMs: Long) {
+		if (durationMs <= 0 || bytes <= 0) return
+
+		val kbps = ((bytes * 8 * 1000) / (durationMs * 1024)).toInt()
+		addBandwidthSample(kbps)
+
+		logDebug { "Download reported: ${bytes}B in ${durationMs}ms = ${kbps}kbps" }
+	}
+
+	/**
+	 * Start tracking a download.
+	 */
+	fun startDownloadTracking() {
+		downloadStartTime.set(System.currentTimeMillis())
+		bytesDownloaded.set(0)
+	}
+
+	/**
+	 * Add bytes to the current download tracking.
+	 */
+	fun addDownloadedBytes(bytes: Long) {
+		bytesDownloaded.addAndGet(bytes)
+	}
+
+	/**
+	 * End tracking and report the download.
+	 */
+	fun endDownloadTracking() {
+		val start = downloadStartTime.getAndSet(0)
+		val bytes = bytesDownloaded.getAndSet(0)
+		if (start > 0 && bytes > 0) {
+			val duration = System.currentTimeMillis() - start
+			reportDownload(bytes, duration)
+		}
+	}
+
+	/**
+	 * Get recommended concurrent connection limit based on network quality.
+	 */
+	fun getRecommendedConcurrency(): Int {
+		return when (_quality.value) {
+			NetworkQuality.EXCELLENT -> 6
+			NetworkQuality.GOOD -> 4
+			NetworkQuality.MODERATE -> 2
+			NetworkQuality.POOR -> 1
+			NetworkQuality.OFFLINE -> 0
+		}
+	}
+
+	/**
+	 * Get recommended timeout multiplier based on network quality.
+	 */
+	fun getTimeoutMultiplier(): Float {
+		return when (_quality.value) {
+			NetworkQuality.EXCELLENT -> 0.8f
+			NetworkQuality.GOOD -> 1.0f
+			NetworkQuality.MODERATE -> 1.5f
+			NetworkQuality.POOR -> 2.5f
+			NetworkQuality.OFFLINE -> 1.0f
+		}
+	}
+
+	/**
+	 * Check if preloading should be enabled.
+	 */
+	fun shouldPreload(): Boolean {
+		return _quality.value.allowsPreloading
+	}
+
+	/**
+	 * Check if high quality images should be used.
+	 */
+	fun shouldUseHighQuality(): Boolean {
+		return _quality.value.allowsHighQuality
+	}
+
+	/**
+	 * Get the number of pages to preload based on network quality.
+	 */
+	fun getPreloadPageCount(): Int {
+		return when (_quality.value) {
+			NetworkQuality.EXCELLENT -> 5
+			NetworkQuality.GOOD -> 3
+			NetworkQuality.MODERATE -> 1
+			NetworkQuality.POOR -> 0
+			NetworkQuality.OFFLINE -> 0
+		}
+	}
+
+	private fun assessNetworkQuality() {
+		val network = connectivityManager.activeNetwork
+		if (network == null) {
+			_quality.value = NetworkQuality.OFFLINE
+			return
+		}
+
+		val capabilities = connectivityManager.getNetworkCapabilities(network)
+		if (capabilities == null) {
+			_quality.value = NetworkQuality.OFFLINE
+			return
+		}
+
+		// Determine base quality from network type and capabilities
+		val baseQuality = assessBaseQuality(capabilities)
+
+		// Adjust based on measured bandwidth if available
+		val avgBandwidth = getAverageBandwidth()
+		val bandwidthQuality = when {
+			avgBandwidth <= 0 -> baseQuality
+			avgBandwidth < 256 -> NetworkQuality.POOR
+			avgBandwidth < 1024 -> NetworkQuality.MODERATE
+			avgBandwidth < 5120 -> NetworkQuality.GOOD
+			else -> NetworkQuality.EXCELLENT
+		}
+
+		// Adjust based on latency if available
+		val latency = _latencyMs.value
+		val latencyQuality = when {
+			latency <= 0 -> baseQuality
+			latency > 1000 -> NetworkQuality.POOR
+			latency > 500 -> NetworkQuality.MODERATE
+			latency > 200 -> NetworkQuality.GOOD
+			else -> NetworkQuality.EXCELLENT
+		}
+
+		// Use the lowest quality assessment
+		val finalQuality = minOf(baseQuality, bandwidthQuality, latencyQuality, compareBy { it.level })
+		_quality.value = finalQuality
+
+		logDebug { "Network quality assessed: $finalQuality (base=$baseQuality, bw=$bandwidthQuality, lat=$latencyQuality)" }
+	}
+
+	private fun assessBaseQuality(capabilities: NetworkCapabilities): NetworkQuality {
+		// Check for validated internet
+		if (!capabilities.hasCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET)) {
+			return NetworkQuality.OFFLINE
+		}
+
+		// Check transport type
+		return when {
+			capabilities.hasTransport(NetworkCapabilities.TRANSPORT_WIFI) -> {
+				assessWifiQuality(capabilities)
+			}
+			capabilities.hasTransport(NetworkCapabilities.TRANSPORT_ETHERNET) -> {
+				NetworkQuality.EXCELLENT
+			}
+			capabilities.hasTransport(NetworkCapabilities.TRANSPORT_CELLULAR) -> {
+				assessCellularQuality(capabilities)
+			}
+			capabilities.hasTransport(NetworkCapabilities.TRANSPORT_VPN) -> {
+				// VPN quality depends on underlying network
+				NetworkQuality.GOOD
+			}
+			else -> NetworkQuality.MODERATE
+		}
+	}
+
+	private fun assessWifiQuality(capabilities: NetworkCapabilities): NetworkQuality {
+		if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
+			val downstreamBandwidth = capabilities.linkDownstreamBandwidthKbps
+			val upstreamBandwidth = capabilities.linkUpstreamBandwidthKbps
+
+			return when {
+				downstreamBandwidth >= 50000 -> NetworkQuality.EXCELLENT
+				downstreamBandwidth >= 10000 -> NetworkQuality.GOOD
+				downstreamBandwidth >= 1000 -> NetworkQuality.MODERATE
+				downstreamBandwidth > 0 -> NetworkQuality.POOR
+				else -> NetworkQuality.GOOD // Unknown, assume good
+			}
+		}
+		return NetworkQuality.GOOD
+	}
+
+	private fun assessCellularQuality(capabilities: NetworkCapabilities): NetworkQuality {
+		// Try to get bandwidth info from capabilities
+		if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
+			val downstreamBandwidth = capabilities.linkDownstreamBandwidthKbps
+
+			return when {
+				downstreamBandwidth >= 20000 -> NetworkQuality.EXCELLENT // 5G/LTE
+				downstreamBandwidth >= 5000 -> NetworkQuality.GOOD // LTE
+				downstreamBandwidth >= 1000 -> NetworkQuality.MODERATE // 3G
+				downstreamBandwidth > 0 -> NetworkQuality.POOR // 2G
+				else -> assessCellularByTelephony()
+			}
+		}
+		return assessCellularByTelephony()
+	}
+
+	private fun assessCellularByTelephony(): NetworkQuality {
+		val telephonyManager = context.getSystemService(Context.TELEPHONY_SERVICE) as? TelephonyManager
+			?: return NetworkQuality.MODERATE
+
+		return try {
+			when (telephonyManager.dataNetworkType) {
+				TelephonyManager.NETWORK_TYPE_NR -> NetworkQuality.EXCELLENT // 5G
+				TelephonyManager.NETWORK_TYPE_LTE -> NetworkQuality.GOOD
+				TelephonyManager.NETWORK_TYPE_HSPAP,
+				TelephonyManager.NETWORK_TYPE_HSPA,
+				TelephonyManager.NETWORK_TYPE_HSDPA,
+				TelephonyManager.NETWORK_TYPE_HSUPA -> NetworkQuality.MODERATE
+				TelephonyManager.NETWORK_TYPE_UMTS,
+				TelephonyManager.NETWORK_TYPE_EVDO_0,
+				TelephonyManager.NETWORK_TYPE_EVDO_A,
+				TelephonyManager.NETWORK_TYPE_EVDO_B -> NetworkQuality.MODERATE
+				TelephonyManager.NETWORK_TYPE_EDGE,
+				TelephonyManager.NETWORK_TYPE_GPRS,
+				TelephonyManager.NETWORK_TYPE_CDMA,
+				TelephonyManager.NETWORK_TYPE_1xRTT -> NetworkQuality.POOR
+				else -> NetworkQuality.MODERATE
+			}
+		} catch (e: SecurityException) {
+			NetworkQuality.MODERATE
+		}
+	}
+
+	private fun addBandwidthSample(kbps: Int) {
+		synchronized(bandwidthSamples) {
+			bandwidthSamples.add(kbps)
+			while (bandwidthSamples.size > maxSamples) {
+				bandwidthSamples.removeAt(0)
+			}
+			_bandwidthKbps.value = getAverageBandwidth()
+		}
+		assessNetworkQuality()
+	}
+
+	private fun getAverageBandwidth(): Int {
+		synchronized(bandwidthSamples) {
+			if (bandwidthSamples.isEmpty()) return 0
+			return bandwidthSamples.average().roundToInt()
+		}
+	}
+
+	private suspend fun measureLatency() {
+		if (!isMonitoring) return
+
+		try {
+			val startTime = System.currentTimeMillis()
+			val url = URL(LATENCY_TEST_URL)
+			val connection = url.openConnection() as HttpURLConnection
+			connection.connectTimeout = 5000
+			connection.readTimeout = 5000
+			connection.requestMethod = "HEAD"
+
+			try {
+				connection.connect()
+				val latency = System.currentTimeMillis() - startTime
+				_latencyMs.value = latency
+				logDebug { "Latency measured: ${latency}ms" }
+				assessNetworkQuality()
+			} finally {
+				connection.disconnect()
+			}
+		} catch (e: IOException) {
+			logDebug { "Latency measurement failed: ${e.message}" }
+			// Keep the last known latency
+		} catch (e: Exception) {
+			logDebug { "Latency measurement error: ${e.message}" }
+		}
+	}
+
+	private fun <T : Comparable<T>> minOf(a: T, b: T, c: T, comparator: Comparator<T>): T {
+		var min = a
+		if (comparator.compare(b, min) < 0) min = b
+		if (comparator.compare(c, min) < 0) min = c
+		return min
+	}
+
+	private inner class NetworkCallbackImpl : ConnectivityManager.NetworkCallback() {
+		override fun onAvailable(network: Network) {
+			assessNetworkQuality()
+		}
+
+		override fun onLost(network: Network) {
+			_quality.value = NetworkQuality.OFFLINE
+		}
+
+		override fun onCapabilitiesChanged(network: Network, capabilities: NetworkCapabilities) {
+			assessNetworkQuality()
+		}
+
+		override fun onUnavailable() {
+			_quality.value = NetworkQuality.OFFLINE
+		}
+	}
+
+	private inline fun logDebug(message: () -> String) {
+		if (BuildConfig.DEBUG) {
+			Log.d(TAG, message())
+		}
+	}
+
+	companion object {
+		private const val TAG = "NetworkQualityMonitor"
+		private const val LATENCY_CHECK_INTERVAL_MS = 60_000L // 1 minute
+		private const val LATENCY_TEST_URL = "https://www.google.com/generate_204"
+	}
+}
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/os/NetworkState.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/os/NetworkState.kt
index 6bef33c..f418623 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/os/NetworkState.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/os/NetworkState.kt
@@ -54,6 +54,39 @@ class NetworkState(
 
 	fun isOfflineOrRestricted() = !isOnline() || isRestricted()
 
+	/**
+	 * Check if currently connected via WiFi.
+	 */
+	fun isWifi(): Boolean {
+		val network = connectivityManager.activeNetwork ?: return false
+		val capabilities = connectivityManager.getNetworkCapabilities(network) ?: return false
+		return capabilities.hasTransport(NetworkCapabilities.TRANSPORT_WIFI)
+	}
+
+	/**
+	 * Check if currently connected via cellular.
+	 */
+	fun isCellular(): Boolean {
+		val network = connectivityManager.activeNetwork ?: return false
+		val capabilities = connectivityManager.getNetworkCapabilities(network) ?: return false
+		return capabilities.hasTransport(NetworkCapabilities.TRANSPORT_CELLULAR)
+	}
+
+	/**
+	 * Get the current transport type as a readable string.
+	 */
+	fun getTransportType(): String {
+		val network = connectivityManager.activeNetwork ?: return "none"
+		val capabilities = connectivityManager.getNetworkCapabilities(network) ?: return "unknown"
+		return when {
+			capabilities.hasTransport(NetworkCapabilities.TRANSPORT_WIFI) -> "wifi"
+			capabilities.hasTransport(NetworkCapabilities.TRANSPORT_CELLULAR) -> "cellular"
+			capabilities.hasTransport(NetworkCapabilities.TRANSPORT_ETHERNET) -> "ethernet"
+			capabilities.hasTransport(NetworkCapabilities.TRANSPORT_VPN) -> "vpn"
+			else -> "other"
+		}
+	}
+
 	suspend fun awaitForConnection() {
 		if (value) {
 			return

From 65a0879a5727c8f34acf7737e3cc26056c997212 Mon Sep 17 00:00:00 2001
From: AgentKush <finlayhansford66@gmail.com>
Date: Thu, 22 Jan 2026 07:12:42 +0000
Subject: [PATCH 23/35] feat: Implement DNS Prefetching for Common Domains (#7)

- Add DnsPrefetcher class implementing OkHttp Dns interface
  - Caches DNS results with 5-minute TTL
  - Proactive refresh before entries expire
  - Common CDN domains pre-configured
  - Observable cache statistics
- Add DnsPrefetchManager for manga source integration
  - Auto-prefetch domains for enabled sources
  - Prefetch when sources become enabled
  - Source-specific CDN domain support
- Integrate with existing DoH infrastructure
  - DnsPrefetcher wraps DoHManager as delegate
  - Seamless integration with existing DNS-over-HTTPS
- Initialize on app startup via BaseApp

Features:
- DNS cache with configurable TTL (5 min default)
- Background refresh 1 minute before expiry
- Prefetch for enabled manga source domains
- Common CDN domains (jsdelivr, cloudflare, googleapis)
- Source-specific CDN domains (MangaDex, Webtoon)
- Cache statistics for debugging
- Network-aware (skip when offline)
---
 .../org/koitharu/kotatsu/core/BaseApp.kt      |   5 +
 .../core/network/DnsPrefetchManager.kt        | 127 ++++++++
 .../kotatsu/core/network/DnsPrefetcher.kt     | 304 ++++++++++++++++++
 .../kotatsu/core/network/NetworkModule.kt     |   6 +-
 4 files changed, 441 insertions(+), 1 deletion(-)
 create mode 100644 app/src/main/kotlin/org/koitharu/kotatsu/core/network/DnsPrefetchManager.kt
 create mode 100644 app/src/main/kotlin/org/koitharu/kotatsu/core/network/DnsPrefetcher.kt

diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/BaseApp.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/BaseApp.kt
index 3084229..216d4ab 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/BaseApp.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/BaseApp.kt
@@ -26,6 +26,7 @@ import org.koitharu.kotatsu.R
 import org.koitharu.kotatsu.core.db.MangaDatabase
 import org.koitharu.kotatsu.core.os.AppValidator
 import org.koitharu.kotatsu.core.os.RomCompat
+import org.koitharu.kotatsu.core.network.DnsPrefetchManager
 import org.koitharu.kotatsu.core.prefs.AppSettings
 import org.koitharu.kotatsu.core.util.ext.processLifecycleScope
 import org.koitharu.kotatsu.local.data.LocalStorageChanges
@@ -61,6 +62,9 @@ open class BaseApp : Application(), Configuration.Provider {
 	@Inject
 	lateinit var workScheduleManager: WorkScheduleManager
 
+	@Inject
+	lateinit var dnsPrefetchManager: DnsPrefetchManager
+
 	@Inject
 	lateinit var localMangaIndexProvider: Provider<LocalMangaIndex>
 
@@ -94,6 +98,7 @@ open class BaseApp : Application(), Configuration.Provider {
 			localStorageChanges.collect(localMangaIndexProvider.get())
 		}
 		workScheduleManager.init()
+		dnsPrefetchManager.initialize()
 	}
 
 	override fun attachBaseContext(base: Context) {
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/network/DnsPrefetchManager.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/DnsPrefetchManager.kt
new file mode 100644
index 0000000..3d26367
--- /dev/null
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/DnsPrefetchManager.kt
@@ -0,0 +1,127 @@
+package org.koitharu.kotatsu.core.network
+
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.flow.launchIn
+import kotlinx.coroutines.flow.onEach
+import kotlinx.coroutines.launch
+import org.koitharu.kotatsu.core.os.NetworkState
+import org.koitharu.kotatsu.explore.data.MangaSourcesRepository
+import org.koitharu.kotatsu.parsers.model.MangaParserSource
+import org.koitharu.kotatsu.parsers.model.MangaSource
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Manages DNS prefetching for manga sources.
+ *
+ * Automatically prefetches DNS for:
+ * - All enabled manga sources when app starts
+ * - Sources when they become enabled
+ * - Common CDN domains used by multiple sources
+ */
+@Singleton
+class DnsPrefetchManager @Inject constructor(
+	private val dnsPrefetcher: DnsPrefetcher,
+	private val sourcesRepository: MangaSourcesRepository,
+	private val networkState: NetworkState,
+) {
+	private val scope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
+	private var isInitialized = false
+
+	/**
+	 * Initialize DNS prefetching.
+	 * Should be called during app startup.
+	 */
+	fun initialize() {
+		if (isInitialized) return
+		isInitialized = true
+
+		// Start prefetcher with common domains
+		dnsPrefetcher.start()
+
+		// Observe enabled sources and prefetch their domains
+		sourcesRepository.observeEnabledSources()
+			.onEach { sources ->
+				if (networkState.isOnline()) {
+					prefetchSourceDomains(sources.map { it.mangaSource })
+				}
+			}
+			.launchIn(scope)
+
+		// Initial prefetch
+		scope.launch {
+			val enabledSources = sourcesRepository.getEnabledSources()
+			prefetchSourceDomains(enabledSources)
+		}
+	}
+
+	/**
+	 * Prefetch DNS for a specific source when the user opens it.
+	 */
+	fun prefetchForSource(source: MangaSource) {
+		val domain = extractDomainFromSource(source) ?: return
+		dnsPrefetcher.prefetch(domain)
+
+		// Also prefetch common image CDN domains for this source
+		val cdnDomains = getSourceCdnDomains(source)
+		if (cdnDomains.isNotEmpty()) {
+			dnsPrefetcher.prefetch(*cdnDomains.toTypedArray())
+		}
+	}
+
+	/**
+	 * Prefetch DNS for URLs that are about to be loaded.
+	 */
+	fun prefetchForUrls(vararg urls: String) {
+		dnsPrefetcher.prefetchFromUrls(*urls)
+	}
+
+	/**
+	 * Get cache statistics for debugging.
+	 */
+	fun getCacheStats(): DnsPrefetcher.CacheStats {
+		return dnsPrefetcher.getCacheStats()
+	}
+
+	/**
+	 * Clear the DNS cache.
+	 */
+	fun clearCache() {
+		dnsPrefetcher.clearCache()
+	}
+
+	private fun prefetchSourceDomains(sources: List<MangaSource>) {
+		val domains = sources.mapNotNull { extractDomainFromSource(it) }.toSet()
+		if (domains.isNotEmpty()) {
+			dnsPrefetcher.prefetch(*domains.toTypedArray())
+		}
+	}
+
+	private fun extractDomainFromSource(source: MangaSource): String? {
+		if (source !is MangaParserSource) return null
+
+		// Extract domain from source's known domains
+		return try {
+			source.domains.firstOrNull()
+		} catch (e: Exception) {
+			null
+		}
+	}
+
+	private fun getSourceCdnDomains(source: MangaSource): Set<String> {
+		// Common CDN domains used by manga sites
+		// This can be extended based on known source patterns
+		return when {
+			source.name.contains("mangadex", ignoreCase = true) -> setOf(
+				"uploads.mangadex.org",
+				"api.mangadex.org",
+			)
+			source.name.contains("webtoon", ignoreCase = true) -> setOf(
+				"webtoon-phinf.pstatic.net",
+			)
+			else -> emptySet()
+		}
+	}
+}
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/network/DnsPrefetcher.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/DnsPrefetcher.kt
new file mode 100644
index 0000000..5299255
--- /dev/null
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/DnsPrefetcher.kt
@@ -0,0 +1,304 @@
+package org.koitharu.kotatsu.core.network
+
+import android.util.Log
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.isActive
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.sync.Mutex
+import kotlinx.coroutines.sync.withLock
+import okhttp3.Dns
+import org.koitharu.kotatsu.BuildConfig
+import org.koitharu.kotatsu.core.os.NetworkState
+import java.net.InetAddress
+import java.net.UnknownHostException
+import java.util.concurrent.ConcurrentHashMap
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * DNS Prefetcher that proactively resolves domain names for faster first connections.
+ *
+ * Features:
+ * - Caches DNS results with configurable TTL
+ * - Prefetches domains for enabled manga sources
+ * - Background refresh before entries expire
+ * - Observable prefetch status for debugging
+ * - Integrates with existing DoH/DNS infrastructure
+ */
+@Singleton
+class DnsPrefetcher @Inject constructor(
+	private val networkState: NetworkState,
+) : Dns {
+
+	private val scope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
+	private val cache = ConcurrentHashMap<String, DnsCacheEntry>()
+	private val refreshMutex = Mutex()
+	private val pendingPrefetches = ConcurrentHashMap.newKeySet<String>()
+
+	private var delegate: Dns = Dns.SYSTEM
+	private var isRunning = false
+
+	/**
+	 * Common domains that should be prefetched.
+	 * These include CDN providers and common manga hosting services.
+	 */
+	private val commonDomains = setOf(
+		// CDN providers commonly used by manga sites
+		"cdn.jsdelivr.net",
+		"cdnjs.cloudflare.com",
+		"fonts.googleapis.com",
+		"fonts.gstatic.com",
+		
+		// Image hosting services
+		"i.imgur.com",
+		"imgur.com",
+		
+		// Common infrastructure
+		"cloudflare.com",
+		"fastly.net",
+	)
+
+	/**
+	 * Set the delegate DNS resolver (e.g., DoHManager).
+	 */
+	fun setDelegate(dns: Dns) {
+		delegate = dns
+	}
+
+	/**
+	 * Start the prefetcher with a list of domains to prefetch.
+	 */
+	fun start(domains: Set<String> = emptySet()) {
+		if (isRunning) return
+		isRunning = true
+
+		scope.launch {
+			// Initial prefetch
+			val allDomains = commonDomains + domains
+			prefetchDomains(allDomains)
+
+			// Background refresh loop
+			while (isActive && isRunning) {
+				delay(REFRESH_INTERVAL_MS)
+				refreshExpiringSoon()
+			}
+		}
+	}
+
+	/**
+	 * Stop the prefetcher.
+	 */
+	fun stop() {
+		isRunning = false
+	}
+
+	/**
+	 * Add domains to prefetch queue.
+	 */
+	fun prefetch(vararg domains: String) {
+		if (!networkState.isOnline()) return
+
+		scope.launch {
+			for (domain in domains) {
+				prefetchSingle(domain)
+			}
+		}
+	}
+
+	/**
+	 * Add domains from URLs to prefetch queue.
+	 */
+	fun prefetchFromUrls(vararg urls: String) {
+		val domains = urls.mapNotNull { extractDomain(it) }.toSet()
+		if (domains.isNotEmpty()) {
+			prefetch(*domains.toTypedArray())
+		}
+	}
+
+	/**
+	 * DNS lookup with cache support.
+	 */
+	override fun lookup(hostname: String): List<InetAddress> {
+		// Check cache first
+		val cached = cache[hostname]
+		if (cached != null && !cached.isExpired()) {
+			logDebug { "DNS cache hit: $hostname -> ${cached.addresses.size} addresses" }
+			return cached.addresses
+		}
+
+		// Cache miss or expired, do actual lookup
+		return try {
+			val addresses = delegate.lookup(hostname)
+			cache[hostname] = DnsCacheEntry(
+				hostname = hostname,
+				addresses = addresses,
+				timestamp = System.currentTimeMillis(),
+			)
+			logDebug { "DNS lookup: $hostname -> ${addresses.size} addresses" }
+			addresses
+		} catch (e: UnknownHostException) {
+			// Remove from cache on failure
+			cache.remove(hostname)
+			throw e
+		}
+	}
+
+	/**
+	 * Get current cache statistics.
+	 */
+	fun getCacheStats(): CacheStats {
+		val now = System.currentTimeMillis()
+		var validCount = 0
+		var expiredCount = 0
+		var totalAddresses = 0
+
+		for (entry in cache.values) {
+			if (entry.isExpired(now)) {
+				expiredCount++
+			} else {
+				validCount++
+				totalAddresses += entry.addresses.size
+			}
+		}
+
+		return CacheStats(
+			totalEntries = cache.size,
+			validEntries = validCount,
+			expiredEntries = expiredCount,
+			totalAddresses = totalAddresses,
+			pendingPrefetches = pendingPrefetches.size,
+		)
+	}
+
+	/**
+	 * Clear the DNS cache.
+	 */
+	fun clearCache() {
+		cache.clear()
+		logDebug { "DNS cache cleared" }
+	}
+
+	/**
+	 * Check if a domain is cached and valid.
+	 */
+	fun isCached(hostname: String): Boolean {
+		val entry = cache[hostname] ?: return false
+		return !entry.isExpired()
+	}
+
+	private suspend fun prefetchDomains(domains: Set<String>) {
+		if (!networkState.isOnline()) return
+
+		for (domain in domains) {
+			prefetchSingle(domain)
+			// Small delay to avoid flooding
+			delay(50)
+		}
+	}
+
+	private suspend fun prefetchSingle(hostname: String) {
+		// Skip if already cached and valid
+		val cached = cache[hostname]
+		if (cached != null && !cached.isExpiringSoon()) {
+			return
+		}
+
+		// Skip if already pending
+		if (!pendingPrefetches.add(hostname)) {
+			return
+		}
+
+		try {
+			val addresses = delegate.lookup(hostname)
+			cache[hostname] = DnsCacheEntry(
+				hostname = hostname,
+				addresses = addresses,
+				timestamp = System.currentTimeMillis(),
+			)
+			logDebug { "DNS prefetch: $hostname -> ${addresses.size} addresses" }
+		} catch (e: UnknownHostException) {
+			logDebug { "DNS prefetch failed: $hostname - ${e.message}" }
+		} catch (e: Exception) {
+			logDebug { "DNS prefetch error: $hostname - ${e.message}" }
+		} finally {
+			pendingPrefetches.remove(hostname)
+		}
+	}
+
+	private suspend fun refreshExpiringSoon() {
+		if (!networkState.isOnline()) return
+
+		refreshMutex.withLock {
+			val now = System.currentTimeMillis()
+			val toRefresh = cache.values.filter { it.isExpiringSoon(now) }.map { it.hostname }
+
+			for (hostname in toRefresh) {
+				prefetchSingle(hostname)
+				delay(100)
+			}
+
+			// Clean up expired entries
+			cache.entries.removeIf { it.value.isExpired(now) }
+		}
+	}
+
+	private fun extractDomain(url: String): String? {
+		return try {
+			val withoutProtocol = url
+				.removePrefix("https://")
+				.removePrefix("http://")
+			val endIndex = withoutProtocol.indexOfAny(charArrayOf('/', ':', '?', '#'))
+			if (endIndex > 0) {
+				withoutProtocol.substring(0, endIndex)
+			} else {
+				withoutProtocol
+			}
+		} catch (e: Exception) {
+			null
+		}
+	}
+
+	private inline fun logDebug(message: () -> String) {
+		if (BuildConfig.DEBUG) {
+			Log.d(TAG, message())
+		}
+	}
+
+	/**
+	 * Cache entry for a DNS lookup result.
+	 */
+	private data class DnsCacheEntry(
+		val hostname: String,
+		val addresses: List<InetAddress>,
+		val timestamp: Long,
+	) {
+		fun isExpired(now: Long = System.currentTimeMillis()): Boolean {
+			return now - timestamp > TTL_MS
+		}
+
+		fun isExpiringSoon(now: Long = System.currentTimeMillis()): Boolean {
+			return now - timestamp > TTL_MS - REFRESH_BEFORE_EXPIRY_MS
+		}
+	}
+
+	/**
+	 * Statistics about the DNS cache.
+	 */
+	data class CacheStats(
+		val totalEntries: Int,
+		val validEntries: Int,
+		val expiredEntries: Int,
+		val totalAddresses: Int,
+		val pendingPrefetches: Int,
+	)
+
+	companion object {
+		private const val TAG = "DnsPrefetcher"
+		private const val TTL_MS = 5 * 60 * 1000L // 5 minutes
+		private const val REFRESH_BEFORE_EXPIRY_MS = 60 * 1000L // Refresh 1 minute before expiry
+		private const val REFRESH_INTERVAL_MS = 30 * 1000L // Check every 30 seconds
+	}
+}
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/network/NetworkModule.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/NetworkModule.kt
index 26a7436..7387a7d 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/network/NetworkModule.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/NetworkModule.kt
@@ -64,6 +64,7 @@ interface NetworkModule {
 			cookieJar: CookieJar,
 			settings: AppSettings,
 			proxyProvider: ProxyProvider,
+			dnsPrefetcher: DnsPrefetcher,
 		): OkHttpClient = OkHttpClient.Builder().apply {
 			assertNotInMainThread()
 			connectTimeout(20, TimeUnit.SECONDS)
@@ -72,7 +73,10 @@ interface NetworkModule {
 			cookieJar(cookieJar)
 			proxySelector(proxyProvider.selector)
 			proxyAuthenticator(proxyProvider.authenticator)
-			dns(DoHManager(cache, settings))
+			// Set up DNS with prefetching - prefetcher wraps DoHManager
+			val dohManager = DoHManager(cache, settings)
+			dnsPrefetcher.setDelegate(dohManager)
+			dns(dnsPrefetcher)
 			if (settings.isSSLBypassEnabled) {
 				disableCertificateVerification()
 			} else {

From e2f97b5393e3f5ec3b93c056c2f5fdcedc9e7408 Mon Sep 17 00:00:00 2001
From: AgentKush <finlayhansford66@gmail.com>
Date: Thu, 22 Jan 2026 07:36:21 +0000
Subject: [PATCH 24/35] feat: Implement Download Resume Support (#8)

- Add ResumableDownloader for HTTP Range request support
  - Detects server support via Accept-Ranges header
  - Resumes partial downloads from last byte position
  - Falls back to full download if resume not supported
  - Validates Content-Range responses

- Add DownloadStateTracker for persistent download state
  - Tracks chapter download progress (completed pages)
  - Stores partial file information for resume
  - Automatically cleans up data older than 7 days
  - Thread-safe with mutex protection

- Integrate with DownloadWorker
  - Use resumable downloader for HTTP page downloads
  - Track partial files on download failure
  - Resume from partial files on retry
  - Clean up tracking after successful download
---
 .../download/domain/DownloadStateTracker.kt   | 315 ++++++++++++++++++
 .../download/domain/ResumableDownloader.kt    | 271 +++++++++++++++
 .../download/ui/worker/DownloadWorker.kt      |  59 +++-
 3 files changed, 628 insertions(+), 17 deletions(-)
 create mode 100644 app/src/main/kotlin/org/koitharu/kotatsu/download/domain/DownloadStateTracker.kt
 create mode 100644 app/src/main/kotlin/org/koitharu/kotatsu/download/domain/ResumableDownloader.kt

diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/download/domain/DownloadStateTracker.kt b/app/src/main/kotlin/org/koitharu/kotatsu/download/domain/DownloadStateTracker.kt
new file mode 100644
index 0000000..151ce36
--- /dev/null
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/download/domain/DownloadStateTracker.kt
@@ -0,0 +1,315 @@
+package org.koitharu.kotatsu.download.domain
+
+import android.content.Context
+import android.content.SharedPreferences
+import dagger.hilt.android.qualifiers.ApplicationContext
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.sync.Mutex
+import kotlinx.coroutines.sync.withLock
+import kotlinx.coroutines.withContext
+import org.json.JSONArray
+import org.json.JSONObject
+import java.io.File
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Tracks partial download state for resume capability.
+ *
+ * Stores:
+ * - Chapter download progress (which pages are complete)
+ * - Partial file information (path, expected size, current size)
+ * - Download session metadata
+ */
+@Singleton
+class DownloadStateTracker @Inject constructor(
+	@ApplicationContext private val context: Context,
+) {
+	private val prefs: SharedPreferences by lazy {
+		context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+	}
+
+	private val mutex = Mutex()
+
+	/**
+	 * Record that a chapter download has started.
+	 */
+	suspend fun startChapter(
+		mangaId: Long,
+		chapterId: Long,
+		totalPages: Int,
+	) = mutex.withLock {
+		withContext(Dispatchers.IO) {
+			val key = getChapterKey(mangaId, chapterId)
+			val state = ChapterDownloadState(
+				chapterId = chapterId,
+				totalPages = totalPages,
+				completedPages = mutableSetOf(),
+				startedAt = System.currentTimeMillis(),
+			)
+			prefs.edit().putString(key, state.toJson()).apply()
+		}
+	}
+
+	/**
+	 * Mark a page as completed.
+	 */
+	suspend fun markPageComplete(
+		mangaId: Long,
+		chapterId: Long,
+		pageIndex: Int,
+	) = mutex.withLock {
+		withContext(Dispatchers.IO) {
+			val key = getChapterKey(mangaId, chapterId)
+			val json = prefs.getString(key, null) ?: return@withContext
+			val state = ChapterDownloadState.fromJson(json)
+			state.completedPages.add(pageIndex)
+			prefs.edit().putString(key, state.toJson()).apply()
+		}
+	}
+
+	/**
+	 * Mark a chapter as fully completed.
+	 */
+	suspend fun completeChapter(
+		mangaId: Long,
+		chapterId: Long,
+	) = mutex.withLock {
+		withContext(Dispatchers.IO) {
+			val key = getChapterKey(mangaId, chapterId)
+			prefs.edit().remove(key).apply()
+
+			// Add to completed chapters list
+			val completedKey = getCompletedChaptersKey(mangaId)
+			val completed = getCompletedChapterIds(mangaId).toMutableSet()
+			completed.add(chapterId)
+			prefs.edit().putString(completedKey, JSONArray(completed.toList()).toString()).apply()
+		}
+	}
+
+	/**
+	 * Get the download state for a chapter.
+	 */
+	suspend fun getChapterState(
+		mangaId: Long,
+		chapterId: Long,
+	): ChapterDownloadState? = mutex.withLock {
+		withContext(Dispatchers.IO) {
+			val key = getChapterKey(mangaId, chapterId)
+			val json = prefs.getString(key, null) ?: return@withContext null
+			ChapterDownloadState.fromJson(json)
+		}
+	}
+
+	/**
+	 * Get completed pages for a chapter (for resume).
+	 */
+	suspend fun getCompletedPages(
+		mangaId: Long,
+		chapterId: Long,
+	): Set<Int> {
+		return getChapterState(mangaId, chapterId)?.completedPages ?: emptySet()
+	}
+
+	/**
+	 * Get IDs of fully completed chapters.
+	 */
+	suspend fun getCompletedChapterIds(mangaId: Long): Set<Long> = mutex.withLock {
+		withContext(Dispatchers.IO) {
+			val key = getCompletedChaptersKey(mangaId)
+			val json = prefs.getString(key, null) ?: return@withContext emptySet()
+			try {
+				val array = JSONArray(json)
+				(0 until array.length()).map { array.getLong(it) }.toSet()
+			} catch (e: Exception) {
+				emptySet()
+			}
+		}
+	}
+
+	/**
+	 * Track a partial file download.
+	 */
+	suspend fun trackPartialFile(
+		url: String,
+		file: File,
+		expectedSize: Long,
+	) = mutex.withLock {
+		withContext(Dispatchers.IO) {
+			val key = getPartialFileKey(url)
+			val state = PartialFileState(
+				url = url,
+				filePath = file.absolutePath,
+				expectedSize = expectedSize,
+				downloadedSize = file.length(),
+				lastModified = System.currentTimeMillis(),
+			)
+			prefs.edit().putString(key, state.toJson()).apply()
+		}
+	}
+
+	/**
+	 * Get partial file state for resume.
+	 */
+	suspend fun getPartialFile(url: String): PartialFileState? = mutex.withLock {
+		withContext(Dispatchers.IO) {
+			val key = getPartialFileKey(url)
+			val json = prefs.getString(key, null) ?: return@withContext null
+			val state = PartialFileState.fromJson(json)
+
+			// Verify file still exists
+			val file = File(state.filePath)
+			if (!file.exists()) {
+				prefs.edit().remove(key).apply()
+				return@withContext null
+			}
+
+			// Update with current size
+			state.copy(downloadedSize = file.length())
+		}
+	}
+
+	/**
+	 * Remove partial file tracking.
+	 */
+	suspend fun removePartialFile(url: String) = mutex.withLock {
+		withContext(Dispatchers.IO) {
+			val key = getPartialFileKey(url)
+			prefs.edit().remove(key).apply()
+		}
+	}
+
+	/**
+	 * Clear all tracking data for a manga.
+	 */
+	suspend fun clearMangaState(mangaId: Long) = mutex.withLock {
+		withContext(Dispatchers.IO) {
+			val editor = prefs.edit()
+			prefs.all.keys
+				.filter { it.startsWith("chapter_${mangaId}_") || it == getCompletedChaptersKey(mangaId) }
+				.forEach { editor.remove(it) }
+			editor.apply()
+		}
+	}
+
+	/**
+	 * Clean up old tracking data (older than 7 days).
+	 */
+	suspend fun cleanupOldData() = mutex.withLock {
+		withContext(Dispatchers.IO) {
+			val cutoff = System.currentTimeMillis() - MAX_AGE_MS
+			val editor = prefs.edit()
+			var removed = 0
+
+			prefs.all.forEach { (key, value) ->
+				if (key.startsWith("chapter_") && value is String) {
+					try {
+						val state = ChapterDownloadState.fromJson(value)
+						if (state.startedAt < cutoff) {
+							editor.remove(key)
+							removed++
+						}
+					} catch (e: Exception) {
+						editor.remove(key)
+					}
+				} else if (key.startsWith("partial_") && value is String) {
+					try {
+						val state = PartialFileState.fromJson(value)
+						if (state.lastModified < cutoff) {
+							editor.remove(key)
+							removed++
+						}
+					} catch (e: Exception) {
+						editor.remove(key)
+					}
+				}
+			}
+
+			if (removed > 0) {
+				editor.apply()
+			}
+		}
+	}
+
+	private fun getChapterKey(mangaId: Long, chapterId: Long) = "chapter_${mangaId}_$chapterId"
+	private fun getCompletedChaptersKey(mangaId: Long) = "completed_$mangaId"
+	private fun getPartialFileKey(url: String) = "partial_${url.hashCode()}"
+
+	/**
+	 * State of a chapter download in progress.
+	 */
+	data class ChapterDownloadState(
+		val chapterId: Long,
+		val totalPages: Int,
+		val completedPages: MutableSet<Int>,
+		val startedAt: Long,
+	) {
+		fun toJson(): String {
+			return JSONObject().apply {
+				put("chapterId", chapterId)
+				put("totalPages", totalPages)
+				put("completedPages", JSONArray(completedPages.toList()))
+				put("startedAt", startedAt)
+			}.toString()
+		}
+
+		companion object {
+			fun fromJson(json: String): ChapterDownloadState {
+				val obj = JSONObject(json)
+				val pagesArray = obj.getJSONArray("completedPages")
+				val pages = (0 until pagesArray.length()).map { pagesArray.getInt(it) }.toMutableSet()
+				return ChapterDownloadState(
+					chapterId = obj.getLong("chapterId"),
+					totalPages = obj.getInt("totalPages"),
+					completedPages = pages,
+					startedAt = obj.optLong("startedAt", 0L),
+				)
+			}
+		}
+	}
+
+	/**
+	 * State of a partial file download.
+	 */
+	data class PartialFileState(
+		val url: String,
+		val filePath: String,
+		val expectedSize: Long,
+		val downloadedSize: Long,
+		val lastModified: Long,
+	) {
+		val isComplete: Boolean
+			get() = expectedSize > 0 && downloadedSize >= expectedSize
+
+		val progress: Float
+			get() = if (expectedSize > 0) downloadedSize.toFloat() / expectedSize else 0f
+
+		fun toJson(): String {
+			return JSONObject().apply {
+				put("url", url)
+				put("filePath", filePath)
+				put("expectedSize", expectedSize)
+				put("downloadedSize", downloadedSize)
+				put("lastModified", lastModified)
+			}.toString()
+		}
+
+		companion object {
+			fun fromJson(json: String): PartialFileState {
+				val obj = JSONObject(json)
+				return PartialFileState(
+					url = obj.getString("url"),
+					filePath = obj.getString("filePath"),
+					expectedSize = obj.getLong("expectedSize"),
+					downloadedSize = obj.getLong("downloadedSize"),
+					lastModified = obj.optLong("lastModified", 0L),
+				)
+			}
+		}
+	}
+
+	companion object {
+		private const val PREFS_NAME = "download_state_tracker"
+		private const val MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000L // 7 days
+	}
+}
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/download/domain/ResumableDownloader.kt b/app/src/main/kotlin/org/koitharu/kotatsu/download/domain/ResumableDownloader.kt
new file mode 100644
index 0000000..3f593a3
--- /dev/null
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/download/domain/ResumableDownloader.kt
@@ -0,0 +1,271 @@
+package org.koitharu.kotatsu.download.domain
+
+import android.util.Log
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+import okhttp3.OkHttpClient
+import okhttp3.Request
+import okhttp3.Response
+import okio.buffer
+import okio.sink
+import org.koitharu.kotatsu.BuildConfig
+import org.koitharu.kotatsu.core.network.MangaHttpClient
+import org.koitharu.kotatsu.core.util.ext.ensureSuccess
+import org.koitharu.kotatsu.core.util.ext.writeAllCancellable
+import org.koitharu.kotatsu.parsers.util.requireBody
+import java.io.File
+import java.io.IOException
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Handles resumable downloads with HTTP Range header support.
+ *
+ * Features:
+ * - Detects server support for range requests (Accept-Ranges header)
+ * - Resumes partial downloads from last byte position
+ * - Falls back to full download if resume not supported
+ * - Validates Content-Range responses
+ * - Tracks download progress for resume capability
+ */
+@Singleton
+class ResumableDownloader @Inject constructor(
+	@MangaHttpClient private val okHttp: OkHttpClient,
+) {
+
+	/**
+	 * Download a file with resume support.
+	 *
+	 * @param request The original OkHttp request
+	 * @param targetFile The file to download to (may be partial)
+	 * @param progressCallback Optional callback for download progress
+	 * @return The completed file
+	 */
+	suspend fun download(
+		request: Request,
+		targetFile: File,
+		progressCallback: ((downloaded: Long, total: Long) -> Unit)? = null,
+	): File = withContext(Dispatchers.IO) {
+		val existingBytes = if (targetFile.exists()) targetFile.length() else 0L
+
+		// If file exists and has content, try to resume
+		if (existingBytes > 0) {
+			logDebug { "Attempting resume from byte $existingBytes for ${request.url}" }
+
+			// First, check if server supports range requests
+			val supportsRange = checkRangeSupport(request)
+
+			if (supportsRange) {
+				try {
+					return@withContext resumeDownload(request, targetFile, existingBytes, progressCallback)
+				} catch (e: RangeNotSatisfiableException) {
+					logDebug { "Range not satisfiable, file may be complete or corrupted: ${e.message}" }
+					// File might be complete or corrupted, verify size
+					val contentLength = getContentLength(request)
+					if (contentLength > 0 && existingBytes >= contentLength) {
+						logDebug { "File appears complete ($existingBytes >= $contentLength)" }
+						progressCallback?.invoke(existingBytes, existingBytes)
+						return@withContext targetFile
+					}
+					// File is corrupted, restart download
+					targetFile.delete()
+				} catch (e: ResumeNotSupportedException) {
+					logDebug { "Resume not supported: ${e.message}" }
+					targetFile.delete()
+				}
+			} else {
+				logDebug { "Server doesn't support range requests, starting fresh" }
+				targetFile.delete()
+			}
+		}
+
+		// Full download (no resume)
+		fullDownload(request, targetFile, progressCallback)
+	}
+
+	/**
+	 * Check if the server supports HTTP Range requests.
+	 */
+	private suspend fun checkRangeSupport(request: Request): Boolean {
+		return try {
+			val headRequest = request.newBuilder()
+				.head()
+				.build()
+
+			val response = okHttp.newCall(headRequest).execute()
+			response.use {
+				val acceptRanges = it.header("Accept-Ranges")
+				val supportsRange = acceptRanges?.equals("bytes", ignoreCase = true) == true
+
+				// Also check if Content-Length is present (needed for progress)
+				val contentLength = it.header("Content-Length")?.toLongOrNull() ?: 0L
+
+				logDebug { "Range support check: Accept-Ranges=$acceptRanges, Content-Length=$contentLength" }
+				supportsRange && contentLength > 0
+			}
+		} catch (e: Exception) {
+			logDebug { "Failed to check range support: ${e.message}" }
+			false
+		}
+	}
+
+	/**
+	 * Get the content length for a request.
+	 */
+	private suspend fun getContentLength(request: Request): Long {
+		return try {
+			val headRequest = request.newBuilder()
+				.head()
+				.build()
+
+			okHttp.newCall(headRequest).execute().use { response ->
+				response.header("Content-Length")?.toLongOrNull() ?: -1L
+			}
+		} catch (e: Exception) {
+			-1L
+		}
+	}
+
+	/**
+	 * Resume a partial download.
+	 */
+	private suspend fun resumeDownload(
+		request: Request,
+		targetFile: File,
+		existingBytes: Long,
+		progressCallback: ((downloaded: Long, total: Long) -> Unit)?,
+	): File {
+		val rangeRequest = request.newBuilder()
+			.header("Range", "bytes=$existingBytes-")
+			.build()
+
+		val response = okHttp.newCall(rangeRequest).execute()
+
+		return response.use { resp ->
+			when (resp.code) {
+				206 -> {
+					// Partial content - resume successful
+					val contentRange = resp.header("Content-Range")
+					val totalSize = parseContentRangeTotal(contentRange) ?: run {
+						// Fallback: use Content-Length + existing bytes
+						val contentLength = resp.body?.contentLength() ?: 0L
+						existingBytes + contentLength
+					}
+
+					logDebug { "Resuming download: existing=$existingBytes, total=$totalSize" }
+
+					resp.requireBody().use { body ->
+						// Append to existing file
+						targetFile.sink(append = true).buffer().use { sink ->
+							var downloaded = existingBytes
+							val source = body.source()
+							val buffer = okio.Buffer()
+
+							while (true) {
+								val read = source.read(buffer, BUFFER_SIZE)
+								if (read == -1L) break
+
+								sink.write(buffer, read)
+								downloaded += read
+								progressCallback?.invoke(downloaded, totalSize)
+							}
+						}
+					}
+					targetFile
+				}
+				416 -> {
+					// Range Not Satisfiable
+					throw RangeNotSatisfiableException("Server returned 416: Range not satisfiable")
+				}
+				200 -> {
+					// Server ignored range request, sent full file
+					throw ResumeNotSupportedException("Server returned 200 instead of 206")
+				}
+				else -> {
+					resp.ensureSuccess()
+					throw IOException("Unexpected response code: ${resp.code}")
+				}
+			}
+		}
+	}
+
+	/**
+	 * Perform a full download (no resume).
+	 */
+	private suspend fun fullDownload(
+		request: Request,
+		targetFile: File,
+		progressCallback: ((downloaded: Long, total: Long) -> Unit)?,
+	): File {
+		val response = okHttp.newCall(request).execute()
+
+		return response.use { resp ->
+			resp.ensureSuccess()
+
+			resp.requireBody().use { body ->
+				val totalSize = body.contentLength().takeIf { it > 0 } ?: -1L
+
+				targetFile.sink(append = false).buffer().use { sink ->
+					if (progressCallback != null && totalSize > 0) {
+						// Download with progress tracking
+						var downloaded = 0L
+						val source = body.source()
+						val buffer = okio.Buffer()
+
+						while (true) {
+							val read = source.read(buffer, BUFFER_SIZE)
+							if (read == -1L) break
+
+							sink.write(buffer, read)
+							downloaded += read
+							progressCallback.invoke(downloaded, totalSize)
+						}
+					} else {
+						// Simple download without progress
+						sink.writeAllCancellable(body.source())
+					}
+				}
+			}
+			targetFile
+		}
+	}
+
+	/**
+	 * Parse the total size from Content-Range header.
+	 * Format: bytes start-end/total
+	 * Example: bytes 1000-1999/5000
+	 */
+	private fun parseContentRangeTotal(contentRange: String?): Long? {
+		if (contentRange == null) return null
+
+		return try {
+			val parts = contentRange.split("/")
+			if (parts.size == 2) {
+				val total = parts[1].trim()
+				if (total != "*") {
+					total.toLongOrNull()
+				} else {
+					null
+				}
+			} else {
+				null
+			}
+		} catch (e: Exception) {
+			null
+		}
+	}
+
+	private inline fun logDebug(message: () -> String) {
+		if (BuildConfig.DEBUG) {
+			Log.d(TAG, message())
+		}
+	}
+
+	class RangeNotSatisfiableException(message: String) : IOException(message)
+	class ResumeNotSupportedException(message: String) : IOException(message)
+
+	companion object {
+		private const val TAG = "ResumableDownloader"
+		private const val BUFFER_SIZE = 8192L
+	}
+}
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/download/ui/worker/DownloadWorker.kt b/app/src/main/kotlin/org/koitharu/kotatsu/download/ui/worker/DownloadWorker.kt
index 41298f1..252e821 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/download/ui/worker/DownloadWorker.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/download/ui/worker/DownloadWorker.kt
@@ -75,6 +75,8 @@ import org.koitharu.kotatsu.core.util.ext.writeAllCancellable
 import org.koitharu.kotatsu.core.util.progress.RealtimeEtaEstimator
 import org.koitharu.kotatsu.download.domain.DownloadProgress
 import org.koitharu.kotatsu.download.domain.DownloadState
+import org.koitharu.kotatsu.download.domain.DownloadStateTracker
+import org.koitharu.kotatsu.download.domain.ResumableDownloader
 import org.koitharu.kotatsu.local.data.LocalMangaRepository
 import org.koitharu.kotatsu.local.data.LocalStorageCache
 import org.koitharu.kotatsu.local.data.LocalStorageChanges
@@ -113,6 +115,8 @@ class DownloadWorker @AssistedInject constructor(
 	@LocalStorageChanges private val localStorageChanges: MutableSharedFlow<LocalManga?>,
 	private val slowdownDispatcher: DownloadSlowdownDispatcher,
 	private val imageProxyInterceptor: ImageProxyInterceptor,
+	private val resumableDownloader: ResumableDownloader,
+	private val downloadStateTracker: DownloadStateTracker,
 	notificationFactoryFactory: DownloadNotificationFactory.Factory,
 ) : CoroutineWorker(appContext, params) {
 
@@ -395,27 +399,48 @@ class DownloadWorker @AssistedInject constructor(
 			}
 			return file
 		}
+		
+		// HTTP download with resume support
 		val request = PageLoader.createPageRequest(url, source)
 		slowdownDispatcher.delay(source)
-		return imageProxyInterceptor.interceptPageRequest(request, okHttp)
-			.ensureSuccess()
-			.use { response ->
-				var file: File? = null
-				try {
-					response.requireBody().use { body ->
-						file = destination.createTempFile(
-							ext = MimeTypes.getExtension(body.contentType()?.toMimeType())
-						)
-						file.sink(append = false).buffer().use {
-							it.writeAllCancellable(body.source())
-						}
-					}
-				} catch (e: Exception) {
-					file?.delete()
-					throw e
+		
+		// Check for existing partial download
+		val partialState = downloadStateTracker.getPartialFile(url)
+		val targetFile = if (partialState != null) {
+			File(partialState.filePath)
+		} else {
+			destination.createTempFile(null) // Extension determined after download
+		}
+		
+		return try {
+			// Use resumable downloader for HTTP requests
+			resumableDownloader.download(request, targetFile)
+			
+			// Clean up tracking after successful download
+			downloadStateTracker.removePartialFile(url)
+			
+			// Rename with correct extension if needed
+			val mimeType = getMediaType(url, targetFile)
+			val ext = mimeType?.let { MimeTypes.getExtension(it) }
+			if (!ext.isNullOrEmpty() && !targetFile.name.contains(".$ext")) {
+				val renamedFile = File(targetFile.parent, "${targetFile.nameWithoutExtension}.$ext.tmp")
+				if (targetFile.renameTo(renamedFile)) {
+					renamedFile
+				} else {
+					targetFile
 				}
-				checkNotNull(file)
+			} else {
+				targetFile
 			}
+		} catch (e: Exception) {
+			// Track partial download for potential resume
+			if (targetFile.exists() && targetFile.length() > 0) {
+				downloadStateTracker.trackPartialFile(url, targetFile, -1L)
+			} else {
+				targetFile.delete()
+			}
+			throw e
+		}
 	}
 
 	private fun File.createTempFile(ext: String?) = File(

From cd4df25e54ca6ce4597e807986192b600a5d02df Mon Sep 17 00:00:00 2001
From: AgentKush <finlayhansford66@gmail.com>
Date: Thu, 22 Jan 2026 07:36:26 +0000
Subject: [PATCH 25/35] chore: Update Java target to 17 and improve DNS
 prefetch

- Update Java compatibility from 11 to 17
- Optimize DnsPrefetchManager to prefetch on-demand
- Add more CDN domains for MangaKakalot and MangaSee sources
---
 app/build.gradle                              |  6 +-
 .../core/network/DnsPrefetchManager.kt        | 60 ++++++-------------
 2 files changed, 20 insertions(+), 46 deletions(-)

diff --git a/app/build.gradle b/app/build.gradle
index eaa3957..c8308d4 100644
--- a/app/build.gradle
+++ b/app/build.gradle
@@ -82,11 +82,11 @@ android {
 	}
 	compileOptions {
 		coreLibraryDesugaringEnabled true
-		sourceCompatibility JavaVersion.VERSION_11
-		targetCompatibility JavaVersion.VERSION_11
+		sourceCompatibility JavaVersion.VERSION_17
+		targetCompatibility JavaVersion.VERSION_17
 	}
 	kotlinOptions {
-		jvmTarget = JavaVersion.VERSION_11.toString()
+		jvmTarget = JavaVersion.VERSION_17.toString()
 		freeCompilerArgs += [
 			'-opt-in=kotlin.ExperimentalStdlibApi',
 			'-opt-in=kotlinx.coroutines.ExperimentalCoroutinesApi',
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/network/DnsPrefetchManager.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/DnsPrefetchManager.kt
index 3d26367..895a4e3 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/network/DnsPrefetchManager.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/network/DnsPrefetchManager.kt
@@ -3,12 +3,9 @@ package org.koitharu.kotatsu.core.network
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.SupervisorJob
-import kotlinx.coroutines.flow.launchIn
-import kotlinx.coroutines.flow.onEach
 import kotlinx.coroutines.launch
 import org.koitharu.kotatsu.core.os.NetworkState
 import org.koitharu.kotatsu.explore.data.MangaSourcesRepository
-import org.koitharu.kotatsu.parsers.model.MangaParserSource
 import org.koitharu.kotatsu.parsers.model.MangaSource
 import javax.inject.Inject
 import javax.inject.Singleton
@@ -17,9 +14,8 @@ import javax.inject.Singleton
  * Manages DNS prefetching for manga sources.
  *
  * Automatically prefetches DNS for:
- * - All enabled manga sources when app starts
- * - Sources when they become enabled
  * - Common CDN domains used by multiple sources
+ * - Source-specific domains when sources are accessed
  */
 @Singleton
 class DnsPrefetchManager @Inject constructor(
@@ -40,34 +36,20 @@ class DnsPrefetchManager @Inject constructor(
 
 		// Start prefetcher with common domains
 		dnsPrefetcher.start()
-
-		// Observe enabled sources and prefetch their domains
-		sourcesRepository.observeEnabledSources()
-			.onEach { sources ->
-				if (networkState.isOnline()) {
-					prefetchSourceDomains(sources.map { it.mangaSource })
-				}
-			}
-			.launchIn(scope)
-
-		// Initial prefetch
-		scope.launch {
-			val enabledSources = sourcesRepository.getEnabledSources()
-			prefetchSourceDomains(enabledSources)
-		}
 	}
 
 	/**
 	 * Prefetch DNS for a specific source when the user opens it.
 	 */
 	fun prefetchForSource(source: MangaSource) {
-		val domain = extractDomainFromSource(source) ?: return
-		dnsPrefetcher.prefetch(domain)
+		if (!networkState.isOnline()) return
 
-		// Also prefetch common image CDN domains for this source
+		// Prefetch common image CDN domains for this source
 		val cdnDomains = getSourceCdnDomains(source)
 		if (cdnDomains.isNotEmpty()) {
-			dnsPrefetcher.prefetch(*cdnDomains.toTypedArray())
+			scope.launch {
+				dnsPrefetcher.prefetch(*cdnDomains.toTypedArray())
+			}
 		}
 	}
 
@@ -75,7 +57,10 @@ class DnsPrefetchManager @Inject constructor(
 	 * Prefetch DNS for URLs that are about to be loaded.
 	 */
 	fun prefetchForUrls(vararg urls: String) {
-		dnsPrefetcher.prefetchFromUrls(*urls)
+		if (!networkState.isOnline()) return
+		scope.launch {
+			dnsPrefetcher.prefetchFromUrls(*urls)
+		}
 	}
 
 	/**
@@ -92,24 +77,6 @@ class DnsPrefetchManager @Inject constructor(
 		dnsPrefetcher.clearCache()
 	}
 
-	private fun prefetchSourceDomains(sources: List<MangaSource>) {
-		val domains = sources.mapNotNull { extractDomainFromSource(it) }.toSet()
-		if (domains.isNotEmpty()) {
-			dnsPrefetcher.prefetch(*domains.toTypedArray())
-		}
-	}
-
-	private fun extractDomainFromSource(source: MangaSource): String? {
-		if (source !is MangaParserSource) return null
-
-		// Extract domain from source's known domains
-		return try {
-			source.domains.firstOrNull()
-		} catch (e: Exception) {
-			null
-		}
-	}
-
 	private fun getSourceCdnDomains(source: MangaSource): Set<String> {
 		// Common CDN domains used by manga sites
 		// This can be extended based on known source patterns
@@ -121,6 +88,13 @@ class DnsPrefetchManager @Inject constructor(
 			source.name.contains("webtoon", ignoreCase = true) -> setOf(
 				"webtoon-phinf.pstatic.net",
 			)
+			source.name.contains("mangakakalot", ignoreCase = true) -> setOf(
+				"cm.blazefast.co",
+				"avt.mkklcdnv6temp.com",
+			)
+			source.name.contains("mangasee", ignoreCase = true) -> setOf(
+				"temp.compsci88.com",
+			)
 			else -> emptySet()
 		}
 	}

From a44909c8b2a1fa6b928e9765a5d723bb039aefda Mon Sep 17 00:00:00 2001
From: AgentKush <finlayhansford66@gmail.com>
Date: Thu, 22 Jan 2026 07:42:45 +0000
Subject: [PATCH 26/35] feat: Database Query Optimization (#9)

Add comprehensive database indexes and optimization utilities:

Migration 27->28 adds indexes for:
- manga: source, title, public_url
- history: deleted_at, updated_at, created_at, percent, composite
- tracks: chapters_new, last_chapter_date, last_check_time
- favourites: composite deleted_at + created_at
- bookmarks, scrobblings, local_index, suggestions: manga_id
- tags: title
- track_logs: manga_id, created_at
- stats: manga_id, started_at

Entity annotations updated:
- MangaEntity: Added Index annotations for source, title, public_url
- HistoryEntity: Added Index annotations for all query-critical columns
- TrackEntity: Added Index annotations for sorting columns

DatabaseOptimizer utility:
- ANALYZE for query planner statistics
- VACUUM for database compaction
- Database size and fragmentation statistics
- Index listing for debugging
- Integrity checking
- Query plan explanation (debug builds)

These indexes significantly improve performance for:
- History list with filtering/sorting
- Favourites list with sorting
- Search by title/author/tag
- Track new chapters queries
- Manga lookup by source
---
 .../kotatsu/core/db/DatabaseOptimizer.kt      | 236 ++++++++++++++++++
 .../koitharu/kotatsu/core/db/MangaDatabase.kt |   4 +-
 .../kotatsu/core/db/entity/MangaEntity.kt     |  10 +-
 .../core/db/migrations/Migration27To28.kt     |  66 +++++
 .../kotatsu/history/data/HistoryEntity.kt     |   8 +
 .../kotatsu/tracker/data/TrackEntity.kt       |   6 +
 6 files changed, 328 insertions(+), 2 deletions(-)
 create mode 100644 app/src/main/kotlin/org/koitharu/kotatsu/core/db/DatabaseOptimizer.kt
 create mode 100644 app/src/main/kotlin/org/koitharu/kotatsu/core/db/migrations/Migration27To28.kt

diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/db/DatabaseOptimizer.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/db/DatabaseOptimizer.kt
new file mode 100644
index 0000000..a5f88df
--- /dev/null
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/db/DatabaseOptimizer.kt
@@ -0,0 +1,236 @@
+package org.koitharu.kotatsu.core.db
+
+import android.content.Context
+import android.util.Log
+import androidx.room.RoomDatabase
+import androidx.sqlite.db.SupportSQLiteDatabase
+import dagger.hilt.android.qualifiers.ApplicationContext
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+import org.koitharu.kotatsu.BuildConfig
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Database query optimizer that provides runtime optimizations and diagnostics.
+ *
+ * Features:
+ * - Periodic ANALYZE to update query planner statistics
+ * - VACUUM for database compaction (when database is idle)
+ * - Query plan analysis for debugging slow queries
+ * - Index usage statistics
+ */
+@Singleton
+class DatabaseOptimizer @Inject constructor(
+	@ApplicationContext private val context: Context,
+	private val database: MangaDatabase,
+) {
+
+	/**
+	 * Run ANALYZE to update SQLite's query planner statistics.
+	 * Should be called periodically (e.g., once per app session or daily).
+	 */
+	suspend fun analyzeDatabase() = withContext(Dispatchers.IO) {
+		try {
+			database.openHelper.writableDatabase.execSQL("ANALYZE")
+			logDebug { "Database ANALYZE completed successfully" }
+		} catch (e: Exception) {
+			Log.e(TAG, "Failed to analyze database", e)
+		}
+	}
+
+	/**
+	 * Run VACUUM to compact the database and reclaim unused space.
+	 * Should be called infrequently (e.g., weekly or when database size is large).
+	 * Note: This operation can be slow and locks the database.
+	 */
+	suspend fun vacuumDatabase() = withContext(Dispatchers.IO) {
+		try {
+			database.openHelper.writableDatabase.execSQL("VACUUM")
+			logDebug { "Database VACUUM completed successfully" }
+		} catch (e: Exception) {
+			Log.e(TAG, "Failed to vacuum database", e)
+		}
+	}
+
+	/**
+	 * Get the current database file size in bytes.
+	 */
+	fun getDatabaseSize(): Long {
+		return try {
+			context.getDatabasePath("kotatsu-db").length()
+		} catch (e: Exception) {
+			-1L
+		}
+	}
+
+	/**
+	 * Get database statistics including page count, free pages, etc.
+	 */
+	suspend fun getDatabaseStats(): DatabaseStats = withContext(Dispatchers.IO) {
+		try {
+			val db = database.openHelper.readableDatabase
+			
+			val pageCount = queryPragmaInt(db, "page_count")
+			val pageSize = queryPragmaInt(db, "page_size")
+			val freeListCount = queryPragmaInt(db, "freelist_count")
+			
+			DatabaseStats(
+				sizeBytes = getDatabaseSize(),
+				pageCount = pageCount,
+				pageSize = pageSize,
+				freePages = freeListCount,
+				usedPages = pageCount - freeListCount,
+				fragmentationPercent = if (pageCount > 0) {
+					(freeListCount.toFloat() / pageCount * 100).coerceIn(0f, 100f)
+				} else 0f,
+			)
+		} catch (e: Exception) {
+			Log.e(TAG, "Failed to get database stats", e)
+			DatabaseStats()
+		}
+	}
+
+	/**
+	 * Explain a query plan for debugging purposes.
+	 * Only available in debug builds.
+	 */
+	suspend fun explainQueryPlan(query: String): List<String> = withContext(Dispatchers.IO) {
+		if (!BuildConfig.DEBUG) {
+			return@withContext emptyList()
+		}
+		
+		try {
+			val db = database.openHelper.readableDatabase
+			val results = mutableListOf<String>()
+			
+			db.query("EXPLAIN QUERY PLAN $query").use { cursor ->
+				while (cursor.moveToNext()) {
+					val detail = cursor.getString(cursor.getColumnIndexOrThrow("detail"))
+					results.add(detail)
+				}
+			}
+			
+			results
+		} catch (e: Exception) {
+			Log.e(TAG, "Failed to explain query plan", e)
+			emptyList()
+		}
+	}
+
+	/**
+	 * Get a list of all indexes in the database.
+	 */
+	suspend fun getIndexList(): List<IndexInfo> = withContext(Dispatchers.IO) {
+		try {
+			val db = database.openHelper.readableDatabase
+			val indexes = mutableListOf<IndexInfo>()
+			
+			// Get all tables
+			db.query("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' AND name NOT LIKE 'room_%'").use { tablesCursor ->
+				while (tablesCursor.moveToNext()) {
+					val tableName = tablesCursor.getString(0)
+					
+					// Get indexes for each table
+					db.query("PRAGMA index_list('$tableName')").use { indexCursor ->
+						while (indexCursor.moveToNext()) {
+							val indexName = indexCursor.getString(indexCursor.getColumnIndexOrThrow("name"))
+							val isUnique = indexCursor.getInt(indexCursor.getColumnIndexOrThrow("unique")) == 1
+							
+							// Get columns in the index
+							val columns = mutableListOf<String>()
+							db.query("PRAGMA index_info('$indexName')").use { colCursor ->
+								while (colCursor.moveToNext()) {
+									columns.add(colCursor.getString(colCursor.getColumnIndexOrThrow("name")))
+								}
+							}
+							
+							indexes.add(IndexInfo(
+								name = indexName,
+								tableName = tableName,
+								columns = columns,
+								isUnique = isUnique,
+							))
+						}
+					}
+				}
+			}
+			
+			indexes
+		} catch (e: Exception) {
+			Log.e(TAG, "Failed to get index list", e)
+			emptyList()
+		}
+	}
+
+	/**
+	 * Check database integrity.
+	 */
+	suspend fun checkIntegrity(): Boolean = withContext(Dispatchers.IO) {
+		try {
+			val db = database.openHelper.readableDatabase
+			db.query("PRAGMA integrity_check").use { cursor ->
+				if (cursor.moveToFirst()) {
+					val result = cursor.getString(0)
+					return@withContext result == "ok"
+				}
+			}
+			false
+		} catch (e: Exception) {
+			Log.e(TAG, "Failed to check database integrity", e)
+			false
+		}
+	}
+
+	/**
+	 * Optimize database for better performance.
+	 * Combines ANALYZE and optional VACUUM based on fragmentation.
+	 */
+	suspend fun optimize(forceVacuum: Boolean = false) = withContext(Dispatchers.IO) {
+		// Always run ANALYZE
+		analyzeDatabase()
+		
+		// Only VACUUM if fragmentation is high or forced
+		val stats = getDatabaseStats()
+		if (forceVacuum || stats.fragmentationPercent > VACUUM_THRESHOLD_PERCENT) {
+			logDebug { "Running VACUUM due to ${stats.fragmentationPercent}% fragmentation" }
+			vacuumDatabase()
+		}
+	}
+
+	private fun queryPragmaInt(db: SupportSQLiteDatabase, pragma: String): Int {
+		return db.query("PRAGMA $pragma").use { cursor ->
+			if (cursor.moveToFirst()) cursor.getInt(0) else 0
+		}
+	}
+
+	private inline fun logDebug(message: () -> String) {
+		if (BuildConfig.DEBUG) {
+			Log.d(TAG, message())
+		}
+	}
+
+	data class DatabaseStats(
+		val sizeBytes: Long = 0,
+		val pageCount: Int = 0,
+		val pageSize: Int = 0,
+		val freePages: Int = 0,
+		val usedPages: Int = 0,
+		val fragmentationPercent: Float = 0f,
+	) {
+		val sizeMb: Float
+			get() = sizeBytes / (1024f * 1024f)
+	}
+
+	data class IndexInfo(
+		val name: String,
+		val tableName: String,
+		val columns: List<String>,
+		val isUnique: Boolean,
+	)
+
+	companion object {
+		private const val TAG = "DatabaseOptimizer"
+		private const val VACUUM_THRESHOLD_PERCENT = 20f
+	}
+}
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/db/MangaDatabase.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/db/MangaDatabase.kt
index 72a4ba3..2a6c3df 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/db/MangaDatabase.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/db/MangaDatabase.kt
@@ -43,6 +43,7 @@ import org.koitharu.kotatsu.core.db.migrations.Migration24To23
 import org.koitharu.kotatsu.core.db.migrations.Migration24To25
 import org.koitharu.kotatsu.core.db.migrations.Migration25To26
 import org.koitharu.kotatsu.core.db.migrations.Migration26To27
+import org.koitharu.kotatsu.core.db.migrations.Migration27To28
 import org.koitharu.kotatsu.core.db.migrations.Migration2To3
 import org.koitharu.kotatsu.core.db.migrations.Migration3To4
 import org.koitharu.kotatsu.core.db.migrations.Migration4To5
@@ -70,7 +71,7 @@ import org.koitharu.kotatsu.tracker.data.TrackEntity
 import org.koitharu.kotatsu.tracker.data.TrackLogEntity
 import org.koitharu.kotatsu.tracker.data.TracksDao
 
-const val DATABASE_VERSION = 27
+const val DATABASE_VERSION = 28
 
 @Database(
 	entities = [
@@ -142,6 +143,7 @@ fun getDatabaseMigrations(context: Context): Array<Migration> = arrayOf(
 	Migration24To25(),
 	Migration25To26(),
 	Migration26To27(),
+	Migration27To28(),
 )
 
 fun MangaDatabase(context: Context): MangaDatabase = Room
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/db/entity/MangaEntity.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/db/entity/MangaEntity.kt
index fd4a230..3635f03 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/db/entity/MangaEntity.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/db/entity/MangaEntity.kt
@@ -2,10 +2,18 @@ package org.koitharu.kotatsu.core.db.entity
 
 import androidx.room.ColumnInfo
 import androidx.room.Entity
+import androidx.room.Index
 import androidx.room.PrimaryKey
 import org.koitharu.kotatsu.core.db.TABLE_MANGA
 
-@Entity(tableName = TABLE_MANGA)
+@Entity(
+	tableName = TABLE_MANGA,
+	indices = [
+		Index(value = ["source"]),
+		Index(value = ["title"]),
+		Index(value = ["public_url"]),
+	],
+)
 data class MangaEntity(
 	@PrimaryKey(autoGenerate = false)
 	@ColumnInfo(name = "manga_id") val id: Long,
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/db/migrations/Migration27To28.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/db/migrations/Migration27To28.kt
new file mode 100644
index 0000000..2ca72a9
--- /dev/null
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/db/migrations/Migration27To28.kt
@@ -0,0 +1,66 @@
+package org.koitharu.kotatsu.core.db.migrations
+
+import androidx.room.migration.Migration
+import androidx.sqlite.db.SupportSQLiteDatabase
+
+/**
+ * Migration 27 to 28: Database Query Optimization
+ *
+ * Adds indexes to improve query performance for:
+ * - Manga searches by source, title, author
+ * - History queries with deleted_at filtering and updated_at ordering
+ * - Track queries for new chapters and last chapter date
+ * - Bookmark lookups by manga_id
+ * - Scrobbling lookups by manga_id
+ */
+class Migration27To28 : Migration(27, 28) {
+
+	override fun migrate(db: SupportSQLiteDatabase) {
+		// Manga table indexes
+		db.execSQL("CREATE INDEX IF NOT EXISTS index_manga_source ON manga(source)")
+		db.execSQL("CREATE INDEX IF NOT EXISTS index_manga_title ON manga(title)")
+		db.execSQL("CREATE INDEX IF NOT EXISTS index_manga_public_url ON manga(public_url)")
+		
+		// History table indexes for common query patterns
+		db.execSQL("CREATE INDEX IF NOT EXISTS index_history_deleted_at ON history(deleted_at)")
+		db.execSQL("CREATE INDEX IF NOT EXISTS index_history_updated_at ON history(updated_at)")
+		db.execSQL("CREATE INDEX IF NOT EXISTS index_history_created_at ON history(created_at)")
+		db.execSQL("CREATE INDEX IF NOT EXISTS index_history_percent ON history(percent)")
+		// Composite index for the most common history query pattern
+		db.execSQL("CREATE INDEX IF NOT EXISTS index_history_deleted_updated ON history(deleted_at, updated_at DESC)")
+		
+		// Tracks table indexes for sorting and filtering
+		db.execSQL("CREATE INDEX IF NOT EXISTS index_tracks_chapters_new ON tracks(chapters_new)")
+		db.execSQL("CREATE INDEX IF NOT EXISTS index_tracks_last_chapter_date ON tracks(last_chapter_date)")
+		db.execSQL("CREATE INDEX IF NOT EXISTS index_tracks_last_check_time ON tracks(last_check_time)")
+		
+		// Favourites additional indexes (composite for common queries)
+		db.execSQL("CREATE INDEX IF NOT EXISTS index_favourites_deleted_created ON favourites(deleted_at, created_at DESC)")
+		
+		// Bookmarks index for manga lookups
+		db.execSQL("CREATE INDEX IF NOT EXISTS index_bookmarks_manga_id ON bookmarks(manga_id)")
+		
+		// Scrobblings index for manga lookups
+		db.execSQL("CREATE INDEX IF NOT EXISTS index_scrobblings_manga_id ON scrobblings(manga_id)")
+		
+		// Local index table optimization
+		db.execSQL("CREATE INDEX IF NOT EXISTS index_local_index_manga_id ON local_index(manga_id)")
+		
+		// Suggestions index
+		db.execSQL("CREATE INDEX IF NOT EXISTS index_suggestions_manga_id ON suggestions(manga_id)")
+		
+		// Tags index for title searches
+		db.execSQL("CREATE INDEX IF NOT EXISTS index_tags_title ON tags(title)")
+		
+		// Track logs index for efficient lookups
+		db.execSQL("CREATE INDEX IF NOT EXISTS index_track_logs_manga_id ON track_logs(manga_id)")
+		db.execSQL("CREATE INDEX IF NOT EXISTS index_track_logs_created_at ON track_logs(created_at)")
+		
+		// Stats table indexes
+		db.execSQL("CREATE INDEX IF NOT EXISTS index_stats_manga_id ON stats(manga_id)")
+		db.execSQL("CREATE INDEX IF NOT EXISTS index_stats_started_at ON stats(started_at)")
+		
+		// Run ANALYZE to update query planner statistics
+		db.execSQL("ANALYZE")
+	}
+}
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/history/data/HistoryEntity.kt b/app/src/main/kotlin/org/koitharu/kotatsu/history/data/HistoryEntity.kt
index 421565d..045a1c3 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/history/data/HistoryEntity.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/history/data/HistoryEntity.kt
@@ -3,6 +3,7 @@ package org.koitharu.kotatsu.history.data
 import androidx.room.ColumnInfo
 import androidx.room.Entity
 import androidx.room.ForeignKey
+import androidx.room.Index
 import androidx.room.PrimaryKey
 import org.koitharu.kotatsu.core.db.TABLE_HISTORY
 import org.koitharu.kotatsu.core.db.entity.MangaEntity
@@ -17,6 +18,13 @@ import org.koitharu.kotatsu.core.db.entity.MangaEntity
 			onDelete = ForeignKey.CASCADE,
 		),
 	],
+	indices = [
+		Index(value = ["deleted_at"]),
+		Index(value = ["updated_at"]),
+		Index(value = ["created_at"]),
+		Index(value = ["percent"]),
+		Index(value = ["deleted_at", "updated_at"]),
+	],
 )
 data class HistoryEntity(
 	@PrimaryKey(autoGenerate = false)
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/tracker/data/TrackEntity.kt b/app/src/main/kotlin/org/koitharu/kotatsu/tracker/data/TrackEntity.kt
index 925508f..0e14643 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/tracker/data/TrackEntity.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/tracker/data/TrackEntity.kt
@@ -4,6 +4,7 @@ import androidx.annotation.IntDef
 import androidx.room.ColumnInfo
 import androidx.room.Entity
 import androidx.room.ForeignKey
+import androidx.room.Index
 import androidx.room.PrimaryKey
 import org.koitharu.kotatsu.core.db.entity.MangaEntity
 
@@ -17,6 +18,11 @@ import org.koitharu.kotatsu.core.db.entity.MangaEntity
 			onDelete = ForeignKey.CASCADE,
 		),
 	],
+	indices = [
+		Index(value = ["chapters_new"]),
+		Index(value = ["last_chapter_date"]),
+		Index(value = ["last_check_time"]),
+	],
 )
 class TrackEntity(
 	@PrimaryKey(autoGenerate = false)

From bb33f23ebb80563ce59ecbcbf622fc17116bc945 Mon Sep 17 00:00:00 2001
From: AgentKush <finlayhansford66@gmail.com>
Date: Thu, 22 Jan 2026 08:19:54 +0000
Subject: [PATCH 27/35] Improvement #10: Enhanced App Update Check

Implements automatic background checking for app updates with notifications:

Core Components:
- AppUpdateCheckWorker: Background worker for periodic update checks using WorkManager
  - Configurable check interval (6/12/24/48/72 hours, default: 24)
  - WiFi-only option for data-conscious users
  - Respects user preferences for stable/unstable releases
  - Exponential backoff retry policy (max 3 attempts)
  - Flex interval (25% of check interval) for WorkManager optimization
  - Requires battery not low + network connectivity

- AppUpdateNotifier: Rich notification system for available updates
  - Notification channel 'app_updates' with low importance
  - Displays version name, APK size, and changelog preview (first 3 lines)
  - Two actions: Download (opens AppUpdateActivity) and Dismiss
  - Handles Android 13+ notification permission check

- AppUpdateDismissReceiver: Broadcast receiver for notification dismissal

Settings Integration:
- isAutoUpdateCheckEnabled: Toggle background checks (default: true)
- updateCheckIntervalHours: Check frequency selection
- isUpdateCheckWifiOnly: Restrict checks to WiFi (default: false)
- lastUpdateCheckTime: Timestamp tracking for check scheduling
- skipVersion/isVersionSkipped: Allow users to skip specific versions

WorkScheduleManager Integration:
- Automatic scheduling on app startup
- Reschedules when relevant settings change
- Proper cancellation when feature disabled

AppUpdateViewModel Enhancement:
- Added skipCurrentVersion() method for UI integration
- Injected AppSettings for version skip functionality
---
 app/src/main/AndroidManifest.xml              |   3 +
 .../core/github/AppUpdateCheckWorker.kt       | 129 +++++++++++++++
 .../core/github/AppUpdateDismissReceiver.kt   |  21 +++
 .../kotatsu/core/github/AppUpdateNotifier.kt  | 153 ++++++++++++++++++
 .../kotatsu/core/prefs/AppSettings.kt         |  37 +++++
 .../settings/about/AppUpdateViewModel.kt      |  12 ++
 .../settings/work/WorkScheduleManager.kt      |  12 ++
 7 files changed, 367 insertions(+)
 create mode 100644 app/src/main/kotlin/org/koitharu/kotatsu/core/github/AppUpdateCheckWorker.kt
 create mode 100644 app/src/main/kotlin/org/koitharu/kotatsu/core/github/AppUpdateDismissReceiver.kt
 create mode 100644 app/src/main/kotlin/org/koitharu/kotatsu/core/github/AppUpdateNotifier.kt

diff --git a/app/src/main/AndroidManifest.xml b/app/src/main/AndroidManifest.xml
index d23fea7..b1a7745 100644
--- a/app/src/main/AndroidManifest.xml
+++ b/app/src/main/AndroidManifest.xml
@@ -445,6 +445,9 @@
 				<action android:name="${applicationId}.action.REPORT_ERROR" />
 			</intent-filter>
 		</receiver>
+		<receiver
+			android:name="org.koitharu.kotatsu.core.github.AppUpdateDismissReceiver"
+			android:exported="false" />
 
 		<meta-data
 			android:name="android.webkit.WebView.EnableSafeBrowsing"
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/github/AppUpdateCheckWorker.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/github/AppUpdateCheckWorker.kt
new file mode 100644
index 0000000..cd1506e
--- /dev/null
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/github/AppUpdateCheckWorker.kt
@@ -0,0 +1,129 @@
+package org.koitharu.kotatsu.core.github
+
+import android.content.Context
+import androidx.hilt.work.HiltWorker
+import androidx.work.BackoffPolicy
+import androidx.work.Constraints
+import androidx.work.CoroutineWorker
+import androidx.work.ExistingPeriodicWorkPolicy
+import androidx.work.NetworkType
+import androidx.work.PeriodicWorkRequestBuilder
+import androidx.work.WorkManager
+import androidx.work.WorkerParameters
+import dagger.assisted.Assisted
+import dagger.assisted.AssistedInject
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+import org.koitharu.kotatsu.core.prefs.AppSettings
+import java.util.concurrent.TimeUnit
+
+/**
+ * Background worker that periodically checks for app updates.
+ *
+ * Features:
+ * - Configurable check interval (default: daily)
+ * - WiFi-only option for data-conscious users
+ * - Respects user preferences for update channels
+ * - Shows notification when update is available
+ */
+@HiltWorker
+class AppUpdateCheckWorker @AssistedInject constructor(
+	@Assisted appContext: Context,
+	@Assisted params: WorkerParameters,
+	private val updateRepository: AppUpdateRepository,
+	private val updateNotifier: AppUpdateNotifier,
+	private val settings: AppSettings,
+) : CoroutineWorker(appContext, params) {
+
+	override suspend fun doWork(): Result = withContext(Dispatchers.IO) {
+		try {
+			// Check if auto-update check is enabled
+			if (!settings.isAutoUpdateCheckEnabled) {
+				return@withContext Result.success()
+			}
+
+			// Fetch available update
+			val update = updateRepository.fetchUpdate()
+
+			if (update != null) {
+				// Check if this version was previously skipped
+				if (!settings.isVersionSkipped(update.name)) {
+					updateNotifier.showUpdateNotification(update)
+				}
+			}
+
+			// Update last check time
+			settings.lastUpdateCheckTime = System.currentTimeMillis()
+
+			Result.success()
+		} catch (e: Exception) {
+			if (runAttemptCount < MAX_RETRY_COUNT) {
+				Result.retry()
+			} else {
+				Result.failure()
+			}
+		}
+	}
+
+	companion object {
+		private const val WORK_NAME = "app_update_check"
+		private const val MAX_RETRY_COUNT = 3
+
+		/**
+		 * Schedule periodic update checks.
+		 */
+		fun schedule(context: Context, settings: AppSettings) {
+			val workManager = WorkManager.getInstance(context)
+
+			if (!settings.isAutoUpdateCheckEnabled) {
+				workManager.cancelUniqueWork(WORK_NAME)
+				return
+			}
+
+			val intervalHours = settings.updateCheckIntervalHours.toLong()
+
+			val constraints = Constraints.Builder()
+				.setRequiredNetworkType(
+					if (settings.isUpdateCheckWifiOnly) NetworkType.UNMETERED
+					else NetworkType.CONNECTED
+				)
+				.setRequiresBatteryNotLow(true)
+				.build()
+
+			val request = PeriodicWorkRequestBuilder<AppUpdateCheckWorker>(
+				intervalHours, TimeUnit.HOURS,
+				intervalHours / 4, TimeUnit.HOURS, // Flex interval
+			)
+				.setConstraints(constraints)
+				.setBackoffCriteria(BackoffPolicy.EXPONENTIAL, 30, TimeUnit.MINUTES)
+				.build()
+
+			workManager.enqueueUniquePeriodicWork(
+				WORK_NAME,
+				ExistingPeriodicWorkPolicy.UPDATE,
+				request,
+			)
+		}
+
+		/**
+		 * Cancel scheduled update checks.
+		 */
+		fun cancel(context: Context) {
+			WorkManager.getInstance(context).cancelUniqueWork(WORK_NAME)
+		}
+
+		/**
+		 * Run an immediate update check.
+		 */
+		fun checkNow(context: Context) {
+			val request = androidx.work.OneTimeWorkRequestBuilder<AppUpdateCheckWorker>()
+				.setConstraints(
+					Constraints.Builder()
+						.setRequiredNetworkType(NetworkType.CONNECTED)
+						.build()
+				)
+				.build()
+			WorkManager.getInstance(context).enqueue(request)
+		}
+	}
+}
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/github/AppUpdateDismissReceiver.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/github/AppUpdateDismissReceiver.kt
new file mode 100644
index 0000000..fa96161
--- /dev/null
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/github/AppUpdateDismissReceiver.kt
@@ -0,0 +1,21 @@
+package org.koitharu.kotatsu.core.github
+
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import dagger.hilt.android.AndroidEntryPoint
+import javax.inject.Inject
+
+/**
+ * Broadcast receiver for handling update notification dismissal.
+ */
+@AndroidEntryPoint
+class AppUpdateDismissReceiver : BroadcastReceiver() {
+
+	@Inject
+	lateinit var updateNotifier: AppUpdateNotifier
+
+	override fun onReceive(context: Context, intent: Intent) {
+		updateNotifier.cancelNotification()
+	}
+}
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/github/AppUpdateNotifier.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/github/AppUpdateNotifier.kt
new file mode 100644
index 0000000..cb3758e
--- /dev/null
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/github/AppUpdateNotifier.kt
@@ -0,0 +1,153 @@
+package org.koitharu.kotatsu.core.github
+
+import android.Manifest
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.PendingIntent
+import android.content.Context
+import android.content.Intent
+import android.content.pm.PackageManager
+import android.os.Build
+import androidx.core.app.NotificationCompat
+import androidx.core.app.NotificationManagerCompat
+import androidx.core.content.ContextCompat
+import dagger.hilt.android.qualifiers.ApplicationContext
+import org.koitharu.kotatsu.R
+import org.koitharu.kotatsu.core.util.FileSize
+import org.koitharu.kotatsu.settings.about.AppUpdateActivity
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Handles app update notifications.
+ */
+@Singleton
+class AppUpdateNotifier @Inject constructor(
+	@ApplicationContext private val context: Context,
+) {
+	private val notificationManager = NotificationManagerCompat.from(context)
+
+	init {
+		createNotificationChannel()
+	}
+
+	/**
+	 * Show a notification about an available update.
+	 */
+	fun showUpdateNotification(version: AppVersion) {
+		if (!hasNotificationPermission()) {
+			return
+		}
+
+		val intent = Intent(context, AppUpdateActivity::class.java).apply {
+			flags = Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TOP
+		}
+
+		val pendingIntent = PendingIntent.getActivity(
+			context,
+			NOTIFICATION_ID,
+			intent,
+			PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE,
+		)
+
+		val notification = NotificationCompat.Builder(context, CHANNEL_ID)
+			.setSmallIcon(R.drawable.ic_updated)
+			.setContentTitle(context.getString(R.string.new_version_s, version.name))
+			.setContentText(
+				context.getString(R.string.size_s, FileSize.BYTES.format(context, version.apkSize))
+			)
+			.setStyle(
+				NotificationCompat.BigTextStyle()
+					.bigText(buildNotificationText(version))
+			)
+			.setContentIntent(pendingIntent)
+			.setAutoCancel(true)
+			.setPriority(NotificationCompat.PRIORITY_LOW)
+			.setCategory(NotificationCompat.CATEGORY_RECOMMENDATION)
+			.addAction(
+				R.drawable.ic_download,
+				context.getString(R.string.download),
+				pendingIntent,
+			)
+			.addAction(
+				0,
+				context.getString(R.string.close),
+				createDismissIntent(),
+			)
+			.build()
+
+		notificationManager.notify(NOTIFICATION_ID, notification)
+	}
+
+	/**
+	 * Cancel the update notification.
+	 */
+	fun cancelNotification() {
+		notificationManager.cancel(NOTIFICATION_ID)
+	}
+
+	private fun buildNotificationText(version: AppVersion): String {
+		return buildString {
+			append(context.getString(R.string.new_version_s, version.name))
+			appendLine()
+			append(context.getString(R.string.size_s, FileSize.BYTES.format(context, version.apkSize)))
+
+			// Add first few lines of changelog if available
+			val changelog = version.description.lines()
+				.filter { it.isNotBlank() }
+				.take(3)
+			if (changelog.isNotEmpty()) {
+				appendLine()
+				appendLine()
+				append(context.getString(R.string.changelog))
+				append(":")
+				changelog.forEach { line ->
+					appendLine()
+					append("• ")
+					append(line.removePrefix("- ").removePrefix("* ").trim())
+				}
+			}
+		}
+	}
+
+	private fun createDismissIntent(): PendingIntent {
+		val intent = Intent(context, AppUpdateDismissReceiver::class.java)
+		return PendingIntent.getBroadcast(
+			context,
+			DISMISS_REQUEST_CODE,
+			intent,
+			PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE,
+		)
+	}
+
+	private fun createNotificationChannel() {
+		if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+			val channel = NotificationChannel(
+				CHANNEL_ID,
+				context.getString(R.string.updates),
+				NotificationManager.IMPORTANCE_LOW,
+			).apply {
+				description = context.getString(R.string.updates)
+				setShowBadge(true)
+			}
+			notificationManager.createNotificationChannel(channel)
+		}
+	}
+
+	private fun hasNotificationPermission(): Boolean {
+		return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+			ContextCompat.checkSelfPermission(
+				context,
+				Manifest.permission.POST_NOTIFICATIONS,
+			) == PackageManager.PERMISSION_GRANTED
+		} else {
+			true
+		}
+	}
+
+	companion object {
+		private const val CHANNEL_ID = "app_updates"
+		private const val NOTIFICATION_ID = 10001
+		private const val DISMISS_REQUEST_CODE = 10002
+	}
+}
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/prefs/AppSettings.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/prefs/AppSettings.kt
index 758ab4d..11c20dd 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/prefs/AppSettings.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/prefs/AppSettings.kt
@@ -324,6 +324,35 @@ class AppSettings @Inject constructor(@ApplicationContext context: Context) {
 	val isUnstableUpdatesAllowed: Boolean
 		get() = prefs.getBoolean(KEY_UPDATES_UNSTABLE, false)
 
+	/**
+	 * Enhanced App Update Check settings
+	 */
+	var isAutoUpdateCheckEnabled: Boolean
+		get() = prefs.getBoolean(KEY_AUTO_UPDATE_CHECK, true)
+		set(value) = prefs.edit { putBoolean(KEY_AUTO_UPDATE_CHECK, value) }
+
+	val isUpdateCheckWifiOnly: Boolean
+		get() = prefs.getBoolean(KEY_UPDATE_CHECK_WIFI_ONLY, false)
+
+	val updateCheckIntervalHours: Int
+		get() = prefs.getString(KEY_UPDATE_CHECK_INTERVAL, null)?.toIntOrNull() ?: DEFAULT_UPDATE_CHECK_INTERVAL_HOURS
+
+	var lastUpdateCheckTime: Long
+		get() = prefs.getLong(KEY_LAST_UPDATE_CHECK, 0L)
+		set(value) = prefs.edit { putLong(KEY_LAST_UPDATE_CHECK, value) }
+
+	fun isVersionSkipped(versionName: String): Boolean {
+		return prefs.getString(KEY_SKIPPED_UPDATE_VERSION, null) == versionName
+	}
+
+	fun skipVersion(versionName: String) {
+		prefs.edit { putString(KEY_SKIPPED_UPDATE_VERSION, versionName) }
+	}
+
+	fun clearSkippedVersion() {
+		prefs.edit { remove(KEY_SKIPPED_UPDATE_VERSION) }
+	}
+
 	val isPagesTabEnabled: Boolean
 		get() = prefs.getBoolean(KEY_PAGES_TAB, true)
 
@@ -801,6 +830,11 @@ class AppSettings @Inject constructor(@ApplicationContext context: Context) {
 		const val KEY_APP_LOCALE = "app_locale"
 		const val KEY_SOURCES_GRID = "sources_grid"
 		const val KEY_UPDATES_UNSTABLE = "updates_unstable"
+		const val KEY_AUTO_UPDATE_CHECK = "auto_update_check"
+		const val KEY_UPDATE_CHECK_WIFI_ONLY = "update_check_wifi_only"
+		const val KEY_UPDATE_CHECK_INTERVAL = "update_check_interval"
+		const val KEY_LAST_UPDATE_CHECK = "last_update_check"
+		const val KEY_SKIPPED_UPDATE_VERSION = "skipped_update_version"
 		const val KEY_TIPS_CLOSED = "tips_closed"
 		const val KEY_SSL_BYPASS = "ssl_bypass"
 		const val KEY_READER_AUTOSCROLL_SPEED = "as_speed"
@@ -887,5 +921,8 @@ class AppSettings @Inject constructor(@ApplicationContext context: Context) {
 
 		// tracker defaults
 		const val DEFAULT_TRACKER_PARALLELISM = 6
+
+		// update check defaults
+		const val DEFAULT_UPDATE_CHECK_INTERVAL_HOURS = 24
 	}
 }
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/settings/about/AppUpdateViewModel.kt b/app/src/main/kotlin/org/koitharu/kotatsu/settings/about/AppUpdateViewModel.kt
index cd5f0dc..f3b61ec 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/settings/about/AppUpdateViewModel.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/settings/about/AppUpdateViewModel.kt
@@ -14,6 +14,7 @@ import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.isActive
 import org.koitharu.kotatsu.R
 import org.koitharu.kotatsu.core.github.AppUpdateRepository
+import org.koitharu.kotatsu.core.prefs.AppSettings
 import org.koitharu.kotatsu.core.ui.BaseViewModel
 import org.koitharu.kotatsu.core.util.ext.MutableEventFlow
 import org.koitharu.kotatsu.core.util.ext.call
@@ -23,6 +24,7 @@ import javax.inject.Inject
 @HiltViewModel
 class AppUpdateViewModel @Inject constructor(
 	private val repository: AppUpdateRepository,
+	private val settings: AppSettings,
 	@ApplicationContext context: Context,
 ) : BaseViewModel() {
 
@@ -76,6 +78,16 @@ class AppUpdateViewModel @Inject constructor(
 		}
 	}
 
+	/**
+	 * Skip the current available update version.
+	 * The user won't be notified about this version again.
+	 */
+	fun skipCurrentVersion() {
+		nextVersion.value?.let { version ->
+			settings.skipVersion(version.name)
+		}
+	}
+
 	private suspend fun observeDownload(id: Long) {
 		val query = DownloadManager.Query()
 		query.setFilterById(id)
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/settings/work/WorkScheduleManager.kt b/app/src/main/kotlin/org/koitharu/kotatsu/settings/work/WorkScheduleManager.kt
index 794e964..88192e7 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/settings/work/WorkScheduleManager.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/settings/work/WorkScheduleManager.kt
@@ -1,8 +1,11 @@
 package org.koitharu.kotatsu.settings.work
 
+import android.content.Context
 import android.content.SharedPreferences
+import dagger.hilt.android.qualifiers.ApplicationContext
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.launch
+import org.koitharu.kotatsu.core.github.AppUpdateCheckWorker
 import org.koitharu.kotatsu.core.prefs.AppSettings
 import org.koitharu.kotatsu.core.util.ext.processLifecycleScope
 import org.koitharu.kotatsu.suggestions.ui.SuggestionsWorker
@@ -12,6 +15,7 @@ import javax.inject.Singleton
 
 @Singleton
 class WorkScheduleManager @Inject constructor(
+	@ApplicationContext private val context: Context,
 	private val settings: AppSettings,
 	private val suggestionScheduler: SuggestionsWorker.Scheduler,
 	private val trackerScheduler: TrackWorker.Scheduler,
@@ -33,6 +37,12 @@ class WorkScheduleManager @Inject constructor(
 				isEnabled = settings.isSuggestionsEnabled,
 				force = key != AppSettings.KEY_SUGGESTIONS,
 			)
+
+			AppSettings.KEY_AUTO_UPDATE_CHECK,
+			AppSettings.KEY_UPDATE_CHECK_WIFI_ONLY,
+			AppSettings.KEY_UPDATE_CHECK_INTERVAL -> {
+				AppUpdateCheckWorker.schedule(context, settings)
+			}
 		}
 	}
 
@@ -41,6 +51,8 @@ class WorkScheduleManager @Inject constructor(
 		processLifecycleScope.launch(Dispatchers.Default) {
 			updateWorkerImpl(trackerScheduler, settings.isTrackerEnabled, true) // always force due to adaptive interval
 			updateWorkerImpl(suggestionScheduler, settings.isSuggestionsEnabled, false)
+			// Schedule app update checks
+			AppUpdateCheckWorker.schedule(context, settings)
 		}
 	}
 

From 3b0022083c409f63a8433523249483bc8a4561b1 Mon Sep 17 00:00:00 2001
From: AgentKush <finlayhansford66@gmail.com>
Date: Thu, 22 Jan 2026 08:39:50 +0000
Subject: [PATCH 28/35] Improvement #11: Source Health Monitor

Implements tracking of source reliability and performance metrics:

Database Layer:
- SourceHealthEntity: Stores comprehensive health metrics per source
  - Success/failure counts for reliability calculation
  - Response time stats (avg, min, max) using exponential moving average
  - Consecutive failure tracking for detecting outages
  - Last error message storage (truncated to 200 chars)
  - Stats reset timestamp for data freshness

- SourceHealthDao: CRUD operations with health-aware queries
  - recordSuccess(): Updates counts, recalculates response time average
  - recordFailure(): Increments failure counts, stores error
  - getHealthySources(): Filter by minimum success rate
  - getFailingSources(): Find sources with high consecutive failures

- Migration28To29: Creates source_health table with index

Repository Layer:
- SourceHealthRepository: High-level API for health data
  - Query methods: by reliability score, by speed, by health status
  - HealthSummary: Aggregate stats across all tracked sources
  - Health status enum: UNKNOWN, HEALTHY, DEGRADED, POOR, CRITICAL

Health Metrics:
- Success rate: (success_count / total) * 100
- Reliability score (0-100): 70% from success rate + 30% from response time
  - Response time scoring: <1s=30pts, <2s=25pts, <3s=20pts, etc.
- Health status thresholds: >=80=HEALTHY, >=60=DEGRADED, >=40=POOR, <40=CRITICAL

Integration:
- SourceHealthTracker: Wraps operations to automatically record metrics
  - trackOperation(): Measures time, records success/failure
  - isSourceUnreliable(): Check if source has too many consecutive failures
  - Empty result detection for potential source issues
---
 .../koitharu/kotatsu/core/db/MangaDatabase.kt |  10 +-
 .../org/koitharu/kotatsu/core/db/Tables.kt    |   1 +
 .../kotatsu/core/db/dao/SourceHealthDao.kt    | 129 ++++++++++++++
 .../core/db/entity/SourceHealthEntity.kt      | 113 ++++++++++++
 .../core/db/migrations/Migration28To29.kt     |  36 ++++
 .../core/parser/SourceHealthTracker.kt        | 123 +++++++++++++
 .../explore/data/SourceHealthRepository.kt    | 167 ++++++++++++++++++
 7 files changed, 577 insertions(+), 2 deletions(-)
 create mode 100644 app/src/main/kotlin/org/koitharu/kotatsu/core/db/dao/SourceHealthDao.kt
 create mode 100644 app/src/main/kotlin/org/koitharu/kotatsu/core/db/entity/SourceHealthEntity.kt
 create mode 100644 app/src/main/kotlin/org/koitharu/kotatsu/core/db/migrations/Migration28To29.kt
 create mode 100644 app/src/main/kotlin/org/koitharu/kotatsu/core/parser/SourceHealthTracker.kt
 create mode 100644 app/src/main/kotlin/org/koitharu/kotatsu/explore/data/SourceHealthRepository.kt

diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/db/MangaDatabase.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/db/MangaDatabase.kt
index 2a6c3df..abae6f7 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/db/MangaDatabase.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/db/MangaDatabase.kt
@@ -16,6 +16,7 @@ import org.koitharu.kotatsu.core.db.dao.ChaptersDao
 import org.koitharu.kotatsu.core.db.dao.MangaDao
 import org.koitharu.kotatsu.core.db.dao.MangaSourcesDao
 import org.koitharu.kotatsu.core.db.dao.PreferencesDao
+import org.koitharu.kotatsu.core.db.dao.SourceHealthDao
 import org.koitharu.kotatsu.core.db.dao.TagsDao
 import org.koitharu.kotatsu.core.db.dao.TrackLogsDao
 import org.koitharu.kotatsu.core.db.entity.ChapterEntity
@@ -23,6 +24,7 @@ import org.koitharu.kotatsu.core.db.entity.MangaEntity
 import org.koitharu.kotatsu.core.db.entity.MangaPrefsEntity
 import org.koitharu.kotatsu.core.db.entity.MangaSourceEntity
 import org.koitharu.kotatsu.core.db.entity.MangaTagsEntity
+import org.koitharu.kotatsu.core.db.entity.SourceHealthEntity
 import org.koitharu.kotatsu.core.db.entity.TagEntity
 import org.koitharu.kotatsu.core.db.migrations.Migration10To11
 import org.koitharu.kotatsu.core.db.migrations.Migration11To12
@@ -44,6 +46,7 @@ import org.koitharu.kotatsu.core.db.migrations.Migration24To25
 import org.koitharu.kotatsu.core.db.migrations.Migration25To26
 import org.koitharu.kotatsu.core.db.migrations.Migration26To27
 import org.koitharu.kotatsu.core.db.migrations.Migration27To28
+import org.koitharu.kotatsu.core.db.migrations.Migration28To29
 import org.koitharu.kotatsu.core.db.migrations.Migration2To3
 import org.koitharu.kotatsu.core.db.migrations.Migration3To4
 import org.koitharu.kotatsu.core.db.migrations.Migration4To5
@@ -71,14 +74,14 @@ import org.koitharu.kotatsu.tracker.data.TrackEntity
 import org.koitharu.kotatsu.tracker.data.TrackLogEntity
 import org.koitharu.kotatsu.tracker.data.TracksDao
 
-const val DATABASE_VERSION = 28
+const val DATABASE_VERSION = 29
 
 @Database(
 	entities = [
 		MangaEntity::class, TagEntity::class, HistoryEntity::class, MangaTagsEntity::class, ChapterEntity::class,
 		FavouriteCategoryEntity::class, FavouriteEntity::class, MangaPrefsEntity::class, TrackEntity::class,
 		TrackLogEntity::class, SuggestionEntity::class, BookmarkEntity::class, ScrobblingEntity::class,
-		MangaSourceEntity::class, StatsEntity::class, LocalMangaIndexEntity::class,
+		MangaSourceEntity::class, StatsEntity::class, LocalMangaIndexEntity::class, SourceHealthEntity::class,
 	],
 	version = DATABASE_VERSION,
 )
@@ -113,6 +116,8 @@ abstract class MangaDatabase : RoomDatabase() {
 	abstract fun getLocalMangaIndexDao(): LocalMangaIndexDao
 
 	abstract fun getChaptersDao(): ChaptersDao
+
+	abstract fun getSourceHealthDao(): SourceHealthDao
 }
 
 fun getDatabaseMigrations(context: Context): Array<Migration> = arrayOf(
@@ -144,6 +149,7 @@ fun getDatabaseMigrations(context: Context): Array<Migration> = arrayOf(
 	Migration25To26(),
 	Migration26To27(),
 	Migration27To28(),
+	Migration28To29(),
 )
 
 fun MangaDatabase(context: Context): MangaDatabase = Room
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/db/Tables.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/db/Tables.kt
index cbd87b5..6fd0ea1 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/db/Tables.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/db/Tables.kt
@@ -9,3 +9,4 @@ const val TABLE_MANGA_TAGS = "manga_tags"
 const val TABLE_SOURCES = "sources"
 const val TABLE_CHAPTERS = "chapters"
 const val TABLE_PREFERENCES = "preferences"
+const val TABLE_SOURCE_HEALTH = "source_health"
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/db/dao/SourceHealthDao.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/db/dao/SourceHealthDao.kt
new file mode 100644
index 0000000..467dae3
--- /dev/null
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/db/dao/SourceHealthDao.kt
@@ -0,0 +1,129 @@
+package org.koitharu.kotatsu.core.db.dao
+
+import androidx.room.Dao
+import androidx.room.Insert
+import androidx.room.OnConflictStrategy
+import androidx.room.Query
+import androidx.room.Transaction
+import kotlinx.coroutines.flow.Flow
+import org.koitharu.kotatsu.core.db.entity.SourceHealthEntity
+
+@Dao
+abstract class SourceHealthDao {
+
+	@Query("SELECT * FROM source_health WHERE source = :source")
+	abstract suspend fun get(source: String): SourceHealthEntity?
+
+	@Query("SELECT * FROM source_health WHERE source = :source")
+	abstract fun observe(source: String): Flow<SourceHealthEntity?>
+
+	@Query("SELECT * FROM source_health ORDER BY (success_count + failure_count) DESC")
+	abstract suspend fun getAll(): List<SourceHealthEntity>
+
+	@Query("SELECT * FROM source_health ORDER BY (success_count + failure_count) DESC")
+	abstract fun observeAll(): Flow<List<SourceHealthEntity>>
+
+	@Query("SELECT * FROM source_health WHERE (CAST(success_count AS REAL) / (success_count + failure_count)) * 100 >= :minSuccessRate ORDER BY avg_response_time ASC")
+	abstract suspend fun getHealthySources(minSuccessRate: Float = 80f): List<SourceHealthEntity>
+
+	@Query("SELECT * FROM source_health WHERE consecutive_failures >= :threshold")
+	abstract suspend fun getFailingSources(threshold: Int = 3): List<SourceHealthEntity>
+
+	@Insert(onConflict = OnConflictStrategy.REPLACE)
+	abstract suspend fun upsert(entity: SourceHealthEntity)
+
+	@Query("DELETE FROM source_health WHERE source = :source")
+	abstract suspend fun delete(source: String)
+
+	@Query("DELETE FROM source_health")
+	abstract suspend fun deleteAll()
+
+	/**
+	 * Record a successful request for a source
+	 */
+	@Transaction
+	open suspend fun recordSuccess(source: String, responseTimeMs: Long) {
+		val existing = get(source)
+		val now = System.currentTimeMillis()
+		
+		if (existing == null) {
+			upsert(
+				SourceHealthEntity(
+					source = source,
+					successCount = 1,
+					failureCount = 0,
+					avgResponseTime = responseTimeMs,
+					minResponseTime = responseTimeMs,
+					maxResponseTime = responseTimeMs,
+					lastSuccessAt = now,
+					consecutiveFailures = 0,
+				)
+			)
+		} else {
+			val totalRequests = existing.successCount + existing.failureCount + 1
+			// Exponential moving average for response time (weight recent more heavily)
+			val newAvg = if (existing.avgResponseTime > 0) {
+				((existing.avgResponseTime * 0.7) + (responseTimeMs * 0.3)).toLong()
+			} else {
+				responseTimeMs
+			}
+			
+			upsert(
+				existing.copy(
+					successCount = existing.successCount + 1,
+					avgResponseTime = newAvg,
+					minResponseTime = minOf(existing.minResponseTime, responseTimeMs),
+					maxResponseTime = maxOf(existing.maxResponseTime, responseTimeMs),
+					lastSuccessAt = now,
+					consecutiveFailures = 0, // Reset on success
+				)
+			)
+		}
+	}
+
+	/**
+	 * Record a failed request for a source
+	 */
+	@Transaction
+	open suspend fun recordFailure(source: String, errorMessage: String?) {
+		val existing = get(source)
+		val now = System.currentTimeMillis()
+		val truncatedError = errorMessage?.take(200)
+		
+		if (existing == null) {
+			upsert(
+				SourceHealthEntity(
+					source = source,
+					successCount = 0,
+					failureCount = 1,
+					lastFailureAt = now,
+					lastError = truncatedError,
+					consecutiveFailures = 1,
+				)
+			)
+		} else {
+			upsert(
+				existing.copy(
+					failureCount = existing.failureCount + 1,
+					lastFailureAt = now,
+					lastError = truncatedError,
+					consecutiveFailures = existing.consecutiveFailures + 1,
+				)
+			)
+		}
+	}
+
+	/**
+	 * Reset statistics for a specific source
+	 */
+	@Transaction
+	open suspend fun resetStats(source: String) {
+		val existing = get(source) ?: return
+		upsert(
+			SourceHealthEntity(
+				source = source,
+				statsResetAt = System.currentTimeMillis(),
+			)
+		)
+	}
+}
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/db/entity/SourceHealthEntity.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/db/entity/SourceHealthEntity.kt
new file mode 100644
index 0000000..a09ba3e
--- /dev/null
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/db/entity/SourceHealthEntity.kt
@@ -0,0 +1,113 @@
+package org.koitharu.kotatsu.core.db.entity
+
+import androidx.room.ColumnInfo
+import androidx.room.Entity
+import androidx.room.PrimaryKey
+import org.koitharu.kotatsu.core.db.TABLE_SOURCE_HEALTH
+
+/**
+ * Entity for tracking source health metrics.
+ * Records success/failure counts, response times, and reliability scores.
+ */
+@Entity(tableName = TABLE_SOURCE_HEALTH)
+data class SourceHealthEntity(
+	@PrimaryKey(autoGenerate = false)
+	@ColumnInfo(name = "source")
+	val source: String,
+
+	/** Total number of successful requests */
+	@ColumnInfo(name = "success_count")
+	val successCount: Long = 0L,
+
+	/** Total number of failed requests */
+	@ColumnInfo(name = "failure_count")
+	val failureCount: Long = 0L,
+
+	/** Average response time in milliseconds (rolling average) */
+	@ColumnInfo(name = "avg_response_time")
+	val avgResponseTime: Long = 0L,
+
+	/** Minimum response time observed */
+	@ColumnInfo(name = "min_response_time")
+	val minResponseTime: Long = Long.MAX_VALUE,
+
+	/** Maximum response time observed */
+	@ColumnInfo(name = "max_response_time")
+	val maxResponseTime: Long = 0L,
+
+	/** Timestamp of last successful request */
+	@ColumnInfo(name = "last_success_at")
+	val lastSuccessAt: Long = 0L,
+
+	/** Timestamp of last failed request */
+	@ColumnInfo(name = "last_failure_at")
+	val lastFailureAt: Long = 0L,
+
+	/** Most recent error message (truncated) */
+	@ColumnInfo(name = "last_error")
+	val lastError: String? = null,
+
+	/** Number of consecutive failures (reset on success) */
+	@ColumnInfo(name = "consecutive_failures")
+	val consecutiveFailures: Int = 0,
+
+	/** Timestamp when stats were last reset */
+	@ColumnInfo(name = "stats_reset_at")
+	val statsResetAt: Long = System.currentTimeMillis(),
+) {
+	/**
+	 * Calculate success rate as a percentage (0-100)
+	 */
+	val successRate: Float
+		get() {
+			val total = successCount + failureCount
+			return if (total > 0) (successCount.toFloat() / total) * 100f else 0f
+		}
+
+	/**
+	 * Calculate reliability score (0-100) based on success rate and response time
+	 */
+	val reliabilityScore: Float
+		get() {
+			val total = successCount + failureCount
+			if (total == 0L) return 0f
+
+			// Base score from success rate (0-70 points)
+			val successScore = successRate * 0.7f
+
+			// Response time score (0-30 points)
+			// Target: < 1000ms = 30 points, > 5000ms = 0 points
+			val responseScore = when {
+				avgResponseTime <= 0 -> 15f // No data, neutral
+				avgResponseTime < 1000 -> 30f
+				avgResponseTime < 2000 -> 25f
+				avgResponseTime < 3000 -> 20f
+				avgResponseTime < 4000 -> 15f
+				avgResponseTime < 5000 -> 10f
+				else -> 5f
+			}
+
+			return successScore + responseScore
+		}
+
+	/**
+	 * Determine health status based on reliability score
+	 */
+	val healthStatus: HealthStatus
+		get() = when {
+			successCount + failureCount == 0L -> HealthStatus.UNKNOWN
+			consecutiveFailures >= 5 -> HealthStatus.CRITICAL
+			reliabilityScore >= 80f -> HealthStatus.HEALTHY
+			reliabilityScore >= 60f -> HealthStatus.DEGRADED
+			reliabilityScore >= 40f -> HealthStatus.POOR
+			else -> HealthStatus.CRITICAL
+		}
+
+	enum class HealthStatus {
+		UNKNOWN,
+		HEALTHY,
+		DEGRADED,
+		POOR,
+		CRITICAL
+	}
+}
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/db/migrations/Migration28To29.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/db/migrations/Migration28To29.kt
new file mode 100644
index 0000000..f129fc5
--- /dev/null
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/db/migrations/Migration28To29.kt
@@ -0,0 +1,36 @@
+package org.koitharu.kotatsu.core.db.migrations
+
+import androidx.room.migration.Migration
+import androidx.sqlite.db.SupportSQLiteDatabase
+
+/**
+ * Migration 28 to 29: Source Health Monitor
+ *
+ * Creates the source_health table to track reliability and performance metrics
+ * for manga sources including success/failure rates, response times, and error history.
+ */
+class Migration28To29 : Migration(28, 29) {
+
+	override fun migrate(db: SupportSQLiteDatabase) {
+		db.execSQL(
+			"""
+			CREATE TABLE IF NOT EXISTS source_health (
+				source TEXT NOT NULL PRIMARY KEY,
+				success_count INTEGER NOT NULL DEFAULT 0,
+				failure_count INTEGER NOT NULL DEFAULT 0,
+				avg_response_time INTEGER NOT NULL DEFAULT 0,
+				min_response_time INTEGER NOT NULL DEFAULT 9223372036854775807,
+				max_response_time INTEGER NOT NULL DEFAULT 0,
+				last_success_at INTEGER NOT NULL DEFAULT 0,
+				last_failure_at INTEGER NOT NULL DEFAULT 0,
+				last_error TEXT,
+				consecutive_failures INTEGER NOT NULL DEFAULT 0,
+				stats_reset_at INTEGER NOT NULL DEFAULT 0
+			)
+			""".trimIndent()
+		)
+		
+		// Add index for efficient queries on health status
+		db.execSQL("CREATE INDEX IF NOT EXISTS index_source_health_consecutive_failures ON source_health(consecutive_failures)")
+	}
+}
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/parser/SourceHealthTracker.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/parser/SourceHealthTracker.kt
new file mode 100644
index 0000000..7514c71
--- /dev/null
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/parser/SourceHealthTracker.kt
@@ -0,0 +1,123 @@
+package org.koitharu.kotatsu.core.parser
+
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+import org.koitharu.kotatsu.explore.data.SourceHealthRepository
+import org.koitharu.kotatsu.parsers.model.MangaSource
+import org.koitharu.kotatsu.parsers.util.runCatchingCancellable
+import javax.inject.Inject
+import javax.inject.Singleton
+import kotlin.system.measureTimeMillis
+
+/**
+ * Tracks health metrics for manga sources.
+ * Wraps network operations to automatically record success/failure and response times.
+ */
+@Singleton
+class SourceHealthTracker @Inject constructor(
+	private val healthRepository: SourceHealthRepository,
+) {
+	/**
+	 * Execute an operation and track its health metrics.
+	 * Records success with response time, or failure with error message.
+	 * 
+	 * @param source The manga source being accessed
+	 * @param operation The suspend operation to execute
+	 * @return The result of the operation
+	 */
+	suspend fun <T> trackOperation(
+		source: MangaSource,
+		operation: suspend () -> T
+	): T {
+		var responseTime = 0L
+		val result = runCatchingCancellable {
+			var operationResult: T
+			responseTime = measureTimeMillis {
+				operationResult = operation()
+			}
+			operationResult
+		}
+		
+		// Record metrics in background
+		withContext(Dispatchers.Default) {
+			result.fold(
+				onSuccess = {
+					// Validate result - empty collections may indicate issues
+					val isValidResult = when (it) {
+						is Collection<*> -> it.isNotEmpty()
+						is String -> it.isNotEmpty()
+						else -> true
+					}
+					if (isValidResult) {
+						healthRepository.recordSuccess(source, responseTime)
+					} else {
+						// Empty result might indicate a source issue
+						healthRepository.recordFailure(source, EmptyResultException())
+					}
+				},
+				onFailure = { error ->
+					healthRepository.recordFailure(source, error)
+				}
+			)
+		}
+		
+		return result.getOrThrow()
+	}
+
+	/**
+	 * Execute an operation that returns a nullable result and track its health metrics.
+	 * Null results are treated as successful if expected.
+	 */
+	suspend fun <T> trackNullableOperation(
+		source: MangaSource,
+		operation: suspend () -> T?
+	): T? {
+		var responseTime = 0L
+		val result = runCatchingCancellable {
+			var operationResult: T?
+			responseTime = measureTimeMillis {
+				operationResult = operation()
+			}
+			operationResult
+		}
+		
+		withContext(Dispatchers.Default) {
+			result.fold(
+				onSuccess = {
+					healthRepository.recordSuccess(source, responseTime)
+				},
+				onFailure = { error ->
+					healthRepository.recordFailure(source, error)
+				}
+			)
+		}
+		
+		return result.getOrThrow()
+	}
+
+	/**
+	 * Record a manual success for operations tracked externally
+	 */
+	suspend fun recordSuccess(source: MangaSource, responseTimeMs: Long) {
+		healthRepository.recordSuccess(source, responseTimeMs)
+	}
+
+	/**
+	 * Record a manual failure for operations tracked externally
+	 */
+	suspend fun recordFailure(source: MangaSource, error: Throwable?) {
+		healthRepository.recordFailure(source, error)
+	}
+
+	/**
+	 * Check if a source is currently unreliable (many consecutive failures)
+	 */
+	suspend fun isSourceUnreliable(source: MangaSource): Boolean {
+		return healthRepository.isSourceUnreliable(source)
+	}
+
+	/**
+	 * Exception for empty results that shouldn't necessarily fail but indicate potential issues
+	 */
+	class EmptyResultException : Exception("Operation returned empty result")
+}
diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/explore/data/SourceHealthRepository.kt b/app/src/main/kotlin/org/koitharu/kotatsu/explore/data/SourceHealthRepository.kt
new file mode 100644
index 0000000..ca32b11
--- /dev/null
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/explore/data/SourceHealthRepository.kt
@@ -0,0 +1,167 @@
+package org.koitharu.kotatsu.explore.data
+
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.map
+import org.koitharu.kotatsu.core.db.MangaDatabase
+import org.koitharu.kotatsu.core.db.dao.SourceHealthDao
+import org.koitharu.kotatsu.core.db.entity.SourceHealthEntity
+import org.koitharu.kotatsu.parsers.model.MangaSource
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Repository for tracking and querying source health metrics.
+ * Provides methods to record successes/failures and query source reliability.
+ */
+@Singleton
+class SourceHealthRepository @Inject constructor(
+	private val db: MangaDatabase,
+) {
+	private val dao: SourceHealthDao
+		get() = db.getSourceHealthDao()
+
+	/**
+	 * Record a successful request for a source
+	 * @param source The manga source
+	 * @param responseTimeMs Response time in milliseconds
+	 */
+	suspend fun recordSuccess(source: MangaSource, responseTimeMs: Long) {
+		dao.recordSuccess(source.name, responseTimeMs)
+	}
+
+	/**
+	 * Record a failed request for a source
+	 * @param source The manga source
+	 * @param error The error that occurred
+	 */
+	suspend fun recordFailure(source: MangaSource, error: Throwable?) {
+		dao.recordFailure(source.name, error?.message)
+	}
+
+	/**
+	 * Get health metrics for a specific source
+	 */
+	suspend fun getHealth(source: MangaSource): SourceHealthEntity? {
+		return dao.get(source.name)
+	}
+
+	/**
+	 * Observe health metrics for a specific source
+	 */
+	fun observeHealth(source: MangaSource): Flow<SourceHealthEntity?> {
+		return dao.observe(source.name)
+	}
+
+	/**
+	 * Get all source health metrics
+	 */
+	suspend fun getAllHealth(): List<SourceHealthEntity> {
+		return dao.getAll()
+	}
+
+	/**
+	 * Observe all source health metrics
+	 */
+	fun observeAllHealth(): Flow<List<SourceHealthEntity>> {
+		return dao.observeAll()
+	}
+
+	/**
+	 * Get sources that meet a minimum success rate threshold
+	 * @param minSuccessRate Minimum success rate percentage (0-100)
+	 */
+	suspend fun getHealthySources(minSuccessRate: Float = 80f): List<SourceHealthEntity> {
+		return dao.getHealthySources(minSuccessRate)
+	}
+
+	/**
+	 * Get sources that are currently failing (high consecutive failures)
+	 * @param threshold Number of consecutive failures to consider as "failing"
+	 */
+	suspend fun getFailingSources(threshold: Int = 3): List<SourceHealthEntity> {
+		return dao.getFailingSources(threshold)
+	}
+
+	/**
+	 * Get sources sorted by reliability score (highest first)
+	 */
+	suspend fun getSourcesByReliability(): List<SourceHealthEntity> {
+		return dao.getAll().sortedByDescending { it.reliabilityScore }
+	}
+
+	/**
+	 * Get sources sorted by response time (fastest first)
+	 */
+	suspend fun getSourcesBySpeed(): List<SourceHealthEntity> {
+		return dao.getAll()
+			.filter { it.avgResponseTime > 0 }
+			.sortedBy { it.avgResponseTime }
+	}
+
+	/**
+	 * Observe source health with calculated summary stats
+	 */
+	fun observeHealthSummary(): Flow<HealthSummary> {
+		return dao.observeAll().map { entities ->
+			val total = entities.size
+			val healthy = entities.count { it.healthStatus == SourceHealthEntity.HealthStatus.HEALTHY }
+			val degraded = entities.count { it.healthStatus == SourceHealthEntity.HealthStatus.DEGRADED }
+			val poor = entities.count { it.healthStatus == SourceHealthEntity.HealthStatus.POOR }
+			val critical = entities.count { it.healthStatus == SourceHealthEntity.HealthStatus.CRITICAL }
+			val unknown = entities.count { it.healthStatus == SourceHealthEntity.HealthStatus.UNKNOWN }
+			val avgReliability = if (entities.isNotEmpty()) {
+				entities.filter { it.successCount + it.failureCount > 0 }
+					.map { it.reliabilityScore }
+					.average()
+					.toFloat()
+			} else 0f
+			
+			HealthSummary(
+				totalSources = total,
+				healthyCount = healthy,
+				degradedCount = degraded,
+				poorCount = poor,
+				criticalCount = critical,
+				unknownCount = unknown,
+				averageReliability = avgReliability,
+			)
+		}
+	}
+
+	/**
+	 * Reset statistics for a specific source
+	 */
+	suspend fun resetStats(source: MangaSource) {
+		dao.resetStats(source.name)
+	}
+
+	/**
+	 * Clear all health statistics
+	 */
+	suspend fun clearAllStats() {
+		dao.deleteAll()
+	}
+
+	/**
+	 * Check if a source should be considered unreliable
+	 * @param source The manga source to check
+	 * @param failureThreshold Number of consecutive failures to consider unreliable
+	 */
+	suspend fun isSourceUnreliable(source: MangaSource, failureThreshold: Int = 5): Boolean {
+		val health = dao.get(source.name) ?: return false
+		return health.consecutiveFailures >= failureThreshold
+	}
+
+	/**
+	 * Summary of health across all tracked sources
+	 */
+	data class HealthSummary(
+		val totalSources: Int,
+		val healthyCount: Int,
+		val degradedCount: Int,
+		val poorCount: Int,
+		val criticalCount: Int,
+		val unknownCount: Int,
+		val averageReliability: Float,
+	)
+}

From 639ddfaa18a84d49157580a35db77dff23d29b18 Mon Sep 17 00:00:00 2001
From: AgentKush <finlayhansford66@gmail.com>
Date: Thu, 22 Jan 2026 09:57:17 +0000
Subject: [PATCH 29/35] Add fallbackToDestructiveMigration for incompatible
 database schemas

When the app encounters an old database with an incompatible schema
(e.g., from a previous Kotatsu installation), Room will now drop all
tables and recreate the database instead of crashing with a migration
error. This ensures the app can always start fresh when migrations fail.
---
 .../main/kotlin/org/koitharu/kotatsu/core/db/MangaDatabase.kt  | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/db/MangaDatabase.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/db/MangaDatabase.kt
index abae6f7..1f87ec1 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/db/MangaDatabase.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/db/MangaDatabase.kt
@@ -23,8 +23,8 @@ import org.koitharu.kotatsu.core.db.entity.ChapterEntity
 import org.koitharu.kotatsu.core.db.entity.MangaEntity
 import org.koitharu.kotatsu.core.db.entity.MangaPrefsEntity
 import org.koitharu.kotatsu.core.db.entity.MangaSourceEntity
-import org.koitharu.kotatsu.core.db.entity.MangaTagsEntity
 import org.koitharu.kotatsu.core.db.entity.SourceHealthEntity
+import org.koitharu.kotatsu.core.db.entity.MangaTagsEntity
 import org.koitharu.kotatsu.core.db.entity.TagEntity
 import org.koitharu.kotatsu.core.db.migrations.Migration10To11
 import org.koitharu.kotatsu.core.db.migrations.Migration11To12
@@ -156,6 +156,7 @@ fun MangaDatabase(context: Context): MangaDatabase = Room
 	.databaseBuilder(context, MangaDatabase::class.java, "kotatsu-db")
 	.addMigrations(*getDatabaseMigrations(context))
 	.addCallback(DatabasePrePopulateCallback(context.resources))
+	.fallbackToDestructiveMigration(dropAllTables = true)
 	.build()
 
 fun InvalidationTracker.removeObserverAsync(observer: InvalidationTracker.Observer) {

From 6449afd4147e62af8bbe37aa6cbaf83cea32278a Mon Sep 17 00:00:00 2001
From: AgentKush <finlayhansford66@gmail.com>
Date: Thu, 22 Jan 2026 13:21:57 +0000
Subject: [PATCH 30/35] Fix memory leak in CaptchaHandler.onError()

The original ImageRequest was being retained in the coroutine, holding
a reference to the FragmentContextWrapper which kept the destroyed
MainActivity alive.

Fix: Extract only the necessary data (requestData, suppressCaptcha flag)
and rebuild the retry request using application context instead of
reusing the original request with its potentially stale context reference.
---
 .../core/exceptions/resolve/CaptchaHandler.kt     | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/exceptions/resolve/CaptchaHandler.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/exceptions/resolve/CaptchaHandler.kt
index 2b5ff69..fa041bf 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/exceptions/resolve/CaptchaHandler.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/exceptions/resolve/CaptchaHandler.kt
@@ -84,17 +84,24 @@ class CaptchaHandler @Inject constructor(
 		super.onError(request, result)
 		val e = result.throwable
 		if (e is CloudFlareException) {
-			val scope = request.lifecycle?.coroutineScope ?: processLifecycleScope
+			val lifecycle = request.lifecycle
+			val scope = lifecycle?.coroutineScope ?: processLifecycleScope
+			// Extract request data to avoid holding reference to potentially destroyed context
+			val requestData = request.data
+			val suppressCaptcha = request.extras[suppressCaptchaKey]
 			scope.launch {
 				if (
 					handleException(
 						source = e.source,
 						exception = e,
-						notify = request.extras[suppressCaptchaKey] != true,
+						notify = suppressCaptcha != true,
 					)
 				) {
-					// Retry the failed request now that captcha is resolved
-					coilProvider.get().enqueue(request)
+					// Rebuild the request with application context to avoid leaking Activity
+					val newRequest = ImageRequest.Builder(context)
+						.data(requestData)
+						.build()
+					coilProvider.get().enqueue(newRequest)
 				}
 			}
 		}

From 284df7cb521934fb539952c887b01922590a286b Mon Sep 17 00:00:00 2001
From: AgentKush <finlayhansford66@gmail.com>
Date: Thu, 22 Jan 2026 14:18:41 +0000
Subject: [PATCH 31/35] Update kotatsu-parsers to latest commit (b5b4d2cd43)

Includes recent fixes since v1.2 release:
- CloudFlare fixes for Gallery sources
- Rate-limit utility for some sources
- Yuri Garden API fixes
- Comix parser modernization
- MangaOkuTr domain update
- New XBatCat source
---
 gradle/libs.versions.toml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml
index 3f129a9..c59b157 100644
--- a/gradle/libs.versions.toml
+++ b/gradle/libs.versions.toml
@@ -35,8 +35,8 @@ material = "1.14.0-alpha05"
 moshi = "1.15.2"
 okhttp = "5.2.1"
 okio = "3.16.1"
-# YakaTeam/kotatsu-parsers - Updated to latest tagged release
-parsers = "1.2"
+# YakaTeam/kotatsu-parsers - Using latest commit for recent fixes
+parsers = "b5b4d2cd43"
 preference = "1.2.1"
 recyclerview = "1.4.0"
 room = "2.7.2"

From c939d741f7ba8f5bcf9649567052ab8faec43354 Mon Sep 17 00:00:00 2001
From: AgentKush <finlayhansford66@gmail.com>
Date: Thu, 22 Jan 2026 20:23:11 +0000
Subject: [PATCH 32/35] Fix VersionId parsing for nightly builds

- Add detection for 'N' prefix (e.g., N20260122) in version strings
- Update testCurrentVersion to handle nightly builds correctly
- Nightly builds now properly identified as variant type 'n'
---
 .../org/koitharu/kotatsu/core/github/VersionId.kt      |  5 +++--
 .../org/koitharu/kotatsu/core/github/VersionIdTest.kt  | 10 ++++++++--
 2 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/app/src/main/kotlin/org/koitharu/kotatsu/core/github/VersionId.kt b/app/src/main/kotlin/org/koitharu/kotatsu/core/github/VersionId.kt
index 8fde282..dd6bada 100644
--- a/app/src/main/kotlin/org/koitharu/kotatsu/core/github/VersionId.kt
+++ b/app/src/main/kotlin/org/koitharu/kotatsu/core/github/VersionId.kt
@@ -45,8 +45,9 @@ val VersionId.isStable: Boolean
 
 fun VersionId(versionName: String): VersionId {
 	if (versionName.contains("nightly", ignoreCase = true) ||
-		versionName.contains("daily", ignoreCase = true)) {
-		// Nightly build
+		versionName.contains("daily", ignoreCase = true) ||
+		versionName.startsWith("N", ignoreCase = false)) {
+		// Nightly build (handles "nightly", "daily", and "N20260122" formats)
 		return VersionId(
 			major = 0,
 			minor = 0,
diff --git a/app/src/test/kotlin/org/koitharu/kotatsu/core/github/VersionIdTest.kt b/app/src/test/kotlin/org/koitharu/kotatsu/core/github/VersionIdTest.kt
index 45b4144..51d2ac1 100644
--- a/app/src/test/kotlin/org/koitharu/kotatsu/core/github/VersionIdTest.kt
+++ b/app/src/test/kotlin/org/koitharu/kotatsu/core/github/VersionIdTest.kt
@@ -45,8 +45,14 @@ class VersionIdTest {
 
 	@Test
 	fun testCurrentVersion() {
+		val currentVersion = VersionId(BuildConfig.VERSION_NAME)
+		// Skip comparison for nightly builds since they use date-based versioning
+		if (currentVersion.variantType == "n") {
+			// Just verify nightly version was parsed correctly
+			assertTrue(currentVersion.build > 0)
+			return
+		}
 		val version1 = VersionId("2.4.6")
-		val version2 = VersionId(BuildConfig.VERSION_NAME)
-		assertTrue(version1 < version2)
+		assertTrue(version1 < currentVersion)
 	}
 }
\ No newline at end of file

From c4c0e8580d36645c49348c0026248683651d98e1 Mon Sep 17 00:00:00 2001
From: AgentKush <finlayhansford66@gmail.com>
Date: Thu, 22 Jan 2026 20:36:33 +0000
Subject: [PATCH 33/35] Enable release APK signing with debug keystore

Use debug signing config for release and nightly builds to allow
building signed APKs for testing. Replace with proper keystore for
production releases.
---
 app/build.gradle | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/app/build.gradle b/app/build.gradle
index c8308d4..7afb747 100644
--- a/app/build.gradle
+++ b/app/build.gradle
@@ -56,12 +56,13 @@ android {
 			minifyEnabled true
 			shrinkResources true
 			proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
-//			signingConfig signingConfigs.Yukimi
+			// Use debug signing for testing - replace with proper keystore for production
+			signingConfig signingConfigs.debug
 		}
 		nightly {
 			initWith release
 			applicationIdSuffix = '.nightly'
-//			signingConfig signingConfigs.Yukimi
+			signingConfig signingConfigs.debug
 		}
 	}
 	buildFeatures {

From a80ea611048c3e8b19d134573a1e55162d301b75 Mon Sep 17 00:00:00 2001
From: AgentKush <finlayhansford66@gmail.com>
Date: Thu, 22 Jan 2026 20:39:26 +0000
Subject: [PATCH 34/35] Add comprehensive README

- Project description and features
- Download and build instructions
- Tech stack and project structure
- Contributing guidelines
- License information
---
 README.md | 168 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 168 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2afb78b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,168 @@
+# Yumemi
+
+<p align="center">
+  <img src="app/src/main/res/mipmap-xxxhdpi/ic_launcher_round.png" width="120" alt="Yumemi Logo"/>
+</p>
+
+<p align="center">
+  <b>A feature-rich manga reader for Android</b>
+</p>
+
+<p align="center">
+  <a href="https://github.com/AgentKush/Yumemi/releases"><img src="https://img.shields.io/github/v/release/AgentKush/Yumemi?style=flat-square" alt="Release"/></a>
+  <a href="https://github.com/AgentKush/Yumemi/blob/devel/LICENSE"><img src="https://img.shields.io/github/license/AgentKush/Yumemi?style=flat-square" alt="License: GPL-3.0"/></a>
+  <img src="https://img.shields.io/badge/Android-7.0%2B-brightgreen?style=flat-square" alt="Android 7.0+"/>
+  <img src="https://img.shields.io/badge/Kotlin-2.2-blue?style=flat-square" alt="Kotlin"/>
+</p>
+
+---
+
+Yumemi is a free and open-source manga reader for Android based on [Kotatsu](https://github.com/KotatsuApp/Kotatsu). It provides a clean, modern interface for reading manga from various online sources with powerful features for organizing and tracking your reading progress.
+
+## Features
+
+- **Multiple Sources** — Access manga from 1000+ sources via [kotatsu-parsers](https://github.com/YakaTeam/kotatsu-parsers)
+- **Offline Reading** — Download chapters for reading without internet
+- **Reading Progress Tracking** — Automatic history and bookmarks
+- **Scrobbling** — Sync progress with MyAnimeList, AniList, Shikimori, and Kitsu
+- **Local Manga** — Read downloaded CBZ/CBR/ZIP archives
+- **Customizable Reader** — Multiple reading modes, color filters, and gestures
+- **Material Design** — Modern UI following Material Design 3 guidelines
+- **App Lock** — Protect the app with biometric or PIN authentication
+- **Discord Rich Presence** — Share what you're reading on Discord
+- **Tracker** — Get notified when new chapters are available
+- **Categories & Favorites** — Organize your library your way
+- **Search** — Find manga across all sources simultaneously
+
+## Screenshots
+
+<!-- Add screenshots here -->
+
+## Download
+
+Download the latest APK from the [Releases](https://github.com/AgentKush/Yumemi/releases) page.
+
+### Build Variants
+
+| Variant | Description |
+|---------|-------------|
+| **Release** | Optimized build with ProGuard minification |
+| **Debug** | Development build with debugging enabled |
+| **Nightly** | Daily builds with latest changes |
+
+## Building from Source
+
+### Prerequisites
+
+- Android Studio Ladybug or later
+- JDK 17 or later
+- Android SDK 36
+
+### Build Commands
+
+```bash
+# Clone the repository
+git clone https://github.com/AgentKush/Yumemi.git
+cd Yumemi
+
+# Build debug APK
+./gradlew assembleDebug
+
+# Build release APK
+./gradlew assembleRelease
+
+# Build nightly APK
+./gradlew assembleNightly
+
+# Run tests
+./gradlew test
+```
+
+### Output Locations
+
+- Debug: `app/build/outputs/apk/debug/app-debug.apk`
+- Release: `app/build/outputs/apk/release/app-release.apk`
+- Nightly: `app/build/outputs/apk/nightly/app-nightly.apk`
+
+## Tech Stack
+
+- **Language:** Kotlin
+- **Architecture:** MVVM with Clean Architecture
+- **Dependency Injection:** Hilt
+- **Database:** Room
+- **Networking:** OkHttp + Coroutines
+- **Image Loading:** Coil 3
+- **Background Work:** WorkManager
+- **UI:** Material Design 3, ViewBinding
+
+## Project Structure
+
+```
+app/
+├── src/main/kotlin/org/koitharu/kotatsu/
+│   ├── bookmarks/       # Bookmark management
+│   ├── browser/         # WebView browser for sources
+│   ├── core/            # Core utilities, database, network
+│   ├── details/         # Manga details screen
+│   ├── download/        # Download management
+│   ├── explore/         # Source exploration
+│   ├── favourites/      # Favorites management
+│   ├── filter/          # Search filters
+│   ├── history/         # Reading history
+│   ├── list/            # Manga list components
+│   ├── local/           # Local manga handling
+│   ├── main/            # Main activity and navigation
+│   ├── reader/          # Manga reader
+│   ├── scrobbling/      # External tracker integration
+│   ├── search/          # Search functionality
+│   ├── settings/        # App settings
+│   ├── sync/            # Cloud sync
+│   ├── tracker/         # Update tracker
+│   └── widget/          # Home screen widgets
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+### Reporting Issues
+
+- Check existing issues before creating a new one
+- Include device info, Android version, and app version
+- Provide steps to reproduce the issue
+- Include screenshots or logs if applicable
+
+## Acknowledgements
+
+- [Kotatsu](https://github.com/KotatsuApp/Kotatsu) — Original project
+- [YakaTeam/kotatsu-parsers](https://github.com/YakaTeam/kotatsu-parsers) — Manga source parsers
+- All the contributors who help improve this project
+
+## License
+
+```
+Copyright (C) 2020-2026 Yumemi Contributors
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+```
+
+---
+
+<p align="center">Made with ❤️ for manga readers everywhere</p>

From 74738d799589877c904254f966833895d6142ac8 Mon Sep 17 00:00:00 2001
From: AgentKush <finlayhansford66@gmail.com>
Date: Thu, 22 Jan 2026 20:47:23 +0000
Subject: [PATCH 35/35] Fix README logo path to use .webp extension

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 2afb78b..ed56dab 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,7 @@
 # Yumemi
 
 <p align="center">
-  <img src="app/src/main/res/mipmap-xxxhdpi/ic_launcher_round.png" width="120" alt="Yumemi Logo"/>
+  <img src="app/src/main/res/mipmap-xxxhdpi/ic_launcher_round.webp" width="120" alt="Yumemi Logo"/>
 </p>
 
 <p align="center">