Honzo

The "ideal" ebook format.

Honzo is a binary ebook format designed for simplicity, performance, and portability. Zero-copy parsing, pull-based streaming, per-chunk compression, and portable annotations that travel with the file.

Features

| Feature | Description | |------------------------------|---------------------------------------------------------------------| | Zero-copy parsing | Read without allocating. Embeddable on bare metal. | | Pull-based streaming | Decompress chapters on demand. Never hold the whole book in memory. | | Per-chunk compression | LZ4 per chapter via TOC flag. Images and fonts store raw. | | Separately editable tail | META is last. Edit title, tags, revision without touching DATA. | | Portable annotations | Highlights, bookmarks, notes stored in the file via EXTRA section. | | Search index | Inverted term index as SIDX chunk (MessagePack). | | Encryption envelope | AES-256-GCM per-chunk encryption with X25519 ECDH key exchange. | | Multi-language metadata | Titles and descriptions localized per BCP 47 language tag. | | Format conversion | Import from EPUB, MOBI, PDF; embedded WASM converter for browsers. |

Quick Start

Rust

use honzo_core::HonzoParser;
use honzo_io::{HonzoBuilder, HonzoStream};

// Zero-copy parse
let data = std::fs::read("book.hzo").unwrap();
let p = HonzoParser::new(&data, 1).unwrap();
println!("{} chunks", p.head().chunk_count);
for entry in p.toc_entries() {
    println!("  {} - {:?}", entry.chunk_id,
             std::str::from_utf8(&entry.chunk_type));
}

// Streaming read
let file = std::fs::File::open("book.hzo").unwrap();
let mut stream = HonzoStream::open(file, 1).unwrap();
for chapter in stream.chapters() {
    let text = chapter.unwrap();
    println!("Chapter: {} bytes", text.len());
}

// Build
let hzo = HonzoBuilder::new()
    .add_chunk(*b"CHAP", b"Hello, world!", Compression::None,
               MarkupType::Markdown, CoverType::Front, None, None, None)
    .finalize()
    .unwrap();

TypeScript

import { createReader, buildHonzo } from '@nisoku/honzo';

const response = await fetch('book.hzo');
const buf = new Uint8Array(await response.arrayBuffer());
const reader = await createReader(buf);
console.log(reader.chunkCount, reader.layoutMode);

const meta = reader.getMeta();
console.log(meta.title?.en);

C

#include "honzo.h"

HonzoHandle* handle = HonzoHandle_parse(data, data_len, 1);
uint32_t count = HonzoHandle_chunk_count(handle);

Repository Layout

Honzo/
  Cargo.toml                # Rust workspace root
  honzo.ksy                 # Kaitai Struct binary spec
  Build/
    crates/
      honzo-core/           # no_std wire-format parser
      honzo-chunks/         # Chunk types, validation, search index
      honzo-io/             # Builder, reader, stream, DRM (std)
      honzo-convert/        # EPUB/MOBI/PDF/CBZ import
      honzo-c/              # C FFI bindings (Diplomat)
      honzo-wasm/           # WASM bindings
      honzo-cli/            # CLI binary
      honzo-fixtures/       # Test fixture generator
    adapters/typescript/    # npm @nisoku/honzo
  Demo/                     # Vite web demo (reader, maker, inspect, convert)
  Docs/                     # Documentation site (docmd)
  Tests/                    # Integration tests

Documentation

• Getting Started
• Format Specification
• API Reference
• Live Demo

Packages

| Language | Package | Links | |-------------------|-----------------|----------------------------------------------------------| | Rust (core) | honzo-core | crates.io | | Rust (chunks) | honzo-chunks | crates.io | | Rust (io) | honzo-io | crates.io | | Rust (convert) | honzo-convert | crates.io | | Rust (CLI) | honzo-cli | crates.io | | TypeScript / WASM | @nisoku/honzo | npm | | C | honzo-c | Source in Build/crates/honzo-c |

Contributing

See CONTRIBUTING.md.

License

Apache License 2.0. See LICENSE.