# EPUB versus K2F

The **K2F format** operates on a dual-state architecture: an editable, declarative semantic JSON tree (State A) and a compiled, **pixel stable lock** (`document.K2F.lock` / State C) packaged inside a self-contained ZIP archive. While reflowable EPUB defers geometry, pagination, and line wrapping to client-side reading systems (such as Apple Books WebKit, Chromium, or Adobe RMSDK)—allowing readers to dynamically alter font sizes, margins, and typefaces at runtime—K2F compiles semantic intent into deterministic geometry using a dedicated Rust reference layout engine (`k2f_layout`), strictly isolating content meaning from visual theme primitives and mandating embedded fonts.

K2F is not a lossless superset of EPUB. K2F v0.1 does not import or export EPUB packages, cannot import PDF documents (`PDF_IS_NOT_A_SOURCE`), lacks arbitrary Bézier vector art directly in State A (external graphics must be pre-rendered SVGs or images in `/assets/`), does not provide a dynamic reflowable reading mode for responsive runtime font scaling on small mobile screens or E-ink devices, lacks synchronized audio narration (SMIL Media Overlays), lacks vertical writing modes (`vertical-rl`) in v0.1, and does not target the commercial trade e-book retail supply chain (such as Amazon KDP or Apple Books). Furthermore, all export deliverables derived from K2F (PDF, Word, PowerPoint, InDesign) are unidirectional renderings of the compiled lock (`*_IS_NOT_A_SOURCE`) rather than round-trip authoring sources.

## At a glance

| Topic | EPUB | K2F |
| :--- | :--- | :--- |
| What the file *is* | Containerized multi-document web markup package (XHTML5, CSS, SVG, XML metadata; OCF 3.3 / ISO/IEC TS 30135) in a ZIP archive | Declarative semantic JSON tree (State A) + compiled render lock (State C) in a self-contained ZIP archive |
| Primary authoring model | Export destination from DTP (InDesign), word processors (Word, Pages), or Pandoc, often followed by code-level adjustments in tools like Sigil or Calibre | Programmatic authoring, inspection, and patching by AI agents and automated code pipelines |
| Layout & pagination execution | Runtime layout and dynamic pagination computed client-side by consumer reading engines (Apple Books WebKit, Chromium, Adobe RMSDK, Kindle engine) | Compile-time ahead-of-time deterministic layout (`f(content, theme) → geometry`); viewers strictly paint the published `document.K2F.lock` |
| Cross-device pixel stability | Anti-pixel-stable by design (reflowable text adapts to screen/reader settings); Fixed-Layout (FXL) is fragmented by aspect-ratio letterboxing, synthetic spreads, and font-obfuscation fallbacks | Yes — viewers paint the pre-compiled lock directly; mandatory embedded fonts (`assets/fonts/`) guarantee cross-device pixel stability |
| Node addressing for AI | Fragile; elements lack mandatory IDs; index-based Canonical Fragment Identifiers (`epubcfi(...)`) break when sibling nodes are modified, forcing agents to rely on fragile text-scraping heuristics | Mandatory, hierarchical dotted IDs (`parent_id.child_type_semantic_name`) on every semantic node in State A |
| Text modification & multi-file sync | Multi-file coordination: modifying or adding sections requires synchronized updates across `content.opf`, `nav.xhtml`, and XHTML content files; strict XML parsing fails on minor syntax errors | Single unified semantic JSON tree (`content/root.json`) with closed-enum modifiers; verified locally against embedded `/schema/` via `pack_verify` |
| Separation of concerns | CSS style rules frequently leak into XHTML elements via inline styles; reading systems aggressively override author styles (fonts, margins, colors) | Strict separation: zero styling on State A nodes; visual primitives live exclusively in `styles/theme.json` |
| Theming & global restyling | Manual CSS edits risk cascade conflicts across multiple chapter stylesheets or rejection by reader app overrides | Single token change in `styles/theme.json` restyles entire document deterministically upon recompilation without layout drift |
| Typography & font embedding | Embedded fonts often subject to proprietary obfuscation (IDPF vs Adobe) or ignored in favor of reader-selected system fonts (Bookerly, Georgia) | Mandatory complete embedded fonts (`assets/fonts/`); standard text shaping (HarfBuzz/rustybuzz), Unicode UAX #14 line breaks, and NFC normalization |
| Reading UX & ergonomics | Reader-centric ergonomics: adjustable font sizes, dyslexia fonts, margins, line spacing, and continuous reflow for phones and E-ink screens | Publisher-controlled paged canvas (`canvas_mode: "paged"`): fixed sheet bounds, strict vertical page budgets, running headers and footers |
| Arbitrary vector art | Native inline SVG and CSS vector styling supported in XHTML Content Documents | Forbidden in State A JSON; external vector graphics stored as pre-rendered SVGs or images in `/assets/` |
| Document integrity & trust | Optional XMLDSig (`META-INF/signatures.xml`) universally ignored by reading systems; relies on proprietary DRM (Adobe ADEPT, FairPlay, Readium LCP) enforcing access control rather than visual fidelity | Dual-hash architecture (`content_hash`, `appearance_hash`), optional Ed25519 signatures, mandatory viewer banner (`SIGNED`, `UNSIGNED`, `SIGNED_BUT_BROKEN`, `BROKEN_INTEGRITY`, `UNLOCKED`) |
| Interactive forms | Basic HTML5 form tags supported in spec but rarely functional or supported across standard consumer e-readers | Native `form_field` semantic nodes compile directly into genuine interactive AcroForm PDF exports |
| Multi-format delivery | Standalone consumer e-book deliverable; cannot export natively to editable Office documents or InDesign packages | Single-source lock-drawn exports to PDF (with interactive AcroForms), Microsoft Word (`.docx`), PowerPoint (`.pptx`), and InDesign (`.idml`) |
| Import / Source of truth | Treated as compiled, read-only retail delivery artifact; upstream source (InDesign, Word, Scrivener) is the true source of truth | `.K2F` is sole source of truth; K2F v0.1 does not import EPUB or PDF (`PDF_IS_NOT_A_SOURCE`); exports are unidirectional drawings of the lock (`*_IS_NOT_A_SOURCE`) |

