The Pattern Under All Three Quiet Bugs

TLDR

Silent bugs in complex web applications survive integration testing because code does not throw exceptions; it produces visually distorted output. Across coordinate spaces, scroll synchronization, and editor state, three major bug classes stemmed from a single architectural mistake: treating two non-equivalent entities as identical. Enforcing three pre-comparison architectural checks prevents silent failures across multi-surface systems.

Silent Defect Pattern	Hidden Non-Equivalence	System Behavior	Architectural Remedy
Coordinate Space Shift	PDF Points vs Viewport Pixels	Missing underlines, off-by-fractions	Explicit units on every record
Scroll Sync Drift	Spatial vs Semantic Scroll Offset	Panes drift vertically apart	IntersectionObserver page snaps
Multi-Surface Editor Drift	Independent DOM string copies	State changes clobbered	Single canonical state coordinator

---

The three architectural pre-comparison disciplines

1. Unit & Source Verification: Before executing arithmetic between two values, verify that they share a unit (PDF pt vs Viewport px), a semantic meaning, and an authoritative source.
2. Canonical State Verification: Before synchronizing two UI surfaces, confirm they read from and write to a single shared canonical record.
3. Layout Metric Verification: Before aligning two containers, verify that they share a metric rather than merely sharing a visual axis.

// Pre-Comparison Guard Example: Coordinate Space Validation
export function convertPdfPointToViewportPx(pdfCoordinatePt, scaleFactor, devicePixelRatio = 1) {
  if (typeof pdfCoordinatePt !== 'number' || isNaN(pdfCoordinatePt)) {
    throw new TypeError('[CoordinateGuard] Invalid PDF point value');
  }
  return pdfCoordinatePt  scaleFactor  devicePixelRatio;
}

Rule of thumb: Verify shared units, canonical state sources, and reference frames before performing arithmetic or synchronization across distinct application surfaces.