Merge pull request #3824 from rommapp/fix/v2-gallery-batch-hydration-cap

fix(v2): batch gallery hydration into windows and cap concurrency

Author: gantoine

frontend/src/services/api/rom.ts

@@ -183,9 +183,10 @@ export interface GetRomsParams {
   playerCountsLogic?: string | null;
   metadataProvidersLogic?: string | null;
   tagsLogic?: string | null;
-  // Skip the char index / filter-value aggregations server-side
+  // Skip the char index / filter-value / id-index aggregations server-side
   withCharIndex?: boolean;
   withFilterValues?: boolean;
+  withRomIdIndex?: boolean;
   // Cancel an in-flight request
   signal?: AbortSignal;
 }
@@ -236,6 +237,7 @@ async function getRoms({
   tagsLogic = null,
   withCharIndex = undefined,
   withFilterValues = undefined,
+  withRomIdIndex = undefined,
   signal = undefined,
 }: GetRomsParams) {
   const params = {
@@ -346,6 +348,9 @@ async function getRoms({
     ...(withFilterValues !== undefined
       ? { with_filter_values: withFilterValues }
       : {}),
+    ...(withRomIdIndex !== undefined
+      ? { with_rom_id_index: withRomIdIndex }
+      : {}),
   };
 
   return api.get<GetRomsResponse>(`/roms`, {

frontend/src/v2/components/Gallery/GalleryShell.vue

@@ -554,23 +554,20 @@ const currentLetter = computed<string>(() => {
   return "";
 });
 
-// Per-card viewport-driven fetch. The shell tracks which positions are
-// currently visible (from the rows in `viewportRange`) and keeps
-// `byPosition` in sync via per-card `GET /roms/{id}/simple` calls — pure
-// by-id lookups on the backend, much faster than the paginated
-// `getRoms(limit/offset)` pipeline. Each fetch is independent, so covers
-// stream in as their individual responses land.
+// Viewport-driven windowed fetch. The shell collects which positions are
+// currently visible (from the rows in `viewportRange`, for both grid and
+// list layouts) and hands them to the store's `syncVisibleWindows`, which
+// aligns each to its shared 72-item window, dedupes, starts the windows
+// covering the viewport, and cancels any that scrolled out of view.
+// Batching visible cards into a handful of paginated `getRoms` requests
+// (instead of one request per card) is what keeps a fast scroll — or two
+// users scrolling at once — from flooding the single-worker backend.
 //
-// No idle-time prefetch: when the user stops scrolling, no new requests
-// are fired. Cards already in the viewport that are still missing keep
-// loading; everything off-screen waits until the user scrolls there.
-//
-// Cancellation: positions that leave the viewport while their fetch is in
-// flight are aborted via `cancelFetchAt`. A small debounce on viewport
-// changes prevents fire-and-cancel storms during smooth scrolling — only
-// when the viewport settles for `FETCH_DEBOUNCE_MS` do we sync.
+// A small debounce on viewport changes prevents fire-and-cancel storms
+// during smooth scrolling — only when the viewport settles for
+// `FETCH_DEBOUNCE_MS` do we sync. Both layouts share this one path, so the
+// list is debounced too (list rows no longer self-fetch on mount).
 const FETCH_DEBOUNCE_MS = 80;
-const visiblePositions = new Set<number>();
 let fetchDebounceTimer: ReturnType<typeof setTimeout> | null = null;
 let pendingRange: { first: number; last: number } | null = null;
 
@@ -583,34 +580,20 @@ function collectVisiblePositions(range: {
   const items = virtualItems.value;
   for (let i = range.first; i <= range.last; i++) {
     const it = items[i];
-    if (!it || it.kind !== "row") continue;
-    for (let p = it.startPosition; p < it.endPosition; p++) out.add(p);
+    if (!it) continue;
+    // Grid rows fan out into a contiguous run of card positions; list rows
+    // carry a single position each.
+    if (it.kind === "row") {
+      for (let p = it.startPosition; p < it.endPosition; p++) out.add(p);
+    } else if (it.kind === "list-row") {
+      out.add(it.position);
+    }
   }
   return out;
 }
 
 function syncFetches(range: { first: number; last: number }) {
-  const next = collectVisiblePositions(range);
-
-  // Cancel positions that left the viewport before their fetch resolved.
-  // The store's per-position controller handles the network abort;
-  // idempotent if nothing was in flight.
-  for (const p of visiblePositions) {
-    if (!next.has(p) && !galleryRoms.byPosition.has(p)) {
-      galleryRoms.cancelFetchAt(p);
-    }
-  }
-
-  // Fire per-card fetches for positions that just entered. The store
-  // dedupes against in-flight + already-loaded internally.
-  for (const p of next) {
-    if (!galleryRoms.byPosition.has(p)) {
-      void galleryRoms.fetchRomAt(p);
-    }
-  }
-
-  visiblePositions.clear();
-  for (const p of next) visiblePositions.add(p);
+  galleryRoms.syncVisibleWindows(collectVisiblePositions(range));
 }
 
 function scheduleFetchSync(range: { first: number; last: number }) {
@@ -663,9 +646,9 @@ function scrollToLetter(letter: string) {
     toolbarHeight.value + (layout.value === "list" ? LIST_HEADER_HEIGHT : 0);
   scrollerRef.value?.scrollToIndex(idx, { smooth: true, stickyOffset });
   // The viewport-driven fetch sync handles the destination — once the
-  // smooth scroll settles, `update:viewportRange` fires and the cards
-  // at the landing zone start loading via `syncFetches` (grid) or via
-  // each `GameListRow`'s onMounted (list). No manual prefetch needed.
+  // smooth scroll settles, `update:viewportRange` fires and the windows at
+  // the landing zone start loading via `syncFetches` (both layouts). No
+  // manual prefetch needed.
 }
 
 // ── Search filter (debounced) ───────────────────────────────────────
@@ -792,12 +775,10 @@ onBeforeUnmount(() => {
   gallerySelection.clear();
   if (searchDebounce) clearTimeout(searchDebounce);
   if (fetchDebounceTimer) clearTimeout(fetchDebounceTimer);
-  // When leaving the gallery entirely, stop any per-card fetches still in
-  // flight so navigating away mid-scroll doesn't keep the network /
-  // backend busy. Keeps the hydrated cache so returning to the same
-  // gallery is instant.
+  // When leaving the gallery entirely, stop any in-flight window fetches so
+  // navigating away mid-scroll doesn't keep the network / backend busy.
+  // Keeps the hydrated cache so returning to the same gallery is instant.
   galleryRoms.abortInFlight();
-  visiblePositions.clear();
   inflowResizeObserver?.disconnect();
   inflowResizeObserver = null;
   // Drop the debug stats so the overlay doesn't show stale gallery numbers

frontend/src/v2/components/Gallery/GameListRow.vue

@@ -2,16 +2,6 @@
 // GameListRow — single row of the list-mode gallery.
 //
 // Owns:
-//   * Per-row lazy fetch: a watch fires `fetchRomAt(position)` whenever
-//     the row is missing its rom but the store knows the id — covering
-//     both mount ("entered the overscan window") and a context refresh
-//     that clears `byPosition` under a still-mounted row. onUnmount aborts
-//     the fetch via `cancelFetchAt(position)` so a fast scroll past
-//     mid-flight doesn't keep server work queued for invisible rows.
-//     Mirror of the per-card grid flow, with the same "row mount =
-//     entered viewport" contract via the shell's RVirtualScroller
-//     overscan window.
-//
 //   * Skeleton ↔ real swap — when `getRomAt(position)` returns null the
 //     row paints skeleton placeholders in every column; once the fetch
 //     resolves it flips to the real cells. Same row height in both
@@ -29,7 +19,7 @@ import {
   RSkeletonBlock,
   RTooltip,
 } from "@v2/lib";
-import { computed, onBeforeUnmount, watch } from "vue";
+import { computed } from "vue";
 import { useI18n } from "vue-i18n";
 import { useRouter } from "vue-router";
 import storePlatforms from "@/stores/platforms";
@@ -59,13 +49,13 @@ defineOptions({ inheritAttrs: false });
 const PILLS_VISIBLE = 4;
 
 interface Props {
-  /** Absolute position in the active gallery (0-indexed). Drives the
-   * row's per-row fetch + serves as the lookup key into the store's
-   * `byPosition` map. Pass either this or `rom`, not both. */
+  /** Absolute position in the active gallery (0-indexed). Serves as the
+   * lookup key into the store's `byPosition` map; the shell drives the
+   * windowed fetch that fills it. Pass either this or `rom`, not both. */
   position?: number;
   /** Static ROM data — used by non-gallery surfaces (Settings → Missing
    * games) that already own the rom list. When provided, the row skips
-   * the galleryRoms position lookup and the per-row lazy fetch. */
+   * the galleryRoms position lookup. */
   rom?: SimpleRom | null;
   /** Cover variant — when the browser supports webp the thumb URL is
    * rewritten to .webp before the request. Wired from the shell so the
@@ -263,39 +253,6 @@ function onRowPointerEnd() {
   if (isStatic.value) return;
   selectionInput.handlePointerEnd();
 }
-
-// Kick the per-row fetch whenever this position is missing its rom but
-// the store knows its id. This covers both mount ("entered the overscan
-// window") and a context refresh: a filter / search / sort / scan clears
-// `byPosition` and repopulates `romIdIndex`, but the row can stay mounted
-// at the same position — without this watch it would sit on skeletons
-// until it scrolled out and remounted. The store dedupes against
-// in-flight + already-loaded, so re-runs are cheap. Guarding on the id
-// (not just null rom) also re-fetches when a resort lands a different rom
-// at the same position.
-watch(
-  () => {
-    if (isStatic.value || props.position === undefined) return null;
-    if (galleryRoms.byPosition.has(props.position)) return null;
-    return galleryRoms.romIdIndex[props.position] ?? null;
-  },
-  (romId) => {
-    if (romId != null && props.position !== undefined) {
-      void galleryRoms.fetchRomAt(props.position);
-    }
-  },
-  { immediate: true },
-);
-
-onBeforeUnmount(() => {
-  if (isStatic.value || props.position === undefined) return;
-  // Left the overscan window before the fetch resolved — abort so the
-  // server doesn't keep building a row the user already scrolled past.
-  // Idempotent if nothing was in flight.
-  if (!galleryRoms.byPosition.has(props.position)) {
-    galleryRoms.cancelFetchAt(props.position);
-  }
-});
 </script>
 
 <template>