Release EPUB Tools 0.1.0

2026-09-01 02:39:03 +02:00
commit f68dcfe4ea
66 changed files with 10579 additions and 0 deletions
@@ -0,0 +1,40 @@
+# 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.
+
+## 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.
+
+```sh
+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](THIRD_PARTY_NOTICES.md).