[OPIK-8050] [FE] fix: paginate prompt version history and fix version labeling (#8140)

* [OPIK-8050] [FE] fix: paginate prompt version history and fix version labeling

Version history on the Prompt tab only ever loaded the first 25 versions
(single page, client-computed vN labels), so older versions were
unreachable and a deep link to one silently fell back to the latest
version while still showing a stale label. Switches to a paginated
usePromptVersionsByIdInfinite hook, wires the lazy-load already built
into VersionHistoryTimeline, and replaces index-derived labels with the
backend's persistent version_number (falling back to commit when a
pre-migration row has none). Also fixes OPIK-8189: the Compare sheet
recomputed labels from whatever was locally loaded instead of the true
total, mislabeling versions past the first page.

Guards a stale/crafted activeVersionId from rendering a different
prompt's content, aligns the new hook's cache key with existing
mutation invalidations so the sidebar refreshes after writes, and
extends the Diff dropdown to auto-paginate so "Compare against" isn't
capped at the first loaded page either.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(prompts): guard version-history pagination, dedupe fetcher, extract orchestration hook

- Gate the deep-link, diff-menu, and scroll-sentinel pagination triggers on
  isFetching/isError (not just isFetchingNextPage) to stop a permanently
  failing page fetch from hammering the backend in an infinite retry loop.
- Reject version_type=mask when resolving the active version by id, both for
  rendering and for the playground-load fetch, since the by-id lookup isn't
  scoped the way the paginated list is.
- Fix the mobile version dropdown to highlight the resolved active version
  instead of the raw query param.
- Share one fetcher between usePromptVersionsById and
  usePromptVersionsByIdInfinite instead of duplicating the request logic.
- Reuse an already-loaded version from the paginated list instead of issuing
  a redundant by-id fetch when switching between loaded versions.
- Extract version-history orchestration (pagination, selection, active
  version resolution) out of PromptTab into usePromptVersionHistory.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(prompts): paginate Deploy menu owners, unify positional labels, dedupe pagination triggers

- DeployToEnvironmentMenu now auto-paginates while open (mirroring the Diff
  menu) so "Currently vN" resolves for owners on unloaded pages instead of
  silently omitting them.
- Replace remaining positional v{total-idx} labels with the backend's
  version_number/commit in usePromptVersionLabel, usePromptVersionsWithLabels,
  and PromptLibraryMenu, so labels stay correct across Playground, trace
  details, prompt select boxes, Optimizations, and Agent Runner even after
  older versions are deleted.
- Merge the deep-link, Diff-menu, and Deploy-menu pagination triggers into a
  single effect so at most one fetchNextPage() fires per render — two
  separate effects both firing in the same render could cancel each other
  via TanStack Query's default cancelRefetch behavior.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(prompts): keep compare dialog target correct during deep-link pagination

Inject the already-resolved activeVersion into the versions array passed to
ComparePromptVersionDialog when it isn't yet in the paginated list. Without
this, opening Diff while a deep-linked version's page was still loading made
the dialog silently fall back to the newest loaded version instead of the
one actually requested.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(prompts): bound version-history refetch cost to actual changes

useInfiniteQuery refetches every already-loaded page sequentially on any
trigger, and the Diff/Deploy menus can load many pages for large prompts —
so the prior refetchInterval/refetchOnWindowFocus multiplied request volume
by however many pages a session had loaded. Drop those from the infinite
query and instead poll the cheap prompt object (version_count) on the same
interval, invalidating the versions list only when that count actually
changes.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(prompts): disable window-focus refetch on version-history query

The prior fix's intent comment claimed refetchOnWindowFocus was off, but
never actually set it — the default true still refetched every loaded page
on window focus, defeating the point of bounding refetch cost to actual
version_count changes.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(prompts): guard pagination, dedupe scan cost, and stop compare-dialog resets

- usePromptVersionsByIdInfinite: getNextPageParam now treats an empty page
  as terminal instead of trusting `total`, which could loop forever if the
  two go out of sync (e.g. a concurrent delete between the count and the
  page query). Also gives the infinite-query cache key an explicit
  `view: "infinite"` marker instead of relying on the implicit (and
  breakable) "this hook never has page/size" invariant to stay distinct
  from usePromptVersionsById's key.
- usePromptVersionHistory: memoize isChasingDeepLink so a stale/nonexistent
  activeVersionId doesn't re-scan the whole (growing) version list on every
  unrelated render while it chases pages.
