Lock hunk-bar viewport indicator to cursor with optimistic ghost paint

geevensingh · Copilot · geevensingh · commit 9130979b14d9 · 2026-05-19T12:23:44.000-07:00
The viewport band's painted position was sourced from VM.Viewport,
which only updates after the editor finishes scrolling and lays
itself out. On a fast band drag the chain
    MouseMove -&gt; RequestScrollByVerticalFraction
              -&gt; editor.ScrollToVerticalOffset
              -&gt; editor layout pass
              -&gt; ScrollChanged -&gt; Viewport update
              -&gt; PropertyChanged -&gt; InvalidateVisual -&gt; paint
takes more than one render tick, so the band visibly trailed the
cursor by several frames on large files.

Decouple the bar's paint from the editor's scroll: on every MouseMove
during a drag, set a _dragGhostBandTop in bar pixels (clamped to the
bar's drag range) and call InvalidateVisual right away. OnRender
translates the computed viewport band so its top sits at the ghost,
so the band paints at the cursor on the very next render tick. The
editor still scrolls via the normal path; once it catches up the
translation collapses to zero. ResetInteraction clears the ghost so
the band snaps back to the editor's truth after the drag ends.

Add HunkOverviewBarGeometry.TranslateBand + GetBandHeight as the
pure-geometry primitives the ghost path needs, with unit tests for
both. Public surface of the geometry helper grows by two static
methods; no behaviour change for non-drag paint or other callers.

AI-Local-Session: b53d5fe5-38cc-41dd-b987-3def5ef3f0d3
AI-Cloud-Session: 744dd836-01e5-48af-91db-daa8241a01d7
Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -32,7 +32,11 @@ body. Keep section headings exact and write notes in Markdown.
   that a press landing on a hunk marker which overlaps the viewport
   band can still promote to a drag if the user moves the mouse past
   the system drag threshold — previously, the jump fired immediately
-  and stole the drag.
+  and stole the drag. The viewport indicator paints at the cursor's
+  position on every mouse-move frame instead of waiting for the
+  editor's scroll + layout pass to round-trip — keeps the indicator
+  truly stuck to the cursor even on large files where the editor
+  scroll can't quite keep up at fast drag speeds.
 - Language-aware syntax highlighting for TypeScript (`.ts`, `.tsx`),
   YAML (`.yaml`, `.yml`), Go (`.go`), Rust (`.rs`), Ruby (`.rb`),
   Bash / shell (`.sh`, `.bash`, `.zsh`), and TOML (`.toml`). Combined
diff --git a/DiffViewer.Tests/Rendering/HunkOverviewBarGeometryTests.cs b/DiffViewer.Tests/Rendering/HunkOverviewBarGeometryTests.cs
@@ -624,4 +624,95 @@ public void GetBandTopY_SingleSideBand_UsesThatRectsTop()
         // Right rect only: y in [38, 120]. Top = 38.
         HunkOverviewBarGeometry.GetBandTopY(band).Should().BeApproximately(38, 0.001);
     }
