The Pattern Under All Three Quiet Bugs
TLDR: The three quiet bugs in this series (coordinate spaces, semantic vs spatial sync, and multi-surface state) look unrelated. They are the same bug. In each case, two things were treated as equivalent that were not. The form of equivalence was different each time, but the failure mode was identical: the system didn't crash. It just produced output that looked a little wrong.
Repo: tools/pdf-processor
The three bugs
In each case, two things had the same surface form but a hidden incompatibility:
- Coordinate-space mismatch. Two values had the same shape (numbers) but different units (PDF points vs viewport pixels).
- Layout-metric mismatch. Two pixel measurements had the same unit but different meanings (spatial vs semantic).
- State-surface mismatch. Three DOM strings had the same role but no shared canonical record.
Why these survive
Quiet bugs survive because the system does not crash. It just produces output that looks a little wrong.
In the coordinate-space bug, the page still rendered. Underlines were just missing. Columns were detected with subtle off-by-fractions.
In the scroll-sync bug, both panes scrolled. They just didn't show the same content.
In the multi-surface bug, the editor accepted input. The changes just didn't propagate, or did propagate but got clobbered later.
Each of these survived code review. Each survived integration testing. Each survived the deploy. Each died only when a user noticed that something felt off, and someone went back to first principles and asked: what am I actually comparing?
The discipline
Three questions, applied before any cross-thing comparison:
- Before any arithmetic between two values, ask whether they share a unit, a meaning, and a source. Numbers that look the same can mean different things.
- Before any sync between two surfaces, ask whether they have a shared canonical record. If three things "represent the same state," there should be one place that state lives.
- Before any sync between two layouts, ask whether they share a metric or merely share an axis. Two things can both be measured in pixels and still be incomparable.
The cost
The three fixes together were less than 200 lines of code. The diagnosis took half a day. The discipline above takes seconds per check.
The bugs were in flight for weeks before anyone noticed. They survived because nothing crashed.
The PDF processor now handles all three. Coordinate spaces are explicit on every text record. Visual diff scroll uses page-snap and the IntersectionObserver. The editor surfaces share a single coordinator with a single guard.
The whole rebuild is open source. If you spot a fourth invariant we missed, the issue tracker is open.
This is part 4 (the synthesis) of a four-part series. Start at the overview if you came in here cold.