@storyteller-platform/epub 0.8.1 → 1.0.0

package/dist/adapters/interface.d.ts

@@ -8,6 +8,25 @@
  *    reads only
  */
 export type EpubStorageKind = "tmp-dir" | "in-memory" | (string & {});
+export type ArchiveSource = string | Uint8Array | Blob;
+/**
+ * A file in an opened zip archive. Directory entries are left out.
+ */
+export interface ZipEntry {
+    readonly filename: string;
+    readonly compressedSize: number;
+    readonly uncompressedSize: number;
+    /** rejects when the data doesn't match the CRC32 or size in the central directory */
+    read(): Promise<Uint8Array>;
+}
+/**
+ * An opened zip archive. The `#zip` import picks the reader:
+ * yauzl-promise in Node, zip.js everywhere else.
+ */
+export interface ZipArchive {
+    readonly entries: readonly ZipEntry[];
+    close(): Promise<void>;
+}
 export interface EpubStorageCapabilities {
     /** when false, the Epub class refuses every mutation method at runtime */
     readonly writable: boolean;
@@ -63,7 +82,7 @@ export interface EpubStorageAdapterClass<Opts extends object = object> {
      * Open an archive from a path or buffer.
      * Will throw if the archive is not a valid EPUB 3
      */
-    init(source: string | Uint8Array, opts?: Opts): Promise<EpubStorageAdapter>;
+    init(source: ArchiveSource, opts?: Opts): Promise<EpubStorageAdapter>;
     /**
      * Initialize an empty extract root for {@link Epub.create}.
      * Only necessary for adapters that can write

package/dist/adapters/memory.d.ts

@@ -1,4 +1,4 @@
-import type { EpubStorageAdapter } from "./interface.ts";
+import type { ArchiveSource, EpubStorageAdapter } from "./interface.ts";
 export interface MemoryAdapterOptions {
     /**
      * per-entry decompressed buffer cache
@@ -23,7 +23,7 @@ export declare class MemoryAdapter implements EpubStorageAdapter {
     static readonly capabilities: {
         readonly writable: false;
     };
-    static init(source: string | Uint8Array, opts?: MemoryAdapterOptions): Promise<MemoryAdapter>;
+    static init(source: ArchiveSource, opts?: MemoryAdapterOptions): Promise<MemoryAdapter>;
     private constructor();
     read(entry: string): Promise<Uint8Array>;
     read(entry: string, encoding: "utf-8"): Promise<string>;

package/dist/adapters/memory.js

@@ -1,4 +1,5 @@
-import { openZip } from "../zip.js";
+import { openZip } from "#zip";
+const utf8 = new TextDecoder("utf-8", { ignoreBOM: true });
 /**
  * Loads an EPUB archive into memory and serves all I/O off the in-memory zip handle.
  *
@@ -15,20 +16,11 @@ export class MemoryAdapter {
         const { cache = true, signal } = opts;
         signal?.throwIfAborted();
         const zip = await openZip(source);
-        const entries = new Map();
-        try {
-            for await (const entry of zip) {
-                signal?.throwIfAborted();
-                if (entry.filename.endsWith("/"))
-                    continue;
-                entries.set(entry.filename, entry);
-            }
-        }
-        catch (error) {
+        if (signal?.aborted) {
             await zip.close();
-            throw error;
+            signal.throwIfAborted();
         }
-        return new MemoryAdapter(zip, entries, cache ? new Map() : null);
+        return new MemoryAdapter(zip, new Map(zip.entries.map((entry) => [entry.filename, entry])), cache ? new Map() : null);
     }
     constructor(zip, entries, cache) {
         this.zip = zip;
@@ -36,24 +28,18 @@ export class MemoryAdapter {
         this.cache = cache;
     }
     async read(entry, encoding) {
-        const cached = this.cache?.get(entry);
-        if (cached) {
-            return encoding ? cached.toString(encoding) : new Uint8Array(cached);
-        }
-        const zipEntry = this.entries.get(entry);
-        if (!zipEntry) {
-            const err = new Error(`ENOENT: zip entry not found in EPUB archive: ${entry}`);
-            err.code = "ENOENT";
-            throw err;
-        }
-        const stream = await zipEntry.openReadStream();
-        const chunks = [];
-        for await (const chunk of stream) {
-            chunks.push(chunk);
+        let data = this.cache?.get(entry);
+        if (!data) {
+            const zipEntry = this.entries.get(entry);
+            if (!zipEntry) {
+                const err = new Error(`ENOENT: zip entry not found in EPUB archive: ${entry}`);
+                err.code = "ENOENT";
+                throw err;
+            }
+            data = await zipEntry.read();
+            this.cache?.set(entry, data);
         }
-        const buf = Buffer.concat(chunks);
-        this.cache?.set(entry, buf);
-        return encoding ? buf.toString(encoding) : new Uint8Array(buf);
+        return encoding ? utf8.decode(data) : new Uint8Array(data);
     }
     // eslint-disable-next-line @typescript-eslint/require-await
     async exists(entry) {

package/dist/adapters/tmpfs.browser.d.ts

@@ -0,0 +1,11 @@
+import type { EpubStorageAdapter } from "./interface.ts";
+declare function unavailable(): Promise<EpubStorageAdapter>;
+export declare const TmpFsAdapter: {
+    readonly kind: "extracted-dir";
+    readonly capabilities: {
+        readonly writable: true;
+    };
+    readonly init: typeof unavailable;
+    readonly initEmpty: typeof unavailable;
+};
+export {};

package/dist/adapters/tmpfs.browser.js

@@ -0,0 +1,9 @@
+function unavailable() {
+    return Promise.reject(new Error("TmpFsAdapter extracts EPUBs to a temp directory and only works in Node.js. Use Epub.using(MemoryAdapter) instead."));
+}
+export const TmpFsAdapter = {
+    kind: "extracted-dir",
+    capabilities: { writable: true },
+    init: unavailable,
+    initEmpty: unavailable,
+};

package/dist/adapters/tmpfs.d.ts

@@ -1,4 +1,4 @@
-import type { EpubListEntry, EpubStorageAdapter } from "./interface.ts";
+import type { ArchiveSource, EpubListEntry, EpubStorageAdapter } from "./interface.ts";
 /**
  * Extracts an EPUB archive to a temp directory and serves all I/O off
  * the real filesystem.
@@ -10,7 +10,7 @@ export declare class TmpFsAdapter implements EpubStorageAdapter {
     static readonly capabilities: {
         readonly writable: true;
     };
-    static init(source: string | Uint8Array): Promise<TmpFsAdapter>;
+    static init(source: ArchiveSource): Promise<TmpFsAdapter>;
     static initEmpty(): Promise<TmpFsAdapter>;
     private constructor();
     private diskPath;

package/dist/adapters/tmpfs.js

@@ -58,7 +58,7 @@ import { ZipFile } from "yazl";
 import { scratchPath } from "@storyteller-platform/fs";
 import { MediaType } from "@storyteller-platform/media-types";
 import { dirname, join, sep } from "@storyteller-platform/path";
-import { openZip } from "../zip.js";
+import { openZip } from "../zip.node.js";
 const PRECOMPRESSED_KINDS = new Set([
     "audio",
     "image",
@@ -90,44 +90,31 @@ export class TmpFsAdapter {
     static kind = "extracted-dir";
     static capabilities = { writable: true };
     static async init(source) {
-        const rootPath = mintRootPath();
+        const env_1 = { stack: [], error: void 0, hasError: false };
         try {
-            const env_1 = { stack: [], error: void 0, hasError: false };
-            try {
-                const zipfile = await openZip(source);
-                const stack = __addDisposableResource(env_1, new AsyncDisposableStack(), true);
-                stack.defer(async () => {
-                    await zipfile.close();
-                });
-                for await (const entry of zipfile) {
-                    if (entry.filename.endsWith("/")) {
-                        // directory entries are skipped; parent dirs are created implicitly
-                        continue;
-                    }
-                    if (!isStorableEntryName(entry.filename))
-                        continue;
-                    const writePath = join(rootPath, ...entry.filename.split("/"));
-                    const readStream = await entry.openReadStream();
-                    await mkdir(dirname(writePath), { recursive: true });
-                    const writeStream = createWriteStream(writePath);
-                    await pipeline(readStream, writeStream);
-                }
-            }
-            catch (e_1) {
-                env_1.error = e_1;
-                env_1.hasError = true;
-            }
-            finally {
-                const result_1 = __disposeResources(env_1);
-                if (result_1)
-                    await result_1;
+            const cleanup = __addDisposableResource(env_1, new AsyncDisposableStack(), true);
+            const rootPath = mintRootPath();
+            cleanup.defer(() => rm(rootPath, { force: true, recursive: true }));
+            const zip = __addDisposableResource(env_1, await openZip(source), true);
+            for (const entry of zip.entries) {
+                if (!isStorableEntryName(entry.filename))
+                    continue;
+                const writePath = join(rootPath, ...entry.filename.split("/"));
+                await mkdir(dirname(writePath), { recursive: true });
+                await pipeline(await entry.openReadStream(), createWriteStream(writePath));
             }
+            cleanup.move();
+            return new TmpFsAdapter(rootPath);
         }
-        catch (error) {
-            rmSync(rootPath, { force: true, recursive: true });
-            throw error;
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            const result_1 = __disposeResources(env_1);
+            if (result_1)
+                await result_1;
         }
-        return new TmpFsAdapter(rootPath);
     }
     static async initEmpty() {
         const rootPath = mintRootPath();

package/dist/files.browser.d.ts

@@ -0,0 +1,2 @@
+export declare function openFile(path: string): Promise<Blob>;
+export declare function copyFile(from: string, to: string): Promise<void>;

package/dist/files.browser.js

@@ -0,0 +1,7 @@
+const PATHS_NEED_NODE = "File paths only work in Node.js. Pass the EPUB as a Blob, File or Uint8Array instead.";
+export function openFile(path) {
+    return Promise.reject(new Error(`Cannot open "${path}". ${PATHS_NEED_NODE}`));
+}
+export function copyFile(from, to) {
+    return Promise.reject(new Error(`Cannot copy "${from}" to "${to}". ${PATHS_NEED_NODE}`));
+}

package/dist/files.node.d.ts

@@ -0,0 +1,2 @@
+export declare function openFile(path: string): Promise<Blob>;
+export declare function copyFile(from: string, to: string): Promise<void>;

package/dist/files.node.js

@@ -0,0 +1,10 @@
+import { openAsBlob } from "node:fs";
+import { cp, mkdir } from "node:fs/promises";
+import { dirname } from "@storyteller-platform/path";
+export async function openFile(path) {
+    return await openAsBlob(path);
+}
+export async function copyFile(from, to) {
+    await mkdir(dirname(to), { recursive: true });
+    await cp(from, to, { force: true });
+}

package/dist/index.d.ts

@@ -1,41 +1,33 @@
-import { XMLParser } from "fast-xml-parser";
-import type { AdapterOptions, EpubStorageAdapter, EpubStorageAdapterClass, EpubStorageKind } from "./adapters/interface.ts";
-import * as Upgrade from "./upgrade.ts";
-export type { EpubStorageKind } from "./adapters/interface.ts";
-export { type AdapterOptions, type EpubListEntry, type EpubStorageAdapter, type EpubStorageAdapterClass, type EpubStorageCapabilities, } from "./adapters/interface.ts";
+/** @jsxImportSource @storyteller-platform/epub */
+import type { Document, Element, Node } from "@xmldom/xmldom";
+import type { AdapterOptions, ArchiveSource, EpubStorageAdapter, EpubStorageAdapterClass, EpubStorageKind } from "./adapters/interface.ts";
+import * as Upgrade from "./upgrade.tsx";
+export { TmpFsAdapter } from "#tmpfs";
+export type { AdapterOptions, ArchiveSource, EpubListEntry, EpubStorageAdapter, EpubStorageAdapterClass, EpubStorageCapabilities, EpubStorageKind, } from "./adapters/interface.ts";
 export { MemoryAdapter, type MemoryAdapterOptions } from "./adapters/memory.ts";
-export { TmpFsAdapter } from "./adapters/tmpfs.ts";
+/**
+ * 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.ts";
+export type { XmlDiagnostic } from "./xml.ts";
+export type { Attr, Document, DocumentType, Element, Node, Text, } from "@xmldom/xmldom";
 declare global {
     namespace Intl {
         interface Locale {
-            textInfo: {
+            textInfo?: {
                 direction: "rtl" | "ltr";
             };
         }
     }
 }
-type Letter = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z";
-type QuestionMark = "?";
-/** A valid name for an XML element (must start with a letter) */
-export type ElementName = `${Letter | Uppercase<Letter> | QuestionMark}${string}`;
-type PropertyPrefix = "@_";
-/** An XML element */
-export type XmlElement<Name extends ElementName = ElementName> = {
-    ":@"?: Record<`${PropertyPrefix}${string}`, string>;
-} & {
-    [key in Name]: ParsedXml;
-};
-/** A text node in an XML document */
-export type XmlTextNode = {
-    "#text": string;
-};
-/** A valid XML node. May be either an element or a text node. */
-export type XmlNode = XmlElement | XmlTextNode;
-/** An XML structure */
-export type ParsedXml = Array<XmlNode>;
 export type ManifestItem = {
     id: string;
     href: string;
+    title?: string | undefined;
     mediaType?: string | undefined;
     fallback?: string | undefined;
     mediaOverlay?: string | undefined;
@@ -43,7 +35,7 @@ export type ManifestItem = {
 };
 export type MetadataEntry = {
     id?: string | undefined;
-    type: ElementName;
+    type: string;
     properties: Record<string, string>;
     value: string | undefined;
 };
@@ -116,12 +108,11 @@ export interface Navigation {
     role: string;
     children: NavigationList;
 }
-interface GuideItem {
+export interface GuideItem {
     href: string;
     title: string;
     type: string;
 }
-export type PackageElement = XmlElement<"package">;
 export interface FromOptions {
     /**
      * when true, mutation methods throw {@link EpubReadOnlyError} at runtime
@@ -162,7 +153,7 @@ export declare class EpubReadOnlyError extends Error {
  * 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);
@@ -177,10 +168,6 @@ export declare class Epub {
     protected adapter: EpubStorageAdapter;
     protected inputPath: string | undefined;
     protected readonlyOverride: boolean;
-    static xmlParser: XMLParser;
-    static xhtmlParser: XMLParser;
-    static xmlBuilder: import("fast-xml-builder").XMLBuilder;
-    static xhtmlBuilder: import("fast-xml-builder").XMLBuilder;
     /**
      * Format a duration, provided as a number of seconds, as
      * a SMIL clock value, to be used for Media Overlays.
@@ -188,62 +175,6 @@ export declare class Epub {
      * @link https://www.w3.org/TR/epub-33/#sec-duration
      */
     static formatSmilDuration(duration: number): string;
-    /**
-     * 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: ParsedXml, link: {
-        rel: string;
-        href: string;
-        type: string;
-    }): void;
-    /**
-     * 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: ParsedXml): ParsedXml;
-    static createXmlElement<Name extends ElementName>(name: Name, properties: Record<string, string>, children?: XmlNode[]): XmlElement<Name>;
-    static createXmlTextNode(text: string): XmlTextNode;
-    /**
-     * 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: ParsedXml): string;
-    /**
-     * Given an XMLElement, return its attributes.
-     */
-    static getXmlAttributes(element: XmlElement): Record<string, string>;
-    /**
-     * Given an XMLElement, return its tag name.
-     */
-    static getXmlElementName<Name extends ElementName>(element: XmlElement<Name>): Name;
-    /**
-     * Given an XMLElement, return a list of its children
-     */
-    static getXmlChildren<Name extends ElementName>(element: XmlElement<Name>): ParsedXml;
-    static replaceXmlChildren<Name extends ElementName>(element: XmlElement<Name>, children: XmlNode[]): void;
-    /**
-     * Given an XML structure, find the first child matching
-     * the provided name and optional filter.
-     */
-    static findXmlChildByName<Name extends ElementName>(name: Name, xml: ParsedXml, filter?: (node: XmlElement<Name>) => boolean): XmlElement<Name> | undefined;
-    /**
-     * 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 extends ElementName>(name: Name, xml: ParsedXml, filter?: (node: XmlElement<Name>) => boolean): XmlElement<Name> | undefined;
-    /**
-     * Given an XMLNode, determine whether it represents
-     * a text node or an XML element.
-     */
-    static isXmlTextNode(node: XmlNode): node is XmlTextNode;
     private rootfile;
     private manifest;
     private spine;
@@ -299,11 +230,11 @@ export declare class Epub {
      *   `Epub.using(MemoryAdapter).from(path)` for read-only, in-memory access)
      * @throws {EpubVersionError} when the archive is not a valid EPUB 3
      */
-    static from(pathOrData: string | Uint8Array): Promise<Epub>;
-    static from(pathOrData: string | Uint8Array, options: FromOptions & {
+    static from(pathOrData: ArchiveSource): Promise<Epub>;
+    static from(pathOrData: ArchiveSource, options: FromOptions & {
         readonly: true;
     }): Promise<EpubReader>;
-    static from(pathOrData: string | Uint8Array, options?: FromOptions): Promise<Epub | EpubReader>;
+    static from(pathOrData: ArchiveSource, options?: FromOptions): Promise<Epub | EpubReader>;
     static assertEpub3(epub: Epub): Promise<void>;
     copy(path?: string): Promise<Epub>;
     private removeEntry;
@@ -314,8 +245,9 @@ export declare class Epub {
      */
     getItemArchiveLength(id: string): Promise<number>;
     getRootfile(): Promise<string>;
+    getPackageDocumentSource(): Promise<string>;
     private getPackageDocument;
-    getPackageElement(): Promise<XmlElement<"package">>;
+    getPackageElement(): Promise<Element>;
     /**
      * Safely modify the package document, without race conditions.
      *
@@ -328,7 +260,7 @@ export declare class Epub {
      *    it returns a new package document, that will be persisted, otherwise
      *    it will be assumed that the package document was modified in place.
      */
-    withPackage(producer: ((packageElement: PackageElement) => void) | ((packageElement: PackageElement) => PackageElement) | ((packageElement: PackageElement) => Promise<PackageElement>) | ((packageElement: PackageElement) => Promise<void>)): Promise<void>;
+    withPackage(producer: ((packageElement: Element) => void) | ((packageElement: Element) => Element) | ((packageElement: Element) => Promise<Element>) | ((packageElement: Element) => Promise<void>)): Promise<void>;
     /**
      * Retrieve the manifest for the Epub.
      *
@@ -353,26 +285,12 @@ export declare class Epub {
      * Returns the item in the metadata element's children array
      * that matches the provided predicate.
      */
-    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}`;
-        properties: {
-            [k: string]: string;
-        };
-        value: string | undefined;
-    } | null>;
+    findMetadataItem(predicate: (entry: MetadataEntry) => boolean): Promise<MetadataEntry | null>;
     /**
      * Returns the item in the metadata element's children array
      * that matches the provided predicate.
      */
-    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}`;
-        properties: {
-            [k: string]: string;
-        };
-        value: string | undefined;
-    }[]>;
+    findAllMetadataItems(predicate: (entry: MetadataEntry) => boolean): Promise<MetadataEntry[]>;
     private static parseMetadataItem;
     /**
      * Retrieve the metadata entries for the Epub.
@@ -511,7 +429,7 @@ export declare 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.
      */
     private static removeRefiningMetas;
     /**
@@ -836,7 +754,9 @@ export declare class Epub {
      *
      * @link https://www.w3.org/TR/epub-33/#sec-spine-elem
      */
-    getSpineItems(): Promise<ManifestItem[]>;
+    getSpineItems(): Promise<(ManifestItem & {
+        linear: boolean;
+    })[]>;
     /**
      * Add an item to the spine of the EPUB.
      *
@@ -945,6 +865,13 @@ export declare class Epub {
      */
     readItemContents(id: string): Promise<Uint8Array>;
     readItemContents(id: string, encoding: "utf-8"): Promise<string>;
+    /**
+     * 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: Element): Document;
     /**
      * Create a new XHTML document with the given body
      * and head.
@@ -953,7 +880,7 @@ export declare class Epub {
      * @param head Optional - the XMl nodes to place in the head
      * @param language Optional - defaults to the EPUB's language
      */
-    createXhtmlDocument(body: ParsedXml, head?: ParsedXml, language?: Intl.Locale): Promise<(XmlElement<"?xml"> | XmlElement<"html">)[]>;
+    createXhtmlDocument(body: Node[], head?: Node[], language?: Intl.Locale): Promise<Document>;
     /**
      * Retrieves the contents of an XHTML item, given its manifest id.
      *
@@ -963,7 +890,7 @@ export declare class Epub {
      *
      * @link https://www.w3.org/TR/epub-33/#sec-xhtml
      */
-    readXhtmlItemContents(id: string, as?: "xhtml"): Promise<ParsedXml>;
+    readXhtmlItemContents(id: string, as?: "xhtml"): Promise<Document>;
     readXhtmlItemContents(id: string, as: "text"): Promise<string>;
     private writeEntryContents;
     /**
@@ -996,7 +923,7 @@ export declare class Epub {
      *
      * @link https://www.w3.org/TR/epub-33/#sec-xhtml
      */
-    writeXhtmlItemContents(id: string, contents: ParsedXml): Promise<void>;
+    writeXhtmlItemContents(id: string, contents: Document): Promise<void>;
     removeManifestItem(id: string): Promise<void>;
     /**
      * Create a new manifest item and write its contents to a
@@ -1011,7 +938,7 @@ export declare class Epub {
      * @link https://www.w3.org/TR/epub-33/#sec-pkg-manifest
      * @link https://www.w3.org/TR/epub-33/#sec-contentdocs
      */
-    addManifestItem(item: ManifestItem, contents: ParsedXml, encoding: "xml"): Promise<void>;
+    addManifestItem(item: ManifestItem, contents: Document, encoding: "xml"): Promise<void>;
     addManifestItem(item: ManifestItem, contents: string, encoding: "utf-8"): Promise<void>;
     addManifestItem(item: ManifestItem, contents: Uint8Array): Promise<void>;
     /**
@@ -1123,14 +1050,15 @@ export declare class EpubFactory<A extends EpubStorageAdapterClass> {
      *
      * @throws {EpubVersionError} when the archive is not a valid EPUB 3
      */
-    from(source: string | Uint8Array, options: FromOptions & {
+    from(source: ArchiveSource, options: FromOptions & {
         readonly: true;
     } & AdapterOptions<A>): Promise<EpubReader & {
         storage: A["kind"];
     }>;
-    from(source: string | Uint8Array, options?: FromOptions & AdapterOptions<A>): Promise<EpubInstanceFor<A> & {
+    from(source: ArchiveSource, options?: FromOptions & AdapterOptions<A>): Promise<EpubInstanceFor<A> & {
         storage: A["kind"];
     }>;
+    readPackageDocumentSource(source: ArchiveSource, options?: AdapterOptions<A>): Promise<string>;
     /**
      * Construct a new EPUB on this factory's adapter, optionally seeded
      * with the provided metadata. Requires a writable adapter that
@@ -1160,4 +1088,4 @@ export declare class EpubFactory<A extends EpubStorageAdapterClass> {
      */
     upgrade(path: string, options?: Upgrade.Epub2UpgradeOptions): Promise<EpubInstanceFor<A>>;
 }
-export type { Epub2UpgradeOptions, Landmark } from "./upgrade.ts";
+export type { Epub2UpgradeOptions, Landmark } from "./upgrade.tsx";