fix(frontend): unblock pnpm generate:api after orval v8 upgrade (#11346)

Orval v8's pre-generation validator (@scalar/openapi-parser) treats every
`$ref` key as a JSON Reference. Our spec embeds Perses' `common.JSONRef`
struct, which has a property literally named `$ref`, so validation aborts
with `INVALID_REFERENCE`. Set `input.unsafeDisableValidation: true` to
bypass — codegen itself handles the spec correctly, and the spec is
backend-generated and CI-gated.

Closes SigNoz/engineering-pod#4963

frontend/orval.config.ts

@@ -10,6 +10,13 @@ export default defineConfig({
 	signoz: {
 		input: {
 			target: '../docs/api/openapi.yml',
+			// Perses' `common.JSONRef` (used by `DashboardGridItem.content`) has a
+			// field tagged `json:"$ref"`, so our spec contains a property literally
+			// named `$ref`.
+			// Orval v8's validator (`@scalar/openapi-parser`) treats every `$ref` key
+			// as a JSON Reference and aborts with `INVALID_REFERENCE` when the value isn't a URI string.
+			// Safe to disable: yes, the spec is generated by `cmd/openapi.go` and gated by backend CI, not hand-edited.
+			unsafeDisableValidation: true,
 		},
 		output: {
 			target: './src/api/generated/services',

frontend/src/AppRoutes/routes.ts

@@ -144,18 +144,18 @@ const routes: AppRoutes[] = [
 	// /trace-old serves V3 (URL-only access). Flip the two `component`
 	// values back to release V3.
 	{
-		path: ROUTES.TRACE_DETAIL,
+		path: ROUTES.TRACE_DETAIL_OLD,
 		exact: true,
 		component: TraceDetail,
 		isPrivate: true,
-		key: 'TRACE_DETAIL',
+		key: 'TRACE_DETAIL_OLD',
 	},
 	{
-		path: ROUTES.TRACE_DETAIL_OLD,
+		path: ROUTES.TRACE_DETAIL,
 		exact: true,
 		component: TraceDetailV3,
 		isPrivate: true,
-		key: 'TRACE_DETAIL_OLD',
+		key: 'TRACE_DETAIL',
 	},
 	{
 		path: ROUTES.SETTINGS,

frontend/src/api/generated/services/alerts/index.ts

@@ -3,7 +3,6 @@
  * * The file has been auto-generated using Orval for SigNoz
  * * regenerate with 'pnpm generate:api'
  * SigNoz
- * OpenAPI spec version: 0.0.1
  */
 import { useQuery } from 'react-query';
 import type {

frontend/src/api/generated/services/authdomains/index.ts

@@ -3,7 +3,6 @@
  * * The file has been auto-generated using Orval for SigNoz
  * * regenerate with 'pnpm generate:api'
  * SigNoz
- * OpenAPI spec version: 0.0.1
  */
 import { useMutation, useQuery } from 'react-query';
 import type {

frontend/src/api/generated/services/authz/index.ts

@@ -3,7 +3,6 @@
  * * The file has been auto-generated using Orval for SigNoz
  * * regenerate with 'pnpm generate:api'
  * SigNoz
- * OpenAPI spec version: 0.0.1
  */
 import { useMutation } from 'react-query';
 import type {

frontend/src/api/generated/services/channels/index.ts

@@ -3,7 +3,6 @@
  * * The file has been auto-generated using Orval for SigNoz
  * * regenerate with 'pnpm generate:api'
  * SigNoz
- * OpenAPI spec version: 0.0.1
  */
 import { useMutation, useQuery } from 'react-query';
 import type {

frontend/src/api/generated/services/cloudintegration/index.ts

@@ -3,7 +3,6 @@
  * * The file has been auto-generated using Orval for SigNoz
  * * regenerate with 'pnpm generate:api'
  * SigNoz
- * OpenAPI spec version: 0.0.1
  */
 import { useMutation, useQuery } from 'react-query';
 import type {

frontend/src/api/generated/services/dashboard/index.ts

@@ -3,7 +3,6 @@
  * * The file has been auto-generated using Orval for SigNoz
  * * regenerate with 'pnpm generate:api'
  * SigNoz
- * OpenAPI spec version: 0.0.1
  */
 import { useMutation, useQuery } from 'react-query';
 import type {

frontend/src/api/generated/services/downtimeschedules/index.ts

@@ -3,7 +3,6 @@
  * * The file has been auto-generated using Orval for SigNoz
  * * regenerate with 'pnpm generate:api'
  * SigNoz
- * OpenAPI spec version: 0.0.1
  */
 import { useMutation, useQuery } from 'react-query';
 import type {

frontend/src/api/generated/services/features/index.ts

@@ -3,7 +3,6 @@
  * * The file has been auto-generated using Orval for SigNoz
  * * regenerate with 'pnpm generate:api'
  * SigNoz
- * OpenAPI spec version: 0.0.1
  */
 import { useQuery } from 'react-query';
 import type {

frontend/src/api/generated/services/fields/index.ts

@@ -3,7 +3,6 @@
  * * The file has been auto-generated using Orval for SigNoz
  * * regenerate with 'pnpm generate:api'
  * SigNoz
- * OpenAPI spec version: 0.0.1
  */
 import { useQuery } from 'react-query';
 import type {

frontend/src/api/generated/services/gateway/index.ts

@@ -3,7 +3,6 @@
  * * The file has been auto-generated using Orval for SigNoz
  * * regenerate with 'pnpm generate:api'
  * SigNoz
- * OpenAPI spec version: 0.0.1
  */
 import { useMutation, useQuery } from 'react-query';
 import type {

frontend/src/api/generated/services/global/index.ts

@@ -3,7 +3,6 @@
  * * The file has been auto-generated using Orval for SigNoz
  * * regenerate with 'pnpm generate:api'
  * SigNoz
- * OpenAPI spec version: 0.0.1
  */
 import { useQuery } from 'react-query';
 import type {

frontend/src/api/generated/services/health/index.ts

@@ -3,7 +3,6 @@
  * * The file has been auto-generated using Orval for SigNoz
  * * regenerate with 'pnpm generate:api'
  * SigNoz
- * OpenAPI spec version: 0.0.1
  */
 import { useQuery } from 'react-query';
 import type {

frontend/src/api/generated/services/inframonitoring/index.ts

@@ -3,7 +3,6 @@
  * * The file has been auto-generated using Orval for SigNoz
  * * regenerate with 'pnpm generate:api'
  * SigNoz
- * OpenAPI spec version: 0.0.1
  */
 import { useMutation } from 'react-query';
 import type {

frontend/src/api/generated/services/llmpricingrules/index.ts

@@ -3,7 +3,6 @@
  * * The file has been auto-generated using Orval for SigNoz
  * * regenerate with 'pnpm generate:api'
  * SigNoz
- * OpenAPI spec version: 0.0.1
  */
 import { useMutation, useQuery } from 'react-query';
 import type {

frontend/src/api/generated/services/logs/index.ts

@@ -3,7 +3,6 @@
  * * The file has been auto-generated using Orval for SigNoz
  * * regenerate with 'pnpm generate:api'
  * SigNoz
- * OpenAPI spec version: 0.0.1
  */
 import { useMutation, useQuery } from 'react-query';
 import type {

frontend/src/api/generated/services/metrics/index.ts

@@ -3,7 +3,6 @@
  * * The file has been auto-generated using Orval for SigNoz
  * * regenerate with 'pnpm generate:api'
  * SigNoz
- * OpenAPI spec version: 0.0.1
  */
 import { useMutation, useQuery } from 'react-query';
 import type {

frontend/src/api/generated/services/orgs/index.ts

@@ -3,7 +3,6 @@
  * * The file has been auto-generated using Orval for SigNoz
  * * regenerate with 'pnpm generate:api'
  * SigNoz
- * OpenAPI spec version: 0.0.1
  */
 import { useMutation, useQuery } from 'react-query';
 import type {

frontend/src/api/generated/services/preferences/index.ts

@@ -3,7 +3,6 @@
  * * The file has been auto-generated using Orval for SigNoz
  * * regenerate with 'pnpm generate:api'
  * SigNoz
- * OpenAPI spec version: 0.0.1
  */
 import { useMutation, useQuery } from 'react-query';
 import type {

frontend/src/api/generated/services/querier/index.ts

@@ -3,7 +3,6 @@
  * * The file has been auto-generated using Orval for SigNoz
  * * regenerate with 'pnpm generate:api'
  * SigNoz
- * OpenAPI spec version: 0.0.1
  */
 import { useMutation } from 'react-query';
 import type {

frontend/src/api/generated/services/role/index.ts

@@ -3,7 +3,6 @@
  * * The file has been auto-generated using Orval for SigNoz
  * * regenerate with 'pnpm generate:api'
  * SigNoz
- * OpenAPI spec version: 0.0.1
  */
 import { useMutation, useQuery } from 'react-query';
 import type {

frontend/src/api/generated/services/routepolicies/index.ts

@@ -3,7 +3,6 @@
  * * The file has been auto-generated using Orval for SigNoz
  * * regenerate with 'pnpm generate:api'
  * SigNoz
- * OpenAPI spec version: 0.0.1
  */
 import { useMutation, useQuery } from 'react-query';
 import type {

frontend/src/api/generated/services/rules/index.ts

@@ -3,7 +3,6 @@
  * * The file has been auto-generated using Orval for SigNoz
  * * regenerate with 'pnpm generate:api'
  * SigNoz
- * OpenAPI spec version: 0.0.1
  */
 import { useMutation, useQuery } from 'react-query';
 import type {

frontend/src/api/generated/services/serviceaccount/index.ts

@@ -3,7 +3,6 @@
  * * The file has been auto-generated using Orval for SigNoz
  * * regenerate with 'pnpm generate:api'
  * SigNoz
- * OpenAPI spec version: 0.0.1
  */
 import { useMutation, useQuery } from 'react-query';
 import type {

frontend/src/api/generated/services/sessions/index.ts

@@ -3,7 +3,6 @@
  * * The file has been auto-generated using Orval for SigNoz
  * * regenerate with 'pnpm generate:api'
  * SigNoz
- * OpenAPI spec version: 0.0.1
  */
 import { useMutation, useQuery } from 'react-query';
 import type {

frontend/src/api/generated/services/sigNoz.schemas.ts

@@ -3,7 +3,6 @@
  * * The file has been auto-generated using Orval for SigNoz
  * * regenerate with 'pnpm generate:api'
  * SigNoz
- * OpenAPI spec version: 0.0.1
  */
 export interface AlertmanagertypesChannelDTO {
 	/**

frontend/src/api/generated/services/spanmapper/index.ts

@@ -3,7 +3,6 @@
  * * The file has been auto-generated using Orval for SigNoz
  * * regenerate with 'pnpm generate:api'
  * SigNoz
- * OpenAPI spec version: 0.0.1
  */
 import { useMutation, useQuery } from 'react-query';
 import type {

frontend/src/api/generated/services/tracedetail/index.ts

@@ -3,7 +3,6 @@
  * * The file has been auto-generated using Orval for SigNoz
  * * regenerate with 'pnpm generate:api'
  * SigNoz
- * OpenAPI spec version: 0.0.1
  */
 import { useMutation } from 'react-query';
 import type {

frontend/src/api/generated/services/users/index.ts

@@ -3,7 +3,6 @@
  * * The file has been auto-generated using Orval for SigNoz
  * * regenerate with 'pnpm generate:api'
  * SigNoz
- * OpenAPI spec version: 0.0.1
  */
 import { useMutation, useQuery } from 'react-query';
 import type {

frontend/src/api/generated/services/zeus/index.ts

@@ -3,7 +3,6 @@
  * * The file has been auto-generated using Orval for SigNoz
  * * regenerate with 'pnpm generate:api'
  * SigNoz
- * OpenAPI spec version: 0.0.1
  */
 import { useMutation, useQuery } from 'react-query';
 import type {

frontend/src/lib/uPlotV2/components/Tooltip/__tests__/utils.test.ts

@@ -189,7 +189,7 @@ describe('Tooltip utils', () => {
 			];
 		}
 
-		it('builds tooltip content in series-index order with isActive flag set correctly', () => {
+		it('builds tooltip content sorted by value descending with isActive flag set correctly', () => {
 			const data: AlignedData = [[0], [10], [20], [30]];
 			const series = createSeriesConfig();
 			const dataIndexes = [null, 0, 0, 0];
@@ -206,21 +206,21 @@ describe('Tooltip utils', () => {
 			});
 
 			expect(result).toHaveLength(2);
-			// Series are returned in series-index order (A=index 1 before B=index 2)
+			// Sorted by value descending: B (20) before A (10)
 			expect(result[0]).toMatchObject<Partial<TooltipContentItem>>({
-				label: 'A',
-				value: 10,
-				tooltipValue: 'formatted-10',
-				color: '#ff0000',
-				isActive: false,
-			});
-			expect(result[1]).toMatchObject<Partial<TooltipContentItem>>({
 				label: 'B',
 				value: 20,
 				tooltipValue: 'formatted-20',
 				color: 'color-2',
 				isActive: true,
 			});
+			expect(result[1]).toMatchObject<Partial<TooltipContentItem>>({
+				label: 'A',
+				value: 10,
+				tooltipValue: 'formatted-10',
+				color: '#ff0000',
+				isActive: false,
+			});
 		});
 
 		it('skips series with null data index or non-finite values', () => {
@@ -274,7 +274,7 @@ describe('Tooltip utils', () => {
 			expect(result[1].value).toBe(30);
 		});
 
-		it('returns items in series-index order', () => {
+		it('returns items sorted by value descending', () => {
 			// Series values in non-sorted order: 3, 1, 4, 2
 			const data: AlignedData = [[0], [3], [1], [4], [2]];
 			const series: Series[] = [
@@ -297,7 +297,7 @@ describe('Tooltip utils', () => {
 				decimalPrecision,
 			});
 
-			expect(result.map((item) => item.value)).toStrictEqual([3, 1, 4, 2]);
+			expect(result.map((item) => item.value)).toStrictEqual([4, 3, 2, 1]);
 		});
 	});
 });

frontend/src/lib/uPlotV2/components/Tooltip/utils.ts

@@ -142,5 +142,7 @@ export function buildTooltipContent({
 		}
 	}
 
+	items.sort((a, b) => b.value - a.value);
+
 	return items;
 }

frontend/src/pages/TraceDetailsV3/TraceWaterfall/TraceWaterfallStates/Success/Success.tsx

@@ -473,6 +473,7 @@ export const SpanDuration = memo(function SpanDuration({
 const columnDefHelper = createColumnHelper<SpanV3>();
 
 const ROW_HEIGHT = 28;
+const WATERFALL_BOTTOM_PADDING = 24;
 const DEFAULT_SIDEBAR_WIDTH = 450;
 const MIN_SIDEBAR_WIDTH = 240;
 const MAX_SIDEBAR_WIDTH = 900;
@@ -740,53 +741,69 @@ function Success(props: ISuccessProps): JSX.Element {
 		);
 	}, [spans, sidebarWidth]);
 
-	// Scroll to the interested span only when it isn't already on screen.
-	// Covers every entry point uniformly: deep-link, flamegraph click,
-	// filter prev/next, browser back/forward all scroll only if needed;
-	// waterfall row clicks and chevron expand/collapse don't yank the viewport
-	// because the affected row is by definition already visible.
+	// Scroll a span to viewport center if it isn't already visible. Shared by
+	// the two effects below — one keyed on interestedSpanId (chevron, boundary
+	// pagination, deep-link to unloaded), the other on selectedSpan (in-window
+	// URL navigation that doesn't mutate interestedSpanId).
+	const scrollSpanIntoView = useCallback(
+		(span: SpanV3, spansList: SpanV3[]): void => {
+			if (!virtualizerRef.current) {
+				return;
+			}
+			const idx = spansList.findIndex((s) => s.span_id === span.span_id);
+			if (idx === -1) {
+				return;
+			}
+			const scrollEl = scrollContainerRef.current;
+			const scrollTop = scrollEl?.scrollTop ?? 0;
+			const viewportHeight = scrollEl?.clientHeight ?? 0;
+			const viewportStartIdx = Math.floor(scrollTop / ROW_HEIGHT);
+			const viewportEndIdx =
+				Math.ceil((scrollTop + viewportHeight) / ROW_HEIGHT) - 1;
+			const isOnScreen =
+				viewportHeight > 0 && idx >= viewportStartIdx && idx <= viewportEndIdx;
+			if (isOnScreen) {
+				return;
+			}
+			setTimeout(() => {
+				virtualizerRef.current?.scrollToIndex(idx, {
+					align: 'center',
+					behavior: 'auto',
+				});
+				const sidebarScrollEl = scrollContainerRef.current?.querySelector(
+					'.resizable-box__content',
+				);
+				if (sidebarScrollEl) {
+					const targetScrollLeft = Math.max(0, span.level * CONNECTOR_WIDTH - 40);
+					(sidebarScrollEl as HTMLElement).scrollLeft = targetScrollLeft;
+				}
+			}, 100);
+		},
+		[],
+	);
+
 	useEffect(() => {
-		if (interestedSpanId.spanId !== '' && virtualizerRef.current) {
+		if (interestedSpanId.spanId !== '') {
 			const idx = spans.findIndex(
 				(span) => span.span_id === interestedSpanId.spanId,
 			);
 			if (idx !== -1) {
-				const visible = virtualizerRef.current.getVirtualItems();
-				const isOnScreen =
-					visible.length > 0 &&
-					idx >= visible[0].index &&
-					idx <= visible[visible.length - 1].index;
-
-				if (!isOnScreen) {
-					setTimeout(() => {
-						virtualizerRef.current?.scrollToIndex(idx, {
-							align: 'center',
-							behavior: 'auto',
-						});
-
-						// Auto-scroll sidebar horizontally to show the span name
-						const span = spans[idx];
-						const sidebarScrollEl = scrollContainerRef.current?.querySelector(
-							'.resizable-box__content',
-						);
-						if (sidebarScrollEl) {
-							const targetScrollLeft = Math.max(0, span.level * CONNECTOR_WIDTH - 40);
-							sidebarScrollEl.scrollLeft = targetScrollLeft;
-						}
-					}, 400);
-				}
-
+				scrollSpanIntoView(spans[idx], spans);
 				setSelectedSpan(spans[idx]);
 			}
 		} else {
-			setSelectedSpan((prev) => {
-				if (!prev) {
-					return spans[0];
-				}
-				return prev;
-			});
+			setSelectedSpan((prev) => prev ?? spans[0]);
 		}
-	}, [interestedSpanId, setSelectedSpan, spans]);
+	}, [interestedSpanId, setSelectedSpan, spans, scrollSpanIntoView]);
+
+	// Covers URL-driven navigation to an already-loaded span (flamegraph /
+	// filter / browser back) that the interestedSpanId-keyed effect doesn't see.
+	useEffect(() => {
+		if (selectedSpan) {
+			scrollSpanIntoView(selectedSpan, spans);
+		}
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [selectedSpan, scrollSpanIntoView]);
 
 	const virtualItems = virtualizer.getVirtualItems();
 	const leftRows = leftTable.getRowModel().rows;
@@ -846,7 +863,7 @@ function Success(props: ISuccessProps): JSX.Element {
 				<div
 					className={styles.splitBody}
 					style={{
-						minHeight: virtualizer.getTotalSize(),
+						minHeight: virtualizer.getTotalSize() + WATERFALL_BOTTOM_PADDING,
 						height: '100%',
 					}}
 				>

frontend/src/pages/TraceDetailsV3/index.tsx

@@ -74,17 +74,21 @@ function TraceDetailsV3(): JSX.Element {
 		onClose: handleSpanDetailsClose,
 	});
 
+	const allSpansRef = useRef<SpanV3[]>([]);
+
+	// Refetch only when the URL target isn't already loaded. Keeps row clicks
+	// and other in-window URL navigation from triggering a backend window slide.
 	useEffect(() => {
 		const spanId = urlQuery.get('spanId') || '';
-		// Only update interestedSpanId when a new span is selected,
-		// not when it's cleared (panel close) — avoids unnecessary API refetch
 		if (!spanId) {
 			return;
 		}
-		setInterestedSpanId({
-			spanId,
-			isUncollapsed: true,
-		});
+		const idx = allSpansRef.current.findIndex((s) => s.span_id === spanId);
+		if (idx !== -1) {
+			setSelectedSpan(allSpansRef.current[idx]);
+			return;
+		}
+		setInterestedSpanId({ spanId, isUncollapsed: true });
 	}, [urlQuery]);
 
 	// Hardcoded for now — fetch aggregations for all 3 candidate color-by fields
@@ -145,6 +149,10 @@ function TraceDetailsV3(): JSX.Element {
 		};
 	}
 
+	useEffect(() => {
+		allSpansRef.current = allSpans;
+	}, [allSpans]);
+
 	// Frontend mode: expand all parents by default when full data arrives
 	useEffect(() => {
 		if (isFullDataLoaded && allSpans.length > 0) {