epub-tools/README.md

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.

Version 0.1.0

• Opens strict ZIP-based EPUB containers and parses container.xml, OPF metadata, manifest, spine, EPUB 3 navigation documents, and EPUB 2 NCX navigation.
• Shows a reading-order sidebar and renders XHTML/HTML/SVG content in a sandboxed, script-free iframe. Local images are resolved to temporary object URLs.
• 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, 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. DRM is detected and reported; it is never bypassed. Rebuilds are disabled when encryption metadata is present 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 image resolution is capped at 25 MiB per image; plain-text export 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, stylesheet links, CSS imports/URLs, and event handlers are blocked or removed from the reader surface. Rendering still depends on the current browser and installed fonts.

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.1.0.zip and its SHA-256 sidecar.

Licence

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