EPUB Tools

EPUB Tools is a standalone, local-first EPUB 2/3 reader and publication workbench for the add·ideas Toolbox. Books are opened from a browser File; no upload, account, analytics, or server-side conversion is involved. Bounded UTF-8 HTML/XHTML, Markdown and plain text can also be adapted locally into an explicit one-chapter EPUB workspace.

Current capabilities

Opens strict ZIP-based EPUB containers and parses container.xml, OPF metadata, manifest, spine, EPUB 3 navigation documents, and EPUB 2 NCX navigation.
Adapts UTF-8 HTML/XHTML through a structural allowlist, a documented lightweight Markdown subset, or plain text into a deterministic one-chapter EPUB workspace; every adapter records its format loss in the validation view.
Shows named, determinate opening progress while the archive, package, navigation, and content documents are inspected.
Shows the real nested EPUB navigation tree (with spine fallback) and renders XHTML/HTML/SVG content in a sandboxed, script-free iframe. Internal chapter/fragment links are handled by trusted reader controls; external links remain inert. The reader follows the Toolbox light, dark, or system theme.
Resolves bounded packaged stylesheets, fonts, images, audio/video, SVG href/legacy xlink:href, and CSS URLs to temporary object URLs. CSS imports, active constructs, network URLs, and unresolved resources are removed or blocked by the iframe CSP.
Interprets package/document direction, page progression, and rendition layout/orientation/spread, including a fixed-layout presentation mode.
Searches bounded reading-order text with progress/cancellation and adds in-memory bookmarks, notes, and selected-text quotations that can be explicitly exported/imported as publication-scoped JSON.
Inventories the package and checks required metadata, mimetype ordering/compression, manifest/spine targets, navigation, active content, external resources, missing relative links, hidden entries, encryption metadata, and signatures.
Edits common Dublin Core fields, replaces an existing declared JPEG/PNG/WebP/SVG cover, exports metadata/report/tree JSON, extracts the cover, exports reading-order text/Markdown/safe standalone HTML, and downloads sanitized chapters.
Rebuilds a fresh EPUB with the uncompressed mimetype first, sorted paths, optional normalized timestamps, updated OPF metadata, and an optional replacement cover.

The validator is a focused preflight, not a browser port of EPUBCheck. Version 0.1 does not claim complete schema, CSS, accessibility, media-overlay, signature, DRM, or font-licence validation. Unsupported encryption and DRM are detected and reported; they are never bypassed. The standardized IDPF font-obfuscation mask is decoded locally for reading and preserved (including identifier re-keying) during rebuilds. Rebuilds remain disabled for unsupported protection and invalidate existing signatures.

Safety limits

512 MiB source file, 20,000 entries, 1 GiB declared expanded total
64 MiB per resource, 500:1 maximum declared expansion ratio
16 MiB package/chapter parse limit
Link validation scans at most 500 content documents and 32 MiB total, with every skipped scope disclosed
Reader local-resource resolution is capped at 25 MiB per resource, 128 unique resources, and 128 MiB total per rendered chapter; repeated references reuse one object URL. At most 16 packaged stylesheets, 2 MiB each/8 MiB total, are loaded. Search reads at most 2,000 documents, 8 MiB each/64 MiB total. Derived text/HTML/Markdown export is capped at 32 MiB.
Absolute, backslash, drive-letter, NUL, and parent-traversal archive paths are rejected

DTD/entity declarations, ZIP encryption, scripts, forms, frames, objects, external reader resources/navigation, CSS imports/network URLs, and event handlers are blocked or removed from the reader surface. The iframe permits same-origin DOM access only so the trusted parent reader can intercept internal links, scroll to fragments, and capture an explicitly selected quote; publication scripts remain absent and the iframe CSP denies network access. Rendering still depends on the current browser and font decoder.

Format and export direction

EPUB 2/3 plus bounded UTF-8 HTML/XHTML, Markdown and plain text are current import formats. Remaining deeper-fidelity work includes vertical-writing controls, media-overlay playback, multiple-rendition selection, and more exhaustive accessibility/CSS validation. Further modular, DRM-free import adapters remain candidates for:

MOBI/PRC and KF8 (.azw3), then FB2/FB2.ZIP and CBZ.
HTMLZ and asset-preserving HTML packages.
KFX only as an explicitly experimental later adapter if a maintainable, auditable parser and representative DRM-free fixtures are available. KFX is not treated as a general interchange or publishing target, and protected books will not be decrypted.

Current downloadable outputs are a rebuilt EPUB, reading-order text, text-centric Markdown, safe standalone HTML, a sanitized XHTML chapter, original cover, reading-notes JSON, and JSON metadata/validation/package reports. Asset-preserving HTML ZIP, a print/PDF hand-off, CBZ for image-only publications, and stricter EPUB 3 publishing profiles remain future candidates. Lossy conversion is labelled, and EPUB remains the preferred editable/publishing output.

Development

Requires Node.js 22 and npm 11.

npm ci
npm run check
npm run test:browser

npm run release:artifact creates release/epub-tools-0.2.0.zip and its SHA-256 sidecar.

Licence

GPL-3.0-or-later. Runtime dependencies retain their own licences; see THIRD_PARTY_NOTICES.md.

5.6 KiB Raw Blame History