@storyteller-platform/epub 0.8.2 → 1.0.0

package/dist/index.js

@@ -1,20 +1,26 @@
-import { cp, mkdir } from "node:fs/promises";
+import { jsx as _jsx, jsxs as _jsxs } from "@storyteller-platform/epub/jsx-runtime";
 import { Mutex } from "async-mutex";
-import XMLBuilder from "fast-xml-builder";
-import { XMLParser } from "fast-xml-parser";
 import memoize from "mem";
 import { nanoid } from "nanoid";
 import { MediaType } from "@storyteller-platform/media-types";
-import { dirname } from "@storyteller-platform/path";
-import { TmpFsAdapter } from "./adapters/tmpfs.js";
+import { copyFile } from "#files";
+import { TmpFsAdapter } from "#tmpfs";
 import * as Upgrade from "./upgrade.js";
+import { createDocument, createDocumentType, declareDefaultNamespace, findXmlChildByName, findXmlChildByNameNS, findXmlDescendantByName, getXhtmlBody, insert, isElement, isText, NS, parse, replace, serialize, text, x, } from "./xml.js";
+export { TmpFsAdapter } from "#tmpfs";
 export { MemoryAdapter } from "./adapters/memory.js";
-export { TmpFsAdapter } from "./adapters/tmpfs.js";
+/**
+ * The XML surface. Publication-level operations live on {@link Epub}; for
+ * building and inspecting XML trees directly, use these.
+ *
+ * The DOM node types are re-exported so that callers do not need to depend on
+ * `@xmldom/xmldom` themselves.
+ */
+export { addLinkToXhtmlHead, adoptNamespaces, createDocument, createDocumentType, declareDefaultNamespace, findXmlChildByName, findXmlChildByNameNS, findXmlDescendantByName, findXmlDescendantByNameNS, getXhtmlBody, insert, isCdata, isComment, isElement, isText, NS, parse, replace, serialize, text, x, XMLSerializer, } from "./xml.js";
 export class EpubVersionError extends Error {
 }
 export class EpubReadOnlyError extends Error {
 }
-const OPF_NAMESPACE = "http://www.idpf.org/2007/opf";
 /**
  * makes it easy to distinguish normal hrefs from external/invalid ones
  */
