From dca5551f225f90fef6815c71a736d9352bc66806 Mon Sep 17 00:00:00 2001
From: AJ Banck <ajbanck@planet.nl>
Date: Sat, 17 Jan 2026 12:36:49 +0100
Subject: [PATCH] Decode cover related hrefs for findCoverHrefs

---
 .../epub4j/epub/PackageDocumentReader.java    | 10 ++++++
 .../epub/PackageDocumentReaderTest.java       | 14 +++++++-
 .../resources/opf/test_urlencoded_href.opf    | 32 +++++++++++++++++++
 3 files changed, 55 insertions(+), 1 deletion(-)
 create mode 100644 epub4j-core/src/test/resources/opf/test_urlencoded_href.opf

diff --git a/epub4j-core/src/main/java/io/documentnode/epub4j/epub/PackageDocumentReader.java b/epub4j-core/src/main/java/io/documentnode/epub4j/epub/PackageDocumentReader.java
index 31a251f..304a9a0 100644
--- a/epub4j-core/src/main/java/io/documentnode/epub4j/epub/PackageDocumentReader.java
+++ b/epub4j-core/src/main/java/io/documentnode/epub4j/epub/PackageDocumentReader.java
@@ -369,6 +369,11 @@ static Set<String> findCoverHrefs(Document packageDocument) {
               OPFTags.item, OPFAttributes.id, coverResourceId,
               OPFAttributes.href);
       if (StringUtil.isNotBlank(coverHref)) {
+        try {
+            coverHref = URLDecoder.decode(coverHref, Constants.CHARACTER_ENCODING);
+        } catch (UnsupportedEncodingException e) {
+          log.error(e.getMessage());
+        }
         result.add(coverHref);
       } else {
         result.add(
@@ -381,6 +386,11 @@ static Set<String> findCoverHrefs(Document packageDocument) {
             OPFTags.reference, OPFAttributes.type, OPFValues.reference_cover,
             OPFAttributes.href);
     if (StringUtil.isNotBlank(coverHref)) {
+      try {
+        coverHref = URLDecoder.decode(coverHref, Constants.CHARACTER_ENCODING);
+      } catch (UnsupportedEncodingException e) {
+        log.error(e.getMessage());
+      }
       result.add(coverHref);
     }
     return result;
diff --git a/epub4j-core/src/test/java/io/documentnode/epub4j/epub/PackageDocumentReaderTest.java b/epub4j-core/src/test/java/io/documentnode/epub4j/epub/PackageDocumentReaderTest.java
index 105af12..851aed5 100644
--- a/epub4j-core/src/test/java/io/documentnode/epub4j/epub/PackageDocumentReaderTest.java
+++ b/epub4j-core/src/test/java/io/documentnode/epub4j/epub/PackageDocumentReaderTest.java
@@ -8,6 +8,8 @@
 import java.io.IOException;
 import java.util.Arrays;
 import java.util.Collection;
+import java.util.HashSet;
+import java.util.Set;
 
 import org.junit.Assert;
 import org.junit.Test;
@@ -28,7 +30,17 @@ public void testFindCoverHref_content1() throws SAXException, IOException {
 		assertEquals(1, coverHrefs.size());
 		assertEquals("cover.html", coverHrefs.iterator().next());
 	}
-	
+
+	@Test
+	public void testFindCoverHref_URLEncoded() throws SAXException, IOException {
+		Set<String> expected = new HashSet<>(Arrays.asList("cover+.png", "cover+.html"));
+		Document packageDocument;
+		packageDocument = EpubProcessorSupport.createDocumentBuilder().parse(PackageDocumentReaderTest.class.getResourceAsStream("/opf/test_urlencoded_href.opf"));
+		Collection<String> coverHrefs = PackageDocumentReader.findCoverHrefs(packageDocument);
+		assertEquals(2, coverHrefs.size());
+		assertEquals(expected, coverHrefs);
+	}
+
 	@Test
 	public void testFindTableOfContentsResource_simple_correct_toc_id() {
 		// given
diff --git a/epub4j-core/src/test/resources/opf/test_urlencoded_href.opf b/epub4j-core/src/test/resources/opf/test_urlencoded_href.opf
new file mode 100644
index 0000000..8101d2d
--- /dev/null
+++ b/epub4j-core/src/test/resources/opf/test_urlencoded_href.opf
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<package xmlns="http://www.idpf.org/2007/opf" version="2.0" unique-identifier="BookId">
+  <metadata xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:opf="http://www.idpf.org/2007/opf">
+    <dc:title>EPUB4J test book 1</dc:title>
+    <dc:creator opf:role="aut" opf:file-as="Tester, Joe">Joe Tester</dc:creator>
+    <dc:date>2010-05-27</dc:date>
+    <dc:language>en</dc:language>
+    <meta name="cover" content="cover-image"/>
+    <meta name="generator" content="EPUB4J version 0.1"/>
+  </metadata>
+  <manifest>
+    <item id="ncx" href="toc.ncx" media-type="application/x-dtbncx+xml"/>
+    <item id="cover-image" href="cover%2B.png" media-type="image/png"/>
+    <item id="cover" href="cover%2B.html" media-type="application/xhtml+xml"/>
+    <item id="item_1" href="chapter1%2B.html" media-type="application/xhtml+xml"/>
+    <item id="item_2" href="book1%2B.css" media-type="text/css"/>
+    <item id="item_3" href="chapter2%2B.html" media-type="application/xhtml+xml"/>
+    <item id="item_4" href="flowers%2B.jpg" media-type="image/jpeg"/>
+    <item id="item_5" href="chapter2_1%2B.html" media-type="application/xhtml+xml"/>
+    <item id="item_6" href="chapter3%2B.html" media-type="application/xhtml+xml"/>
+  </manifest>
+  <spine toc="ncx">
+    <itemref idref="cover" linear="no"/>
+    <itemref idref="item_1"/>
+    <itemref idref="item_3"/>
+    <itemref idref="item_5"/>
+    <itemref idref="item_6"/>
+  </spine>
+  <guide>
+    <reference type="cover" href="cover%2B.html"/>
+  </guide>
+</package>
\ No newline at end of file