sequenceDiagram
  actor User
  participant ConversationInput
  participant ConversationStore
  participant VirtualizedList
  participant useScrollToUserMessage
  participant VList

  User->>ConversationInput: Type and send message
  ConversationInput->>ConversationStore: append user message
  ConversationStore-->>VirtualizedList: update displayMessages
  VirtualizedList->>VirtualizedList: compute isLastMessageFromUser
  VirtualizedList->>useScrollToUserMessage: call with dataSourceLength, isLastMessageFromUser, scrollToIndex
  useScrollToUserMessage->>useScrollToUserMessage: detect hasNewMessage
  alt last message is from user
    useScrollToUserMessage->>VList: scrollToIndex(dataSourceLength - 2, align start, smooth true)
  else last message is from agent
    useScrollToUserMessage--xVList: no auto scroll
  end

  note over User,VList: Auto scroll is only triggered for new user messages, not for agent responses

sequenceDiagram
  participant VList
  participant AutoScroll
  participant useAutoScroll
  participant ScrollContainer

  VList->>AutoScroll: render with enabled true
  AutoScroll->>useAutoScroll: useAutoScroll(enabled true, deps)
  useAutoScroll->>ScrollContainer: attach scroll listener
  loop streaming messages
    ScrollContainer->>useAutoScroll: scroll events
    useAutoScroll->>useAutoScroll: manage userHasScrolled
  end

  AutoScroll->>AutoScroll: streaming ends
  AutoScroll->>useAutoScroll: re render with enabled false
  useAutoScroll->>useAutoScroll: detect enabled transitioned from true to false
  useAutoScroll->>ScrollContainer: read currentScrollTop
  useAutoScroll->>useAutoScroll: set isAutoScrollingRef true
  useAutoScroll->>ScrollContainer: requestAnimationFrame restore scrollTop
  useAutoScroll->>useAutoScroll: reset isAutoScrollingRef false

  note over VList,ScrollContainer: Scroll position is preserved across DOM changes when streaming stops

classDiagram
  class VirtualizedList {
    <<component>>
    - virtuaRef : VListHandle
    - scrollEndTimerRef : Timeout | null
    - displayMessages : Message[]
    - lastMessage : Message | undefined
    - isLastMessageFromUser : boolean
    + VirtualizedList(props dataSource : string[], itemContent : function) ReactElement
  }

  class useScrollToUserMessage {
    <<hook>>
    - prevLengthRef : number
    + useScrollToUserMessage(dataSourceLength : number, isLastMessageFromUser : boolean, scrollToIndex : function) void
  }

  class AutoScroll {
    <<component>>
    - shouldAutoScroll : boolean
    - atBottom : boolean
    - dbMessages : Message[]
    - lastMessageContentLength : number
    + AutoScroll() ReactElement
    + scrollToBottom(force : boolean) void
  }

  class useAutoScroll {
    <<hook>>
    - ref : HTMLElement | null
    - userHasScrolled : boolean
    - isAutoScrollingRef : boolean
    - prevEnabledRef : boolean
    + useAutoScroll(enabled : boolean, deps : any[]) HTMLElement | null
    + handleScroll() void
    + scrollToBottom(force : boolean) void
  }

  class VList {
    <<component>>
    + scrollToIndex(index : number, options : ScrollOptions) void
  }

  class BackBottom {
    <<component>>
    + BackBottom(onScrollToBottom : function, visible : boolean) ReactElement
  }

  VirtualizedList ..> useScrollToUserMessage : uses
  VirtualizedList ..> AutoScroll : renders
  VirtualizedList ..> VList : renders
  AutoScroll ..> useAutoScroll : uses
  AutoScroll ..> BackBottom : renders
  useScrollToUserMessage ..> VList : calls scrollToIndex

  class Message {
    + id : string
    + role : string
    + content : string
  }

  VirtualizedList --> "*" Message : displayMessages
  AutoScroll --> "*" Message : dbMessages