@sentry/junior-dashboard 0.271.0 → 0.272.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentry/junior-dashboard",
-  "version": "0.271.0",
+  "version": "0.272.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -39,10 +39,10 @@
     "remark-gfm": "^4.0.1",
     "shiki": "4.1.0",
     "zod": "^4.5.4",
-    "@sentry/junior-plugin-api": "0.271.0"
+    "@sentry/junior-plugin-api": "0.272.0"
   },
   "peerDependencies": {
-    "@sentry/junior": "0.271.0"
+    "@sentry/junior": "0.272.0"
   },
   "devDependencies": {
     "@oxlint/plugins": "1.79.0",
@@ -63,7 +63,7 @@
     "tw-animate-css": "^1.4.0",
     "typescript": "^7.0.2",
     "vitest": "^4.1.12",
-    "@sentry/junior": "0.271.0"
+    "@sentry/junior": "0.272.0"
   },
   "scripts": {
     "build": "pnpm --filter @sentry/junior-plugin-api build && pnpm --filter @sentry/junior build && pnpm run build:client && pnpm run build:css && pnpm run build:server",

package/src/app.ts

@@ -36,6 +36,7 @@ import {
 } from "./auth";
 import { isAuthPath, type AuthenticatedRoute } from "./authenticated-routes";
 import { resetMockConversationArchiveState } from "./mock-reporting/fixtures";
+import { resetMockReadPositions } from "./mock-reporting/read-positions";
 import { createMockReportingApi } from "./mock-reporting/routes";
 import {
   DASHBOARD_AVATAR_HEADER_PATH,
@@ -71,6 +72,7 @@ const mockDisplayNamesByEmail = new Map<string, string>();
 export function resetMockDashboardState(): void {
   mockDisplayNamesByEmail.clear();
   resetMockConversationArchiveState();
+  resetMockReadPositions();
 }
 
 export interface JuniorDashboardOptions {

package/src/client/conversations/ConversationPage.tsx

@@ -98,6 +98,11 @@ import {
 } from "../review-desk/reviewItemFormat";
 import { useConfirmUnsentAnswers } from "../review-desk/UnsentAnswers";
 import { Transcript } from "./TranscriptView";
+import {
+  readConversationStartPosition,
+  useMarkConversationRead,
+  useReadPositionAtOpen,
+} from "./transcriptReadPosition";
 import { TranscriptLoading } from "./TranscriptLoading";
 import type { TranscriptViewMode } from "./transcriptRenderModel";
 import {
@@ -166,6 +171,8 @@ export function ConversationPage(props: {
   const conversations = buildConversations(summaries);
   const detail = useConversationData(conversationId);
   const archive = useArchiveConversation(conversationId);
+  const markRead = useMarkConversationRead(conversationId);
+  const readAtOpen = useReadPositionAtOpen(detail.data, detail.fetchedDetail);
   const feedConversation = conversations.find(
     (item) => item.id === conversationId,
   );
@@ -484,9 +491,11 @@ export function ConversationPage(props: {
                     hasPreviousPage={detail.hasPreviousPage}
                     historyError={detail.historyError}
                     historyVersion={detail.historyVersion}
+                    lastReadSeq={readAtOpen.lastReadSeq}
                     live={live}
                     loadingPreviousPage={detail.isLoadingPreviousPage}
                     onLoadPreviousPage={detail.loadPreviousPage}
+                    onRead={markRead}
                     onSelectedEventSeqChange={setSelectedEventSeq}
                     pendingMessages={detail.inlineMessages}
                     pinRequestVersion={pinRequestVersion}
@@ -497,8 +506,10 @@ export function ConversationPage(props: {
                     search={search}
                     onSearchChange={setSearch}
                     selectedEventSeq={selectedEventSeq}
+                    startAtUnread={readConversationStartPosition() === "unread"}
                     transcript={transcript}
                     turnContextPanel={turnContextPanel}
+                    unread={readAtOpen.unread}
                     view={view}
                   />
                 </>

package/src/client/conversations/ConversationTranscript.tsx

@@ -49,8 +49,13 @@ import {
   type RenderedTranscriptEntry,
 } from "./transcriptRenderModel";
 import { entryMatchesSearch, useTranscriptSearch } from "./transcriptSearch";
-import { TranscriptRow, TranscriptRows } from "./TranscriptRows";
+import {
+  TranscriptRow,
+  TranscriptRows,
+  TranscriptUnreadMarker,
+} from "./TranscriptRows";
 import { TranscriptTimestampProvider } from "./TranscriptTimestamp";
+import type { TranscriptUnreadRange } from "./transcriptReadPosition";
 
 type TranscriptEntry = ReturnType<typeof groupTranscriptMessages>[number];
 type TranscriptContextEntry = Extract<TranscriptEntry, { kind: "context" }>;
@@ -85,6 +90,8 @@ export const ConversationTranscriptView = memo(
     /** Sends that history does not have yet. History wins on message id. */
     pendingMessages?: readonly ConversationMailboxMessage[];
     responding?: boolean;
+    /** Show the "New" marker before the first row in this range. */
+    unread?: TranscriptUnreadRange;
   }) {
     // Cards can change while their Message events stay unchanged.
     const { events, annotations } = props.conversation;
@@ -106,6 +113,7 @@ export const ConversationTranscriptView = memo(
             conversation={props.conversation}
             messages={messages}
             responding={props.responding}
+            unread={props.unread}
           />
         </section>
       </TranscriptTimestampProvider>
@@ -121,6 +129,7 @@ function SegmentEvents(props: {
   conversation: ConversationTranscript;
   messages: TranscriptViewMessage[];
   responding?: boolean;
+  unread?: TranscriptUnreadRange;
 }) {
   return (
     <TranscriptRows>
@@ -134,6 +143,7 @@ function SegmentEvents(props: {
           onOpenSubagentTranscript={props.onOpenSubagentTranscript}
           transcript={props.messages}
           conversation={props.conversation}
+          unread={props.unread}
         />
       ) : props.conversation.eventHistory.status === "redacted" &&
         props.messages.length > 0 ? (
@@ -205,6 +215,7 @@ const VisibleTranscriptEntries = memo(function VisibleTranscriptEntries(props: {
   }) => void;
   transcript: TranscriptViewMessage[];
   conversation: ConversationTranscript;
+  unread?: TranscriptUnreadRange;
 }) {
   const entries = useMemo(
     () => groupTranscriptMessages(props.transcript),
@@ -214,6 +225,7 @@ const VisibleTranscriptEntries = memo(function VisibleTranscriptEntries(props: {
     <TranscriptEntryList
       entries={entries}
       keyPrefix={props.conversation.conversationId}
+      unread={props.unread}
       renderContext={(entry) => (
         <TranscriptRailEvent
           kind={entry.part.event.type === "handoff" ? "handoff" : "compaction"}
@@ -314,11 +326,26 @@ function TranscriptEntryList(props: {
   renderReasoning: (entry: TranscriptReasoningEntry) => ReactNode;
   renderSubagent: (entry: TranscriptSubagentEntry) => ReactNode;
   renderTool: (entry: TranscriptToolEntry) => ReactNode;
+  unread?: TranscriptUnreadRange;
 }) {
   const search = useTranscriptSearch();
   const activityKeys = useRef(new Map<string, string>());
   const claimedActivityKeys = new Set<string>();
   const rows: ReactNode[] = [];
+  // Search results are not a reading order, so they get no marker.
+  const markerSeq = search.active
+    ? undefined
+    : unreadMarkerSeq(props.entries, props.unread);
+  let unreadMarkerPending = markerSeq !== undefined;
+  // Entries are in seq order, so the first row that reaches the marker seq
+  // gets the marker.
+  const pushRow = (seq: number | undefined, row: ReactNode) => {
+    if (unreadMarkerPending && seq !== undefined && seq >= markerSeq!) {
+      unreadMarkerPending = false;
+      rows.push(<TranscriptUnreadMarker key="unread-marker" />);
+    }
+    rows.push(row);
+  };
 
   const renderEntry = (entry: TranscriptEntry): ReactNode => {
     if (entry.kind === "subagent") return props.renderSubagent(entry);
@@ -359,8 +386,16 @@ function TranscriptEntryList(props: {
           keyPrefix: props.keyPrefix,
           knownKeys: activityKeys.current,
         });
-        rows.push(
-          <TranscriptRow anchorKey={activityKey} indent key={activityKey}>
+        const lastSeq = lastEntrySeq(activityEntries);
+        // The marker goes before the group when any of it is unread.
+        pushRow(
+          lastSeq,
+          <TranscriptRow
+            anchorKey={activityKey}
+            indent
+            key={activityKey}
+            seq={lastSeq}
+          >
             <TranscriptActivityGroup
               entries={visibleEntries}
               renderEntry={renderEntry}
@@ -373,8 +408,9 @@ function TranscriptEntryList(props: {
 
     if (!search.active || entryMatchesSearch(entry, search.normalizedQuery)) {
       const rowKey = `${props.keyPrefix}:${entry.key}`;
-      rows.push(
-        <TranscriptRow anchorKey={rowKey} key={rowKey}>
+      pushRow(
+        entry.seq,
+        <TranscriptRow anchorKey={rowKey} key={rowKey} seq={entry.seq}>
           {renderEntry(entry)}
         </TranscriptRow>,
       );
@@ -391,6 +427,39 @@ function TranscriptEntryList(props: {
   return rows;
 }
 
+/**
+ * Find the seq of the first unread row. Entries are in seq order, and pending
+ * sends without a seq come last, so a binary search finds the first seq after
+ * the read position. Rows after the range arrived after open, so they get no
+ * marker.
+ */
+function unreadMarkerSeq(
+  entries: readonly TranscriptEntry[],
+  unread: TranscriptUnreadRange | undefined,
+): number | undefined {
+  if (!unread) return undefined;
+  let low = 0;
+  let high = entries.length;
+  while (low < high) {
+    const middle = (low + high) >> 1;
+    const seq = entries[middle]!.seq;
+    if (seq !== undefined && seq <= unread.afterSeq) low = middle + 1;
+    else high = middle;
+  }
+  const seq = entries[low]?.seq;
+  return seq !== undefined && seq <= unread.throughSeq ? seq : undefined;
+}
+
+function lastEntrySeq(
+  entries: readonly RenderedTranscriptEntry[],
+): number | undefined {
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    const seq = entries[index]!.seq;
+    if (seq !== undefined) return seq;
+  }
+  return undefined;
+}
+
 /** Keep one activity group mounted while new or historical events extend either edge. */
 function stableActivityGroupKey(args: {
   claimedKeys: Set<string>;

package/src/client/conversations/TranscriptRows.tsx

@@ -15,17 +15,40 @@ export function TranscriptRows({
   );
 }
 
+/**
+ * Mark where unread rows start. The pinning hook can open the transcript here.
+ */
+export function TranscriptUnreadMarker() {
+  return (
+    <div
+      className="flex items-center gap-3 py-1"
+      data-transcript-unread-marker=""
+      role="separator"
+      aria-label="New messages"
+    >
+      <span className="h-px flex-1 bg-dashboard-accent/50" />
+      <span className="shrink-0 font-sans text-xs font-semibold text-dashboard-accent-text">
+        New
+      </span>
+      <span className="h-px flex-1 bg-dashboard-accent/50" />
+    </div>
+  );
+}
+
 /** Leave room for control outlines inside the mobile row's paint bounds. */
 export function TranscriptRow(props: {
   /** Stable row id that holds the reader's place while layout changes. */
   anchorKey?: string;
   children: ReactNode;
   indent?: boolean;
+  /** Last event sequence in the row. Read positions use it. */
+  seq?: number;
 }) {
   return (
     <div
       className="mobile-transcript-row -mx-2 px-2 py-1.5"
       data-scroll-anchor={props.anchorKey}
+      data-transcript-seq={props.seq}
     >
       {props.indent ? (
         <div className="pl-11">{props.children}</div>

package/src/client/conversations/TranscriptView.tsx

@@ -22,6 +22,10 @@ import {
   usePinnedTranscriptBottom,
 } from "./transcriptBottomPinning";
 import type { TranscriptViewMode } from "./transcriptRenderModel";
+import {
+  useTranscriptReadReporter,
+  type TranscriptUnreadRange,
+} from "./transcriptReadPosition";
 import { TranscriptSearchProvider } from "./transcriptSearch";
 import {
   TurnContextPanelProvider,
@@ -34,9 +38,13 @@ export function Transcript(props: {
   historyError?: Error | null;
   historyVersion?: string;
   live?: boolean;
+  /** The read position when the Conversation opened. */
+  lastReadSeq?: number;
   loadingPreviousPage?: boolean;
   pinRequestVersion?: number;
   onLoadPreviousPage?: () => void;
+  /** Receive the last event sequence the reader saw in the transcript. */
+  onRead?: (seq: number) => void;
   onSelectedEventSeqChange?(seq: number | undefined): void;
   /** The reader's own sends to show at the end until history has them. */
   pendingMessages?: readonly ConversationMailboxMessage[];
@@ -51,6 +59,10 @@ export function Transcript(props: {
   transcript?: ConversationTranscript;
   /** Show turn context in the owner's panel. Without it, a drawer opens. */
   turnContextPanel?: TurnContextPanel;
+  /** Open at the "New" marker instead of the latest message. */
+  startAtUnread?: boolean;
+  /** Rows that were unread when the Conversation opened get a marker. */
+  unread?: TranscriptUnreadRange;
   view?: TranscriptViewMode;
 }) {
   const view = props.view ?? "rich";
@@ -64,6 +76,7 @@ export function Transcript(props: {
     historyVersion: props.historyVersion ?? "empty",
     juniorMessageVersion: transcriptJuniorMessageVersion(props.transcript),
     pinRequestVersion: props.pinRequestVersion,
+    startAtUnread: view === "rich" && props.startAtUnread,
     view,
     versions: {
       rich: transcriptBottomVersion(props.transcript, "rich"),
@@ -71,6 +84,14 @@ export function Transcript(props: {
     },
   });
 
+  // Read positions follow the transcript rows, not the event log. Search
+  // results skip rows, so they do not move the read position.
+  useTranscriptReadReporter({
+    content: bottomPinning.contentElement,
+    lastReadSeq: props.lastReadSeq,
+    onRead: props.onRead,
+    paused: view !== "rich" || search.trim().length > 0,
+  });
   const loadPreviousPage = () => props.onLoadPreviousPage?.();
   const previousPageRef = useAutoLoadPreviousPage({
     enabled: Boolean(
@@ -144,6 +165,7 @@ export function Transcript(props: {
               conversation={props.transcript}
               pendingMessages={props.pendingMessages}
               responding={props.responding ?? props.live ?? false}
+              unread={props.unread}
             />
           </TurnContextPanelProvider>
         )}

package/src/client/conversations/queries.ts

@@ -178,9 +178,12 @@ export function conversationDetailQueryOptions(
     structuralSharing: (previous, next) => {
       if (!next || typeof next !== "object") return next;
       if (!previous || typeof previous !== "object") return next;
-      return reuseConversationEventReferences(
+      return keepLatestReadPosition(
         previous as ConversationSnapshot,
-        next as ConversationSnapshot,
+        reuseConversationEventReferences(
+          previous as ConversationSnapshot,
+          next as ConversationSnapshot,
+        ),
       );
     },
     refetchInterval: (query) =>
@@ -196,6 +199,20 @@ export function conversationDetailQueryOptions(
   });
 }
 
+/**
+ * Read positions only move forward. A poll that started before a read report
+ * finished must not put an older position back in the cache.
+ */
+function keepLatestReadPosition(
+  previous: ConversationSnapshot,
+  next: ConversationSnapshot,
+): ConversationSnapshot {
+  const kept = previous.readPosition;
+  if (!kept) return next;
+  if ((next.readPosition?.lastReadSeq ?? -1) >= kept.lastReadSeq) return next;
+  return { ...next, readPosition: kept };
+}
+
 function outboxActorIdentity(
   queryClient: QueryClient,
 ): ActorIdentity | undefined {
@@ -704,14 +721,17 @@ export function useConversationData(conversationId: string | undefined) {
     0,
     ...awaitingRows.map((message) => Date.parse(message.createdAt)),
   );
-  const detail = useQuery(
-    conversationDetailQueryOptions(conversationId, {
+  const detail = useQuery({
+    ...conversationDetailQueryOptions(conversationId, {
       awaitingMessage: awaitingRows.length > 0,
       fastPollUntilMs: latestSendAtMs
         ? latestSendAtMs + FAST_POLL_WINDOW_MS
         : undefined,
     }),
-  );
+    // A reopened Conversation shows the cached copy at once, but it can miss
+    // messages that arrived while the reader was away. Fetch it each visit.
+    refetchOnMount: "always",
+  });
   // Defer the whole server snapshot, not history alone. Queue removal and the
   // matching transcript must paint together while composer input stays urgent.
   const deferredDetail = useDeferredValue(detail.data);
@@ -893,6 +913,11 @@ export function useConversationData(conversationId: string | undefined) {
       ? history.hasNextPage
       : Boolean(detailData?.previousCursor),
     isPending: detail.isPending,
+    /** The latest detail after a fetch in this visit, before it is deferred. */
+    fetchedDetail:
+      detail.isFetchedAfterMount && !detail.isFetching
+        ? detail.data
+        : undefined,
     isLoadingPreviousPage,
     pendingAuthorization: mailbox?.authorization,
     pendingGeneratedAt: mailbox?.generatedAt,

package/src/client/conversations/transcriptBottomPinning.ts

@@ -22,6 +22,8 @@ import {
 const BOTTOM_PROXIMITY_PX = 96;
 const PREVIOUS_PAGE_PROXIMITY_PX = 600;
 const USER_SCROLL_DELTA_PX = 2;
+// Leave a little earlier context above the "New" marker.
+const UNREAD_START_OFFSET_PX = 48;
 const PIN_START_ATTRIBUTE = "data-transcript-pin-start";
 const PIN_START_MARGIN_PX = 16;
 
@@ -46,6 +48,7 @@ export type ScrollSnapshot = {
 
 type BottomPinResult = {
   anchorRef: RefObject<HTMLDivElement | null>;
+  contentElement: HTMLDivElement | null;
   contentRef: RefCallback<HTMLDivElement>;
   hasPendingUpdate: boolean;
   jumpToBottom: () => void;
@@ -259,14 +262,19 @@ export function terminalReplyPinState(input: {
 
 /**
  * Show the jump control only when the reader left the bottom and a newer tail
- * arrived. Staying pinned, or intentionally following, must not flash it.
+ * arrived, or when the transcript opened at unread rows. Staying pinned, or
+ * intentionally following, must not flash it.
  */
 export function shouldShowJumpToLatest(input: {
   enabled: boolean;
   following: boolean;
   hasPendingUpdate: boolean;
+  openedAtUnread?: boolean;
 }): boolean {
-  return input.enabled && !input.following && input.hasPendingUpdate;
+  return (
+    !input.following &&
+    (Boolean(input.openedAtUnread) || (input.enabled && input.hasPendingUpdate))
+  );
 }
 
 /** Resolve scroll intent with user upward movement taking precedence over bottom slack. */
@@ -314,6 +322,8 @@ export function usePinnedTranscriptBottom(input: {
   historyVersion: string;
   juniorMessageVersion: string;
   pinRequestVersion?: number;
+  /** Open at the "New" marker when the transcript has one. */
+  startAtUnread?: boolean;
   view: TranscriptViewMode;
   versions: Record<TranscriptViewMode, string>;
 }): BottomPinResult {
@@ -337,6 +347,7 @@ export function usePinnedTranscriptBottom(input: {
   const seenPinStartsRef = useRef(new Set<string>());
   const [following, setFollowing] = useState(false);
   const [hasPendingUpdate, setHasPendingUpdate] = useState(false);
+  const [openedAtUnread, setOpenedAtUnread] = useState(false);
   const [contentElement, setContentElement] = useState<HTMLDivElement | null>(
     null,
   );
@@ -351,9 +362,14 @@ export function usePinnedTranscriptBottom(input: {
     if (!input.enabled) setHasPendingUpdate(false);
   }, [input.enabled]);
 
+  // The transcript opened at the latest message, but the reader prefers the
+  // "New" marker. The marker can appear when a fetch replaces a cached detail.
+  const awaitingUnreadMarkerRef = useRef(false);
   const setFollowingIntent = useCallback((value: boolean) => {
     followingRef.current = value;
     setFollowing(value);
+    if (value) setOpenedAtUnread(false);
+    else awaitingUnreadMarkerRef.current = false;
   }, []);
 
   const rememberPlace = useCallback(() => {
@@ -502,6 +518,32 @@ export function usePinnedTranscriptBottom(input: {
     [setFollowingIntent],
   );
 
+  /** Scroll to the "New" marker, if the transcript has one. */
+  const openAtUnreadMarker = useCallback((): boolean => {
+    const content = contentElementRef.current;
+    const root = scrollRootFor(content);
+    const marker = content?.querySelector("[data-transcript-unread-marker]");
+    if (!root || !marker) return false;
+    awaitingUnreadMarkerRef.current = false;
+    const offset =
+      marker.getBoundingClientRect().top - viewportBounds(root).top;
+    setScrollTop(
+      root,
+      Math.max(
+        0,
+        scrollSnapshot(root).scrollTop + offset - UNREAD_START_OFFSET_PX,
+      ),
+    );
+    const snapshot = scrollSnapshot(root);
+    previousScrollTopRef.current = snapshot.scrollTop;
+    // Unread rows that fit above the bottom leave the reader at the latest.
+    const atBottom = isNearScrollBottom(snapshot);
+    setFollowingIntent(atBottom);
+    setOpenedAtUnread(!atBottom);
+    rememberPlace();
+    return true;
+  }, [rememberPlace, setFollowingIntent]);
+
   useBrowserLayoutEffect(() => {
     if (!contentElement || !input.conversationId) return;
     if (initializedConversationRef.current === input.conversationId) return;
@@ -510,24 +552,40 @@ export function usePinnedTranscriptBottom(input: {
     if (!root) return;
 
     initializedConversationRef.current = input.conversationId;
+    setHasPendingUpdate(false);
+    if (input.startAtUnread && openAtUnreadMarker()) return;
+
     setScrollTop(root, scrollSnapshot(root).scrollHeight);
     previousScrollTopRef.current = scrollSnapshot(root).scrollTop;
-    // Start every conversation at its latest message. Keep following until the
-    // reader scrolls up so late content and footer layout cannot expose stale
-    // space below the transcript.
+    // Without unread rows, start at the latest message. Keep following until
+    // the reader scrolls up so late content and footer layout cannot expose
+    // stale space below the transcript.
     setFollowingIntent(true);
-    setHasPendingUpdate(false);
-  }, [contentElement, input.conversationId, setFollowingIntent]);
+    awaitingUnreadMarkerRef.current = Boolean(input.startAtUnread);
+  }, [
+    contentElement,
+    input.conversationId,
+    input.startAtUnread,
+    openAtUnreadMarker,
+    setFollowingIntent,
+  ]);
+
+  // Follow the latest message, unless the "New" marker appeared before the
+  // reader moved. Then open at the marker, as if it was there at the start.
+  const followLatest = useCallback(() => {
+    if (awaitingUnreadMarkerRef.current && openAtUnreadMarker()) return;
+    scrollToBottom("auto");
+  }, [openAtUnreadMarker, scrollToBottom]);
 
   const syncAfterLayoutChange = useCallback(() => {
     if (followingRef.current) {
-      scrollToBottom("auto");
+      followLatest();
       return;
     }
 
     restorePlace();
     measurePosition("measure");
-  }, [measurePosition, restorePlace, scrollToBottom]);
+  }, [followLatest, measurePosition, restorePlace]);
 
   // An earlier page renders above the reader. Hold their place before paint;
   // a reader at the bottom stays at the latest message.
@@ -568,7 +626,7 @@ export function usePinnedTranscriptBottom(input: {
         following: followingRef.current,
       })
     ) {
-      scrollToBottom("auto");
+      followLatest();
       setHasPendingUpdate(false);
       return;
     }
@@ -581,7 +639,7 @@ export function usePinnedTranscriptBottom(input: {
     input.view,
     input.versions.rich,
     input.versions.raw,
-    scrollToBottom,
+    followLatest,
     setFollowingIntent,
   ]);
 
@@ -655,6 +713,7 @@ export function usePinnedTranscriptBottom(input: {
   }, [contentElement, syncAfterLayoutChange]);
 
   const jumpToBottom = useCallback(() => {
+    awaitingUnreadMarkerRef.current = false;
     setFollowingIntent(true);
     setHasPendingUpdate(false);
     scrollToBottom(preferredExplicitScrollBehavior());
@@ -698,6 +757,7 @@ export function usePinnedTranscriptBottom(input: {
   return useMemo(
     () => ({
       anchorRef,
+      contentElement,
       contentRef,
       hasPendingUpdate,
       jumpToBottom,
@@ -705,9 +765,18 @@ export function usePinnedTranscriptBottom(input: {
         enabled: input.enabled,
         following,
         hasPendingUpdate,
+        openedAtUnread,
       }),
     }),
-    [contentRef, following, hasPendingUpdate, input.enabled, jumpToBottom],
+    [
+      contentElement,
+      contentRef,
+      following,
+      hasPendingUpdate,
+      input.enabled,
+      jumpToBottom,
+      openedAtUnread,
+    ],
   );
 }
 
@@ -744,7 +813,8 @@ export function useAutoLoadPreviousPage(input: {
   return setSentinel;
 }
 
-function scrollRootFor(element: HTMLElement | null): ScrollRoot | null {
+/** Find the nearest element that scrolls the transcript, or the window. */
+export function scrollRootFor(element: HTMLElement | null): ScrollRoot | null {
   if (typeof window === "undefined") return null;
   if (!element) return window;
 
@@ -819,6 +889,7 @@ function setScrollTop(
   root.scrollTo({ behavior, top: scrollTop });
 }
 
+/** Read the visible band of a scroll root in client coordinates. */
 function viewportBounds(root: ScrollRoot): { bottom: number; top: number } {
   if (isWindowRoot(root)) return { bottom: window.innerHeight, top: 0 };
   const top = root.getBoundingClientRect().top;