fix(web): stop repeated scroll drift after deep timeline axis jumps #939

Merged
chris merged 1 commit from fix/timeline-jump-drift into main 2026-09-28 10:12:39 +02:00
Owner

Summary

After a deep axis jump the timeline rendered as placeholder walls and then the scrollbar visibly jumped repeatedly (once per network round trip) until the view settled at the top of the library.

Root cause: schedulePreviousDaysRevealCheck used inverted viewport geometry — sentinel.top < innerHeight + 900 is trivially true when the top reveal sentinel sits above the viewport (its bottom is negative). After every hydration batch the check misfired, revealPreviousDays prepended 8 day sections above the viewport without a mutation-time scroll anchor (protection PR #895 had removed), displacing the viewport and re-triggering the check: a deterministic feedback loop until visibleDayStartIndex hit 0.

Changes

  • extract reveal-margin predicate into timelineReveal.ts (sentinelWithinRevealMargin: requires rect.bottom >= 0) + 8 vitest cases
  • capture/restore the scroll anchor around the visible-window mutation in revealPreviousDays, composing with the hydrateDays merge-time anchor from #895 (delta-from-fresh-capture, never absolute Y)
  • suppress observer-driven hydration/reveals while jumpingDayKey is set; clear it in .finally
  • disable native scroll anchoring on the timeline route (html:has(.timeline-owns-scroll) { overflow-anchor: none }) so JS is the single scroll owner
  • skip debounced state persist while jumping/hydrating (checked at schedule + fire time)
  • prefer a viewport-intersecting tile in currentScrollAnchor
  • Playwright regression test (proven: fails on main with window drift 20→0, passes with fix)
  • bump apps/web 0.0.25 → 0.0.26

Verification

  • npm run test:unit: 27 passed
  • npx playwright test tests/timeline.spec.ts: 81 passed, 0 failed (desktop+mobile)
  • npm run check: 0 errors (20 pre-existing a11y warnings)
  • Regression proof: new test fails on unpatched main, passes patched
## Summary After a deep axis jump the timeline rendered as placeholder walls and then the scrollbar visibly jumped repeatedly (once per network round trip) until the view settled at the top of the library. **Root cause:** `schedulePreviousDaysRevealCheck` used inverted viewport geometry — `sentinel.top < innerHeight + 900` is trivially true when the top reveal sentinel sits *above* the viewport (its bottom is negative). After every hydration batch the check misfired, `revealPreviousDays` prepended 8 day sections above the viewport **without a mutation-time scroll anchor** (protection PR #895 had removed), displacing the viewport and re-triggering the check: a deterministic feedback loop until `visibleDayStartIndex` hit 0. ## Changes - extract reveal-margin predicate into `timelineReveal.ts` (`sentinelWithinRevealMargin`: requires `rect.bottom >= 0`) + 8 vitest cases - capture/restore the scroll anchor around the visible-window mutation in `revealPreviousDays`, composing with the hydrateDays merge-time anchor from #895 (delta-from-fresh-capture, never absolute Y) - suppress observer-driven hydration/reveals while `jumpingDayKey` is set; clear it in `.finally` - disable native scroll anchoring on the timeline route (`html:has(.timeline-owns-scroll) { overflow-anchor: none }`) so JS is the single scroll owner - skip debounced state persist while jumping/hydrating (checked at schedule + fire time) - prefer a viewport-intersecting tile in `currentScrollAnchor` - Playwright regression test (proven: fails on main with window drift 20→0, passes with fix) - bump apps/web 0.0.25 → 0.0.26 ## Verification - `npm run test:unit`: 27 passed - `npx playwright test tests/timeline.spec.ts`: 81 passed, 0 failed (desktop+mobile) - `npm run check`: 0 errors (20 pre-existing a11y warnings) - Regression proof: new test fails on unpatched main, passes patched
fix(web): stop repeated scroll drift after deep timeline axis jumps
All checks were successful
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Detect changed services and test scopes (push) Successful in 3s
Build and Deploy / Android unit tests and debug APK (push) Has been skipped
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Smoke web (push) Has been skipped
Build and Deploy / Smoke ML worker (push) Has been skipped
Build and Deploy / Smoke people worker (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Deploy postgres (push) Has been skipped
Build and Deploy / Build API image (push) Has been skipped
Build and Deploy / Build media worker image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Build web image (push) Has been skipped
Build and Deploy / Deploy API (push) Has been skipped
Build and Deploy / Deploy web (push) Has been skipped
Build and Deploy / Deploy media worker (push) Has been skipped
Build and Deploy / Deploy ML worker (push) Has been skipped
Build and Deploy / Deploy plants worker (push) Has been skipped
Build and Deploy / Deploy people worker (push) Has been skipped
Build and Deploy / Deploy converter worker (push) Has been skipped
Build and Deploy / Clean Docker build artifacts (push) Has been skipped
Build and Deploy / Run scoped PR tests (push) Successful in 3m38s
9c05c43842
After a deep axis jump the top reveal sentinel sits above the viewport and
the reveal check's inverted geometry (top < margin, no bottom >= 0 test)
misfired on every hydration batch: revealPreviousDays prepended 8 day
sections above the viewport with no mutation-time anchor, displacing the
viewport once per network round trip until visibleDayStartIndex hit 0 —
the reported seconds-apart scrollbar jumps.

- extract the reveal-margin predicate into timelineReveal.ts
  (sentinelWithinRevealMargin: requires rect.bottom >= 0 && rect.top <
  viewportHeight + 900) with unit tests
- capture + restore the scroll anchor around the visible-window mutation
  in revealPreviousDays, composing with the hydrateDays merge-time anchor
- suppress dayHydrationObserver, revealNextDays and the reveal check while
  jumpingDayKey is set; clear jumpingDayKey in .finally so a throw cannot
  wedge the settle gate; reset pendingPreviousDaysReveal on jump start
- disable native scroll anchoring on the timeline route
  (html:has(.timeline-owns-scroll) { overflow-anchor: none }) — JS owns
  all scroll compensation there
- skip the debounced state persist while jumping/hydrating (checked at
  schedule and fire time); the jump persists once at settle
- prefer a viewport-intersecting tile in currentScrollAnchor over the
  first document-order tile below the top edge
- add a Playwright regression test (fails on main: window drifts 20 -> 0)
- bump apps/web 0.0.25 -> 0.0.26
chris merged commit a5c70e22e8 into main 2026-09-28 10:12:39 +02:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
chris/memories!939
No description provided.