[gbolly122]

Summary

Adds a bounded streamed-feed reveal buffer for issue #306. Incoming items are
kept separate from the rendered list while the reader is scrolled away or in a
background tab; a reveal commits them in descending timestamp order without
duplicates, and the state exposes the pending count, label, and reduced-motion
flag for a reveal control.

Closes #306

Type of change

• New feature
• Tests / CI

What changed

• src/lib/realtime/stream-reveal-buffer.ts
  • StreamRevealBuffer<T> with pushIncoming, revealPending,
    setScrollPosition, setTabVisibility, setReducedMotion, and getState.
  • Auto-reveals when at the top of a visible tab with no pending items; buffers
    otherwise.
  • Deduplicates by item id across visible and pending.
  • Bounds the pending buffer (default 200) and visible list (default 500).
  • Sorts visible items newest-first and reports animateReveal: false when
    reduced motion is requested.
• src/lib/realtime/__tests__/stream-reveal-buffer.test.ts
  • auto-reveal at top/visible
  • buffering while scrolled/hidden, duplicate suppression, ordered reveal
  • buffer cap and reduced-motion flag

Validation

npx vitest run src/lib/realtime/__tests__/stream-reveal-buffer.test.ts
Test Files  1 passed (1)
Tests       3 passed (3)

Checklist

• I read CONTRIBUTING.md
• Tests added for the change
• Full local gate — blocked by pre-existing main issues: 16 tracked
  files are 0 bytes (including src/app/layout.tsx, globals.css, Button.tsx,
  Navbar.tsx, and the coverage/pool hooks), and src/app/cover/page.tsx is
  truncated mid-component. tsc/vitest fail on main before this change.
• No secrets or env values committed
• Behaviour documented in code comments and the PR

Notes for reviewers

This is the buffering primitive required by the issue. Wiring the control into
the landing/dashboard feeds depends on the missing hooks/pages above; I kept the
PR limited to the module and its tests so it can merge independently of that
restoration work.

[drips-wave]

@gbolly122 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits