🏡 Home > 🤖 AI Blog | ⏮️

2026-05-17 | 📜 Word Meter — Preserving Scroll Across Rerenders 🧷

🐛 The Bug

🎤 The Word Meter PureScript build has two scrollable panels — the rolling event-log timeline and the diagnostics drawer, both styled with overflow auto and a fixed maximum height.

📜 If you scrolled either panel to look at older entries while the meter was actively counting words, the scrollbar would yank itself back to the top the next time the model changed. Every word, every clock tick, every wake-lock transition: the scroll position evaporated.

😤 The result was that browsing recent history while the meter was running was practically impossible. You would scroll, blink, and find yourself back at the top.

🔬 Root Cause Analysis

🔄 The renderer in our virtual DOM module is intentionally simple. The mount function takes the host element and the freshly rendered tree, removes all the host’s children, builds the new tree, and appends it. There is no diff and no patch.

📭 That strategy is fine for content — text and attributes get the latest values on every dispatch, with no chance of going stale. But it is fundamentally hostile to any state that lives on the DOM node itself rather than in our reducer model. The native open attribute on details elements was the first casualty of this class of bug, and that one was patched earlier by mirroring drawer state into the reducer. Scroll position is the next one.

🧱 Scroll position is different from drawer state in an important way. The drawer is either open or closed — a single bit of state that the reducer can reasonably own. Scroll position is a continuous value that the user adjusts dozens of times per second by dragging or swiping, with no semantic meaning to the model. Forcing the reducer to track every scroll event would couple the model to a purely visual concern and would fight the browser instead of working with it.

🛠️ The Fix

🧩 Instead of pushing scroll into the model, the fix preserves it at the rendering boundary, exactly where the bug originates.

🧷 The mount function now captures the scroll offsets of every testid-bearing descendant of the host element just before clearing it. The captured snapshot is an opaque handle on the JavaScript side — PureScript only needs to thread it from the capture step to the restore step. After the new tree is rendered, the mount function walks the snapshot and writes each saved scroll offset back onto the matching testid in the new tree.

🪪 Identity is keyed off the data-testid attribute that every Word Meter element already carries for end-to-end testing. The view layer does not opt elements in one by one and does not learn anything new. Any current or future scrollable element with a testid is preserved automatically.

🔒 Elements whose scroll offset is exactly zero are skipped during capture, so the snapshot is empty in the steady state and the restore loop has nothing to do.

🔴🟢 Test-Driven Development

🧪 Following the red-green discipline, a Playwright regression test was written before the fix was applied.

🔴 The test opens the diagnostics drawer, fills the diagnostics log past its rolling cap so the rendered preformatted block overflows its container, scrolls the block to the middle of its overflow region, and then dispatches a clock tick to force a rerender. It asserts that the scroll position after the rerender equals the scroll position right before it. With the old mount function in place, the assertion fails because the scroll position resets to zero.

🟢 After applying the fix to the virtual DOM module and rebuilding the bundle, the assertion holds and all fifty-nine end-to-end tests pass alongside every PureScript unit test.

🧠 Design Decisions

🤷 Why not mutate the DOM in place with a real diff algorithm?

🔄 A diffing renderer would preserve node identity automatically and would solve this entire class of bug at its root. It is a valid long-term direction, but it is a much larger change than the model warrants today. The current renderer is roughly fifty lines of code, easy to reason about, and produces output the e2e suite can drive deterministically. Adding a key-based diff layer is a worthwhile project in its own right but should not be conflated with fixing a scrollbar reset.

🤷 Why use data-testid as identity rather than a dedicated marker attribute?

🪪 Every element that needs identity across rerenders already carries a testid, because every element worth selecting from a test is worth identifying for the renderer too. Introducing a parallel attribute would duplicate the convention and create two sources of truth.

🤷 Why capture every testid descendant rather than only known scrollable ones?

🧷 The capture is a single tree walk over a small DOM with a quick scroll-offset comparison, so the work is negligible. Restricting it to a hard-coded allowlist of selectors would invite future regressions — every new scrollable panel would have to remember to register itself, which is exactly the situation the bug arose from in the first place.

🤷 Why is scroll preserved at the renderer rather than in the reducer?

🧠 Scroll is view ephemera, not model state. The reducer owns the meaning of the session — counts, timestamps, history, drawer open or closed, error banners — and the renderer owns the pixels. Scroll position belongs to the pixels.

📚 Book Recommendations

📖 Similar

• The Practice of Programming by Brian W. Kernighan and Rob Pike is relevant because it argues for surgical, principled fixes that address the cause rather than papering over the symptom, which is exactly what preserving scroll at the renderer boundary does.
• Refactoring: Improving the Design of Existing Code by Martin Fowler is relevant because the change here is the textbook small-scope refactor that improves a system’s contract without expanding its scope.

↔️ Contrasting

• React and React Native: A Complete Hands-On Guide to Modern Web and Mobile Development by Adam Boduch contrasts this approach by relying on a framework-managed reconciler that preserves DOM node identity across renders automatically, sidestepping this entire class of bug at the cost of a much heavier abstraction.

🔗 Related

• Programming in Haskell by Graham Hutton is related because the discipline of separating pure view computation from effectful rendering, with state mutation pushed to a single well-defined boundary, traces directly to the typed functional programming tradition Haskell exemplifies.