fix: Stale waterfall selection when opening another span

.changeset/trace-span-follows-opened-result.md

@@ -0,0 +1,5 @@
+---
+'@hyperdx/app': patch
+---
+
+Fix the trace waterfall sticking on the previously opened span when another span of the same trace is opened, including from a session replay. Closing the result clears the selected span. Opening a different result selects that result's span, including when the waterfall stays mounted on cached data.

packages/app/src/SessionSidePanel.tsx

@@ -38,6 +38,7 @@ import SidePanelBreadcrumbs, {
   BreadcrumbItem,
 } from '@/components/SidePanelBreadcrumbs';
 import { useCloseOnClickOutside } from '@/hooks/useCloseOnClickOutside';
+import { useClearSpanSelection } from '@/hooks/useOpenedRowSpanSelection';
 import useResizable from '@/hooks/useResizable';
 import { WithClause } from '@/hooks/useRowWhere';
 import {
@@ -129,25 +130,29 @@ export default function SessionSidePanel({
     initialRowId: selectedEvent?.rowId,
   });
 
+  const clearSpanSelection = useClearSpanSelection();
+
   const handleBackToSession = useCallback(() => {
     setSelectedEvent(null);
     sidePanelStack.clearTrail();
   }, [setSelectedEvent, sidePanelStack]);
 
   const handleEventNavigate = useCallback(
     (rowId: string, aliasWith: WithClause[]) => {
+      clearSpanSelection();
       sidePanelStack.clearTrail();
       setSelectedEvent({ rowId, aliasWith, sessionId });
     },
-    [setSelectedEvent, sidePanelStack, sessionId],
+    [clearSpanSelection, setSelectedEvent, sidePanelStack, sessionId],
   );
 
   // X / Esc-at-root closes the whole panel and clears the session-panel params.
   const handleClose = useCallback(() => {
+    clearSpanSelection();
     setSelectedEvent(null);
     sidePanelStack.clearTrail();
     onClose();
-  }, [setSelectedEvent, sidePanelStack, onClose]);
+  }, [clearSpanSelection, setSelectedEvent, sidePanelStack, onClose]);
 
   useHotkeys(['esc'], handleClose, { enabled: !selectedEvent });
 

packages/app/src/components/DBRowSidePanel.tsx

@@ -9,6 +9,7 @@ import {
 } from 'react';
 import { add } from 'date-fns';
 import { isString } from 'lodash';
+import { useQueryState } from 'nuqs';
 import { ErrorBoundary, FallbackProps } from 'react-error-boundary';
 import { useHotkeys } from 'react-hotkeys-hook';
 import SqlString from 'sqlstring';