@@ -34,52 +40,48 @@ function resolveEntryUrl(from, href) {
     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;
-        }
+function ensureOpfNamespace(doc) {
+    const { documentElement } = doc;
+    if (!documentElement)
+        return;
+    if (!documentElement.hasAttribute("xmlns")) {
+        declareDefaultNamespace(documentElement, NS.opf);
     }
-    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;
+/**
+ * Names within a directory must stay distinct after Unicode normalization and
+ * full case folding, since names that collapse onto one another overwrite each
+ * other on any filesystem that normalizes.
+ *
+ * @link https://www.w3.org/TR/epub-33/#sec-names-paths
+ */
+function foldPathName(path) {
+    return path.normalize("NFKC").toLowerCase();
 }
-function normalizeOpfNamespacePrefixes(doc) {
-    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 (root[":@"]?.[`@_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;
+/** The media types that make a manifest item an EPUB content document. */
+const CONTENT_DOCUMENT_MEDIA_TYPES = new Set([
+    MediaType.XHTML.mime,
+    MediaType.SVG.mime,
+]);
+/**
+ * Whether a manifest item may be referenced from the spine: it must be an EPUB
+ * content document, or a foreign content document whose manifest fallback chain
+ * reaches one.
+ *
+ * @link https://www.w3.org/TR/epub-33/#sec-item-elem
+ */
+function spineReferenceable(manifest, item) {
+    const visited = new Set();
+    let current = item;
+    while (current && !visited.has(current.id)) {
+        visited.add(current.id);
+        if (current.mediaType &&
+            CONTENT_DOCUMENT_MEDIA_TYPES.has(current.mediaType)) {
+            return true;
+        }
+        current = current.fallback ? manifest[current.fallback] : undefined;
+    }
+    return false;
 }
 /**
  * A single EPUB instance.
@@ -98,7 +100,7 @@ function normalizeOpfNamespacePrefixes(doc) {
  * const chptOneXml = await epub.readXhtmlItemContents(chptOne.id);
  *
  * const body = getBody(chptOneXml);
- * const h1 = Epub.findXmlChildByName('h1', body);
+ * const h1 = findXmlChildByName('h1', body);
  * const headingText = textContent(h1);
  *
  * await epub.setTitle(headingText);
@@ -113,65 +115,6 @@ export class Epub {
     adapter;
     inputPath;
     readonlyOverride;
-    static xmlParser = new XMLParser({
-        allowBooleanAttributes: true,
-        preserveOrder: true,
-        ignoreAttributes: false,
-        parseTagValue: false,
-    });
-    static xhtmlParser = (() => {
-        const parser = new XMLParser({
-            allowBooleanAttributes: true,
-            alwaysCreateTextNode: true,
-            preserveOrder: true,
-            ignoreAttributes: false,
-            // oxlint-disable-next-line typescript/no-deprecated entityDecoder appears completely undocumented
-            htmlEntities: true,
-            processEntities: {
-                enabled: true,
-                maxEntityCount: Infinity,
-                maxTotalExpansions: Infinity,
-            },
-            trimValues: false,
-            stopNodes: ["*.script"],
-            parseTagValue: false,
-            updateTag(_tagName, _jPath, attrs) {
-                // There's never an attribute called '/';
-                // this erroneously happens sometimes when parsing
-                // self-closing stop nodes with ignoreAttributes: false
-                // and allowBooleanAttributes: true.
-                //
-                // Also attrs is undefined if there are no attrs;
-                // the types are wrong.
-                // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-                if (attrs && "@_/" in attrs) {
-                    delete attrs["@_/"];
-                }
-                return true;
-            },
-        });
-        // fast-xml-parser's htmlEntities option seems to map   to
-        // regular space (U+0020) instead of non-breaking space (U+00A0).
-        // Override the entity mapping to use the correct character.
-        // oxlint-disable-next-line typescript/no-deprecated entityDecoder appears completely undocumented
-        parser.addEntity("nbsp", "\u00A0");
-        // oxlint-disable-next-line typescript/no-deprecated entityDecoder appears completely undocumented
-        parser.addEntity("#160", "\u00A0");
-        return parser;
-    })();
-    static xmlBuilder = new XMLBuilder({
-        preserveOrder: true,
-        format: true,
-        ignoreAttributes: false,
-        suppressEmptyNode: true,
-    });
-    static xhtmlBuilder = new XMLBuilder({
-        preserveOrder: true,
-        ignoreAttributes: false,
-        stopNodes: ["*.script"],
-        suppressEmptyNode: true,
-        processEntities: true,
-    });
     /**
      * Format a duration, provided as a number of seconds, as
      * a SMIL clock value, to be used for Media Overlays.
@@ -188,135 +131,6 @@ export class Epub {
         // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
         return `${hours.toString().padStart(2, "0")}:${minutes.toString().padStart(2, "0")}:${seconds.padStart(2, "0")}.${millis ?? "0"}`;
     }
-    /**
-     * Given an XML structure representing a complete XHTML document,
-     * add a `link` element to the `head` of the document.
-     *
-     * This method modifies the provided XML structure.
-     */
-    static addLinkToXhtmlHead(xml, link) {
-        const html = Epub.findXmlChildByName("html", xml);
-        if (!html)
-            throw new Error("Invalid XHTML document: no html element");
-        const head = Epub.findXmlChildByName("head", html.html);
-        if (!head)
-            throw new Error("Invalid XHTML document: no head element");
-        head["head"].push({
-            link: [],
-            ":@": {
-                "@_rel": link.rel,
-                "@_href": link.href,
-                "@_type": link.type,
-            },
-        });
-    }
-    /**
-     * Given an XML structure representing a complete XHTML document,
-     * return the sub-structure representing the children of the
-     * document's body element.
-     */
-    static getXhtmlBody(xml) {
-        const html = Epub.findXmlChildByName("html", xml);
-        if (!html)
-            throw new Error("Invalid XHTML document: no html element");
-        const body = Epub.findXmlChildByName("body", html["html"]);
-        if (!body)
-            throw new Error("Invalid XHTML document: No body element");
-        return body["body"];
-    }
-    static createXmlElement(name, properties, children = []) {
-        return {
-            ":@": Object.fromEntries(Object.entries(properties).map(([prop, value]) => [`@_${prop}`, value])),
-            [name]: children,
-        };
-    }
-    static createXmlTextNode(text) {
-        return { ["#text"]: text };
-    }
-    /**
-     * Given an XML structure representing a complete XHTML document,
-     * return a string representing the concatenation of all text nodes
-     * in the document.
-     */
-    static getXhtmlTextContent(xml) {
-        let text = "";
-        for (const child of xml) {
-            if (Epub.isXmlTextNode(child)) {
-                text += child["#text"];
-                continue;
-            }
-            const children = Epub.getXmlChildren(child);
-            text += Epub.getXhtmlTextContent(children);
-        }
-        return text;
-    }
-    /**
-     * Given an XMLElement, return its attributes.
-     */
-    static getXmlAttributes(element) {
-        return Object.fromEntries(Object.entries(element[":@"] ?? {}).map(([key, value]) => [
-            key.slice(2),
-            value,
-        ]));
-    }
-    /**
-     * Given an XMLElement, return its tag name.
-     */
-    static getXmlElementName(element) {
-        const keys = Object.keys(element);
-        const elementName = keys.find((key) => key !== ":@" && key !== "#text");
-        if (!elementName)
-            throw new Error(`Invalid XML Element: missing tag name\n${JSON.stringify(element, null, 2)}`);
-        return elementName;
-    }
-    /**
-     * Given an XMLElement, return a list of its children
-     */
-    static getXmlChildren(element) {
-        const elementName = Epub.getXmlElementName(element);
-        // It's not clear to me why this needs to be cast
-        return element[elementName];
-    }
-    static replaceXmlChildren(element, children) {
-        const elementName = Epub.getXmlElementName(element);
-        element[elementName] = children;
-    }
-    /**
-     * Given an XML structure, find the first child matching
-     * the provided name and optional filter.
-     */
-    static findXmlChildByName(name, xml, filter) {
-        const element = xml.find((e) => name in e && (filter ? filter(e) : true));
-        return element;
-    }
-    /**
-     * Given an XML structure, find the first descendant matching
-     * the provided name and optional filter.
-     *
-     * Will perform a breadth first search for the element, returning
-     * the highest element in the tree matching the name and filter.
-     */
-    static findXmlDescendantByName(name, xml, filter) {
-        const found = Epub.findXmlChildByName(name, xml, filter);
-        if (found)
-            return found;
-        for (const node of xml) {
-            if (Epub.isXmlTextNode(node))
-                continue;
-            const children = Epub.getXmlChildren(node);
-            const found = this.findXmlDescendantByName(name, children, filter);
-            if (found)
-                return found;
-        }
-        return undefined;
-    }
-    /**
-     * Given an XMLNode, determine whether it represents
-     * a text node or an XML element.
-     */
-    static isXmlTextNode(node) {
-        return "#text" in node;
-    }
     rootfile = null;
     manifest = null;
     spine = null;
@@ -425,16 +239,15 @@ export class Epub {
         const containerString = await this.adapter.read("META-INF/container.xml", "utf-8");
         if (!containerString)
             throw new Error("Failed to parse EPUB: Missing META-INF/container.xml");
-        const containerDocument = Epub.xmlParser.parse(containerString);
-        const container = Epub.findXmlChildByName("container", containerDocument);
+        const containerDocument = parse(containerString, "text/xml");
+        const container = containerDocument.documentElement;
         if (!container)
             throw new Error("Failed to parse EPUB container.xml: Found no container element");
-        const rootfiles = Epub.findXmlChildByName("rootfiles", Epub.getXmlChildren(container));
+        const rootfiles = findXmlChildByName("rootfiles", container);
         if (!rootfiles)
             throw new Error("Failed to parse EPUB container.xml: Found no rootfiles element");
-        const rootfile = Epub.findXmlChildByName("rootfile", Epub.getXmlChildren(rootfiles), (node) => !Epub.isXmlTextNode(node) &&
-            node[":@"]?.["@_media-type"] === MediaType.OPF.mime);
-        const fullPath = rootfile?.[":@"]?.["@_full-path"];
+        const rootfile = findXmlChildByName("rootfile", rootfiles, (element) => element.getAttribute("media-type") === MediaType.OPF.mime);
+        const fullPath = rootfile?.getAttribute("full-path");
         if (!fullPath)
             throw new Error("Failed to parse EPUB container.xml: Found no rootfile element");
         this.rootfile = await this.resolveEntry("", fullPath);
@@ -448,12 +261,15 @@ export class Epub {
         return packageDocumentString;
     }
     async getPackageDocument() {
-        const packageDocument = Epub.xmlParser.parse(await this.getPackageDocumentSource());
-        return normalizeOpfNamespacePrefixes(packageDocument);
+        const packageDocument = parse(await this.getPackageDocumentSource(), "text/xml");
+        ensureOpfNamespace(packageDocument);
+        return packageDocument;
     }
     async getPackageElement() {
         const packageDocument = await this.getPackageDocument();
-        const packageElement = Epub.findXmlChildByName("package", packageDocument);
+        const packageElement = packageDocument.documentElement?.localName === "package"
+            ? packageDocument.documentElement
+            : null;
         if (!packageElement) {
             throw new Error("Failed to parse EPUB: Found no package element in package document");
         }
@@ -475,12 +291,14 @@ export class Epub {
         this.assertWritable();
         await this.packageMutex.runExclusive(async () => {
             const packageDocument = await this.getPackageDocument();
-            const packageElement = Epub.findXmlChildByName("package", packageDocument);
+            const packageElement = packageDocument.documentElement?.localName === "package"
+                ? packageDocument.documentElement
+                : null;
             if (!packageElement) {
                 throw new Error("Failed to parse EPUB: Found no package element in package document");
             }
-            const produced = (await producer(packageElement));
-            const updatedPackageDocument = Epub.xmlBuilder.build(produced ?? packageDocument);
+            const produced = await producer(packageElement);
+            const updatedPackageDocument = serialize(produced ?? packageDocument);
             const rootfile = await this.getRootfile();
             await this.writeEntryContents(rootfile, updatedPackageDocument, "utf-8");
         });
@@ -497,24 +315,25 @@ export class Epub {
         if (this.manifest !== null)
             return this.manifest;
         const packageElement = await this.getPackageElement();
-        const manifest = Epub.findXmlChildByName("manifest", Epub.getXmlChildren(packageElement));
-        if (!manifest)
+        const manifest = findXmlChildByNameNS(NS.opf, "manifest", packageElement);
+        if (!manifest) {
             throw new Error("Failed to parse EPUB: Found no manifest element in package document");
-        this.manifest = Epub.getXmlChildren(manifest).reduce((acc, item) => {
-            if (Epub.isXmlTextNode(item))
-                return acc;
-            if (!item[":@"]?.["@_id"] || !item[":@"]["@_href"]) {
+        }
+        this.manifest = Array.from(manifest.children).reduce((acc, item) => {
+            const id = item.getAttribute("id");
+            const href = item.getAttribute("href");
+            if (!id || !href) {
                 return acc;
             }
             return {
                 ...acc,
-                [item[":@"]["@_id"]]: {
-                    id: item[":@"]["@_id"],
-                    href: item[":@"]["@_href"],
-                    mediaType: item[":@"]["@_media-type"],
-                    mediaOverlay: item[":@"]["@_media-overlay"],
-                    fallback: item[":@"]["@_fallback"],
-                    properties: item[":@"]["@_properties"]?.split(" "),
+                [id]: {
+                    id,
+                    href,
+                    mediaType: item.getAttribute("media-type") ?? undefined,
+                    mediaOverlay: item.getAttribute("media-overlay") ?? undefined,
+                    fallback: item.getAttribute("fallback") ?? undefined,
+                    properties: item.getAttribute("properties")?.split(" ") ?? undefined,
                 },
             };
         }, {});
@@ -531,13 +350,11 @@ export class Epub {
      * array, this method is only meant to be used internally.
      */
     findMetadataIndex(packageElement, predicate) {
-        const metadataElement = Epub.findXmlChildByName("metadata", Epub.getXmlChildren(packageElement));
+        const metadataElement = findXmlChildByNameNS(NS.opf, "metadata", packageElement);
         if (!metadataElement)
             throw new Error("Failed to parse EPUB: Found no metadata element in package document");
-        return metadataElement.metadata.findIndex((node) => {
+        return Array.from(metadataElement.children).findIndex((node) => {
             const item = Epub.parseMetadataItem(node);
-            if (!item)
-                return false;
             return predicate(item);
         });
     }
@@ -555,36 +372,26 @@ export class Epub {
      */
     async findAllMetadataItems(predicate) {
         const packageElement = await this.getPackageElement();
-        const metadataElement = Epub.findXmlChildByName("metadata", Epub.getXmlChildren(packageElement));
+        const metadataElement = findXmlChildByNameNS(NS.opf, "metadata", packageElement);
         if (!metadataElement)
             throw new Error("Failed to parse EPUB: Found no metadata element in package document");
-        const elements = metadataElement.metadata.filter((node) => {
+        const elements = metadataElement.children.filter((node) => {
             const item = Epub.parseMetadataItem(node);
-            if (!item)
-                return false;
             return predicate(item);
         });
-        return elements
-            .map((element) => Epub.parseMetadataItem(element))
-            .filter((item) => !!item);
+        return elements.map((element) => Epub.parseMetadataItem(element));
     }
-    static parseMetadataItem(node) {
-        if (Epub.isXmlTextNode(node))
-            return null;
-        const elementName = Epub.getXmlElementName(node);
-        const textNode = Epub.getXmlChildren(node)[0];
+    static parseMetadataItem(element) {
+        const elementName = element.nodeName;
+        const textNode = element.firstChild;
         // https://www.w3.org/TR/epub-33/#sec-metadata-values
         // Whitespace within these element values is not significant.
         // Sequences of one or more whitespace characters are collapsed
         // to a single space [infra] during processing .
-        const value = !textNode || !Epub.isXmlTextNode(textNode)
+        const value = !textNode || !isText(textNode)
             ? undefined
-            : textNode["#text"].replaceAll(/\s+/g, " ");
-        const attributes = node[":@"] ?? {};
-        const { id, ...properties } = Object.fromEntries(Object.entries(attributes).map(([attrName, value]) => [
-            attrName.slice(2),
-            value,
-        ]));
+            : textNode.data.replaceAll(/\s+/g, " ").trim();
+        const { id, ...properties } = Object.fromEntries(Array.from(element.attributes).map((attr) => [attr.name, attr.value]));
         return {
             id,
             type: elementName,
@@ -605,12 +412,10 @@ export class Epub {
      */
     async getMetadata() {
         const packageElement = await this.getPackageElement();
-        const metadataElement = Epub.findXmlChildByName("metadata", Epub.getXmlChildren(packageElement));
+        const metadataElement = findXmlChildByNameNS(NS.opf, "metadata", packageElement);
         if (!metadataElement)
             throw new Error("Failed to parse EPUB: Found no metadata element in package document");
-        const metadata = metadataElement.metadata
-            .map((node) => Epub.parseMetadataItem(node))
-            .filter((node) => !!node);
+        const metadata = Array.from(metadataElement.children).map((node) => Epub.parseMetadataItem(node));
         return metadata;
     }
     /**
@@ -675,7 +480,7 @@ export class Epub {
      */
     async setUniqueIdentifier(identifier) {
         await this.withPackage(async (packageElement) => {
-            const metadata = Epub.findXmlChildByName("metadata", Epub.getXmlChildren(packageElement));
+            const metadata = findXmlChildByNameNS(NS.opf, "metadata", packageElement);
             if (!metadata) {
                 throw new Error("Failed to parse EPUB: found no metadata element in package document");
             }
@@ -683,23 +488,15 @@ export class Epub {
             if (!uniqueId) {
                 // Create a new unique identifier id
                 const newUniqueId = nanoid();
-                packageElement[":@"] = {
-                    ...packageElement[":@"],
-                    "@_unique-identifier": newUniqueId,
-                };
+                packageElement.setAttribute("unique-identifier", newUniqueId);
                 uniqueId = newUniqueId;
             }
-            const children = Epub.getXmlChildren(metadata);
-            const entry = Epub.findXmlChildByName("dc:identifier", children, (node) => node[":@"]?.["@_id"] === uniqueId);
+            const entry = findXmlChildByNameNS(NS.dc, "identifier", metadata, (node) => node.getAttribute("id") === uniqueId);
             if (entry) {
-                children.splice(children.indexOf(entry), 1, Epub.createXmlElement("dc:identifier", { id: uniqueId }, [
-                    Epub.createXmlTextNode(identifier),
-                ]));
+                replace(metadata, _jsx("dc:identifier", { id: uniqueId, children: identifier }), entry);
                 return;
             }
-            children.push(Epub.createXmlElement("dc:identifier", { id: uniqueId }, [
-                Epub.createXmlTextNode(identifier),
-            ]));
+            insert(metadata, _jsx("dc:identifier", { id: uniqueId, children: identifier }));
         });
     }
     /**
@@ -710,7 +507,7 @@ export class Epub {
      */
     async getUniqueIdentifierId() {
         const packageElement = await this.getPackageElement();
-        return packageElement[":@"]?.["@_unique-identifier"] ?? null;
+        return packageElement.getAttribute("unique-identifier") ?? null;
     }
     /**
      * Collect `dc:identifier` or `dc:source` entries, attaching the value and
@@ -855,47 +652,37 @@ export class Epub {
     async setIdentifiers(identifiers) {
         const uniqueId = await this.getUniqueIdentifierId();
         await this.withPackage((packageElement) => {
-            const metadata = Epub.findXmlChildByName("metadata", Epub.getXmlChildren(packageElement));
-            if (!metadata)
+            const metadata = findXmlChildByNameNS(NS.opf, "metadata", packageElement);
+            if (!metadata) {
                 throw new Error("Failed to parse EPUB: found no metadata element in package document");
-            const children = Epub.getXmlChildren(metadata);
+            }
             const removedIds = new Set();
-            for (let i = children.length - 1; i >= 0; i--) {
-                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-                const node = children[i];
-                if (Epub.isXmlTextNode(node) ||
-                    Epub.getXmlElementName(node) !== "dc:identifier") {
+            for (const child of Array.from(metadata.children)) {
+                if (child.nodeName !== "dc:identifier") {
                     continue;
                 }
-                const id = node[":@"]?.["@_id"];
+                const id = child.getAttribute("id");
                 if (id && id === uniqueId) {
                     continue;
                 }
                 if (id) {
                     removedIds.add(id);
                 }
-                children.splice(i, 1);
+                metadata.removeChild(child);
             }
-            Epub.removeRefiningMetas(children, removedIds, ["identifier-type"]);
+            Epub.removeRefiningMetas(metadata, removedIds, ["identifier-type"]);
             for (const identifier of identifiers) {
                 // we don't allow you to set the unique identifier, you need to use setUniqueIdentifier
                 if (identifier.id && identifier.id === uniqueId)
                     continue;
                 const id = identifier.id ??
                     (identifier.identifierType !== undefined ? nanoid() : undefined);
-                children.push(Epub.createXmlElement("dc:identifier", {
-                    ...(id && { id }),
-                    ...(identifier.scheme &&
-                        identifier.identifierType === undefined && {
+                insert(metadata, _jsx("dc:identifier", { ...(id && { id }), ...(identifier.scheme &&
+                        identifier.id === undefined && {
                         "opf:scheme": identifier.scheme,
-                    }),
-                }, [Epub.createXmlTextNode(identifier.value)]));
+                    }), children: identifier.value }));
                 if (identifier.identifierType !== undefined && id) {
-                    children.push(Epub.createXmlElement("meta", {
-                        refines: `#${id}`,
-                        property: "identifier-type",
-                        ...(identifier.scheme && { scheme: identifier.scheme }),
-                    }, [Epub.createXmlTextNode(identifier.identifierType)]));
+                    insert(metadata, _jsx("meta", { refines: `#${id}`, property: "identifier-type", ...(identifier.scheme && { scheme: identifier.scheme }), children: identifier.identifierType }));
                 }
             }
         });
