@sentry/junior-dashboard 0.279.0 → 0.281.0

package/src/client/conversations/{transcriptUnreadHistory.ts → transcriptAroundHistory.ts}

@@ -1,11 +1,13 @@
 /**
- * Open a long Conversation at the reader's read position.
+ * Open a long Conversation away from its latest events: at the reader's read
+ * position, or at a linked event, Turn, or memory.
  *
  * The detail holds the latest page of events. When the read position is
  * older than that page, the transcript starts with the page around the read
  * position instead: the last read events and the unread events after them.
  * The first detail fetch of a visit brings that page, so it needs no second
- * request.
+ * request. A link to a row that the transcript does not hold starts it with
+ * the page around that row, which the server finds in one request.
  * Like earlier pages, newer pages load when the reader scrolls near them, so
  * the server reads only the pages that the reader reaches.
  *
@@ -54,23 +56,33 @@ export type TranscriptHistory = {
 };
 
 /**
- * Load the transcript from `unreadCursor`. Returns `undefined` when there is
- * no cursor, or when the first page fails, so the caller shows the latest
- * page instead.
+ * The row that the transcript opens at: the `unreadCursor` of the read
+ * position, or a linked event seq or Turn id.
  */
-export function useUnreadHistory(input: {
+export type HistoryStart =
+  | { around: string }
+  | { event: string }
+  | { turn: string };
+
+/**
+ * Load the transcript from the page around `start`. Returns `undefined` when
+ * there is no start, or when the first page fails, so the caller shows the
+ * latest page instead.
+ */
+export function useHistoryAround(input: {
   conversationId: string;
   /** The latest page, from the polled detail. */
   detail: ConversationDetailReport | undefined;
-  /** `unreadCursor` from the detail when the Conversation opened. */
-  unreadCursor: string | undefined;
-  /** Skip the newer pages. The caller then passes no `unreadCursor`. */
+  start?: HistoryStart;
+  /** Skip the newer pages. The caller then passes no `start`. */
   onShowLatest: () => void;
-  /** The page around `unreadCursor`, when the detail brought it. */
-  unreadPage?: ConversationEventPage;
+  /** The page around `start` failed. */
+  onStartFailed?: () => void;
+  /** The page around `start`, when the detail brought it. */
+  startPage?: ConversationEventPage;
 }): (TranscriptHistory & { isPending: boolean }) | undefined {
-  const { conversationId, detail, onShowLatest, unreadCursor, unreadPage } =
-    input;
+  const { conversationId, detail, onShowLatest, onStartFailed, start } = input;
+  const startKey = start ? Object.entries(start)[0]?.join(":") : undefined;
   const latestEventsRef = useRef<ConversationReportEvent[]>([]);
   const latestEvents = useMemo(() => {
     const kept = keepLatestEvents(latestEventsRef.current, detail?.events);
@@ -78,28 +90,24 @@ export function useUnreadHistory(input: {
     return kept;
   }, [detail?.events]);
   const latestFirstSeq = latestEvents[0]?.seq;
-  const joinedRef = useRef(false);
+  // The start whose newer pages joined the latest page.
+  const joinedRef = useRef<string>(undefined);
   const newer = useInfiniteQuery({
-    // Only the page around the read position loads by itself. The data never
-    // goes stale, so a refetch cannot reload every newer page at once.
-    enabled: Boolean(unreadCursor),
+    // Only the page around the start loads by itself. The data never goes
+    // stale, so a refetch cannot reload every newer page at once.
+    enabled: Boolean(start),
     staleTime: Infinity,
-    // Each visit starts again from the page around the read position. Pages
-    // from an earlier visit can end at an old latest event, which would
-    // leave a gap before the latest page.
+    // Each visit starts again from the page around the start. Pages from an
+    // earlier visit can end at an old latest event, which would leave a gap
+    // before the latest page.
     gcTime: 0,
-    queryKey: ["conversation", conversationId, "unread", unreadCursor, "newer"],
+    queryKey: ["conversation", conversationId, "around", startKey, "newer"],
     queryFn: ({ pageParam, signal }) =>
       readConversationEventsFrom(conversationId, pageParam, signal),
-    initialPageParam: { around: unreadCursor ?? "" } as NewerPageParam,
+    initialPageParam: (start ?? { around: "" }) as NewerPageParam,
     // The page that came with the detail. Without it, the query reads it.
-    ...(unreadPage
-      ? {
-          initialData: {
-            pageParams: [{ around: unreadCursor ?? "" }],
-            pages: [unreadPage],
-          },
-        }
+    ...(input.startPage && start
+      ? { initialData: { pageParams: [start], pages: [input.startPage] } }
       : undefined),
     getNextPageParam: (page): NewerPageParam | undefined =>
       reachesLatest(page, latestFirstSeq) || !page.nextCursor
@@ -110,13 +118,7 @@ export function useUnreadHistory(input: {
   const firstNewerPage = newer.data?.pages[0];
   const earlier = useInfiniteQuery({
     enabled: false,
-    queryKey: [
-      "conversation",
-      conversationId,
-      "unread",
-      unreadCursor,
-      "earlier",
-    ],
+    queryKey: ["conversation", conversationId, "around", startKey, "earlier"],
     queryFn: ({ pageParam, signal }) =>
       readConversationEvents(conversationId, pageParam, signal),
     initialPageParam: firstNewerPage?.previousCursor ?? "",
@@ -130,16 +132,20 @@ export function useUnreadHistory(input: {
   const reached = lastNewerPage
     ? reachesLatest(lastNewerPage, latestFirstSeq)
     : false;
-  if (reached) joinedRef.current = true;
+  if (reached) joinedRef.current = startKey;
   // No newer page can fill the gap before the latest page, or the latest
   // events already on screen would leave until one does.
   const skipped =
     lastNewerPage !== undefined &&
     !reached &&
-    (joinedRef.current || !lastNewerPage.nextCursor);
+    (joinedRef.current === startKey || !lastNewerPage.nextCursor);
   useEffect(() => {
     if (skipped) onShowLatest();
   }, [onShowLatest, skipped]);
+  const startFailed = Boolean(start && newer.error && !newerPages);
+  useEffect(() => {
+    if (startFailed) onStartFailed?.();
+  }, [onStartFailed, startFailed]);
   const pages = useMemo(
     () => [...(earlierPages ?? []), ...(newerPages ?? [])],
     [earlierPages, newerPages],
@@ -156,7 +162,7 @@ export function useUnreadHistory(input: {
     [detail, latestEvents, newerPages, pages, reached],
   );
 
-  if (!unreadCursor || skipped || (newer.error && !newerPages)) {
+  if (!start || skipped || startFailed) {
     return undefined;
   }
 
@@ -225,10 +231,10 @@ function reachesLatest(
   return lastSeq + 1 >= latestFirstSeq;
 }
 
-/** The first page is around the read position. The rest follow it. */
-type NewerPageParam = { around: string } | { after: string };
+/** The first page is around the start. The rest follow it. */
+type NewerPageParam = HistoryStart | { after: string };
 
-/** Read one bounded page of events around or after a history cursor. */
+/** Read one bounded page of events around a start or after a cursor. */
 function readConversationEventsFrom(
   conversationId: string,
   param: NewerPageParam,

package/src/client/conversations/transcriptBottomPinning.ts

@@ -1,4 +1,5 @@
 import {
+  createContext,
   useCallback,
   useEffect,
   useLayoutEffect,
@@ -52,6 +53,8 @@ type BottomPinResult = {
   contentRef: RefCallback<HTMLDivElement>;
   hasPendingUpdate: boolean;
   jumpToBottom: () => void;
+  /** The `data-scroll-anchor` key of the row that holds the reader's place. */
+  scrollAnchorKey: () => string | undefined;
   showJumpToLatest: boolean;
 };
 
@@ -319,6 +322,8 @@ export function usePinnedTranscriptBottom(input: {
   historyVersion: string;
   juniorMessageVersion: string;
   pinRequestVersion?: number;
+  /** Open where a link shows its row, not at the latest message. */
+  startAtLink?: boolean;
   /** Open at the "New" marker when the transcript has one. */
   startAtUnread?: boolean;
   view: TranscriptViewMode;
@@ -331,10 +336,14 @@ export function usePinnedTranscriptBottom(input: {
   endsAtLatestRef.current = input.endsAtLatest ?? true;
   const followingRef = useRef(false);
   const initializedRef = useRef(false);
-  const initializedConversationRef = useRef<string | null>(null);
+  // The Conversation and start that the transcript opened with. A link at
+  // open that fails becomes a normal start, so the transcript opens again.
+  const startedRef = useRef<string | null>(null);
   const previousScrollTopRef = useRef<number | null>(null);
-  // The scroll position that the last restore set. Its scroll event is not
-  // a reader scroll, so it must not change follow intent.
+  // The scroll position that the last restore or open at the marker set.
+  // Its scroll event is not a reader scroll, so it must not change follow
+  // intent or the recorded place. Rows can change size before that event,
+  // and the restore after them needs the place from before.
   const restoredScrollTopRef = useRef<number | null>(null);
   const scrollAnchorRef = useRef<ScrollAnchor | null>(null);
   const pinRequestVersionRef = useRef(input.pinRequestVersion ?? 0);
@@ -415,7 +424,6 @@ export function usePinnedTranscriptBottom(input: {
       const root = scrollRootFor(contentElementRef.current);
       if (!root) return;
 
-      if (source === "scroll") rememberPlace();
       const snapshot = scrollSnapshot(root);
       const previousScrollTop = previousScrollTopRef.current;
       previousScrollTopRef.current = snapshot.scrollTop;
@@ -427,6 +435,7 @@ export function usePinnedTranscriptBottom(input: {
         if (restored !== null && Math.abs(snapshot.scrollTop - restored) < 1) {
           return;
         }
+        rememberPlace();
       }
 
       const intent = transcriptFollowIntent({
@@ -536,6 +545,7 @@ export function usePinnedTranscriptBottom(input: {
     );
     const snapshot = scrollSnapshot(root);
     previousScrollTopRef.current = snapshot.scrollTop;
+    restoredScrollTopRef.current = snapshot.scrollTop;
     // Unread rows that fit above the bottom leave the reader at the latest.
     const atBottom = endsAtLatestRef.current && isNearScrollBottom(snapshot);
     setFollowingIntent(atBottom);
@@ -546,13 +556,20 @@ export function usePinnedTranscriptBottom(input: {
 
   useBrowserLayoutEffect(() => {
     if (!contentElement || !input.conversationId) return;
-    if (initializedConversationRef.current === input.conversationId) return;
+    const start = `${input.conversationId}:${input.startAtLink ? "link" : "start"}`;
+    if (startedRef.current === start) return;
 
     const root = scrollRootFor(contentElement);
     if (!root) return;
 
-    initializedConversationRef.current = input.conversationId;
+    startedRef.current = start;
     setHasPendingUpdate(false);
+    // The link scrolls to its row, maybe before this runs. Do not move away.
+    if (input.startAtLink) {
+      previousScrollTopRef.current = scrollSnapshot(root).scrollTop;
+      setFollowingIntent(false);
+      return;
+    }
     if (input.startAtUnread && openAtUnreadMarker()) return;
 
     setScrollTop(root, scrollSnapshot(root).scrollHeight);
@@ -565,6 +582,7 @@ export function usePinnedTranscriptBottom(input: {
   }, [
     contentElement,
     input.conversationId,
+    input.startAtLink,
     input.startAtUnread,
     openAtUnreadMarker,
     setFollowingIntent,
@@ -678,7 +696,12 @@ export function usePinnedTranscriptBottom(input: {
     measurePosition("measure");
     rememberPlace();
     // Listen on the scroll root, so gestures outside transcript rows count.
-    target.addEventListener("scroll", onScroll, { passive: true });
+    // Capture runs first at the root, so the place is recorded before a
+    // virtual list mounts the rows for the new position.
+    target.addEventListener("scroll", onScroll, {
+      capture: true,
+      passive: true,
+    });
     target.addEventListener("wheel", onWheel, { passive: true });
     target.addEventListener("touchstart", onTouchStart, {
       passive: true,
@@ -688,7 +711,7 @@ export function usePinnedTranscriptBottom(input: {
     });
     window.addEventListener("resize", syncAfterLayoutChange);
     return () => {
-      target.removeEventListener("scroll", onScroll);
+      target.removeEventListener("scroll", onScroll, { capture: true });
       target.removeEventListener("wheel", onWheel);
       target.removeEventListener("touchstart", onTouchStart);
       target.removeEventListener("touchmove", onTouchMove);
@@ -761,6 +784,8 @@ export function usePinnedTranscriptBottom(input: {
     scrollToBottom("auto");
   }, [input.pinRequestVersion, scrollToBottom, setFollowingIntent]);
 
+  const scrollAnchorKey = useCallback(() => scrollAnchorRef.current?.key, []);
+
   return useMemo(
     () => ({
       anchorRef,
@@ -768,6 +793,7 @@ export function usePinnedTranscriptBottom(input: {
       contentRef,
       hasPendingUpdate,
       jumpToBottom,
+      scrollAnchorKey,
       showJumpToLatest: shouldShowJumpToLatest({
         enabled: input.enabled,
         endsAtLatest: input.endsAtLatest,
@@ -785,10 +811,16 @@ export function usePinnedTranscriptBottom(input: {
       input.endsAtLatest,
       jumpToBottom,
       openedAtUnread,
+      scrollAnchorKey,
     ],
   );
 }
 
+/** Jump to the latest row from inside the transcript, like the floating pill. */
+export const TranscriptJumpToLatestContext = createContext<
+  (() => void) | undefined
+>(undefined);
+
 /**
  * Load the next history page when the reader scrolls near the edge where it
  * goes: the top for earlier pages, the bottom for newer pages.

package/src/client/conversations/transcriptListRows.ts

@@ -0,0 +1,215 @@
+import {
+  isCollapsibleActivityEntry,
+  quietTurnEntryKeys,
+} from "./TranscriptActivityGroup";
+import type { RenderedTranscriptEntry } from "./transcriptRenderModel";
+import { entryMatchesSearch } from "./transcriptSearch";
+import type { TranscriptUnreadRange } from "./transcriptReadPosition";
+
+/** One row of the rich transcript list, in seq order. */
+export type TranscriptListRow =
+  | { kind: "unread_marker"; key: string }
+  | {
+      kind: "entry";
+      entry: RenderedTranscriptEntry;
+      key: string;
+      seq?: number;
+    }
+  | {
+      kind: "activity";
+      entries: RenderedTranscriptEntry[];
+      key: string;
+      /** Last event sequence in the group. */
+      seq?: number;
+    };
+
+/** The key of the "New" marker row. */
+export const UNREAD_MARKER_KEY = "unread-marker";
+
+/**
+ * Turn transcript entries into list rows. Runs of collapsible activity
+ * become one group row, search drops rows that do not match, and the
+ * "New" marker becomes its own row before the first unread row.
+ *
+ * `knownActivityKeys` maps entry keys to group keys across calls, so a
+ * group keeps its key while events extend either edge.
+ */
+export function transcriptListRows(input: {
+  entries: readonly RenderedTranscriptEntry[];
+  keyPrefix: string;
+  knownActivityKeys: Map<string, string>;
+  /** The normalized search query, when search is active. */
+  search?: string;
+  unread?: TranscriptUnreadRange;
+}): TranscriptListRow[] {
+  const { entries, search } = input;
+  const quietKeys = quietTurnEntryKeys(entries);
+  const collapsible = (entry: RenderedTranscriptEntry) =>
+    isCollapsibleActivityEntry(entry) || quietKeys.has(entry.key);
+  const matches = (entry: RenderedTranscriptEntry) =>
+    search === undefined || entryMatchesSearch(entry, search);
+  const claimedActivityKeys = new Set<string>();
+  const rows: TranscriptListRow[] = [];
+  // Search results are not a reading order, so they get no marker.
+  const markerSeq =
+    search === undefined ? unreadMarkerSeq(entries, input.unread) : undefined;
+  let markerPending = markerSeq !== undefined;
+  // Entries are in seq order, so the first row that reaches the marker seq
+  // gets the marker.
+  const pushRow = (
+    row: Exclude<TranscriptListRow, { kind: "unread_marker" }>,
+  ) => {
+    if (markerPending && row.seq !== undefined && row.seq >= markerSeq!) {
+      markerPending = false;
+      rows.push({ kind: "unread_marker", key: UNREAD_MARKER_KEY });
+    }
+    rows.push(row);
+  };
+
+  for (let index = 0; index < entries.length; ) {
+    const entry = entries[index]!;
+    if (collapsible(entry)) {
+      const group: RenderedTranscriptEntry[] = [];
+      while (index < entries.length && collapsible(entries[index]!)) {
+        group.push(entries[index]!);
+        index += 1;
+      }
+      const visible = group.filter(matches);
+      if (visible.length > 0) {
+        // The marker goes before the group when any of it is unread.
+        pushRow({
+          kind: "activity",
+          entries: visible,
+          key: stableActivityGroupKey({
+            claimedKeys: claimedActivityKeys,
+            entries: group,
+            keyPrefix: input.keyPrefix,
+            knownKeys: input.knownActivityKeys,
+          }),
+          seq: lastEntrySeq(group),
+        });
+      }
+      continue;
+    }
+    if (matches(entry)) {
+      pushRow({
+        kind: "entry",
+        entry,
+        key: `${input.keyPrefix}:${entry.key}`,
+        seq: entry.seq,
+      });
+    }
+    index += 1;
+  }
+  return rows;
+}
+
+/**
+ * Find the first row whose last seq is at or after `seq`. The New marker
+ * sorts with the row before it, and other rows without a seq come last, so a
+ * binary search works. Returns `rows.length` when no row reaches it.
+ */
+export function rowIndexForSeq(
+  rows: readonly TranscriptListRow[],
+  seq: number,
+): number {
+  let low = 0;
+  let high = rows.length;
+  while (low < high) {
+    const middle = (low + high) >> 1;
+    const row = rows[middle]!;
+    const rowSeq =
+      row.kind === "unread_marker"
+        ? (rowSeqBefore(rows, middle) ?? Number.NEGATIVE_INFINITY)
+        : row.seq;
+    if (rowSeq !== undefined && rowSeq < seq) low = middle + 1;
+    else high = middle;
+  }
+  return low;
+}
+
+function rowSeqBefore(
+  rows: readonly TranscriptListRow[],
+  index: number,
+): number | undefined {
+  const row = rows[index - 1];
+  return row === undefined || row.kind === "unread_marker"
+    ? undefined
+    : row.seq;
+}
+
+/**
+ * Group rows whose heights are alike, so a row can borrow the measured
+ * height of others before it renders.
+ */
+export function transcriptRowSizeClass(row: TranscriptListRow): string {
+  if (row.kind !== "entry") return row.kind;
+  const { entry } = row;
+  return entry.kind === "message"
+    ? `message:${entry.message.role}`
+    : entry.kind;
+}
+
+/** Guess the height of a row of a size class before any of them measure. */
+export function defaultTranscriptRowSize(sizeClass: string): number {
+  if (sizeClass === "unread_marker") return 32;
+  if (sizeClass === "activity") return 36;
+  if (sizeClass === "attachments_delivered") return 240;
+  if (sizeClass === "message:assistant") return 120;
+  if (sizeClass.startsWith("message:")) return 80;
+  return 44;
+}
+
+/**
+ * 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 RenderedTranscriptEntry[],
+  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>;
+  entries: RenderedTranscriptEntry[];
+  keyPrefix: string;
+  knownKeys: Map<string, string>;
+}): string {
+  const entryKeys = args.entries.map(
+    (entry) => `${args.keyPrefix}:${entry.key}`,
+  );
+  const knownKey = entryKeys
+    .map((entryKey) => args.knownKeys.get(entryKey))
+    .find((key) => key !== undefined && !args.claimedKeys.has(key));
+  const groupKey =
+    knownKey ?? `${args.keyPrefix}:activity:${args.entries[0]!.key}`;
+
+  args.claimedKeys.add(groupKey);
+  entryKeys.forEach((entryKey) => args.knownKeys.set(entryKey, groupKey));
+  return groupKey;
+}

package/src/client/conversations/transcriptReadPosition.ts

@@ -4,7 +4,8 @@
  * Rows from stored events carry `data-transcript-seq`. While the page is
  * visible, the reporter sends the sequence of the last row that has reached
  * the viewport. The server keeps the highest value, so every client of the
- * same user shares one position. Detail polls bring it back to other clients.
+ * same user shares one position. A write does not change the detail version,
+ * so other clients get it with the next detail change or a reload.
  *
  * The page reads the position once when a Conversation opens. That value
  * places the "New" marker and, by the reader's preference, where the
@@ -139,6 +140,27 @@ function readPositionAtOpen(
   return { lastReadSeq, unread: { afterSeq: lastReadSeq, throughSeq } };
 }
 
+/**
+ * Put a stored read position in the cached detail. Polls answer 304 after a
+ * read, so the cache must also drop the unread cursor once the reader reaches
+ * the latest page, as the server would. Otherwise the next visit in this
+ * session opens at rows the reader has already read.
+ */
+function withReadPosition(
+  detail: ConversationDetailReport,
+  readPosition: ConversationReadPosition,
+): ConversationDetailReport {
+  const firstSeq = detail.events[0]?.seq;
+  if (
+    !detail.unreadCursor ||
+    (firstSeq !== undefined && readPosition.lastReadSeq + 1 < firstSeq)
+  ) {
+    return { ...detail, readPosition };
+  }
+  const { unreadCursor: _cursor, unreadPage: _page, ...rest } = detail;
+  return { ...rest, readPosition };
+}
+
 /**
  * Send read positions for one Conversation. A position at or before the one
  * in the cached detail is not sent, because the server already has it. The
@@ -157,7 +179,7 @@ export function useMarkConversationRead(conversationId: string) {
     onSuccess: (readPosition) => {
       queryClient.setQueryData<ConversationDetailReport>(
         conversationDetailQueryKey(conversationId),
-        (detail) => (detail ? { ...detail, readPosition } : detail),
+        (detail) => detail && withReadPosition(detail, readPosition),
       );
     },
   });

package/src/client/conversations/turnContext.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import * as z from "zod";
 
 import type { TranscriptViewTurnContext } from "../types";