npm - @storyteller-platform/epub - Versions diffs - 0.5.0 → 0.6.0 - Mend

@storyteller-platform/epub 0.5.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (20) hide show

package/README.md +1491 -284
package/dist/adapters/interface.cjs +16 -0
package/dist/adapters/interface.d.cts +69 -0
package/dist/adapters/interface.d.ts +69 -0
package/dist/adapters/interface.js +0 -0
package/dist/adapters/memory.cjs +103 -0
package/dist/adapters/memory.d.cts +37 -0
package/dist/adapters/memory.d.ts +37 -0
package/dist/adapters/memory.js +83 -0
package/dist/adapters/tmpfs.cjs +235 -0
package/dist/adapters/tmpfs.d.cts +29 -0
package/dist/adapters/tmpfs.d.ts +29 -0
package/dist/adapters/tmpfs.js +178 -0
package/dist/index.cjs +289 -280
package/dist/index.d.cts +4 -1
package/dist/index.d.ts +4 -1
package/dist/index.js +292 -240
package/dist/upgrade.d.cts +142 -19
package/dist/upgrade.d.ts +142 -19
package/package.json +3 -2

package/README.md CHANGED Viewed

@@ -220,7 +220,7 @@ To get started with developing in the Storyteller monorepo, check out the
 ## Epub
 Defined in:
-[epub/index.ts:229](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L229)
+[epub/index.ts:267](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L267)
 A single EPUB instance.
@@ -259,17 +259,25 @@ https://www.w3.org/TR/epub-33/
 #### Constructor
