In-chat scroll position & New messages separator

[dev-adamant-im]

This document describes how scroll position in chat should behave when a user enters a chat.

Two scroll states

Scroll position is stored separately for each chat:

1. Position is not stored
2. Position is stored — user scrolled manually and saved a scroll position

When to show the Scroll to bottom button?

• Show it when the last single-lined message is hidden for ~¾ of the screen.

Scroll to bottom button action

• If there are new messages (counter is shown near the button):
  → Scroll to the “New messages” separator
• If no new messages, or user is already below the separator (it is visible or below):
  → Scroll to the very bottom

The “New messages” position

When we scroll to “New messages”:

• Place the separator plus about three lines of messages above it
• Don’t play sound/vibration or highlight messages

Don’t show the separator

• Never show before the very first message in a chat
  Example: A user receives 10 messages from a new contact. We still scroll to the very first message, but no separator is shown.

Saving scroll position

• Save scroll position only if user is not at the very bottom
• A few pixels from the bottom = considered “at the very bottom” (don’t save)
• Rule of thumb: if the Scroll to bottom button is visible → save position

State	Save scroll?	Illustration
At the very bottom	❌ Don’t save
Also at the very bottom	❌ Don’t save
Not at the very bottom	✅ Save

Note: If chat length is below screen height (few short messages) → always considered “at the very bottom”, button hidden, don’t save scroll.

Restoring scroll position

There are several events we handle:

1. The user is inside a chat when a new message arrives
2. The user opens a chat that has new messages from the Chat list

• Same for: The user opens a chat from another screen (e.g., Go to chat from Transaction list → Transaction details)

3. The user opens a chat from a new-message notification (including in-app and push notifications)

We react differently depending on the event:

Event	When no stored position	When position is saved
1. User is inside a chat and a new message arrives	Always scroll to very bottom with each new message (incoming + outgoing). Don’t show separator.	- Incoming message: Don’t scroll, update counter on button, show separator (revealed when user taps or scrolls) - Outgoing message: Always scroll to very bottom
2. User enters a chat with new messages (from Chat list or other screens)	Go to the “New messages” separator.	Don’t scroll, update counter on button, show separator (a user will see it when tap on “Scroll to bottom” button or scroll manually to the new messages).
3. User enters a chat from a notification of a new message	Go to the “New messages” separator (even if multiple messages were received — don’t go to the very latest one).	Same as left column.

This guide ensures consistent and predictable behavior for scrolling, separators, and restoring position across all chat entry points.

[al-onyxprotocol]

One small suggestion: consider adding an edge-case note for very fast incoming messages (e.g. when 20+ arrive while the user is mid-scroll). Right now the logic is consistent, but making explicit how counters/“new messages” separators behave under bursty conditions could avoid ambiguity.

Another idea: you might want to clarify how screen orientation changes / resize events affect stored scroll position — should it reset, or try to preserve the relative place in chat.

[adamantmm]

One small suggestion: consider adding an edge-case note for very fast incoming messages (e.g. when 20+ arrive while the user is mid-scroll). Right now the logic is consistent, but making explicit how counters/“new messages” separators behave under bursty conditions could avoid ambiguity.

Another idea: you might want to clarify how screen orientation changes / resize events affect stored scroll position — should it reset, or try to preserve the relative place in chat.

We can amend the doc once basic things are implemented.

[adamantmm]

Fine description, especially important for smooth UX.