## EPUB vs K2F: What EPUB is good at

EPUB is the foundational open standard for consumer digital books and e-reading hardware. Its core strengths include:

- **Long-form immersive linear reading:** Reflowable EPUB is expressly engineered for novels, narrative non-fiction, and continuous prose. Readers have full ergonomic control over their reading experience, with the freedom to adjust font sizes across 10–14 granular steps, switch to dyslexia-friendly typefaces (such as OpenDyslexic), customize line spacing and margins, and toggle visual modes (Sepia, Warm, OLED Pure Dark, High Contrast).
- **Dedicated E-ink hardware ergonomics:** Electronic paper displays (Amazon Kindle, Kobo, PocketBook, Onyx Boox) rely on slow refresh cycles and compact physical dimensions. Reflowable EPUB allows text to flow naturally across virtual screens without requiring the cumbersome horizontal panning and two-finger zooming unavoidable with fixed-page formats.
- **Universal accessibility mandates (EPUB Accessibility 1.1 / ISO/IEC TS 30135):** EPUB provides the publishing industry's most robust accessibility framework. Structural semantics (`epub:type`, ARIA landmark roles, and MathML for mathematical notation) integrate natively with screen readers (NVDA, JAWS, Apple VoiceOver) and refreshable braille displays. Text dynamically scales to 48pt+ without clipping or horizontal scrolling, satisfying legal accessibility mandates such as the European Accessibility Act and WCAG 2.1.
- **Global commercial trade publishing and retail distribution:** EPUB is the universal retail ingestion standard across the digital publishing industry. Delivering compliant EPUB packages is mandatory for distribution through major retail marketplaces, including Apple Books, Kobo Writing Life, Barnes & Noble Press (Nook), Google Play Books, and Amazon KDP (which converts EPUB to proprietary Kindle formats).
- **International text direction and non-Latin typography:** Inheriting modern W3C CSS capabilities, EPUB provides mature support for non-Western typography: vertical writing modes (`writing-mode: vertical-rl` for traditional Japanese and Chinese), phonetic pronunciation annotations (`<ruby>`, `<rt>`), and bidirectional right-to-left layout for Arabic and Hebrew.
- **Synchronized read-aloud multimedia (Media Overlays):** Standardized SMIL (Synchronized Multimedia Integration Language) 3.0 Media Overlays synchronize prerecorded audio narration with real-time text highlighting, making EPUB the industry standard for interactive children's picture books and language-learning publications.

