epub-codec 1.2.12 → 1.3.0

package/README.md

@@ -87,6 +87,17 @@ const bytes2 = z.encode(epubCodec, tree);
 
 This is the no-extra-options form only — `readEpub(Content)`/`writeEpub(Content)` remain the entry points for a diagnostic sink.
 
+The lossless byte-level `Package` (ExaDev/documents.js#963), for a caller that wants a genuine EPUB-to-EPUB round trip with no `ContentDocument`/`DocumentTree` projection in between — `readEpub(Content)`/`writeEpubContent` already cross this exact boundary internally, so reaching for it directly is for a caller inspecting or editing raw parts, not a prerequisite for ordinary reading/writing:
+
+```ts
+import { decodePackage, encodePackage } from "epub-codec";
+
+const pkg = decodePackage(epubBytes); // -> { parts: Record<string, Part> }, every zip entry as XML nodes or base64 bytes
+const bytes2 = encodePackage(pkg); // decode -> encode is a fixed point: bytes2 carries the identical part content
+```
+
+Unlike `ooxml.js`/`odf.js`, neither of which offers a one-shot bytes-in convenience at all (their own typed readers take an already-decoded `Package`, e.g. `readDocx(decodePackage(bytes))`), `readEpub(Content)`/`writeEpub(Content)` above stay this package's own established bytes-in/bytes-out API — `decodePackage`/`encodePackage` are additive, not a replacement for it.
+
 One spine itemref becomes one `ContentSection`, in spine order — **every** itemref, including one marked `linear="no"` (an EPUB 2 idiom for supplementary content, most often a footnote/endnote page): this package reads it as an ordinary section rather than silently skipping real content a reading system happens to route around. EPUB has no page concept of its own, so every section is given the same invented A4 + 1in default geometry (`ReadEpubOptions`/`WriteEpubOptions` carry no override for this, unlike `markdown-codec`'s `pageSize`/`margins` options — nothing in this package's own scope needs one yet).
 
 ## Architecture
@@ -94,17 +105,18 @@ One spine itemref becomes one `ContentSection`, in spine order — **every** ite
 Layered from the lossless OCF/XML primitives outward to the XHTML-to-`ContentDocument` mapping itself:
 
 - **`src/zip.ts`** — the OCF ZIP container: fixed-mtime, ordered-entries `zipPackage`/`unzipPackage` over `fflate`, hand-duplicated from `ooxml.js`'s and `odf.js`'s own identical wrappers rather than depending on `archive-codec` — see [Dependency choices](#dependency-choices).
-- **`src/xml/`** — the lossless XML layer every other module in this package builds on: `parse.ts`/`build.ts` wrap `fast-xml-parser` with the identical `preserveOrder` configuration `ooxml.js`'s and `odf.js`'s own XML modules use (order and mixed content survive; entity encoding stays raw until `entities.ts` decodes it in the one place text actually becomes content), `query.ts` the same handful of tree-walking helpers (`rootElement`, `findChildElement`, `childrenWithTag`, `elementsWithTag`, `attrValue`, plus `findElement` and `textContent`, needed here for footnote-target and nav-toc resolution respectively).
+- **`src/xml/`** — the lossless XML layer every other module in this package builds on: `parse.ts`/`build.ts` wrap `fast-xml-parser` with the identical `preserveOrder` configuration `ooxml.js`'s and `odf.js`'s own XML modules use (order and mixed content survive; entity encoding stays raw until `entities.ts` decodes it in the one place text actually becomes content), `query.ts` the same handful of tree-walking helpers (`rootElement`, `findChildElement`, `childrenWithTag`, `elementsWithTag`, `attrValue`, plus `findElement` and `textContent`, needed here for footnote-target and nav-toc resolution respectively), `node.ts` the ordered `XmlNode` forest itself — also the shape `src/model/package.ts`'s own `XmlPart` carries.
+- **`src/model/package.ts`/`src/package-io/`** — the lossless byte-level `Package` model (ExaDev/documents.js#963), mirroring `ooxml.js`'s and `odf.js`'s own `model/package.ts`/`package-io/` exactly: every zip entry as a `Part` (an `XmlNode[]` forest, or raw base64 bytes), `read.ts`'s `parsePackage`/`packageFromEntries` classifying entries into parts, `write.ts`'s `serializePackage`/`packageToEntries` the structural inverse (including the OCF mimetype-first-stored hoist). `src/codec.ts` wraps the pair as `decodePackage`/`encodePackage`; `src/read.ts`/`src/write.ts` cross this same boundary internally rather than talking to `src/zip.ts` directly.
 - **`src/ocf/`** — `container.ts` resolves the OPF rootfile from `META-INF/container.xml` (EPUB 3.3 §6.7.2); `write.ts` is its structural inverse.
 - **`src/opf/`** — `parse.ts`/`write.ts` read and write the OPF package document (§5.4): Dublin Core metadata (`metadata.ts`), the manifest, and the spine.
 - **`src/nav/`** — `nav3.ts`/`ncx.ts` reduce the EPUB 3 `<nav epub:type="toc">` document and the EPUB 2 NCX to a flat, fragment-stripped href sequence each; `reconcile.ts` compares that sequence against the spine's own reading order (the issue's own explicit "the spine wins" decision); `write.ts` builds a minimal EPUB 3 nav document, one entry per section, titled from each section's own first heading.
-- **`src/xhtml/`** — the mapping this package exists for: `read.ts` (`readXhtmlBody`, one XHTML content document's `<body>` to `ContentBlock[]`), `write.ts` (`writeXhtmlBody`, its structural inverse, built on `document-schema.js`'s own `decomposeSection` rather than re-deriving heading/list/construct nesting by hand), `inline.ts` (run-level formatting and footnote reference extents), `footnote.ts` (EPUB 3 `epub:type="noteref"`/`"footnote"` and the EPUB 2 linked-anchor idiom, both mapped onto the identical `anchor` construct), `list-id.ts` (list marker type packed into the opaque `numId`, mirroring `markdown-codec`'s own mechanism for the identical schema gap), `context.ts`/`style-constants.ts` (shared read-side plumbing and round-trip-only styleId/font constants).
+- **`src/xhtml/`** — the mapping this package exists for: `read.ts` (`readXhtmlBody`, one XHTML content document's `<body>` to `ContentBlock[]`), `write.ts` (`writeXhtmlBody`, its structural inverse, built on `document-schema.js`'s own `decomposeSection` rather than re-deriving heading/list/construct nesting by hand), `inline.ts` (run-level formatting, footnote reference extents, and internal-link extents), `footnote.ts` (EPUB 3 `epub:type="noteref"`/`"footnote"` and the EPUB 2 linked-anchor idiom, both mapped onto the identical `anchor` construct), `link-target.ts` (`resolveHrefTarget`, the same-/cross-document href-to-element resolver `src/read.ts`'s own whole-spine internal-link registry and `inline.ts`'s reference-side lookup both build on — ExaDev/documents.js#963), `list-id.ts` (list marker type packed into the opaque `numId`, mirroring `markdown-codec`'s own mechanism for the identical schema gap), `context.ts`/`style-constants.ts` (shared read-side plumbing and round-trip-only styleId/font constants).
 - **`src/image/dimensions.ts`** — PNG/JPEG format detection and pixel dimensions, hand-written rather than reused from `byte-codec` — see [Dependency choices](#dependency-choices).
 - **`src/util/base64.ts`** — isomorphic base64 codec, a third hand-written copy of the identical helper `odf.js`'s and `pdf-codec`'s own `src/util/base64.ts` already carry.
 - **`src/path.ts`** — package-relative path resolution (manifest hrefs against the OPF's own directory, `<img src>` against its own XHTML document's directory), honouring `../` segments.
 - **`src/diagnostics.ts`** — the three-tier read/write failure policy; see [Conventions](#conventions).
-- **`src/read.ts`/`src/write.ts`** — the public entry points, composing every layer above into `readEpub(Content)`/`writeEpub(Content)`.
-- **`src/codec.ts`** — `epubCodec`/`epubContentCodec`, the `z.codec()` pair.
+- **`src/read.ts`/`src/write.ts`** — the public entry points, composing every layer above into `readEpub(Content)`/`writeEpub(Content)`, `decodePackage`/`encodePackage` first/last.
+- **`src/codec.ts`** — `epubCodec`/`epubContentCodec` (the `ContentDocument`/`DocumentTree` round trip) and `packageCodec`/`decodePackage`/`encodePackage` (the lossless `Package` round trip), each a `z.codec()` pair.
 
 ## Dependency choices
 
@@ -127,8 +139,8 @@ The issue that created this package ([ExaDev/documents.js#801](https://github.co
 Every construct this package's XHTML mapping cannot represent losslessly is a documented `EpubDiagnosticCodes` entry — see `src/diagnostics.ts` for the full table, and each module's own top-of-file comment for which side (read/write) it belongs to:
 
 - **`epub/element-unmapped`** — `<sub>`/`<sup>` degrade to plain text: `document-schema.js`'s `ContentRun` carries no subscript/superscript field at all, a genuine family-wide schema gap (no sibling codec has ever needed one; `ooxml.js`'s own docx reader has no `w:vertAlign` handling either), not something specific to this package.
-- **`epub/link-target-external-only`** — every href, external or same-/cross-document, rides `ContentRun.hyperlink` verbatim rather than building the full internal-target `link` construct bookkeeping `document-schema.js`'s own vocabulary supports (an internal link construct needs a resolved same-document `anchor` target this package does not build for ordinary hyperlinks, only for recognised footnote references — see below). A deliberate scope decision: every href still restores byte-for-byte either way, and the feature this degrades is real semantic internal-navigation fidelity, not content loss.
-- **Footnotes are same-document only.** Both the EPUB 3 structured idiom (`epub:type="noteref"`/`"footnote"`) and the EPUB 2 linked-anchor idiom (a `class="footnote"`/`"noteref"` convention with no `epub:type` vocabulary at all, recognised by `src/xhtml/footnote.ts`) map onto the identical `anchor` construct — a run-level point extent at the reference site, a `constructStart`/blocks/`constructEnd` triple around the body. Recognition never crosses a spine itemref boundary: `document-schema.js`'s own construct-marker contract states a bracket pair can never straddle a block list boundary, and each `ContentSection` is its own block list, so a cross-document footnote (a separate "notes.xhtml", the more common real-world EPUB 2 shape) falls through to the ordinary internal-hyperlink handling above instead of being force-fit into a shape the schema cannot express.
+- **Internal-link semantics** (ExaDev/documents.js#963) — a same-document fragment href, or a cross-document href naming another spine document's own id, that resolves to a real, block-level element anywhere in the spine builds `document-schema.js`'s own internal-target `link` construct (a run-level extent, `target: { kind: "internal", anchor }`) rather than riding `ContentRun.hyperlink` as a plain string; the target element itself is wrapped in its own `anchor` construct (`anchorType: "bookmark"`) so the two ends of the link are both addressable. A cross-document target's own name is qualified with its owning document's own path (`"OEBPS/chapter2.xhtml#sec2"`, never a bare `"sec2"`) precisely because two different target documents can otherwise legitimately reuse the identical id; a same-document target keeps the bare fragment. `src/write.ts`'s own whole-document anchor-section index resolves a reference back to either a same-file `"#name"` href or a cross-file `"sectionN.xhtml#name"` one on write, so this round-trips through a same-format write. `epub/link-target-external-only` remains the diagnostic for what's left: an href genuinely external (a URI scheme), or an internal-looking href this package cannot resolve to a real element at all (a nonexistent fragment, or one with no fragment naming only a whole document) — that still rides `ContentRun.hyperlink` verbatim, restoring byte-for-byte either way.
+- **Footnotes recognise a cross-document body** (ExaDev/documents.js#963). Both the EPUB 3 structured idiom (`epub:type="noteref"`/`"footnote"`) and the EPUB 2 linked-anchor idiom (a `class="footnote"`/`"noteref"` convention with no `epub:type` vocabulary at all, recognised by `src/xhtml/footnote.ts`'s `isFootnoteReference`) map onto the identical `anchor` construct — a run-level point extent at the reference site, a `constructStart`/blocks/`constructEnd` triple around the body. A reference and its own body need not live in the same spine document: `document-schema.js`'s own construct-marker contract still forbids a single bracket pair from straddling a block-list boundary (each `ContentSection` is its own block list), but this was never that — the reference's own point extent and the body's own `constructStart`/`constructEnd` pair are two independently well-formed markers in two different sections, connected only by sharing one `name`. `src/read.ts`'s own whole-spine pass resolves every href (same- and cross-document) before any section is read, so a cross-document footnote (a separate "notes.xhtml", the more common real-world EPUB 2 shape) is recognised and linked exactly like a same-document one; a cross-document name is qualified with its owning document's own path (`"OEBPS/notes.xhtml#note1"`) to keep it distinct from a same-named footnote in a different document, and `src/write.ts`'s own whole-document anchor-section index resolves the reference back to a working same-file or cross-file href on every write.
 - **`epub/style-residue`** — a document's own `<head>` style declarations (`<link rel="stylesheet">`, `<style>`) are quarantined verbatim as `SourceResidue` on the owning `ContentSection`, never interpreted: CSS is residue, not content. `writeEpubContent` re-emits it into the written `<head>` on a same-format write (this family's standard restorable-fidelity re-emission contract).
 - **An empty or whitespace-only paragraph (`<p></p>`, `<p> </p>`, or bare whitespace text between two block-level siblings — the common case in any pretty-printed real EPUB) is dropped entirely on read**, matching the same "anonymous block box" rule a browser's own HTML block-formatting context already applies to inter-block whitespace, rather than becoming a bogus empty `ContentParagraph`.
 - **List marker type (bullet vs. ordered, and an `<ol>`'s own non-default `start`) is packed into the opaque `numId`** (`epub{N}:{bullet|ordered}[@{start}]`, `src/xhtml/list-id.ts`), since `ContentListMembership` carries no field of its own for it — the identical mechanism `markdown-codec`'s own `src/shared/list-id.ts` uses for its GFM bullet/ordered distinction, hand-mirrored rather than shared. A numId outside this grammar (odf.js's bare `"list1"`, markdown-codec's own `"md1:bullet"`) is read back as an ordinary bullet list with no declared start.
@@ -145,11 +157,13 @@ Every construct this package's XHTML mapping cannot represent losslessly is a do
 
 ## Fidelity
 
-**Semantic fidelity** — headings, paragraphs, lists (nested, bullet/ordered), definition lists, tables, images, hyperlinks, text styling (bold/italic/underline/strike/monospace), blockquotes, pre/code blocks, horizontal rules, figure/figcaption, and footnotes (both EPUB 2 and EPUB 3 idioms) all survive as first-class `document-schema.js` nodes or constructs — see [ExaDev/documents.js#801](https://github.com/ExaDev/documents.js/issues/801) for the full acceptance list this package was built against, and `src/roundtrip.test.ts` for the real end-to-end proof (a hand-built `ContentDocument` covering nearly all of it, written to a genuine EPUB 3 zip and read back unchanged).
+**Semantic fidelity** — headings, paragraphs, lists (nested, bullet/ordered), definition lists, tables, images, hyperlinks (external and internal, same- or cross-document — ExaDev/documents.js#963), text styling (bold/italic/underline/strike/monospace), blockquotes, pre/code blocks, horizontal rules, figure/figcaption, and footnotes (both EPUB 2 and EPUB 3 idioms, same- or cross-document — ExaDev/documents.js#963) all survive as first-class `document-schema.js` nodes or constructs — see [ExaDev/documents.js#801](https://github.com/ExaDev/documents.js/issues/801) for the full acceptance list this package was built against, and `src/roundtrip.test.ts` for the real end-to-end proof (a hand-built `ContentDocument` covering nearly all of it, written to a genuine EPUB 3 zip and read back unchanged).
+
+**Restorable fidelity** — a same-format (EPUB-to-EPUB) round trip re-emits quarantined CSS residue verbatim, and re-resolves an internal link/bookmark or footnote reference/body pair to a working same-file or cross-file href on every write (ExaDev/documents.js#963); the one remaining documented gap above (sub/sup styling) is a permanent, structural limit rather than a restorable one, since the source construct itself has nowhere in the schema to ride.
 
-**Restorable fidelity** — a same-format (EPUB-to-EPUB) round trip re-emits quarantined CSS residue verbatim; every other documented gap above (sub/sup styling, internal-link semantics, cross-document footnotes) is a permanent, structural limit rather than a restorable one, since the source construct itself has nowhere in the schema to ride.
+**Byte fidelity, at the Package level** (ExaDev/documents.js#963). This package now has the same lossless byte-level `Package` model `ooxml.js`/`odf.js` do — a `decodePackage`/`encodePackage` pair, mirroring theirs exactly, that reads every OCF zip entry into a generic `Part` (an XML entry as an ordered `XmlNode[]` forest, anything else as raw base64 bytes) and writes it straight back, with no EPUB-specific interpretation in between. `decodePackage(bytes) |> encodePackage` is a genuine fixed point: `src/package-round-trip.test.ts` pins `decode -> encode -> decode` idempotence, per-part content preservation (an XML part's own entities/structure, a binary part's own bytes verbatim), and the one deliberate departure from a generic zip-of-XML writer this format shares with ODF's identical requirement — the `mimetype` part hoisted first and stored uncompressed (EPUB 3.3 §6.3), regardless of the input zip's own entry order, and never fabricated if the input never carried one. `readEpub(Content)`/`writeEpubContent` cross this identical boundary internally (`decodePackage` first, `encodePackage` last) rather than talking to the zip layer directly, so the two are the same lossless core, not two independent implementations that happen to agree.
 
-**Not byte fidelity.** This package has no lossless byte-level `Package` model the way `ooxml.js`/`odf.js` do — there is no `decodePackage`/`encodePackage` pair, and a read-then-write round trip never reproduces the original bytes (a fresh `dc:identifier` is minted on every write, per this package's own explicit write scope). What _is_ deterministic: two writes of the _same_ `ContentDocument` produce byte-identical zip _layout_ (mimetype-first, stored, ordered entries, fixed mtimes) even though the OPF entry's own compressed bytes differ (the fresh identifier). `src/roundtrip.test.ts` pins the layout invariant directly rather than claiming full byte determinism.
+**Not byte fidelity at the ContentDocument level.** The `ContentDocument`/`DocumentTree` mapping stays a lossy projection on top of that lossless core — the same "lossless core vs. lossy views" boundary `ooxml.js`'s own README states for its identical `decodePackage`/`readDocx` split: `writeEpubContent` always builds a _fresh_ `EpubPackage` from the content it's given rather than touching one `readEpubContent` might have decoded, so a read-then-write round trip through the content level never reproduces the original bytes (a fresh `dc:identifier` is minted on every write, per this package's own explicit write scope, among other differences a lossy projection can't avoid). What _is_ deterministic at this level: two writes of the _same_ `ContentDocument` produce byte-identical zip _layout_ (mimetype-first, stored, ordered entries, fixed mtimes) even though the OPF entry's own compressed bytes differ (the fresh identifier). `src/roundtrip.test.ts` pins the layout invariant directly rather than claiming full byte determinism at this level.
 
 ## Build, test, and lint
 
@@ -177,7 +191,7 @@ Conventional Commits, enforced workspace-wide by commitlint through a root `comm
 
 - [document-schema.js](../document-schema.js/README.md) — the canonical `ContentDocument`/`DocumentTree` schema and the `decompose`/`flattenTree`/`assembleTree` transform this package's writer is built on.
 - [markdown-codec](../markdown-codec/README.md) — the closest architectural relative: hand-written, AST-to-`ContentDocument` lowering, the identical dual-level (`DocumentTree`/`ContentDocument`) API, the identical three-tier diagnostic policy, and the identical list-`numId`-packing mechanism for the identical schema gap.
-- [ooxml.js](../ooxml.js/README.md) / [odf.js](../odf.js/README.md) — the OCF/ZIP and lossless-XML-layer conventions this package's own `src/zip.ts`/`src/xml/` mirror.
+- [ooxml.js](../ooxml.js/README.md) / [odf.js](../odf.js/README.md) — the OCF/ZIP, lossless-XML-layer, and byte-level `Package` model (`decodePackage`/`encodePackage`, ExaDev/documents.js#963) conventions this package's own `src/zip.ts`/`src/xml/`/`src/model/package.ts`/`src/package-io/` mirror; `odf.js`'s in particular, since ODF shares EPUB's identical OCF mimetype-first-stored requirement.
 - [archive-codec](../archive-codec/README.md) — the ZIP-in-ZIP/CFB utility package this package deliberately does not depend on; see [Dependency choices](#dependency-choices).
 - [byte-codec](../byte-codec/README.md) — the byte/image utility package this package deliberately does not depend on for image dimensions; see [Dependency choices](#dependency-choices).
 - [EPUB 3.3](https://www.w3.org/TR/epub-33/) — the current W3C Recommendation this package's own EPUB 3 reading and writing targets.

package/dist/base64--HuymRl_.d.cts

@@ -0,0 +1,5 @@
+//#region src/util/base64.d.ts
+declare function bytesToBase64(bytes: Uint8Array<ArrayBuffer>): string;
+declare function base64ToBytes(b64: string): Uint8Array<ArrayBuffer>;
+//#endregion
+export { bytesToBase64 as n, base64ToBytes as t };

package/dist/base64--HuymRl_.d.ts

@@ -0,0 +1,5 @@
+//#region src/util/base64.d.ts
+declare function bytesToBase64(bytes: Uint8Array<ArrayBuffer>): string;
+declare function base64ToBytes(b64: string): Uint8Array<ArrayBuffer>;
+//#endregion
+export { bytesToBase64 as n, base64ToBytes as t };

package/dist/build-B1UxbO20.d.cts

@@ -0,0 +1,5 @@
+import { d as XmlNode } from "./node-CJLSSs1k.cjs";
+//#region src/xml/build.d.ts
+declare function buildXml(nodes: XmlNode[]): string;
+//#endregion
+export { buildXml as t };

package/dist/build-BCUsHLYw.d.ts

@@ -0,0 +1,5 @@
+import { d as XmlNode } from "./node-CJLSSs1k.js";
+//#region src/xml/build.d.ts
+declare function buildXml(nodes: XmlNode[]): string;
+//#endregion
+export { buildXml as t };