Rasura

How it works

Bytes to a document model and back, and the one mechanism that keeps edits local.

The pipeline

Text
bytes → objects → content streams → glyph runs → document model
↓ mutate
bytes ← incremental append ← patched streams ← reflowed runs

Reading goes up the stack and writing comes back down the same path. The important property is that the descent is partial: a text edit produces a patched content stream and nothing else, so every object it did not touch is written back from the original bytes.

How locality holds

The writer keeps the byte span each object occupied in the source file. On save, anything unmodified is copied out of the original buffer verbatim rather than re-serialised.

That is the whole mechanism, and it is why the property survives as the layers above it grow. A re-serialising writer would drift: a dictionary that round-trips today gains a space, a different number format, or a reordered key the moment anything downstream changes, and non-locality returns without anyone editing the writer.

Reconstruction

A content stream says draw glyph 36 at this point. Getting from there to a paragraph takes six steps, and each one can fail in a way worth reporting.

  1. Extract glyph runs with their positions and the font in force.
  2. Resolve each glyph to a character. /ToUnicode covers about half of embedded fonts, so six other strategies exist behind it, and the glyph name list carries more glyphs than /ToUnicode does.
  3. Segment words, which frequently means inferring spaces the file does not contain.
  4. Assemble lines from runs that share a baseline.
  5. Cut the page into blocks and columns, recursively.
  6. Reconstruct paragraphs: alignment, leading, indents and hyphenation.

Every step reports rather than assumes. Hyphenation that was joined is flagged, alignment that was inferred is distinguished from alignment that was measured, and a glyph resolved by heuristic lowers the paragraph’s confidence.

How it is checked

  • 1,196 unit tests and 41 JavaScript tests.
  • 1,030 real PDFs, mostly the pdf.js regression suite, run through eight invariants on every build. Skips are itemised with reasons rather than counted as passes.
  • Three independent judges. pdf.js extracts text and builds fonts, pdfium renders pages for pixel comparison, qpdf validates structure. None of them has a stake in agreeing with this library.
  • Fuzzing on the lexer, document open, the filters and the cross-reference parser.
  • A real browser loads the site before anything deploys, because a check that never executes the artifact reports green for ever.

The full account

docs/report.md is the honest version: what exists, what does not, what was refused, and the mistakes that were found and fixed along the way.