A few core ideas make Honzo different from other ebook formats.

The File Structure

Every Honzo file follows the same layout:

+------+-----+-------+------------+------+
| HEAD | TOC | DATA  | EXTRA      | META |
|      |     |       | (optional) |      |
+------+-----+-------+------------+------+

META is deliberately last. Edit the title, tags, or revision without touching DATA.

Zero Copy Parsing

The wire format is designed for direct casting. You take the file bytes and overlay structs. No parsing, no allocation.

let data = std::fs::read("book.hzo").unwrap();
let p = HonzoParser::new(&data, 1).unwrap();

// head() is a pointer cast, not a copy
let head = p.head();

When you memory map the file, parsing completes in O(1) time with zero heap allocation. This approach works in environments where every allocation counts. Think embedded devices, WASM runtimes, and kernel modules.

Pull Based Streaming

The TOC tells you exactly where each chunk lives. You never have to read everything at once.

• Parse only the header (48 bytes) to open a file.
• Skip to META to read the title. No chunk data is parsed.
• Decompress chapters one at a time as the reader turns pages.
• Seek to a specific image by its TOC offset.

The streaming API (HonzoStream) reads and decompresses one chapter at a time. A 1GB book with 100 chapters uses memory proportional to the largest single chapter.

Per Chunk Compression

Each TOC entry picks its compression independently:

LZ4 favors decode speed over compression ratio. Text chapters typically compress to 40-60 percent of their original size. Since compression is per chunk, you control the tradeoff. Do not waste CPU decompressing JPEG images that will not shrink. Do compress chapters where the savings matter.

Tail Mutability

META lives at the end of the file. This design lets you:

No bytes in DATA need rewriting. The same strategy powers MP4 and other streaming oriented formats. EXTRA entries sit between DATA and META. They are appendable too.

Chunk Types

See Chunk Types for the full reference.

EXTRA Namespaces

EXTRA entries use reverse domain namespacing for extensibility:

Anyone can define a custom namespace. Unrecognized entries are preserved during round trips. No data is lost.

Next Steps