@storyteller-platform/epub 0.7.0 → 0.7.1

package/dist/index.js

@@ -3,14 +3,9 @@ import { cp, mkdir } from "node:fs/promises";
 import { Mutex } from "async-mutex";
 import { XMLBuilder, XMLParser } from "fast-xml-parser";
 import memoize from "mem";
-import { lookup } from "mime-types";
 import { nanoid } from "nanoid";
-import {
-  dirname,
-  hrefToPlatformPath,
-  join,
-  resolve
-} from "@storyteller-platform/path";
+import { MediaType } from "@storyteller-platform/media-types";
+import { dirname } from "@storyteller-platform/path";
 import { TmpFsAdapter } from "./adapters/tmpfs.js";
 import * as Upgrade from "./upgrade.js";
 import { MemoryAdapter } from "./adapters/memory.js";
@@ -19,6 +14,61 @@ class EpubVersionError extends Error {
 }
 class EpubReadOnlyError extends Error {
 }
+const OPF_NAMESPACE = "http://www.idpf.org/2007/opf";
+const ENTRY_ORIGIN = "epub:///";
+function entryToUrlPath(entry) {
+  return entry.split("/").map(encodeURIComponent).join("/");
+}
+function resolveEntryUrl(from, href) {
+  const base = new URL(entryToUrlPath(from), ENTRY_ORIGIN);
+  if (!URL.canParse(href, base.toString())) return null;
+  const url = new URL(href, base);
+  return url.href.startsWith(ENTRY_ORIGIN) ? url : null;
+}
+function renameOpfAttributes(attrs, prefix) {
+  const attrPrefix = `@_${prefix}:`;
+  const renamed = {};
+  for (const [key, value] of Object.entries(attrs)) {
+    if (key === `@_xmlns:${prefix}`) continue;
+    if (key.startsWith(attrPrefix)) {
+      renamed[`@_opf:${key.slice(attrPrefix.length)}`] = value;
+    } else {
+      renamed[key] = value;
+    }
+  }
+  return renamed;
+}
+function stripOpfPrefix(node, prefix) {
+  if (Epub.isXmlTextNode(node)) return node;
+  const name = Epub.getXmlElementName(node);
+  const bareName = name.startsWith(`${prefix}:`) ? name.slice(prefix.length + 1) : name;
+  const element = {
+    [bareName]: Epub.getXmlChildren(node).map(
+      (child) => stripOpfPrefix(child, prefix)
+    )
+  };
+  if (node[":@"]) {
+    element[":@"] = renameOpfAttributes(node[":@"], prefix);
+  }
+  return element;
+}
+function normalizeOpfNamespacePrefixes(doc) {
+  var _a;
+  const root = doc.find(
+    (node) => !Epub.isXmlTextNode(node) && Epub.getXmlElementName(node).endsWith(":package")
+  );
+  if (!root) return doc;
+  const prefix = Epub.getXmlElementName(root).slice(0, -":package".length);
+  if (((_a = root[":@"]) == null ? void 0 : _a[`@_xmlns:${prefix}`]) !== OPF_NAMESPACE) return doc;
+  const stripped = stripOpfPrefix(root, prefix);
+  stripped[":@"] = {
+    ...stripped[":@"],
+    "@_xmlns": OPF_NAMESPACE,
+    "@_xmlns:opf": OPF_NAMESPACE
+  };
+  doc[doc.indexOf(root)] = stripped;
+  return doc;
+}
 class Epub {
   /**
    * Prefer the static factories ({@link Epub.using}, {@link Epub.from},
@@ -299,14 +349,7 @@ ${JSON.stringify(element, null, 2)}`
       );
     }
     const rootfile = await this.getRootfile();
-    const filename = this.resolveInternalHref(rootfile, href);
-    await this.adapter.remove(filename);
-  }
-  async getFileData(path, encoding) {
-    if (encoding) {
-      return this.adapter.read(path, encoding);
-    }
-    return this.adapter.read(path);
+    await this.adapter.remove(await this.resolveEntry(rootfile, href));
   }
   /**
    * Length of the underlying archive entry for a manifest item, in bytes
@@ -319,14 +362,15 @@ ${JSON.stringify(element, null, 2)}`
     const manifestItem = manifest[id];
     if (!manifestItem)
       throw new Error(`Could not find item with id "${id}" in manifest`);
-    const path = this.resolveInternalHref(rootfile, manifestItem.href);
-    return this.adapter.archiveLength(path);
+    return this.adapter.archiveLength(
+      await this.resolveEntry(rootfile, manifestItem.href)
+    );
   }
   async getRootfile() {
     var _a;
     if (this.rootfile !== null) return this.rootfile;
-    const containerString = await this.getFileData(
-      join(this.adapter.rootPath, "META-INF", "container.xml"),
+    const containerString = await this.adapter.read(
+      "META-INF/container.xml",
       "utf-8"
     );
     if (!containerString)
@@ -350,7 +394,7 @@ ${JSON.stringify(element, null, 2)}`
       Epub.getXmlChildren(rootfiles),
       (node) => {
         var _a2;
-        return !Epub.isXmlTextNode(node) && ((_a2 = node[":@"]) == null ? void 0 : _a2["@_media-type"]) === "application/oebps-package+xml";
+        return !Epub.isXmlTextNode(node) && ((_a2 = node[":@"]) == null ? void 0 : _a2["@_media-type"]) === MediaType.OPF.mime;
       }
     );
     const fullPath = (_a = rootfile == null ? void 0 : rootfile[":@"]) == null ? void 0 : _a["@_full-path"];
@@ -358,12 +402,12 @@ ${JSON.stringify(element, null, 2)}`
       throw new Error(
         "Failed to parse EPUB container.xml: Found no rootfile element"
       );
-    this.rootfile = resolve(this.adapter.rootPath, fullPath);
+    this.rootfile = await this.resolveEntry("", fullPath);
     return this.rootfile;
   }
   async getPackageDocument() {
     const rootfile = await this.getRootfile();
-    const packageDocumentString = await this.getFileData(rootfile, "utf-8");
+    const packageDocumentString = await this.adapter.read(rootfile, "utf-8");
     if (!packageDocumentString)
       throw new Error(
         `Failed to parse EPUB: could not find package document at ${rootfile}`
@@ -371,7 +415,7 @@ ${JSON.stringify(element, null, 2)}`
     const packageDocument = Epub.xmlParser.parse(
       packageDocumentString
     );
-    return packageDocument;
+    return normalizeOpfNamespacePrefixes(packageDocument);
   }
   async getPackageElement() {
     const packageDocument = await this.getPackageDocument();
@@ -1043,11 +1087,12 @@ ${JSON.stringify(element, null, 2)}`
    * the provided href within the publication.
    */
   async setCoverImage(href, data) {
+    var _a;
     const coverImageItem = await this.getCoverImageItem();
     if (coverImageItem) {
       await this.removeManifestItem(coverImageItem.id);
     }
-    const mediaType = lookup(href);
+    const mediaType = (_a = MediaType.fromPath(href)) == null ? void 0 : _a.mime;
     if (!mediaType)
       throw new Error(`Invalid file extension for cover image: ${href}`);
     await this.addManifestItem(
@@ -2026,35 +2071,81 @@ ${JSON.stringify(element, null, 2)}`
     return this.getNavigation("page-list", { resolveToRoot });
   }
   /**
-   * Returns a Zip Entry path for an HREF
+   * Name the entry a resolved URL addresses.
+   *
+   * A correctly authored publication percent-encodes its hrefs, so the
+   * decoded reading is the one the spec calls for and the one we prefer.
+   * Some publications instead write the entry name verbatim, so when the two
+   * readings differ we ask the archive which one it holds. A verbatim name
+   * carrying a bare `%`, as `100%.xhtml` does, is not a valid encoding at all
+   * and can only be its own answer.
    */
-  resolveInternalHref(from, href) {
-    const startPath = dirname(from);
-    return resolve(
-      this.adapter.rootPath,
-      hrefToPlatformPath(startPath),
-      hrefToPlatformPath(href)
-    );
+  async entryForUrl(url) {
+    const asWritten = url.pathname.slice(1);
+    let decoded;
+    try {
+      decoded = decodeURIComponent(asWritten);
+    } catch {
+      return asWritten;
+    }
+    if (decoded === asWritten) {
+      return decoded;
+    }
+    if (await this.adapter.exists(decoded)) {
+      return decoded;
+    }
+    return await this.adapter.exists(asWritten) ? asWritten : decoded;
+  }
+  /**
+   * Resolve an href to the name of the archive entry it addresses.
+   *
+   * @param from The entry the href appears in; it resolves against that
+   *   entry's directory
+   * @throws when the href addresses something outside the publication
+   */
+  async resolveEntry(from, href) {
+    const url = resolveEntryUrl(from, href);
+    if (!url) {
+      throw new Error(
+        `href does not address an entry in this publication: ${href}`
+      );
+    }
+    return this.entryForUrl(url);
   }
   /**
    * Returns a path-relative-scheme-less URL, relative to the
    * container root.
    *
+   * An href that points outside the publication, such as an external link in
+   * a navigation document, is handed back unchanged.
+   *
    * @param href The href to resolve
    * @param [relativeTo] Optional - The href to resolve this href relative to.
        Use if resolving a relative href from a file other than the package document.
    */
   async resolveHref(href, relativeTo, { toRoot } = {}) {
+    if (href.startsWith("#")) return href;
     const rootfile = await this.getRootfile();
-    const from = relativeTo ? this.resolveInternalHref(rootfile, relativeTo) : rootfile;
-    const path = this.resolveInternalHref(from, href);
-    return path.replace(toRoot ? this.adapter.rootPath : dirname(rootfile), "").slice(1);
+    const from = relativeTo ? await this.resolveEntry(rootfile, relativeTo) : rootfile;
+    const url = resolveEntryUrl(from, href);
+    if (!url) return href;
+    const entry = (await this.entryForUrl(url)).split("/");
+    const base = toRoot ? [] : rootfile.split("/").slice(0, -1);
+    let shared = 0;
+    while (shared < base.length && base[shared] === entry[shared]) {
+      shared++;
+    }
+    const relative = [
+      ...Array(base.length - shared).fill(".."),
+      ...entry.slice(shared).map(encodeURIComponent)
+    ];
+    return relative.join("/") + url.hash;
   }
   async readFileContents(href, relativeTo, encoding) {
     const rootfile = await this.getRootfile();
-    const from = relativeTo ? this.resolveInternalHref(rootfile, relativeTo) : rootfile;
-    const path = this.resolveInternalHref(from, href);
-    const itemEntry = encoding ? await this.getFileData(path, encoding) : await this.getFileData(path);
+    const from = relativeTo ? await this.resolveEntry(rootfile, relativeTo) : rootfile;
+    const entry = await this.resolveEntry(from, href);
+    const itemEntry = encoding ? await this.adapter.read(entry, encoding) : await this.adapter.read(entry);
     return itemEntry;
   }
   async readItemContents(id, encoding) {
@@ -2063,8 +2154,8 @@ ${JSON.stringify(element, null, 2)}`
     const manifestItem = manifest[id];
     if (!manifestItem)
       throw new Error(`Could not find item with id "${id}" in manifest`);
-    const path = this.resolveInternalHref(rootfile, manifestItem.href);
-    const itemEntry = encoding ? await this.getFileData(path, encoding) : await this.getFileData(path);
+    const entry = await this.resolveEntry(rootfile, manifestItem.href);
+    const itemEntry = encoding ? await this.adapter.read(entry, encoding) : await this.adapter.read(entry);
     return itemEntry;
   }
   /**
@@ -2122,11 +2213,11 @@ ${JSON.stringify(element, null, 2)}`
     if (!manifestItem)
       throw new Error(`Could not find item with id "${id}" in manifest`);
     memoize.clear(this.readXhtmlItemContents);
-    const href = this.resolveInternalHref(rootfile, manifestItem.href);
+    const entry = await this.resolveEntry(rootfile, manifestItem.href);
     if (encoding === "utf-8") {
-      await this.writeEntryContents(href, contents, encoding);
+      await this.writeEntryContents(entry, contents, encoding);
     } else {
-      await this.writeEntryContents(href, contents);
+      await this.writeEntryContents(entry, contents);
     }
   }
   /**
@@ -2197,7 +2288,7 @@ ${JSON.stringify(element, null, 2)}`
     });
     this.manifest = null;
     const rootfile = await this.getRootfile();
-    const filename = this.resolveInternalHref(rootfile, item.href);
+    const filename = await this.resolveEntry(rootfile, item.href);
     const data = encoding === "utf-8" || encoding === "xml" ? new TextEncoder().encode(
       encoding === "utf-8" ? contents : await Epub.xmlBuilder.build(
         contents
@@ -2381,10 +2472,7 @@ ${JSON.stringify(element, null, 2)}`
     );
     const spineTocId = (_a = spine == null ? void 0 : spine[":@"]) == null ? void 0 : _a["@_toc"];
     const ncxItem = spineTocId ? manifest[spineTocId] : Object.values(manifest).find(
-      (item) => {
-        var _a2;
-        return ((_a2 = item.mediaType) == null ? void 0 : _a2.toLowerCase()) === "application/x-dtbncx+xml";
-      }
+      (item) => MediaType.fromMime(item.mediaType ?? "") === MediaType.NCX
     );
     if (!ncxItem) return [];
     const ncxContent = await this.readItemContents(ncxItem.id, "utf-8");
@@ -2525,7 +2613,12 @@ class EpubFactory {
         "This is not a valid EPUB publication. Could not read the package document."
       );
     }
-    await Epub.assertEpub3(epub);
+    try {
+      await Epub.assertEpub3(epub);
+    } catch (error) {
+      epub.discardAndClose();
+      throw error;
+    }
     return epub;
   }
   /**
@@ -2565,14 +2658,11 @@ class EpubFactory {
     const container = encoder.encode(`<?xml version="1.0"?>
 <container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
   <rootfiles>
-    <rootfile media-type="application/oebps-package+xml" full-path="OEBPS/content.opf"/>
+    <rootfile media-type="${MediaType.OPF.mime}" full-path="OEBPS/content.opf"/>
   </rootfiles>
 </container>
 `);
-    await adapter.write(
-      join(adapter.rootPath, "META-INF", "container.xml"),
-      container
-    );
+    await adapter.write("META-INF/container.xml", container);
     const packageDocument = encoder.encode(`<?xml version="1.0"?>
 <package unique-identifier="pub-id" dir="${language.textInfo.direction}" xml:lang="${language.toString()}" version="3.0" xmlns:dc="http://purl.org/dc/elements/1.1/">
   <metadata>
@@ -2583,10 +2673,7 @@ class EpubFactory {
   </spine>
 </package>
 `);
-    await adapter.write(
-      join(adapter.rootPath, "OEBPS", "content.opf"),
-      packageDocument
-    );
+    await adapter.write("OEBPS/content.opf", packageDocument);
     const epub = new Epub(this.adapterClass, adapter, path);
     const metadata = [
       {
@@ -2635,7 +2722,6 @@ class EpubFactory {
    * @throws when the adapter is read-only
    */
   async upgrade(path, options = {}) {
-    var _a;
     if (!this.adapterClass.capabilities.writable) {
       throw new EpubReadOnlyError(
         `adapter ${this.adapterClass.kind} is read-only; cannot upgrade`
@@ -2661,49 +2747,55 @@ class EpubFactory {
         "This is not a valid EPUB publication. Could not read the package document."
       );
     }
-    const version = await epub.getVersion();
-    if (version.startsWith("3.")) {
-      return epub;
-    }
-    const tocEntries = await epub.getNcxTableOfContents();
-    let landmarks = [];
-    await epub.withPackage((pkg) => {
-      landmarks = Upgrade.extractGuideLandmarks(pkg);
-      Upgrade.upgradePackageMetadata(pkg);
-      Upgrade.fixFontMimeTypes(pkg);
-      Upgrade.removeGuide(pkg);
+    try {
+      const version = await epub.getVersion();
+      if (version.startsWith("3.")) {
+        return epub;
+      }
+      const tocEntries = await epub.getNcxTableOfContents();
+      let landmarks = [];
+      await epub.withPackage((pkg) => {
+        landmarks = Upgrade.extractGuideLandmarks(pkg);
+        Upgrade.upgradePackageMetadata(pkg);
+        Upgrade.fixFontMimeTypes(pkg);
+        Upgrade.removeGuide(pkg);
+        if (removeNcx) {
+          Upgrade.removeSpineTocRef(pkg);
+        }
+        Upgrade.setPackageVersion(pkg, "3.0");
+      });
+      await Upgrade.collectManifestProperties(epub);
       if (removeNcx) {
-        Upgrade.removeSpineTocRef(pkg);
+        await Upgrade.removeNcx(epub);
       }
-      Upgrade.setPackageVersion(pkg, "3.0");
-    });
-    await Upgrade.collectManifestProperties(epub);
-    if (removeNcx) {
-      await Upgrade.removeNcx(epub);
-    }
-    const navHref = await Upgrade.chooseNavHref(epub);
-    const navContent = await Upgrade.buildNavDocument(
-      epub,
-      tocEntries,
-      landmarks
-    );
-    await epub.addManifestItem(
-      {
-        id: "nav",
-        href: navHref,
-        mediaType: "application/xhtml+xml",
-        properties: ["nav"]
-      },
-      navContent,
-      "utf-8"
-    );
-    const manifest = await epub.getManifest();
-    for (const item of Object.values(manifest)) {
-      if (((_a = item.mediaType) == null ? void 0 : _a.toLowerCase()) !== "application/xhtml+xml") continue;
-      const contents = await epub.readXhtmlItemContents(item.id);
-      await epub.writeXhtmlItemContents(item.id, contents);
+      const navHref = await Upgrade.chooseNavHref(epub);
+      const navContent = await Upgrade.buildNavDocument(
+        epub,
+        tocEntries,
+        landmarks
+      );
+      await epub.addManifestItem(
+        {
+          id: "nav",
+          href: navHref,
+          mediaType: MediaType.XHTML.mime,
+          properties: ["nav"]
+        },
+        navContent,
+        "utf-8"
+      );
+      const manifest = await epub.getManifest();
+      for (const item of Object.values(manifest)) {
+        if (MediaType.fromMime(item.mediaType ?? "") !== MediaType.XHTML)
+          continue;
+        const contents = await epub.readXhtmlItemContents(item.id);
+        await epub.writeXhtmlItemContents(item.id, contents);
+      }
+      return epub;
+    } catch (error) {
+      epub.discardAndClose();
+      throw error;
     }
-    return epub;
   }
 }
 export {

package/dist/upgrade.cjs

@@ -41,6 +41,7 @@ __export(upgrade_exports, {
 });
 module.exports = __toCommonJS(upgrade_exports);
 var import_nanoid = require("nanoid");
+var import_media_types = require("@storyteller-platform/media-types");
 var import_index = require("./index.cjs");
 const GUIDE_TO_EPUBTYPE = {
   acknowledgements: "acknowledgments",
@@ -88,31 +89,7 @@ const GUIDE_TO_EPUBTYPE = {
   "other.volume": "volume",
   "other.warning": "warning"
 };
-const XHTML_MEDIA_TYPES = /* @__PURE__ */ new Set([
-  "application/xhtml+xml",
-  "application/vnd.adobe-page-template+xml",
-  "text/html"
-]);
-const OEB_FONTS = /* @__PURE__ */ new Set([
-  "application/vnd.ms-opentype",
-  "application/x-font-ttf",
-  "application/x-font-otf",
-  "application/x-font-truetype",
-  "application/font-sfnt",
-  "application/font-woff",
-  "application/font-woff2",
-  "font/woff",
-  "font/woff2",
-  "font/otf",
-  "font/ttf",
-  "font/sfnt"
-]);
-const FONT_MIME_BY_EXT = {
-  ".ttf": "application/font-sfnt",
-  ".otf": "application/font-sfnt",
-  ".woff": "application/font-woff",
-  ".woff2": "font/woff2"
-};
+const XHTML_MEDIA_TYPES = /* @__PURE__ */ new Set([import_media_types.MediaType.XHTML, import_media_types.MediaType.HTML]);
 function getMetadataElement(pkg) {
   return import_index.Epub.findXmlChildByName("metadata", import_index.Epub.getXmlChildren(pkg));
 }
@@ -389,11 +366,10 @@ function removeSpineTocRef(pkg) {
   delete spine[":@"]["@_toc"];
 }
 async function collectManifestProperties(epub) {
-  var _a;
   const manifest = await epub.getManifest();
   for (const item of Object.values(manifest)) {
-    const mediaType = ((_a = item.mediaType) == null ? void 0 : _a.toLowerCase()) ?? "";
-    if (!XHTML_MEDIA_TYPES.has(mediaType)) continue;
+    const mediaType = import_media_types.MediaType.fromMime(item.mediaType ?? "");
+    if (!mediaType || !XHTML_MEDIA_TYPES.has(mediaType)) continue;
     let xml;
     try {
       xml = await epub.readXhtmlItemContents(item.id);
@@ -414,21 +390,16 @@ async function collectManifestProperties(epub) {
   }
 }
 function fixFontMimeTypes(pkg) {
-  var _a, _b;
+  var _a, _b, _c;
   const manifest = getManifestElement(pkg);
   if (!manifest) return;
   for (const item of findAllByName("item", manifest.manifest)) {
-    const mt = (((_a = item[":@"]) == null ? void 0 : _a["@_media-type"]) ?? "").toLowerCase();
-    if (!OEB_FONTS.has(mt)) continue;
-    const href = ((_b = item[":@"]) == null ? void 0 : _b["@_href"]) ?? "";
-    const dotIdx = href.lastIndexOf(".");
-    if (dotIdx === -1) continue;
-    const ext = href.slice(dotIdx).toLowerCase();
-    const corrected = FONT_MIME_BY_EXT[ext];
-    if (corrected && corrected !== mt) {
-      item[":@"] ??= {};
-      item[":@"]["@_media-type"] = corrected;
-    }
+    const declared = ((_a = item[":@"]) == null ? void 0 : _a["@_media-type"]) ?? "";
+    if (!((_b = import_media_types.MediaType.fromMime(declared)) == null ? void 0 : _b.is("font"))) continue;
+    const corrected = import_media_types.MediaType.fromPath(((_c = item[":@"]) == null ? void 0 : _c["@_href"]) ?? "");
+    if (!(corrected == null ? void 0 : corrected.is("font")) || corrected.mime === declared) continue;
+    item[":@"] ??= {};
+    item[":@"]["@_media-type"] = corrected.mime;
   }
 }
 function buildTocOl(entries) {
@@ -521,10 +492,7 @@ async function chooseNavHref(epub) {
 async function removeNcx(epub) {
   const manifest = await epub.getManifest();
   const ncxItem = Object.values(manifest).find(
-    (item) => {
-      var _a;
-      return ((_a = item.mediaType) == null ? void 0 : _a.toLowerCase()) === "application/x-dtbncx+xml";
-    }
+    (item) => import_media_types.MediaType.fromMime(item.mediaType ?? "") === import_media_types.MediaType.NCX
   );
   if (ncxItem) {
     await epub.removeManifestItem(ncxItem.id);

package/dist/upgrade.d.cts

@@ -339,10 +339,6 @@ declare class Epub {
     static assertEpub3(epub: Epub): Promise<void>;
     copy(path?: string): Promise<Epub>;
     private removeEntry;
-    /**
-     * Read raw bytes (or utf-8 text) from the underlying adapter
-     */
-    private getFileData;
     /**
      * Length of the underlying archive entry for a manifest item, in bytes
      * Necessary to compute the readium page count which is for COMPRESSED content
@@ -391,7 +387,7 @@ declare class Epub {
      */
     findMetadataItem(predicate: (entry: MetadataEntry) => boolean): Promise<{
         id: string | undefined;
-        type: `?${string}` | `a${string}` | `b${string}` | `c${string}` | `d${string}` | `e${string}` | `f${string}` | `g${string}` | `h${string}` | `i${string}` | `j${string}` | `k${string}` | `l${string}` | `m${string}` | `n${string}` | `o${string}` | `p${string}` | `q${string}` | `r${string}` | `s${string}` | `t${string}` | `u${string}` | `v${string}` | `w${string}` | `x${string}` | `y${string}` | `z${string}` | `A${string}` | `B${string}` | `C${string}` | `D${string}` | `E${string}` | `F${string}` | `G${string}` | `H${string}` | `I${string}` | `J${string}` | `K${string}` | `L${string}` | `M${string}` | `N${string}` | `O${string}` | `P${string}` | `Q${string}` | `R${string}` | `S${string}` | `T${string}` | `U${string}` | `V${string}` | `W${string}` | `X${string}` | `Y${string}` | `Z${string}`;
+        type: `a${string}` | `b${string}` | `c${string}` | `d${string}` | `e${string}` | `f${string}` | `g${string}` | `h${string}` | `i${string}` | `j${string}` | `k${string}` | `l${string}` | `m${string}` | `n${string}` | `o${string}` | `p${string}` | `q${string}` | `r${string}` | `s${string}` | `t${string}` | `u${string}` | `v${string}` | `w${string}` | `x${string}` | `y${string}` | `z${string}` | `A${string}` | `B${string}` | `C${string}` | `D${string}` | `E${string}` | `F${string}` | `G${string}` | `H${string}` | `I${string}` | `J${string}` | `K${string}` | `L${string}` | `M${string}` | `N${string}` | `O${string}` | `P${string}` | `Q${string}` | `R${string}` | `S${string}` | `T${string}` | `U${string}` | `V${string}` | `W${string}` | `X${string}` | `Y${string}` | `Z${string}` | `?${string}`;
         properties: {
             [k: string]: string;
         };
@@ -403,7 +399,7 @@ declare class Epub {
      */
     findAllMetadataItems(predicate: (entry: MetadataEntry) => boolean): Promise<{
         id: string | undefined;
-        type: `?${string}` | `a${string}` | `b${string}` | `c${string}` | `d${string}` | `e${string}` | `f${string}` | `g${string}` | `h${string}` | `i${string}` | `j${string}` | `k${string}` | `l${string}` | `m${string}` | `n${string}` | `o${string}` | `p${string}` | `q${string}` | `r${string}` | `s${string}` | `t${string}` | `u${string}` | `v${string}` | `w${string}` | `x${string}` | `y${string}` | `z${string}` | `A${string}` | `B${string}` | `C${string}` | `D${string}` | `E${string}` | `F${string}` | `G${string}` | `H${string}` | `I${string}` | `J${string}` | `K${string}` | `L${string}` | `M${string}` | `N${string}` | `O${string}` | `P${string}` | `Q${string}` | `R${string}` | `S${string}` | `T${string}` | `U${string}` | `V${string}` | `W${string}` | `X${string}` | `Y${string}` | `Z${string}`;
+        type: `a${string}` | `b${string}` | `c${string}` | `d${string}` | `e${string}` | `f${string}` | `g${string}` | `h${string}` | `i${string}` | `j${string}` | `k${string}` | `l${string}` | `m${string}` | `n${string}` | `o${string}` | `p${string}` | `q${string}` | `r${string}` | `s${string}` | `t${string}` | `u${string}` | `v${string}` | `w${string}` | `x${string}` | `y${string}` | `z${string}` | `A${string}` | `B${string}` | `C${string}` | `D${string}` | `E${string}` | `F${string}` | `G${string}` | `H${string}` | `I${string}` | `J${string}` | `K${string}` | `L${string}` | `M${string}` | `N${string}` | `O${string}` | `P${string}` | `Q${string}` | `R${string}` | `S${string}` | `T${string}` | `U${string}` | `V${string}` | `W${string}` | `X${string}` | `Y${string}` | `Z${string}` | `?${string}`;
         properties: {
             [k: string]: string;
         };
@@ -922,13 +918,31 @@ declare class Epub {
         resolveToRoot?: boolean;
     }): Promise<Navigation | null>;
     /**
-     * Returns a Zip Entry path for an HREF
+     * Name the entry a resolved URL addresses.
+     *
+     * A correctly authored publication percent-encodes its hrefs, so the
+     * decoded reading is the one the spec calls for and the one we prefer.
+     * Some publications instead write the entry name verbatim, so when the two
+     * readings differ we ask the archive which one it holds. A verbatim name
+     * carrying a bare `%`, as `100%.xhtml` does, is not a valid encoding at all
+     * and can only be its own answer.
      */
-    private resolveInternalHref;
+    private entryForUrl;
+    /**
+     * Resolve an href to the name of the archive entry it addresses.
+     *
+     * @param from The entry the href appears in; it resolves against that
+     *   entry's directory
+     * @throws when the href addresses something outside the publication
+     */
+    private resolveEntry;
     /**
      * Returns a path-relative-scheme-less URL, relative to the
      * container root.
      *
+     * An href that points outside the publication, such as an external link in
+     * a navigation document, is handed back unchanged.
+     *
      * @param href The href to resolve
      * @param [relativeTo] Optional - The href to resolve this href relative to.
          Use if resolving a relative href from a file other than the package document.