refactor: add comments about MessageList scroll

packages/frontend/src/components/message/MessageList.tsx

@@ -272,6 +272,10 @@ export default function MessageList({ accountId, chat, refComposer }: Props) {
     ]
   )
 
+  // This `useLayoutEffect` is made to run whenever `viewState` changes.
+  // `viewState` controls the desired scroll position of `messageListRef`.
+  // After the following callback is run and the message list is scrolled
+  // to where `viewState` told it to be, we reset `viewState` back to `null`.
   useLayoutEffect(() => {
     if (!chat) {
       return
@@ -334,6 +338,14 @@ export default function MessageList({ accountId, chat, refComposer }: Props) {
         }
       }
     } else if (scrollTo.type === 'scrollToLastKnownPosition') {
+      // "Why need scrollToLastKnownPosition if there is scroll anchoring
+      // in browsers already?"
+      // https://developer.mozilla.org/en-US/docs/Web/CSS/overflow-anchor/Guide_to_scroll_anchoring
+      // Well, I am not sure why it is introduced back then,
+      // but the reason we need it now is because scroll anchoring
+      // isn't supported by Safari (WebKit) yet, and we are gonna run on WebKit
+      // when we switch to Tauri, so let's not remove it yet.
+
       log.debug(
         'scrollTo type: scrollToLastKnownPosition; lastKnownScrollHeight: ' +
           scrollTo.lastKnownScrollHeight +
@@ -382,8 +394,15 @@ export default function MessageList({ accountId, chat, refComposer }: Props) {
       }
     }
     setTimeout(() => {
+      // We just scrolled where we needed to, now let's reset the value of
+      // `viewState` so that we don't keep scrolling to the same place
+      // again and again.
       unlockScroll()
+
       setTimeout(() => {
+        // Since the scroll position might have changed,
+        // let's invoke `onScroll`, e.g. to load more messages if we're close
+        // to top / bottom
         onScroll(null)
       }, 0)
     }, 0)

packages/frontend/src/stores/chat/chat_view_reducer.ts

@@ -11,6 +11,10 @@ interface ScrollToMessage {
   highlight: boolean
 }
 
+/**
+ * Used for manual "scroll anchoring", e.g. when loading older messages
+ * and inserting them into the messages list.
+ */
 interface ScrollToLastKnownPosition {
   type: 'scrollToLastKnownPosition'
   lastKnownScrollHeight: number

packages/frontend/src/stores/messagelist.ts

@@ -22,6 +22,16 @@ interface MessageListState {
   messageCache: { [msgId: number]: T.MessageLoadResult | undefined }
   newestFetchedMessageListItemIndex: number
   oldestFetchedMessageListItemIndex: number
+  /**
+   * This is used as an "event bus". When we need to update the scroll position
+   * of the messages list (e.g. `scrollToMessage`), or, instead, keep the
+   * scroll position in the same place as we append newly loaded messages,
+   * to prevent content jumps (`scrollToLastKnownPosition`,
+   * manual scroll anchoring), then we set `viewState.scrollTo`
+   * to the desired state.
+   * After that, the MessageList component looks at the new state,
+   * sets the scroll position accordingly, and resets the state to null.
+   */
   viewState: ChatViewState
   jumpToMessageStack: number[]
   loaded: boolean