- ComparePromptVersionDialog: the selection-reset effect now fires only on
  the open transition (reading the rest via a ref) instead of on every
  versions/versionOptions change while already open, so a background
  refetch (pagination continuing, a version_count invalidation) no longer
  silently resets the comparison the user is looking at.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(prompts): keep compare dialog target correct during deep-link pagination

ComparePromptVersionDialog previously stored the selected base/diff
PromptVersion objects as state, snapshotted on open. Combined with the
open-only reconciliation effect (added to stop background refetches from
resetting the user's selection), this meant a background refetch could
leave the dialog rendering stale content, or a removed version rendering
content that no longer exists.

Store only the selected version id in state and re-resolve the actual
version live from `versions` on every render instead: a background refetch
now keeps rendered content current, and a version that disappears from the
list resolves to undefined (renders nothing) rather than stale data — while
still not resetting the selection on harmless background changes.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(prompts): guard compare-dialog media diff on missing versions

anyMediaChanged alone gated the media section, unlike the Prompt/Metadata
sections which already require both baseVersion and diffVersion. Since
collectMedia falls back to empty media arrays when a version is undefined
(e.g. deleted out from under an open dialog), any media on the surviving
version read as "changed" and rendered — a one-sided comparison against a
version that no longer exists. Add the same baseVersion && diffVersion
guard already used by the other two sections.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

Author: natagh23

apps/opik-frontend/src/api/prompts/getPromptVersionsById.ts

@@ -0,0 +1,52 @@
+import { QueryFunctionContext } from "@tanstack/react-query";
+import api, { PROMPTS_REST_ENDPOINT } from "@/api/api";
+import { PromptVersion } from "@/types/prompts";
+import { Sorting } from "@/types/sorting";
+import { processSorting } from "@/lib/sorting";
+import { Filter } from "@/types/filters";
+import { processFilters } from "@/lib/filters";
+
+export type GetPromptVersionsByIdParams = {
+  promptId: string;
+  page: number;
+  size: number;
+  sorting?: Sorting;
+  filters?: Filter[];
+  search?: string;
+};
+
+export type PromptVersionsByIdResponse = {
+  content: PromptVersion[];
+  page: number;
+  size: number;
+  total: number;
+  sortable_by: string[];
+};
+
+export const getPromptVersionsById = async (
+  { signal }: QueryFunctionContext,
+  {
+    promptId,
+    size,
+    page,
+    sorting,
+    filters,
+    search,
+  }: GetPromptVersionsByIdParams,
+): Promise<PromptVersionsByIdResponse> => {
+  const { data } = await api.get(
+    `${PROMPTS_REST_ENDPOINT}${promptId}/versions`,
+    {
+      signal,
+      params: {
+        ...processFilters(filters),
+        ...processSorting(sorting),
+        size,
+        page,
+        ...(search && { search }),
+      },
+    },
+  );
+
+  return data;
+};

apps/opik-frontend/src/api/prompts/usePromptVersionsById.ts

@@ -1,59 +1,14 @@
-import { QueryFunctionContext, useQuery } from "@tanstack/react-query";
-import api, { PROMPTS_REST_ENDPOINT, QueryConfig } from "@/api/api";
-import { PromptVersion } from "@/types/prompts";
-import { Sorting } from "@/types/sorting";
-import { processSorting } from "@/lib/sorting";
-import { Filter } from "@/types/filters";
-import { processFilters } from "@/lib/filters";
-
-type UsePromptVersionsByIdParams = {
-  promptId: string;
-  page: number;
-  size: number;
-  sorting?: Sorting;
-  filters?: Filter[];
-  search?: string;
-};
-
-type UsePromptsVersionsByIdResponse = {
-  content: PromptVersion[];
-  page: number;
-  size: number;
-  total: number;
-  sortable_by: string[];
-};
-
-const getPromptVersionsById = async (
-  { signal }: QueryFunctionContext,
-  {
-    promptId,
-    size,
-    page,
-    sorting,
-    filters,
-    search,
-  }: UsePromptVersionsByIdParams,
-) => {
-  const { data } = await api.get(
-    `${PROMPTS_REST_ENDPOINT}${promptId}/versions`,
-    {
-      signal,
-      params: {
-        ...processFilters(filters),
-        ...processSorting(sorting),
-        size,
-        page,
-        ...(search && { search }),
-      },
-    },
-  );
-
-  return data;
-};
+import { useQuery } from "@tanstack/react-query";
+import { QueryConfig } from "@/api/api";
+import {
+  getPromptVersionsById,
+  GetPromptVersionsByIdParams,
+  PromptVersionsByIdResponse,
+} from "./getPromptVersionsById";
 
 export default function usePromptVersionsById(
-  params: UsePromptVersionsByIdParams,
-  options?: QueryConfig<UsePromptsVersionsByIdResponse>,
+  params: GetPromptVersionsByIdParams,
+  options?: QueryConfig<PromptVersionsByIdResponse>,
 ) {
   return useQuery({
     queryKey: ["prompt-versions", params],

apps/opik-frontend/src/api/prompts/usePromptVersionsByIdInfinite.ts

@@ -0,0 +1,61 @@
+import { useInfiniteQuery } from "@tanstack/react-query";
+import { Sorting } from "@/types/sorting";
+import { Filter } from "@/types/filters";
+import {
+  getPromptVersionsById,
+  PromptVersionsByIdResponse,
+} from "./getPromptVersionsById";
+
+const PAGE_SIZE = 25;
+
+type UsePromptVersionsByIdInfiniteParams = {
+  promptId: string;
+  sorting?: Sorting;
+  filters?: Filter[];
+  search?: string;
+};
+
+type UsePromptVersionsByIdInfiniteOptions = {
+  enabled?: boolean;
+  refetchInterval?: number;
+  refetchOnWindowFocus?: boolean;
+};
+
+export default function usePromptVersionsByIdInfinite(
+  params: UsePromptVersionsByIdInfiniteParams,
+  options?: UsePromptVersionsByIdInfiniteOptions,
+) {
+  return useInfiniteQuery<PromptVersionsByIdResponse>({
+    // Shares the "prompt-versions" key prefix with usePromptVersionsById so
+    // the mutation hooks that invalidate that prefix (create/delete/deploy a
+    // version) also invalidate this list — otherwise the sidebar goes stale
+    // after every write. The explicit `view: "infinite"` marker keeps the two
+    // hooks' cache entries apart without relying on the fragile "this one
+    // never has page/size" invariant, which a future change to either hook
+    // could silently break.
+    queryKey: ["prompt-versions", { ...params, view: "infinite" as const }],
+    queryFn: (context) =>
+      getPromptVersionsById(context, {
+        ...params,
+        size: PAGE_SIZE,
+        page: context.pageParam as number,
+      }),
+    // `size` on the response is the actual item count returned (not the
+    // requested page size), so it shrinks on the last page and hits 0 past
+    // it — `page * size` is not a valid "items seen so far" once that
+    // happens. Sum each page's real content length instead. An empty page
+    // always ends pagination outright: trusting `total` past that point can
+    // loop forever if it's out of sync with the actual row count (e.g. a
+    // concurrent delete between the count and the page query).
+    getNextPageParam: (lastPage, allPages) => {
+      if (lastPage.content.length === 0) return undefined;
+      const fetchedCount = allPages.reduce(
+        (sum, p) => sum + p.content.length,
+        0,
+      );
+      return fetchedCount < lastPage.total ? allPages.length + 1 : undefined;
+    },
+    initialPageParam: 1,
+    ...options,
+  });
+}

apps/opik-frontend/src/hooks/usePromptVersionLabel.ts

@@ -3,12 +3,9 @@ import { useMemo } from "react";
 import usePromptVersionsById from "@/api/prompts/usePromptVersionsById";
 
 /**
- * Compute the human-facing "v{n}" label for a specific prompt version.
- *
- * Versions are labeled by their position when sorted by created_at desc:
- * the oldest is v1, the newest is v{total}. We need the versions list to
- * find that position — version_count on the Prompt object only tells us
- * the total (i.e., the latest's label).
+ * Compute the human-facing label for a specific prompt version, using the
+ * backend-persisted version_number so it stays correct even after older
+ * versions are deleted (positional "v{n}" labels shift when that happens).
  */
 const usePromptVersionLabel = (
   promptId: string | undefined,
@@ -27,9 +24,8 @@ const usePromptVersionLabel = (
 
   return useMemo(() => {
     if (versionId && data?.content) {
-      const idx = data.content.findIndex((v) => v.id === versionId);
-      const total = data.total ?? data.content.length;
-      if (idx >= 0 && total > 0) return `v${total - idx}`;
+      const version = data.content.find((v) => v.id === versionId);
+      if (version) return version.version_number ?? version.commit;
     }
     return fallbackVersionCount && fallbackVersionCount > 0
       ? `v${fallbackVersionCount}`

apps/opik-frontend/src/v2/pages-shared/llm/PromptLibraryMenu/PromptLibraryMenu.tsx

@@ -241,7 +241,6 @@ const PromptVersionsList: React.FC<PromptVersionsListProps> = ({
   );
 
   const versions = data?.content ?? [];
-  const total = data?.total ?? versions.length;
 
   if (isLoading) {
     return (
@@ -259,8 +258,8 @@ const PromptVersionsList: React.FC<PromptVersionsListProps> = ({
 
   return (
     <div className="max-h-[40vh] overflow-y-auto">
-      {versions.map((version, idx) => {
-        const label = `v${total - idx}`;
+      {versions.map((version) => {
+        const label = version.version_number ?? version.commit;
         const isActive = version.id === activeVersionId;
         const stage = pickHighestStage(version.tags);
         return (

apps/opik-frontend/src/v2/pages-shared/version-history/DiffVersionMenu.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { Clock, GitCompareArrows } from "lucide-react";
+import { Clock, GitCompareArrows, Loader2 } from "lucide-react";
 
 import { getTimeFromNow } from "@/lib/date";
 import { Button } from "@/ui/button";
@@ -20,18 +20,22 @@ interface DiffVersionMenuProps {
   versions: VersionHistoryItem[];
   onSelectVersion: (item: VersionHistoryItem) => void;
   triggerLabel?: string;
+  onOpenChange?: (open: boolean) => void;
+  isLoadingMore?: boolean;
 }
 
 const DiffVersionMenu: React.FC<DiffVersionMenuProps> = ({
   currentItemId,
   versions,
   onSelectVersion,
   triggerLabel = "Show diff",
+  onOpenChange,
+  isLoadingMore = false,
 }) => {
   const selectableVersions = versions.filter((v) => v.id !== currentItemId);
 
   return (
-    <DropdownMenu>
+    <DropdownMenu onOpenChange={onOpenChange}>
       <DropdownMenuTrigger asChild>
         <Button
           size="sm"
@@ -73,6 +77,11 @@ const DiffVersionMenu: React.FC<DiffVersionMenuProps> = ({
               </span>
             </DropdownMenuItem>
           ))}
+          {isLoadingMore && (
+            <div className="flex justify-center py-2">
+              <Loader2 className="size-4 animate-spin text-light-slate" />
+            </div>
+          )}
         </div>
       </DropdownMenuContent>
     </DropdownMenu>

apps/opik-frontend/src/v2/pages-shared/version-history/VersionHistoryTimeline.tsx

@@ -25,6 +25,16 @@ interface VersionHistoryTimelineProps {
   onSelect: (item: VersionHistoryItem) => void;
   hasNextPage?: boolean;
   isFetchingNextPage?: boolean;
+  // Broader than isFetchingNextPage — also true during a background refetch
+  // (e.g. the 30s poll, or a mutation's invalidation of already-loaded
+  // pages). Used only to gate the auto-load trigger, not the spinner: firing
+  // onLoadMore while an unrelated fetch is in flight races it and can
+  // produce a duplicate/overlapping row once both resolve.
+  isFetching?: boolean;
+  // True once a page fetch has failed. hasNextPage still reflects the last
+  // *successful* page, so without this the sentinel retries a permanently
+  // failing request forever, the moment isFetching settles back to false.
+  hasError?: boolean;
   onLoadMore?: () => void;
   emptyTitle?: string;
 }
@@ -35,16 +45,18 @@ const VersionHistoryTimeline: React.FC<VersionHistoryTimelineProps> = ({
   onSelect,
   hasNextPage = false,
   isFetchingNextPage = false,
+  isFetching = false,
+  hasError = false,
   onLoadMore,
   emptyTitle = "No version history",
 }) => {
   const { ref: sentinelRef, inView } = useInView();
 
   useEffect(() => {
-    if (inView && hasNextPage && !isFetchingNextPage && onLoadMore) {
+    if (inView && hasNextPage && !isFetching && !hasError && onLoadMore) {
       onLoadMore();
     }
-  }, [inView, hasNextPage, isFetchingNextPage, onLoadMore]);
+  }, [inView, hasNextPage, isFetching, hasError, onLoadMore]);
 
   if (items.length === 0) {
     return <DataTableNoData title={emptyTitle} />;

apps/opik-frontend/src/v2/pages-shared/version-history/usePromptVersionsWithLabels.ts

@@ -46,10 +46,10 @@ export function usePromptVersionsWithLabels(
       versions.map((version, index) => ({
         version,
         index,
-        label: `v${total - index}`,
+        label: version.version_number ?? version.commit,
         stage: pickHighestStage(version.tags),
       })),
-    [versions, total],
+    [versions],
   );
 
   const getDescriptor = useMemo(() => {