Port the Invariant, Not the Code

TLDR

Cross-language library ports (such as moving C++/PDFium layout algorithms to JavaScript/PDF.js Web Workers) fail when engineers transliterate syntax line-by-line across incompatible data structures. Successful ports extract invariant typographic thresholds ($\Delta Y > 0.34 \times \text{fontSize}$, font scaling ratios, stretch delimiter thresholds) while completely rewriting iteration mechanics to match the target runtime's data model.

Porting Strategy	Code Structure	Invariant Fidelity	Cross-Library Viability
Line-by-Line Transliteration	Mirrored loops & variables	Fragile (Breaks on data granularity)	Low
Invariant Transplantation	Native JS implementation	100% Retained domain math	High

---

Core invariant specifications

Extract domain invariants into clean, framework-independent constants:

// Portable Typographic Math Invariants
export const MATH_INVARIANTS = {
  NUMERATOR_Y_OFFSET_RATIO: 0.34,   // dy > +0.34 * baseFontSize
  DENOMINATOR_Y_OFFSET_RATIO: 0.30, // dy < -0.30 * baseFontSize
  SCRIPT_FONT_SIZE_RATIO: 0.85,    // fontSize < 0.85 * baseFontSize
  STRETCH_DELIMITER_RATIO: 1.50     // delimiterSize >= 1.50 * medianFontSize
};

Rule of thumb: Document core mathematical and domain invariants separately from language runtime mechanics when porting algorithms between libraries.