bunnyquery 1.8.15 → 1.8.16

package/dist/engine.d.mts

@@ -1961,6 +1961,17 @@ interface ScrollAnchor {
     settleReturn: () => boolean;
     /** A return is armed: its position, not the host's, decides scrollTop. */
     isReturning: () => boolean;
+    /**
+     * The reader is driving. Retire any armed return, at once.
+     *
+     * Call from the raw gesture handlers (wheel, touchstart, touchmove, keydown),
+     * which fire synchronously on a real user action and never for a programmatic
+     * scroll. Waiting for the scroll EVENT is not good enough: a background refresh
+     * can settle in between, and a settle with a return still armed puts the reader
+     * back where they were before they left, which lands as "I touched the scroll
+     * and it threw me somewhere else".
+     */
+    release: () => void;
     /** Pin to the bottom, instantly, recording the write. The ONLY way to pin. */
     pinBottom: () => void;
     /** The box is not being painted (hidden tab). Shared so hosts agree. */

package/dist/engine.d.ts

@@ -1961,6 +1961,17 @@ interface ScrollAnchor {
     settleReturn: () => boolean;
     /** A return is armed: its position, not the host's, decides scrollTop. */
     isReturning: () => boolean;
+    /**
+     * The reader is driving. Retire any armed return, at once.
+     *
+     * Call from the raw gesture handlers (wheel, touchstart, touchmove, keydown),
+     * which fire synchronously on a real user action and never for a programmatic
+     * scroll. Waiting for the scroll EVENT is not good enough: a background refresh
+     * can settle in between, and a settle with a return still armed puts the reader
+     * back where they were before they left, which lands as "I touched the scroll
+     * and it threw me somewhere else".
+     */
+    release: () => void;
     /** Pin to the bottom, instantly, recording the write. The ONLY way to pin. */
     pinBottom: () => void;
     /** The box is not being painted (hidden tab). Shared so hosts agree. */

package/dist/engine.mjs

@@ -2580,6 +2580,7 @@ var ROW_KEY_ATTR = "data-row-key";
 var ROW_POS_ATTR = "data-row-pos";
 var MAX_ALTS = 2;
 var ALT_SCAN_LIMIT = 64;
+var MAX_RETURN_SETTLES = 3;
 var UNKNOWN_ROW_POS = "\0?";
 function createScrollAnchor(options) {
   var held = null;
@@ -2667,6 +2668,7 @@ function createScrollAnchor(options) {
   var parked = null;
   var parkedStuck = false;
   var returning = false;
+  var returnBudget = 0;
   var wroteTop = -1;
   var restoreExact = true;
   var restorePinned = false;
@@ -2762,17 +2764,13 @@ function createScrollAnchor(options) {
   }
   function remember() {
     var b0 = options.getBox();
-    if (returning && b0 && b0.scrollTop !== wroteTop) {
-      parked = null;
-      parkedStuck = false;
-      returning = false;
-    }
+    if (returning && b0 && b0.scrollTop !== wroteTop) release();
     if (frozen()) return;
     held = capture();
   }
   function hold() {
     if (frozen()) return;
-    if (sawFrozen || returning) {
+    if (sawFrozen) {
       settleReturn();
       return;
     }
@@ -2815,6 +2813,13 @@ function createScrollAnchor(options) {
     parked = capture();
     parkedStuck = !!options.isStuck();
     returning = true;
+    returnBudget = MAX_RETURN_SETTLES;
+  }
+  function release() {
+    parked = null;
+    parkedStuck = false;
+    returning = false;
+    returnBudget = 0;
   }
   function pinBottom() {
     var box = options.getBox();
@@ -2824,7 +2829,16 @@ function createScrollAnchor(options) {
   }
   function settleReturn() {
     if (frozen()) return false;
+    var wasFrozen = sawFrozen;
     sawFrozen = false;
+    if (!returning && !wasFrozen) return false;
+    if (returning) {
+      if (returnBudget <= 0) {
+        release();
+        return false;
+      }
+      returnBudget--;
+    }
     if (parkedStuck) {
       pinBottom();
       return true;
@@ -2834,7 +2848,12 @@ function createScrollAnchor(options) {
     restorePinned = false;
     restore(target, true);
     parked = !restorePinned || !restoreExact ? target : null;
-    returning = !!parked;
+    returning = !!parked && returnBudget > 0;
+    if (!returning) {
+      parked = null;
+      parkedStuck = false;
+      returnBudget = 0;
+    }
     return false;
   }
   function isReturning() {
@@ -2860,9 +2879,7 @@ function createScrollAnchor(options) {
   }
   function forget() {
     held = null;
-    parked = null;
-    parkedStuck = false;
-    returning = false;
+    release();
   }
   return {
     capture,
@@ -2873,6 +2890,7 @@ function createScrollAnchor(options) {
     park,
     settleReturn,
     isReturning,
+    release,
     pinBottom,
     isFrozen: frozen,
     thaw,