EPUB Preflight

Inspiration

We run a small EPUB repair service, and the same problems keep coming back. Indie authors export a book from Word or a free converter, upload it to an ebook store, and get a rejection written for engineers. Most of the causes are mechanical: the book was re-zipped with a normal ZIP tool, a date is missing, Word left   in the text. They should not need to pay someone, or learn XML, to fix that.

What it does

EPUB Preflight opens an .epub file in the browser and checks what most often gets a book rejected: packaging, container, metadata, manifest, reading order, navigation, cover, the markup of every chapter, internal links and file names. Every problem becomes a card that says what is wrong, why it matters, how to fix it, and which file to open. Parser errors become sentences: "Line 9: the <p> tag opened on line 7 is never closed."

One click repairs what never needs a person, without touching the text: it repackages the book with mimetype first and uncompressed, writes a correct last-modified date, and replaces HTML entities like   with numeric codes. The page then checks the repaired book again, lists what it fixed, and offers the download. "Copy report" copies the whole list to keep it or to ask for help. A built-in broken sample lets anyone try it without a book.

It is honest about its limits: it is a preflight, not a replacement for EPUBCheck, the official validator.

How we built it

We followed the Devpost Learn Skill Pack with Claude Code: scope.md to cut the idea to its kernel (plain-English explanations plus safe repairs), prd.md for the journey and the acceptance criteria, spec.md for the architecture. They are in the devpost/ folder of the repository.

The tool is plain JavaScript with no dependencies: a small ZIP reader and writer on top of the browser's DecompressionStream and CompressionStream, the browser's own XML parser, and one static page on GitHub Pages. Nothing is uploaded: there is no server at all.

Challenges we ran into

Browsers word XML errors differently, and the raw messages are cryptic. We translate the common ones (unclosed tags, unknown HTML entities, bare &, stray <) and fall back to the browser's message with the line number. Repairs had to be provably safe: the tests check that every file except the repaired ones comes out byte-for-byte identical.

Accomplishments that we're proud of

A broken sample goes from five errors to three in one click, and the three that are left say exactly which file and line to open. The repaired file passes the same checks when you drop it again.

What we learned

Writing the scope first saved the project: "explain in plain English and repair only what cannot change the text" ruled out a lot of tempting features, like rewriting chapters or replacing EPUBCheck.

What's next

More safe repairs (files missing from the manifest, upper/lower case mismatches in links) and accessibility checks for the European Accessibility Act.

Built With

• claude-code
• css3
• github
• html5
• javascript