perf(nav): stop re-measuring the whole page on every scroll frame — fixes the sluggish deck

[IngTian]

The owner, on prod after #50: "the slide animation & transition is way worse than the previous build. it's almost like sluggish."

Correct, and this is the cause. It's mine — shipped in #50 while fixing a phone contrast bug, and it's the one change in that PR that was not phone-scoped, so it slowed the desktop deck, which was never under review.

What was wrong

The nav picks its glass from what's actually painted behind it. That probe ran inside the scroll handler — on every animation frame of every scroll, and a deck slide transition is a ~500ms smooth scroll, so every frame of one. Per frame:

document.querySelectorAll('main > section > *')        a fresh DOM query
nav.getBoundingClientRect()  ×2                       (the old probe() read it twice)
for each candidate: getBoundingClientRect()           forces layout
                    getComputedStyle().backgroundColor    forces style recalc

Interleaving rect reads with style reads is the textbook layout-thrash pattern: each style read forces the layout the previous rect read just invalidated, so the cost isn't N reads, it's N synchronous layouts per frame. The handler this replaced did one offsetHeight and two rect reads.

Why all of it can be hoisted

Nothing that probe measures changes while you scroll. A panel's document-space top and bottom are fixed, its background colour is fixed, and the nav is position: fixed so its centre line is scroll-invariant. Only scrollY moves.

So the measurement moves into measureBackdrops(), called once, and the per-frame path becomes a loop over a cached array of {top, bottom, luminance} bands plus one scrollY read — which does not force layout.

DOM reads per frame: from 1 query + 2 + 2N to zero.

Staleness handled where it actually happens

Rather than re-reading everything constantly:

• resize re-measures — and scroll no longer shares that handler, since the two sharing it is exactly how the measurement ended up in the scroll path
• a ResizeObserver on <main> catches the document changing height without a resize, which it does when the terrain canvas and images settle after first paint

Both fire rarely and neither fires during a scroll. The listener and observer are hoisted to the teardown's scope so they're removed on every astro:page-load — otherwise each View Transition would stack another observer on the same <main>.

Behaviour is unchanged

Same 0.35 luminance split, same descent-fraction fallback, same DARK_FROM threshold. This changes only when the work happens. The contrast fix it was written for still stands (nav labels 3.98:1 → 11.8–13.4:1); it just no longer costs a layout per frame to keep.

Gates

npm run build clean, 813 tests green.

Not measured, and that's worth stating: no browser pass. The headless fleet this branch leaned on took the owner's machine down and they asked for no more browsers, so the claim here is structural — a read count from the code, not a frame time. Best confirmed by the owner's eye on prod, or one profiling run when that's welcome again.

🤖 Generated with Claude Code