A document is not a sequence of pixels

For reading, a document can be treated as “a sequence of page pixels”. For compilation, that is not enough. Pixels have no block identity, no paragraph boundaries and no way to say which later pages a change affected. Incremental compilation, per-page SVG and editor navigation all require admitting that a document is structure first.

An IR is not abstraction for its own sake

Somadoc’s IR turns authored content into blocks with identity: headings, paragraphs, equations, tables, footnotes, references. Identity lets a preview address a block, lets a change be compared, and lets unchanged parts keep their existing layout. Without that layer, “incremental” collapses into re-laying-out whole pages.

Per-page SVG is the output-side proof of this structure: each page can still be displayed as graphics, but the blocks inside it know where they came from. A block-level source map lets an editor and a preview navigate in both directions instead of guessing from scroll position.

Typst is the typesetting core, not the whole system

The boundary needs to be explicit. Typst owns typesetting. Somadoc owns parsing, the IR, incremental contexts, source maps and output. Mixing the two produces phrases like “a pure-Rust typesetting engine” that sound complete but remain vague. For a technical reader, stating the dependency accurately is part of credibility.

“No external toolchain” describes the deployment boundary: no Pandoc, no LaTeX distribution, no external CLI. It does not mean every typesetting algorithm was written from scratch, and it does not mean Typst’s version, fonts and behavior differences can be ignored.

What makes incremental compilation hard

Caching unchanged blocks is only the first step. The difficult work begins after a block changes: a longer paragraph can move footnotes, change float placement, invalidate cross-references and affect several pages downstream. Reliable incremental compilation must know which structural dependencies broke and which layout can be kept.

That is why a persistent compilation context is a correctness concern, not a performance ornament. If a context keeps layout that should have been invalidated, speed only makes the error harder to find.

What is public today

Somadoc’s engine and repository are still under open-source review. The lab on this site is an interface shell with a mock adapter; it does not generate a real PDF. Saying that clearly is more respectful than inviting readers into a fake preview.

A document deserves careful design not because it can become a beautiful page, but because structure determines whether it can be changed, verified, navigated and maintained over time. Pixels are the final presentation, not the document itself.