# 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).