collavre 0.24.0 → 0.25.0

data/app/javascript/controllers/comments/presence_controller.js

@@ -5,7 +5,15 @@ import csrfFetch from '../../lib/api/csrf_fetch'
 import { alertDialog } from '../../lib/utils/dialog'
 
 const TYPING_TIMEOUT = 3000
-const AGENT_STATUS_TIMEOUT = 10000 // Safety timeout for agent_status (heartbeat expected every 3s)
+const AGENT_TASK_POLL_INTERVAL = 15000 // Poll active task statuses every 15s
+const STREAMING_HEARTBEAT_TIMEOUT = 5000 // Transition streaming → thinking if no heartbeat
+const PRESENCE_HEARTBEAT_INTERVAL = 30000
+
+// agent_status values that keep a task registered. thinking/streaming are the
+// agent producing output; pending_approval is it paused on a tool approval,
+// which is not the end of the task — treating it as idle would drop the task
+// and stop the poll, so the status above could never be seen.
+const LIVE_AGENT_STATUSES = new Set(['thinking', 'streaming', 'pending_approval'])
 
 export default class extends Controller {
   static targets = ['participants', 'typingIndicator', 'textarea', 'privateCheckbox', 'channelChips', 'scrollRow']
@@ -19,31 +27,66 @@ export default class extends Controller {
     this.manualTypingMessage = null
     this.presenceSubscription = null
     this.typingTimeoutHandle = null
+    this.activeAgentTasks = {} // { agentId: [taskId, ...] } - ordered, last is most recent
+    this.agentStates = {} // { agentId: 'streaming' | 'thinking' }
+    this.streamingHeartbeatTimers = {} // { agentId: timeoutHandle }
+    this.agentTaskPollHandle = null
     this.hasPresenceConnected = false
+    this.presenceHeartbeatHandle = null
     this.currentUserId = document.body.dataset.currentUserId
+    this.selectedTopicId = null
+    this.mainTopicId = null
+    this.renderedAllTopicIds = null
+    this.renderedAllIncludesLegacy = false
 
     this.handleInput = this.handleInput.bind(this)
     this.handleFocus = this.handleFocus.bind(this)
     this.handleBlur = this.handleBlur.bind(this)
     this.handleTopicChange = this.handleTopicChange.bind(this)
+    this.handleRenderedAllTopics = this.handleRenderedAllTopics.bind(this)
 
     this.textareaTarget.addEventListener('input', this.handleInput)
     this.textareaTarget.addEventListener('focus', this.handleFocus)
     this.textareaTarget.addEventListener('blur', this.handleBlur)
     this.privateCheckboxTarget?.addEventListener('change', () => this.stoppedTyping())
     this.element.addEventListener('comments--topics:change', this.handleTopicChange)
+    this.element.addEventListener('comments--list:rendered-all-topics', this.handleRenderedAllTopics)
   }
 
   disconnect() {
     this.unsubscribe()
+    this.stopAgentTaskPoll()
+    this.clearAllStreamingHeartbeats()
     this.textareaTarget.removeEventListener('input', this.handleInput)
     this.textareaTarget.removeEventListener('focus', this.handleFocus)
     this.textareaTarget.removeEventListener('blur', this.handleBlur)
     this.element.removeEventListener('comments--topics:change', this.handleTopicChange)
+    this.element.removeEventListener('comments--list:rendered-all-topics', this.handleRenderedAllTopics)
   }
 
   handleTopicChange(event) {
     const topicId = event.detail?.topicId
+    const nextSelectedTopicId = topicId || null
+    const nextMainTopicId = event.detail?.mainTopicId || this.mainTopicId
+    const selectionChanged = String(nextSelectedTopicId || '') !== String(this.selectedTopicId || '')
+
+    if (selectionChanged) {
+      this.stoppedTyping()
+      this.clearTopicIndicators()
+    }
+
+    this.selectedTopicId = nextSelectedTopicId
+    this.mainTopicId = nextMainTopicId
+    if (selectionChanged) {
+      this.renderedAllTopicIds = null
+      this.renderedAllIncludesLegacy = false
+    }
+
+    if (selectionChanged) {
+      this.reportViewingTopic()
+      this.requestRunningAgents()
+    }
+
     if (topicId) {
       this.refreshChannelChips(topicId)
     } else {
@@ -51,6 +94,15 @@ export default class extends Controller {
     }
   }
 
+  handleRenderedAllTopics(event) {
+    const { creativeId, topicIds, includesLegacy } = event.detail || {}
+    if (String(creativeId) !== String(this.creativeId) || this.selectedTopicId) return
+
+    this.renderedAllTopicIds = Array.isArray(topicIds) ? topicIds : []
+    this.renderedAllIncludesLegacy = Boolean(includesLegacy)
+    this.reportViewingTopic()
+  }
+
   get listController() {
     return this.application.getControllerForElementAndIdentifier(this.element, 'comments--list')
   }
@@ -64,7 +116,18 @@ export default class extends Controller {
   }
 
   onPopupOpened({ creativeId }) {
+    // Navigating the OPEN popup to another creative comes through here, not through
+    // onPopupClosed() — PopupController#_navigateToEntry reuses open()/openForCreative().
+    // Every piece of agent state below belongs to the chat being left: the poll is keyed
+    // on task ids and /tasks/active_statuses answers for any task the user can read, so a
+    // carried-over id keeps a foreign task's indicator alive here, and the Stop button it
+    // renders cancels a turn in a creative that is no longer on screen.
+    if (this.creativeId !== undefined && String(creativeId) !== String(this.creativeId)) {
+      this.resetAgentActivity()
+    }
     this.creativeId = creativeId
+    this.renderedAllTopicIds = null
+    this.renderedAllIncludesLegacy = false
     this.loadParticipants()
     this.subscribe()
     this.renderParticipants([])
@@ -81,6 +144,9 @@ export default class extends Controller {
       this.element, 'comments--topics'
     )
     const topicId = topicsCtrl?.currentTopicId
+    this.selectedTopicId = topicId || null
+    this.mainTopicId = topicsCtrl?.mainTopicId || null
+    this.reportViewingTopic()
     if (topicId) {
       this.refreshChannelChips(topicId)
     } else {
@@ -88,14 +154,50 @@ export default class extends Controller {
     }
   }
 
+  // Everything that describes activity in ONE chat. Leaving that chat — closed, or
+  // navigated to another creative with the popup still open — has to drop all of it
+  // together: the maps the indicator renders from, the timers that write back into
+  // them, and the poll that keeps them alive. Clearing the maps alone would leave the
+  // interval and the heartbeat timeouts running for a chat nobody is looking at.
+  resetAgentActivity() {
+    this.stopAgentTaskPoll()
+    this.clearAllStreamingHeartbeats()
+    this.clearTypingTimers()
+    this.typingUsers = {}
+    this.activeAgentTasks = {}
+    this.agentStates = {}
+    this.syncGlobalAgentTasks()
+  }
+
+  // An agent's turns, label, state and heartbeat come down together or not at all.
+  // The heartbeat is keyed by agent, so it may only go when the agent itself does —
+  // a surviving turn still needs it to degrade to thinking. Three paths remove an
+  // agent (idle, Stop, poll); routing them all through here is what keeps them from
+  // drifting apart, which is how that heartbeat got dropped early once already.
+  dropAgent(agentId) {
+    delete this.activeAgentTasks[agentId]
+    delete this.typingUsers[agentId]
+    delete this.agentStates[agentId]
+    this.clearStreamingHeartbeat(agentId)
+  }
+
+  // Ends one turn, and the agent with it once nothing is left. A missing taskId means
+  // the caller can't say which turn ended, so the agent goes entirely.
+  dropAgentTask(agentId, taskId) {
+    const tasks = this.activeAgentTasks[agentId]
+    if (!tasks) return this.dropAgent(agentId)
+    if (taskId) {
+      const idx = tasks.indexOf(taskId)
+      if (idx !== -1) tasks.splice(idx, 1)
+    }
+    if (!taskId || tasks.length === 0) this.dropAgent(agentId)
+  }
+
   onPopupClosed() {
     this.unsubscribe()
     this.participantsData = null
     this.currentPresentIds = []
-    this.typingUsers = {}
-    this.activeAgentTasks = {}
-    this.syncGlobalAgentTasks()
-    this.clearTypingTimers()
+    this.resetAgentActivity()
     this.clearManualTypingMessage()
     this.renderParticipants([])
     this.renderTypingIndicator()
@@ -116,13 +218,17 @@ export default class extends Controller {
 
   typing() {
     if (!this.presenceSubscription || this.privateCheckboxTarget?.checked) return
-    this.presenceSubscription.perform('typing')
+    const topicId = this.typingTopicId
+    if (!topicId) return
+
+    this.presenceSubscription.perform('typing', { topic_id: topicId })
     this.resetTypingTimeout()
   }
 
   stoppedTyping() {
-    if (this.presenceSubscription) {
-      this.presenceSubscription.perform('stopped_typing')
+    const topicId = this.typingTopicId
+    if (this.presenceSubscription && topicId) {
+      this.presenceSubscription.perform('stopped_typing', { topic_id: topicId })
     }
     if (this.typingTimeoutHandle) {
       clearTimeout(this.typingTimeoutHandle)
@@ -130,7 +236,13 @@ export default class extends Controller {
     }
   }
 
-  loadParticipants({ closeOnForbidden = false } = {}) {
+  requestRunningAgents() {
+    if (!this.presenceSubscription || !this.selectedTopicId) return
+
+    this.presenceSubscription.perform('running_agents', { topic_id: this.selectedTopicId })
+  }
+
+  loadParticipants() {
     if (!this.creativeId) return
     fetch(`/creatives/${this.creativeId}/comments/participants`, {
       cache: 'no-store',
@@ -150,16 +262,11 @@ export default class extends Controller {
         this.renderParticipants(this.currentPresentIds)
         this.renderTypingIndicator()
       })
-      .catch((error) => {
+      .catch(() => {
         this.participantsData = []
         this.canShare = false
         this.renderParticipants([])
         this.renderTypingIndicator()
-
-        if (closeOnForbidden) {
-          alertDialog(error.message)
-          this.popupController?.close()
-        }
       })
   }
 
@@ -175,6 +282,8 @@ export default class extends Controller {
             this.listController?.loadInitialComments()
           }
           this.hasPresenceConnected = true
+          this.reportViewingTopic()
+          this.startPresenceHeartbeat()
         },
         received: (data) => this.handlePresenceMessage(data),
       },
@@ -182,6 +291,7 @@ export default class extends Controller {
   }
 
   unsubscribe() {
+    this.stopPresenceHeartbeat()
     if (this.presenceSubscription) {
       this.presenceSubscription.unsubscribe()
       this.presenceSubscription = null
@@ -189,6 +299,31 @@ export default class extends Controller {
     this.stoppedTyping()
   }
 
+  reportViewingTopic() {
+    if (!this.presenceSubscription) return
+
+    const payload = { topic_id: this.selectedTopicId }
+    if (!this.selectedTopicId && Array.isArray(this.renderedAllTopicIds)) {
+      payload.rendered_topic_ids = this.renderedAllTopicIds
+      if (this.renderedAllIncludesLegacy) payload.rendered_legacy_topic = true
+    }
+    this.presenceSubscription.perform('viewing_topic', payload)
+  }
+
+  startPresenceHeartbeat() {
+    this.stopPresenceHeartbeat()
+    this.presenceHeartbeatHandle = setInterval(() => {
+      this.presenceSubscription?.perform('heartbeat')
+    }, PRESENCE_HEARTBEAT_INTERVAL)
+  }
+
+  stopPresenceHeartbeat() {
+    if (this.presenceHeartbeatHandle) {
+      clearInterval(this.presenceHeartbeatHandle)
+      this.presenceHeartbeatHandle = null
+    }
+  }
+
   handlePresenceMessage(data) {
     if (data.ids) {
       this.currentPresentIds = data.ids.map((id) => parseInt(id, 10))
@@ -196,7 +331,9 @@ export default class extends Controller {
       this.updateReadReceiptPresence(this.currentPresentIds)
     }
     if (data.typing) {
-      const { id, name } = data.typing
+      const { id, name, topic_id: topicId } = data.typing
+      if (!this.isSelectedTopic(topicId)) return
+
       const isNewTyper = !(id in this.typingUsers)
       // The user always wants to see their OWN typing indicator the moment it
       // appears — they just started typing. Stick-to-end (which pauses while the
@@ -213,7 +350,9 @@ export default class extends Controller {
       }, TYPING_TIMEOUT)
     }
     if (data.stop_typing) {
-      const { id } = data.stop_typing
+      const { id, topic_id: topicId } = data.stop_typing
+      if (!this.isSelectedTopic(topicId)) return
+
       delete this.typingUsers[id]
       if (this.typingTimers[id]) {
         clearTimeout(this.typingTimers[id])
@@ -234,40 +373,63 @@ export default class extends Controller {
         this.formController?.setCommentPermission(shareChange.can_comment)
       }
 
-      this.loadParticipants({ closeOnForbidden: shareChange.has_access === false })
+      if (shareChange.has_access === false) {
+        document.dispatchEvent(new CustomEvent('workspace-tree:invalidate', {
+          detail: { creativeIds: [String(this.creativeId)] },
+        }))
+        alertDialog(this.element.dataset.noPermissionText || 'No permission')
+        if (this.popupController?.isDocked()) {
+          this.popupController.resetDockedToEmpty()
+        } else {
+          this.popupController?.close()
+        }
+        return
+      }
+
+      this.loadParticipants()
       return
     }
     if (data.channel_chips) {
       this.refreshChannelChips(data.channel_chips.topic_id)
     }
     if (data.agent_status) {
-      const { id, name, status, task_id, creative_id: agentCreativeId } = data.agent_status
+      const { id, name, status, task_id, topic_id: topicId, creative_id: agentCreativeId } = data.agent_status
       // Only show typing indicator if agent is working on this specific creative
       if (agentCreativeId && String(agentCreativeId) !== String(this.creativeId)) {
         return
       }
+      if (!topicId) {
+        // Turns are tracked per agent as an array, so a legacy idle has to match a
+        // member — String() on the array only happens to work at length 1.
+        const activeTaskIds = this.activeAgentTasks?.[id] || []
+        const matchingLegacyIdle = status === 'idle' && task_id &&
+          activeTaskIds.some((activeTaskId) => String(activeTaskId) === String(task_id))
+        if (!matchingLegacyIdle) return
+      } else if (!this.isSelectedTopic(topicId)) {
+        return
+      }
+
       const isNewAgent = (status === 'thinking' || status === 'streaming') && !(id in this.typingUsers)
-      if (status === 'thinking' || status === 'streaming') {
+      if (LIVE_AGENT_STATUSES.has(status)) {
         this.typingUsers[id] = name
-        if (!this.activeAgentTasks) this.activeAgentTasks = {}
-        if (task_id) this.activeAgentTasks[id] = task_id
-        // Safety timeout: auto-remove if no heartbeat within AGENT_STATUS_TIMEOUT
-        if (!this.agentStatusTimers) this.agentStatusTimers = {}
-        if (this.agentStatusTimers[id]) clearTimeout(this.agentStatusTimers[id])
-        this.agentStatusTimers[id] = setTimeout(() => {
-          delete this.typingUsers[id]
-          delete this.agentStatusTimers[id]
-          delete this.activeAgentTasks?.[id]
-          this.syncGlobalAgentTasks()
-          this.renderTypingIndicator()
-        }, AGENT_STATUS_TIMEOUT)
-      } else {
-        delete this.typingUsers[id]
-        delete this.activeAgentTasks?.[id]
-        if (this.agentStatusTimers?.[id]) {
-          clearTimeout(this.agentStatusTimers[id])
-          delete this.agentStatusTimers[id]
+        this.agentStates[id] = status
+        if (!this.activeAgentTasks[id]) this.activeAgentTasks[id] = []
+        if (task_id && !this.activeAgentTasks[id].includes(task_id)) {
+          this.activeAgentTasks[id].push(task_id)
         }
+        // Streaming heartbeat: transition to thinking if no update within timeout
+        this.clearStreamingHeartbeat(id)
+        if (status === 'streaming') {
+          this.streamingHeartbeatTimers[id] = setTimeout(() => {
+            this.agentStates[id] = 'thinking'
+            delete this.streamingHeartbeatTimers[id]
+            this.renderTypingIndicator()
+          }, STREAMING_HEARTBEAT_TIMEOUT)
+        }
+        this.startAgentTaskPoll()
+      } else {
+        this.dropAgentTask(id, task_id)
+        this.maybeStopAgentTaskPoll()
       }
       this.syncGlobalAgentTasks()
       this.renderTypingIndicator({ newItem: isNewAgent })
@@ -384,7 +546,7 @@ export default class extends Controller {
     this.typingIndicatorTarget.style.opacity = '1'
 
     // Add stop button first (before avatars/names) for active agent tasks
-    const hasActiveTask = ids.some((id) => this.activeAgentTasks?.[id])
+    const hasActiveTask = ids.some((id) => this.activeAgentTasks[id]?.length > 0)
     if (hasActiveTask) {
       const stopBtn = document.createElement('button')
       stopBtn.type = 'button'
@@ -394,8 +556,11 @@ export default class extends Controller {
       stopBtn.title = stopLabel
       stopBtn.addEventListener('click', () => {
         ids.forEach((id) => {
-          const taskId = this.activeAgentTasks?.[id]
-          if (taskId) this.cancelAgentTask(taskId, id)
+          const tasks = this.activeAgentTasks[id]
+          if (tasks?.length > 0) {
+            // Cancel the last (most recent) task
+            this.cancelAgentTask(tasks[tasks.length - 1], id)
+          }
         })
       })
       this.typingIndicatorTarget.appendChild(stopBtn)
@@ -425,9 +590,13 @@ export default class extends Controller {
         this.typingIndicatorTarget.appendChild(wrapper)
       })
     }
-    const names = ids.map((id) => this.typingUsers[id])
     const text = document.createElement('span')
-    text.textContent = `${names.join(', ')} ...`
+    const parts = ids.map((id) => {
+      const name = this.typingUsers[id]
+      const isAgentThinking = this.activeAgentTasks[id]?.length > 0 && this.agentStates[id] !== 'streaming'
+      return isAgentThinking ? `${name} \u23F3` : `${name} ...`
+    })
+    text.textContent = parts.join('  ')
     this.typingIndicatorTarget.appendChild(text)
 
     if (stickToEnd) this.scrollRowToEnd()
@@ -463,11 +632,13 @@ export default class extends Controller {
   }
 
   cancelAllAgentTasks() {
-    const ids = Object.keys(this.activeAgentTasks || {})
-    if (ids.length === 0) return false
-    ids.forEach((id) => {
-      const taskId = this.activeAgentTasks[id]
-      if (taskId) this.cancelAgentTask(taskId, id)
+    const agentIds = Object.keys(this.activeAgentTasks)
+    if (agentIds.length === 0) return false
+    agentIds.forEach((agentId) => {
+      const tasks = this.activeAgentTasks[agentId]
+      if (tasks?.length > 0) {
+        this.cancelAgentTask(tasks[tasks.length - 1], agentId)
+      }
     })
     return true
   }
@@ -479,12 +650,8 @@ export default class extends Controller {
     })
       .then((response) => {
         if (response.ok) {
-          delete this.typingUsers[agentId]
-          delete this.activeAgentTasks?.[agentId]
-          if (this.agentStatusTimers?.[agentId]) {
-            clearTimeout(this.agentStatusTimers[agentId])
-            delete this.agentStatusTimers[agentId]
-          }
+          this.dropAgentTask(agentId, taskId)
+          this.maybeStopAgentTaskPoll()
           this.syncGlobalAgentTasks()
           this.renderTypingIndicator()
         }
@@ -548,7 +715,9 @@ export default class extends Controller {
     csrfFetch(`/channels/${id}`, {
       method: 'DELETE',
       headers: { Accept: 'application/json' },
-    }).catch((err) => console.warn('[presence] detach channel failed:', err))
+    })
+      .then((response) => response.status === 204 && !response.redirected && btn.closest('.channel-chip')?.remove())
+      .catch((err) => console.warn('[presence] detach channel failed:', err))
   }
 
   clearTypingTimers() {
@@ -556,6 +725,99 @@ export default class extends Controller {
     this.typingTimers = {}
   }
 
+  // Every indicator on screen belongs to the topic being left, and the replay that
+  // follows is scoped to the new one — so the whole agent state goes, heartbeats and
+  // poll included. A surviving poll would keep resurrecting the old topic's turns.
+  clearTopicIndicators() {
+    this.resetAgentActivity()
+    this.renderTypingIndicator()
+  }
+
+  get typingTopicId() {
+    return this.selectedTopicId || this.mainTopicId
+  }
+
+  isSelectedTopic(topicId) {
+    return Boolean(
+      this.selectedTopicId &&
+      topicId &&
+      String(topicId) === String(this.selectedTopicId)
+    )
+  }
+
+  // ── Streaming heartbeat ─────────────────────────────────
+
+  clearStreamingHeartbeat(agentId) {
+    if (this.streamingHeartbeatTimers[agentId]) {
+      clearTimeout(this.streamingHeartbeatTimers[agentId])
+      delete this.streamingHeartbeatTimers[agentId]
+    }
+  }
+
+  clearAllStreamingHeartbeats() {
+    Object.values(this.streamingHeartbeatTimers).forEach((timer) => clearTimeout(timer))
+    this.streamingHeartbeatTimers = {}
+  }
+
+  // ── Agent task status polling ──────────────────────────
+
+  startAgentTaskPoll() {
+    if (this.agentTaskPollHandle) return
+    this.agentTaskPollHandle = setInterval(() => this.pollAgentTaskStatuses(), AGENT_TASK_POLL_INTERVAL)
+  }
+
+  stopAgentTaskPoll() {
+    if (this.agentTaskPollHandle) {
+      clearInterval(this.agentTaskPollHandle)
+      this.agentTaskPollHandle = null
+    }
+  }
+
+  maybeStopAgentTaskPoll() {
+    if (Object.keys(this.activeAgentTasks).length === 0) this.stopAgentTaskPoll()
+  }
+
+  pollAgentTaskStatuses() {
+    const allTaskIds = Object.values(this.activeAgentTasks).flat()
+    if (allTaskIds.length === 0) {
+      this.stopAgentTaskPoll()
+      return
+    }
+    const requestedTaskIds = new Set(allTaskIds)
+
+    csrfFetch(`/tasks/active_statuses?task_ids=${allTaskIds.join(',')}`, {
+      headers: { Accept: 'application/json' },
+    })
+      .then((response) => {
+        if (!response.ok) return null
+        return response.json()
+      })
+      .then((data) => {
+        if (!data) return
+        // Task#active? decides what still deserves an indicator and a Stop
+        // button, so the client never has to know the status vocabulary.
+        const activeTaskIds = new Set(data.tasks.filter((t) => t.active).map((t) => t.id))
+
+        // This response only speaks for the ids it was asked about. A task that
+        // an agent_status message appended while the request was in flight was
+        // never requested, so its absence here means nothing — keep it until a
+        // poll that actually asked about it says otherwise.
+        let changed = false
+        Object.keys(this.activeAgentTasks).forEach((agentId) => {
+          const before = this.activeAgentTasks[agentId].length
+          this.activeAgentTasks[agentId] = this.activeAgentTasks[agentId].filter(
+            (taskId) => activeTaskIds.has(taskId) || !requestedTaskIds.has(taskId),
+          )
+          if (this.activeAgentTasks[agentId].length !== before) changed = true
+          if (this.activeAgentTasks[agentId].length === 0) this.dropAgent(agentId)
+        })
+
+        if (changed) this.renderTypingIndicator()
+        this.maybeStopAgentTaskPoll()
+      })
+      .catch((err) => console.warn('[presence] poll agent task statuses failed:', err))
+  }
+
   handleInput() {
     this.clearManualTypingMessage()
     this.typing()

data/app/javascript/controllers/comments/prev_message_navigator.js

@@ -0,0 +1,94 @@
+// Tracks where the "previous message" button left off.
+//
+// The button scrolls with `behavior: 'smooth'`, so a rapid second click arrives
+// while the list is still mid-animation. Deriving the current position purely
+// from geometry at that moment picks the item we just left (it has not reached
+// the top yet), which makes the list bounce up and down instead of walking
+// backwards. Remembering the last target as an anchor keeps each click stepping
+// one message further back.
+//
+// The anchor is dropped once the user moves the list themselves, so geometry
+// takes over from wherever they landed. Invalidation is driven by input events
+// rather than scroll events: a scroll event cannot be attributed to the user
+// without guessing how long our own animation runs, and guessing short brings
+// the bounce back. Dropping the anchor is always the safe direction — a settled
+// list resolves correctly from geometry alone.
+//
+// Kept free of DOM access so it can be unit tested: jsdom has no layout engine,
+// so the controller measures the items and passes `{ id, top }` pairs in.
+
+// Sub-pixel scroll offsets (HiDPI, browser rounding) mean an item parked at the
+// top is rarely at exactly `viewportTop`.
+const TOP_TOLERANCE = 4
+
+export default class PrevMessageNavigator {
+  constructor() {
+    this.anchorId = null
+  }
+
+  // items: `{ id, top }` in DOM order (oldest first), top relative to viewport.
+  // Returns the index to scroll to, or -1 when there is nothing older in the
+  // list (the caller then loads older comments).
+  resolveTargetIndex(items, viewportTop) {
+    if (items.length === 0) return -1
+
+    if (this.anchorId !== null) {
+      const anchorIdx = items.findIndex((item) => item.id === this.anchorId)
+      if (anchorIdx !== -1 && this.anchorIsOnItsWay(items[anchorIdx].top, viewportTop)) {
+        return anchorIdx - 1
+      }
+      this.anchorId = null
+    }
+
+    let currentIdx = items.findIndex((item) => item.top >= viewportTop - TOP_TOLERANCE)
+    if (currentIdx === -1) currentIdx = items.length - 1
+
+    const isAtTop = Math.abs(items[currentIdx].top - viewportTop) < TOP_TOLERANCE
+    return isAtTop ? currentIdx - 1 : currentIdx
+  }
+
+  // The anchor travels from wherever it sat when we committed to `viewportTop`,
+  // and nothing else moves it. Outside that corridor the list was scrolled by
+  // something other than us - a new message arriving, a permalink jump - none of
+  // which fire a user input event, so the anchor would otherwise survive and wedge
+  // the button (anchored on the oldest item, every click resolves to -1 forever).
+  //
+  // The corridor spans both endpoints because the anchor can approach the top from
+  // either side: usually from above (the next message back), but from below when
+  // the click started between messages and we pulled the partially visible one up.
+  //
+  // Comparing the anchor against its own start position rather than the list's
+  // scroll offset keeps this correct when older comments are prepended: that
+  // shifts `scrollTop` but leaves the anchor where it is on screen.
+  anchorIsOnItsWay(anchorTop, viewportTop) {
+    const low = Math.min(this.anchorStartTop, viewportTop) - TOP_TOLERANCE
+    const high = Math.max(this.anchorStartTop, viewportTop) + TOP_TOLERANCE
+    return anchorTop >= low && anchorTop <= high
+  }
+
+  // Called once we start scrolling towards `id`, which currently sits at `top`.
+  commit(id, top) {
+    this.anchorId = id
+    this.anchorStartTop = top
+  }
+
+  // Called when the user interacts with the list (wheel, touch, key, pointer).
+  notifyUserInput() {
+    this.anchorId = null
+  }
+
+  // Called when our own code repositions the list without going through the
+  // button - jumping to the newest message, a permalink highlight. These fire no
+  // user input event, and a small jump can leave the anchor inside the corridor
+  // above, where geometry cannot tell it apart from our own in-flight scroll. The
+  // corridor still catches larger jumps, but the caller drops the anchor at these
+  // known sites so a still-visible message is never skipped.
+  notifyProgrammaticScroll() {
+    this.anchorId = null
+  }
+
+  // Called when the list contents are replaced wholesale.
+  reset() {
+    this.anchorId = null
+  }
+}