## What K2F adds

K2F is engineered for workflows where autonomous AI agents and automated software pipelines require deterministic structure, verifiable rendering, and multi-format delivery:

- **Declarative semantic tree & stable dotted IDs:** Every node in State A (`content/root.json`) carries a mandatory, hierarchical dotted ID (e.g., `financials.q3_results.table_revenue`, `contract.clauses.clause_4_indemnity`). AI agents read, patch, diff, and revert specific content nodes with 100% addressable precision by ID, avoiding fragile regex patterns, fuzzy text scraping, and brittle index-based Canonical Fragment Identifiers (`epubcfi(...)`) that break when sibling nodes change.
- **Deterministic layout compilation & pixel-stable lock (`document.K2F.lock`):** K2F strictly decouples structural intent from visual geometry. The reference Rust layout engine (`k2f_layout`) calculates exact physical coordinates using HarfBuzz text shaping (`rustybuzz`), Unicode line breaking (UAX #14), and IEEE-754 math layout into an immutable render lock (State C). Official viewers (`<k2f-viewer>`, Desktop Reader) strictly paint the published lock directly without running layout or reflowing body text, eliminating the aspect-ratio letterboxing, synthetic spread inconsistencies, and font-fallback wrap shifts common in Fixed-Layout EPUB.
- **Mandatory embedded fonts & typography determinism:** EPUB reading systems frequently substitute author-specified fonts with reader preferences or fail to de-obfuscate embedded fonts (due to incompatible IDPF vs. Adobe obfuscation algorithms), causing text boxes to overflow. K2F mandates complete embedded fonts in `assets/fonts/` and prohibits system font fallbacks, ensuring identical character metrics across all operating systems.
- **Strict intent-presentation separation & global restyling:** In EPUB, visual styles frequently leak into XHTML files through inline styles, or collide with reader application overrides. K2F strictly forbids inline styling on State A nodes; visual attributes are governed entirely by named design primitives in `styles/theme.json`. A single prompt or theme token restyles an entire document deterministically upon recompilation without layout drift.
- **Single-package architecture & automated schema verification (`pack_verify`):** Modifying an EPUB requires updating multiple disparate files in lockstep (`content.opf`, `nav.xhtml`, `chapter.xhtml`). In contrast, K2F maintains a unified semantic JSON tree verified locally against embedded JSON Schemas (`/schema/`) via `pack_verify`. Agents self-diagnose and repair schema violations before compilation, eliminating EPUB's multi-file desynchronization errors.
- **Dual-hash cryptographic integrity & mandatory viewer banner:** EPUB's optional XMLDSig signatures (`META-INF/signatures.xml`) are universally ignored by consumer reading systems, while commercial DRM adds proprietary restrictions without guaranteeing visual fidelity. K2F implements a dual-hash architecture: `content_hash` hashes the semantic tree, while `appearance_hash` binds content, theme primitives, embedded fonts, page setup, and the pinned reference engine identity (`engine_commit_sha`). Official readers enforce a mandatory integrity banner reporting five canonical states (`SIGNED`, `UNSIGNED`, `SIGNED_BUT_BROKEN`, `BROKEN_INTEGRITY`, `UNLOCKED`), alongside runtime layout engine discrepancies (`ENGINE_MISMATCH`).
- **Git-native collaboration & semantic diffs:** EPUB containers bundle loose XHTML files subject to XML serializer churn, namespace mangling, and merge conflicts. K2F source trees are maintained as Canonical JSON (alphabetically sorted keys, 2-space indentation), enabling AI agents and human teams to review clean semantic diffs, resolve merge conflicts, and audit modifications node by node.
- **Native fillable PDF forms (AcroForm):** While EPUB offers minimal, unreliable support for interactive forms on consumer e-readers, K2F's `form_field` semantic nodes compile directly into genuine interactive AcroForm PDF fields upon export, bridging agent-generated form logic with universal document distribution.
- **Single-source multi-format publishing pipeline:** A single `.K2F` document compiles once to produce lock-drawn deliverables for PDF (with interactive AcroForms), Microsoft Word (`.docx`), PowerPoint (`.pptx`), and Adobe InDesign (`.idml`), while strictly enforcing that exports are read-only drawings of the lock (`*_IS_NOT_A_SOURCE`).
- **Agent tooling and template ecosystem:** K2F provides an official agent skill implementing the `agent_v0` authoring dialect, schema verification utilities (`pack_verify`), and a public [Gallery](/gallery) of 469+ templates on [k2f.dev](https://k2f.dev) with multi-format downloads (`.K2F`, `.docx`, `.pptx`, `.idml`) without requiring accounts or subscriptions.

## When to pick which

- **Pick EPUB when:**
  - Publishing long-form narrative books (novels, biographies, general non-fiction) intended for immersive, continuous reading where readers expect personalized font scaling, custom margins, and background theme toggles.
  - Distributing digital publications to dedicated E-ink hardware devices (Amazon Kindle, Kobo, PocketBook, Onyx Boox) where fluid text reflow prevents horizontal scrolling.
  - Submitting commercial trade e-books to retail marketplaces (Amazon KDP, Apple Books, Kobo Writing Life, Barnes & Noble Press, Google Play Books).
  - Complying with strict digital accessibility mandates requiring dynamic text enlargement up to 48pt+ with continuous line reflow and screen-reader accessibility (EPUB Accessibility 1.1 / European Accessibility Act).
  - Publications require vertical writing modes (`writing-mode: vertical-rl` for East Asian typography) or synchronized audio-text read-aloud narration via SMIL 3.0 Media Overlays.

- **Pick K2F when:**
  - Creating publisher-controlled business, legal, or technical documents (reports, whitepapers, proposals, contracts, invoices, certificates, or interactive forms) requiring exact page geometry, vertical page budgets, and print-ready presentation.
  - Autonomous AI agents and automated software pipelines must programmatically inspect, target, patch, and validate document content using stable dotted node IDs with schema validation (`pack_verify`), avoiding fragile regex matching or brittle index-based CFIs.
  - Documents demand cross-device, cross-platform pixel stability via embedded fonts and a compiled geometry lock (`document.K2F.lock`), eliminating client-side layout discrepancies.
  - Publishing simultaneously from a single source of truth to PDF (with interactive AcroForms), Microsoft Word (`.docx`), PowerPoint (`.pptx`), and Adobe InDesign (`.idml`).
  - Workflows require Git-native semantic version control with clean diffs, theme-driven restyling without content edits, and cryptographic tamper-evident integrity banners.

- **Complementary roles and coexistence:**
  - EPUB and K2F address distinct publishing requirements. EPUB is a consumer e-reader delivery format optimized for user-customizable text reflow; K2F is an agent-native authoring format optimized for publisher-controlled deterministic geometry and multi-format enterprise export. K2F v0.1 does not import or export EPUB packages, nor does it import PDF files (`PDF_IS_NOT_A_SOURCE`). Deliverables exported from K2F are unidirectional drawings of the lock, not editable sources of truth (`PDF_IS_NOT_A_SOURCE`, `DOCX_IS_NOT_A_SOURCE`, `PPTX_IS_NOT_A_SOURCE`, `IDML_IS_NOT_A_SOURCE`). All authoritative structural edits must occur in K2F State A.

## Bottom line

For additional details on K2F architecture, explore the technical [documentation](/docs), review pre-built templates in the [Gallery](/gallery), read [why K2F exists](/why), or view the full format matrix on [Compare](/compare).

This comparison is based on publicly available information at the time of writing. Capabilities, pricing, and policies may change; verify details with the relevant provider.