Hardening the Version Comparison Engine

Bulletproof Diffs

Our Version Comparison Engine had been built incrementally across several sprints, and that growth introduced a class of subtle React hook violations that only appeared when a user quickly switched between historical snapshots.

These caused the diffing UI to display stale data or, in worst cases, crash the entire contract detail view.

Root Cause Analysis

• Hook Order Violations: Conditional hook calls inside rendering loops caused the number of hooks per render to fluctuate, corrupting React's internal state tree.
• Stale Closure References: The diff computation function captured contractId in closures at render time, meaning rapid navigation triggered diffs between a new version and a stale ID.
• Missing useEffect Cleanup: Timeline subscriptions were not cleaned up on unmount, leading to memory leaks and phantom state updates.

The Refactor

1. 1.Extracted Hooks to Top Level: All hook calls were moved unconditionally to the component's top level, with logic gated by if statements rather than wrapping the hook call.
2. 2.Ref-Based Closure Anchoring: useRef now holds the latest contractId and versionIndex, so the diff function always accesses current values without a stale closure.
3. 3.Strict Cleanup Registry: Every useEffect now returns a cleanup function, validated by our ESLint rule set before any PR can merge.

Zero Crash Sessions

Since the refactor, the Version Comparison Engine has logged zero crash sessions. Diff rendering is deterministic regardless of navigation speed.