The horizon that wobbled for eight rounds

There's a horizon line in the 3D version of this site. Sky above, ocean below, a crisp line where they meet. For two days, that line wobbled every time you scrolled. Not a lot. Just enough to make the whole world feel like it was breathing wrong.

Here's the part I want to write down, because I'll need it again: we fixed it five times before we fixed it.

The plausible suspects

Every fix made sense at the time. The camera was tilting on scroll, so we locked the pitch. The parallax was rotating instead of translating, so we rebuilt it as a pure slide. The ocean plane was finite and the far edge crawled, so we made it quasi-infinite. The line itself was a hard edge that aliased, so we softened it. Toon shading bands were forming ruler-straight lines at distance, so we dissolved them.

All five of those were real problems. All five fixes stayed in. And the horizon kept wobbling.

That's the trap with rendering bugs. The plausible mechanism is not always the actual mechanism, and every plausible fix improves something, which makes you feel like you're closing in. You're not closing in. You're redecorating.

The question I should have asked first

What broke the case wasn't a better theory. It was a dumber question: which layer is actually moving?

I took a screenshot mid-scroll and looked at it like a compositor instead of a programmer. The blue was fine. The water texture was fine. The grey gradient layer — the sky dome — was the thing sliding around. Once we knew the element, the cause fell out in minutes.

The sky dome was a small sphere that re-centered itself on the camera every frame with a "follow the camera" callback. But frame callbacks run in whatever order they want, and some frames the dome followed a camera that hadn't moved yet. One frame of lag. On a dome only 60 units wide, a few units of camera motion inside it swings the apparent horizon by several degrees. The wobble was literally the dome being late to work.

The fix that can't lag

The answer came from how actual games do skyboxes: never position the dome at all. Strip the translation out of the camera matrix in the vertex shader and keep only the rotation. The dome is then centered on the camera by construction — not by a callback that hopefully runs in the right order, but by math that has no other option.

That's the difference between a fix and a correct design. The five earlier patches reduced symptoms. The shader change made the failure mode impossible.

What I'm keeping

Two rules came out of this, and they're pinned above the workbench now:

1. Isolate the element before theorizing the mechanism. Toggle layers. Tint them. Ask which pixel is moving. A screenshot and a hard look beat an afternoon of clever hypotheses.
2. Prefer fixes where the bug becomes impossible, not unlikely. Anything that "follows" something else every frame is a race waiting to happen. If you can restructure so there's nothing to race, do that instead.

The line is crisp now. The ocean got real waves this week too, and a giant version of me breakdances on it. But that's another note.