+
+    // ---------- GetBandHeight ----------
+
+    [Fact]
+    public void GetBandHeight_SymmetricBand_ReturnsRectHeight()
+    {
+        var state = new DiffViewer.Models.ViewportState(10, 30, 10, 30);
+        var band = HunkOverviewBarGeometry.ComputeViewport(
+            state, 100, 100, BarWidth, 200, ColumnWidth)!;
+        // Both rects: y in [18, 60] → height = 42.
+        HunkOverviewBarGeometry.GetBandHeight(band).Should().BeApproximately(42, 0.001);
+    }
+
+    [Fact]
+    public void GetBandHeight_AsymmetricBand_UsesLargerHeight()
+    {
+        // Left: lines 10..30 of 100 → [18, 60], h=42.
+        // Right: lines 5..10 of 50 → [16, 40], h=24.
+        // Larger height = 42.
+        var state = new DiffViewer.Models.ViewportState(10, 30, 5, 10);
+        var band = HunkOverviewBarGeometry.ComputeViewport(
+            state, 100, 50, BarWidth, 200, ColumnWidth)!;
+        HunkOverviewBarGeometry.GetBandHeight(band).Should().BeApproximately(42, 0.001);
+    }
+
+    [Fact]
+    public void GetBandHeight_SingleSideBand_UsesThatRectsHeight()
+    {
+        var state = new DiffViewer.Models.ViewportState(0, 0, 20, 60);
+        var band = HunkOverviewBarGeometry.ComputeViewport(
+            state, 100, 100, BarWidth, 200, ColumnWidth)!;
+        // Right rect only: y in [38, 120] → height = 82.
+        HunkOverviewBarGeometry.GetBandHeight(band).Should().BeApproximately(82, 0.001);
+    }
+
+    // ---------- TranslateBand ----------
+
+    [Fact]
+    public void TranslateBand_PositiveDy_ShiftsBothRectsDown()
+    {
+        var band = new HunkOverviewBarGeometry.ViewportBand(
+            new Rect(0, 10, 10, 20),
+            new Rect(22, 10, 10, 20));
+        var moved = HunkOverviewBarGeometry.TranslateBand(band, 15);
+        moved.LeftRect!.Value.Should().Be(new Rect(0, 25, 10, 20));
+        moved.RightRect!.Value.Should().Be(new Rect(22, 25, 10, 20));
+    }
+
+    [Fact]
+    public void TranslateBand_NegativeDy_ShiftsBothRectsUp()
+    {
+        var band = new HunkOverviewBarGeometry.ViewportBand(
+            new Rect(0, 30, 10, 20),
+            new Rect(22, 30, 10, 20));
+        var moved = HunkOverviewBarGeometry.TranslateBand(band, -12);
+        moved.LeftRect!.Value.Should().Be(new Rect(0, 18, 10, 20));
+        moved.RightRect!.Value.Should().Be(new Rect(22, 18, 10, 20));
+    }
+
+    [Fact]
+    public void TranslateBand_ZeroDy_ReturnsSameInstance()
+    {
+        // Fast-path: avoids allocating a new ViewportBand for no-op
+        // translations (common when the editor has caught up exactly).
+        var band = new HunkOverviewBarGeometry.ViewportBand(
+            new Rect(0, 10, 10, 20),
+            new Rect(22, 10, 10, 20));
+        HunkOverviewBarGeometry.TranslateBand(band, 0).Should().BeSameAs(band);
+    }
+
+    [Fact]
+    public void TranslateBand_LeftOnlyBand_LeavesRightNull()
+    {
+        var band = new HunkOverviewBarGeometry.ViewportBand(
+            new Rect(0, 10, 10, 20),
+            null);
+        var moved = HunkOverviewBarGeometry.TranslateBand(band, 5);
+        moved.LeftRect!.Value.Should().Be(new Rect(0, 15, 10, 20));
+        moved.RightRect.Should().BeNull();
+    }
+
+    [Fact]
+    public void TranslateBand_RightOnlyBand_LeavesLeftNull()
+    {
+        var band = new HunkOverviewBarGeometry.ViewportBand(
+            null,
+            new Rect(22, 10, 10, 20));
+        var moved = HunkOverviewBarGeometry.TranslateBand(band, 5);
+        moved.LeftRect.Should().BeNull();
+        moved.RightRect!.Value.Should().Be(new Rect(22, 15, 10, 20));
+    }
 }
diff --git a/DiffViewer/Rendering/HunkOverviewBar.cs b/DiffViewer/Rendering/HunkOverviewBar.cs
@@ -93,6 +93,20 @@ private enum BarInteractionState
     /// </summary>
     private double _bandDragOffsetFromTop;
 
+    /// <summary>
+    /// Optimistic band-top Y while a drag is active, in bar coords.
+    /// Set on every MouseMove from the cursor position; cleared on drag
+    /// end. When set, <see cref="OnRender"/> translates the computed
+    /// viewport band so its top sits here — decouples the band's
+    /// painted position from the editor's actual scroll, which trails
+    /// MouseMove by a layout pass and can fall many frames behind
+    /// under fast drag. The editor scroll still catches up via the
+    /// normal <see cref="DiffPaneViewModel.RequestScrollByVerticalFraction"/>
+    /// path; the ghost just makes the bar's visual feedback frame-
+    /// instant so the band feels truly stuck to the cursor.
+    /// </summary>
+    private double? _dragGhostBandTop;
+
     public HunkOverviewBar()
     {
         Cursor = Cursors.Hand;
@@ -231,6 +245,18 @@ protected override void OnRender(DrawingContext dc)
             _vm.Viewport, leftTotal, rightTotal, ActualWidth, ActualHeight, ColumnWidth);
         if (viewportBand is not null)
         {
+            // Optimistic translation during drag — see _dragGhostBandTop
+            // for why. Outside a drag, the ghost is null and the band
+            // paints at the editor's actual viewport position.
+            if (_dragGhostBandTop is double ghostTop)
+            {
+                double actualTop = HunkOverviewBarGeometry.GetBandTopY(viewportBand);
+                double dy = ghostTop - actualTop;
+                if (dy != 0)
+                {
+                    viewportBand = HunkOverviewBarGeometry.TranslateBand(viewportBand, dy);
+                }
+            }
             DrawViewport(dc, viewportBand);
         }
     }
@@ -393,6 +419,15 @@ private void ResetInteraction()
         _pendingHunkIndex = -1;
         _bandWasUnderClick = false;
         if (IsMouseCaptured) ReleaseMouseCapture();
