62 lines
5.6 KiB
Markdown
62 lines
5.6 KiB
Markdown
# EPUB Tools
|
|
|
|
EPUB Tools is a standalone, local-first EPUB 2/3 reader and publication workbench for the [add·ideas Toolbox](https://git.add-ideas.de/lotobo/toolbox-portal). 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:
|
|
|
|
1. MOBI/PRC and KF8 (`.azw3`), then FB2/FB2.ZIP and CBZ.
|
|
2. HTMLZ and asset-preserving HTML packages.
|
|
3. 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.
|
|
|
|
```sh
|
|
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](THIRD_PARTY_NOTICES.md).
|