From d5dfb4ebdec7303a15f98f8df25bf8a37c7f0d69 Mon Sep 17 00:00:00 2001
From: Paul D'Ambra <paul.dambra@gmail.com>
Date: Tue, 21 Jul 2026 14:59:58 +0100
Subject: [PATCH 01/15] feat(ui): add user-message marker rail to conversation
 scrollbar

Add a marker rail in the scrollbar gutter of both conversation views (the
legacy ConversationView and the new ChatThread). Each user message gets a
darker marker positioned at its scroll offset; clicking jumps to the message
and hovering shows its first few words as a tooltip.

The native browser scrollbar can't be colored per-message or given click
handlers/tooltip points, so this is a thin absolutely-positioned rail beside
the scroll area instead.

- New scrollbar-rail/ module: MessageScrollbarRail (presentation) +
  useMessageRailMarkers (measures rendered user-message rows and computes
  fractional positions; interpolates unmeasured/virtualized rows between
  measured neighbours).
- Legacy ConversationView: VirtualizedList exposes its scroll + content
  elements via the imperative handle; the rail mounts in the container over
  the scrollbar gutter.
- New ChatThread: a ThreadScrollbarRail locates the quill scroller viewport +
  content via a hidden probe (same pattern as StickyHeaderOverlay) and mounts
  the rail inside ChatMessageScroller.

Generated-By: PostHog Code
Task-Id: a950f289-b4c3-472e-b375-0799e0cbf8a4
---
 .../sessions/components/ConversationView.tsx  |  55 +++++
 .../sessions/components/VirtualizedList.tsx   |  12 +
 .../components/chat-thread/ChatThread.tsx     | 103 ++++++++
 .../MessageScrollbarRail.test.tsx             |  89 +++++++
 .../scrollbar-rail/MessageScrollbarRail.tsx   |  81 ++++++
 .../scrollbar-rail/messageRailTypes.ts        |  40 +++
 .../scrollbar-rail/useMessageRailMarkers.ts   | 230 ++++++++++++++++++
 7 files changed, 610 insertions(+)
 create mode 100644 packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.test.tsx
 create mode 100644 packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.tsx
 create mode 100644 packages/ui/src/features/sessions/components/scrollbar-rail/messageRailTypes.ts
 create mode 100644 packages/ui/src/features/sessions/components/scrollbar-rail/useMessageRailMarkers.ts

