ux(showcase): pipeline fetches in-order, chunk size 3, keep the trickle

Operator-flagged 2026-05-30 (round 3): the all-parallel fetch was fast
but could let later chunks arrive ahead of earlier ones — even when
each chunk is a random sample, that "later chunk loads first" risk made
the load order non-deterministic. And the original goal behind asking
for batching was a faster first-image-on-screen, which neither sequen-
tial nor parallel really addressed cleanly.

Switched the loadInitial flow to a PIPELINE:
- Only one fetch in flight at any moment (in-order arrival, no race).
- The NEXT fetch kicks off as soon as the current one resolves (NOT
  after its trickle finishes), so the next RTT overlaps the visible
  trickle window — round-trips are hidden behind the animation cadence.
- PAGE 5 → 3 + INITIAL_BATCHES 12 → 20 (total still 60). Smaller chunk
  → first chunk's items appear sooner (a chunk of 3 trickles in 240ms,
  well within one RTT, so by the time chunk 2 is in-hand the first
  trickle is just finishing).

Trickle, sequence-token guard, and infinite-scroll behaviour unchanged.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-05-30 22:52:55 -04:00
parent 9cd6d09e60
commit e3a7aff7a3
+39 -27
View File
@@ -2,20 +2,22 @@ import { defineStore } from 'pinia'
import { ref, computed } from 'vue'
import { useApi } from '../composables/useApi.js'
// Operator-flagged 2026-05-30 (round 2): the per-batch-then-pause cadence
// from the original sequential-fetch implementation still felt "chunky" —
// 5 items appear together, then the API round-trip pauses for ~200 ms,
// then another 5 burst in. To smooth that:
// 1. Fire all INITIAL_BATCHES fetches IN PARALLEL — collapses the per-
// batch round-trip gap (12 concurrent calls return in ~1 RTT instead
// of 12 sequential RTTs).
// 2. Trickle responses into images.value one item at a time with a
// small APPEND_DELAY_MS delay between each — the user sees a steady
// cadence rather than per-batch bursts.
// fetchPage (the infinite-scroll path) reuses the same trickle so its
// 5-item appends also cascade one-by-one instead of popping in together.
const PAGE = 5
const INITIAL_BATCHES = 12
// Operator-flagged 2026-05-30 (round 3): the all-parallel fetch was fast
// but risked later chunks arriving first — undesirable even when each
// chunk is a random sample. Switched to a PIPELINE: only one fetch in
// flight at any moment, but the next fetch kicks off as soon as the
// previous one resolves (NOT after its trickle finishes). The next RTT
// overlaps with the current batch's trickle, hiding the per-batch
// round-trip behind the visible animation cadence. Responses arrive in
// fire-order, so no out-of-order rendering surprises.
//
// Smaller PAGE (3 vs 5) → first chunk's items appear sooner: a chunk of
// 3 trickles in 240 ms, well within one RTT, so by the time chunk 2 is
// in-hand the trickle is just finishing. Total wall-clock is roughly
// RTT + N × max(trickle_time, RTT); APPEND_DELAY_MS keeps the visible
// cadence smooth throughout.
const PAGE = 3
const INITIAL_BATCHES = 20
const APPEND_DELAY_MS = 80 // ≈ the MasonryGrid stagger animation (70 ms)
@@ -64,10 +66,19 @@ export const useShowcaseStore = defineStore('showcase', () => {
}
}
// Reset state, fire INITIAL_BATCHES fetches in parallel, then trickle
// each response's items into images.value at APPEND_DELAY_MS cadence.
// Total wall-clock = ~1 RTT (parallel) + N items × APPEND_DELAY_MS;
// the user sees a smooth steady stream throughout.
function _fetchOne() {
return api.get('/api/showcase', { params: { limit: PAGE } }).catch(e => {
error.value = error.value || (e.message || String(e))
return null
})
}
// Reset state and pipeline INITIAL_BATCHES fetches: only one in flight
// at a time, but kick off the next one as soon as the previous resolves
// (NOT after its trickle finishes), so the next RTT runs concurrently
// with the current batch's trickle. Responses arrive in fire-order, so
// items always render in the order they were fetched — no out-of-order
// surprises from parallel races.
async function loadInitial() {
_seq += 1
const mySeq = _seq
@@ -77,16 +88,17 @@ export const useShowcaseStore = defineStore('showcase', () => {
error.value = null
loading.value = true
try {
const fetches = Array.from({ length: INITIAL_BATCHES }, () =>
api.get('/api/showcase', { params: { limit: PAGE } }).catch(e => {
error.value = error.value || (e.message || String(e))
return null
})
)
for (const fetchPromise of fetches) {
let nextFetch = _fetchOne()
for (let i = 0; i < INITIAL_BATCHES; i++) {
if (mySeq !== _seq) return
const body = await fetchPromise
if (body && body.images) await _trickleAppend(body.images, mySeq)
const body = await nextFetch
// Fire the NEXT fetch immediately so its RTT overlaps the trickle.
if (i + 1 < INITIAL_BATCHES) nextFetch = _fetchOne()
if (!body || !body.images || body.images.length === 0) {
exhausted.value = true
break
}
await _trickleAppend(body.images, mySeq)
}
if (mySeq === _seq && images.value.length === 0) exhausted.value = true
} finally {