bunnyquery 1.8.14 → 1.8.16

package/dist/engine.d.mts

@@ -1618,6 +1618,20 @@ interface ChatHost {
      *  that cannot scroll has no way to reach page 2 (see viewport_fill). Only
      *  the view can measure that, which is why the engine merely announces it. */
     onHistoryLoaded?(fetchMore: boolean, token: number): void;
+    /**
+     * A list refresh just changed heights: put the reader back where they were.
+     *
+     * Called at BOTH moments a first-page refresh moves things — the surface page
+     * landing, and the deferred background-indexing batch merging on top of it a
+     * round trip later — because leaving a wrong position on screen between the two
+     * is what reads as "the scroll jumped, then travelled somewhere else".
+     *
+     * The view owns the decision (it is the only side that can measure): pinned to
+     * the bottom means the bottom AFTER the batch merged, anywhere else means the
+     * exact line the reader was on. Falls back to scrollToBottomIfSticky when a host
+     * does not implement it, which is the old behaviour.
+     */
+    settleScroll?(): void;
     cancelRequest(opts: {
         url: string;
         method: string;
@@ -1874,6 +1888,23 @@ interface RowAnchor {
      * key. Never trusted without re-checking that it is still in the box.
      */
     el: AnchorRowEl | null;
+    /**
+     * The next few anchorable rows below the primary, each with its own offset.
+     *
+     * The primary row does not always survive: a refresh can drop it, a collapsed
+     * indexing row can be re-identified, an expanded group can fold. Without a
+     * fallback the only thing left is lost(), which guesses from the list's total
+     * growth — and total growth includes everything added BELOW the reader, so a
+     * merge that lands rows on both sides of them over-pays. A second row that is
+     * still there beats any guess, and collecting them costs nothing: capture is
+     * already walking these rows.
+     */
+    alts?: Array<{
+        key: string;
+        top: number;
+        pos: string | null;
+        el: AnchorRowEl;
+    }>;
 }
 interface ScrollAnchorOptions {
     /** The scrolling message box, or null when it is not mounted. */
@@ -1883,6 +1914,21 @@ interface ScrollAnchorOptions {
      * scrollToBottom* paths own the position, so every method here no-ops.
      */
     isStuck: () => boolean;
+    /**
+     * The reader cannot see this box right now (the tab is hidden), so FREEZE:
+     * remember where they were and refuse to move them.
+     *
+     * A hidden tab still runs everything that mutates the list — a resumed poll, a
+     * head refresh and its deferred background batch, a settling request — and each
+     * of those would otherwise write scrollTop against a layout nobody is looking at
+     * and re-stamp the remembered position on the way through. The reader then comes
+     * back to wherever the last of those writes happened to land, which is the
+     * "somehow placed in the middle" they see, and only the NEXT correction puts
+     * them right. So while frozen, reads still happen but nothing writes and nothing
+     * re-stamps: the anchor holds the last position the reader actually had, and one
+     * hold() on return puts them back on it.
+     */
+    isFrozen?: () => boolean;
     /**
      * Fall back to the raw scrollTop when the anchored row cannot be found again.
      *
@@ -1905,6 +1951,33 @@ interface ScrollAnchor {
     remember: () => void;
     /** Put the remembered place back, if it is still the reader's own. */
     hold: () => void;
+    /** The reader is going away: park the exact place they are leaving. */
+    park: () => void;
+    /**
+     * They are back. Puts them on the parked place, and STAYS ARMED until it has
+     * actually landed. Returns true when the host must pin to the bottom instead
+     * (the reader left pinned), which only the host can do meaningfully.
+     */
+    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. */
+    isFrozen: () => boolean;
+    /** Deprecated alias of settleReturn, kept so a stale dist does not break. */
+    thaw: () => void;
     /** Absorb one element's own resize. See below. */
     absorb: (el: AnchorGrowableEl | null | undefined) => void;
     /** Drop the remembered place (chat switch, unmount). */

package/dist/engine.d.ts

@@ -1618,6 +1618,20 @@ interface ChatHost {
      *  that cannot scroll has no way to reach page 2 (see viewport_fill). Only
      *  the view can measure that, which is why the engine merely announces it. */
     onHistoryLoaded?(fetchMore: boolean, token: number): void;
+    /**
+     * A list refresh just changed heights: put the reader back where they were.
+     *
+     * Called at BOTH moments a first-page refresh moves things — the surface page
+     * landing, and the deferred background-indexing batch merging on top of it a
+     * round trip later — because leaving a wrong position on screen between the two
+     * is what reads as "the scroll jumped, then travelled somewhere else".
+     *
+     * The view owns the decision (it is the only side that can measure): pinned to
+     * the bottom means the bottom AFTER the batch merged, anywhere else means the
+     * exact line the reader was on. Falls back to scrollToBottomIfSticky when a host
+     * does not implement it, which is the old behaviour.
+     */
+    settleScroll?(): void;
     cancelRequest(opts: {
         url: string;
         method: string;
@@ -1874,6 +1888,23 @@ interface RowAnchor {
      * key. Never trusted without re-checking that it is still in the box.
      */
     el: AnchorRowEl | null;
+    /**
+     * The next few anchorable rows below the primary, each with its own offset.
+     *
+     * The primary row does not always survive: a refresh can drop it, a collapsed
+     * indexing row can be re-identified, an expanded group can fold. Without a
+     * fallback the only thing left is lost(), which guesses from the list's total
+     * growth — and total growth includes everything added BELOW the reader, so a
+     * merge that lands rows on both sides of them over-pays. A second row that is
+     * still there beats any guess, and collecting them costs nothing: capture is
+     * already walking these rows.
+     */
+    alts?: Array<{
+        key: string;
+        top: number;
+        pos: string | null;
+        el: AnchorRowEl;
+    }>;
 }
 interface ScrollAnchorOptions {
     /** The scrolling message box, or null when it is not mounted. */
@@ -1883,6 +1914,21 @@ interface ScrollAnchorOptions {
      * scrollToBottom* paths own the position, so every method here no-ops.
      */
     isStuck: () => boolean;
+    /**
+     * The reader cannot see this box right now (the tab is hidden), so FREEZE:
+     * remember where they were and refuse to move them.
+     *
+     * A hidden tab still runs everything that mutates the list — a resumed poll, a
+     * head refresh and its deferred background batch, a settling request — and each
+     * of those would otherwise write scrollTop against a layout nobody is looking at
+     * and re-stamp the remembered position on the way through. The reader then comes
+     * back to wherever the last of those writes happened to land, which is the
+     * "somehow placed in the middle" they see, and only the NEXT correction puts
+     * them right. So while frozen, reads still happen but nothing writes and nothing
+     * re-stamps: the anchor holds the last position the reader actually had, and one
+     * hold() on return puts them back on it.
+     */
+    isFrozen?: () => boolean;
     /**
      * Fall back to the raw scrollTop when the anchored row cannot be found again.
      *
@@ -1905,6 +1951,33 @@ interface ScrollAnchor {
     remember: () => void;
     /** Put the remembered place back, if it is still the reader's own. */
     hold: () => void;
+    /** The reader is going away: park the exact place they are leaving. */
+    park: () => void;
+    /**
+     * They are back. Puts them on the parked place, and STAYS ARMED until it has
+     * actually landed. Returns true when the host must pin to the bottom instead
+     * (the reader left pinned), which only the host can do meaningfully.
+     */
+    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. */
+    isFrozen: () => boolean;
+    /** Deprecated alias of settleReturn, kept so a stale dist does not break. */
+    thaw: () => void;
     /** Absorb one element's own resize. See below. */
     absorb: (el: AnchorGrowableEl | null | undefined) => void;
     /** Drop the remembered place (chat switch, unmount). */

package/dist/engine.mjs

@@ -2578,6 +2578,9 @@ function shouldRescueInFlightMessage(m, ctx) {
 // src/engine/scroll_anchor.ts
 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;
@@ -2588,6 +2591,7 @@ function createScrollAnchor(options) {
     var boxTop = box.getBoundingClientRect().top;
     var kids = box.children;
     var fallback = null;
+    var fallbackAt = -1;
     for (var i = 0; i < kids.length; i++) {
       var el = kids[i];
       if (!el || typeof el.getAttribute !== "function") continue;
@@ -2606,10 +2610,20 @@ function createScrollAnchor(options) {
         scrollHeight: box.scrollHeight,
         el
       };
-      if (rawPos === null) return cand;
-      if (!fallback) fallback = cand;
+      if (rawPos === null) {
+        cand.alts = collectAlts(box, boxTop, i + 1);
+        return cand;
+      }
+      if (!fallback) {
+        fallback = cand;
+        fallbackAt = i;
+      }
+    }
+    if (fallback) {
+      fallback.alts = collectAlts(box, boxTop, fallbackAt + 1, true);
+      return fallback;
     }
-    return fallback || {
+    return {
       key: null,
       top: 0,
       pos: null,
@@ -2618,6 +2632,26 @@ function createScrollAnchor(options) {
       el: null
     };
   }
+  function collectAlts(box, boxTop, from, ordinaryOnly) {
+    var out = [];
+    var kids = box.children;
+    var stop = Math.min(kids.length, from + ALT_SCAN_LIMIT);
+    for (var i = from; i < stop && out.length < MAX_ALTS; i++) {
+      var el = kids[i];
+      if (!el || typeof el.getAttribute !== "function") continue;
+      var key = el.getAttribute(ROW_KEY_ATTR);
+      if (!key) continue;
+      var rawPos = el.getAttribute(ROW_POS_ATTR);
+      if (ordinaryOnly && rawPos !== null) continue;
+      out.push({
+        key,
+        top: el.getBoundingClientRect().top - boxTop,
+        pos: rawPos === null ? null : rawPos || UNKNOWN_ROW_POS,
+        el
+      });
+    }
+    return out.length ? out : void 0;
+  }
   function findRow(box, anchor) {
     var el = anchor.el;
     if (el && el.parentNode === box) return el;
@@ -2630,31 +2664,80 @@ function createScrollAnchor(options) {
     }
     return null;
   }
-  function restore(anchor) {
+  var sawFrozen = false;
+  var parked = null;
+  var parkedStuck = false;
+  var returning = false;
+  var returnBudget = 0;
+  var wroteTop = -1;
+  var restoreExact = true;
+  var restorePinned = false;
+  function frozen() {
+    var f = !!options.isFrozen && options.isFrozen();
+    if (f) sawFrozen = true;
+    return f;
+  }
+  function restore(anchor, unbounded) {
+    if (frozen()) return;
     var box = options.getBox();
     if (!box || !anchor || options.isStuck()) return;
     var el = findRow(box, anchor);
     if (el) {
       var livePos = el.getAttribute(ROW_POS_ATTR) || UNKNOWN_ROW_POS;
-      if (anchor.pos !== null && anchor.pos !== UNKNOWN_ROW_POS && livePos !== UNKNOWN_ROW_POS && livePos !== anchor.pos) {
-        lost(box, anchor);
-        return;
-      }
+      if (anchor.pos !== null && anchor.pos !== UNKNOWN_ROW_POS && livePos !== UNKNOWN_ROW_POS && livePos !== anchor.pos) el = null;
+    }
+    if (el) {
       var boxTop = box.getBoundingClientRect().top;
       var delta = el.getBoundingClientRect().top - boxTop - anchor.top;
       var slack = Math.abs(box.scrollHeight - anchor.scrollHeight) + box.clientHeight;
-      if (delta > slack || delta < -slack) {
+      if (!unbounded && (delta > slack || delta < -slack)) {
         lost(box, anchor);
         return;
       }
+      var want = box.scrollTop + delta;
       if (delta >= 1 || delta <= -1) box.scrollTop += delta;
+      wroteTop = box.scrollTop;
+      restorePinned = true;
+      restoreExact = box.scrollTop >= want - 1 && box.scrollTop <= want + 1;
       held = {
         key: anchor.key,
         top: anchor.top,
         pos: anchor.pos,
         scrollTop: box.scrollTop,
         scrollHeight: box.scrollHeight,
-        el
+        el,
+        // Carried, not dropped: one successful restore used to disarm the
+        // standbys for every later hold.
+        alts: anchor.alts
+      };
+      return;
+    }
+    var alts = anchor.alts;
+    for (var ai = 0; alts && ai < alts.length; ai++) {
+      var alt = alts[ai];
+      var ael = findRow(box, { key: alt.key, top: alt.top, pos: alt.pos, scrollTop: anchor.scrollTop, scrollHeight: anchor.scrollHeight, el: alt.el });
+      if (!ael) continue;
+      if (alt.pos !== null && alt.pos !== UNKNOWN_ROW_POS) {
+        var altLive = ael.getAttribute(ROW_POS_ATTR) || UNKNOWN_ROW_POS;
+        if (altLive !== UNKNOWN_ROW_POS && altLive !== alt.pos) continue;
+      }
+      var aboxTop = box.getBoundingClientRect().top;
+      var adelta = ael.getBoundingClientRect().top - aboxTop - alt.top;
+      var aslack = Math.abs(box.scrollHeight - anchor.scrollHeight) + box.clientHeight;
+      if (!unbounded && (adelta > aslack || adelta < -aslack)) continue;
+      var awant = box.scrollTop + adelta;
+      if (adelta >= 1 || adelta <= -1) box.scrollTop += adelta;
+      wroteTop = box.scrollTop;
+      restorePinned = true;
+      restoreExact = box.scrollTop >= awant - 1 && box.scrollTop <= awant + 1;
+      held = {
+        key: alt.key,
+        top: alt.top,
+        pos: alt.pos,
+        scrollTop: box.scrollTop,
+        scrollHeight: box.scrollHeight,
+        el: ael,
+        alts: alts.slice(ai + 1)
       };
       return;
     }
@@ -2665,9 +2748,13 @@ function createScrollAnchor(options) {
     var grew = box.scrollHeight - anchor.scrollHeight;
     if (grew > 0) {
       box.scrollTop = anchor.scrollTop + grew;
+      wroteTop = box.scrollTop;
       return;
     }
-    if (options.rawFallback) box.scrollTop = anchor.scrollTop;
+    if (options.rawFallback) {
+      box.scrollTop = anchor.scrollTop;
+      wroteTop = box.scrollTop;
+    }
   }
   function preserve(mutate) {
     var anchor = capture();
@@ -2676,9 +2763,17 @@ function createScrollAnchor(options) {
     return result;
   }
   function remember() {
+    var b0 = options.getBox();
+    if (returning && b0 && b0.scrollTop !== wroteTop) release();
+    if (frozen()) return;
     held = capture();
   }
   function hold() {
+    if (frozen()) return;
+    if (sawFrozen) {
+      settleReturn();
+      return;
+    }
     var box = options.getBox();
     if (!box || options.isStuck()) {
       held = null;
@@ -2705,12 +2800,86 @@ function createScrollAnchor(options) {
     if (prev === void 0) prev = 0;
     var delta = h - prev;
     if (delta === 0) return;
+    if (frozen()) {
+      foldFrozenGrowth(box, el, delta);
+      return;
+    }
     if (el.getBoundingClientRect().top >= box.getBoundingClientRect().top) return;
     box.scrollTop += delta;
+    wroteTop = box.scrollTop;
     if (held) held = capture();
   }
+  function park() {
+    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();
+    if (!box) return;
+    box.scrollTop = box.scrollHeight;
+    wroteTop = box.scrollTop;
+  }
+  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;
+    }
+    var target = parked || held;
+    restoreExact = true;
+    restorePinned = false;
+    restore(target, true);
+    parked = !restorePinned || !restoreExact ? target : null;
+    returning = !!parked && returnBudget > 0;
+    if (!returning) {
+      parked = null;
+      parkedStuck = false;
+      returnBudget = 0;
+    }
+    return false;
+  }
+  function isReturning() {
+    return returning;
+  }
+  function thaw() {
+    settleReturn();
+  }
+  function foldFrozenGrowth(box, el, delta) {
+    var elTop = el.getBoundingClientRect().top;
+    foldInto(box, held, elTop, delta);
+    foldInto(box, parked, elTop, delta);
+  }
+  function foldInto(box, a, elTop, delta) {
+    if (!a || a.top >= 0) return;
+    var rowEl = findRow(box, a);
+    if (!rowEl) return;
+    var within = elTop - rowEl.getBoundingClientRect().top;
+    if (within < 0 || within >= rowEl.offsetHeight) return;
+    if (within >= -a.top) return;
+    a.top -= delta;
+    a.scrollHeight += delta;
+  }
   function forget() {
     held = null;
+    release();
   }
   return {
     capture,
@@ -2718,6 +2887,13 @@ function createScrollAnchor(options) {
     preserve,
     remember,
     hold,
+    park,
+    settleReturn,
+    isReturning,
+    release,
+    pinBottom,
+    isFrozen: frozen,
+    thaw,
     absorb,
     forget
   };
@@ -5820,6 +5996,7 @@ var ChatSession = class {
           releaseBgFlag();
           self.updateHistoryCache();
           self.host.notify();
+          if (self.host.settleScroll) self.host.settleScroll();
         }, function() {
           releaseBgFlag();
           self.host.notify();
@@ -5901,7 +6078,7 @@ var ChatSession = class {
         self.drainBgTaskQueue();
       }
       if (!fetchMore) self.refreshLiveIndexState();
-      if (!fetchMore) return self.host.scrollToBottomIfSticky();
+      if (!fetchMore) return self.host.settleScroll ? self.host.settleScroll() : self.host.scrollToBottomIfSticky();
     }).catch(function(err) {
       console.warn("[chat-engine] getChatHistory failed", err);
     }).then(function() {