perf(back-to-top): keep button mounted, swap mount/unmount for opacity

The previous `{#if showGlobalBackToTop}` block mounted/unmounted a
`position: fixed` button (with box-shadow) every time the user scrolled
past the 800px threshold. On 4K under software compositing the
unmount path (going up across the threshold) registered as a visible
hiccup — the user perceived it as a stutter halfway through scrolling
back to the top.

The button is now always mounted. Visibility is driven by a `.hidden`
class with `opacity: 0; pointer-events: none` and a 150ms opacity
transition. `tabindex` and `aria-hidden` reflect the boolean for a11y.

Also rewrites the scroll listener: previously each scroll event wrote
to a `$state<number>` and triggered a `$derived` recompute (60-120
times/second during active scrolling). Now the listener
rAF-coalesces and only assigns when the threshold actually flips.
Default scroll cost drops from "per-event reactive churn" to
"one boolean flip per threshold cross".

cc
This commit is contained in:
vicrodh committed 2026-05-11 22:38:12 -06:00
1 parent e477d0ce8e
commit 67118b21e4
1 file changed
+56 -17
+56 -17
View File
@@ -601,30 +601,52 @@
let isAutoUpdating = $state(false); let isAutoUpdating = $state(false);
let autoUpdateProgress = $state<AutoUpdateProgress>({ state: 'checking' }); let autoUpdateProgress = $state<AutoUpdateProgress>({ state: 'checking' });
// Global back-to-top button // Global back-to-top button.
//
// The previous implementation registered a capture-phase scroll listener
// on .main-content that wrote `globalScrollTop = target.scrollTop` to a
// `$state` on every scroll event, and used `$derived(globalScrollTop > 800)`
// to gate the button. That fired Svelte reactivity 60-120 times/second
// during scroll, and when the derived crossed the 800px threshold the
// button mount/unmount work added an extra repaint that registered as
// a visible hiccup at 4K under software compositing — especially
// pronounced when scrolling up (button unmount).
//
// New impl: track only the boolean visibility state, coalesce reads via
// requestAnimationFrame, and only assign when the threshold flips. This
// takes the per-scroll-tick reactive work from "every event" down to
// "at most once per animation frame, only on state change".
let mainContentEl: HTMLElement | null = $state(null); let mainContentEl: HTMLElement | null = $state(null);
let globalScrollTop = $state(0); let showGlobalBackToTop = $state(false);
let activeScrollTarget: HTMLElement | null = null; let activeScrollTarget: HTMLElement | null = null;
const showGlobalBackToTop = $derived(globalScrollTop > 800); const BACK_TO_TOP_THRESHOLD_PX = 800;
$effect(() => { $effect(() => {
if (!mainContentEl) return; if (!mainContentEl) return;
let rafId = 0;
const handler = (e: Event) => { const handler = (e: Event) => {
const target = e.target as HTMLElement; const target = e.target as HTMLElement;
if (target !== mainContentEl) { if (target === mainContentEl) return;
globalScrollTop = target.scrollTop; activeScrollTarget = target;
activeScrollTarget = target; if (rafId !== 0) return;
} rafId = requestAnimationFrame(() => {
rafId = 0;
const next = target.scrollTop > BACK_TO_TOP_THRESHOLD_PX;
if (next !== showGlobalBackToTop) showGlobalBackToTop = next;
});
}; };
mainContentEl.addEventListener('scroll', handler, true); mainContentEl.addEventListener('scroll', handler, true);
return () => mainContentEl?.removeEventListener('scroll', handler, true); return () => {
mainContentEl?.removeEventListener('scroll', handler, true);
if (rafId !== 0) cancelAnimationFrame(rafId);
};
}); });
// Reset scroll state on view or item change (but not on back/forward — that restores saved position) // Reset scroll state on view or item change (but not on back/forward — that restores saved position)
$effect(() => { $effect(() => {
void activeView; void activeView;
void currentNavItemId; void currentNavItemId;
globalScrollTop = 0; showGlobalBackToTop = false;
// Scroll to top for forward navigation (not back/forward, which restores saved position) // Scroll to top for forward navigation (not back/forward, which restores saved position)
if (!isBackForward()) { if (!isBackForward()) {
tick().then(() => { tick().then(() => {
@@ -4927,7 +4949,7 @@
// Save scroll position of the view we're leaving // Save scroll position of the view we're leaving
if (prevView !== navState.activeView || prevItemId !== navState.activeItemId) { if (prevView !== navState.activeView || prevItemId !== navState.activeItemId) {
const scrollTopToSave = activeScrollTarget?.scrollTop ?? globalScrollTop; const scrollTopToSave = activeScrollTarget?.scrollTop ?? 0;
saveScrollPosition(prevView, scrollTopToSave, prevItemId); saveScrollPosition(prevView, scrollTopToSave, prevItemId);
} }
@@ -4946,7 +4968,7 @@
tick().then(() => { tick().then(() => {
if (activeScrollTarget) { if (activeScrollTarget) {
activeScrollTarget.scrollTop = savedScroll; activeScrollTarget.scrollTop = savedScroll;
globalScrollTop = savedScroll; showGlobalBackToTop = savedScroll > BACK_TO_TOP_THRESHOLD_PX;
} }
}); });
} }
@@ -6642,11 +6664,19 @@
{/if} {/if}
</main> </main>
{#if showGlobalBackToTop} <!-- Always mounted to avoid the mount/unmount paint cost when crossing
<button class="back-to-top-global" onclick={globalScrollToTop} title="Back to top"> the 800px threshold (visible hiccup on scroll-up at 4K under software
<ChevronUp size={20} /> compositing). Visibility is toggled via class + opacity transition. -->
</button> <button
{/if} class="back-to-top-global"
class:hidden={!showGlobalBackToTop}
onclick={globalScrollToTop}
title="Back to top"
tabindex={showGlobalBackToTop ? 0 : -1}
aria-hidden={!showGlobalBackToTop}
>
<ChevronUp size={20} />
</button>
<!-- Lyrics Sidebar --> <!-- Lyrics Sidebar -->
{#if lyricsSidebarVisible && !isQueueOpen} {#if lyricsSidebarVisible && !isQueueOpen}
@@ -7263,10 +7293,19 @@
align-items: center; align-items: center;
justify-content: center; justify-content: center;
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.3); box-shadow: 0 2px 8px rgba(0, 0, 0, 0.3);
transition: background 150ms ease, color 150ms ease; /* Opacity-only transition for show/hide so the button can stay mounted
at all times. Mounting/unmounting a position:fixed element on every
scroll-threshold crossing forced an extra paint event that the user
perceived as a stutter, especially on scroll-up at 4K. */
transition: background 150ms ease, color 150ms ease, opacity 150ms ease;
z-index: 200; z-index: 200;
} }
.back-to-top-global.hidden {
opacity: 0;
pointer-events: none;
}
.back-to-top-global:hover { .back-to-top-global:hover {
background: var(--bg-tertiary); background: var(--bg-tertiary);
color: var(--text-primary); color: var(--text-primary);