@@ -903,21 +690,19 @@ export class Epub {
     /**
      * Remove `meta` refinements pointing at any of the given ids,
      * restricted to the given `property` values as a cleanup step
-     * Mutates `children` in place.
+     * Mutates `metadata` in place.
      */
-    static removeRefiningMetas(children, ids, properties) {
-        for (let i = children.length - 1; i >= 0; i--) {
-            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-            const node = children[i];
-            if (Epub.isXmlTextNode(node) || Epub.getXmlElementName(node) !== "meta") {
+    static removeRefiningMetas(metadata, ids, properties) {
+        for (const child of Array.from(metadata.children)) {
+            if (child.nodeName !== "meta") {
                 continue;
             }
-            const property = node[":@"]?.["@_property"];
-            if (!property || !properties.includes(property))
+            const property = child.getAttribute("property");
+            if (properties && (!property || !properties.includes(property)))
                 continue;
-            const refines = node[":@"]?.["@_refines"]?.slice(1);
+            const refines = child.getAttribute("refines")?.slice(1);
             if (refines && ids.has(refines)) {
-                children.splice(i, 1);
+                metadata.removeChild(child);
             }
         }
     }
@@ -937,47 +722,37 @@ export class Epub {
      */
     async setSources(sources) {
         await this.withPackage((packageElement) => {
-            const metadata = Epub.findXmlChildByName("metadata", Epub.getXmlChildren(packageElement));
-            if (!metadata)
+            const metadata = findXmlChildByNameNS(NS.opf, "metadata", packageElement);
+            if (!metadata) {
                 throw new Error("Failed to parse EPUB: found no metadata element in package document");
-            const children = Epub.getXmlChildren(metadata);
+            }
             const removedIds = new Set();
-            for (let i = children.length - 1; i >= 0; i--) {
-                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-                const node = children[i];
-                if (Epub.isXmlTextNode(node) ||
-                    Epub.getXmlElementName(node) !== "dc:source") {
+            for (const child of Array.from(metadata.children)) {
+                if (child.nodeName !== "dc:source") {
                     continue;
                 }
-                const id = node[":@"]?.["@_id"];
+                const id = child.getAttribute("id");
                 if (id) {
                     removedIds.add(id);
                 }
-                children.splice(i, 1);
+                metadata.removeChild(child);
             }
-            Epub.removeRefiningMetas(children, removedIds, [
+            Epub.removeRefiningMetas(metadata, removedIds, [
                 "identifier-type",
                 "source-of",
             ]);
             for (const source of sources) {
                 const needsId = source.identifierType !== undefined || source.isPageBreakSource;
                 const id = source.id ?? (needsId ? nanoid() : undefined);
-                children.push(Epub.createXmlElement("dc:source", {
-                    ...(id && { id }),
-                    ...(source.scheme &&
+                insert(metadata, _jsx("dc:source", { ...(id && { id }), ...(source.scheme &&
                         source.identifierType === undefined && {
                         "opf:scheme": source.scheme,
-                    }),
-                }, [Epub.createXmlTextNode(source.value)]));
+                    }), children: source.value }));
                 if (source.identifierType !== undefined && id) {
-                    children.push(Epub.createXmlElement("meta", {
-                        refines: `#${id}`,
-                        property: "identifier-type",
-                        ...(source.scheme && { scheme: source.scheme }),
-                    }, [Epub.createXmlTextNode(source.identifierType)]));
+                    insert(metadata, _jsx("meta", { refines: `#${id}`, property: "identifier-type", ...(source.scheme && { scheme: source.scheme }), children: source.identifierType }));
                 }
                 if (source.isPageBreakSource && id) {
-                    children.push(Epub.createXmlElement("meta", { refines: `#${id}`, property: "source-of" }, [Epub.createXmlTextNode("pagination")]));
+                    insert(metadata, _jsx("meta", { refines: `#${id}`, property: "source-of", children: "pagination" }));
                 }
             }
         });
@@ -991,11 +766,11 @@ export class Epub {
      */
     async getEpub2CoverImage() {
         const packageElement = await this.getPackageElement();
-        const metadataElement = Epub.findXmlChildByName("metadata", Epub.getXmlChildren(packageElement));
+        const metadataElement = findXmlChildByNameNS(NS.opf, "metadata", packageElement);
         if (!metadataElement)
             throw new Error("Failed to parse EPUB: Found no metadata element in package document");
-        const coverImageElement = Epub.getXmlChildren(metadataElement).find((node) => !Epub.isXmlTextNode(node) && node[":@"]?.["@_name"] === "cover");
-        const manifestItemId = coverImageElement?.[":@"]?.["@_content"];
+        const coverImageElement = Array.from(metadataElement.children).find((element) => element.getAttribute("name") === "cover");
+        const manifestItemId = coverImageElement?.getAttribute("content");
         if (!manifestItemId)
             return null;
         const manifest = await this.getManifest();
@@ -1121,7 +896,7 @@ export class Epub {
      */
     async getBaseDirection() {
         const packageEl = await this.getPackageElement();
-        const dir = packageEl[":@"]?.["@_dir"];
+        const dir = packageEl.getAttribute("dir");
         if (dir !== "ltr" && dir !== "rtl" && dir !== "auto") {
             return "auto";
         }
@@ -1198,24 +973,14 @@ export class Epub {
      */
     async removeSubject(index) {
         await this.withPackage((packageElement) => {
-            const metadata = Epub.findXmlChildByName("metadata", Epub.getXmlChildren(packageElement));
+            const metadata = findXmlChildByNameNS(NS.opf, "metadata", packageElement);
             if (!metadata)
                 throw new Error("Failed to parse EPUB: found no metadata element in package document");
-            let subjectCount = null;
-            let metadataIndex = null;
-            for (const meta of Epub.getXmlChildren(metadata)) {
-                if (subjectCount === index)
-                    break;
-                metadataIndex = metadataIndex === null ? 0 : metadataIndex + 1;
-                if (Epub.isXmlTextNode(meta))
-                    continue;
-                if (Epub.getXmlElementName(meta) !== "dc:subject")
-                    continue;
-                subjectCount = subjectCount === null ? 0 : subjectCount + 1;
-            }
-            if (subjectCount === null || metadataIndex === null)
+            const subjects = metadata.children.filter((child) => child.nodeName === "dc:subject");
+            const subject = subjects[index];
+            if (!subject)
                 return;
-            Epub.getXmlChildren(metadata).splice(metadataIndex, 1);
+            metadata.removeChild(subject);
         });
     }
     /**
@@ -1412,7 +1177,7 @@ export class Epub {
      */
     async getPackageVocabularyPrefixes() {
         const packageElement = await this.getPackageElement();
-        const prefixValue = packageElement[":@"]?.["@_prefix"];
+        const prefixValue = packageElement.getAttribute("prefix");
         if (!prefixValue)
             return {};
         const matches = prefixValue.matchAll(/(?:([a-z]+): +(\S+)\s*)/gs);
@@ -1427,10 +1192,9 @@ export class Epub {
         await this.withPackage(async (packageElement) => {
             const prefixes = await this.getPackageVocabularyPrefixes();
             prefixes[prefix] = uri;
-            packageElement[":@"] ??= {};
-            packageElement[":@"]["@_prefix"] = Object.entries(prefixes)
+            packageElement.setAttribute("prefix", Object.entries(prefixes)
                 .map(([p, u]) => `${p}: ${u}`)
-                .join("\n    ");
+                .join("\n    "));
         });
     }
     /**
@@ -1447,49 +1211,44 @@ export class Epub {
     // rather than a single string, to support expanded titles.
     async setTitle(title) {
         await this.withPackage((packageElement) => {
-            const metadata = Epub.findXmlChildByName("metadata", Epub.getXmlChildren(packageElement));
-            if (!metadata)
+            const metadata = findXmlChildByNameNS(NS.opf, "metadata", packageElement);
+            if (!metadata) {
                 throw new Error("Failed to parse EPUB: found no metadata element in package document");
-            const titleElement = Epub.findXmlChildByName("dc:title", metadata.metadata);
+            }
+            const titleElement = findXmlChildByNameNS(NS.dc, "title", metadata);
             if (!titleElement) {
-                Epub.getXmlChildren(metadata).push(Epub.createXmlElement("dc:title", {}, [
-                    Epub.createXmlTextNode(title),
-                ]));
+                insert(metadata, _jsx("dc:title", { children: title }));
             }
             else {
-                titleElement["dc:title"] = [Epub.createXmlTextNode(title)];
+                while (titleElement.firstChild) {
+                    titleElement.removeChild(titleElement.firstChild);
+                }
+                insert(titleElement, text(title));
             }
         });
     }
     async setTitles(entries) {
         await this.withPackage((packageElement) => {
-            const metadata = Epub.findXmlChildByName("metadata", Epub.getXmlChildren(packageElement));
+            const metadata = findXmlChildByNameNS(NS.opf, "metadata", packageElement);
             if (!metadata) {
                 throw new Error("Failed to parse EPUB: found no metadata element in package document");
             }
-            const metadataEntries = Epub.getXmlChildren(metadata);
-            for (let i = metadataEntries.length - 1; i >= 0; i--) {
-                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-                const meta = metadataEntries[i];
-                if (Epub.isXmlTextNode(meta))
-                    continue;
-                if (Epub.getXmlElementName(meta) === "dc:title" ||
-                    meta[":@"]?.["@_property"] === "title-type" ||
-                    meta[":@"]?.["@_property"] === "display-seq") {
-                    metadataEntries.splice(i, 1);
+            for (const meta of Array.from(metadata.children)) {
+                if (meta.nodeName === "dc:title" ||
+                    meta.getAttribute("property") === "title-type" ||
+                    meta.getAttribute("property") === "display-seq") {
+                    metadata.removeChild(meta);
                 }
             }
             for (let i = 0; i < entries.length; i++) {
                 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
                 const entry = entries[i];
                 const id = nanoid();
-                metadataEntries.push(Epub.createXmlElement("dc:title", { id }, [
-                    Epub.createXmlTextNode(entry.title),
-                ]));
+                insert(metadata, _jsx("dc:title", { id: id, children: entry.title }));
                 if (entry.type) {
-                    metadataEntries.push(Epub.createXmlElement("meta", { refines: `#${id}`, property: "title-type" }, [Epub.createXmlTextNode(entry.type)]));
+                    insert(metadata, _jsx("meta", { refines: `#${id}`, property: "title-type", children: entry.type }));
                 }
-                metadataEntries.push(Epub.createXmlElement("meta", { refines: `#${id}`, property: "display-seq" }, [Epub.createXmlTextNode((i + 1).toString())]));
+                insert(metadata, _jsx("meta", { refines: `#${id}`, property: "display-seq", children: (i + 1).toString() }));
             }
         });
     }
@@ -1530,24 +1289,24 @@ export class Epub {
         // We have to manually find the correct insertion point
         // based on the provided index
         await this.withPackage((packageElement) => {
-            const metadata = Epub.findXmlChildByName("metadata", Epub.getXmlChildren(packageElement));
+            const metadata = findXmlChildByNameNS(NS.opf, "metadata", packageElement);
             if (!metadata)
                 throw new Error("Failed to parse EPUB: found no metadata element in package document");
             let collectionCount = 0;
             let metadataIndex = 0;
-            for (const meta of Epub.getXmlChildren(metadata)) {
+            for (const meta of metadata.childNodes) {
                 if (collectionCount === index)
                     break;
                 metadataIndex++;
-                if (Epub.isXmlTextNode(meta))
+                if (!isElement(meta))
                     continue;
-                if (Epub.getXmlElementName(meta) !== "meta")
+                if (meta.nodeName !== "meta")
                     continue;
-                if (meta[":@"]?.["@_property"] !== "belongs-to-collection")
+                if (meta.getAttribute("property") !== "belongs-to-collection")
                     continue;
                 collectionCount++;
             }
-            Epub.getXmlChildren(metadata).splice(metadataIndex, 0, Epub.createXmlElement("meta", { id: collectionId, property: "belongs-to-collection" }, [Epub.createXmlTextNode(collection.name)]));
+            insert(metadata, _jsx("meta", { id: collectionId, property: "belongs-to-collection", children: collection.name }), metadata.childNodes.item(metadataIndex));
         });
         // These can all just go at the end; order is only
         // important for the `dc:creator`/`dc:contributor`
@@ -1578,38 +1337,20 @@ export class Epub {
      */
     async removeCollection(index) {
         await this.withPackage((packageElement) => {
-            const metadata = Epub.findXmlChildByName("metadata", Epub.getXmlChildren(packageElement));
-            if (!metadata)
+            const metadata = findXmlChildByNameNS(NS.opf, "metadata", packageElement);
+            if (!metadata) {
                 throw new Error("Failed to parse EPUB: found no metadata element in package document");
-            let collectionCount = null;
-            let metadataIndex = null;
-            for (const meta of Epub.getXmlChildren(metadata)) {
-                if (collectionCount === index)
-                    break;
-                metadataIndex = metadataIndex === null ? 0 : metadataIndex + 1;
-                if (Epub.isXmlTextNode(meta))
-                    continue;
-                if (Epub.getXmlElementName(meta) !== "meta")
-                    continue;
-                if (meta[":@"]?.["@_property"] !== "belongs-to-collection")
-                    continue;
-                collectionCount = collectionCount === null ? 0 : collectionCount + 1;
             }
-            if (collectionCount === null || metadataIndex === null)
+            // The index refers to what `getCollections()` returns, so filter the
+            // same way before indexing
+            const removed = Array.from(metadata.children).filter((child) => child.getAttribute("property") === "belongs-to-collection" &&
+                !!child.textContent?.trim())[index];
+            if (!removed)
                 return;
-            const [removed] = Epub.getXmlChildren(metadata).splice(metadataIndex, 1);
-            if (removed && !Epub.isXmlTextNode(removed) && removed[":@"]?.["@_id"]) {
-                const id = removed[":@"]["@_id"];
-                const newChildren = Epub.getXmlChildren(metadata).filter((node) => {
-                    if (Epub.isXmlTextNode(node))
-                        return true;
-                    if (Epub.getXmlElementName(node) !== "meta")
-                        return true;
-                    if (node[":@"]?.["@_refines"] !== `#${id}`)
-                        return true;
-                    return false;
-                });
-                Epub.replaceXmlChildren(metadata, newChildren);
+            const removedId = removed.getAttribute("id");
+            metadata.removeChild(removed);
+            if (removedId) {
+                Epub.removeRefiningMetas(metadata, new Set([removedId]));
             }
         });
     }
@@ -1692,24 +1433,24 @@ export class Epub {
         // We have to manually find the correct insertion point
         // based on the provided index
         await this.withPackage((packageElement) => {
-            const metadata = Epub.findXmlChildByName("metadata", Epub.getXmlChildren(packageElement));
+            const metadata = findXmlChildByNameNS(NS.opf, "metadata", packageElement);
             if (!metadata)
                 throw new Error("Failed to parse EPUB: found no metadata element in package document");
             let creatorCount = 0;
             let metadataIndex = 0;
-            for (const meta of Epub.getXmlChildren(metadata)) {
+            for (const meta of metadata.childNodes) {
                 if (creatorCount === index)
                     break;
                 metadataIndex++;
-                if (Epub.isXmlTextNode(meta))
+                if (!isElement(meta))
+                    continue;
+                if (meta.nodeName !== `dc:${type}`)
                     continue;
-                if (Epub.getXmlElementName(meta) !== `dc:${type}`)
+                if (meta.getAttribute("property") !== "belongs-to-collection")
                     continue;
                 creatorCount++;
             }
-            Epub.getXmlChildren(metadata).splice(metadataIndex, 0, Epub.createXmlElement(`dc:${type}`, { id: creatorId }, [
-                Epub.createXmlTextNode(creator.name),
-            ]));
+            insert(metadata, x(`dc:${type}`, { id: creatorId }, creator.name), metadata.childNodes.item(metadataIndex));
         });
         // These can all just go at the end; order is only
         // important for the `dc:creator`/`dc:contributor`
@@ -1756,36 +1497,16 @@ export class Epub {
      */
     async removeCreator(index, type = "creator") {
         await this.withPackage((packageElement) => {
-            const metadata = Epub.findXmlChildByName("metadata", Epub.getXmlChildren(packageElement));
+            const metadata = findXmlChildByNameNS(NS.opf, "metadata", packageElement);
             if (!metadata)
                 throw new Error("Failed to parse EPUB: found no metadata element in package document");
-            let creatorCount = null;
-            let metadataIndex = null;
-            for (const meta of Epub.getXmlChildren(metadata)) {
-                if (creatorCount === index)
-                    break;
-                metadataIndex = metadataIndex === null ? 0 : metadataIndex + 1;
-                if (Epub.isXmlTextNode(meta))
-                    continue;
-                if (Epub.getXmlElementName(meta) !== `dc:${type}`)
-                    continue;
-                creatorCount = creatorCount === null ? 0 : creatorCount + 1;
-            }
-            if (creatorCount === null || metadataIndex === null)
+            const toRemove = Array.from(metadata.children).filter((child) => child.nodeName === `dc:${type}`)[index];
+            if (!toRemove)
                 return;
-            const [removed] = Epub.getXmlChildren(metadata).splice(metadataIndex, 1);
-            if (removed && !Epub.isXmlTextNode(removed) && removed[":@"]?.["@_id"]) {
-                const id = removed[":@"]["@_id"];
-                const newChildren = Epub.getXmlChildren(metadata).filter((node) => {
-                    if (Epub.isXmlTextNode(node))
-                        return true;
-                    if (Epub.getXmlElementName(node) !== "meta")
-                        return true;
-                    if (node[":@"]?.["@_refines"] !== `#${id}`)
-                        return true;
-                    return false;
-                });
-                Epub.replaceXmlChildren(metadata, newChildren);
+            const id = toRemove.getAttribute("id");
+            metadata.removeChild(toRemove);
+            if (id) {
+                Epub.removeRefiningMetas(metadata, new Set([id]));
             }
         });
     }
@@ -1822,17 +1543,14 @@ export class Epub {
         if (this.spine !== null)
             return this.spine;
         const packageElement = await this.getPackageElement();
-        const spine = Epub.findXmlChildByName("spine", Epub.getXmlChildren(packageElement));
+        const spine = findXmlChildByNameNS(NS.opf, "spine", packageElement);
         if (!spine)
             throw new Error("Failed to parse EPUB: Found no spine element in package document");
-        this.spine = spine["spine"]
-            .filter((node) => !Epub.isXmlTextNode(node))
+        this.spine = Array.from(spine.children)
             .map((itemref) => {
-            const idRef = itemref[":@"]?.["@_idref"];
-            const linear = itemref[":@"]?.["@_linear"];
             return {
-                itemRef: idRef,
-                linear: linear === "no" ? false : true,
+                itemRef: itemref.getAttribute("idref"),
+                linear: itemref.getAttribute("linear") !== "no",
             };
         })
             .filter((itemref) => !!itemref.itemRef);
@@ -1871,21 +1589,24 @@ export class Epub {
      * @link https://www.w3.org/TR/epub-33/#sec-spine-elem
      */
     async addSpineItem(manifestId, index) {
-        const item = Epub.createXmlElement("itemref", { idref: manifestId });
+        const item = _jsx("itemref", { idref: manifestId });
         const manifest = await this.getManifest();
         const manifestItem = manifest[manifestId];
         if (!manifestItem)
             throw new Error(`Manifest item not found with id "${manifestId}"`);
+        if ((await this.getSpine()).some(({ itemRef }) => itemRef === manifestId)) {
+            throw new Error(`Manifest item "${manifestId}" is already referenced in the spine`);
+        }
+        if (!spineReferenceable(manifest, manifestItem)) {
+            throw new Error(`Manifest item "${manifestId}" is not an EPUB content document, so it cannot be added to the spine`);
+        }
         await this.withPackage((packageElement) => {
-            const spine = Epub.findXmlChildByName("spine", Epub.getXmlChildren(packageElement));
+            const spine = findXmlChildByNameNS(NS.opf, "spine", packageElement);
             if (!spine)
                 throw new Error("Failed to parse EPUB: Found no spine element in package document");
-            if (index === undefined) {
-                Epub.getXmlChildren(spine).push(item);
-            }
-            else {
-                Epub.getXmlChildren(spine).splice(index, 0, item);
-            }
+            insert(spine, item, index === undefined
+                ? null
+                : (Array.from(spine.children)[index] ?? null));
         });
         // Reset the spine cache
         this.spine = null;
@@ -1897,41 +1618,42 @@ export class Epub {
      */
     async removeSpineItem(index) {
         await this.withPackage((packageElement) => {
-            const spine = Epub.findXmlChildByName("spine", Epub.getXmlChildren(packageElement));
+            const spine = findXmlChildByNameNS(NS.opf, "spine", packageElement);
             if (!spine)
                 throw new Error("Failed to parse EPUB: Found no spine element in package document");
-            Epub.getXmlChildren(spine).splice(index, 1);
+            const itemref = Array.from(spine.children)[index];
+            if (itemref)
+                spine.removeChild(itemref);
         });
         // Reset the spine cache
         this.spine = null;
     }
     async getNavigationChildren(ol, navHref, { resolveToRoot } = {}) {
         const children = [];
-        const childrenElements = Epub.getXmlChildren(ol).filter((node) => !Epub.isXmlTextNode(node) && Epub.getXmlElementName(node) === "li");
-        for (const childEl of childrenElements) {
-            const [firstChild, secondChild] = Epub.getXmlChildren(childEl).filter((node) => !Epub.isXmlTextNode(node) &&
-                ["a", "span", "ol"].includes(Epub.getXmlElementName(node)));
+        const listItems = Array.from(ol.children).filter((element) => element.nodeName === "li");
+        for (const childEl of listItems) {
+            const [firstChild, secondChild] = Array.from(childEl.children).filter((element) => ["a", "span", "ol"].includes(element.nodeName));
             if (!firstChild)
                 continue;
-            if (!["a", "span"].includes(Epub.getXmlElementName(firstChild))) {
+            const name = firstChild.nodeName;
+            if (name !== "a" && name !== "span")
                 continue;
-            }
-            if (Epub.getXmlElementName(firstChild) === "span" &&
-                (!secondChild || Epub.getXmlElementName(secondChild) !== "ol")) {
+            if (name === "span" && (!secondChild || secondChild.nodeName !== "ol")) {
                 continue;
             }
-            const role = firstChild[":@"]?.["@_epub:type"]?.trim();
+            const role = firstChild.getAttribute("epub:type")?.trim();
+            const href = firstChild.getAttribute("href");
             children.push({
-                title: Epub.getXhtmlTextContent(Epub.getXmlChildren(firstChild)),
-                ...(Epub.getXmlElementName(firstChild) === "a" &&
-                    firstChild[":@"]?.["@_href"] && {
-                    href: await this.resolveHref(firstChild[":@"]["@_href"], navHref, {
+                title: firstChild.textContent ?? "",
+                ...(name === "a" &&
+                    href && {
+                    href: await this.resolveHref(href, navHref, {
                         toRoot: resolveToRoot,
                     }),
                 }),
                 ...(role && { role }),
                 ...(secondChild &&
-                    Epub.getXmlElementName(secondChild) === "ol" && {
+                    secondChild.nodeName === "ol" && {
                     children: await this.getNavigationChildren(secondChild, navHref, {
                         resolveToRoot,
                     }),
@@ -1946,19 +1668,21 @@ export class Epub {
         if (!navItem)
             return null;
         const navContents = await this.readXhtmlItemContents(navItem.id);
-        const navEl = Epub.findXmlDescendantByName("nav", navContents, (node) => Epub.getXmlAttributes(node)["epub:type"] === role);
+        const html = navContents.documentElement;
+        if (!html)
+            return null;
+        const navEl = findXmlDescendantByName("nav", html, (node) => node.getAttribute("epub:type") === role);
         if (!navEl)
             return null;
-        const [firstChild, secondChild] = Epub.getXmlChildren(navEl).filter((node) => !!(!Epub.isXmlTextNode(node) &&
-            Epub.getXmlElementName(node).match(/(?:h[1-6]|ol)/)));
+        const [firstChild, secondChild] = Array.from(navEl.children).filter((element) => /h[1-6]|ol/.test(element.nodeName));
         if (!firstChild)
             return null;
-        const title = Epub.getXmlElementName(firstChild).match(/h[1-6]/)
-            ? Epub.getXhtmlTextContent(Epub.getXmlChildren(firstChild))
+        const title = /h[1-6]/.test(firstChild.nodeName)
+            ? (firstChild.textContent ?? "")
             : null;
-        const list = Epub.getXmlElementName(firstChild) === "ol"
+        const list = firstChild.nodeName === "ol"
             ? firstChild
-            : secondChild && Epub.getXmlElementName(secondChild) === "ol"
+            : secondChild && secondChild.nodeName === "ol"
                 ? secondChild
                 : null;
         if (!list)
@@ -2103,6 +1827,26 @@ export class Epub {
             : await this.adapter.read(entry);
         return itemEntry;
     }
+    /**
+     * Create a new XML document with the given root node.
+     *
+     * @param root The XML node to use as the document element
+     * @param language Optional - defaults to the EPUB's language
+     */
+    createXmlDocument(root) {
+        const document = createDocument(root.namespaceURI ?? root.getAttribute("xmlns"), root.nodeName, null);
+        const docRoot = document.documentElement;
+        if (!docRoot)
+            throw new Error("Failed to create XML document");
+        for (const attr of root.attributes) {
+            docRoot.setAttributeNode(attr.cloneNode());
+        }
+        for (const child of Array.from(root.childNodes)) {
+            insert(docRoot, child);
+        }
+        document.insertBefore(document.createProcessingInstruction("xml", 'version="1.0" encoding="UTF-8"'), docRoot);
+        return document;
+    }
     /**
      * Create a new XHTML document with the given body
      * and head.
@@ -2113,27 +1857,32 @@ export class Epub {
      */
     async createXhtmlDocument(body, head, language) {
         const lang = language ?? (await this.getLanguage());
-        return [
-            Epub.createXmlElement("?xml", { version: "1.0", encoding: "UTF-8" }, [
-                { "#text": "" },
-            ]),
-            Epub.createXmlElement("html", {
-                xmlns: "http://www.w3.org/1999/xhtml",
-                "xmlns:epub": "http://www.idpf.org/2007/ops",
-                ...(lang && { "xml:lang": lang.toString(), lang: lang.toString() }),
-            }, [
-                Epub.createXmlElement("head", {}, head),
-                Epub.createXmlElement("body", {}, body),
-            ]),
-        ];
+        const document = createDocument(NS.xhtml, "html", createDocumentType("html", "", ""));
+        const html = document.documentElement;
+        if (!html)
+            throw new Error("Failed to create XHTML document");
+        html.setAttributeNS(NS.xmlns, "xmlns:epub", NS.epub);
+        if (lang) {
+            html.setAttributeNS(NS.xml, "xml:lang", lang.toString());
+            html.setAttribute("lang", lang.toString());
+        }
+        const headElement = document.createElement("head");
+        for (const node of head ?? [])
+            insert(headElement, node);
+        insert(html, headElement);
+        const bodyElement = document.createElement("body");
+        for (const node of body)
+            insert(bodyElement, node);
+        insert(html, bodyElement);
+        document.insertBefore(document.createProcessingInstruction("xml", 'version="1.0" encoding="UTF-8"'), document.doctype);
+        return document;
     }
     async readXhtmlItemContents(id, as = "xhtml") {
         const contents = await this.readItemContents(id, "utf-8");
-        const xml = Epub.xhtmlParser.parse(contents);
+        const document = parse(contents, "application/xhtml+xml");
         if (as === "xhtml")
-            return xml;
-        const body = Epub.getXhtmlBody(xml);
-        return Epub.getXhtmlTextContent(body);
+            return document;
+        return getXhtmlBody(document).textContent ?? "";
     }
     async writeEntryContents(path, contents, encoding) {
         this.assertWritable();
@@ -2177,42 +1926,52 @@ export class Epub {
      * @link https://www.w3.org/TR/epub-33/#sec-xhtml
      */
     async writeXhtmlItemContents(id, contents) {
-        await this.writeItemContents(id, Epub.xhtmlBuilder.build(contents), "utf-8");
+        await this.writeItemContents(id, serialize(contents), "utf-8");
     }
     async removeManifestItem(id) {
         await this.withPackage(async (packageElement) => {
-            const manifest = Epub.findXmlChildByName("manifest", Epub.getXmlChildren(packageElement));
+            const manifest = findXmlChildByNameNS(NS.opf, "manifest", packageElement);
             if (!manifest)
                 throw new Error("Failed to parse EPUB: Found no manifest element in package document");
-            const itemIndex = Epub.getXmlChildren(manifest).findIndex((node) => !Epub.isXmlTextNode(node) && node[":@"]?.["@_id"] === id);
-            if (itemIndex === -1)
+            const item = Array.from(manifest.children).find((element) => element.getAttribute("id") === id);
+            if (!item)
                 return;
-            const [item] = Epub.getXmlChildren(manifest).splice(itemIndex, 1);
-            if (!item || Epub.isXmlTextNode(item) || !item[":@"]?.["@_href"])
+            const href = item.getAttribute("href");
+            manifest.removeChild(item);
+            const spine = findXmlChildByNameNS(NS.opf, "spine", packageElement);
+            if (spine) {
+                for (const itemref of Array.from(spine.children)) {
+                    if (itemref.getAttribute("idref") === id)
+                        spine.removeChild(itemref);
+                }
+            }
+            if (!href)
                 return;
-            await this.removeEntry(item[":@"]["@_href"]);
+            await this.removeEntry(href);
         });
-        // Reset the cached manifest, so that it will be read from
+        // Reset the cached manifest and spine, so that they will be read from
         // the updated XML next time
         this.manifest = null;
+        this.spine = null;
     }
     async addManifestItem(item, contents, encoding) {
+        const existingItems = Object.values(await this.getManifest());
+        if (existingItems.some((existing) => existing.id === item.id)) {
+            throw new Error(`Cannot add manifest item: an item with the id "${item.id}" already exists`);
+        }
+        // 4.2.1: hrefs that normalize and case-fold to the same path would
+        // overwrite each other on a normalizing filesystem.
+        const foldedHref = foldPathName(item.href);
+        for (const existing of existingItems) {
+            if (foldPathName(existing.href) === foldedHref) {
+                throw new Error(`Cannot add manifest item: "${item.href}" collides with the existing item "${existing.href}"`);
+            }
+        }
         await this.withPackage((packageElement) => {
-            const manifest = Epub.findXmlChildByName("manifest", Epub.getXmlChildren(packageElement));
+            const manifest = findXmlChildByNameNS(NS.opf, "manifest", packageElement);
             if (!manifest)
                 throw new Error("Failed to parse EPUB: Found no manifest element in package document");
-            // TODO: Should we ensure that there isn't already a manifest
-            // item with this id first?
-            Epub.getXmlChildren(manifest).push(Epub.createXmlElement("item", {
-                id: item.id,
-                href: item.href,
-                ...(item.mediaType && { "media-type": item.mediaType }),
-                ...(item.fallback && { fallback: item.fallback }),
-                ...(item.mediaOverlay && { "media-overlay": item.mediaOverlay }),
-                ...(item.properties && {
-                    properties: item.properties.join(" "),
-                }),
-            }));
+            insert(manifest, _jsx("item", { id: item.id, href: item.href, ...(item.mediaType && { "media-type": item.mediaType }), ...(item.fallback && { fallback: item.fallback }), ...(item.mediaOverlay && { "media-overlay": item.mediaOverlay }), ...(item.properties && { properties: item.properties.join(" ") }) }));
         });
         // Reset the cached manifest, so that it will be read from
         // the updated XML next time
@@ -2223,7 +1982,7 @@ export class Epub {
         const data = encoding === "utf-8" || encoding === "xml"
             ? new TextEncoder().encode(encoding === "utf-8"
                 ? contents
-                : Epub.xmlBuilder.build(contents))
+                : serialize(contents))
             : contents;
         /* oxlint-enable typescript/no-unnecessary-type-assertion */
         await this.writeEntryContents(filename, data);
@@ -2238,22 +1997,17 @@ export class Epub {
      */
     async updateManifestItem(id, newItem) {
         await this.withPackage((packageElement) => {
-            const manifest = Epub.findXmlChildByName("manifest", Epub.getXmlChildren(packageElement));
+            const manifest = findXmlChildByNameNS(NS.opf, "manifest", packageElement);
             if (!manifest)
                 throw new Error("Failed to parse EPUB: Found no manifest element in package document");
-            const itemIndex = manifest["manifest"].findIndex((item) => !Epub.isXmlTextNode(item) && item[":@"]?.["@_id"] === id);
-            Epub.getXmlChildren(manifest).splice(itemIndex, 1, Epub.createXmlElement("item", {
-                id: id,
-                href: newItem.href,
-                ...(newItem.mediaType && { "media-type": newItem.mediaType }),
-                ...(newItem.fallback && { fallback: newItem.fallback }),
-                ...(newItem.mediaOverlay && {
+            const existing = Array.from(manifest.children).find((element) => element.getAttribute("id") === id);
+            if (!existing)
+                return;
+            replace(manifest, _jsx("item", { id: id, href: newItem.href, ...(newItem.mediaType && { "media-type": newItem.mediaType }), ...(newItem.fallback && { fallback: newItem.fallback }), ...(newItem.mediaOverlay && {
                     "media-overlay": newItem.mediaOverlay,
-                }),
-                ...(newItem.properties && {
+                }), ...(newItem.properties && {
                     properties: newItem.properties.join(" "),
-                }),
-            }));
+                }) }), existing);
         });
         // Reset the cached manifest, so that it will be read from
         // the updated XML next time
@@ -2271,15 +2025,13 @@ export class Epub {
      */
     async addMetadata(entry) {
         await this.withPackage((packageElement) => {
-            const metadata = Epub.findXmlChildByName("metadata", Epub.getXmlChildren(packageElement));
+            const metadata = findXmlChildByNameNS(NS.opf, "metadata", packageElement);
             if (!metadata)
                 throw new Error("Failed to parse EPUB: found no metadata element in package document");
-            Epub.getXmlChildren(metadata).push(Epub.createXmlElement(entry.type, {
+            insert(metadata, x(entry.type, {
                 ...(entry.id && { id: entry.id }),
                 ...entry.properties,
-            }, entry.value !== undefined
-                ? [Epub.createXmlTextNode(entry.value)]
-                : []));
+            }, entry.value));
         });
     }
     /**
@@ -2297,19 +2049,22 @@ export class Epub {
      */
     async replaceMetadata(predicate, entry) {
         await this.withPackage((packageElement) => {
-            const metadataElement = Epub.findXmlChildByName("metadata", Epub.getXmlChildren(packageElement));
+            const metadataElement = findXmlChildByNameNS(NS.opf, "metadata", packageElement);
             if (!metadataElement)
                 throw new Error("Failed to parse EPUB: found no metadata element in package document");
             const oldEntryIndex = this.findMetadataIndex(packageElement, predicate);
-            const newElement = Epub.createXmlElement(entry.type, {
+            const newElement = x(entry.type, {
                 ...(entry.id && { id: entry.id }),
                 ...entry.properties,
-            }, entry.value !== undefined ? [Epub.createXmlTextNode(entry.value)] : []);
-            if (oldEntryIndex === -1) {
-                metadataElement.metadata.push(newElement);
+            }, entry.value);
+            const existing = oldEntryIndex === -1
+                ? null
+                : (Array.from(metadataElement.children)[oldEntryIndex] ?? null);
+            if (existing) {
+                replace(metadataElement, newElement, existing);
             }
             else {
-                metadataElement.metadata.splice(oldEntryIndex, 1, newElement);
+                insert(metadataElement, newElement);
             }
         });
     }
@@ -2327,19 +2082,14 @@ export class Epub {
      */
     async removeMetadata(predicate) {
         await this.withPackage((packageElement) => {
-            const metadataElement = Epub.findXmlChildByName("metadata", Epub.getXmlChildren(packageElement));
+            const metadataElement = findXmlChildByNameNS(NS.opf, "metadata", packageElement);
             if (!metadataElement) {
                 throw new Error("Failed to parse EPUB: found no metadata element in package document");
             }
-            const metadataEntries = Epub.getXmlChildren(metadataElement);
-            for (let i = metadataEntries.length - 1; i >= 0; i--) {
-                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-                const meta = metadataEntries[i];
+            for (const meta of Array.from(metadataElement.children)) {
                 const item = Epub.parseMetadataItem(meta);
-                if (!item)
-                    continue;
                 if (predicate(item)) {
-                    metadataEntries.splice(i, 1);
+                    metadataElement.removeChild(meta);
                 }
             }
         });
@@ -2349,7 +2099,7 @@ export class Epub {
      */
     async getVersion() {
         const packageElement = await this.getPackageElement();
-        return packageElement[":@"]?.["@_version"] ?? "2.0";
+        return packageElement.getAttribute("version") ?? "2.0";
     }
     /**
      * Parse the NCX table of contents, if one exists, and return
@@ -2364,49 +2114,42 @@ export class Epub {
             this.getManifest(),
             this.getPackageElement(),
         ]);
-        const spine = Epub.findXmlChildByName("spine", Epub.getXmlChildren(packageElement));
-        const spineTocId = spine?.[":@"]?.["@_toc"];
+        const spine = findXmlChildByNameNS(NS.opf, "spine", packageElement);
+        const spineTocId = spine?.getAttribute("toc");
         const ncxItem = spineTocId
             ? manifest[spineTocId]
             : Object.values(manifest).find((item) => MediaType.fromMime(item.mediaType ?? "") === MediaType.NCX);
         if (!ncxItem)
             return [];
         const ncxContent = await this.readItemContents(ncxItem.id, "utf-8");
-        const ncxXml = Epub.xmlParser.parse(ncxContent);
-        const ncxElement = Epub.findXmlChildByName("ncx", ncxXml);
-        if (!ncxElement)
+        const ncxElement = parse(ncxContent, "text/xml").documentElement;
+        if (!ncxElement || ncxElement.localName !== "ncx")
             return [];
-        const ncxChildren = Epub.getXmlChildren(ncxElement);
-        const navMap = Epub.findXmlChildByName("navMap", ncxChildren) ??
-            Epub.findXmlChildByName("navmap", ncxChildren);
+        const navMap = findXmlChildByName("navMap", ncxElement) ??
+            findXmlChildByName("navmap", ncxElement);
         if (!navMap)
             return [];
-        return this.parseNavPoints(Epub.getXmlChildren(navMap), ncxItem.href);
+        return this.parseNavPoints(navMap, ncxItem.href);
     }
-    async parseNavPoints(nodes, ncxHref) {
+    async parseNavPoints(parent, ncxHref) {
         const entries = [];
-        for (const node of nodes) {
-            if (Epub.isXmlTextNode(node))
-                continue;
-            const name = Epub.getXmlElementName(node);
-            const isNavPoint = name === "navPoint" || name === "navpoint";
-            if (!isNavPoint)
+        for (const node of Array.from(parent.children)) {
+            if (node.nodeName !== "navPoint" && node.nodeName !== "navpoint") {
                 continue;
-            const children = Epub.getXmlChildren(node);
-            const navLabel = Epub.findXmlChildByName("navLabel", children) ??
-                Epub.findXmlChildByName("navlabel", children);
+            }
+            const navLabel = findXmlChildByName("navLabel", node) ??
+                findXmlChildByName("navlabel", node);
             let title = null;
             if (navLabel) {
-                const textEl = Epub.findXmlChildByName("text", Epub.getXmlChildren(navLabel));
+                const textEl = findXmlChildByName("text", navLabel);
                 if (textEl) {
-                    title =
-                        Epub.getXhtmlTextContent(Epub.getXmlChildren(textEl)).trim() || null;
+                    title = textEl.textContent?.trim() || null;
                 }
             }
-            const contentEl = Epub.findXmlChildByName("content", children);
-            const src = contentEl?.[":@"]?.["@_src"];
+            const contentEl = findXmlChildByName("content", node);
+            const src = contentEl?.getAttribute("src");
             const href = src ? await this.resolveHref(src, ncxHref) : null;
-            const childEntries = await this.parseNavPoints(children, ncxHref);
+            const childEntries = await this.parseNavPoints(node, ncxHref);
             entries.push({
                 title: title ?? `${entries.length}`,
                 ...(href && { href }),
@@ -2423,15 +2166,15 @@ export class Epub {
      */
     async getGuideEntries() {
         const packageElement = await this.getPackageElement();
-        const guide = Epub.findXmlChildByName("guide", Epub.getXmlChildren(packageElement));
+        const guide = findXmlChildByNameNS(NS.opf, "guide", packageElement);
         if (!guide)
             return [];
-        return Epub.getXmlChildren(guide)
-            .filter((node) => !Epub.isXmlTextNode(node) && "reference" in node)
-            .map((ref) => ({
-            href: ref[":@"]?.["@_href"] ?? "",
-            title: ref[":@"]?.["@_title"] ?? "",
-            type: (ref[":@"]?.["@_type"] ?? "").toLowerCase(),
+        return Array.from(guide.children)
+            .filter((reference) => reference.nodeName === "reference")
+            .map((reference) => ({
+            href: reference.getAttribute("href") ?? "",
+            title: reference.getAttribute("title") ?? "",
+            type: (reference.getAttribute("type") ?? "").toLowerCase(),
         }))
             .filter((entry) => entry.href);
     }
@@ -2542,27 +2285,14 @@ export class EpubFactory {
             // unreachable: a writable adapter must implement write
             throw new Error(`adapter ${this.adapterClass.kind} declared writable but did not implement write()`);
         }
-        const encoder = new TextEncoder();
-        const container = encoder.encode(`<?xml version="1.0"?>
-<container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
-  <rootfiles>
-    <rootfile media-type="${MediaType.OPF.mime}" full-path="OEBPS/content.opf"/>
-  </rootfiles>
-</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>
-  </metadata>
-  <manifest>
-  </manifest>
-  <spine>
-  </spine>
-</package>
-`);
-        await adapter.write("OEBPS/content.opf", packageDocument);
+        const textInfo = typeof language.getTextInfo === "function"
+            ? language.getTextInfo()
+            : language.textInfo;
         const epub = new Epub(this.adapterClass, adapter, path);
+        const container = epub.createXmlDocument(_jsx("container", { version: "1.0", xmlns: "urn:oasis:names:tc:opendocument:xmlns:container", children: _jsx("rootfiles", { children: _jsx("rootfile", { "media-type": MediaType.OPF.mime, "full-path": "OEBPS/content.opf" }) }) }));
+        await adapter.write("META-INF/container.xml", serialize(container), "utf-8");
+        const packageDocument = epub.createXmlDocument(_jsxs("package", { xmlns: NS.opf, "unique-identifier": "pub-id", dir: textInfo?.direction ?? "ltr", "xml:lang": language.toString(), version: "3.0", "xmlns:dc": "http://purl.org/dc/elements/1.1/", children: [_jsx("metadata", {}), _jsx("manifest", {}), _jsx("spine", {})] }));
+        await adapter.write("OEBPS/content.opf", serialize(packageDocument), "utf-8");
         const metadata = [
             {
                 id: "pub-id",
@@ -2586,7 +2316,7 @@ export class EpubFactory {
             await Promise.all(creators.map((creator) => epub.addCreator(creator)));
         }
         if (contributors) {
-            await Promise.all(contributors.map((contributor) => epub.addCreator(contributor)));
+            await Promise.all(contributors.map((contributor) => epub.addContributor(contributor)));
         }
         return epub; // oxlint-disable-line typescript/no-unnecessary-type-assertion
     }
@@ -2614,10 +2344,8 @@ export class EpubFactory {
             throw new EpubReadOnlyError(`adapter ${this.adapterClass.kind} is read-only; cannot upgrade`);
         }
         const { removeNcx = false, outputPath } = options;
-        if (outputPath) {
-            await mkdir(dirname(outputPath), { recursive: true });
-            await cp(path, outputPath, { force: true });
-        }
+        if (outputPath)
+            await copyFile(path, outputPath);
         const source = outputPath ?? path;
         const adapter = await this.adapterClass.init(source, // oxlint-disable-line typescript/no-unnecessary-type-assertion
         options);
@@ -2662,14 +2390,14 @@ export class EpubFactory {
                 mediaType: MediaType.XHTML.mime,
                 properties: ["nav"],
             }, navContent, "utf-8");
-            // go over each xhtml item and replace the outdated
-            // <!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.1//EN' 'http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd'>
-            // with <!DOCTYPE html>
+            // XHTML 1.x doctypes are not valid HTML5, so rewrite them to
+            // <!DOCTYPE html> as part of the upgrade.
             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);
+                Upgrade.normalizeDoctype(contents);
                 await epub.writeXhtmlItemContents(item.id, contents);
             }
             // oxlint-disable-next-line typescript/no-unnecessary-type-assertion -- tsgolint treats the cast as unnecessary but it still narrows the type