@@ -37,6 +38,7 @@ import {
 import { IconCopy, IconKeyboard, IconShare, IconX } from '@tabler/icons-react';
 
 import { useCloseOnClickOutside } from '@/hooks/useCloseOnClickOutside';
+import { useOpenedRowSpanSelection } from '@/hooks/useOpenedRowSpanSelection';
 import useResizable from '@/hooks/useResizable';
 import { WithClause } from '@/hooks/useRowWhere';
 import useSidePanelStack, {
@@ -77,6 +79,7 @@ import {
   DrawerFullWidthToggle,
   INITIAL_DRAWER_WIDTH_PERCENT,
 } from './DrawerUtils';
+import { eventRowWhereParser } from './eventRowWhere';
 import LogLevel from './LogLevel';
 import SidePanelBreadcrumbs, { BreadcrumbItem } from './SidePanelBreadcrumbs';
 import { SpanLinkData } from './SpanLinksSubpanel';
@@ -203,6 +206,7 @@ function SidePanelHeaderActions({
             size="sm"
             onClick={onClose}
             aria-label="Close"
+            data-testid="side-panel-close"
           >
             <IconX size={16} />
           </ActionIcon>
@@ -407,18 +411,22 @@ export const DBRowSidePanelInner = ({
     [pushSource],
   );
 
+  const clearSpanSelection = useOpenedRowSpanSelection(initialRowId);
+
   const handlePanelBack = useCallback(() => {
     // Pop one level (nav → source), restoring the tab active before that level
     // was entered. When the trail is empty, leave the panel: hand off to an
-    // embedding parent (session) or close.
+    // embedding parent (session) or close. The search drawer clears the span
+    // in its own close handler; a parent (the session) does not.
     if (popOne() === 'none') {
       if (onNavigateToParent) {
+        clearSpanSelection();
         onNavigateToParent();
       } else {
         onClose();
       }
     }
-  }, [popOne, onNavigateToParent, onClose]);
+  }, [popOne, onNavigateToParent, onClose, clearSpanSelection]);
 
   useHotkeys(['esc'], handlePanelBack);
 
@@ -760,7 +768,23 @@ export const DBRowSidePanelInner = ({
     const items: BreadcrumbItem[] = [];
 
     if (parentBreadcrumbs) {
-      items.push(...parentBreadcrumbs);
+      // A parent crumb (the session name) leaves this row without going
+      // through Back or Close. Clear the span on that click too.
+      items.push(
+        ...parentBreadcrumbs.map(item => {
+          const onClick = item.onClick;
+          if (onClick == null) {
+            return item;
+          }
+          return {
+            ...item,
+            onClick: () => {
+              clearSpanSelection();
+              onClick();
+            },
+          };
+        }),
+      );
     }
 
     const crumbSourceStack = sourceStack;
@@ -822,6 +846,7 @@ export const DBRowSidePanelInner = ({
     source.kind,
     handleBreadcrumbNavigation,
     parentBreadcrumbs,
+    clearSpanSelection,
   ]);
 
   const availableTabs = useMemo<Tab[]>(() => {
@@ -1327,6 +1352,10 @@ export default function DBRowSidePanelErrorBoundary({
   }, [isFullWidth, setSize]);
 
   const { clear: clearTraceWaterfallSearchState } = useWaterfallSearchState({});
+  const [, setEventRowWhere] = useQueryState(
+    'eventRowWhere',
+    eventRowWhereParser,
+  );
 
   const sidePanelStack = useSidePanelStack({ initialRowId: rowId });
 
@@ -1336,8 +1365,16 @@ export default function DBRowSidePanelErrorBoundary({
     // Clear waterfall search state on close, so that filters don't
     // persist when reopening another trace.
     clearTraceWaterfallSearchState();
+    // The selected span is in the URL. Leaving it there makes the next open,
+    // and any shared row link, show the previous span.
+    setEventRowWhere(null);
     onClose();
-  }, [sidePanelStack, onClose, clearTraceWaterfallSearchState]);
+  }, [
+    sidePanelStack,
+    onClose,
+    clearTraceWaterfallSearchState,
+    setEventRowWhere,
+  ]);
 
   useCloseOnClickOutside({
     // Only close on outside click at the root level. When the user has

packages/app/src/components/DBTracePanel.tsx

@@ -10,14 +10,12 @@ import { useAtom } from 'jotai';
 import { atomWithStorage } from 'jotai/utils';
 import { useQueryState } from 'nuqs';
 import { useForm, useWatch } from 'react-hook-form';
-import { z } from 'zod';
 import { tcFromSource } from '@hyperdx/common-utils/dist/core/metadata';
 import {
   isLogSource,
   isTraceSource,
   SourceKind,
   TSource,
-  WithClauseSchema,
 } from '@hyperdx/common-utils/dist/types';
 import {
   ActionIcon,
@@ -38,10 +36,10 @@ import {
 import { DBTraceWaterfallChartContainer } from '@/components/DBTraceWaterfallChart';
 import { SQLInlineEditorControlled } from '@/components/SQLEditor/SQLInlineEditor';
 import useResizable from '@/hooks/useResizable';
+import { RowHighlightHint } from '@/hooks/useRowHighlightHint';
 import { WithClause } from '@/hooks/useRowWhere';
 import { useSource, useUpdateSource } from '@/source';
 import TabBar from '@/TabBar';
-import { parseAsJsonEncoded } from '@/utils/queryParsers';
 
 import DBInfraPanel from './DBInfraPanel';
 import { RowDataPanel, rowHasK8sContext, useRowData } from './DBRowDataPanel';
@@ -50,35 +48,14 @@ import {
   deriveRowSidePanelContextForSource,
   RowSidePanelContext,
 } from './DBRowSidePanel';
+import { eventRowWhereParser } from './eventRowWhere';
 import SourceSchemaPreview, {
   isSourceSchemaPreviewEnabled,
 } from './SourceSchemaPreview';
 import { SourceSelectControlled } from './SourceSelect';
 
 import resizeStyles from '@/../styles/ResizablePanel.module.scss';
 
-type EventRowWhere = {
-  id: string;
-  type: string;
-  aliasWith: WithClause[];
-  // The trace this span selection was made in. Used to gate a selection left in
-  // the URL from a previous trace so it can't render against a different one.
-  traceId?: string;
-};
-
-// Validate the persisted span selection so a stale / hand-edited `eventRowWhere`
-// (valid JSON but wrong shape) resolves to null instead of feeding a malformed
-// row id into the span detail query.
-const eventRowWhereSchema = z.object({
-  id: z.string(),
-  type: z.string(),
-  aliasWith: z.array(WithClauseSchema),
-  traceId: z.string().optional(),
-});
-const eventRowWhereParser = parseAsJsonEncoded<EventRowWhere>(
-  eventRowWhereSchema.parse,
-);
-
 enum SpanDetailTab {
   Overview = 'overview',
   Parsed = 'parsed',
@@ -255,11 +232,7 @@ export default function DBTracePanel({
   // Passed in from side panel to try to identify which
   // span in the chart to highlight first without constructing
   // a full row where clause
-  initialRowHighlightHint?: {
-    timestamp: string;
-    spanId: string;
-    body: string;
-  };
+  initialRowHighlightHint?: RowHighlightHint;
   emptyState?: ReactNode;
   'data-testid'?: string;
 }) {

packages/app/src/components/DBTraceWaterfallChart.tsx

@@ -1,11 +1,4 @@
-import {
-  ReactNode,
-  useCallback,
-  useEffect,
-  useMemo,
-  useRef,
-  useState,
-} from 'react';
+import { ReactNode, useCallback, useMemo, useState } from 'react';
 import _, { omit } from 'lodash';
 import { useForm } from 'react-hook-form';
 import SqlString from 'sqlstring';
@@ -59,6 +52,10 @@ import {
 } from '@/components/traceWaterfallLimits';
 import { useColumns } from '@/hooks/useMetadata';
 import useOffsetPaginatedQuery from '@/hooks/useOffsetPaginatedQuery';
+import {
+  RowHighlightHint,
+  useRowHighlightHint,
+} from '@/hooks/useRowHighlightHint';
 import useRowWhere, { WithClause } from '@/hooks/useRowWhere';
 import useWaterfallSearchState from '@/hooks/useWaterfallSearchState';
 import {
@@ -686,11 +683,7 @@ export function DBTraceWaterfallChartContainer({
     aliasWith: WithClause[];
   }) => void;
   highlightedRowWhere?: string | null;
-  initialRowHighlightHint?: {
-    timestamp: string;
-    spanId: string;
-    body: string;
-  };
+  initialRowHighlightHint?: RowHighlightHint;
   emptyState?: ReactNode;
   /** Extra controls rendered in the waterfall controls bar (e.g. the correlated logs source selector). */
   controlsExtra?: ReactNode;
@@ -967,53 +960,13 @@ export function DBTraceWaterfallChartContainer({
     logRowsMeta,
   ]);
 
-  // Auto-select the originating span once when the panel opens — but only if
-  // nothing is already selected. Two cases must NOT trigger a (re-)select:
-  //   - the user explicitly cleared the selection (closing the span detail), and
-  //   - a selection was restored from the URL on load (deep link / reload).
-  // We mark the hint applied as soon as a selection exists or we apply it
-  // ourselves, so it never fires twice for the same hint; it re-fires only when
-  // the hint genuinely changes (different originating span / trace).
-  const appliedHighlightHintRef = useRef<string | null>(null);
-
-  useEffect(() => {
-    appliedHighlightHintRef.current = null;
-  }, [traceId]);
-
-  useEffect(() => {
-    if (!initialRowHighlightHint || !onClick) {
-      return;
-    }
-
-    const hintKey = `${initialRowHighlightHint.timestamp}|${initialRowHighlightHint.spanId}|${initialRowHighlightHint.body}`;
-    if (appliedHighlightHintRef.current === hintKey) {
-      return;
-    }
-
-    // A selection already exists (restored from the URL, or user-chosen). Honor
-    // it and record the hint so we never override it — now or later.
-    if (highlightedRowWhere != null) {
-      appliedHighlightHintRef.current = hintKey;
-      return;
-    }
-
-    const initialRowHighlightIndex = rows.findIndex(row => {
-      return (
-        row.Timestamp === initialRowHighlightHint.timestamp &&
-        row.SpanId === initialRowHighlightHint.spanId &&
-        row.Body === initialRowHighlightHint.body
-      );
-    });
-
-    if (initialRowHighlightIndex !== -1) {
-      appliedHighlightHintRef.current = hintKey;
-      onClick({
-        id: rows[initialRowHighlightIndex].id,
-        type: rows[initialRowHighlightIndex].type ?? '',
-        aliasWith: rows[initialRowHighlightIndex].aliasWith,
-      });
-    }
-  }, [initialRowHighlightHint, rows, onClick, highlightedRowWhere]);
+  useRowHighlightHint({
+    traceId,
+    initialRowHighlightHint,
+    highlightedRowWhere,
+    rows,
+    onClick,
+  });
 
   // 3 Edge-cases
   // 1. No spans, just logs (ex. sampling)