✨ feat: authenticated catalog covers via Coil + thumbnail-rel parsing (#2)

* docs: 📝 design for authenticated catalog cover loading

Documents the gap (Coil uses a default ImageLoader without the OPDS
BasicAuthInterceptor, so calibre-web cover requests 401) and the planned
fix: an ImageLoaderFactory on EReaderApp wired to OpdsHttpClient.okHttp,
plus reordering OpdsClient to prefer rel="…/image/thumbnail" over
rel="…/image" for grid use.

* docs: 📝 implementation plan for catalog covers

Plan for wiring Coil to OpdsHttpClient.okHttp via an ImageLoaderFactory
on EReaderApp, and reordering OpdsClient to prefer rel="…/image/thumbnail"
over rel="…/image". Tests, fixtures, and manual verification steps
included. References the design at
docs/superpowers/specs/2026-05-07-catalog-covers-design.md.

* feat: ✨ prefer OPDS thumbnail rel and survive thumbnail-only feeds

Readium's OPDS model populates pub.subcollections["images"] only when an
opds:image rel is present and silently drops opds:image/thumbnail when it
appears alone. Skip the Readium-routed image extraction and parse cover
links directly from each <entry>, mirroring the existing parseSearchLink
workaround for the analogous {searchTerms} quirk. Within an entry, prefer
opds:image/thumbnail (sized for the 2-col grid) over opds:image, and join
back to Readium's parsed publications via the unique epub acquisition href.

Spec at docs/superpowers/specs/2026-05-07-catalog-covers-design.md updated
to record the discovered Readium behavior.

* feat: ✨ route Coil image loads through authenticated OPDS OkHttp client

Coil's default singleton ImageLoader has no awareness of the OPDS
BasicAuthInterceptor, so cover requests against authenticated calibre-web
instances 401 silently and the catalog grid only ever shows the
gradient+initials fallback. Implement coil.ImageLoaderFactory on
EReaderApp with an ImageLoader built against the existing
OpdsHttpClient.okHttp, so Coil inherits Basic auth (and any future
interceptors) automatically. AppContainer's opdsHttp is promoted from
private to public to be reachable from the Application class.

Author: vitofico

app/src/main/java/io/theficos/ereader/EReaderApp.kt

@@ -1,14 +1,21 @@
 package io.theficos.ereader
 
 import android.app.Application
+import coil.ImageLoader
+import coil.ImageLoaderFactory
 import io.theficos.ereader.di.AppContainer
 
-class EReaderApp : Application() {
+class EReaderApp : Application(), ImageLoaderFactory {
     lateinit var container: AppContainer
         private set
 
     override fun onCreate() {
         super.onCreate()
         container = AppContainer(this)
     }
+
+    override fun newImageLoader(): ImageLoader =
+        ImageLoader.Builder(this)
+            .okHttpClient(container.opdsHttp.okHttp)
+            .build()
 }

app/src/main/java/io/theficos/ereader/di/AppContainer.kt

@@ -20,7 +20,7 @@ class AppContainer(context: Context) {
 
     val credentialStore: CalibreCredentialStore = CalibreCredentialStore(appContext)
 
-    private val opdsHttp = OpdsHttpClient(credentialStore)
+    val opdsHttp = OpdsHttpClient(credentialStore)
     val opdsClient: OpdsClient = OpdsClient(opdsHttp.okHttp)
     val bookDownloader: BookDownloader = BookDownloader(
         okHttp = opdsHttp.okHttp,

data/opds/src/main/java/io/theficos/ereader/data/opds/OpdsClient.kt

@@ -26,6 +26,9 @@ class OpdsClient(
             // Readium silently drops links whose href contains template chars like `{searchTerms}`,
             // so we always look for rel="search" ourselves from the raw XML.
             val searchLink = parseSearchLink(bytes, absoluteUrl)
+            // Readium also drops opds:image/thumbnail links unless a sibling opds:image link
+            // is present, so we pull cover hrefs from the raw XML and join by acquisition href.
+            val coversByEpubHref = parseCoverHrefs(bytes, absoluteUrl)
             OpdsFeed(
                 title = feed.metadata.title,
                 navigation = feed.navigation.map { link ->
@@ -39,17 +42,12 @@ class OpdsClient(
                         link.rels.contains("http://opds-spec.org/acquisition") &&
                             link.mediaType.toString() == "application/epub+zip"
                     } ?: return@mapNotNull null
-                    val imageLinks = pub.subcollections["images"].orEmpty().flatMap { it.links }
-                    val coverLink = imageLinks.firstOrNull { link ->
-                        link.rels.contains("http://opds-spec.org/image")
-                    } ?: imageLinks.firstOrNull { link ->
-                        link.rels.contains("http://opds-spec.org/image/thumbnail")
-                    } ?: imageLinks.firstOrNull()
+                    val absoluteEpubHref = absolutize(absoluteUrl, epubLink.href.toString())
                     OpdsPublication(
                         title = pub.metadata.title.orEmpty(),
                         author = pub.metadata.authors.firstOrNull()?.name,
-                        epubDownloadHref = absolutize(absoluteUrl, epubLink.href.toString()),
-                        coverUrl = coverLink?.href?.toString()?.let { absolutize(absoluteUrl, it) },
+                        epubDownloadHref = absoluteEpubHref,
+                        coverUrl = coversByEpubHref[absoluteEpubHref],
                     )
                 },
                 searchLink = searchLink,
@@ -64,6 +62,41 @@ class OpdsClient(
         return absolutize(link.baseUrl, applyTemplate(rawTemplate, query))
     }
 
+    private fun parseCoverHrefs(bytes: ByteArray, feedUrl: String): Map<String, String> {
+        val doc = runCatching {
+            DocumentBuilderFactory.newInstance()
+                .apply { isNamespaceAware = true }
+                .newDocumentBuilder()
+                .parse(ByteArrayInputStream(bytes))
+        }.getOrNull() ?: return emptyMap()
+        val entries = doc.getElementsByTagNameNS("http://www.w3.org/2005/Atom", "entry")
+        val result = mutableMapOf<String, String>()
+        for (i in 0 until entries.length) {
+            val entry = entries.item(i) as org.w3c.dom.Element
+            val links = entry.getElementsByTagNameNS("http://www.w3.org/2005/Atom", "link")
+            var epubHref: String? = null
+            var thumbnailHref: String? = null
+            var imageHref: String? = null
+            for (j in 0 until links.length) {
+                val el = links.item(j) as org.w3c.dom.Element
+                val rel = el.getAttribute("rel")
+                val href = el.getAttribute("href").takeIf { it.isNotBlank() } ?: continue
+                when (rel) {
+                    "http://opds-spec.org/acquisition" -> {
+                        if (el.getAttribute("type") == "application/epub+zip") epubHref = href
+                    }
+                    "http://opds-spec.org/image/thumbnail" -> thumbnailHref = href
+                    "http://opds-spec.org/image" -> imageHref = href
+                }
+            }
+            val cover = thumbnailHref ?: imageHref
+            if (epubHref != null && cover != null) {
+                result[absolutize(feedUrl, epubHref)] = absolutize(feedUrl, cover)
+            }
+        }
+        return result
+    }
+
     private fun parseSearchLink(bytes: ByteArray, feedUrl: String): OpdsSearchLink? {
         val doc = runCatching {
             DocumentBuilderFactory.newInstance()

data/opds/src/test/java/io/theficos/ereader/data/opds/OpdsClientTest.kt

@@ -42,6 +42,10 @@ class OpdsClientTest {
                         .setBody(resource("/opds/catalog-with-direct-search.xml"))
                     "/opds/osd" -> MockResponse().setHeader("Content-Type", "application/opensearchdescription+xml")
                         .setBody(resource("/opds/opensearch.xml"))
+                    "/opds/both" -> MockResponse().setHeader("Content-Type", "application/atom+xml")
+                        .setBody(resource("/opds/catalog-feed-thumbnail-and-image.xml"))
+                    "/opds/thumb-only" -> MockResponse().setHeader("Content-Type", "application/atom+xml")
+                        .setBody(resource("/opds/catalog-feed-thumbnail-only.xml"))
                     else -> MockResponse().setResponseCode(404)
                 }
             }
@@ -111,4 +115,25 @@ class OpdsClientTest {
         assertThat(resolved).doesNotContain("startIndex={")
     }
 
+    @Test fun `cover prefers thumbnail rel when both rels present`() = runTest {
+        val feed = client.fetch(server.url("/opds/both").toString())
+        val pub = feed.publications.single()
+        assertThat(pub.coverUrl).isNotNull()
+        assertThat(pub.coverUrl).endsWith("/opds/cover/42/thumb")
+    }
+
+    @Test fun `cover uses thumbnail rel when only thumbnail is present`() = runTest {
+        val feed = client.fetch(server.url("/opds/thumb-only").toString())
+        val pub = feed.publications.single()
+        assertThat(pub.coverUrl).isNotNull()
+        assertThat(pub.coverUrl).endsWith("/opds/cover/42/thumb")
+    }
+
+    @Test fun `cover falls back to full-size image rel when thumbnail is absent`() = runTest {
+        val feed = client.fetch(server.url("/opds/new").toString())
+        val pub = feed.publications.single()
+        assertThat(pub.coverUrl).isNotNull()
+        assertThat(pub.coverUrl).endsWith("/opds/cover/42")
+    }
+
 }

data/opds/src/test/resources/opds/catalog-feed-thumbnail-and-image.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<feed xmlns="http://www.w3.org/2005/Atom" xmlns:opds="http://opds-spec.org/2010/catalog" xmlns:dc="http://purl.org/dc/terms/">
+  <id>urn:calibre-web:both</id>
+  <title>Both Rels</title>
+  <updated>2026-04-26T00:00:00Z</updated>
+  <link rel="self" href="/opds/both" type="application/atom+xml;profile=opds-catalog;kind=acquisition"/>
+  <entry>
+    <title>The Sample Book</title>
+    <id>urn:calibre-web:42</id>
+    <updated>2026-04-26T00:00:00Z</updated>
+    <author><name>Jane Doe</name></author>
+    <dc:identifier>urn:uuid:550e8400-e29b-41d4-a716-446655440000</dc:identifier>
+    <link rel="http://opds-spec.org/acquisition" href="/opds/download/42/epub" type="application/epub+zip"/>
+    <link rel="http://opds-spec.org/image" href="/opds/cover/42" type="image/jpeg"/>
+    <link rel="http://opds-spec.org/image/thumbnail" href="/opds/cover/42/thumb" type="image/jpeg"/>
+  </entry>
+</feed>

data/opds/src/test/resources/opds/catalog-feed-thumbnail-only.xml

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<feed xmlns="http://www.w3.org/2005/Atom" xmlns:opds="http://opds-spec.org/2010/catalog" xmlns:dc="http://purl.org/dc/terms/">
+  <id>urn:calibre-web:thumb-only</id>
+  <title>Thumb Only</title>
+  <updated>2026-04-26T00:00:00Z</updated>
+  <link rel="self" href="/opds/thumb-only" type="application/atom+xml;profile=opds-catalog;kind=acquisition"/>
+  <entry>
+    <title>The Sample Book</title>
+    <id>urn:calibre-web:42</id>
+    <updated>2026-04-26T00:00:00Z</updated>
+    <author><name>Jane Doe</name></author>
+    <dc:identifier>urn:uuid:550e8400-e29b-41d4-a716-446655440000</dc:identifier>
+    <link rel="http://opds-spec.org/acquisition" href="/opds/download/42/epub" type="application/epub+zip"/>
+    <link rel="http://opds-spec.org/image/thumbnail" href="/opds/cover/42/thumb" type="image/jpeg"/>
+  </entry>
+</feed>