-> `protected` **new Epub**(`extractPath`, `inputPath`): [`Epub`](#epub)
+> **new Epub**(`adapterClass`, `adapter`, `inputPath`, `readonlyOverride`):
+> [`Epub`](#epub)
 Defined in:
-[epub/index.ts:480](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L480)
+[epub/index.ts:533](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L533)
+Prefer the static factories ([Epub.using](#using), [Epub.from](#from),
+[Epub.create](#create), [Epub.upgrade](#upgrade)) over calling this constructor
+directly. It's public so [EpubFactory](#epubfactory) can construct instances;
+nothing else should need to.
 ##### Parameters
-| Parameter     | Type                    |
-| ------------- | ----------------------- |
-| `extractPath` | `string`                |
-| `inputPath`   | `undefined` \| `string` |
+| Parameter          | Type                                                  | Default value |
+| ------------------ | ----------------------------------------------------- | ------------- |
+| `adapterClass`     | [`EpubStorageAdapterClass`](#epubstorageadapterclass) | `undefined`   |
+| `adapter`          | [`EpubStorageAdapter`](#epubstorageadapter)           | `undefined`   |
+| `inputPath`        | `undefined` \| `string`                               | `undefined`   |
+| `readonlyOverride` | `boolean`                                             | `false`       |
 ##### Returns
@@ -277,47 +285,75 @@ Defined in:
 ### Properties
-#### extractPath
+#### adapter
+> `protected` **adapter**: [`EpubStorageAdapter`](#epubstorageadapter)
+Defined in:
+[epub/index.ts:535](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L535)
+#### adapterClass
-> `protected` **extractPath**: `string`
+> `protected` **adapterClass**:
+> [`EpubStorageAdapterClass`](#epubstorageadapterclass)
 Defined in:
-[epub/index.ts:481](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L481)
+[epub/index.ts:534](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L534)
 #### inputPath
 > `protected` **inputPath**: `undefined` \| `string`
 Defined in:
-[epub/index.ts:482](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L482)
+[epub/index.ts:536](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L536)
+#### readonlyOverride
+> `protected` **readonlyOverride**: `boolean` = `false`
+Defined in:
+[epub/index.ts:537](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L537)
+#### storage
+> `readonly` **storage**: [`EpubStorageKind`](#epubstoragekind)
+Defined in:
+[epub/index.ts:525](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L525)
+Storage backend kind in use for this instance
+Public so callers can declare type-level requirements via
+[InMemoryEpubReader](#inmemoryepubreader) Orthogonal to the read-only / writable
+axis (controlled by `readonlyOverride` and the adapter's capability bag)
 #### xhtmlBuilder
 > `static` **xhtmlBuilder**: `XMLBuilder`
 Defined in:
-[epub/index.ts:277](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L277)
+[epub/index.ts:315](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L315)
 #### xhtmlParser
 > `static` **xhtmlParser**: `XMLParser`
 Defined in:
-[epub/index.ts:237](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L237)
+[epub/index.ts:275](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L275)
 #### xmlBuilder
 > `static` **xmlBuilder**: `XMLBuilder`
 Defined in:
-[epub/index.ts:270](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L270)
+[epub/index.ts:308](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L308)
 #### xmlParser
 > `static` **xmlParser**: `XMLParser`
 Defined in:
-[epub/index.ts:230](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L230)
+[epub/index.ts:268](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L268)
 ### Methods
@@ -326,7 +362,7 @@ Defined in:
 > **\[dispose\]**(): `void`
 Defined in:
-[epub/index.ts:3098](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L3098)
+[epub/index.ts:2995](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2995)
 ##### Returns
@@ -337,7 +373,7 @@ Defined in:
 > **addCollection**(`collection`, `index?`): `Promise`\<`void`\>
 Defined in:
-[epub/index.ts:1698](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1698)
+[epub/index.ts:1696](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1696)
 Add a collection to the EPUB metadata.
@@ -360,7 +396,7 @@ collections. Otherwise, it will be added to the end of the list.
 > **addContributor**(`contributor`, `index?`): `Promise`\<`void`\>
 Defined in:
-[epub/index.ts:2040](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2040)
+[epub/index.ts:2038](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2038)
 Add a contributor to the EPUB metadata.
@@ -390,7 +426,7 @@ https://www.w3.org/TR/epub-33/#sec-opf-dccreator
 > **addCreator**(`creator`, `index?`, `type?`): `Promise`\<`void`\>
 Defined in:
-[epub/index.ts:1885](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1885)
+[epub/index.ts:1883](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1883)
 Add a creator to the EPUB metadata.
@@ -420,7 +456,7 @@ https://www.w3.org/TR/epub-33/#sec-opf-dccreator
 > **addManifestItem**(`item`, `contents`, `encoding`): `Promise`\<`void`\>
 Defined in:
-[epub/index.ts:2570](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2570)
+[epub/index.ts:2581](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2581)
 Create a new manifest item and write its contents to a new entry.
@@ -449,7 +485,7 @@ https://www.w3.org/TR/epub-33/#sec-contentdocs
 > **addManifestItem**(`item`, `contents`, `encoding`): `Promise`\<`void`\>
 Defined in:
-[epub/index.ts:2575](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2575)
+[epub/index.ts:2586](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2586)
 Create a new manifest item and write its contents to a new entry.
@@ -478,7 +514,7 @@ https://www.w3.org/TR/epub-33/#sec-contentdocs
 > **addManifestItem**(`item`, `contents`): `Promise`\<`void`\>
 Defined in:
-[epub/index.ts:2580](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2580)
+[epub/index.ts:2591](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2591)
 Create a new manifest item and write its contents to a new entry.
@@ -506,7 +542,7 @@ https://www.w3.org/TR/epub-33/#sec-contentdocs
 > **addMetadata**(`entry`): `Promise`\<`void`\>
 Defined in:
-[epub/index.ts:2692](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2692)
+[epub/index.ts:2702](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2702)
 Add a new metadata entry to the Epub.
@@ -533,7 +569,7 @@ https://www.w3.org/TR/epub-33/#sec-pkg-metadata
 > **addSpineItem**(`manifestId`, `index?`): `Promise`\<`void`\>
 Defined in:
-[epub/index.ts:2094](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2094)
+[epub/index.ts:2092](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2092)
 Add an item to the spine of the EPUB.
@@ -563,7 +599,7 @@ https://www.w3.org/TR/epub-33/#sec-spine-elem
 > **addSubject**(`subject`): `Promise`\<`void`\>
 Defined in:
-[epub/index.ts:1227](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1227)
+[epub/index.ts:1225](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1225)
 Add a subject to the EPUB metadata.
@@ -586,7 +622,7 @@ https://www.w3.org/TR/epub-33/#sec-opf-dcsubject
 > **copy**(`path?`): `Promise`\<[`Epub`](#epub)\>
 Defined in:
-[epub/index.ts:652](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L652)
+[epub/index.ts:630](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L630)
 ##### Parameters
@@ -605,7 +641,7 @@ Defined in:
 > [`XmlElement`](#xmlelement)\<`"html"`\>)[]\>
 Defined in:
-[epub/index.ts:2396](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2396)
+[epub/index.ts:2398](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2398)
 Create a new XHTML document with the given body and head.
@@ -627,7 +663,7 @@ Create a new XHTML document with the given body and head.
 > **discardAndClose**(): `void`
 Defined in:
-[epub/index.ts:2935](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2935)
+[epub/index.ts:2945](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2945)
 ##### Returns
@@ -638,7 +674,7 @@ Defined in:
 > **findAllMetadataItems**(`predicate`): `Promise`\<`object`[]\>
 Defined in:
-[epub/index.ts:897](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L897)
+[epub/index.ts:895](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L895)
 Returns the item in the metadata element's children array that matches the
 provided predicate.
@@ -678,7 +714,7 @@ provided predicate.
 > \}\>
 Defined in:
-[epub/index.ts:888](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L888)
+[epub/index.ts:886](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L886)
 Returns the item in the metadata element's children array that matches the
 provided predicate.
@@ -717,7 +753,7 @@ provided predicate.
 > **getBaseDirection**(): `Promise`\<`"auto"` \| `"rtl"` \| `"ltr"`\>
 Defined in:
-[epub/index.ts:1181](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1181)
+[epub/index.ts:1179](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1179)
 Retrieve the base direction from the package element.
@@ -736,7 +772,7 @@ https://www.w3.org/TR/epub-33/#attrdef-dir
 > **getCollections**(): `Promise`\<[`Collection`](#collection)[]\>
 Defined in:
-[epub/index.ts:1658](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1658)
+[epub/index.ts:1656](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1656)
 Retrieve the list of collections.
@@ -749,7 +785,7 @@ Retrieve the list of collections.
 > **getContributors**(): `Promise`\<[`DcCreator`](#dccreator)[]\>
 Defined in:
-[epub/index.ts:1872](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1872)
+[epub/index.ts:1870](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1870)
 Retrieve the list of contributors.
@@ -768,7 +804,7 @@ https://www.w3.org/TR/epub-33/#sec-opf-dccontributor
 > **getCoverImage**(): `Promise`\<`null` \| `Uint8Array`\<`ArrayBufferLike`\>\>
 Defined in:
-[epub/index.ts:1077](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1077)
+[epub/index.ts:1075](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1075)
 Retrieve the cover image data as a byte array.
@@ -789,7 +825,7 @@ https://www.w3.org/TR/epub-33/#sec-cover-image
 > [`ManifestItem`](#manifestitem)\>
 Defined in:
-[epub/index.ts:1058](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1058)
+[epub/index.ts:1056](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1056)
 Retrieve the cover image manifest item.
@@ -809,7 +845,7 @@ https://www.w3.org/TR/epub-33/#sec-cover-image
 > **getCreators**(`type`): `Promise`\<[`DcCreator`](#dccreator)[]\>
 Defined in:
-[epub/index.ts:1811](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1811)
+[epub/index.ts:1809](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1809)
 Retrieve the list of creators.
@@ -832,7 +868,7 @@ https://www.w3.org/TR/epub-33/#sec-opf-dccreator
 > **getDescription**(): `Promise`\<`null` \| `string`\>
 Defined in:
-[epub/index.ts:1509](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1509)
+[epub/index.ts:1507](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1507)
 Retrieve the Epub's description as specified in its package document metadata.
@@ -848,7 +884,7 @@ as a string. Descriptions may include HTML markup.
 > **getGuideEntries**(): `Promise`\<`GuideItem`[]\>
 Defined in:
-[epub/index.ts:2912](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2912)
+[epub/index.ts:2922](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2922)
 Retrieve the guide entries from the package document.
@@ -864,7 +900,7 @@ many publications still include it.
 > **getIdentifier**(): `Promise`\<`null` \| `string`\>
 Defined in:
-[epub/index.ts:992](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L992)
+[epub/index.ts:990](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L990)
 Retrieve the identifier from the dc:identifier element in the EPUB metadata.
@@ -878,13 +914,37 @@ If there is no dc:identifier element, returns null.
 https://www.w3.org/TR/epub-33/#sec-opf-dcidentifier
+#### getItemArchiveLength()
+> **getItemArchiveLength**(`id`): `Promise`\<`number`\>
+Defined in:
+[epub/index.ts:672](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L672)
+Length of the underlying archive entry for a manifest item, in bytes Necessary
+to compute the readium page count which is for COMPRESSED content
+##### Parameters
+| Parameter | Type     |
+| --------- | -------- |
+| `id`      | `string` |
+##### Returns
+`Promise`\<`number`\>
+##### See
+[https://github.com/readium/architecture/issues/123](https://github.com/readium/architecture/issues/123)
 #### getLandmarks()
 > **getLandmarks**(`__namedParameters`): `Promise`\<`null` \|
 > [`Navigation`](#navigation)\>
 Defined in:
-[epub/index.ts:2273](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2273)
+[epub/index.ts:2271](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2271)
 Returns the structured landmarks navigation document as a Navigation object
@@ -908,7 +968,7 @@ https://www.w3.org/TR/epub-33/#sec-nav-landmarks
 > **getLanguage**(): `Promise`\<`null` \| `Locale`\>
 Defined in:
-[epub/index.ts:1346](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1346)
+[epub/index.ts:1344](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1344)
 Retrieve the Epub's language as specified in its package document metadata.
@@ -928,7 +988,7 @@ https://www.w3.org/TR/epub-33/#sec-opf-dclanguage
 > **getLayout**(): `Promise`\<`"pre-paginated"` \| `"reflowable"`\>
 Defined in:
-[epub/index.ts:1162](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1162)
+[epub/index.ts:1160](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1160)
 Retrieve the layout from the rendition:layout meta element in the EPUB metadata.
@@ -948,7 +1008,7 @@ https://www.w3.org/TR/epub-33/#layout
 > [`ManifestItem`](#manifestitem)\>\>
 Defined in:
-[epub/index.ts:813](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L813)
+[epub/index.ts:811](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L811)
 Retrieve the manifest for the Epub.
@@ -968,7 +1028,7 @@ https://www.w3.org/TR/epub-33/#sec-pkg-manifest
 > **getMetadata**(): `Promise`\<[`EpubMetadata`](#epubmetadata)\>
 Defined in:
-[epub/index.ts:964](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L964)
+[epub/index.ts:962](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L962)
 Retrieve the metadata entries for the Epub.
@@ -991,7 +1051,7 @@ https://www.w3.org/TR/epub-33/#sec-pkg-metadata
 > **getModifiedDate**(): `Promise`\<`null` \| `Date`\>
 Defined in:
-[epub/index.ts:1145](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1145)
+[epub/index.ts:1143](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1143)
 Retrieve the modified date from the dcterms:modified metadata in the EPUB
 metadata as a Date object.
@@ -1011,7 +1071,7 @@ https://www.w3.org/TR/epub-33/#sec-metadata-last-modified
 > **getNcxTableOfContents**(): `Promise`\<[`NavigationList`](#navigationlist)\>
 Defined in:
-[epub/index.ts:2817](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2817)
+[epub/index.ts:2827](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2827)
 Parse the NCX table of contents, if one exists, and return a tree of TocEntry
 nodes.
@@ -1023,13 +1083,25 @@ and EPUB 3 publications that retain an NCX for backwards compatibility.
 `Promise`\<[`NavigationList`](#navigationlist)\>
+#### getPackageElement()
+> **getPackageElement**():
+> `Promise`\<[`XmlElement`](#xmlelement)\<`"package"`\>\>
+Defined in:
+[epub/index.ts:746](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L746)
+##### Returns
+`Promise`\<[`XmlElement`](#xmlelement)\<`"package"`\>\>
 #### getPackageVocabularyPrefixes()
 > **getPackageVocabularyPrefixes**(): `Promise`\<`Record`\<`string`,
 > `string`\>\>
 Defined in:
-[epub/index.ts:1526](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1526)
+[epub/index.ts:1524](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1524)
 Return the set of custom vocabulary prefixes set on this publication's root
 package element.
@@ -1050,7 +1122,7 @@ https://www.w3.org/TR/epub-33/#sec-prefix-attr
 > [`Navigation`](#navigation)\>
 Defined in:
-[epub/index.ts:2285](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2285)
+[epub/index.ts:2283](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2283)
 Returns the structured page list navigation document as a Navigation object
@@ -1074,7 +1146,7 @@ https://www.w3.org/TR/epub-33/#sec-nav-landmarks
 > **getPublicationDate**(): `Promise`\<`null` \| `Date`\>
 Defined in:
-[epub/index.ts:1114](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1114)
+[epub/index.ts:1112](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1112)
 Retrieve the publication date from the dc:date element in the EPUB metadata as a
 Date object.
@@ -1094,7 +1166,7 @@ https://www.w3.org/TR/epub-33/#sec-opf-dcdate
 > **getRootfile**(): `Promise`\<`string`\>
 Defined in:
-[epub/index.ts:685](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L685)
+[epub/index.ts:682](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L682)
 ##### Returns
@@ -1105,7 +1177,7 @@ Defined in:
 > **getSpineItems**(): `Promise`\<[`ManifestItem`](#manifestitem)[]\>
 Defined in:
-[epub/index.ts:2075](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2075)
+[epub/index.ts:2073](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2073)
 Retrieve the manifest items that make up the Epub's spine.
@@ -1125,7 +1197,7 @@ https://www.w3.org/TR/epub-33/#sec-spine-elem
 > **getSubjects**(): `Promise`\<(`string` \| [`DcSubject`](#dcsubject))[]\>
 Defined in:
-[epub/index.ts:1301](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1301)
+[epub/index.ts:1299](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1299)
 Retrieve the list of subjects for this EPUB.
@@ -1146,7 +1218,7 @@ https://www.w3.org/TR/epub-33/#sec-opf-dcsubject
 > **getSubtitle**(): `Promise`\<`null` \| `string`\>
 Defined in:
-[epub/index.ts:1416](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1416)
+[epub/index.ts:1414](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1414)
 Retrieve the subtitle of the Epub, if it exists.
@@ -1164,7 +1236,7 @@ https://www.w3.org/TR/epub-33/#sec-opf-dctitle
 > [`Navigation`](#navigation)\>
 Defined in:
-[epub/index.ts:2256](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2256)
+[epub/index.ts:2254](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2254)
 Returns the structured table of contents navigation document as a Navigation
 object.
@@ -1189,7 +1261,7 @@ https://www.w3.org/TR/epub-33/#sec-nav-toc
 > **getTitle**(`expanded`): `Promise`\<`null` \| `string`\>
 Defined in:
-[epub/index.ts:1392](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1392)
+[epub/index.ts:1390](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1390)
 Retrieve the title of the Epub.
@@ -1212,7 +1284,7 @@ https://www.w3.org/TR/epub-33/#sec-opf-dctitle
 > **getTitles**(): `Promise`\<`object`[]\>
 Defined in:
-[epub/index.ts:1428](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1428)
+[epub/index.ts:1426](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1426)
 Retrieve all title entries of the Epub.
@@ -1229,7 +1301,7 @@ https://www.w3.org/TR/epub-33/#sec-opf-dctitle
 > **getType**(): `Promise`\<`null` \| [`MetadataEntry`](#metadataentry)\>
 Defined in:
-[epub/index.ts:1214](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1214)
+[epub/index.ts:1212](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1212)
 Retrieve the publication type from the dc:type element in the EPUB metadata.
@@ -1248,7 +1320,7 @@ https://www.w3.org/TR/epub-33/#sec-opf-dctype
 > **getVersion**(): `Promise`\<`string`\>
 Defined in:
-[epub/index.ts:2804](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2804)
+[epub/index.ts:2814](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2814)
 Returns the EPUB version declared on the package element.
@@ -1264,7 +1336,7 @@ Returns the EPUB version declared on the package element.
 > `Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\>
 Defined in:
-[epub/index.ts:2335](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2335)
+[epub/index.ts:2337](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2337)
 Retrieve the contents of a file, given its href.
@@ -1287,7 +1359,7 @@ encoding parameter.
 > **readFileContents**(`href`, `relativeTo`, `encoding`): `Promise`\<`string`\>
 Defined in:
-[epub/index.ts:2336](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2336)
+[epub/index.ts:2338](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2338)
 Retrieve the contents of a file, given its href.
@@ -1313,7 +1385,7 @@ encoding parameter.
 > **readItemContents**(`id`): `Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\>
 Defined in:
-[epub/index.ts:2368](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2368)
+[epub/index.ts:2370](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2370)
 Retrieve the contents of a manifest item, given its id.
@@ -1336,7 +1408,7 @@ https://www.w3.org/TR/epub-33/#sec-contentdocs
 > **readItemContents**(`id`, `encoding`): `Promise`\<`string`\>
 Defined in:
-[epub/index.ts:2369](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2369)
+[epub/index.ts:2371](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2371)
 Retrieve the contents of a manifest item, given its id.
@@ -1362,7 +1434,7 @@ https://www.w3.org/TR/epub-33/#sec-contentdocs
 > **readXhtmlItemContents**(`id`, `as?`): `Promise`\<[`ParsedXml`](#parsedxml)\>
 Defined in:
-[epub/index.ts:2431](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2431)
+[epub/index.ts:2433](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2433)
 Retrieves the contents of an XHTML item, given its manifest id.
@@ -1386,7 +1458,7 @@ https://www.w3.org/TR/epub-33/#sec-xhtml
 > **readXhtmlItemContents**(`id`, `as`): `Promise`\<`string`\>
 Defined in:
-[epub/index.ts:2432](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2432)
+[epub/index.ts:2434](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2434)
 Retrieves the contents of an XHTML item, given its manifest id.
@@ -1410,7 +1482,7 @@ https://www.w3.org/TR/epub-33/#sec-xhtml
 > **removeCollection**(`index`): `Promise`\<`void`\>
 Defined in:
-[epub/index.ts:1767](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1767)
+[epub/index.ts:1765](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1765)
 Remove a collection from the EPUB metadata.
@@ -1432,7 +1504,7 @@ returned by `epub.getCollections()`.
 > **removeContributor**(`index`): `Promise`\<`void`\>
 Defined in:
-[epub/index.ts:2024](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2024)
+[epub/index.ts:2022](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2022)
 Remove a contributor from the EPUB metadata.
@@ -1460,7 +1532,7 @@ https://www.w3.org/TR/epub-33/#sec-opf-dccreator
 > **removeCreator**(`index`, `type`): `Promise`\<`void`\>
 Defined in:
-[epub/index.ts:1972](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1972)
+[epub/index.ts:1970](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1970)
 Remove a creator from the EPUB metadata.
@@ -1487,7 +1559,7 @@ https://www.w3.org/TR/epub-33/#sec-opf-dccreator
 > **removeManifestItem**(`id`): `Promise`\<`void`\>
 Defined in:
-[epub/index.ts:2527](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2527)
+[epub/index.ts:2538](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2538)
 ##### Parameters
@@ -1504,7 +1576,7 @@ Defined in:
 > **removeMetadata**(`predicate`): `Promise`\<`void`\>
 Defined in:
-[epub/index.ts:2776](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2776)
+[epub/index.ts:2786](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2786)
 Remove one or more metadata entries.
@@ -1530,7 +1602,7 @@ https://www.w3.org/TR/epub-33/#sec-pkg-metadata
 > **removeSpineItem**(`index`): `Promise`\<`void`\>
 Defined in:
-[epub/index.ts:2130](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2130)
+[epub/index.ts:2128](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2128)
 Remove the spine item at the specified index.
@@ -1553,7 +1625,7 @@ https://www.w3.org/TR/epub-33/#sec-spine-elem
 > **removeSubject**(`index`): `Promise`\<`void`\>
 Defined in:
-[epub/index.ts:1264](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1264)
+[epub/index.ts:1262](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1262)
 Remove a subject from the EPUB metadata.
@@ -1579,7 +1651,7 @@ https://www.w3.org/TR/epub-33/#sec-opf-dccreator
 > **replaceMetadata**(`predicate`, `entry`): `Promise`\<`void`\>
 Defined in:
-[epub/index.ts:2731](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2731)
+[epub/index.ts:2741](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2741)
 Replace a metadata entry with a new one.
@@ -1607,7 +1679,7 @@ https://www.w3.org/TR/epub-33/#sec-pkg-metadata
 > `Promise`\<`string`\>
 Defined in:
-[epub/index.ts:2307](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2307)
+[epub/index.ts:2309](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2309)
 Returns a path-relative-scheme-less URL, relative to the container root.
@@ -1629,7 +1701,7 @@ Returns a path-relative-scheme-less URL, relative to the container root.
 > **saveAndClose**(): `Promise`\<`void`\>
 Defined in:
-[epub/index.ts:2951](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2951)
+[epub/index.ts:2960](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2960)
 Write the current contents of the Epub to a new EPUB archive on disk.
@@ -1645,7 +1717,7 @@ updated to the current UTC timestamp.
 > **setCoverImage**(`href`, `data`): `Promise`\<`void`\>
 Defined in:
-[epub/index.ts:1091](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1091)
+[epub/index.ts:1089](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1089)
 Set the cover image for the EPUB.
@@ -1668,7 +1740,7 @@ then writes the provided image data to the provided href within the publication.
 > **setDescription**(`description`): `Promise`\<`void`\>
 Defined in:
-[epub/index.ts:1493](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1493)
+[epub/index.ts:1491](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1491)
 Update the Epub's description metadata entry.
@@ -1691,7 +1763,7 @@ encoded as HTML entities.
 > **setIdentifier**(`identifier`): `Promise`\<`void`\>
 Defined in:
-[epub/index.ts:1006](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1006)
+[epub/index.ts:1004](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1004)
 Set the dc:identifier metadata element with the provided string.
@@ -1717,7 +1789,7 @@ https://www.w3.org/TR/epub-33/#sec-opf-dcidentifier
 > **setLanguage**(`locale`): `Promise`\<`void`\>
 Defined in:
-[epub/index.ts:1375](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1375)
+[epub/index.ts:1373](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1373)
 Update the Epub's language metadata entry.
@@ -1743,7 +1815,7 @@ https://www.w3.org/TR/epub-33/#sec-opf-dclanguage
 > **setPackageVocabularyPrefix**(`prefix`, `uri`): `Promise`\<`void`\>
 Defined in:
-[epub/index.ts:1544](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1544)
+[epub/index.ts:1542](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1542)
 Set a custom vocabulary prefix on the root package element.
@@ -1767,7 +1839,7 @@ https://www.w3.org/TR/epub-33/#sec-prefix-attr
 > **setPublicationDate**(`date`): `Promise`\<`void`\>
 Defined in:
-[epub/index.ts:1129](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1129)
+[epub/index.ts:1127](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1127)
 Set the dc:date metadata element with the provided date.
@@ -1793,7 +1865,7 @@ https://www.w3.org/TR/epub-33/#sec-opf-dcdate
 > **setTitle**(`title`): `Promise`\<`void`\>
 Defined in:
-[epub/index.ts:1568](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1568)
+[epub/index.ts:1566](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1566)
 Set the title of the Epub.
@@ -1821,7 +1893,7 @@ https://www.w3.org/TR/epub-33/#sec-opf-dctitle
 > **setTitles**(`entries`): `Promise`\<`void`\>
 Defined in:
-[epub/index.ts:1596](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1596)
+[epub/index.ts:1594](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1594)
 ##### Parameters
@@ -1838,7 +1910,7 @@ Defined in:
 > **setType**(`type`): `Promise`\<`void`\>
 Defined in:
-[epub/index.ts:1198](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1198)
+[epub/index.ts:1196](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L1196)
 Set the dc:type metadata element.
@@ -1864,7 +1936,7 @@ https://www.w3.org/TR/epub-33/#sec-opf-dctype
 > **updateManifestItem**(`id`, `newItem`): `Promise`\<`void`\>
 Defined in:
-[epub/index.ts:2643](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2643)
+[epub/index.ts:2653](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2653)
 Update the manifest entry for an existing item.
@@ -1886,6 +1958,30 @@ To update the contents of an entry, use `epub.writeItemContents()` or
 https://www.w3.org/TR/epub-33/#sec-pkg-manifest
+#### withPackage()
+> **withPackage**(`producer`): `Promise`\<`void`\>
+Defined in:
+[epub/index.ts:772](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L772)
+Safely modify the package document, without race conditions.
+Since the reading the package document is an async process, multiple
+simultaneously dispatched function calls that all attempt to modify it can
+clobber each other's changes. This method uses a mutex to ensure that each
+update runs exclusively.
+##### Parameters
+| Parameter  | Type                                                                                                                                                                                                             | Description                                                                                                                                                                              |
+| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `producer` | (`packageElement`) => `void` \| (`packageElement`) => [`PackageElement`](#packageelement) \| (`packageElement`) => `Promise`\<[`PackageElement`](#packageelement)\> \| (`packageElement`) => `Promise`\<`void`\> | The function to update the package document. If it returns a new package document, that will be persisted, otherwise it will be assumed that the package document was modified in place. |
+##### Returns
+`Promise`\<`void`\>
 #### writeItemContents()
 ##### Call Signature
@@ -1893,7 +1989,7 @@ https://www.w3.org/TR/epub-33/#sec-pkg-manifest
 > **writeItemContents**(`id`, `contents`): `Promise`\<`void`\>
 Defined in:
-[epub/index.ts:2479](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2479)
+[epub/index.ts:2490](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2490)
 Write new contents for an existing manifest item, specified by its id.
@@ -1920,7 +2016,7 @@ https://www.w3.org/TR/epub-33/#sec-contentdocs
 > **writeItemContents**(`id`, `contents`, `encoding`): `Promise`\<`void`\>
 Defined in:
-[epub/index.ts:2480](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2480)
+[epub/index.ts:2491](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2491)
 Write new contents for an existing manifest item, specified by its id.
@@ -1948,7 +2044,7 @@ https://www.w3.org/TR/epub-33/#sec-contentdocs
 > **writeXhtmlItemContents**(`id`, `contents`): `Promise`\<`void`\>
 Defined in:
-[epub/index.ts:2519](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2519)
+[epub/index.ts:2530](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2530)
 Write new contents for an existing XHTML item, specified by its id.
@@ -1975,7 +2071,7 @@ https://www.w3.org/TR/epub-33/#sec-xhtml
 > `static` **addLinkToXhtmlHead**(`xml`, `link`): `void`
 Defined in:
-[epub/index.ts:307](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L307)
+[epub/index.ts:345](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L345)
 Given an XML structure representing a complete XHTML document, add a `link`
 element to the `head` of the document.
@@ -1996,22 +2092,40 @@ This method modifies the provided XML structure.
 `void`
+#### assertEpub3()
+> `static` **assertEpub3**(`epub`): `Promise`\<`void`\>
+Defined in:
+[epub/index.ts:620](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L620)
+##### Parameters
+| Parameter | Type            |
+| --------- | --------------- |
+| `epub`    | [`Epub`](#epub) |
+##### Returns
+`Promise`\<`void`\>
 #### create()
-> `static` **create**(`path`, `__namedParameters`, `additionalMetadata`):
+> `static` **create**(`path`, `dublinCore`, `additionalMetadata`):
 > `Promise`\<[`Epub`](#epub)\>
 Defined in:
-[epub/index.ts:500](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L500)
+[epub/index.ts:568](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L568)
-Construct an Epub instance, optionally beginning with the provided metadata.
+Construct a new EPUB on a writable backend, optionally seeded with the provided
+metadata. Equivalent to `Epub.using(TmpFsAdapter).create(...)`.
 ##### Parameters
 | Parameter            | Type                            | Default value | Description                             |
 | -------------------- | ------------------------------- | ------------- | --------------------------------------- |
 | `path`               | `string`                        | `undefined`   | -                                       |
-| `__namedParameters`  | [`DublinCore`](#dublincore)     | `undefined`   | -                                       |
+| `dublinCore`         | [`DublinCore`](#dublincore)     | `undefined`   | Core metadata terms                     |
 | `additionalMetadata` | [`EpubMetadata`](#epubmetadata) | `[]`          | An array of additional metadata entries |
 ##### Returns
@@ -2024,7 +2138,7 @@ Construct an Epub instance, optionally beginning with the provided metadata.
 > [`XmlElement`](#xmlelement)\<`Name`\>
 Defined in:
-[epub/index.ts:342](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L342)
+[epub/index.ts:380](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L380)
 ##### Type Parameters
@@ -2049,7 +2163,7 @@ Defined in:
 > `static` **createXmlTextNode**(`text`): [`XmlTextNode`](#xmltextnode)
 Defined in:
-[epub/index.ts:355](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L355)
+[epub/index.ts:393](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L393)
 ##### Parameters
@@ -2067,7 +2181,7 @@ Defined in:
 > `undefined` \| [`XmlElement`](#xmlelement)\<`Name`\>
 Defined in:
-[epub/index.ts:428](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L428)
+[epub/index.ts:466](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L466)
 Given an XML structure, find the first child matching the provided name and
 optional filter.
@@ -2096,7 +2210,7 @@ optional filter.
 > `undefined` \| [`XmlElement`](#xmlelement)\<`Name`\>
 Defined in:
-[epub/index.ts:446](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L446)
+[epub/index.ts:484](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L484)
 Given an XML structure, find the first descendant matching the provided name and
 optional filter.
@@ -2127,7 +2241,7 @@ element in the tree matching the name and filter.
 > `static` **formatSmilDuration**(`duration`): `string`
 Defined in:
-[epub/index.ts:290](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L290)
+[epub/index.ts:328](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L328)
 Format a duration, provided as a number of seconds, as a SMIL clock value, to be
 used for Media Overlays.
@@ -2148,29 +2262,103 @@ https://www.w3.org/TR/epub-33/#sec-duration
 #### from()
+##### Call Signature
 > `static` **from**(`pathOrData`): `Promise`\<[`Epub`](#epub)\>
 Defined in:
-[epub/index.ts:583](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L583)
+[epub/index.ts:604](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L604)
-Construct an Epub instance by reading an existing EPUB publication.
+Open an existing EPUB publication, extracting it to a temp directory so writes
+can mutate the unpacked tree and rezip with `saveAndClose`.
-##### Parameters
+Pass `{ readonly: true }` to gate mutations at runtime.
-| Parameter    | Type                                          | Description                                                                                                                           |
-| ------------ | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| `pathOrData` | `string` \| `Uint8Array`\<`ArrayBufferLike`\> | Must be either a string representing the path to an EPUB file on disk, or a Uint8Array representing the data of the EPUB publication. |
+prefer `Epub.using(TmpFsAdapter).from(path)` (or
+`Epub.using(MemoryAdapter).from(path)` for read-only, in-memory access)
-##### Returns
+###### Parameters
+| Parameter    | Type                                          |
+| ------------ | --------------------------------------------- |
+| `pathOrData` | `string` \| `Uint8Array`\<`ArrayBufferLike`\> |
+###### Returns
 `Promise`\<[`Epub`](#epub)\>
+###### Throws
+when the archive is not a valid EPUB 3
+##### Call Signature
+> `static` **from**(`pathOrData`, `options`):
+> `Promise`\<[`EpubReader`](#epubreader)\>
+Defined in:
+[epub/index.ts:605](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L605)
+Open an existing EPUB publication, extracting it to a temp directory so writes
+can mutate the unpacked tree and rezip with `saveAndClose`.
+Pass `{ readonly: true }` to gate mutations at runtime.
+prefer `Epub.using(TmpFsAdapter).from(path)` (or
+`Epub.using(MemoryAdapter).from(path)` for read-only, in-memory access)
+###### Parameters
+| Parameter    | Type                                          |
+| ------------ | --------------------------------------------- |
+| `pathOrData` | `string` \| `Uint8Array`\<`ArrayBufferLike`\> |
+| `options`    | [`FromOptions`](#fromoptions) & `object`      |
+###### Returns
+`Promise`\<[`EpubReader`](#epubreader)\>
+###### Throws
+when the archive is not a valid EPUB 3
+##### Call Signature
+> `static` **from**(`pathOrData`, `options?`): `Promise`\<[`Epub`](#epub) \|
+> [`EpubReader`](#epubreader)\>
+Defined in:
+[epub/index.ts:609](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L609)
+Open an existing EPUB publication, extracting it to a temp directory so writes
+can mutate the unpacked tree and rezip with `saveAndClose`.
+Pass `{ readonly: true }` to gate mutations at runtime.
+prefer `Epub.using(TmpFsAdapter).from(path)` (or
+`Epub.using(MemoryAdapter).from(path)` for read-only, in-memory access)
+###### Parameters
+| Parameter    | Type                                          |
+| ------------ | --------------------------------------------- |
+| `pathOrData` | `string` \| `Uint8Array`\<`ArrayBufferLike`\> |
+| `options?`   | [`FromOptions`](#fromoptions)                 |
+###### Returns
+`Promise`\<[`Epub`](#epub) \| [`EpubReader`](#epubreader)\>
+###### Throws
+when the archive is not a valid EPUB 3
 #### getXhtmlBody()
 > `static` **getXhtmlBody**(`xml`): [`ParsedXml`](#parsedxml)
 Defined in:
-[epub/index.ts:332](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L332)
+[epub/index.ts:370](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L370)
 Given an XML structure representing a complete XHTML document, return the
 sub-structure representing the children of the document's body element.
@@ -2190,7 +2378,7 @@ sub-structure representing the children of the document's body element.
 > `static` **getXhtmlTextContent**(`xml`): `string`
 Defined in:
-[epub/index.ts:364](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L364)
+[epub/index.ts:402](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L402)
 Given an XML structure representing a complete XHTML document, return a string
 representing the concatenation of all text nodes in the document.
@@ -2210,7 +2398,7 @@ representing the concatenation of all text nodes in the document.
 > `static` **getXmlAttributes**(`element`): `Record`\<`string`, `string`\>
 Defined in:
-[epub/index.ts:381](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L381)
+[epub/index.ts:419](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L419)
 Given an XMLElement, return its attributes.
@@ -2229,7 +2417,7 @@ Given an XMLElement, return its attributes.
 > `static` **getXmlChildren**\<`Name`\>(`element`): [`ParsedXml`](#parsedxml)
 Defined in:
-[epub/index.ts:408](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L408)
+[epub/index.ts:446](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L446)
 Given an XMLElement, return a list of its children
@@ -2254,7 +2442,7 @@ Given an XMLElement, return a list of its children
 > `static` **getXmlElementName**\<`Name`\>(`element`): `Name`
 Defined in:
-[epub/index.ts:393](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L393)
+[epub/index.ts:431](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L431)
 Given an XMLElement, return its tag name.
@@ -2279,7 +2467,7 @@ Given an XMLElement, return its tag name.
 > `static` **isXmlTextNode**(`node`): `node is XmlTextNode`
 Defined in:
-[epub/index.ts:468](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L468)
+[epub/index.ts:506](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L506)
 Given an XMLNode, determine whether it represents a text node or an XML element.
@@ -2298,7 +2486,7 @@ Given an XMLNode, determine whether it represents a text node or an XML element.
 > `static` **replaceXmlChildren**\<`Name`\>(`element`, `children`): `void`
 Defined in:
-[epub/index.ts:416](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L416)
+[epub/index.ts:454](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L454)
 ##### Type Parameters
@@ -2322,10 +2510,220 @@ Defined in:
 > `static` **upgrade**(`path`, `options`): `Promise`\<[`Epub`](#epub)\>
 Defined in:
-[epub/index.ts:3022](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L3022)
+[epub/index.ts:2988](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L2988)
 Upgrade an EPUB 2 publication to EPUB 3 in place, returning a new, valid Epub 3
-instance.
+instance. Equivalent to `Epub.using(TmpFsAdapter).upgrade(...)`.
+##### Parameters
+| Parameter | Type                                          |
+| --------- | --------------------------------------------- |
+| `path`    | `string`                                      |
+| `options` | [`Epub2UpgradeOptions`](#epub2upgradeoptions) |
+##### Returns
+`Promise`\<[`Epub`](#epub)\>
+#### using()
+> `static` **using**\<`A`\>(`adapterClass`):
+> [`EpubFactory`](#epubfactory)\<`A`\>
+Defined in:
+[epub/index.ts:588](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L588)
+Specify the storage backend to use for the EPUB
+The returned factory exposes `from`, `create`, and `upgrade`, which route
+through the supplied adapter.
+##### Type Parameters
+| Type Parameter                                                                  |
+| ------------------------------------------------------------------------------- |
+| `A` _extends_ [`EpubStorageAdapterClass`](#epubstorageadapterclass)\<`object`\> |
+##### Parameters
+| Parameter      | Type |
+| -------------- | ---- |
+| `adapterClass` | `A`  |
+##### Returns
+[`EpubFactory`](#epubfactory)\<`A`\>
+##### Example
+```ts
+using epub = await Epub.using(TmpFsAdapter).from(path)
+using reader = await Epub.using(MemoryAdapter).from(buffer, { cache: false })
+```
+---
+## EpubFactory\<A\>
+Defined in:
+[epub/index.ts:3017](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L3017)
+Adapter-bound factory returned by [Epub.using](#using).
+Mirrors the static factory surface (`from`, `create`, `upgrade`) but routes all
+I/O through the supplied adapter. Each method's signature degrades gracefully
+when the adapter doesn't support the operation: `create` and `upgrade` throw at
+runtime if the adapter is read-only or lacks `initEmpty`.
+### Type Parameters
+| Type Parameter                                                      |
+| ------------------------------------------------------------------- |
+| `A` _extends_ [`EpubStorageAdapterClass`](#epubstorageadapterclass) |
+### Constructors
+#### Constructor
+> **new EpubFactory**\<`A`\>(`adapterClass`):
+> [`EpubFactory`](#epubfactory)\<`A`\>
+Defined in:
+[epub/index.ts:3018](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L3018)
+##### Parameters
+| Parameter      | Type |
+| -------------- | ---- |
+| `adapterClass` | `A`  |
+##### Returns
+[`EpubFactory`](#epubfactory)\<`A`\>
+### Properties
+#### adapterClass
+> `readonly` **adapterClass**: `A`
+Defined in:
+[epub/index.ts:3018](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L3018)
+### Methods
+#### create()
+> **create**(`path`, `__namedParameters`, `additionalMetadata`):
+> `Promise`\<[`EpubInstanceFor`](#epubinstancefor)\<`A`\>\>
+Defined in:
+[epub/index.ts:3074](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L3074)
+Construct a new EPUB on this factory's adapter, optionally seeded with the
+provided metadata. Requires a writable adapter that implements `initEmpty`
+(today: [TmpFsAdapter](#tmpfsadapter)).
+##### Parameters
+| Parameter            | Type                            | Default value |
+| -------------------- | ------------------------------- | ------------- |
+| `path`               | `string`                        | `undefined`   |
+| `__namedParameters`  | [`DublinCore`](#dublincore)     | `undefined`   |
+| `additionalMetadata` | [`EpubMetadata`](#epubmetadata) | `[]`          |
+##### Returns
+`Promise`\<[`EpubInstanceFor`](#epubinstancefor)\<`A`\>\>
+##### Throws
+when the adapter is read-only or does not implement initEmpty
+#### from()
+##### Call Signature
+> **from**(`source`, `options`): `Promise`\<`Pick`\<[`Epub`](#epub), `"storage"`
+> \| `"getManifest"` \| `"getVersion"` \| `"getLayout"` \| `"getBaseDirection"`
+> \| `"getMetadata"` \| `"findMetadataItem"` \| `"findAllMetadataItems"` \|
+> `"getIdentifier"` \| `"getTitle"` \| `"getSubtitle"` \| `"getTitles"` \|
+> `"getLanguage"` \| `"getPublicationDate"` \| `"getModifiedDate"` \|
+> `"getDescription"` \| `"getType"` \| `"getCreators"` \| `"getContributors"` \|
+> `"getSubjects"` \| `"getCollections"` \| `"getPackageVocabularyPrefixes"` \|
+> `"getCoverImageItem"` \| `"getCoverImage"` \| `"getSpineItems"` \|
+> `"getNcxTableOfContents"` \| `"getGuideEntries"` \| `"getTableOfContents"` \|
+> `"getLandmarks"` \| `"getPageList"` \| `"resolveHref"` \| `"readFileContents"`
+> \| `"readItemContents"` \| `"readXhtmlItemContents"` \|
+> `"getItemArchiveLength"` \| `"discardAndClose"`\> & `Disposable` & `object`\>
+Defined in:
+[epub/index.ts:3025](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L3025)
+Open an existing EPUB through this factory's adapter
+###### Parameters
+| Parameter | Type                                                                                  |
+| --------- | ------------------------------------------------------------------------------------- |
+| `source`  | `string` \| `Uint8Array`\<`ArrayBufferLike`\>                                         |
+| `options` | [`FromOptions`](#fromoptions) & `object` & [`AdapterOptions`](#adapteroptions)\<`A`\> |
+###### Returns
+`Promise`\<`Pick`\<[`Epub`](#epub), `"storage"` \| `"getManifest"` \|
+`"getVersion"` \| `"getLayout"` \| `"getBaseDirection"` \| `"getMetadata"` \|
+`"findMetadataItem"` \| `"findAllMetadataItems"` \| `"getIdentifier"` \|
+`"getTitle"` \| `"getSubtitle"` \| `"getTitles"` \| `"getLanguage"` \|
+`"getPublicationDate"` \| `"getModifiedDate"` \| `"getDescription"` \|
+`"getType"` \| `"getCreators"` \| `"getContributors"` \| `"getSubjects"` \|
+`"getCollections"` \| `"getPackageVocabularyPrefixes"` \| `"getCoverImageItem"`
+\| `"getCoverImage"` \| `"getSpineItems"` \| `"getNcxTableOfContents"` \|
+`"getGuideEntries"` \| `"getTableOfContents"` \| `"getLandmarks"` \|
+`"getPageList"` \| `"resolveHref"` \| `"readFileContents"` \|
+`"readItemContents"` \| `"readXhtmlItemContents"` \| `"getItemArchiveLength"` \|
+`"discardAndClose"`\> & `Disposable` & `object`\>
+###### Throws
+when the archive is not a valid EPUB 3
+##### Call Signature
+> **from**(`source`, `options?`):
+> `Promise`\<[`EpubInstanceFor`](#epubinstancefor)\<`A`\> & `object`\>
+Defined in:
+[epub/index.ts:3029](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L3029)
+Open an existing EPUB through this factory's adapter
+###### Parameters
+| Parameter  | Type                                                                       |
+| ---------- | -------------------------------------------------------------------------- |
+| `source`   | `string` \| `Uint8Array`\<`ArrayBufferLike`\>                              |
+| `options?` | [`FromOptions`](#fromoptions) & [`AdapterOptions`](#adapteroptions)\<`A`\> |
+###### Returns
+`Promise`\<[`EpubInstanceFor`](#epubinstancefor)\<`A`\> & `object`\>
+###### Throws
+when the archive is not a valid EPUB 3
+#### upgrade()
+> **upgrade**(`path`, `options`):
+> `Promise`\<[`EpubInstanceFor`](#epubinstancefor)\<`A`\>\>
+Defined in:
+[epub/index.ts:3187](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L3187)
+Upgrade an EPUB 2 publication to EPUB 3 in place using this factory's adapter,
+returning a new, valid Epub 3 instance.
 Performs the following transformations:
@@ -2338,6 +2736,11 @@ Performs the following transformations:
 - goes over each xhtml item and rewrites it using XMLParser to make sure the
   output is valid XHTML
+Requires a writable adapter. When
+[Upgrade.Epub2UpgradeOptions.outputPath](#outputpath) is set, the source file is
+copied to that path on disk first; this only makes sense for adapters whose
+`source` is a real fs path.
 ##### Parameters
 | Parameter | Type                                          |
@@ -2347,14 +2750,18 @@ Performs the following transformations:
 ##### Returns
-`Promise`\<[`Epub`](#epub)\>
+`Promise`\<[`EpubInstanceFor`](#epubinstancefor)\<`A`\>\>
+##### Throws
+when the adapter is read-only
 ---
-## EpubVersionError
+## EpubReadOnlyError
 Defined in:
-[epub/index.ts:200](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L200)
+[epub/index.ts:238](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L238)
 ### Extends
@@ -2364,7 +2771,8 @@ Defined in:
 #### Constructor
-> **new EpubVersionError**(`message?`): [`EpubVersionError`](#epubversionerror)
+> **new EpubReadOnlyError**(`message?`):
+> [`EpubReadOnlyError`](#epubreadonlyerror)
 Defined in: node_modules/typescript/lib/lib.es5.d.ts:1082
@@ -2376,7 +2784,7 @@ Defined in: node_modules/typescript/lib/lib.es5.d.ts:1082
 ##### Returns
-[`EpubVersionError`](#epubversionerror)
+[`EpubReadOnlyError`](#epubreadonlyerror)
 ##### Inherited from
@@ -2384,8 +2792,8 @@ Defined in: node_modules/typescript/lib/lib.es5.d.ts:1082
 #### Constructor
-> **new EpubVersionError**(`message?`, `options?`):
-> [`EpubVersionError`](#epubversionerror)
+> **new EpubReadOnlyError**(`message?`, `options?`):
+> [`EpubReadOnlyError`](#epubreadonlyerror)
 Defined in: node_modules/typescript/lib/lib.es5.d.ts:1082
@@ -2398,7 +2806,7 @@ Defined in: node_modules/typescript/lib/lib.es5.d.ts:1082
 ##### Returns
-[`EpubVersionError`](#epubversionerror)
+[`EpubReadOnlyError`](#epubreadonlyerror)
 ##### Inherited from
@@ -2582,63 +2990,747 @@ https://v8.dev/docs/stack-trace-api#customizing-stack-traces
 ---
-## AlternateScript
+## EpubVersionError
 Defined in:
-[epub/index.ts:110](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L110)
+[epub/index.ts:237](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L237)
-### Properties
+### Extends
-#### locale
+- `Error`
-> **locale**: `Locale`
+### Constructors
-Defined in:
-[epub/index.ts:112](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L112)
+#### Constructor
-#### name
+> **new EpubVersionError**(`message?`): [`EpubVersionError`](#epubversionerror)
-> **name**: `string`
+Defined in: node_modules/typescript/lib/lib.es5.d.ts:1082
-Defined in:
-[epub/index.ts:111](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L111)
+##### Parameters
----
+| Parameter  | Type     |
+| ---------- | -------- |
+| `message?` | `string` |
-## Collection
+##### Returns
-Defined in:
-[epub/index.ts:134](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L134)
+[`EpubVersionError`](#epubversionerror)
+##### Inherited from
+`Error.constructor`
+#### Constructor
+> **new EpubVersionError**(`message?`, `options?`):
+> [`EpubVersionError`](#epubversionerror)
+Defined in: node_modules/typescript/lib/lib.es5.d.ts:1082
+##### Parameters
+| Parameter  | Type           |
+| ---------- | -------------- |
+| `message?` | `string`       |
+| `options?` | `ErrorOptions` |
+##### Returns
+[`EpubVersionError`](#epubversionerror)
+##### Inherited from
+`Error.constructor`
+### Properties
+#### cause?
+> `optional` **cause**: `unknown`
+Defined in: node_modules/typescript/lib/lib.es2022.error.d.ts:26
+##### Inherited from
+`Error.cause`
+#### message
+> **message**: `string`
+Defined in: node_modules/typescript/lib/lib.es5.d.ts:1077
+##### Inherited from
+`Error.message`
+#### name
+> **name**: `string`
+Defined in: node_modules/typescript/lib/lib.es5.d.ts:1076
+##### Inherited from
+`Error.name`
+#### stack?
+> `optional` **stack**: `string`
+Defined in: node_modules/typescript/lib/lib.es5.d.ts:1078
+##### Inherited from
+`Error.stack`
+#### stackTraceLimit
+> `static` **stackTraceLimit**: `number`
+Defined in: node_modules/@types/node/globals.d.ts:68
+The `Error.stackTraceLimit` property specifies the number of stack frames
+collected by a stack trace (whether generated by `new Error().stack` or
+`Error.captureStackTrace(obj)`).
+The default value is `10` but may be set to any valid JavaScript number. Changes
+will affect any stack trace captured _after_ the value has been changed.
+If set to a non-number value, or set to a negative number, stack traces will not
+capture any frames.
+##### Inherited from
+`Error.stackTraceLimit`
+### Methods
+#### captureStackTrace()
+> `static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void`
+Defined in: node_modules/@types/node/globals.d.ts:52
+Creates a `.stack` property on `targetObject`, which when accessed returns a
+string representing the location in the code at which
+`Error.captureStackTrace()` was called.
+```js
+const myObject = {}
+Error.captureStackTrace(myObject)
+myObject.stack // Similar to `new Error().stack`
+```
+The first line of the trace will be prefixed with
+`${myObject.name}: ${myObject.message}`.
+The optional `constructorOpt` argument accepts a function. If given, all frames
+above `constructorOpt`, including `constructorOpt`, will be omitted from the
+generated stack trace.
+The `constructorOpt` argument is useful for hiding implementation details of
+error generation from the user. For instance:
+```js
+function a() {
+  b()
+}
+function b() {
+  c()
+}
+function c() {
+  // Create an error without stack trace to avoid calculating the stack trace twice.
+  const { stackTraceLimit } = Error
+  Error.stackTraceLimit = 0
+  const error = new Error()
+  Error.stackTraceLimit = stackTraceLimit
+  // Capture the stack trace above function b
+  Error.captureStackTrace(error, b) // Neither function c, nor b is included in the stack trace
+  throw error
+}
+a()
+```
+##### Parameters
+| Parameter         | Type       |
+| ----------------- | ---------- |
+| `targetObject`    | `object`   |
+| `constructorOpt?` | `Function` |
+##### Returns
+`void`
+##### Inherited from
+`Error.captureStackTrace`
+#### isError()
+> `static` **isError**(`error`): `error is Error`
+Defined in: node_modules/typescript/lib/lib.esnext.error.d.ts:23
+Indicates whether the argument provided is a built-in Error instance or not.
+##### Parameters
+| Parameter | Type      |
+| --------- | --------- |
+| `error`   | `unknown` |
+##### Returns
+`error is Error`
+##### Inherited from
+`Error.isError`
+#### prepareStackTrace()
+> `static` **prepareStackTrace**(`err`, `stackTraces`): `any`
+Defined in: node_modules/@types/node/globals.d.ts:56
+##### Parameters
+| Parameter     | Type         |
+| ------------- | ------------ |
+| `err`         | `Error`      |
+| `stackTraces` | `CallSite`[] |
+##### Returns
+`any`
+##### See
+https://v8.dev/docs/stack-trace-api#customizing-stack-traces
+##### Inherited from
+`Error.prepareStackTrace`
+---
+## MemoryAdapter
+Defined in:
+[epub/adapters/memory.ts:32](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/memory.ts#L32)
+Loads an EPUB archive into memory and serves all I/O off the in-memory zip
+handle.
+read only
+### Implements
+- [`EpubStorageAdapter`](#epubstorageadapter)
+### Properties
+#### rootPath
+> `readonly` **rootPath**: `string`
+Defined in:
+[epub/adapters/memory.ts:71](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/memory.ts#L71)
+Opaque path prefix used by `resolveInternalHref` to anchor absolute paths within
+the archive. For TmpFsAdapter this is the tmp dir; for MemoryAdapter it's a
+virtual prefix that's never written to disk
+##### Implementation of
+[`EpubStorageAdapter`](#epubstorageadapter).[`rootPath`](#rootpath-2)
+#### capabilities
+> `readonly` `static` **capabilities**: `object`
+Defined in:
+[epub/adapters/memory.ts:34](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/memory.ts#L34)
+##### writable
+> `readonly` **writable**: `false` = `false`
+#### kind
+> `readonly` `static` **kind**: `"in-memory"`
+Defined in:
+[epub/adapters/memory.ts:33](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/memory.ts#L33)
+### Methods
+#### archiveLength()
+> **archiveLength**(`path`): `Promise`\<`number`\>
+Defined in:
+[epub/adapters/memory.ts:114](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/memory.ts#L114)
+Length of an entry in bytes, for the readium page-count heuristic which expects
+compressed size when available
+##### Parameters
+| Parameter | Type     |
+| --------- | -------- |
+| `path`    | `string` |
+##### Returns
+`Promise`\<`number`\>
+##### Implementation of
+[`EpubStorageAdapter`](#epubstorageadapter).[`archiveLength`](#archivelength-4)
+#### dispose()
+> **dispose**(): `void`
+Defined in:
+[epub/adapters/memory.ts:120](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/memory.ts#L120)
+Always called on close or error
+##### Returns
+`void`
+##### Implementation of
+[`EpubStorageAdapter`](#epubstorageadapter).[`dispose`](#dispose-6)
+#### read()
+##### Call Signature
+> **read**(`path`): `Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\>
+Defined in:
+[epub/adapters/memory.ts:85](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/memory.ts#L85)
+###### Parameters
+| Parameter | Type     |
+| --------- | -------- |
+| `path`    | `string` |
+###### Returns
+`Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\>
+###### Implementation of
+[`EpubStorageAdapter`](#epubstorageadapter).[`read`](#read-6)
+##### Call Signature
+> **read**(`path`, `encoding`): `Promise`\<`string`\>
+Defined in:
+[epub/adapters/memory.ts:86](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/memory.ts#L86)
+###### Parameters
+| Parameter  | Type      |
+| ---------- | --------- |
+| `path`     | `string`  |
+| `encoding` | `"utf-8"` |
+###### Returns
+`Promise`\<`string`\>
+###### Implementation of
+[`EpubStorageAdapter`](#epubstorageadapter).[`read`](#read-6)
+#### init()
+> `static` **init**(`source`, `opts`):
+> `Promise`\<[`MemoryAdapter`](#memoryadapter)\>
+Defined in:
+[epub/adapters/memory.ts:36](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/memory.ts#L36)
+##### Parameters
+| Parameter | Type                                            |
+| --------- | ----------------------------------------------- |
+| `source`  | `string` \| `Uint8Array`\<`ArrayBufferLike`\>   |
+| `opts`    | [`MemoryAdapterOptions`](#memoryadapteroptions) |
+##### Returns
+`Promise`\<[`MemoryAdapter`](#memoryadapter)\>
+---
+## TmpFsAdapter
+Defined in:
+[epub/adapters/tmpfs.ts:59](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/tmpfs.ts#L59)
+Extracts an EPUB archive to a temp directory and serves all I/O off the real
+filesystem. `Epub.using(TmpFsAdapter).from(...)` returns a writable
+[Epub](#epub).
+### Implements
+- [`EpubStorageAdapter`](#epubstorageadapter)
+### Properties
+#### rootPath
+> `readonly` **rootPath**: `string`
+Defined in:
+[epub/adapters/tmpfs.ts:102](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/tmpfs.ts#L102)
+Opaque path prefix used by `resolveInternalHref` to anchor absolute paths within
+the archive. For TmpFsAdapter this is the tmp dir; for MemoryAdapter it's a
+virtual prefix that's never written to disk
+##### Implementation of
+[`EpubStorageAdapter`](#epubstorageadapter).[`rootPath`](#rootpath-2)
+#### capabilities
+> `readonly` `static` **capabilities**: `object`
+Defined in:
+[epub/adapters/tmpfs.ts:61](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/tmpfs.ts#L61)
+##### writable
+> `readonly` **writable**: `true` = `true`
+#### kind
+> `readonly` `static` **kind**: `"extracted-dir"`
+Defined in:
+[epub/adapters/tmpfs.ts:60](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/tmpfs.ts#L60)
+### Methods
+#### archiveLength()
+> **archiveLength**(`path`): `Promise`\<`number`\>
+Defined in:
+[epub/adapters/tmpfs.ts:125](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/tmpfs.ts#L125)
+Length of an entry in bytes, for the readium page-count heuristic which expects
+compressed size when available
+##### Parameters
+| Parameter | Type     |
+| --------- | -------- |
+| `path`    | `string` |
+##### Returns
+`Promise`\<`number`\>
+##### Implementation of
+[`EpubStorageAdapter`](#epubstorageadapter).[`archiveLength`](#archivelength-4)
+#### dispose()
+> **dispose**(): `void`
+Defined in:
+[epub/adapters/tmpfs.ts:198](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/tmpfs.ts#L198)
+Always called on close or error
+##### Returns
+`void`
+##### Implementation of
+[`EpubStorageAdapter`](#epubstorageadapter).[`dispose`](#dispose-6)
+#### duplicate()
+> **duplicate**(): `Promise`\<[`TmpFsAdapter`](#tmpfsadapter)\>
+Defined in:
+[epub/adapters/tmpfs.ts:149](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/tmpfs.ts#L149)
+Required for Epub.copy
+##### Returns
+`Promise`\<[`TmpFsAdapter`](#tmpfsadapter)\>
+##### Implementation of
+[`EpubStorageAdapter`](#epubstorageadapter).[`duplicate`](#duplicate-2)
+#### list()
+> **list**(): `AsyncIterable`\<[`EpubListEntry`](#epublistentry)\>
+Defined in:
+[epub/adapters/tmpfs.ts:134](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/tmpfs.ts#L134)
+Required for Epub.saveAndClose to walk the contents
+##### Returns
+`AsyncIterable`\<[`EpubListEntry`](#epublistentry)\>
+##### Implementation of
+[`EpubStorageAdapter`](#epubstorageadapter).[`list`](#list-2)
+#### read()
+##### Call Signature
+> **read**(`path`): `Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\>
+Defined in:
+[epub/adapters/tmpfs.ts:104](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/tmpfs.ts#L104)
+###### Parameters
+| Parameter | Type     |
+| --------- | -------- |
+| `path`    | `string` |
+###### Returns
+`Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\>
+###### Implementation of
+[`EpubStorageAdapter`](#epubstorageadapter).[`read`](#read-6)
+##### Call Signature
+> **read**(`path`, `encoding`): `Promise`\<`string`\>
+Defined in:
+[epub/adapters/tmpfs.ts:105](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/tmpfs.ts#L105)
+###### Parameters
+| Parameter  | Type      |
+| ---------- | --------- |
+| `path`     | `string`  |
+| `encoding` | `"utf-8"` |
+###### Returns
+`Promise`\<`string`\>
+###### Implementation of
+[`EpubStorageAdapter`](#epubstorageadapter).[`read`](#read-6)
+#### remove()
+> **remove**(`path`): `Promise`\<`void`\>
+Defined in:
+[epub/adapters/tmpfs.ts:121](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/tmpfs.ts#L121)
+Required for removeManifestItem / setCoverImage replacement
+##### Parameters
+| Parameter | Type     |
+| --------- | -------- |
+| `path`    | `string` |
+##### Returns
+`Promise`\<`void`\>
+##### Implementation of
+[`EpubStorageAdapter`](#epubstorageadapter).[`remove`](#remove-2)
+#### serialize()
+> **serialize**(`targetPath`): `Promise`\<`void`\>
+Defined in:
+[epub/adapters/tmpfs.ts:160](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/tmpfs.ts#L160)
+Required for Epub.saveAndClose
+##### Parameters
+| Parameter    | Type     |
+| ------------ | -------- |
+| `targetPath` | `string` |
+##### Returns
+`Promise`\<`void`\>
+##### Implementation of
+[`EpubStorageAdapter`](#epubstorageadapter).[`serialize`](#serialize-2)
+#### write()
+##### Call Signature
+> **write**(`path`, `data`): `Promise`\<`void`\>
+Defined in:
+[epub/adapters/tmpfs.ts:110](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/tmpfs.ts#L110)
+Required for any mutation method on Epub
+###### Parameters
+| Parameter | Type         |
+| --------- | ------------ |
+| `path`    | `string`     |
+| `data`    | `Uint8Array` |
+###### Returns
+`Promise`\<`void`\>
+###### Implementation of
+[`EpubStorageAdapter`](#epubstorageadapter).[`write`](#write-3)
+##### Call Signature
+> **write**(`path`, `data`, `encoding`): `Promise`\<`void`\>
+Defined in:
+[epub/adapters/tmpfs.ts:111](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/tmpfs.ts#L111)
+###### Parameters
+| Parameter  | Type      |
+| ---------- | --------- |
+| `path`     | `string`  |
+| `data`     | `string`  |
+| `encoding` | `"utf-8"` |
+###### Returns
+`Promise`\<`void`\>
+###### Implementation of
+[`EpubStorageAdapter`](#epubstorageadapter).[`write`](#write-3)
+#### init()
+> `static` **init**(`source`): `Promise`\<[`TmpFsAdapter`](#tmpfsadapter)\>
+Defined in:
+[epub/adapters/tmpfs.ts:63](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/tmpfs.ts#L63)
+##### Parameters
+| Parameter | Type                                          |
+| --------- | --------------------------------------------- |
+| `source`  | `string` \| `Uint8Array`\<`ArrayBufferLike`\> |
+##### Returns
+`Promise`\<[`TmpFsAdapter`](#tmpfsadapter)\>
+#### initEmpty()
+> `static` **initEmpty**(): `Promise`\<[`TmpFsAdapter`](#tmpfsadapter)\>
+Defined in:
+[epub/adapters/tmpfs.ts:96](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/tmpfs.ts#L96)
+##### Returns
+`Promise`\<[`TmpFsAdapter`](#tmpfsadapter)\>
+---
+## AlternateScript
+Defined in:
+[epub/index.ts:127](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L127)
 ### Properties
+#### locale
+> **locale**: `Locale`
+Defined in:
+[epub/index.ts:129](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L129)
 #### name
 > **name**: `string`
 Defined in:
-[epub/index.ts:135](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L135)
+[epub/index.ts:128](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L128)
+---
+## Collection
+Defined in:
+[epub/index.ts:151](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L151)
+### Properties
+#### name
+> **name**: `string`
+Defined in:
+[epub/index.ts:152](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L152)
 #### position?
 > `optional` **position**: `string`
 Defined in:
-[epub/index.ts:137](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L137)
+[epub/index.ts:154](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L154)
 #### type?
 > `optional` **type**: `string`
 Defined in:
-[epub/index.ts:136](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L136)
+[epub/index.ts:153](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L153)
 ---
 ## DcCreator
 Defined in:
-[epub/index.ts:115](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L115)
+[epub/index.ts:132](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L132)
 ### Properties
@@ -2647,42 +3739,42 @@ Defined in:
 > `optional` **alternateScripts**: [`AlternateScript`](#alternatescript)[]
 Defined in:
-[epub/index.ts:120](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L120)
+[epub/index.ts:137](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L137)
 #### fileAs?
 > `optional` **fileAs**: `string`
 Defined in:
-[epub/index.ts:119](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L119)
+[epub/index.ts:136](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L136)
 #### name
 > **name**: `string`
 Defined in:
-[epub/index.ts:116](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L116)
+[epub/index.ts:133](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L133)
 #### role?
 > `optional` **role**: `string`
 Defined in:
-[epub/index.ts:117](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L117)
+[epub/index.ts:134](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L134)
 #### roleScheme?
 > `optional` **roleScheme**: `string`
 Defined in:
-[epub/index.ts:118](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L118)
+[epub/index.ts:135](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L135)
 ---
 ## DcSubject
 Defined in:
-[epub/index.ts:104](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L104)
+[epub/index.ts:121](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L121)
 ### Properties
@@ -2691,28 +3783,28 @@ Defined in:
 > **authority**: `string`
 Defined in:
-[epub/index.ts:106](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L106)
+[epub/index.ts:123](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L123)
 #### term
 > **term**: `string`
 Defined in:
-[epub/index.ts:107](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L107)
+[epub/index.ts:124](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L124)
 #### value
 > **value**: `string`
 Defined in:
-[epub/index.ts:105](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L105)
+[epub/index.ts:122](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L122)
 ---
 ## DublinCore
 Defined in:
-[epub/index.ts:123](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L123)
+[epub/index.ts:140](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L140)
 ### Properties
@@ -2721,56 +3813,56 @@ Defined in:
 > `optional` **contributors**: [`DcCreator`](#dccreator)[]
 Defined in:
-[epub/index.ts:130](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L130)
+[epub/index.ts:147](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L147)
 #### creators?
 > `optional` **creators**: [`DcCreator`](#dccreator)[]
 Defined in:
-[epub/index.ts:129](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L129)
+[epub/index.ts:146](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L146)
 #### date?
 > `optional` **date**: `Date`
 Defined in:
-[epub/index.ts:127](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L127)
+[epub/index.ts:144](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L144)
 #### identifier
 > **identifier**: `string`
 Defined in:
-[epub/index.ts:126](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L126)
+[epub/index.ts:143](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L143)
 #### language
 > **language**: `Locale`
 Defined in:
-[epub/index.ts:125](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L125)
+[epub/index.ts:142](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L142)
 #### subjects?
 > `optional` **subjects**: (`string` \| [`DcSubject`](#dcsubject))[]
 Defined in:
-[epub/index.ts:128](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L128)
+[epub/index.ts:145](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L145)
 #### title
 > **title**: `string`
 Defined in:
-[epub/index.ts:124](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L124)
+[epub/index.ts:141](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L141)
 #### type?
 > `optional` **type**: `string`
 Defined in:
-[epub/index.ts:131](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L131)
+[epub/index.ts:148](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L148)
 ---
@@ -2802,279 +3894,394 @@ Whether to remove the NCX file, as it's technically optional in EPUB 3.
 ---
-## Landmark
+## EpubListEntry
 Defined in:
-[epub/upgrade.ts:87](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/upgrade.ts#L87)
+[epub/adapters/interface.ts:17](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/interface.ts#L17)
 ### Properties
-#### href
+#### absolutePath
-> **href**: `string`
+> **absolutePath**: `string`
 Defined in:
-[epub/upgrade.ts:88](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/upgrade.ts#L88)
-#### title
-> **title**: `string`
+[epub/adapters/interface.ts:19](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/interface.ts#L19)
-Defined in:
-[epub/upgrade.ts:89](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/upgrade.ts#L89)
+absolute path under [EpubStorageAdapter.rootPath](#rootpath-2)
-#### type
+#### relativePath
-> **type**: `string`
+> **relativePath**: `string`
 Defined in:
-[epub/upgrade.ts:90](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/upgrade.ts#L90)
+[epub/adapters/interface.ts:21](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/interface.ts#L21)
+path relative to [EpubStorageAdapter.rootPath](#rootpath-2), slash-separated
 ---
-## Navigation
+## EpubStorageAdapter
 Defined in:
-[epub/index.ts:148](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L148)
+[epub/adapters/interface.ts:24](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/interface.ts#L24)
 ### Properties
-#### children
+#### rootPath
-> **children**: [`NavigationList`](#navigationlist)
+> `readonly` **rootPath**: `string`
 Defined in:
-[epub/index.ts:150](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L150)
+[epub/adapters/interface.ts:30](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/interface.ts#L30)
-#### title?
+Opaque path prefix used by `resolveInternalHref` to anchor absolute paths within
+the archive. For TmpFsAdapter this is the tmp dir; for MemoryAdapter it's a
+virtual prefix that's never written to disk
-> `optional` **title**: `string`
+### Methods
+#### archiveLength()
+> **archiveLength**(`path`): `Promise`\<`number`\>
 Defined in:
-[epub/index.ts:149](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L149)
+[epub/adapters/interface.ts:39](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/interface.ts#L39)
----
+Length of an entry in bytes, for the readium page-count heuristic which expects
+compressed size when available
-## NavigationItem
+##### Parameters
-Defined in:
-[epub/index.ts:140](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L140)
+| Parameter | Type     |
+| --------- | -------- |
+| `path`    | `string` |
-### Properties
+##### Returns
+`Promise`\<`number`\>
-#### children?
+#### dispose()
-> `optional` **children**: [`NavigationList`](#navigationlist)
+> **dispose**(): `void` \| `Promise`\<`void`\>
 Defined in:
-[epub/index.ts:143](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L143)
+[epub/adapters/interface.ts:58](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/interface.ts#L58)
-#### href?
+Always called on close or error
-> `optional` **href**: `string`
+##### Returns
-Defined in:
-[epub/index.ts:142](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L142)
+`void` \| `Promise`\<`void`\>
-#### title
+#### duplicate()?
-> **title**: `string`
+> `optional` **duplicate**():
+> `Promise`\<[`EpubStorageAdapter`](#epubstorageadapter)\>
 Defined in:
-[epub/index.ts:141](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L141)
+[epub/adapters/interface.ts:52](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/interface.ts#L52)
----
+Required for Epub.copy
-## ElementName
+##### Returns
+`Promise`\<[`EpubStorageAdapter`](#epubstorageadapter)\>
-> **ElementName** =
-> \`$\{Letter \| Uppercase\<Letter\> \| QuestionMark\}$\{string\}\`
+#### list()?
+> `optional` **list**(): `AsyncIterable`\<[`EpubListEntry`](#epublistentry)\>
 Defined in:
-[epub/index.ts:65](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L65)
+[epub/adapters/interface.ts:49](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/interface.ts#L49)
-A valid name for an XML element (must start with a letter)
+Required for Epub.saveAndClose to walk the contents
----
+##### Returns
+`AsyncIterable`\<[`EpubListEntry`](#epublistentry)\>
-## EpubMetadata
+#### read()
+##### Call Signature
-> **EpubMetadata** = [`MetadataEntry`](#metadataentry)[]
+> **read**(`path`): `Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\>
 Defined in:
-[epub/index.ts:102](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L102)
+[epub/adapters/interface.ts:32](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/interface.ts#L32)
----
+###### Parameters
+| Parameter | Type     |
+| --------- | -------- |
+| `path`    | `string` |
+###### Returns
+`Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\>
-## ManifestItem
+##### Call Signature
-> **ManifestItem** = `object`
+> **read**(`path`, `encoding`): `Promise`\<`string`\>
 Defined in:
-[epub/index.ts:86](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L86)
+[epub/adapters/interface.ts:33](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/interface.ts#L33)
-### Properties
+###### Parameters
-#### fallback?
+| Parameter  | Type      |
+| ---------- | --------- |
+| `path`     | `string`  |
+| `encoding` | `"utf-8"` |
-> `optional` **fallback**: `string`
+###### Returns
-Defined in:
-[epub/index.ts:90](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L90)
+`Promise`\<`string`\>
-#### href
+#### remove()?
-> **href**: `string`
+> `optional` **remove**(`path`): `Promise`\<`void`\>
 Defined in:
-[epub/index.ts:88](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L88)
+[epub/adapters/interface.ts:46](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/interface.ts#L46)
-#### id
+Required for removeManifestItem / setCoverImage replacement
-> **id**: `string`
+##### Parameters
-Defined in:
-[epub/index.ts:87](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L87)
+| Parameter | Type     |
+| --------- | -------- |
+| `path`    | `string` |
+##### Returns
+`Promise`\<`void`\>
-#### mediaOverlay?
+#### serialize()?
-> `optional` **mediaOverlay**: `string`
+> `optional` **serialize**(`targetPath`): `Promise`\<`void`\>
 Defined in:
-[epub/index.ts:91](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L91)
+[epub/adapters/interface.ts:55](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/interface.ts#L55)
+Required for Epub.saveAndClose
+##### Parameters
+| Parameter    | Type     |
+| ------------ | -------- |
+| `targetPath` | `string` |
+##### Returns
+`Promise`\<`void`\>
+#### write()?
-#### mediaType?
+##### Call Signature
-> `optional` **mediaType**: `string`
+> `optional` **write**(`path`, `data`): `Promise`\<`void`\>
 Defined in:
-[epub/index.ts:89](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L89)
+[epub/adapters/interface.ts:42](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/interface.ts#L42)
+Required for any mutation method on Epub
+###### Parameters
+| Parameter | Type         |
+| --------- | ------------ |
+| `path`    | `string`     |
+| `data`    | `Uint8Array` |
-#### properties?
+###### Returns
+`Promise`\<`void`\>
+##### Call Signature
-> `optional` **properties**: `string`[]
+> `optional` **write**(`path`, `data`, `encoding`): `Promise`\<`void`\>
 Defined in:
-[epub/index.ts:92](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L92)
+[epub/adapters/interface.ts:43](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/interface.ts#L43)
----
+###### Parameters
+| Parameter  | Type      |
+| ---------- | --------- |
+| `path`     | `string`  |
+| `data`     | `string`  |
+| `encoding` | `"utf-8"` |
-## MetadataEntry
+###### Returns
+`Promise`\<`void`\>
+---
-> **MetadataEntry** = `object`
+## EpubStorageAdapterClass\<Opts\>
 Defined in:
-[epub/index.ts:95](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L95)
+[epub/adapters/interface.ts:61](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/interface.ts#L61)
+### Type Parameters
+| Type Parameter            | Default type |
+| ------------------------- | ------------ |
+| `Opts` _extends_ `object` | `object`     |
 ### Properties
-#### id?
+#### capabilities
-> `optional` **id**: `string`
+> `readonly` **capabilities**:
+> [`EpubStorageCapabilities`](#epubstoragecapabilities)
 Defined in:
-[epub/index.ts:96](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L96)
+[epub/adapters/interface.ts:63](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/interface.ts#L63)
-#### properties
+#### kind
-> **properties**: `Record`\<`string`, `string`\>
+> `readonly` **kind**: [`EpubStorageKind`](#epubstoragekind)
 Defined in:
-[epub/index.ts:98](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L98)
+[epub/adapters/interface.ts:62](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/interface.ts#L62)
-#### type
+### Methods
-> **type**: [`ElementName`](#elementname)
+#### init()
+> **init**(`source`, `opts?`):
+> `Promise`\<[`EpubStorageAdapter`](#epubstorageadapter)\>
 Defined in:
-[epub/index.ts:97](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L97)
+[epub/adapters/interface.ts:70](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/interface.ts#L70)
-#### value
+Open an archive from a path or buffer. The returned adapter is ready to read;
+the Epub class will assert it's a valid EPUB 3 afterwards.
-> **value**: `string` \| `undefined`
+##### Parameters
-Defined in:
-[epub/index.ts:99](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L99)
+| Parameter | Type                                          |
+| --------- | --------------------------------------------- |
+| `source`  | `string` \| `Uint8Array`\<`ArrayBufferLike`\> |
+| `opts?`   | `Opts`                                        |
----
+##### Returns
-## NavigationList
+`Promise`\<[`EpubStorageAdapter`](#epubstorageadapter)\>
-> **NavigationList** = [`NavigationItem`](#navigationitem)[]
+#### initEmpty()?
+> `optional` **initEmpty**(`opts?`):
+> `Promise`\<[`EpubStorageAdapter`](#epubstorageadapter)\>
 Defined in:
-[epub/index.ts:146](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L146)
+[epub/adapters/interface.ts:79](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/interface.ts#L79)
----
+Initialize an empty extract root for [Epub.create](#create).
-## PackageElement
+Optional — adapters that can't be written to from scratch (e.g. read-only zip
+handles) should leave this off, and `Epub.using(...).create(...)` will throw.
-> **PackageElement** = [`XmlElement`](#xmlelement)\<`"package"`\>
+##### Parameters
-Defined in:
-[epub/index.ts:159](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L159)
+| Parameter | Type   |
+| --------- | ------ |
+| `opts?`   | `Opts` |
+##### Returns
+`Promise`\<[`EpubStorageAdapter`](#epubstorageadapter)\>
 ---
-## ParsedXml
+## EpubStorageCapabilities
+Defined in:
+[epub/adapters/interface.ts:12](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/interface.ts#L12)
+### Properties
+#### writable
-> **ParsedXml** = [`XmlNode`](#xmlnode)[]
+> `readonly` **writable**: `boolean`
 Defined in:
-[epub/index.ts:84](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L84)
+[epub/adapters/interface.ts:14](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/interface.ts#L14)
-An XML structure
+when false, the Epub class refuses every mutation method at runtime
 ---
-## XmlElement\<Name\>
-> **XmlElement**\<`Name`\> = `object` & `{ [key in Name]: ParsedXml }`
+## FromOptions
 Defined in:
-[epub/index.ts:71](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L71)
+[epub/index.ts:178](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L178)
+### Properties
-An XML element
+#### readonly?
-### Type Declaration
+> `optional` **readonly**: `boolean`
-#### :@?
+Defined in:
+[epub/index.ts:183](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L183)
-> `optional` **:@**: `Record`\<`` `${PropertyPrefix}${string}` ``, `string`\>
+when true, mutation methods throw [EpubReadOnlyError](#epubreadonlyerror) at
+runtime
-### Type Parameters
+##### Default
-| Type Parameter                                 | Default type                  |
-| ---------------------------------------------- | ----------------------------- |
-| `Name` _extends_ [`ElementName`](#elementname) | [`ElementName`](#elementname) |
+```ts
+false
+```
 ---
-## XmlNode
+## Landmark
+Defined in:
+[epub/upgrade.ts:87](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/upgrade.ts#L87)
+### Properties
+#### href
-> **XmlNode** = [`XmlElement`](#xmlelement) \| [`XmlTextNode`](#xmltextnode)
+> **href**: `string`
 Defined in:
-[epub/index.ts:81](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L81)
+[epub/upgrade.ts:88](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/upgrade.ts#L88)
-A valid XML node. May be either an element or a text node.
+#### title
----
+> **title**: `string`
+Defined in:
+[epub/upgrade.ts:89](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/upgrade.ts#L89)
-## XmlTextNode
+#### type
-> **XmlTextNode** = `object`
+> **type**: `string`
 Defined in:
-[epub/index.ts:78](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L78)
+[epub/upgrade.ts:90](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/upgrade.ts#L90)
+---
+## MemoryAdapterOptions
-A text node in an XML document
+Defined in:
+[epub/adapters/memory.ts:15](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/memory.ts#L15)
 ### Properties
-#### #text
+#### cache?
-> **#text**: `string`
+> `optional` **cache**: `boolean`
 Defined in:
-[epub/index.ts:78](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/index.ts#L78)
+[epub/adapters/memory.ts:22](https://gitlab.com/storyteller-platform/storyteller/-/blob/main/epub/adapters/memory.ts#L22)
+per-entry decompressed buffer cache turn it off when opening many EPUBs and
+reading eac