diff --git a/packages/ui/src/features/sessions/components/ConversationView.tsx b/packages/ui/src/features/sessions/components/ConversationView.tsx
index 5a049e930a..ac6679fd4d 100644
--- a/packages/ui/src/features/sessions/components/ConversationView.tsx
+++ b/packages/ui/src/features/sessions/components/ConversationView.tsx
@@ -23,6 +23,8 @@ import {
 import { MessageJumpPicker } from "@posthog/ui/features/sessions/components/chat-thread/MessageJumpPicker";
 import { THREAD_HOTKEY_OPTIONS } from "@posthog/ui/features/sessions/components/chat-thread/threadHotkeys";
 import { usePromptRecallSource } from "@posthog/ui/features/sessions/components/chat-thread/usePromptRecallSource";
+import { MessageScrollbarRail } from "@posthog/ui/features/sessions/components/scrollbar-rail/MessageScrollbarRail";
+import { useMessageRailMarkers } from "@posthog/ui/features/sessions/components/scrollbar-rail/useMessageRailMarkers";
 import { GitActionMessage } from "@posthog/ui/features/sessions/components/GitActionMessage";
 import { GitActionResult } from "@posthog/ui/features/sessions/components/GitActionResult";
 import { mergeConversationItems } from "@posthog/ui/features/sessions/components/mergeConversationItems";
@@ -235,6 +237,10 @@ export function ConversationView({
         id != null ? itemIdToRowIndexRef.current.get(id) : undefined;
       listRef.current?.scrollToIndex(rowIdx ?? index);
     },
+    // Search doesn't read scroll/content geometry, so these forward to the real
+    // handle purely to satisfy the (now-extended) VirtualizedListHandle shape.
+    getScrollElement: () => listRef.current?.getScrollElement() ?? null,
+    getContentElement: () => listRef.current?.getContentElement() ?? null,
   });
 
   const search = useConversationSearch({
@@ -330,6 +336,54 @@ export function ConversationView({
     [userMessages, scrollToUserMessage],
   );
 
+  // The scrollbar marker rail needs the VirtualizedList's scroll + content
+  // elements. They're only available after mount, so resolve them into state from
+  // the imperative handle; the rail re-renders once they're populated. The list's
+  // internal refs are stable for its lifetime, so a mount-time resolve (with a
+  // rAF retry for the first paint where the ref isn't attached yet) is enough.
+  const [scrollElements, setScrollElements] = useState<{
+    scrollEl: HTMLElement | null;
+    contentEl: HTMLElement | null;
+  }>({ scrollEl: null, contentEl: null });
+  useEffect(() => {
+    const sync = () => {
+      const handle = listRef.current;
+      if (!handle) return;
+      const scrollEl = handle.getScrollElement();
+      const contentEl = handle.getContentElement();
+      setScrollElements((prev) =>
+        prev.scrollEl === scrollEl && prev.contentEl === contentEl
+          ? prev
+          : { scrollEl, contentEl },
+      );
+    };
+    sync();
+    const raf = requestAnimationFrame(sync);
+    return () => cancelAnimationFrame(raf);
+  }, []);
+
+  const railUserMessages = useMemo(
+    () =>
+      userMessages.map((m) => ({
+        id: m.id,
+        content: m.content,
+        index: m.index,
+      })),
+    [userMessages],
+  );
+  const railMarkers = useMessageRailMarkers({
+    contentEl: scrollElements.contentEl,
+    scrollEl: scrollElements.scrollEl,
+    userMessages: railUserMessages,
+    onJump: (id) => {
+      const message = userMessages.find((entry) => entry.id === id);
+      if (!message) return;
+      setKeyboardFocusedMessageId(id);
+      scrollToUserMessage(id, message.index);
+    },
+    activeId: keyboardFocusedMessageId,
+  });
+
   const handleScrollStateChange = useCallback((isAtBottom: boolean) => {
     isAtBottomRef.current = isAtBottom;
     setShowScrollButton(!isAtBottom);
@@ -521,6 +575,7 @@ export function ConversationView({
             scrollX={scrollX}
           />
         </SessionTaskIdProvider>
+        <MessageScrollbarRail markers={railMarkers} />
         {showScrollButton && (
           <Box className="absolute right-6 bottom-4 z-10">
             <Tooltip>
diff --git a/packages/ui/src/features/sessions/components/VirtualizedList.tsx b/packages/ui/src/features/sessions/components/VirtualizedList.tsx
index ef5ae0e174..1e95107336 100644
--- a/packages/ui/src/features/sessions/components/VirtualizedList.tsx
+++ b/packages/ui/src/features/sessions/components/VirtualizedList.tsx
@@ -35,6 +35,14 @@ interface VirtualizedListProps<T> {
 export interface VirtualizedListHandle {
   scrollToBottom: () => void;
   scrollToIndex: (index: number) => void;
+  /** The scrolling element (the `overflow-y-auto` viewport). Exposed so a
+   * scrollbar marker rail can read `scrollTop`/`scrollHeight` and refresh on
+   * scroll. `null` until the list mounts. */
+  getScrollElement: () => HTMLDivElement | null;
+  /** The inner content element whose height == the virtual total size. Rows
+   * (and their `data-conversation-item-id` stamps) live inside this, so a
+   * marker rail measures row offsets against it. `null` until the list mounts. */
+  getContentElement: () => HTMLDivElement | null;
 }
 
 const AT_BOTTOM_THRESHOLD = 50;
@@ -63,6 +71,7 @@ function VirtualizedListInner<T>(
   ref: React.ForwardedRef<VirtualizedListHandle>,
 ) {
   const parentRef = useRef<HTMLDivElement>(null);
+  const contentRef = useRef<HTMLDivElement>(null);
   const footerRef = useRef<HTMLDivElement>(null);
   const initializedRef = useRef(false);
   const isAtBottomRef = useRef(true);
@@ -156,6 +165,8 @@ function VirtualizedListInner<T>(
         isAtBottomRef.current = false;
         virtualizer.scrollToIndex(index, { align: "center" });
       },
+      getScrollElement: () => parentRef.current,
+      getContentElement: () => contentRef.current,
     }),
     [virtualizer, settleAtEnd],
   );
@@ -258,6 +269,7 @@ function VirtualizedListInner<T>(
         style={{ scrollbarGutter: "stable" }}
       >
         <div
+          ref={contentRef}
           style={{
             height: totalSize,
             position: "relative",
diff --git a/packages/ui/src/features/sessions/components/chat-thread/ChatThread.tsx b/packages/ui/src/features/sessions/components/chat-thread/ChatThread.tsx
index 75a79c707a..3b755fe1a8 100644
--- a/packages/ui/src/features/sessions/components/chat-thread/ChatThread.tsx
+++ b/packages/ui/src/features/sessions/components/chat-thread/ChatThread.tsx
@@ -54,6 +54,8 @@ import {
 } from "@posthog/ui/features/sessions/components/chat-thread/ToolGroup";
 import { THREAD_HOTKEY_OPTIONS } from "@posthog/ui/features/sessions/components/chat-thread/threadHotkeys";
 import { usePromptRecallSource } from "@posthog/ui/features/sessions/components/chat-thread/usePromptRecallSource";
+import { MessageScrollbarRail } from "@posthog/ui/features/sessions/components/scrollbar-rail/MessageScrollbarRail";
+import { useMessageRailMarkers } from "@posthog/ui/features/sessions/components/scrollbar-rail/useMessageRailMarkers";
 import { GitActionMessage } from "@posthog/ui/features/sessions/components/GitActionMessage";
 import { GitActionResult } from "@posthog/ui/features/sessions/components/GitActionResult";
 import { mergeConversationItems } from "@posthog/ui/features/sessions/components/mergeConversationItems";
@@ -955,6 +957,10 @@ function ThreadScrollBody({
     >
       <StickyHeaderOverlay items={items} />
       <ThreadAutoFollow items={items} />
+      <ThreadScrollbarRail
+        items={items}
+        keyboardFocusedMessageId={keyboardFocusedMessageId}
+      />
       <ChatMessageScrollerViewport>
         <ChatMessageScrollerContent
           className="gap-4 py-4 pb-8"
@@ -983,6 +989,103 @@ function ThreadScrollBody({
   );
 }
 
+/**
+ * Scrollbar marker rail for the (non-virtualized) ChatThread. One darker marker
+ * per user message, positioned by that message's offset within the scroller;
+ * click jumps to it (`scrollToMessage`), hover shows the first few words.
+ *
+ * Locates the quill scroller elements at runtime via a hidden probe (the same
+ * `closest('[data-slot="chat-message-scroller"]')` pattern `StickyHeaderOverlay`
+ * and `ThreadAutoFollow` use), since they're owned by quill and not handed to us
+ * as refs. The viewport is the scroll element; the inner `ChatMessageScrollerContent`
+ * is the content element (rows are its children, so their offsets within it are
+ * scroll-invariant).
+ */
+function ThreadScrollbarRail({
+  items,
+  keyboardFocusedMessageId,
+}: {
+  items: ConversationItem[];
+  keyboardFocusedMessageId?: string | null;
+}) {
+  const { scrollToMessage } = useChatMessageScroller();
+  const probeRef = useRef<HTMLSpanElement>(null);
+  const [els, setEls] = useState<{
+    scrollEl: HTMLElement | null;
+    contentEl: HTMLElement | null;
+  }>({ scrollEl: null, contentEl: null });
+
+  useLayoutEffect(() => {
+    const resolve = (): {
+      scrollEl: HTMLElement | null;
+      contentEl: HTMLElement | null;
+    } => {
+      const scroller = probeRef.current?.closest(
+        '[data-slot="chat-message-scroller"]',
+      );
+      return {
+        scrollEl:
+          (scroller?.querySelector(
+            '[data-slot="chat-message-scroller-viewport"]',
+          ) as HTMLElement | null) ?? null,
+        contentEl:
+          (scroller?.querySelector(
+            '[data-slot="chat-message-scroller-content"]',
+          ) as HTMLElement | null) ?? null,
+      };
+    };
+    const found = resolve();
+    setEls((prev) =>
+      prev.scrollEl === found.scrollEl && prev.contentEl === found.contentEl
+        ? prev
+        : found,
+    );
+    if (!found.scrollEl || !found.contentEl) {
+      // Re-resolve once the scroller's inner elements have mounted.
+      const raf = requestAnimationFrame(() => {
+        const again = resolve();
+        setEls((prev) =>
+          prev.scrollEl === again.scrollEl && prev.contentEl === again.contentEl
+            ? prev
+            : again,
+        );
+      });
+      return () => cancelAnimationFrame(raf);
+    }
+    return;
+  }, []);
+
+  const userMessages = useMemo(
+    () =>
+      items
+        .map((item, index) =>
+          item.type === "user_message"
+            ? { id: item.id, content: item.content, index }
+            : null,
+        )
+        .filter(
+          (x): x is { id: string; content: string; index: number } => x != null,
+        ),
+    [items],
+  );
+
+  const railMarkers = useMessageRailMarkers({
+    contentEl: els.contentEl,
+    scrollEl: els.scrollEl,
+    userMessages,
+    onJump: (id) => scrollToMessage(id),
+    activeId: keyboardFocusedMessageId,
+    rowAttribute: "data-message-id",
+  });
+
+  return (
+    <>
+      <span ref={probeRef} className="hidden" aria-hidden="true" />
+      <MessageScrollbarRail markers={railMarkers} />
+    </>
+  );
+}
+
 /**
  * Thread renderer built on the ChatX (quill) primitives.
  *
diff --git a/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.test.tsx b/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.test.tsx
new file mode 100644
index 0000000000..b2a7a0ec7c
--- /dev/null
+++ b/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.test.tsx
@@ -0,0 +1,89 @@
+import { render } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { MessageScrollbarRail } from "./MessageScrollbarRail";
+import {
+  MESSAGE_RAIL_LABEL_MAX_LENGTH,
+  truncateMessageLabel,
+  type MessageRailMarker,
+} from "./messageRailTypes";
+
+describe("truncateMessageLabel", () => {
+  it("collapses newlines and trims", () => {
+    expect(truncateMessageLabel("  hello\n\n  world  ", 80)).toBe(
+      "hello world",
+    );
+  });
+
+  it("collapses runs of spaces/tabs to one space", () => {
+    expect(truncateMessageLabel("hello\t\t   world", 80)).toBe("hello world");
+  });
+
+  it("returns short text unchanged", () => {
+    expect(truncateMessageLabel("hi there", 80)).toBe("hi there");
+  });
+
+  it("appends an ellipsis past the limit", () => {
+    const text = "a".repeat(MESSAGE_RAIL_LABEL_MAX_LENGTH + 10);
+    const out = truncateMessageLabel(text, MESSAGE_RAIL_LABEL_MAX_LENGTH);
+    expect(out.length).toBe(MESSAGE_RAIL_LABEL_MAX_LENGTH + 1);
+    expect(out.endsWith("…")).toBe(true);
+  });
+});
+
+function marker(overrides: Partial<MessageRailMarker>): MessageRailMarker {
+  return {
+    id: overrides.id ?? "m1",
+    topPct: overrides.topPct ?? 0,
+    heightPct: overrides.heightPct ?? 0.05,
+    label: overrides.label ?? "first few words",
+    active: overrides.active,
+    onClick: overrides.onClick ?? vi.fn(),
+  };
+}
+
+describe("MessageScrollbarRail", () => {
+  it("renders nothing when there are no markers", () => {
+    const { container } = render(<MessageScrollbarRail markers={[]} />);
+    expect(container.firstChild).toBeNull();
+  });
+
+  it("renders one marker button per user message", () => {
+    const { container } = render(
+      <MessageScrollbarRail
+        markers={[
+          marker({ id: "m1", topPct: 0, label: "hello" }),
+          marker({ id: "m2", topPct: 0.5, label: "world" }),
+        ]}
+      />,
+    );
+    // The rail is aria-hidden (the messages are already accessible in the
+    // transcript), so query buttons within the container rather than by role.
+    const buttons = container.querySelectorAll("button");
+    expect(buttons).toHaveLength(2);
+  });
+
+  it("positions each marker at its fractional top offset", () => {
+    const { container } = render(
+      <MessageScrollbarRail
+        markers={[
+          marker({ id: "m1", topPct: 0.25 }),
+          marker({ id: "m2", topPct: 0.75 }),
+        ]}
+      />,
+    );
+    const buttons = container.querySelectorAll("button");
+    expect(buttons[0].getAttribute("style")).toContain("top: 25%");
+    expect(buttons[1].getAttribute("style")).toContain("top: 75%");
+  });
+
+  it("calls onClick when a marker is clicked", () => {
+    const onClick = vi.fn();
+    const { container } = render(
+      <MessageScrollbarRail markers={[marker({ id: "m1", onClick })]} />,
+    );
+    const button = container.querySelector("button");
+    expect(button).not.toBeNull();
+    button?.click();
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.tsx b/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.tsx
new file mode 100644
index 0000000000..7f1e895028
--- /dev/null
+++ b/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.tsx
@@ -0,0 +1,81 @@
+import { cn, Tooltip, TooltipContent, TooltipTrigger } from "@posthog/quill";
+import type { MessageRailMarker } from "./messageRailTypes";
+
+export interface MessageScrollbarRailProps {
+  /**
+   * Markers to render, one per user message. The rail is responsible only for
+   * painting them at the given fractional positions and wiring click/tooltip.
+   */
+  markers: MessageRailMarker[];
+  /**
+   * The browser scrollbar's intrinsic width in CSS pixels — used to size the
+   * gutter the rail sits in so it lines up with (and visually replaces) the
+   * native thumb. Defaults to 8px (the global `::-webkit-scrollbar` width).
+   */
+  scrollbarWidth?: number;
+  /** Extra classes on the rail root. */
+  className?: string;
+}
+
+/**
+ * A vertical marker rail drawn in the scrollbar gutter of a conversation view.
+ *
+ * Each marker is positioned by a fractional `topPct` / `heightPct` of the
+ * scrollable content height (the consumer converts measured row offsets into
+ * those fractions). Clicking a marker calls its `onClick` (scroll-to-message);
+ * hovering shows a tooltip with the message's first few words.
+ *
+ * The rail is `position: absolute` and pinned to the right edge, sized to the
+ * native scrollbar gutter so it reads as part of the scrollbar rather than a
+ * floating overlay. It is mouse-only — native drag-scrolling and keyboard
+ * scrolling still work because the rail only intercepts clicks on its markers.
+ */
+export function MessageScrollbarRail({
+  markers,
+  scrollbarWidth = 8,
+  className,
+}: MessageScrollbarRailProps) {
+  if (markers.length === 0) return null;
+
+  return (
+    <div
+      aria-hidden
+      className={cn(
+        "pointer-events-none absolute top-0 right-0 z-10 h-full",
+        className,
+      )}
+      style={{ width: scrollbarWidth }}
+    >
+      {markers.map((marker) => (
+        <Tooltip key={marker.id}>
+          <TooltipTrigger
+            render={
+              <button
+                type="button"
+                onClick={marker.onClick}
+                // The marker button spans the rail's full width; its vertical
+                // position is the fractional offset of the message within the
+                // scrollable content.
+                className="pointer-events-auto absolute left-0 w-full cursor-pointer border-0 bg-transparent p-0"
+                style={{
+                  top: `${marker.topPct * 100}%`,
+                  height: `${Math.max(marker.heightPct * 100, 0.6)}%`,
+                }}
+              >
+                <span
+                  className={cn(
+                    "block h-full w-full rounded-full transition-colors",
+                    marker.active
+                      ? "bg-(--accent-9)"
+                      : "bg-(--gray-10) hover:bg-(--gray-11)",
+                  )}
+                />
+              </button>
+            }
+          />
+          <TooltipContent side="left">{marker.label}</TooltipContent>
+        </Tooltip>
+      ))}
+    </div>
+  );
+}
diff --git a/packages/ui/src/features/sessions/components/scrollbar-rail/messageRailTypes.ts b/packages/ui/src/features/sessions/components/scrollbar-rail/messageRailTypes.ts
new file mode 100644
index 0000000000..4b45d1d68a
--- /dev/null
+++ b/packages/ui/src/features/sessions/components/scrollbar-rail/messageRailTypes.ts
@@ -0,0 +1,40 @@
+/**
+ * A single marker drawn on the conversation scrollbar rail, one per user message.
+ *
+ * `topPct` / `heightPct` position the marker within the rail as a fraction of the
+ * scrollable content's total height (0–1, relative to the inner content, not the
+ * viewport). The rail converts these to absolute pixels on render.
+ *
+ * `onClick` scrolls the conversation to this message; `label` is the first few
+ * words, shown as a hover tooltip.
+ */
+export interface MessageRailMarker {
+  /** Stable id — also used as the React key and the tooltip anchor. */
+  id: string;
+  /** Top offset as a fraction (0–1) of total scrollable content height. */
+  topPct: number;
+  /** Marker height as a fraction (0–1) of total scrollable content height. */
+  heightPct: number;
+  /** Tooltip text — the first few words of the message. */
+  label: string;
+  /** Whether this message is currently the keyboard-focused one. */
+  active?: boolean;
+  /** Scrolls the conversation to this message. */
+  onClick: () => void;
+}
+
+/**
+ * Truncate a message body to a single-line label suitable for a hover tooltip.
+ * Collapses all runs of whitespace (newlines, tabs, multiple spaces) to a single
+ * space, trims, and cuts with an ellipsis past `maxLength` — the same intent as
+ * the `MessageJumpPicker` truncation but whitespace-normalized so indented or
+ * multi-line prompts read cleanly on one line.
+ */
+export function truncateMessageLabel(text: string, maxLength: number): string {
+  const singleLine = text.replace(/\s+/g, " ").trim();
+  if (singleLine.length <= maxLength) return singleLine;
+  return `${singleLine.slice(0, maxLength)}…`;
+}
+
+/** Default cap for the rail tooltip label. */
+export const MESSAGE_RAIL_LABEL_MAX_LENGTH = 80;
diff --git a/packages/ui/src/features/sessions/components/scrollbar-rail/useMessageRailMarkers.ts b/packages/ui/src/features/sessions/components/scrollbar-rail/useMessageRailMarkers.ts
new file mode 100644
index 0000000000..84e20034a2
--- /dev/null
+++ b/packages/ui/src/features/sessions/components/scrollbar-rail/useMessageRailMarkers.ts
@@ -0,0 +1,230 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import {
+  MESSAGE_RAIL_LABEL_MAX_LENGTH,
+  truncateMessageLabel,
+  type MessageRailMarker,
+} from "./messageRailTypes";
+
+interface UserMessageEntry {
+  id: string;
+  content: string;
+  /** Item index within the conversation — used to order markers. */
+  index: number;
+}
+
+interface MeasuredOffset {
+  top: number;
+  height: number;
+}
+
+/**
+ * Drives the scrollbar marker rail for a conversation view.
+ *
+ * Returns the markers the rail should paint. It measures each rendered
+ * user-message row's `offsetTop`/`offsetHeight` inside `contentEl` (the scroll
+ * container's inner content element), persists those measurements in a ref so a
+ * marker stays put once its row has rendered even after it scrolls out of view,
+ * and recomputes the fractional positions whenever the content scrolls, resizes,
+ * or the DOM mutates (rows entering/leaving the virtualization window).
+ *
+ * Rows not yet rendered (virtualized views, e.g. the legacy `ConversationView`)
+ * have no DOM node and therefore no measured offset; their markers are placed
+ * by linearly interpolating between the nearest measured neighbours using their
+ * item indices, which is accurate enough for a click target and self-corrects the
+ * moment the row renders. (Non-virtualized views like the new `ChatThread`
+ * render every row, so every marker is measured directly.)
+ *
+ * @param contentEl       The scroll container's inner content element (the tall
+ *                        div whose height == total content height). Offsets are
+ *                        read relative to it.
+ * @param scrollEl        The scrolling element (has `scrollTop`/`scrollHeight`).
+ *                        Used to trigger marker refresh on scroll. If omitted,
+ *                        only mutation/resize trigger refresh.
+ * @param userMessages    Ordered `{ id, content, index }` entries, one per user
+ *                        message in the conversation.
+ * @param onJump          Scrolls the conversation to the message with this id.
+ * @param activeId        Currently keyboard-focused message id (highlighted).
+ * @param rowAttribute    The data attribute stamped on each message row, used to
+ *                        locate it in the DOM. Defaults to
+ *                        `data-conversation-item-id` (the legacy view); the new
+ *                        `ChatThread` uses `data-message-id`.
+ */
+export function useMessageRailMarkers({
+  contentEl,
+  scrollEl,
+  userMessages,
+  onJump,
+  activeId,
+  rowAttribute = "data-conversation-item-id",
+}: {
+  contentEl: HTMLElement | null;
+  scrollEl: HTMLElement | null;
+  userMessages: readonly UserMessageEntry[];
+  onJump: (id: string) => void;
+  activeId?: string | null;
+  rowAttribute?: string;
+}): MessageRailMarker[] {
+  // Persisted measurements keyed by item id. Stable across renders; updated by
+  // the measure pass. Keeping them in a ref (not state) avoids re-renders on
+  // every scroll tick — a `version` counter triggers the one re-render we need.
+  const measuredRef = useRef<Map<string, MeasuredOffset>>(new Map());
+  const [version, setVersion] = useState(0);
+
+  const bump = useCallback(() => setVersion((v) => v + 1), []);
+
+  // Hold the latest inputs in refs so `measure` is referentially stable —
+  // otherwise a fresh `userMessages` array each render would tear down and
+  // rebuild the scroll/mutation/resize observers every render.
+  const contentElRef = useRef(contentEl);
+  contentElRef.current = contentEl;
+  const userMessagesRef = useRef(userMessages);
+  userMessagesRef.current = userMessages;
+  const rowAttributeRef = useRef(rowAttribute);
+  rowAttributeRef.current = rowAttribute;
+
+  // Re-measure rendered user-message rows and persist their offsets.
+  const measure = useCallback(() => {
+    const content = contentElRef.current;
+    if (!content) return;
+    let changed = false;
+    const map = measuredRef.current;
+    const attr = rowAttributeRef.current;
+    // Content's top in viewport coords; subtracting it from each row's top
+    // yields the row's position within the content (scroll-invariant, since
+    // both move together). `offsetTop` can't be used directly because virtual
+    // list rows live in a `transform`-ed wrapper that becomes the offset parent.
+    const contentTop = content.getBoundingClientRect().top;
+    for (const entry of userMessagesRef.current) {
+      const row = content.querySelector(
+        `[${attr}="${CSS.escape(entry.id)}"]`,
+      ) as HTMLElement | null;
+      if (!row) continue;
+      const rect = row.getBoundingClientRect();
+      const top = rect.top - contentTop;
+      const height = rect.height;
+      const prev = map.get(entry.id);
+      if (!prev || prev.top !== top || prev.height !== height) {
+        map.set(entry.id, { top, height });
+        changed = true;
+      }
+    }
+    if (changed) bump();
+  }, [bump]);
+
+  // Refresh on scroll (positions change as the thumb moves) + on DOM mutation
+  // (rows entering/leaving the virtualization window) + on content resize.
+  useEffect(() => {
+    if (!contentEl) return;
+    measure();
+    const mutation = new MutationObserver(() => measure());
+    mutation.observe(contentEl, { childList: true, subtree: true });
+    const resize = new ResizeObserver(() => measure());
+    resize.observe(contentEl);
+    const onScroll = () => measure();
+    const scroll = scrollEl ?? contentEl;
+    scroll.addEventListener("scroll", onScroll, { passive: true });
+    return () => {
+      mutation.disconnect();
+      resize.disconnect();
+      scroll.removeEventListener("scroll", onScroll);
+    };
+  }, [contentEl, scrollEl, measure]);
+
+  // Drop stale ids (removed messages) so markers don't linger after compaction.
+  useEffect(() => {
+    const map = measuredRef.current;
+    const keep = new Set(userMessages.map((m) => m.id));
+    let changed = false;
+    for (const id of map.keys()) {
+      if (!keep.has(id)) {
+        map.delete(id);
+        changed = true;
+      }
+    }
+    if (changed) bump();
+  }, [userMessages, bump]);
+
+  // Build the markers: fractional position = measured offset / total content
+  // height. Unmeasured rows are interpolated between their nearest measured
+  // neighbours by array position.
+  const markers: MessageRailMarker[] = [];
+  if (contentEl && userMessages.length > 0) {
+    const total = contentEl.scrollHeight;
+    const map = measuredRef.current;
+
+    for (let i = 0; i < userMessages.length; i++) {
+      const entry = userMessages[i];
+      const measured = map.get(entry.id);
+      let top: number;
+      let height: number;
+      if (measured) {
+        top = measured.top;
+        height = measured.height;
+      } else {
+        const interp = interpolateOffset(userMessages, map, i);
+        top = interp.top;
+        height = interp.height;
+      }
+      markers.push({
+        id: entry.id,
+        topPct: total > 0 ? top / total : 0,
+        heightPct: total > 0 ? height / total : 0,
+        label: truncateMessageLabel(
+          entry.content,
+          MESSAGE_RAIL_LABEL_MAX_LENGTH,
+        ),
+        active: activeId === entry.id,
+        onClick: () => onJump(entry.id),
+      });
+    }
+  }
+
+  // `version` is read here so the hook re-runs the build above when measurements
+  // update. Without referencing it, TS would flag it unused; keep the reference.
+  void version;
+  return markers;
+}
+
+/** Estimate the offset of an unmeasured row by interpolating between its nearest
+ * measured neighbours by array position. Falls back to the estimate-size heuristic
+ * (a per-row fraction of total height) when there are no neighbours at all. */
+function interpolateOffset(
+  userMessages: readonly UserMessageEntry[],
+  measured: Map<string, MeasuredOffset>,
+  index: number,
+): MeasuredOffset {
+  // Walk outward from `index` to find the previous and next measured entries.
+  let prevIdx = -1;
+  for (let i = index - 1; i >= 0; i--) {
+    if (measured.has(userMessages[i].id)) {
+      prevIdx = i;
+      break;
+    }
+  }
+  let nextIdx = -1;
+  for (let i = index + 1; i < userMessages.length; i++) {
+    if (measured.has(userMessages[i].id)) {
+      nextIdx = i;
+      break;
+    }
+  }
+
+  const prev = prevIdx >= 0 ? measured.get(userMessages[prevIdx].id) : null;
+  const next = nextIdx >= 0 ? measured.get(userMessages[nextIdx].id) : null;
+  const ESTIMATE = 80;
+
+  if (prev && next && nextIdx > prevIdx) {
+    // Lerp between the two measured neighbours.
+    const span = nextIdx - prevIdx;
+    const t = (index - prevIdx) / span;
+    const top = prev.top + (next.top - prev.top) * t;
+    return { top, height: ESTIMATE };
+  }
+  if (prev) {
+    return { top: prev.top + prev.height + ESTIMATE, height: ESTIMATE };
+  }
+  if (next) {
+    return { top: Math.max(0, next.top - ESTIMATE), height: ESTIMATE };
+  }
+  return { top: index * ESTIMATE, height: ESTIMATE };
+}

From 79ed5bbf65751385e106f4093f1990475bb48c52 Mon Sep 17 00:00:00 2001
From: Paul D'Ambra <paul.dambra@gmail.com>
Date: Tue, 21 Jul 2026 15:07:13 +0100
Subject: [PATCH 02/15] test(ui): add Storybook scenes for the scrollbar marker
 rail

Add `MessageScrollbarRail.stories.tsx` with two scenes:

- `Pure`: the rail in isolation with a hand-built marker set, for reviewing
  marker sizing/spacing and the active state.
- `ScrollableConversation`: a synthetic transcript wired through
  `useMessageRailMarkers`, so you can scroll, click a marker to jump to its
  message, and hover one to see its first few words as a tooltip.

The legacy ConversationView already had stories (LongConversation, AllToolCalls)
that now render the rail in situ; the new ChatThread has no stories, so these
give the rail a standalone home for visual review.

Generated-By: PostHog Code
Task-Id: a950f289-b4c3-472e-b375-0799e0cbf8a4
---
 .../MessageScrollbarRail.stories.tsx          | 205 ++++++++++++++++++
 1 file changed, 205 insertions(+)
 create mode 100644 packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.stories.tsx

diff --git a/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.stories.tsx b/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.stories.tsx
new file mode 100644
index 0000000000..872fd1397c
--- /dev/null
+++ b/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.stories.tsx
@@ -0,0 +1,205 @@
+import { MessageScrollbarRail } from "@posthog/ui/features/sessions/components/scrollbar-rail/MessageScrollbarRail";
+import { useMessageRailMarkers } from "@posthog/ui/features/sessions/components/scrollbar-rail/useMessageRailMarkers";
+import type { MessageRailMarker } from "@posthog/ui/features/sessions/components/scrollbar-rail/messageRailTypes";
+import { useCallback, useRef, useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+/**
+ * Stories for the conversation scrollbar marker rail.
+ *
+ * `Pure` is the rail in isolation with a hand-built marker set (no scroll wiring)
+ * — useful for eyeballing marker sizing / spacing / active state.
+ *
+ * `ScrollableConversation` is the real experience: a synthetic transcript that
+ * scrolls, wired through `useMessageRailMarkers`, so you can scroll, click a
+ * marker to jump to its message, and hover one to see its first few words.
+ */
+const meta: Meta<typeof MessageScrollbarRail> = {
+  title: "Features/Sessions/ScrollbarRail",
+  component: MessageScrollbarRail,
+  parameters: {
+    layout: "fullscreen",
+  },
+};
+export default meta;
+type Story = StoryObj<typeof MessageScrollbarRail>;
+
+const ACCENT = "var(--accent-9)";
+
+function marker(overrides: Partial<MessageRailMarker>): MessageRailMarker {
+  return {
+    id: overrides.id ?? "m1",
+    topPct: overrides.topPct ?? 0,
+    heightPct: overrides.heightPct ?? 0.04,
+    label: overrides.label ?? "first few words",
+    active: overrides.active,
+    onClick: overrides.onClick ?? (() => {}),
+  };
+}
+
+export const Pure: Story = {
+  render: () => (
+    <div className="flex h-[90vh] items-center justify-center bg-(--gray-1)">
+      {/* A fixed-height box so the rail's `h-full` has something to fill. */}
+      <div className="relative h-[520px] w-[440px] rounded-(--radius-3) border border-(--gray-4) bg-(--gray-2)">
+        <MessageScrollbarRail
+          markers={[
+            marker({
+              id: "m1",
+              topPct: 0,
+              label: "How do I set up the dev env?",
+            }),
+            marker({
+              id: "m2",
+              topPct: 0.23,
+              label: "Add a marker to the scrollbar for my messages",
+            }),
+            marker({
+              id: "m3",
+              topPct: 0.48,
+              label: "Why did the build break on CI?",
+              active: true,
+            }),
+            marker({
+              id: "m4",
+              topPct: 0.71,
+              label: "Can you color the scrollbar based on conversation data?",
+            }),
+            marker({
+              id: "m5",
+              topPct: 0.93,
+              label: "Ship it",
+            }),
+          ]}
+        />
+        {/* Caption so the rail (8px, far right) isn't the only thing on screen. */}
+        <div className="flex h-full items-center justify-center px-12 text-center">
+          <p className="text-(--gray-10) text-[13px] leading-relaxed">
+            Markers sit in the scrollbar gutter on the right. Hover one to see
+            the first few words; click to jump. The accent-colored marker is
+            active.
+          </p>
+        </div>
+      </div>
+    </div>
+  ),
+};
+
+/** A synthetic transcript used by the scrollable story. Each entry is one user
+ * message followed by a tall agent reply, so there's something to scroll. */
+interface TranscriptEntry {
+  id: string;
+  prompt: string;
+  reply: string;
+}
+
+function buildTranscript(): TranscriptEntry[] {
+  const prompts = [
+    "How do I set up the dev environment for this repo?",
+    "Add a darker marker to the scrollbar where my messages are",
+    "Why did the build break after the last merge?",
+    "Can you color the scrollbar based on data in the conversation?",
+    "Show the first few words of each message as a tooltip",
+    "Walk me through the DI boot sequence",
+    "What does the host boundary check enforce?",
+    "Refactor the conversation items pipeline",
+    "Generate a changelog entry for the rail",
+    "Ship it once tests are green",
+  ];
+  return prompts.map((prompt, i) => ({
+    id: `user-${i}`,
+    prompt,
+    reply: `Here's a thorough answer to "${prompt}". `.repeat(40),
+  }));
+}
+
+/** Callback-ref helper: forwards the element to a state setter once attached. */
+function useRefState<T extends HTMLElement>() {
+  const [el, setEl] = useState<T | null>(null);
+  const ref = useCallback((node: T | null) => setEl(node), []);
+  return [el, ref] as const;
+}
+
+/** The scrollable transcript: a tall content element with `data-conversation-item-id`
+ * rows, plus the rail wired through `useMessageRailMarkers`. Mirrors how the real
+ * `ConversationView` mounts the rail (the content element is the measured offset
+ * parent; the scroll element is the `overflow-y-auto` viewport). */
+function ScrollableConversationDemo() {
+  const transcript = useRef(buildTranscript()).current;
+  const [activeId, setActiveId] = useState<string | null>(null);
+
+  const [scrollEl, scrollRef] = useRefState<HTMLDivElement>();
+  const [contentEl, contentRef] = useRefState<HTMLDivElement>();
+
+  const userMessages = useRef(
+    transcript.map((entry, index) => ({
+      id: entry.id,
+      content: entry.prompt,
+      index,
+    })),
+  ).current;
+
+  const onJump = useCallback(
+    (id: string) => {
+      setActiveId(id);
+      const row = contentEl?.querySelector(
+        `[data-conversation-item-id="${CSS.escape(id)}"]`,
+      ) as HTMLElement | null;
+      row?.scrollIntoView({ block: "start", behavior: "smooth" });
+    },
+    [contentEl],
+  );
+
+  const markers = useMessageRailMarkers({
+    contentEl,
+    scrollEl,
+    userMessages,
+    onJump,
+    activeId,
+  });
+
+  return (
+    <div className="flex h-[90vh] flex-col bg-background">
+      <div className="border-(--gray-4) border-b px-4 py-2">
+        <span className="text-(--gray-11) text-[13px]">
+          Scroll the transcript, then click a marker in the scrollbar to jump to
+          that message, or hover one for a preview.
+        </span>
+      </div>
+      <div className="relative flex-1">
+        {/* The scroll viewport. `scrollbar-gutter: stable` reserves the gutter the
+            rail sits over, matching the real ConversationView. */}
+        <div
+          ref={scrollRef}
+          className="scroll-mask-8 h-full overflow-y-auto"
+          style={{ scrollbarGutter: "stable" }}
+        >
+          <div ref={contentRef} className="relative">
+            {transcript.map((entry) => (
+              <div
+                key={entry.id}
+                data-conversation-item-id={entry.id}
+                className="mx-auto max-w-[640px] px-4 py-3"
+              >
+                <div
+                  className="rounded-(--radius-2) px-3 py-2 text-[13px] text-white"
+                  style={{ backgroundColor: ACCENT }}
+                >
+                  {entry.prompt}
+                </div>
+                <p className="mt-2 text-(--gray-11) text-[13px] leading-relaxed">
+                  {entry.reply}
+                </p>
+              </div>
+            ))}
+          </div>
+        </div>
+        <MessageScrollbarRail markers={markers} />
+      </div>
+    </div>
+  );
+}
+
+export const ScrollableConversation: Story = {
+  render: () => <ScrollableConversationDemo />,
+};

From d2cccae17dc3edcdccebfe488a9380d9b4698988 Mon Sep 17 00:00:00 2001
From: Paul D'Ambra <paul.dambra@gmail.com>
Date: Tue, 21 Jul 2026 15:09:10 +0100
Subject: [PATCH 03/15] ci: remove the React Doctor workflow

Remove the `React Doctor` pull-request workflow (`.github/workflows/react-doctor.yml`) and its dedicated comment formatter (`.github/scripts/react-doctor-comment.mjs`).

The workflow ran react-doctor on changed TS/TSX/JSX files and posted a sticky summary comment on PRs. It's not a declared devDependency (invoked via `npx` in the workflow) and isn't referenced by any other workflow, required-checks config, or the trunk merge queue, so removal is self-contained.

The only remaining mention is a code comment in ChatThread.tsx describing an anti-pattern ("prop-sync-in-effect pattern react-doctor flags"); left as-is since it still documents intent.

Generated-By: PostHog Code
Task-Id: a950f289-b4c3-472e-b375-0799e0cbf8a4
---
 .github/scripts/react-doctor-comment.mjs | 140 -----------------------
 .github/workflows/react-doctor.yml       | 120 -------------------
 2 files changed, 260 deletions(-)
 delete mode 100644 .github/scripts/react-doctor-comment.mjs
 delete mode 100644 .github/workflows/react-doctor.yml

diff --git a/.github/scripts/react-doctor-comment.mjs b/.github/scripts/react-doctor-comment.mjs
deleted file mode 100644
index bde71abc66..0000000000
--- a/.github/scripts/react-doctor-comment.mjs
+++ /dev/null
@@ -1,140 +0,0 @@
-import fs from "node:fs";
-
-const [reportPath, outPath] = process.argv.slice(2);
-const MARKER = "<!-- react-doctor:summary -->";
-const slug = process.env.GITHUB_REPOSITORY;
-const server = (process.env.GITHUB_SERVER_URL || "https://github.com").replace(
-  /\/$/,
-  "",
-);
-const head = (
-  process.env.REACT_DOCTOR_HEAD_SHA ||
-  process.env.GITHUB_SHA ||
-  ""
-).trim();
-
-const MAX_LISTED = 50;
-const plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
-const inline = (value) =>
-  String(value ?? "")
-    .replace(/\s+/g, " ")
-    .replace(/[`<>]/g, "")
-    .trim();
-const byFileThenLine = (a, b) =>
-  a.filePath === b.filePath
-    ? a.line - b.line
-    : a.filePath < b.filePath
-      ? -1
-      : 1;
-const encodedPath = (file) =>
-  String(file ?? "")
-    .split("/")
-    .map((segment) =>
-      encodeURIComponent(segment).replace(/[()]/g, (c) =>
-        c === "(" ? "%28" : "%29",
-      ),
-    )
-    .join("/");
-const fileLink = (file, line) =>
-  slug && head
-    ? `[\`${inline(file)}:${line}\`](${server}/${slug}/blob/${head}/${encodedPath(file)}#L${line})`
-    : `\`${inline(file)}:${line}\``;
-
-let report;
-try {
-  report = JSON.parse(fs.readFileSync(reportPath, "utf8"));
-} catch {
-  report = null;
-}
-
-const lines = [MARKER, ""];
-
-if (!report) {
-  lines.push("**React Doctor** could not produce a report.");
-} else if (!report.ok) {
-  lines.push(
-    "**React Doctor** could not complete this scan.",
-    "",
-    `> ${inline(report.error?.message) || "scan failed"}`,
-  );
-} else {
-  const summary = report.summary ?? {};
-  const total = summary.totalDiagnosticCount ?? 0;
-  const diagnostics = (report.projects ?? []).flatMap(
-    (project) => project.diagnostics ?? [],
-  );
-
-  if (total === 0) {
-    lines.push("**React Doctor** found no issues in the changed files. 🎉");
-  } else {
-    const severity = [];
-    if (summary.errorCount) severity.push(plural(summary.errorCount, "error"));
-    if (summary.warningCount)
-      severity.push(plural(summary.warningCount, "warning"));
-    const severityTail = severity.length ? ` · ${severity.join(" & ")}` : "";
-    lines.push(
-      `**React Doctor** found **${plural(total, "issue")}** in ${plural(summary.affectedFileCount ?? 0, "file")}${severityTail}.`,
-    );
-
-    const errors = diagnostics
-      .filter((d) => d.severity === "error")
-      .sort(byFileThenLine);
-    if (errors.length) {
-      lines.push("", "**Errors**", "");
-      for (const error of errors.slice(0, MAX_LISTED)) {
-        const title = inline(error.title);
-        lines.push(
-          `- ❌ ${fileLink(error.filePath, error.line)}${title ? ` ${title}` : ""} \`${inline(error.rule)}\``,
-        );
-      }
-      if (errors.length > MAX_LISTED)
-        lines.push(
-          "",
-          `${plural(errors.length - MAX_LISTED, "more error")} not shown.`,
-        );
-    }
-
-    const warnings = diagnostics
-      .filter((d) => d.severity === "warning")
-      .sort(byFileThenLine);
-    if (warnings.length) {
-      lines.push(
-        "",
-        `<details><summary>${plural(warnings.length, "warning")}</summary>`,
-        "",
-      );
-      let currentFile = null;
-      for (const warning of warnings.slice(0, MAX_LISTED)) {
-        if (warning.filePath !== currentFile) {
-          if (currentFile !== null) lines.push("");
-          lines.push(`**\`${inline(warning.filePath)}\`**`);
-          currentFile = warning.filePath;
-        }
-        const title = inline(warning.title);
-        lines.push(
-          `- ⚠️ ${fileLink(warning.filePath, warning.line)}${title ? ` ${title}` : ""} \`${inline(warning.rule)}\``,
-        );
-      }
-      if (warnings.length > MAX_LISTED)
-        lines.push(
-          "",
-          `${plural(warnings.length - MAX_LISTED, "more warning")} not shown.`,
-        );
-      lines.push("", "</details>");
-    }
-  }
-}
-
-const commit = head ? ` for commit \`${head.slice(0, 7)}\`` : "";
-lines.push(
-  "",
-  `<sub>Reviewed by [React Doctor](https://react.doctor)${commit}.</sub>`,
-);
-
-fs.writeFileSync(
-  outPath,
-  `${lines
-    .join("\n")
-    .replace(/\n{3,}/g, "\n\n")
-    .trimEnd()}\n`,
-);
diff --git a/.github/workflows/react-doctor.yml b/.github/workflows/react-doctor.yml
deleted file mode 100644
index d75b7260ec..0000000000
--- a/.github/workflows/react-doctor.yml
+++ /dev/null
@@ -1,120 +0,0 @@
-name: React Doctor
-
-on:
-  pull_request:
-    types: [opened, synchronize, reopened, ready_for_review]
-    # Workflow-level paths only work because react-doctor is not a required
-    # check. If it ever becomes required, move the skip into a gate job like
-    # test.yml, or path-skipped PRs will wait on it forever.
-    paths:
-      - "**/*.ts"
-      - "**/*.tsx"
-      - "**/*.jsx"
-      - ".github/workflows/react-doctor.yml"
-      - ".github/scripts/react-doctor-comment.mjs"
-
-permissions:
-  contents: read
-  pull-requests: write
-
-concurrency:
-  group: react-doctor-${{ github.head_ref || github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  react-doctor:
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-        with:
-          fetch-depth: 0
-          persist-credentials: false
-
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
-        with:
-          node-version: 22
-          package-manager-cache: false
-
-      - id: scan
-        name: Run react-doctor on changed files
-        shell: bash
-        env:
-          NO_COLOR: "1"
-          REACT_DOCTOR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
-          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
-        run: |
-          # -e omitted: exit codes are captured and inspected explicitly.
-          set -uo pipefail
-          CHANGED="${RUNNER_TEMP}/react-doctor-changed-files.txt"
-          if ! git diff --name-only --diff-filter=ACMR "${REACT_DOCTOR_BASE_SHA}...${HEAD_SHA}" > "$CHANGED"; then
-            echo "Could not diff ${REACT_DOCTOR_BASE_SHA}...${HEAD_SHA}; failing rather than skipping the scan." >&2
-            echo "exit-code=1" >> "$GITHUB_OUTPUT"
-            exit 1
-          fi
-          if [ ! -s "$CHANGED" ]; then
-            echo "No changed files; nothing for react-doctor to scan."
-            echo "exit-code=0" >> "$GITHUB_OUTPUT"
-            exit 0
-          fi
-          REPORT="${RUNNER_TEMP}/react-doctor-report.json"
-          status=0
-          npx --yes react-doctor@0.5.4 . --blocking error --changed-files-from "$CHANGED" --json --json-compact --no-telemetry > "$REPORT" || status=$?
-          echo "exit-code=$status" >> "$GITHUB_OUTPUT"
-          echo "report=$REPORT" >> "$GITHUB_OUTPUT"
-          if [ "$status" -ne 0 ]; then
-            echo "react-doctor exited with status ${status}; report follows." >&2
-            cat "$REPORT" >&2 || true
-          fi
-
-      - name: Upsert sticky PR comment
-        if: ${{ always() && steps.scan.outputs.report != '' }}
-        continue-on-error: true
-        shell: bash
-        env:
-          GH_TOKEN: ${{ github.token }}
-          GITHUB_REPOSITORY: ${{ github.repository }}
-          GITHUB_SERVER_URL: ${{ github.server_url }}
-          REACT_DOCTOR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
-          PR_NUMBER: ${{ github.event.pull_request.number }}
-          REPORT: ${{ steps.scan.outputs.report }}
-        run: |
-          set -uo pipefail
-          BODY="${RUNNER_TEMP}/react-doctor-comment.md"
-          node "${GITHUB_WORKSPACE}/.github/scripts/react-doctor-comment.mjs" "$REPORT" "$BODY"
-          cat "$BODY" >> "$GITHUB_STEP_SUMMARY"
-          jq -Rs '{body: .}' "$BODY" > "${RUNNER_TEMP}/react-doctor-payload.json"
-          marker="<!-- react-doctor:summary -->"
-          existing=$(gh api "repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/comments" --paginate \
-            --jq ".[] | select(.body | startswith(\"${marker}\")) | .id" | head -n1 || true)
-          if [ -n "$existing" ]; then
-            gh api -X PATCH "repos/${GITHUB_REPOSITORY}/issues/comments/${existing}" --input "${RUNNER_TEMP}/react-doctor-payload.json" >/dev/null
-          else
-            gh api -X POST "repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/comments" --input "${RUNNER_TEMP}/react-doctor-payload.json" >/dev/null
-          fi
-
-      - name: Enforce blocking findings
-        if: ${{ always() }}
-        shell: bash
-        env:
-          STATUS: ${{ steps.scan.outputs.exit-code }}
-          REPORT: ${{ steps.scan.outputs.report }}
-        run: |
-          # -e omitted: exit codes are captured and inspected explicitly.
-          set -uo pipefail
-          if [ "${STATUS:-1}" = "0" ]; then
-            exit 0
-          fi
-          if [ -n "${REPORT:-}" ]; then
-            if ! jq -e . "$REPORT" >/dev/null 2>&1; then
-              echo "::warning title=React Doctor::Scanner exited ${STATUS:-1} without a valid JSON report; not blocking the PR on a scanner failure."
-              exit 0
-            fi
-            if jq -e '.ok == false' "$REPORT" >/dev/null 2>&1; then
-              # Strip newlines so the message cannot end the ::warning command early.
-              message=$(jq -r '.error.message // "unknown error"' "$REPORT" | tr -d '\n')
-              echo "::warning title=React Doctor::Scanner crashed (${message}); not blocking the PR on a scanner failure."
-              exit 0
-            fi
-          fi
-          exit "${STATUS:-1}"

From 7bb18ef0c9b5e282be60584af53a003ececec746 Mon Sep 17 00:00:00 2001
From: Paul D'Ambra <paul.dambra@gmail.com>
Date: Tue, 21 Jul 2026 15:25:49 +0100
Subject: [PATCH 04/15] fix(ui): sort imports and a11y-harden the scrollbar
 rail markers
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CI fixes for the scrollbar marker rail PR.

- `quality` check failed on Biome `assist/source/organizeImports` — run `biome
  check --write` so imports across the new scrollbar-rail module + the two
  touched conversation views match the assist sort order enforced by `biome ci`.
- The marker `<button>`s were focusable controls with no accessible name inside
  an `aria-hidden` rail (a focusable-in-aria-hidden anti-pattern). Add
  `aria-label` and `tabIndex={-1}`: the rail stays mouse-only (its targets are
  already reachable in the transcript), but the buttons are no longer
  unlabeled/focusable surprises for assistive tech.

`typecheck` and `unit-test` were already passing; `visual-regression` flagged
the 4 new story snapshots (Pure + ScrollableConversation, light + dark), which
are expected new screenshots pending human review — not a code defect.

Generated-By: PostHog Code
Task-Id: a950f289-b4c3-472e-b375-0799e0cbf8a4
---
 .../src/features/sessions/components/ConversationView.tsx  | 4 ++--
 .../sessions/components/chat-thread/ChatThread.tsx         | 4 ++--
 .../scrollbar-rail/MessageScrollbarRail.stories.tsx        | 4 ++--
 .../scrollbar-rail/MessageScrollbarRail.test.tsx           | 2 +-
 .../components/scrollbar-rail/MessageScrollbarRail.tsx     | 7 +++++++
 .../components/scrollbar-rail/useMessageRailMarkers.ts     | 2 +-
 6 files changed, 15 insertions(+), 8 deletions(-)

diff --git a/packages/ui/src/features/sessions/components/ConversationView.tsx b/packages/ui/src/features/sessions/components/ConversationView.tsx
index ac6679fd4d..b37108ccb7 100644
--- a/packages/ui/src/features/sessions/components/ConversationView.tsx
+++ b/packages/ui/src/features/sessions/components/ConversationView.tsx
@@ -23,8 +23,6 @@ import {
 import { MessageJumpPicker } from "@posthog/ui/features/sessions/components/chat-thread/MessageJumpPicker";
 import { THREAD_HOTKEY_OPTIONS } from "@posthog/ui/features/sessions/components/chat-thread/threadHotkeys";
 import { usePromptRecallSource } from "@posthog/ui/features/sessions/components/chat-thread/usePromptRecallSource";
-import { MessageScrollbarRail } from "@posthog/ui/features/sessions/components/scrollbar-rail/MessageScrollbarRail";
-import { useMessageRailMarkers } from "@posthog/ui/features/sessions/components/scrollbar-rail/useMessageRailMarkers";
 import { GitActionMessage } from "@posthog/ui/features/sessions/components/GitActionMessage";
 import { GitActionResult } from "@posthog/ui/features/sessions/components/GitActionResult";
 import { mergeConversationItems } from "@posthog/ui/features/sessions/components/mergeConversationItems";
@@ -36,6 +34,8 @@ import type { CollapseMode } from "@posthog/ui/features/sessions/components/new-
 import { createIncrementalThreadGrouper } from "@posthog/ui/features/sessions/components/new-thread/incrementalThreadGrouping";
 import { ToolCallGroupChip } from "@posthog/ui/features/sessions/components/new-thread/ToolCallGroupChip";
 import { SessionFooter } from "@posthog/ui/features/sessions/components/SessionFooter";
+import { MessageScrollbarRail } from "@posthog/ui/features/sessions/components/scrollbar-rail/MessageScrollbarRail";
+import { useMessageRailMarkers } from "@posthog/ui/features/sessions/components/scrollbar-rail/useMessageRailMarkers";
 import {
   type RenderItem,
   SessionUpdateView,
diff --git a/packages/ui/src/features/sessions/components/chat-thread/ChatThread.tsx b/packages/ui/src/features/sessions/components/chat-thread/ChatThread.tsx
index 3b755fe1a8..df83afcd19 100644
--- a/packages/ui/src/features/sessions/components/chat-thread/ChatThread.tsx
+++ b/packages/ui/src/features/sessions/components/chat-thread/ChatThread.tsx
@@ -54,11 +54,11 @@ import {
 } from "@posthog/ui/features/sessions/components/chat-thread/ToolGroup";
 import { THREAD_HOTKEY_OPTIONS } from "@posthog/ui/features/sessions/components/chat-thread/threadHotkeys";
 import { usePromptRecallSource } from "@posthog/ui/features/sessions/components/chat-thread/usePromptRecallSource";
-import { MessageScrollbarRail } from "@posthog/ui/features/sessions/components/scrollbar-rail/MessageScrollbarRail";
-import { useMessageRailMarkers } from "@posthog/ui/features/sessions/components/scrollbar-rail/useMessageRailMarkers";
 import { GitActionMessage } from "@posthog/ui/features/sessions/components/GitActionMessage";
 import { GitActionResult } from "@posthog/ui/features/sessions/components/GitActionResult";
 import { mergeConversationItems } from "@posthog/ui/features/sessions/components/mergeConversationItems";
+import { MessageScrollbarRail } from "@posthog/ui/features/sessions/components/scrollbar-rail/MessageScrollbarRail";
+import { useMessageRailMarkers } from "@posthog/ui/features/sessions/components/scrollbar-rail/useMessageRailMarkers";
 import { extractCanvasInstructions } from "@posthog/ui/features/sessions/components/session-update/canvasInstructions";
 import { extractChannelContext } from "@posthog/ui/features/sessions/components/session-update/channelContext";
 import { extractCustomInstructions } from "@posthog/ui/features/sessions/components/session-update/customInstructions";
diff --git a/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.stories.tsx b/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.stories.tsx
index 872fd1397c..3b3cc876a5 100644
--- a/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.stories.tsx
+++ b/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.stories.tsx
@@ -1,8 +1,8 @@
 import { MessageScrollbarRail } from "@posthog/ui/features/sessions/components/scrollbar-rail/MessageScrollbarRail";
-import { useMessageRailMarkers } from "@posthog/ui/features/sessions/components/scrollbar-rail/useMessageRailMarkers";
 import type { MessageRailMarker } from "@posthog/ui/features/sessions/components/scrollbar-rail/messageRailTypes";
-import { useCallback, useRef, useState } from "react";
+import { useMessageRailMarkers } from "@posthog/ui/features/sessions/components/scrollbar-rail/useMessageRailMarkers";
 import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useCallback, useRef, useState } from "react";
 
 /**
  * Stories for the conversation scrollbar marker rail.
diff --git a/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.test.tsx b/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.test.tsx
index b2a7a0ec7c..f27597709b 100644
--- a/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.test.tsx
+++ b/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.test.tsx
@@ -3,8 +3,8 @@ import { describe, expect, it, vi } from "vitest";
 import { MessageScrollbarRail } from "./MessageScrollbarRail";
 import {
   MESSAGE_RAIL_LABEL_MAX_LENGTH,
-  truncateMessageLabel,
   type MessageRailMarker,
+  truncateMessageLabel,
 } from "./messageRailTypes";
 
 describe("truncateMessageLabel", () => {
diff --git a/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.tsx b/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.tsx
index 7f1e895028..478b02e996 100644
--- a/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.tsx
+++ b/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.tsx
@@ -53,6 +53,13 @@ export function MessageScrollbarRail({
               <button
                 type="button"
                 onClick={marker.onClick}
+                // The rail is mouse-only (aria-hidden on the root, below) — the
+                // messages it jumps to are already accessible in the transcript.
+                // `tabIndex={-1}` keeps these spatial shortcuts out of the tab
+                // order so the rail never produces focusable-but-unlabeled
+                // controls in the accessibility tree.
+                tabIndex={-1}
+                aria-label={`Jump to message: ${marker.label}`}
                 // The marker button spans the rail's full width; its vertical
                 // position is the fractional offset of the message within the
                 // scrollable content.
diff --git a/packages/ui/src/features/sessions/components/scrollbar-rail/useMessageRailMarkers.ts b/packages/ui/src/features/sessions/components/scrollbar-rail/useMessageRailMarkers.ts
index 84e20034a2..e6930301c4 100644
--- a/packages/ui/src/features/sessions/components/scrollbar-rail/useMessageRailMarkers.ts
+++ b/packages/ui/src/features/sessions/components/scrollbar-rail/useMessageRailMarkers.ts
@@ -1,8 +1,8 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import {
   MESSAGE_RAIL_LABEL_MAX_LENGTH,
-  truncateMessageLabel,
   type MessageRailMarker,
+  truncateMessageLabel,
 } from "./messageRailTypes";
 
 interface UserMessageEntry {

From b4085a4094dce25df377466b355cfdab8f385a34 Mon Sep 17 00:00:00 2001
From: Paul D'Ambra <paul.dambra@gmail.com>
Date: Tue, 21 Jul 2026 17:57:24 +0100
Subject: [PATCH 05/15] fix(ui): make markers visible in the
 ScrollableConversation story
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The scroll viewport in the ScrollableConversation story was `h-full` and in
normal flow inside `relative flex-1`, so without `min-h-0` the flex child grew
to the full content height (~15,000px) instead of the viewport height. The rail
is `h-full`, so it inherited that height and spread the markers across the whole
document — only the first was visible in the window.

Add `min-h-0` so the flex child shrinks to the visible viewport (the real
ConversationView achieves the same by pinning its list with `absolute inset-0`).
The rail is now viewport-height and all 10 markers tile within view.

Generated-By: PostHog Code
Task-Id: a950f289-b4c3-472e-b375-0799e0cbf8a4
---
 .../scrollbar-rail/MessageScrollbarRail.stories.tsx      | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.stories.tsx b/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.stories.tsx
index 3b3cc876a5..df48edab7a 100644
--- a/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.stories.tsx
+++ b/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.stories.tsx
@@ -166,9 +166,12 @@ function ScrollableConversationDemo() {
           that message, or hover one for a preview.
         </span>
       </div>
-      <div className="relative flex-1">
-        {/* The scroll viewport. `scrollbar-gutter: stable` reserves the gutter the
-            rail sits over, matching the real ConversationView. */}
+      <div className="relative min-h-0 flex-1">
+        {/* The scroll viewport. `min-h-0` lets the flex child shrink to the
+            viewport instead of growing with content, so the rail (`h-full`)
+            matches the *visible* height — the real ConversationView pins its
+            list with `absolute inset-0` for the same reason. `scrollbar-gutter:
+            stable` reserves the gutter the rail sits over. */}
         <div
           ref={scrollRef}
           className="scroll-mask-8 h-full overflow-y-auto"

From 313f9ac0e9f8dfb74917b2732c79d66377aca069 Mon Sep 17 00:00:00 2001
From: Paul D'Ambra <paul.dambra@gmail.com>
Date: Tue, 21 Jul 2026 18:01:38 +0100
Subject: [PATCH 06/15] fix(ui): bound scrollbar rail story viewport

Generated-By: PostHog Code
Task-Id: 9a68b219-d8a9-45af-ae6c-3f9b1b19e7b0
---
 .../scrollbar-rail/MessageScrollbarRail.stories.tsx    | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.stories.tsx b/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.stories.tsx
index df48edab7a..cf85a3bd75 100644
--- a/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.stories.tsx
+++ b/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.stories.tsx
@@ -167,14 +167,14 @@ function ScrollableConversationDemo() {
         </span>
       </div>
       <div className="relative min-h-0 flex-1">
-        {/* The scroll viewport. `min-h-0` lets the flex child shrink to the
-            viewport instead of growing with content, so the rail (`h-full`)
-            matches the *visible* height — the real ConversationView pins its
-            list with `absolute inset-0` for the same reason. `scrollbar-gutter:
+        {/* Pin the scroll viewport to this bounded flex child, matching the real
+            ConversationView. Keeping the viewport out of normal flow prevents
+            the long mock transcript from making the rail content-height and
+            spreading most markers below the captured scene. `scrollbar-gutter:
             stable` reserves the gutter the rail sits over. */}
         <div
           ref={scrollRef}
-          className="scroll-mask-8 h-full overflow-y-auto"
+          className="scroll-mask-8 absolute inset-0 overflow-y-auto"
           style={{ scrollbarGutter: "stable" }}
         >
           <div ref={contentRef} className="relative">

From d6a42b419479bfda62b787626f477f12cc1314fc Mon Sep 17 00:00:00 2001
From: "posthog[bot]" <206114724+posthog[bot]@users.noreply.github.com>
Date: Tue, 21 Jul 2026 21:49:33 +0000
Subject: [PATCH 07/15] chore(visual): update storybook baselines

4 updated
Run: 925dc45b-9dab-4332-8c13-77e829b57a3f

Co-authored-by: pauldambra <984817+pauldambra@users.noreply.github.com>
---
 apps/code/snapshots.yml | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/apps/code/snapshots.yml b/apps/code/snapshots.yml
index 3147f9a2f7..b61e19a359 100644
--- a/apps/code/snapshots.yml
+++ b/apps/code/snapshots.yml
@@ -332,6 +332,14 @@ snapshots:
         hash: v1.k4693efd2.602ee87d6d7a745d4b09d9e49bd12a70e52299b78ca97a48b5ca73a01532d801.F_1XKDzCxzMm_opEt9FvzczBb_2n-vyvOyGFXHGJmTk
     features-sessions-conversationview--with-pending-prompt--light:
         hash: v1.k4693efd2.1636dfc3ee0dd9d28065166f2fff0193f2d499692c74749d3afa7585aae898b5.YxTPa4CsqI2YuGLUdck8340ITZQrpna_C6z-SgII4Ws
+    features-sessions-scrollbarrail--pure--dark:
+        hash: v1.k4693efd2.65a8a9751978b1225ebcd43d2cf98fc9af4e08b360505f6341134b3b6f16bec1.A7iVr2e4YkBBM1Vh14gOW_miV7zmG8vny5n5FoM3MOI
+    features-sessions-scrollbarrail--pure--light:
+        hash: v1.k4693efd2.c08d498202dfe03b7eb796a373b695f2e213d48917e4440ad607f4ce6af02e2c.DWl3zrJX1AJEVdlcP2K0zl9wTzT-JbQ87NustHlt8KI
+    features-sessions-scrollbarrail--scrollable-conversation--dark:
+        hash: v1.k4693efd2.d063bb77a125bde7221b2ff96cc616aedf99128726bdfe8ecaf83d7631d49b99.kgO_IIZwLE5meW1Ju38huy1xcH-AyfF9t6M8ypLOIzg
+    features-sessions-scrollbarrail--scrollable-conversation--light:
+        hash: v1.k4693efd2.bef742a0769f0c76217537ba3e7b1e4fec91488b7749c39f80eddf690b37af8f.Fk7y9JBeORTnQJAlL0CAEntiC9gJC-6ThIMY_P5GIIo
     features-sessions-toolcallblock--create-new-file--dark:
         hash: v1.k4693efd2.8847f96037682460aba47f0e0f5113037918235fc98596933f2d1d06fd6f8f92.SHetexoVOtozsZGZQMcVbmpBlbk7M5D5Q0R_TJvPnyc
     features-sessions-toolcallblock--create-new-file--light:

From a68a9554839681ae73e6b4f7cc9f00b2a06f5f2e Mon Sep 17 00:00:00 2001
From: Paul D'Ambra <paul.dambra@gmail.com>
Date: Tue, 21 Jul 2026 23:04:43 +0100
Subject: [PATCH 08/15] fix(ui): show human-only conversation rail markers

Generated-By: PostHog Code
Task-Id: 9a68b219-d8a9-45af-ae6c-3f9b1b19e7b0
---
 .../MessageScrollbarRail.stories.tsx          | 47 ++++++-------------
 1 file changed, 15 insertions(+), 32 deletions(-)

diff --git a/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.stories.tsx b/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.stories.tsx
index cf85a3bd75..67f42b40f6 100644
--- a/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.stories.tsx
+++ b/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.stories.tsx
@@ -51,33 +51,18 @@ export const Pure: Story = {
             }),
             marker({
               id: "m2",
-              topPct: 0.23,
+              topPct: 0.52,
               label: "Add a marker to the scrollbar for my messages",
-            }),
-            marker({
-              id: "m3",
-              topPct: 0.48,
-              label: "Why did the build break on CI?",
               active: true,
             }),
-            marker({
-              id: "m4",
-              topPct: 0.71,
-              label: "Can you color the scrollbar based on conversation data?",
-            }),
-            marker({
-              id: "m5",
-              topPct: 0.93,
-              label: "Ship it",
-            }),
           ]}
         />
         {/* Caption so the rail (8px, far right) isn't the only thing on screen. */}
         <div className="flex h-full items-center justify-center px-12 text-center">
           <p className="text-(--gray-10) text-[13px] leading-relaxed">
-            Markers sit in the scrollbar gutter on the right. Hover one to see
-            the first few words; click to jump. The accent-colored marker is
-            active.
+            Each human message has one marker in the scrollbar gutter. Hover a
+            marker to preview the message; click to jump. The accent-colored
+            marker is active.
           </p>
         </div>
       </div>
@@ -90,26 +75,22 @@ export const Pure: Story = {
 interface TranscriptEntry {
   id: string;
   prompt: string;
-  reply: string;
+  reply: string[];
 }
 
 function buildTranscript(): TranscriptEntry[] {
   const prompts = [
     "How do I set up the dev environment for this repo?",
     "Add a darker marker to the scrollbar where my messages are",
-    "Why did the build break after the last merge?",
-    "Can you color the scrollbar based on data in the conversation?",
-    "Show the first few words of each message as a tooltip",
-    "Walk me through the DI boot sequence",
-    "What does the host boundary check enforce?",
-    "Refactor the conversation items pipeline",
-    "Generate a changelog entry for the rail",
-    "Ship it once tests are green",
   ];
   return prompts.map((prompt, i) => ({
     id: `user-${i}`,
     prompt,
-    reply: `Here's a thorough answer to "${prompt}". `.repeat(40),
+    reply: Array.from(
+      { length: 10 },
+      (_, paragraph) =>
+        `Response paragraph ${paragraph + 1}. Here's a thorough answer to "${prompt}" with enough detail to make the conversation scroll naturally.`,
+    ),
   }));
 }
 
@@ -190,9 +171,11 @@ function ScrollableConversationDemo() {
                 >
                   {entry.prompt}
                 </div>
-                <p className="mt-2 text-(--gray-11) text-[13px] leading-relaxed">
-                  {entry.reply}
-                </p>
+                <div className="mt-2 space-y-3 text-(--gray-11) text-[13px] leading-relaxed">
+                  {entry.reply.map((paragraph) => (
+                    <p key={paragraph}>{paragraph}</p>
+                  ))}
+                </div>
               </div>
             ))}
           </div>

From c735eb251dde066396cfcc6ae40903f6ebc52297 Mon Sep 17 00:00:00 2001
From: Paul D'Ambra <paul.dambra@gmail.com>
Date: Tue, 21 Jul 2026 23:23:48 +0100
Subject: [PATCH 09/15] fix(ui): measure rail markers from human messages only

Generated-By: PostHog Code
Task-Id: 9a68b219-d8a9-45af-ae6c-3f9b1b19e7b0
---
 .../components/scrollbar-rail/MessageScrollbarRail.stories.tsx  | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.stories.tsx b/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.stories.tsx
index 67f42b40f6..7fa67038d8 100644
--- a/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.stories.tsx
+++ b/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.stories.tsx
@@ -162,10 +162,10 @@ function ScrollableConversationDemo() {
             {transcript.map((entry) => (
               <div
                 key={entry.id}
-                data-conversation-item-id={entry.id}
                 className="mx-auto max-w-[640px] px-4 py-3"
               >
                 <div
+                  data-conversation-item-id={entry.id}
                   className="rounded-(--radius-2) px-3 py-2 text-[13px] text-white"
                   style={{ backgroundColor: ACCENT }}
                 >

From 40fe711ca945c848492bc1655e14860d173538ec Mon Sep 17 00:00:00 2001
From: Paul D'Ambra <paul@posthog.com>
Date: Tue, 21 Jul 2026 23:46:25 +0100
Subject: [PATCH 10/15] style(ui): biome-format MessageScrollbarRail story

Collapse a JSX element onto one line so `biome ci` passes formatting.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../scrollbar-rail/MessageScrollbarRail.stories.tsx          | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.stories.tsx b/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.stories.tsx
index 7fa67038d8..904b4c5c83 100644
--- a/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.stories.tsx
+++ b/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.stories.tsx
@@ -160,10 +160,7 @@ function ScrollableConversationDemo() {
         >
           <div ref={contentRef} className="relative">
             {transcript.map((entry) => (
-              <div
-                key={entry.id}
-                className="mx-auto max-w-[640px] px-4 py-3"
-              >
+              <div key={entry.id} className="mx-auto max-w-[640px] px-4 py-3">
                 <div
                   data-conversation-item-id={entry.id}
                   className="rounded-(--radius-2) px-3 py-2 text-[13px] text-white"

From 24ea8de6bedc4753eb1571aeca83f808e79fb5c6 Mon Sep 17 00:00:00 2001
From: "posthog[bot]" <206114724+posthog[bot]@users.noreply.github.com>
Date: Wed, 22 Jul 2026 11:16:22 +0000
Subject: [PATCH 11/15] chore(visual): update storybook baselines

4 updated
Run: 5c72beed-851f-4266-9d48-8750405a5f9c

Co-authored-by: pauldambra <984817+pauldambra@users.noreply.github.com>
---
 apps/code/snapshots.yml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/apps/code/snapshots.yml b/apps/code/snapshots.yml
index b61e19a359..40ce40c1b2 100644
--- a/apps/code/snapshots.yml
+++ b/apps/code/snapshots.yml
@@ -333,13 +333,13 @@ snapshots:
     features-sessions-conversationview--with-pending-prompt--light:
         hash: v1.k4693efd2.1636dfc3ee0dd9d28065166f2fff0193f2d499692c74749d3afa7585aae898b5.YxTPa4CsqI2YuGLUdck8340ITZQrpna_C6z-SgII4Ws
     features-sessions-scrollbarrail--pure--dark:
-        hash: v1.k4693efd2.65a8a9751978b1225ebcd43d2cf98fc9af4e08b360505f6341134b3b6f16bec1.A7iVr2e4YkBBM1Vh14gOW_miV7zmG8vny5n5FoM3MOI
+        hash: v1.k4693efd2.6baec21b1942848a3a376d2b90ca106b2c1b94de74382b4cd05673695d2649ee.UDDPtLDf1J2E3d3Oiy9is77Nm5xRSIfB7q5z0uUZRSQ
     features-sessions-scrollbarrail--pure--light:
-        hash: v1.k4693efd2.c08d498202dfe03b7eb796a373b695f2e213d48917e4440ad607f4ce6af02e2c.DWl3zrJX1AJEVdlcP2K0zl9wTzT-JbQ87NustHlt8KI
+        hash: v1.k4693efd2.33f02943fdbb1ea9774881f8909b580ab03ba02749614c533af1bf51dd817dca.ieP2bhDz0U_PTB4M6Zplvit0XlSTFiUn083GYBFNuC0
     features-sessions-scrollbarrail--scrollable-conversation--dark:
-        hash: v1.k4693efd2.d063bb77a125bde7221b2ff96cc616aedf99128726bdfe8ecaf83d7631d49b99.kgO_IIZwLE5meW1Ju38huy1xcH-AyfF9t6M8ypLOIzg
+        hash: v1.k4693efd2.203b62b52d6365d6ec222f7529c35b3f46b17cd07ca792a8ce2de594af4d589b.3dfpnVM8yxor1PNO5aPk0pxn5THZjK4otA6mbz3XhtA
     features-sessions-scrollbarrail--scrollable-conversation--light:
-        hash: v1.k4693efd2.bef742a0769f0c76217537ba3e7b1e4fec91488b7749c39f80eddf690b37af8f.Fk7y9JBeORTnQJAlL0CAEntiC9gJC-6ThIMY_P5GIIo
+        hash: v1.k4693efd2.fa7ef9cbdb09aef6108efcd3606cee32d889b3ad3b8f8be1ac637aed4e80cc72.0XcIKzM-sZHVG9hTZkAHdnBIPSrBiKmjq56QRQ6nasc
     features-sessions-toolcallblock--create-new-file--dark:
         hash: v1.k4693efd2.8847f96037682460aba47f0e0f5113037918235fc98596933f2d1d06fd6f8f92.SHetexoVOtozsZGZQMcVbmpBlbk7M5D5Q0R_TJvPnyc
     features-sessions-toolcallblock--create-new-file--light:

From 39e9a76786aece15045b655b349ee2d305015502 Mon Sep 17 00:00:00 2001
From: Paul D'Ambra <paul.dambra@gmail.com>
Date: Wed, 22 Jul 2026 12:22:14 +0100
Subject: [PATCH 12/15] fix(ui): address conversation rail React Doctor
 findings

Generated-By: PostHog Code
Task-Id: 106723a6-379c-4fdb-bde2-78568beacdfd
---
 .../sessions/components/ConversationView.tsx  | 143 ++++++++++++------
 .../scrollbar-rail/MessageScrollbarRail.tsx   |  19 ++-
 2 files changed, 105 insertions(+), 57 deletions(-)

diff --git a/packages/ui/src/features/sessions/components/ConversationView.tsx b/packages/ui/src/features/sessions/components/ConversationView.tsx
index b37108ccb7..cb5dcea1a4 100644
--- a/packages/ui/src/features/sessions/components/ConversationView.tsx
+++ b/packages/ui/src/features/sessions/components/ConversationView.tsx
@@ -75,8 +75,8 @@ import {
   useCallback,
   useEffect,
   useMemo,
+  useReducer,
   useRef,
-  useState,
 } from "react";
 import { useHotkeys } from "react-hotkeys-hook";
 
@@ -108,6 +108,57 @@ export interface ConversationViewProps {
   promptRecallRef?: RefObject<PromptRecallHandler | null>;
 }
 
+interface ConversationViewState {
+  showScrollButton: boolean;
+  jumpPickerOpen: boolean;
+  keyboardFocusedMessageId: string | null;
+  scrollElements: {
+    scrollEl: HTMLElement | null;
+    contentEl: HTMLElement | null;
+  };
+}
+
+type ConversationViewAction =
+  | { type: "set-show-scroll-button"; value: boolean }
+  | { type: "set-jump-picker-open"; value: boolean }
+  | { type: "set-keyboard-focused-message"; value: string | null }
+  | {
+      type: "set-scroll-elements";
+      value: ConversationViewState["scrollElements"];
+    };
+
+const INITIAL_CONVERSATION_VIEW_STATE: ConversationViewState = {
+  showScrollButton: false,
+  jumpPickerOpen: false,
+  keyboardFocusedMessageId: null,
+  scrollElements: { scrollEl: null, contentEl: null },
+};
+
+function conversationViewReducer(
+  state: ConversationViewState,
+  action: ConversationViewAction,
+): ConversationViewState {
+  switch (action.type) {
+    case "set-show-scroll-button":
+      return state.showScrollButton === action.value
+        ? state
+        : { ...state, showScrollButton: action.value };
+    case "set-jump-picker-open":
+      return state.jumpPickerOpen === action.value
+        ? state
+        : { ...state, jumpPickerOpen: action.value };
+    case "set-keyboard-focused-message":
+      return state.keyboardFocusedMessageId === action.value
+        ? state
+        : { ...state, keyboardFocusedMessageId: action.value };
+    case "set-scroll-elements":
+      return state.scrollElements.scrollEl === action.value.scrollEl &&
+        state.scrollElements.contentEl === action.value.contentEl
+        ? state
+        : { ...state, scrollElements: action.value };
+  }
+}
+
 export function ConversationView({
   events,
   isPromptPending,
@@ -136,7 +187,10 @@ export function ConversationView({
 
   const listRef = useRef<VirtualizedListHandle>(null);
   const isAtBottomRef = useRef(true);
-  const [showScrollButton, setShowScrollButton] = useState(false);
+  const [viewState, dispatchViewState] = useReducer(
+    conversationViewReducer,
+    INITIAL_CONVERSATION_VIEW_STATE,
+  );
   const debugLogsCloudRuns = useSettingsStore((s) => s.debugLogsCloudRuns);
   const showDebugLogs = debugLogsCloudRuns;
 
@@ -171,14 +225,11 @@ export function ConversationView({
   }
   const firstUserMessageId = firstUserMessageIdRef.current;
 
-  const [initialItemIds] = useState(
-    () =>
-      new Set(
-        conversationItems
-          .filter((i) => i.type === "user_message")
-          .map((i) => i.id),
-      ),
+  const initialItemIdsRef = useRef<Set<string> | null>(null);
+  initialItemIdsRef.current ??= new Set(
+    conversationItems.filter((i) => i.type === "user_message").map((i) => i.id),
   );
+  const initialItemIds = initialItemIdsRef.current;
 
   const pendingPermissions = usePendingPermissionsForTask(taskId ?? "");
   const pendingPermissionsCount = pendingPermissions.size;
@@ -249,10 +300,8 @@ export function ConversationView({
     listRef: searchListRef,
   });
 
-  const [jumpPickerOpen, setJumpPickerOpen] = useState(false);
-  const [keyboardFocusedMessageId, setKeyboardFocusedMessageId] = useState<
-    string | null
-  >(null);
+  const { jumpPickerOpen, keyboardFocusedMessageId, scrollElements } =
+    viewState;
 
   const userMessages = useMemo(() => {
     const result: Array<{ id: string; index: number; content: string }> = [];
@@ -298,7 +347,10 @@ export function ConversationView({
       if (!nextMessage) return;
 
       useSettingsStore.getState().markHintLearned(PROMPT_RECALL_HINT_KEY);
-      setKeyboardFocusedMessageId(nextMessage.id);
+      dispatchViewState({
+        type: "set-keyboard-focused-message",
+        value: nextMessage.id,
+      });
       scrollToUserMessage(nextMessage.id, nextMessage.index);
     },
     [keyboardFocusedMessageId, userMessages, scrollToUserMessage],
@@ -306,7 +358,11 @@ export function ConversationView({
 
   useHotkeys(
     SHORTCUTS.MESSAGE_JUMP,
-    () => setJumpPickerOpen((prev) => !prev),
+    () =>
+      dispatchViewState({
+        type: "set-jump-picker-open",
+        value: !jumpPickerOpen,
+      }),
     THREAD_HOTKEY_OPTIONS,
   );
 
@@ -323,43 +379,31 @@ export function ConversationView({
   );
 
   const clearKeyboardFocus = useCallback(() => {
-    setKeyboardFocusedMessageId(null);
+    dispatchViewState({ type: "set-keyboard-focused-message", value: null });
   }, []);
 
   const handleJumpToMessage = useCallback(
     (id: string) => {
       const message = userMessages.find((entry) => entry.id === id);
       if (!message) return;
-      setKeyboardFocusedMessageId(id);
+      dispatchViewState({ type: "set-keyboard-focused-message", value: id });
       scrollToUserMessage(id, message.index);
     },
     [userMessages, scrollToUserMessage],
   );
 
   // The scrollbar marker rail needs the VirtualizedList's scroll + content
-  // elements. They're only available after mount, so resolve them into state from
-  // the imperative handle; the rail re-renders once they're populated. The list's
-  // internal refs are stable for its lifetime, so a mount-time resolve (with a
-  // rAF retry for the first paint where the ref isn't attached yet) is enough.
-  const [scrollElements, setScrollElements] = useState<{
-    scrollEl: HTMLElement | null;
-    contentEl: HTMLElement | null;
-  }>({ scrollEl: null, contentEl: null });
-  useEffect(() => {
-    const sync = () => {
-      const handle = listRef.current;
-      if (!handle) return;
-      const scrollEl = handle.getScrollElement();
-      const contentEl = handle.getContentElement();
-      setScrollElements((prev) =>
-        prev.scrollEl === scrollEl && prev.contentEl === contentEl
-          ? prev
-          : { scrollEl, contentEl },
-      );
-    };
-    sync();
-    const raf = requestAnimationFrame(sync);
-    return () => cancelAnimationFrame(raf);
+  // elements. Resolve them from the list ref callback so the rail renders as
+  // soon as the imperative handle is attached, without mount-time state setup.
+  const setListRef = useCallback((handle: VirtualizedListHandle | null) => {
+    listRef.current = handle;
+    dispatchViewState({
+      type: "set-scroll-elements",
+      value: {
+        scrollEl: handle?.getScrollElement() ?? null,
+        contentEl: handle?.getContentElement() ?? null,
+      },
+    });
   }, []);
 
   const railUserMessages = useMemo(
@@ -378,7 +422,7 @@ export function ConversationView({
     onJump: (id) => {
       const message = userMessages.find((entry) => entry.id === id);
       if (!message) return;
-      setKeyboardFocusedMessageId(id);
+      dispatchViewState({ type: "set-keyboard-focused-message", value: id });
       scrollToUserMessage(id, message.index);
     },
     activeId: keyboardFocusedMessageId,
@@ -386,19 +430,22 @@ export function ConversationView({
 
   const handleScrollStateChange = useCallback((isAtBottom: boolean) => {
     isAtBottomRef.current = isAtBottom;
-    setShowScrollButton(!isAtBottom);
+    dispatchViewState({
+      type: "set-show-scroll-button",
+      value: !isAtBottom,
+    });
   }, []);
 
   const scrollToBottom = useCallback(() => {
     listRef.current?.scrollToBottom();
-    setShowScrollButton(false);
+    dispatchViewState({ type: "set-show-scroll-button", value: false });
   }, []);
 
   useEffect(() => {
     const handleVisibilityChange = () => {
       if (!document.hidden && isAtBottomRef.current) {
         listRef.current?.scrollToBottom();
-        setShowScrollButton(false);
+        dispatchViewState({ type: "set-show-scroll-button", value: false });
       }
     };
 
@@ -555,14 +602,16 @@ export function ConversationView({
 
         <MessageJumpPicker
           open={jumpPickerOpen}
-          onOpenChange={setJumpPickerOpen}
+          onOpenChange={(open) =>
+            dispatchViewState({ type: "set-jump-picker-open", value: open })
+          }
           items={items}
           onJumpToMessage={handleJumpToMessage}
         />
 
         <SessionTaskIdProvider taskId={taskId}>
           <VirtualizedList<ThreadRow>
-            ref={listRef}
+            ref={setListRef}
             items={threadRows}
             getItemKey={getRowKey}
             renderItem={renderRow}
@@ -576,7 +625,7 @@ export function ConversationView({
           />
         </SessionTaskIdProvider>
         <MessageScrollbarRail markers={railMarkers} />
-        {showScrollButton && (
+        {viewState.showScrollButton && (
           <Box className="absolute right-6 bottom-4 z-10">
             <Tooltip>
               <TooltipTrigger
diff --git a/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.tsx b/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.tsx
index 478b02e996..b1b5fd57da 100644
--- a/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.tsx
+++ b/packages/ui/src/features/sessions/components/scrollbar-rail/MessageScrollbarRail.tsx
@@ -27,8 +27,8 @@ export interface MessageScrollbarRailProps {
  *
  * The rail is `position: absolute` and pinned to the right edge, sized to the
  * native scrollbar gutter so it reads as part of the scrollbar rather than a
- * floating overlay. It is mouse-only — native drag-scrolling and keyboard
- * scrolling still work because the rail only intercepts clicks on its markers.
+ * floating overlay. Its marker buttons are labelled so keyboard and assistive
+ * technology users can jump directly to a message as well.
  */
 export function MessageScrollbarRail({
   markers,
@@ -39,7 +39,6 @@ export function MessageScrollbarRail({
 
   return (
     <div
-      aria-hidden
       className={cn(
         "pointer-events-none absolute top-0 right-0 z-10 h-full",
         className,
@@ -53,13 +52,7 @@ export function MessageScrollbarRail({
               <button
                 type="button"
                 onClick={marker.onClick}
-                // The rail is mouse-only (aria-hidden on the root, below) — the
-                // messages it jumps to are already accessible in the transcript.
-                // `tabIndex={-1}` keeps these spatial shortcuts out of the tab
-                // order so the rail never produces focusable-but-unlabeled
-                // controls in the accessibility tree.
-                tabIndex={-1}
-                aria-label={`Jump to message: ${marker.label}`}
+                aria-labelledby={`message-rail-marker-${marker.id}`}
                 // The marker button spans the rail's full width; its vertical
                 // position is the fractional offset of the message within the
                 // scrollable content.
@@ -69,6 +62,12 @@ export function MessageScrollbarRail({
                   height: `${Math.max(marker.heightPct * 100, 0.6)}%`,
                 }}
               >
+                <span
+                  id={`message-rail-marker-${marker.id}`}
+                  className="sr-only"
+                >
+                  Jump to message: {marker.label}
+                </span>
                 <span
                   className={cn(
                     "block h-full w-full rounded-full transition-colors",

From 96104caabac73ef94d46ea0b44cd14d6bb5e38a1 Mon Sep 17 00:00:00 2001
From: Paul D'Ambra <paul.dambra@gmail.com>
Date: Wed, 22 Jul 2026 12:24:56 +0100
Subject: [PATCH 13/15] fix(ui): space estimated message rail markers

Generated-By: PostHog Code
Task-Id: 106723a6-379c-4fdb-bde2-78568beacdfd
---
 .../components/scrollbar-rail/useMessageRailMarkers.ts | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/packages/ui/src/features/sessions/components/scrollbar-rail/useMessageRailMarkers.ts b/packages/ui/src/features/sessions/components/scrollbar-rail/useMessageRailMarkers.ts
index e6930301c4..2f29ebec47 100644
--- a/packages/ui/src/features/sessions/components/scrollbar-rail/useMessageRailMarkers.ts
+++ b/packages/ui/src/features/sessions/components/scrollbar-rail/useMessageRailMarkers.ts
@@ -221,10 +221,16 @@ function interpolateOffset(
     return { top, height: ESTIMATE };
   }
   if (prev) {
-    return { top: prev.top + prev.height + ESTIMATE, height: ESTIMATE };
+    return {
+      top: prev.top + prev.height + (index - prevIdx) * ESTIMATE,
+      height: ESTIMATE,
+    };
   }
   if (next) {
-    return { top: Math.max(0, next.top - ESTIMATE), height: ESTIMATE };
+    return {
+      top: Math.max(0, next.top - (nextIdx - index) * ESTIMATE),
+      height: ESTIMATE,
+    };
   }
   return { top: index * ESTIMATE, height: ESTIMATE };
 }

From c76c868ac49d824f86b28b7da304c926436d30b0 Mon Sep 17 00:00:00 2001
From: Paul D'Ambra <paul.dambra@gmail.com>
Date: Wed, 22 Jul 2026 12:27:38 +0100
Subject: [PATCH 14/15] chore(ci): restore React Doctor workflow

Generated-By: PostHog Code
Task-Id: 106723a6-379c-4fdb-bde2-78568beacdfd
---
 .github/scripts/react-doctor-comment.mjs | 140 +++++++++++++++++++++++
 .github/workflows/react-doctor.yml       | 120 +++++++++++++++++++
 2 files changed, 260 insertions(+)
 create mode 100644 .github/scripts/react-doctor-comment.mjs
 create mode 100644 .github/workflows/react-doctor.yml

diff --git a/.github/scripts/react-doctor-comment.mjs b/.github/scripts/react-doctor-comment.mjs
new file mode 100644
index 0000000000..bde71abc66
--- /dev/null
+++ b/.github/scripts/react-doctor-comment.mjs
@@ -0,0 +1,140 @@
+import fs from "node:fs";
+
+const [reportPath, outPath] = process.argv.slice(2);
+const MARKER = "<!-- react-doctor:summary -->";
+const slug = process.env.GITHUB_REPOSITORY;
+const server = (process.env.GITHUB_SERVER_URL || "https://github.com").replace(
+  /\/$/,
+  "",
+);
+const head = (
+  process.env.REACT_DOCTOR_HEAD_SHA ||
+  process.env.GITHUB_SHA ||
+  ""
+).trim();
+
+const MAX_LISTED = 50;
+const plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+const inline = (value) =>
+  String(value ?? "")
+    .replace(/\s+/g, " ")
+    .replace(/[`<>]/g, "")
+    .trim();
+const byFileThenLine = (a, b) =>
+  a.filePath === b.filePath
+    ? a.line - b.line
+    : a.filePath < b.filePath
+      ? -1
+      : 1;
+const encodedPath = (file) =>
+  String(file ?? "")
+    .split("/")
+    .map((segment) =>
+      encodeURIComponent(segment).replace(/[()]/g, (c) =>
+        c === "(" ? "%28" : "%29",
+      ),
+    )
+    .join("/");
+const fileLink = (file, line) =>
+  slug && head
+    ? `[\`${inline(file)}:${line}\`](${server}/${slug}/blob/${head}/${encodedPath(file)}#L${line})`
+    : `\`${inline(file)}:${line}\``;
+
+let report;
+try {
+  report = JSON.parse(fs.readFileSync(reportPath, "utf8"));
+} catch {
+  report = null;
+}
+
+const lines = [MARKER, ""];
+
+if (!report) {
+  lines.push("**React Doctor** could not produce a report.");
+} else if (!report.ok) {
+  lines.push(
+    "**React Doctor** could not complete this scan.",
+    "",
+    `> ${inline(report.error?.message) || "scan failed"}`,
+  );
+} else {
+  const summary = report.summary ?? {};
+  const total = summary.totalDiagnosticCount ?? 0;
+  const diagnostics = (report.projects ?? []).flatMap(
+    (project) => project.diagnostics ?? [],
+  );
+
+  if (total === 0) {
+    lines.push("**React Doctor** found no issues in the changed files. 🎉");
+  } else {
+    const severity = [];
+    if (summary.errorCount) severity.push(plural(summary.errorCount, "error"));
+    if (summary.warningCount)
+      severity.push(plural(summary.warningCount, "warning"));
+    const severityTail = severity.length ? ` · ${severity.join(" & ")}` : "";
+    lines.push(
+      `**React Doctor** found **${plural(total, "issue")}** in ${plural(summary.affectedFileCount ?? 0, "file")}${severityTail}.`,
+    );
+
+    const errors = diagnostics
+      .filter((d) => d.severity === "error")
+      .sort(byFileThenLine);
+    if (errors.length) {
+      lines.push("", "**Errors**", "");
+      for (const error of errors.slice(0, MAX_LISTED)) {
+        const title = inline(error.title);
+        lines.push(
+          `- ❌ ${fileLink(error.filePath, error.line)}${title ? ` ${title}` : ""} \`${inline(error.rule)}\``,
+        );
+      }
+      if (errors.length > MAX_LISTED)
+        lines.push(
+          "",
+          `${plural(errors.length - MAX_LISTED, "more error")} not shown.`,
+        );
+    }
+
+    const warnings = diagnostics
+      .filter((d) => d.severity === "warning")
+      .sort(byFileThenLine);
+    if (warnings.length) {
+      lines.push(
+        "",
+        `<details><summary>${plural(warnings.length, "warning")}</summary>`,
+        "",
+      );
+      let currentFile = null;
+      for (const warning of warnings.slice(0, MAX_LISTED)) {
+        if (warning.filePath !== currentFile) {
+          if (currentFile !== null) lines.push("");
+          lines.push(`**\`${inline(warning.filePath)}\`**`);
+          currentFile = warning.filePath;
+        }
+        const title = inline(warning.title);
+        lines.push(
+          `- ⚠️ ${fileLink(warning.filePath, warning.line)}${title ? ` ${title}` : ""} \`${inline(warning.rule)}\``,
+        );
+      }
+      if (warnings.length > MAX_LISTED)
+        lines.push(
+          "",
+          `${plural(warnings.length - MAX_LISTED, "more warning")} not shown.`,
+        );
+      lines.push("", "</details>");
+    }
+  }
+}
+
+const commit = head ? ` for commit \`${head.slice(0, 7)}\`` : "";
+lines.push(
+  "",
+  `<sub>Reviewed by [React Doctor](https://react.doctor)${commit}.</sub>`,
+);
+
+fs.writeFileSync(
+  outPath,
+  `${lines
+    .join("\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trimEnd()}\n`,
+);
diff --git a/.github/workflows/react-doctor.yml b/.github/workflows/react-doctor.yml
new file mode 100644
index 0000000000..d75b7260ec
--- /dev/null
+++ b/.github/workflows/react-doctor.yml
@@ -0,0 +1,120 @@
+name: React Doctor
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+    # Workflow-level paths only work because react-doctor is not a required
+    # check. If it ever becomes required, move the skip into a gate job like
+    # test.yml, or path-skipped PRs will wait on it forever.
+    paths:
+      - "**/*.ts"
+      - "**/*.tsx"
+      - "**/*.jsx"
+      - ".github/workflows/react-doctor.yml"
+      - ".github/scripts/react-doctor-comment.mjs"
+
+permissions:
+  contents: read
+  pull-requests: write
+
+concurrency:
+  group: react-doctor-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  react-doctor:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: 22
+          package-manager-cache: false
+
+      - id: scan
+        name: Run react-doctor on changed files
+        shell: bash
+        env:
+          NO_COLOR: "1"
+          REACT_DOCTOR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          # -e omitted: exit codes are captured and inspected explicitly.
+          set -uo pipefail
+          CHANGED="${RUNNER_TEMP}/react-doctor-changed-files.txt"
+          if ! git diff --name-only --diff-filter=ACMR "${REACT_DOCTOR_BASE_SHA}...${HEAD_SHA}" > "$CHANGED"; then
+            echo "Could not diff ${REACT_DOCTOR_BASE_SHA}...${HEAD_SHA}; failing rather than skipping the scan." >&2
+            echo "exit-code=1" >> "$GITHUB_OUTPUT"
+            exit 1
+          fi
+          if [ ! -s "$CHANGED" ]; then
+            echo "No changed files; nothing for react-doctor to scan."
+            echo "exit-code=0" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          REPORT="${RUNNER_TEMP}/react-doctor-report.json"
+          status=0
+          npx --yes react-doctor@0.5.4 . --blocking error --changed-files-from "$CHANGED" --json --json-compact --no-telemetry > "$REPORT" || status=$?
+          echo "exit-code=$status" >> "$GITHUB_OUTPUT"
+          echo "report=$REPORT" >> "$GITHUB_OUTPUT"
+          if [ "$status" -ne 0 ]; then
+            echo "react-doctor exited with status ${status}; report follows." >&2
+            cat "$REPORT" >&2 || true
+          fi
+
+      - name: Upsert sticky PR comment
+        if: ${{ always() && steps.scan.outputs.report != '' }}
+        continue-on-error: true
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GITHUB_REPOSITORY: ${{ github.repository }}
+          GITHUB_SERVER_URL: ${{ github.server_url }}
+          REACT_DOCTOR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REPORT: ${{ steps.scan.outputs.report }}
+        run: |
+          set -uo pipefail
+          BODY="${RUNNER_TEMP}/react-doctor-comment.md"
+          node "${GITHUB_WORKSPACE}/.github/scripts/react-doctor-comment.mjs" "$REPORT" "$BODY"
+          cat "$BODY" >> "$GITHUB_STEP_SUMMARY"
+          jq -Rs '{body: .}' "$BODY" > "${RUNNER_TEMP}/react-doctor-payload.json"
+          marker="<!-- react-doctor:summary -->"
+          existing=$(gh api "repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/comments" --paginate \
+            --jq ".[] | select(.body | startswith(\"${marker}\")) | .id" | head -n1 || true)
+          if [ -n "$existing" ]; then
+            gh api -X PATCH "repos/${GITHUB_REPOSITORY}/issues/comments/${existing}" --input "${RUNNER_TEMP}/react-doctor-payload.json" >/dev/null
+          else
+            gh api -X POST "repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/comments" --input "${RUNNER_TEMP}/react-doctor-payload.json" >/dev/null
+          fi
+
+      - name: Enforce blocking findings
+        if: ${{ always() }}
+        shell: bash
+        env:
+          STATUS: ${{ steps.scan.outputs.exit-code }}
+          REPORT: ${{ steps.scan.outputs.report }}
+        run: |
+          # -e omitted: exit codes are captured and inspected explicitly.
+          set -uo pipefail
+          if [ "${STATUS:-1}" = "0" ]; then
+            exit 0
+          fi
+          if [ -n "${REPORT:-}" ]; then
+            if ! jq -e . "$REPORT" >/dev/null 2>&1; then
+              echo "::warning title=React Doctor::Scanner exited ${STATUS:-1} without a valid JSON report; not blocking the PR on a scanner failure."
+              exit 0
+            fi
+            if jq -e '.ok == false' "$REPORT" >/dev/null 2>&1; then
+              # Strip newlines so the message cannot end the ::warning command early.
+              message=$(jq -r '.error.message // "unknown error"' "$REPORT" | tr -d '\n')
+              echo "::warning title=React Doctor::Scanner crashed (${message}); not blocking the PR on a scanner failure."
+              exit 0
+            fi
+          fi
+          exit "${STATUS:-1}"

From 8d826377e4bb17c7374474e4fa6afd5cb04553a0 Mon Sep 17 00:00:00 2001
From: Paul D'Ambra <paul@posthog.com>
Date: Wed, 22 Jul 2026 12:30:19 +0100
Subject: [PATCH 15/15] fix(ui): measure rail rows in one DOM pass, coalesce
 per frame

Address qa/codex P2: measure() ran one querySelector per user message on
every scroll event, which in long threads is hundreds/thousands of
synchronous DOM lookups per frame. Collect rendered rows with a single
querySelectorAll pass indexed by id, and coalesce observer/scroll-driven
measures to at most one per animation frame.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../scrollbar-rail/useMessageRailMarkers.ts   | 43 +++++++++++++++----
 1 file changed, 34 insertions(+), 9 deletions(-)

diff --git a/packages/ui/src/features/sessions/components/scrollbar-rail/useMessageRailMarkers.ts b/packages/ui/src/features/sessions/components/scrollbar-rail/useMessageRailMarkers.ts
index 2f29ebec47..73993f6bda 100644
--- a/packages/ui/src/features/sessions/components/scrollbar-rail/useMessageRailMarkers.ts
+++ b/packages/ui/src/features/sessions/components/scrollbar-rail/useMessageRailMarkers.ts
@@ -94,10 +94,18 @@ export function useMessageRailMarkers({
     // both move together). `offsetTop` can't be used directly because virtual
     // list rows live in a `transform`-ed wrapper that becomes the offset parent.
     const contentTop = content.getBoundingClientRect().top;
+    // Collect all rendered rows in a single DOM pass and index them by id,
+    // rather than one `querySelector` per message: in the long threads this
+    // rail targets, a per-message query on every scroll frame is hundreds or
+    // thousands of synchronous DOM lookups. `querySelectorAll` walks the
+    // (virtualized, bounded) rendered set once.
+    const rowById = new Map<string, HTMLElement>();
+    for (const row of content.querySelectorAll<HTMLElement>(`[${attr}]`)) {
+      const id = row.getAttribute(attr);
+      if (id != null) rowById.set(id, row);
+    }
     for (const entry of userMessagesRef.current) {
-      const row = content.querySelector(
-        `[${attr}="${CSS.escape(entry.id)}"]`,
-      ) as HTMLElement | null;
+      const row = rowById.get(entry.id);
       if (!row) continue;
       const rect = row.getBoundingClientRect();
       const top = rect.top - contentTop;
@@ -111,24 +119,41 @@ export function useMessageRailMarkers({
     if (changed) bump();
   }, [bump]);
 
+  // Coalesce observer/scroll-driven measures to at most one per animation
+  // frame — a burst of scroll or mutation events within a frame only needs a
+  // single re-measure. Cancelled on unmount via the ref below.
+  const frameRef = useRef<number | null>(null);
+  const scheduleMeasure = useCallback(() => {
+    if (frameRef.current != null) return;
+    frameRef.current = requestAnimationFrame(() => {
+      frameRef.current = null;
+      measure();
+    });
+  }, [measure]);
+
   // Refresh on scroll (positions change as the thumb moves) + on DOM mutation
   // (rows entering/leaving the virtualization window) + on content resize.
   useEffect(() => {
     if (!contentEl) return;
+    // Measure synchronously on mount so markers paint on the first frame; later
+    // event-driven measures are frame-coalesced through `scheduleMeasure`.
     measure();
-    const mutation = new MutationObserver(() => measure());
+    const mutation = new MutationObserver(scheduleMeasure);
     mutation.observe(contentEl, { childList: true, subtree: true });
-    const resize = new ResizeObserver(() => measure());
+    const resize = new ResizeObserver(scheduleMeasure);
     resize.observe(contentEl);
-    const onScroll = () => measure();
     const scroll = scrollEl ?? contentEl;
-    scroll.addEventListener("scroll", onScroll, { passive: true });
+    scroll.addEventListener("scroll", scheduleMeasure, { passive: true });
     return () => {
       mutation.disconnect();
       resize.disconnect();
-      scroll.removeEventListener("scroll", onScroll);
+      scroll.removeEventListener("scroll", scheduleMeasure);
+      if (frameRef.current != null) {
+        cancelAnimationFrame(frameRef.current);
+        frameRef.current = null;
+      }
     };
-  }, [contentEl, scrollEl, measure]);
+  }, [contentEl, scrollEl, measure, scheduleMeasure]);
 
   // Drop stale ids (removed messages) so markers don't linger after compaction.
   useEffect(() => {