fix(epub): resolve percent-encoded NCX targets

lib/microreader/content/EpubParser.cpp

@@ -310,6 +310,37 @@ static std::string normalize_path(const std::string& path) {
   return result;
 }
 
+// Decode percent escapes in a URI path for ZIP entry lookup.  EPUB 2 NCX
+// targets are URIs, while ZIP entry names store the decoded filename bytes.
+// Invalid escapes are kept verbatim so they can still match a literal '%'.
+static std::string decode_percent_escapes(const std::string& path) {
+  auto hex_value = [](char c) -> int {
+    if (c >= '0' && c <= '9')
+      return c - '0';
+    if (c >= 'a' && c <= 'f')
+      return c - 'a' + 10;
+    if (c >= 'A' && c <= 'F')
+      return c - 'A' + 10;
+    return -1;
+  };
+
+  std::string decoded;
+  decoded.reserve(path.size());
+  for (size_t i = 0; i < path.size(); ++i) {
+    if (path[i] == '%' && i + 2 < path.size()) {
+      int high = hex_value(path[i + 1]);
+      int low = hex_value(path[i + 2]);
+      if (high >= 0 && low >= 0) {
+        decoded += static_cast<char>((high << 4) | low);
+        i += 2;
+        continue;
+      }
+    }
+    decoded += path[i];
+  }
+  return decoded;
+}
+
 static std::string decode_entities(const std::string& text) {
   std::string result;
   result.reserve(text.size());
@@ -414,6 +445,20 @@ static EpubError parse_ncx(IZipFile& file, const ZipReader& zip, const ZipEntry&
               break;
             }
           }
+          // Prefer an exact match: '%' is legal in a ZIP entry name.  If it
+          // is absent, resolve the URI's percent escapes for EPUB 2 NCX files
+          // that encode otherwise literal filename characters (e.g. %21).
+          if (idx < 0 && full_path.find('%') != std::string::npos) {
+            std::string decoded_path = decode_percent_escapes(full_path);
+            if (decoded_path != full_path) {
+              for (size_t i = 0; i < zip.entry_count(); ++i) {
+                if (zip.entry(i).name == decoded_path) {
+                  idx = static_cast<int>(i);
+                  break;
+                }
+              }
+            }
+          }
           if (idx >= 0) {
             uint8_t depth = static_cast<uint8_t>(nav_depth - 1 < 255 ? nav_depth - 1 : 255);
             toc.add_entry(current_label, static_cast<uint16_t>(idx), depth, fragment);

test/fixtures/generate_test_epubs.py

@@ -175,6 +175,32 @@ def gen_multi_chapter():
     write_epub("multi_chapter.epub", files, opf_path)
 
 
+# ---------------------------------------------------------------------------
+# percent_encoded_ncx.epub — NCX URI target with an escaped filename byte
+# ---------------------------------------------------------------------------
+def gen_percent_encoded_ncx():
+    opf_path = "OEBPS/content.opf"
+    filename = "chapter!.xhtml"
+    chapter = make_xhtml("Escaped target", "<h1>Escaped NCX target</h1>")
+    opf = make_opf(
+        title="Percent Encoded NCX",
+        manifest_items=[
+            ("ch1", filename, "application/xhtml+xml"),
+            ("ncx", "toc.ncx", "application/x-dtbncx+xml"),
+        ],
+        spine_idrefs=["ch1"],
+        toc_id="ncx",
+    )
+    ncx = make_ncx([("Escaped target", "chapter%21.xhtml")])
+    files = [
+        ("META-INF/container.xml", CONTAINER_XML.format(opf_path=opf_path), False),
+        (opf_path, opf, True),
+        ("OEBPS/toc.ncx", ncx, True),
+        ("OEBPS/" + filename, chapter, True),
+    ]
+    write_epub("percent_encoded_ncx.epub", files, opf_path)
+
+
 # ---------------------------------------------------------------------------
 # 3. with_css.epub — inline + external CSS
 # ---------------------------------------------------------------------------
@@ -431,6 +457,7 @@ def gen_multilingual():
     print("Generating test EPUBs...")
     gen_basic()
     gen_multi_chapter()
+    gen_percent_encoded_ncx()
     gen_with_css()
     gen_with_images()
     gen_stored()

test/unit/EpubParserTest.cpp

@@ -78,6 +78,14 @@ TEST_F(EpubTest, MultiChapterToc) {
   }
 }
 
+TEST_F(EpubTest, PercentEncodedNcxTargetResolvesToZipEntry) {
+  open_fixture("percent_encoded_ncx.epub");
+
+  ASSERT_EQ(epub.toc().entries.size(), 1u);
+  EXPECT_EQ(epub.toc().label_view(epub.toc().entries[0]), "Escaped target");
+  EXPECT_EQ(epub.toc().entries[0].file_idx, epub.spine()[0].file_idx);
+}
+
 TEST_F(EpubTest, WithCssStylesheet) {
   // CSS is now loaded lazily per chapter — the cache is populated on first parse.
   open_fixture("with_css.epub");