feat(ui): jump to first unread message + unread divider

[sanity]

Problem

User request via Matrix (2026-07-23):

Consider adding a button to jump to the last message before you opened River. Otherwise I have to figure out where to resume reading.

River already tracks the data this needs. The gap is purely UI.

What exists:

• RoomData.last_read_message_id (ui/src/room_data.rs:53), a per-room marker persisted to delegate storage, advanced when the user opens the room, when a message arrives while viewing, and on tab hide.
• It already drives count_unread_in_room_data (ui/src/components/app/document_title.rs:172), the document-title badge, the room-list badge (ui/src/components/room_list.rs:213), and the mobile hamburger badge.

What is missing:

• Switching rooms unconditionally force-scrolls to the newest message (ui/src/components/conversation.rs:1305-1318, added by Suggestions for UI improvements for mobile and touch users #402). No code path scrolls to the first unread, and there is no divider in the scrollback.

So the marker is maintained and counted, then ignored when deciding where to put the reader.

Proposal

1. Render an unread divider ("New messages") at the first message after last_read_message_id.
2. On room switch, if unread > 0, scroll to the divider instead of the bottom.
3. Keep the existing scroll-to-latest button (conversation.rs:2238-2268) for returning to the present.

This is the Slack / Discord / Element pattern, and it is a concrete implementation of the first bullet of #70.

Performance constraints

PR #458 just fixed mobile jank caused by an O(history) use_memo re-running over the entire message list on every ROOMS mutation. Do not reintroduce that shape.

• Freeze the divider boundary at room-open, in a signal. Do not derive it from a memo over ROOMS. Two independent reasons: recomputing on every mutation re-does O(history) work on every sync tick, reaction and inbound message; and a live boundary would slide away as you read, when the divider should stay put (Slack and Discord both freeze it).
• The boundary scan is O(<=100), since max_recent_messages defaults to 100 (common/src/room_state/configuration.rs:179), and it duplicates work count_unread_in_room_data already performs. Worth sharing rather than adding a second pass.
• The divider is one extra DOM node and must not invalidate the per-message HTML cache added in perf(ui): memoize per-message HTML to fix mobile chat jank #458.

Edge cases

• Pruned marker. apply_delta drains the oldest messages beyond max_recent_messages (common/src/room_state/message.rs:229), so the marked message can be evicted from the ring buffer. count_unread_in_room_data already falls back to treating everything as unread (document_title.rs:176-184, pinned by pruned_marker_falls_back_to_all_other_authored at 692-704). Open question: should the divider then sit at the top of the buffer, or be suppressed entirely? Suppressing is probably less confusing, since "everything here is new" is rarely true and the top of a 100-message buffer is an arbitrary place to anchor.
• Zero unread. No divider, keep the current scroll-to-bottom.
• Direct messages track last-seen separately and in memory only (DM_LAST_SEEN, ui/src/components/direct_messages.rs:42, seeded once per session), so DMs are out of scope here unless we want parity in the same pass.

Blocked on a decision in #446

mark_all_rooms_as_read() fires on every visible to hidden visibilitychange (document_title.rs:430-480), so on mobile an app-switch marks every room read, including rooms that were never on screen. A jump-to-unread button that points at a wiped marker is worse than no button at all, and #446 may well be the underlying cause of the original report.

#446 already asks for a product call between three options. Option 1 there ("only mark the current room read on hide") is what this feature requires. @sanity, that is the call #446 has been waiting on.

Recommend resolving #446 as part of this work rather than shipping the button on top of a marker that gets erased.

Not in scope

The second bullet of #70 (append inbound messages to the bottom regardless of timestamp) is a separate display-ordering question and is not proposed here.

Related: #70, #446, #402, #458

[AI-assisted - Claude]

[sanity]

The privacy question this came from (should read position be public, owner-controlled or otherwise) is split out into #460. This issue is deliberately independent of that decision: it uses the existing local-only last_read_message_id and changes no contract state.

[AI-assisted - Claude]

[sanity]

Issue Priority Assessment

Generated: 2026-07-24T12:39:38.155446368+00:00
Issue hash: 53f721ec

Value Assessment

Confirms the code state matches the issue description exactly — the force-scroll-to-bottom logic and last_read_message_id/count_unread_in_room_data are all present as described, unmodified since the issue was filed.

Assessment

Relevance: Still fully accurate. conversation.rs around line 1305 still force-scrolls to bottom on room switch on every actual key change, with no divider or jump-to-unread logic anywhere in the file. last_read_message_id and count_unread_in_room_data (document_title.rs:172) are exactly as described, already computing the unread boundary that the proposal would reuse. Nothing in the current code addresses this — the gap is real and unresolved.

User impact: Moderate-to-high for active/multi-room users. Anyone who lurks in a busy room and reopens River currently lands at the newest message with no way to find where they left off short of scrolling manually — a real, frequently-felt papercut in a chat app, not an edge case. The feature is table stakes for the messaging-app category River is competing in (Slack/Discord/Element parity, as the issue notes), so its absence is a legitimate UX gap rather than a nice-to-have.

Strategic alignment: Good — it's a concrete instance of the broader "reading experience" theme (#70), and it deliberately decouples from the harder privacy question in #460, keeping scope tight and shippable independent of that debate. The performance constraints called out (avoid re-deriving over use_memo given the #458 mobile-jank fix) show the author already thought through the main implementation risk, which lowers execution cost.

Blocking factor: Not blocking other work directly, but it is explicitly gated on a decision in #446 (visibilitychange marking all rooms read on mobile app-switch) — shipping the button before that's resolved would point users at a marker that's frequently wiped, undermining the feature. That makes #446 a real prerequisite, so this issue's priority is coupled to resolving #446 first.

Urgency: Low-to-moderate; came from a single Matrix user request, not a flood of complaints, and there's no deadline pressure. It's worth doing but not urgent — the sensible sequencing is to resolve #446 first, since building this on top of the current mark-all-read behavior would ship a half-working feature.

Cost Assessment

Good, code matches the issue description closely. This is enough to write the assessment.

Cost Assessment

Relevance: Still fully actionable. RoomData.last_read_message_id, count_unread_in_room_data (document_title.rs:172), and the room-switch force-scroll effect (conversation.rs:1280-1318, from #402) all exist exactly as described. The proposed approach — freeze a divider boundary in a signal at room-open rather than a live memo — aligns with the existing #402 pattern (a force_scroll/first_scroll signal pair already gates scroll behavior on room switch), so the new divider logic slots into an established mechanism rather than requiring new architecture.

Scope: Moderate, concentrated in ui/src/components/conversation.rs plus a small addition to ui/src/components/app/document_title.rs (or a shared helper) to expose the boundary index without duplicating the O(≤100) scan count_unread_in_room_data already does. Needs: a new signal for the frozen divider message ID (set in the same room-switch effect that currently sets force_scroll/first_scroll), a divider DOM node rendered conditionally in the message list, and a scroll-to-divider path alongside the existing scroll-to-bottom path. No contract, delegate, or wire-format changes — this is UI-only, so none of the migration machinery applies.

Complexity: Medium. The tricky parts are explicitly flagged in the issue: reusing rather than duplicating the unread-scan logic, keeping the boundary frozen against ROOMS mutations (must not become a use_memo over the full signal per the #458 jank lesson), not invalidating the per-message HTML cache from #458, and handling the pruned-marker fallback (issue leans toward suppressing the divider rather than anchoring at buffer top, which is the simpler and lower-risk choice). Scroll-to-divider on room switch also needs to interact correctly with the existing mount-triggered scroll effect and IntersectionObserver-driven is_at_bottom/scroll-to-latest button — getting the effect ordering right (divider scroll vs. bottom scroll vs. observer reconfirmation) is the main source of subtlety, though it's the same category of ordering problem #402 already solved.

Blocking dependency: The issue explicitly says it should not ship until #446 is resolved (the mark_all_rooms_as_read() visibilitychange handler wipes markers for rooms never viewed, which would make the jump button point at a stale/wrong position on mobile). That's a real external dependency — a product decision from @sanity — not just an implementation task, and the issue author recommends resolving #446 first. This roughly doubles the effective scope if both are done together, or blocks this issue indefinitely if #446 stalls.

Risk: Low-to-moderate. Confined to UI rendering/scroll logic with no data-model or persistence changes, so worst case is a visual/UX regression (wrong scroll position, divider misplaced) rather than data loss. The main regression risk is reintroducing the O(history) re-render jank from before #458 if the boundary is computed via a live memo instead of frozen in a signal — the issue calls this out directly, so it's a known trap rather than a hidden one.

Testing: Needs new coverage for count_unread_in_room_data-adjacent boundary-index logic (likely a shared pure helper, testable without WASM), plus Playwright/manual verification for: divider renders at correct position, scroll lands on divider not bottom when unread > 0, zero-unread keeps old behavior, pruned-marker suppression, and no jank/cache invalidation regression on mobile. The existing Playwright suite (ui/tests/) and manual dx-serve/Playwright-MCP workflow cover the scroll/layout verification well; the pruned-marker and cache-invalidation edge cases will need targeted new tests rather than reuse of existing ones.

---

Generated by issue-prioritizer