+        if (_dragGhostBandTop is not null)
+        {
+            // Clear the ghost first, then invalidate so the next paint
+            // shows the band where the editor actually settled. If the
+            // editor hasn't quite caught up yet, the band may snap by a
+            // pixel or two — fine, drag is over.
+            _dragGhostBandTop = null;
+            InvalidateVisual();
+        }
     }
 
     /// <summary>
@@ -504,10 +539,50 @@ private void EmitDragScroll(Point p)
     {
         if (_vm is null) return;
         double targetBandTopY = p.Y - _bandDragOffsetFromTop;
+
+        // Paint the band at the cursor on the very next render tick,
+        // without waiting for the editor's scroll → layout → ScrollChanged
+        // → ViewportState → PropertyChanged round-trip. Without this
+        // decoupling, the band visibly trails the cursor by however long
+        // the editor takes to settle its layout pass; on large files
+        // that's enough to drop the band several frames behind a fast
+        // drag, which reads as the band "sticking" to lower-than-cursor
+        // positions. The editor still catches up via the normal scroll
+        // path below; the ghost just makes the bar's visual frame-instant.
+        _dragGhostBandTop = ClampGhostTop(targetBandTopY);
+        InvalidateVisual();
+
         double fraction = ActualHeight <= 0 ? 0 : targetBandTopY / ActualHeight;
         _vm.RequestScrollByVerticalFraction(fraction);
     }
 
+    /// <summary>
+    /// Clamp the ghost band's top to <c>[0, ActualHeight − bandHeight]</c>
+    /// so it can't be dragged off either end of the bar. Band height is
+    /// estimated from the current viewport band; if no band exists
+    /// (shouldn't happen mid-drag — we wouldn't have started one) we
+    /// fall back to clamping against the full bar height, which is
+    /// harmlessly loose.
+    /// </summary>
+    private double ClampGhostTop(double top)
+    {
+        double maxTop = ActualHeight;
+        if (_vm is not null)
+        {
+            int leftTotal = Math.Max(1, _vm.LeftDocument.LineCount);
+            int rightTotal = Math.Max(1, _vm.RightDocument.LineCount);
+            var band = HunkOverviewBarGeometry.ComputeViewport(
+                _vm.Viewport, leftTotal, rightTotal, ActualWidth, ActualHeight, ColumnWidth);
+            if (band is not null)
+            {
+                maxTop = Math.Max(0, ActualHeight - HunkOverviewBarGeometry.GetBandHeight(band));
+            }
+        }
+        if (top < 0) top = 0;
+        if (top > maxTop) top = maxTop;
+        return top;
+    }
+
     private IReadOnlyList<HunkOverviewBarGeometry.HunkBarLayout> ComputeLayouts()
     {
         if (_vm is null) return Array.Empty<HunkOverviewBarGeometry.HunkBarLayout>();
diff --git a/DiffViewer/Rendering/HunkOverviewBarGeometry.cs b/DiffViewer/Rendering/HunkOverviewBarGeometry.cs
@@ -305,6 +305,43 @@ public static double GetBandTopY(ViewportBand band)
         return top == double.MaxValue ? 0 : top;
     }
 
+    /// <summary>
+    /// Vertical height of the viewport band, in bar coordinates — the
+    /// distance from <see cref="GetBandTopY"/> to the lower of the two
+    /// rects' bottoms. Used during sticky-thumb drag to clamp the
+    /// optimistic ghost band so it can't be dragged off the ends of the
+    /// bar. For mixed bands the two rects have the same height in
+    /// practice (both come from the same viewport line range) but we
+    /// take the max to be safe against off-by-one rounding.
+    /// Returns 0 for empty bands (matches <see cref="GetBandTopY"/>).
+    /// </summary>
+    public static double GetBandHeight(ViewportBand band)
+    {
+        double h = 0;
+        if (band.LeftRect is Rect L) h = Math.Max(h, L.Height);
+        if (band.RightRect is Rect R) h = Math.Max(h, R.Height);
+        return h;
+    }
+
+    /// <summary>
+    /// Return a copy of <paramref name="band"/> with each rect's Y
+    /// translated by <paramref name="dy"/>. Used during drag to paint
+    /// an "optimistic" band at the cursor position without waiting for
+    /// the editor's scroll → ScrollChanged → ViewportState round-trip;
+    /// the actual editor scroll catches up at its own pace.
+    /// </summary>
+    public static ViewportBand TranslateBand(ViewportBand band, double dy)
+    {
+        if (dy == 0) return band;
+        Rect? left = band.LeftRect is Rect L
+            ? new Rect(L.X, L.Y + dy, L.Width, L.Height)
+            : (Rect?)null;
+        Rect? right = band.RightRect is Rect R
+            ? new Rect(R.X, R.Y + dy, R.Width, R.Height)
+            : (Rect?)null;
+        return new ViewportBand(left, right);
+    }
+
     /// <summary>
     /// Classifies a hunk's content for color selection — pure-add (all
     /// inserted lines), pure-delete (all removed lines), or mixed.
