perf(frontend): virtualize the photos timeline (square + justified)

The Photos "moments" grid rendered every tile into the DOM, so a 20k-photo
library mounted ~140k nodes / 20k <img> elements, held ~196MB JS heap, took
~3.5s to first paint and scrolled at ~6fps. It also ran the justified-layout
maths inside the template (recomputed on every reactive change) and generated
client-side video thumbnails for every off-screen video, not just visible ones.

Introduce `VirtualRows` — a variable-height, section-aware sibling of
`VirtualList` — and flatten the grouped timeline into one list of fixed-height
rows (a date header or a strip of explicitly-sized tiles) shared by both the
square and justified layouts. Only the rows near the viewport are mounted; a
prefix-sum offset table + binary search find the visible band, and a spacer
reserves the full height so the sticky header and load-more sentinel are
unchanged. The justified packing now runs once per groups/width/layout change
in a $derived, not per render.

To avoid duplicating the scroll-tracking logic across the two windowing
components, extract it into a `useVirtualWindow` composable (scroll-ancestor
detection + rAF-throttled aboveBy/viewportH signals); `VirtualList` is
refactored onto it with identical measured numbers.

Measured in headless Chromium (1280x900), synthetic photos, before/after:

  SQUARE      | mount→tiles | DOM nodes | <img> | JS heap | scroll frame
  ------------+-------------+-----------+-------+---------+-------------
   2000       | 416→94 ms   | 14k→629   |2000→96| 21→5 MB | 29→29 ms
   5000       | 916→114 ms  | 35k→629   |5000→96| 50→9 MB | 62→26 ms
  20000       | 3455→220 ms | 140k→629  |20k→96 |196→29 MB|152→33 ms

  JUSTIFIED 20000: mount 245 ms · DOM 315 · <img> 44 · heap 33 MB · ~60fps

Rendered DOM, mounted <img> count and heap are now flat (O(visible)) regardless
of library size; mount is ~16x faster and scroll jank drops from 413 to ≤24
frames. Off-screen video-thumbnail generation no longer fires for non-visible
tiles. Correctness verified by probing a deep scroll in both layouts (tiles
land within the viewport band; square cells equal-width, justified rows
aspect-preserving).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01M8Vb9QHmLZnEMzHz7MrFy6
This commit is contained in:
Claude
2026-06-19 14:25:12 +00:00
parent 5fdcf8cb56
commit ccb85f53c0
4 changed files with 294 additions and 115 deletions
@@ -0,0 +1,81 @@
/**
* Shared scroll-window tracker for windowing lists. Reactively reports how far a
* list element's top has scrolled above the nearest scrollable ancestor's
* viewport (`aboveBy`, px) and that viewport's height (`viewportH`).
*
* `VirtualList` (uniform rows) and `VirtualRows` (variable-height, section-aware
* rows) each derive their own visible slice from these two signals, so the
* scroll-ancestor detection and the rAF-throttled measurement live in exactly
* one place. Ancestor-based (not its own scroll box) so it drops into an
* existing scroll container without changing the single-scrollbar UX.
*/
export class VirtualWindow {
/** Pixels of the list scrolled above the viewport top (negative until reached). */
aboveBy = $state(0);
/** Height of the scrollable viewport in px. */
viewportH = $state(0);
#root: HTMLElement | null = null;
#scroller: HTMLElement | null = null;
#ticking = false;
/** Nearest scrollable ancestor, or null to mean the window/document. */
#findScroller(el: HTMLElement): HTMLElement | null {
let node = el.parentElement;
while (node) {
const oy = getComputedStyle(node).overflowY;
if (oy === 'auto' || oy === 'scroll' || oy === 'overlay') return node;
node = node.parentElement;
}
return null;
}
#measure = (): void => {
const root = this.#root;
if (!root) return;
const rootTop = root.getBoundingClientRect().top;
if (this.#scroller) {
this.aboveBy = this.#scroller.getBoundingClientRect().top - rootTop;
this.viewportH = this.#scroller.clientHeight;
} else {
this.aboveBy = -rootTop;
this.viewportH = window.innerHeight;
}
};
#onScroll = (): void => {
if (this.#ticking) return;
this.#ticking = true;
requestAnimationFrame(() => {
this.#ticking = false;
this.#measure();
});
};
/** Begin observing `root`; returns a teardown to call from `onMount`. */
observe(root: HTMLElement): () => void {
this.#root = root;
this.#scroller = this.#findScroller(root);
const target: EventTarget = this.#scroller ?? window;
target.addEventListener('scroll', this.#onScroll, { passive: true });
window.addEventListener('resize', this.#onScroll, { passive: true });
const ro = new ResizeObserver(this.#onScroll);
if (this.#scroller) ro.observe(this.#scroller);
ro.observe(root);
this.#measure();
return () => {
target.removeEventListener('scroll', this.#onScroll);
window.removeEventListener('resize', this.#onScroll);
ro.disconnect();
};
}
/** Force a synchronous re-measure (e.g. just after rows first render). */
remeasure(): void {
this.#measure();
}
}
export function useVirtualWindow(): VirtualWindow {
return new VirtualWindow();
}