feat(replay): pin line labels to a stable anchor during replay

In "Replay over time", line labels were re-placed every frame by the
greedy placement algorithm, so they teleported between candidate
positions (and the TTFT/E2EL vertical nudge reshuffled them) as the
rooflines animated — visually noisy.

Give each label a positional "affinity": add an opt-in `pinLineLabels`
prop (set by ReplayPanel, like `transitionDuration`/`niceAxes`). When
pinned, each label remembers a data-space x anchor the first time its
series is seen and, on every later frame, resolves that anchor to the
nearest current point on the line — so the label tracks the same spot as
the line moves instead of hopping. The TTFT/E2EL de-overlap nudge is
skipped while pinned so endpoint labels stay glued to their (smoothly
moving) endpoints. Anchors are pruned when a series disappears.

The static (non-pinned) chart is unchanged: the default branch of the
shared placeLabel helper keeps the exact greedy-place + hide-on-collision
behavior, preserving the no-overlap guarantee. Works for both official
and overlay (`?unofficialrun=`) line labels.

Extracts pointNearestX into its own module with unit tests.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: cquil11

packages/app/src/components/inference/replay/ReplayPanel.tsx

@@ -496,6 +496,7 @@ export default function ReplayPanel({
           chartDefinition={chartDefinition}
           transitionDuration={0}
           niceAxes={false}
+          pinLineLabels
         />
         <div
           className="absolute -translate-y-full pointer-events-none text-2xl font-bold tabular-nums opacity-85 leading-none pb-1"

packages/app/src/components/inference/types.ts

@@ -481,6 +481,15 @@ export interface ScatterGraphProps {
    * playback).
    */
   niceAxes?: boolean;
+  /**
+   * Pin each line label to a stable anchor along its roofline so it tracks the
+   * line smoothly instead of re-running the per-frame greedy placement (which
+   * makes labels teleport between candidate positions as the lines animate).
+   * Defaults to false. The replay panel passes true so labels keep a positional
+   * "affinity" across frames. Trades the static chart's per-frame de-overlap for
+   * positional stability — appropriate while the chart is animating.
+   */
+  pinLineLabels?: boolean;
 }
 /**
  * @file types.ts

packages/app/src/components/inference/ui/ScatterGraph.tsx

@@ -6,6 +6,7 @@ import React, { useCallback, useEffect, useMemo, useRef } from 'react';
 
 import { GRADIENT_NUDGE_EVENT } from '@/lib/nudges/registry';
 import { useInference } from '@/components/inference/InferenceContext';
+import { pointNearestX } from '@/components/inference/ui/line-label-anchor';
 import ChartLegend from '@/components/ui/chart-legend';
 import { useUnofficialRun } from '@/components/unofficial-run-provider';
 import { computeToggle } from '@/hooks/useTogglableSet';
@@ -122,6 +123,7 @@ const ScatterGraph = React.memo(
     overlayData,
     transitionDuration = 750,
     niceAxes = true,
+    pinLineLabels = false,
   }: ScatterGraphProps) => {
     const {
       activeHwTypes,
@@ -174,6 +176,11 @@ const ScatterGraph = React.memo(
     } = useUnofficialRun();
     const chartRef = useRef<D3ChartHandle>(null);
 
+    // Pinned line-label anchors (data-space x) keyed by line-label key. Persists
+    // across renders so each label keeps a stable spot along its line during
+    // replay animation. Only read/written when `pinLineLabels` is true.
+    const lineLabelAnchorRef = useRef<Map<string, number>>(new Map());
+
     // Effective active hw types for rendering — shared override when present, else global
     const effectiveOfficialHwTypes = localOfficialOverride ?? activeHwTypes;
 
@@ -946,55 +953,86 @@ const ScatterGraph = React.memo(
                 if (!prev || e.points.length > prev.points.length) bestByGroup.set(groupKey, e);
               }
 
-              // Sort entries by highest y-value first (top of chart) for priority
-              const sorted = [...bestByGroup.values()].toSorted((a, b) => {
-                const ay = yScale(a.points[0].y);
-                const by = yScale(b.points[0].y);
-                return ay - by; // smaller pixel y = higher on chart
-              });
-
-              for (const entry of sorted) {
-                const pts = entry.points;
+              // Place one label per series. When pinned (replay), reuse a stored
+              // data-space anchor so the label tracks the same spot along its line
+              // as it animates; otherwise re-run greedy placement each render and
+              // hide on collision (the static chart's de-overlap behavior).
+              const anchors = lineLabelAnchorRef.current;
+              const placeLabel = (
+                key: string,
+                hw: string,
+                label: string,
+                color: string,
+                pts: InferenceData[],
+              ) => {
                 const candidates = [
-                  pts[Math.min(1, pts.length - 1)], // top-left (near start)
+                  pts[Math.min(1, pts.length - 1)], // near start
                   pts[Math.floor(pts.length / 2)], // midpoint
                   pts[Math.max(0, Math.floor((pts.length * 2) / 3))], // right-third
                   pts.at(-1)!, // endpoint
                 ];
-
-                const label = lineLabelText(entry.hw, entry.precision, multiPrecision);
-                let foundPlacement = false;
+                if (pinLineLabels) {
+                  let anchorX = anchors.get(key);
+                  if (anchorX === undefined) {
+                    // First sighting: pick the first non-colliding candidate
+                    // (endpoint as fallback) and remember its data-x for later
+                    // frames so the label no longer hops between candidates.
+                    let chosen = candidates.at(-1)!;
+                    for (const pt of candidates) {
+                      if (!collides(xScale(pt.x), yScale(pt.y))) {
+                        chosen = pt;
+                        break;
+                      }
+                    }
+                    anchorX = chosen.x;
+                    anchors.set(key, anchorX);
+                  }
+                  const pt = pointNearestX(pts, anchorX);
+                  const px = xScale(pt.x);
+                  const py = yScale(pt.y);
+                  placed.push({ x: px, y: py });
+                  // Stay visible across frames — positional stability is the goal
+                  // during animation, so we don't hide on transient collisions.
+                  lineLabels.push({ key, hw, label, color, x: px, y: py, visible: true });
+                  return;
+                }
                 for (const pt of candidates) {
                   const px = xScale(pt.x);
                   const py = yScale(pt.y);
                   if (!collides(px, py)) {
-                    lineLabels.push({
-                      key: entry.key,
-                      hw: entry.hw,
-                      label,
-                      color: getCssColor(resolveColor(entry.hw)),
-                      x: px,
-                      y: py,
-                      visible: true,
-                    });
+                    lineLabels.push({ key, hw, label, color, x: px, y: py, visible: true });
                     placed.push({ x: px, y: py });
-                    foundPlacement = true;
-                    break;
+                    return;
                   }
                 }
-                // If all candidates collide, hide this label
-                if (!foundPlacement) {
-                  const pt = pts[0];
-                  lineLabels.push({
-                    key: entry.key,
-                    hw: entry.hw,
-                    label,
-                    color: getCssColor(resolveColor(entry.hw)),
-                    x: xScale(pt.x),
-                    y: yScale(pt.y),
-                    visible: false,
-                  });
-                }
+                // All candidates collide — hide this label.
+                const pt = pts[0];
+                lineLabels.push({
+                  key,
+                  hw,
+                  label,
+                  color,
+                  x: xScale(pt.x),
+                  y: yScale(pt.y),
+                  visible: false,
+                });
+              };
+
+              // Sort entries by highest y-value first (top of chart) for priority
+              const sorted = [...bestByGroup.values()].toSorted((a, b) => {
+                const ay = yScale(a.points[0].y);
+                const by = yScale(b.points[0].y);
+                return ay - by; // smaller pixel y = higher on chart
+              });
+
+              for (const entry of sorted) {
+                placeLabel(
+                  entry.key,
+                  entry.hw,
+                  lineLabelText(entry.hw, entry.precision, multiPrecision),
+                  getCssColor(resolveColor(entry.hw)),
+                  entry.points,
+                );
               }
 
               // Also add hidden entries for any curve that wasn't placed (so the
@@ -1039,49 +1077,22 @@ const ScatterGraph = React.memo(
                 .toSorted(([, a], [, b]) => yScale(a.points[0].y) - yScale(b.points[0].y));
 
               for (const [ovKey, group] of sortedOverlay) {
-                const labelKey = `overlay-${ovKey}`;
-                const pts = group.points;
-                const candidates = [
-                  pts[Math.min(1, pts.length - 1)],
-                  pts[Math.floor(pts.length / 2)],
-                  pts[Math.max(0, Math.floor((pts.length * 2) / 3))],
-                  pts.at(-1)!,
-                ];
-                const label = overlayLabelText(
-                  group.runIndex,
+                placeLabel(
+                  `overlay-${ovKey}`,
                   group.hwKey,
-                  group.points[0]?.precision ?? '',
+                  overlayLabelText(group.runIndex, group.hwKey, group.points[0]?.precision ?? ''),
+                  overlayRunColor(group.runIndex),
+                  group.points,
                 );
-                let placedOverlay = false;
-                for (const pt of candidates) {
-                  const px = xScale(pt.x);
-                  const py = yScale(pt.y);
-                  if (!collides(px, py)) {
-                    lineLabels.push({
-                      key: labelKey,
-                      hw: group.hwKey,
-                      label,
-                      color: overlayRunColor(group.runIndex),
-                      x: px,
-                      y: py,
-                      visible: true,
-                    });
-                    placed.push({ x: px, y: py });
-                    placedOverlay = true;
-                    break;
-                  }
-                }
-                if (!placedOverlay) {
-                  const pt = pts[0];
-                  lineLabels.push({
-                    key: labelKey,
-                    hw: group.hwKey,
-                    label,
-                    color: overlayRunColor(group.runIndex),
-                    x: xScale(pt.x),
-                    y: yScale(pt.y),
-                    visible: false,
-                  });
+              }
+
+              // Drop anchors for series no longer present so the map stays bounded
+              // and a re-appearing series gets a fresh, in-range anchor.
+              if (pinLineLabels) {
+                const live = new Set(lineLabels.map((l) => l.key));
+                // Deleting the current key during Map iteration is well-defined.
+                for (const k of anchors.keys()) {
+                  if (!live.has(k)) anchors.delete(k);
                 }
               }
             } else {
@@ -1127,8 +1138,12 @@ const ScatterGraph = React.memo(
                   visible: true,
                 });
               }
+              // Pinned (replay): keep labels exactly at their endpoints, which
+              // already move smoothly with the line. The vertical de-overlap
+              // nudge below reshuffles positions as endpoints shift frame-to-
+              // frame, so skip it to preserve positional affinity.
               const visible = lineLabels.filter((l) => l.visible);
-              if (visible.length > 1) {
+              if (visible.length > 1 && !pinLineLabels) {
                 const yRange = yScale.range();
                 const top = Math.min(yRange[0], yRange[1]) + LABEL_H;
                 const bottom = Math.max(yRange[0], yRange[1]) - LABEL_H;
@@ -1793,6 +1808,7 @@ const ScatterGraph = React.memo(
       allPointLabelsByKey,
       showGradientLabels,
       showLineLabels,
+      pinLineLabels,
       showSpeedOverlay,
       showMinecraftOverlay,
       gradientColorByPoint,

packages/app/src/components/inference/ui/line-label-anchor.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+
+import type { InferenceData } from '@/components/inference/types';
+
+import { pointNearestX } from './line-label-anchor';
+
+// Minimal InferenceData stand-ins — pointNearestX only reads `x`.
+const pt = (x: number, y: number): InferenceData => ({ x, y }) as InferenceData;
+
+describe('pointNearestX', () => {
+  it('returns the point whose x is closest to the target', () => {
+    const pts = [pt(0, 10), pt(5, 20), pt(10, 30)];
+    expect(pointNearestX(pts, 4).x).toBe(5);
+    expect(pointNearestX(pts, 1).x).toBe(0);
+    expect(pointNearestX(pts, 9).x).toBe(10);
+  });
+
+  it('keeps a stable anchor as the line shifts between frames', () => {
+    // An anchor stored at x=5 should resolve to whichever current point sits
+    // nearest x=5 — this is what keeps a replay label glued to its line.
+    const anchorX = 5;
+    const frameA = [pt(0, 10), pt(5, 22), pt(10, 30)];
+    const frameB = [pt(0, 12), pt(5, 18), pt(10, 26)];
+    expect(pointNearestX(frameA, anchorX)).toMatchObject({ x: 5, y: 22 });
+    expect(pointNearestX(frameB, anchorX)).toMatchObject({ x: 5, y: 18 });
+  });
+
+  it('clamps to the nearest endpoint when the anchor is out of range', () => {
+    const pts = [pt(2, 10), pt(4, 20), pt(6, 30)];
+    expect(pointNearestX(pts, -100).x).toBe(2);
+    expect(pointNearestX(pts, 100).x).toBe(6);
+  });
+
+  it('handles a single-point line', () => {
+    const pts = [pt(3, 7)];
+    expect(pointNearestX(pts, 999)).toMatchObject({ x: 3, y: 7 });
+  });
+});

packages/app/src/components/inference/ui/line-label-anchor.ts

@@ -0,0 +1,25 @@
+import type { InferenceData } from '@/components/inference/types';
+
+/**
+ * Find the point on a polyline whose x is closest to a target data-space x.
+ *
+ * Used by the pinned (replay) line-label path: an anchor is stored in data
+ * space so a label tracks the same spot along its line as the line animates,
+ * instead of jumping between discrete candidate positions on every frame. As
+ * the polyline's points shift between frames, resolving the anchor to the
+ * nearest current point keeps the label glued to its line.
+ *
+ * `pts` is assumed non-empty (callers guard with `pts.length >= 2`).
+ */
+export const pointNearestX = (pts: InferenceData[], targetX: number): InferenceData => {
+  let best = pts[0];
+  let bestDist = Math.abs(pts[0].x - targetX);
+  for (let i = 1; i < pts.length; i++) {
+    const dist = Math.abs(pts[i].x - targetX);
+    if (dist < bestDist) {
+      bestDist = dist;
+      best = pts[i];
+    }
+  }
+  return best;
+};