Litho architecture

Last reviewed: 2026-10-10 · Last updated: 2026-10-12 · Change: minor (shared PDF writing) · Target: Adobe InDesign 2026

How Litho is built today. The design notes behind it are in plan/architecture.md (local, gitignored); this file describes what the code on main does. Agents: AGENTS.md has the rules (never crash, everything is a command, layering, clean-room).

Workspace

A Cargo workspace: 16 library crates in crates/, 3 apps in apps/, and xtask. 126,411 lines of Rust, 1,122 tests (2026-10-10). Pure Rust, no C dependencies by default, unsafe_code = "forbid" workspace-wide.

cargo xtask layers enforces the layering: a crate depends only on lower layers (with the intra-layer orders geom → color and doc → fonts); nothing below L6 depends on egui, eframe, winit or rfd; L0–L6 compile for wasm32-unknown-unknown (cargo xtask wasm).

Data model

Coordinates are points (1/72 in), y down; each spread has its own coordinate system with its origin at the top left of its first page. A Document holds settings, spreads and parent spreads (items under Arc, so edits are copy-on-write and undo is cheap), layers, stories, styles (paragraph, character, object, table, cell; based-on chains and groups), swatches, sections and text variables. A story is one String plus paragraph and character run lists of {len, style, overrides}; effective attributes are default ← based-on chain ← style ← overrides. Special characters (page number, footnote reference, anchored object, table) are placeholder code points in the text. Threading is the story's ordered frame list.

Commands, the only way to change a document

Every user-visible action is a CommandSpec (id, label, menu path, shortcut, parameter doc, enabled, run, journaled, undoable) in crates/engine/src/cmd/*. The UI, the CLI, MCP and the control channel all call Session::execute(id, params). UI-only commands (windows, panels, zoom, dialogs) are UI_COMMANDS in crates/ui-egui/src/menus.rs, reachable the same way. Tool gestures emit Begin/Preview/Commit commands so a drag is one undo step. Every journaled command is replayable as a script. Escaped panics during a command or an import/export become an error (engine/src/guard.rs), never a lost document; native recovery is written periodically into each running app's locked folder. Orderly native shutdown finalizes complete, current quit approvals and writes the remaining documents' latest recovery state, including clean-document cleanup after Undo. Unavailable or failed recovery is reported. The desktop opts into a pinned winit 0.30 patch that cancels AppKit termination and queues ordinary window close requests, including Quit from the macOS Dock. The existing unsaved-document transaction can cancel those requests or exit after current approvals are complete. A pending prompt restores and focuses a hidden or minimized window; completed and immediate quits do not activate it. The AppKit callback never runs the confirmation dialogs inside a modal termination loop.

Composition and rendering

The compose cache is keyed by story revision, frame geometry, style revision and font database revision; stories compose in parallel (rayon) on native targets. Composition produces per-frame lines with positioned glyph runs, decorations, anchors and overset. The canvas renders on a background worker with vello_cpu into tiles; after an edit only frames whose composition changed are re-rendered and patched (damage regions, pixel-identical to a full render). The GPU (wgpu: Metal, DirectX 12, Vulkan, OpenGL; WebGPU/WebGL2 on the web) only presents; the backend is chosen before the window exists, with a start-up fallback list in gpu.json, and the adapter (the GPU that drives the display first) by the app, which starts again on the next one when an adapter fails or hangs at start-up (apps/litho/src/gpu.rs).

File I/O

Native .litho (zip + JSON); IDML both ways; PDF, EPUB, HTML, PNG/JPEG, text, XML export; placed graphics through images (PDF/AI pages through hayro); Word/RTF/Excel/Tagged Text through textimport. INDD is not readable. Details: file-format-parity.md.

PDF authoring uses the independently pinned craft-pdf writer and patched Krilla. Document, booklet and merge entry points guard the full export; a failed native drawing unwind returns an error and incomplete backend state cannot serialize. Layout, shaping, PDF/X processing and print preparation remain app-owned. Reader dependencies and the UI/print pins are unchanged. See pdf-backend.md for dependency and failure contracts.

Agent control

The desktop app opens a loopback JSON-lines control channel (--control PORT) with engine.execute, inspection, real input injection (ui.pointer, ui.key, ui.click, ui.drag), dialog control, screenshots and offscreen renders. litho-cli mcp exposes the same as MCP tools, headless or connected to the app. See agents.md, mcp.md, control-protocol.md.

Quality gates

cargo xtask ci: rustfmt, clippy -D warnings, tests, assets (every asset attributed in ASSETS.md), layers, wasm. Clean crates deny unwrap/expect/panic!/todo!/ unimplemented!/unreachable!. CI on GitHub currently runs only the FreeBSD and Windows ARM64 builds (on manifest changes), packaging lint and the release workflow; xtask ci runs locally.

Revision history

PDF parsing and placed-page rasterization use the pinned craft-pdf reader. Litho retains document, placement, layer and export policy; dependency checks and bounds are described in pdf-backend.md.