bunnyquery 1.8.16 → 1.8.18

package/dist/engine.d.mts

@@ -1815,32 +1815,54 @@ declare function shouldRescueInFlightMessage(m: ChatMessage, ctx: RescueDecision
  * prepends, a poll resolves, an indexing row splices in or changes label, a link
  * chip goes grey, an image preview finishes decoding, the "Fetching history..."
  * bar appears and disappears. Every one of those changes the height of something
- * that may sit ABOVE the viewport, and the browser answers by keeping scrollTop —
- * which slides the sentence the user was reading out from under them.
- *
- * Both clients had their own copy of a row anchor for the ONE case each could
- * bracket (agent.vue watched its row-key list, the widget bracketed its full
- * re-render). Everything else — anything that changed a height without changing
- * the row SET, and everything asynchronous — was uncovered in both. This is the
- * single implementation, and it covers both shapes:
+ * that may sit ABOVE the viewport, and the browser answers by keeping scrollTop,
+ * which slides the sentence the reader was on out from under them.
+ *
+ * THE ONE RULE: nothing here stores a position to be applied later. Every method
+ * acts at the moment it is called, against the box as it is at that moment, and
+ * is finished when it returns.
+ *
+ * That rule is the whole design, and it was learned the hard way. An earlier
+ * version of this module also had a "park the place they left, put them back when
+ * they return" half — parked/parkedStuck/returning/returnBudget/sawFrozen, a
+ * frozen mode, a retry budget. Every one of those was a stored instruction that
+ * some later event would carry out, and the reader's experience of a stored
+ * instruction is that the chat throws them somewhere for no reason they can see:
+ * they came back from another app, tapped the composer, the on-screen keyboard
+ * fired a resize, the resize triggered a fetch, the fetch settled, and the settle
+ * dutifully executed an instruction recorded before they ever left. Compensating
+ * at the moment of the change needs no such instruction, and a return then needs
+ * no handling at all, because nothing moved the reader in the first place.
+ *
+ * Two shapes, both immediate:
  *
  *   preserve(fn) / capture() + restore(a)
  *       A mutation you can bracket. Measures immediately before and immediately
  *       after, so it is exact even when the mutation tears the list down.
  *
  *   remember() + hold()
- *       A layout change you CANNOT bracket — an image decoding, a font arriving,
- *       a re-parse triggered from a promise. `remember()` runs from the view's
- *       scroll handler, so the anchor is always the reader's own last position;
- *       `hold()` puts that position back whenever something settles.
- *
- * The staleness rule is what makes the unbracketed half safe. A layout change
- * above the viewport does NOT change scrollTop — the browser preserves it, which
- * is precisely why the content appears to jump. So a remembered anchor is still
- * valid exactly while `box.scrollTop` equals the value it was captured at. If it
- * differs, something moved the box on purpose (the user scrolled, a clamp fired,
- * or the browser's own scroll anchoring already compensated), and `hold()`
- * re-captures rather than dragging the reader back to a position they left.
+ *       A layout change you CANNOT bracket: an image decoding, a font arriving, a
+ *       re-parse from a promise. remember() runs from the view's scroll handler,
+ *       so the anchor is always the reader's own last position.
+ *
+ * hold() is not an exception to the rule, and the staleness check is why. A height
+ * change above the viewport does NOT change scrollTop; the browser preserves it,
+ * which is precisely why the content appears to jump. So the remembered anchor is
+ * valid exactly while `box.scrollTop` still equals the value it was captured at,
+ * i.e. while nothing at all has moved the box. The instant that stops being true
+ * it is re-measured, never replayed. hold() can therefore only ever undo a height
+ * change that just happened, and can never carry out an old intention.
+ *
+ * Two more consequences worth stating, because both were once done the other way:
+ *
+ *   NO FREEZE. Compensation runs whether or not the tab is visible. Layout and
+ *   getBoundingClientRect are live in a hidden tab; only painting and rAF stop.
+ *   Suspending compensation while hidden is what created the need to restore
+ *   something afterwards.
+ *
+ *   A CLAMP IS ACCEPTED. If the content below the reader shrank, their line is
+ *   genuinely unreachable and the browser truncates the correction. Retrying that
+ *   later is how a correction turns into an ambush.
  *
  * DOM-free like the rest of the engine: the element shapes below are structural,
  * so real DOM nodes satisfy them while this file imports nothing from lib.dom.
@@ -1914,21 +1936,6 @@ 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.
      *
@@ -1951,33 +1958,8 @@ 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

@@ -1815,32 +1815,54 @@ declare function shouldRescueInFlightMessage(m: ChatMessage, ctx: RescueDecision
  * prepends, a poll resolves, an indexing row splices in or changes label, a link
  * chip goes grey, an image preview finishes decoding, the "Fetching history..."
  * bar appears and disappears. Every one of those changes the height of something
- * that may sit ABOVE the viewport, and the browser answers by keeping scrollTop —
- * which slides the sentence the user was reading out from under them.
- *
- * Both clients had their own copy of a row anchor for the ONE case each could
- * bracket (agent.vue watched its row-key list, the widget bracketed its full
- * re-render). Everything else — anything that changed a height without changing
- * the row SET, and everything asynchronous — was uncovered in both. This is the
- * single implementation, and it covers both shapes:
+ * that may sit ABOVE the viewport, and the browser answers by keeping scrollTop,
+ * which slides the sentence the reader was on out from under them.
+ *
+ * THE ONE RULE: nothing here stores a position to be applied later. Every method
+ * acts at the moment it is called, against the box as it is at that moment, and
+ * is finished when it returns.
+ *
+ * That rule is the whole design, and it was learned the hard way. An earlier
+ * version of this module also had a "park the place they left, put them back when
+ * they return" half — parked/parkedStuck/returning/returnBudget/sawFrozen, a
+ * frozen mode, a retry budget. Every one of those was a stored instruction that
+ * some later event would carry out, and the reader's experience of a stored
+ * instruction is that the chat throws them somewhere for no reason they can see:
+ * they came back from another app, tapped the composer, the on-screen keyboard
+ * fired a resize, the resize triggered a fetch, the fetch settled, and the settle
+ * dutifully executed an instruction recorded before they ever left. Compensating
+ * at the moment of the change needs no such instruction, and a return then needs
+ * no handling at all, because nothing moved the reader in the first place.
+ *
+ * Two shapes, both immediate:
  *
  *   preserve(fn) / capture() + restore(a)
  *       A mutation you can bracket. Measures immediately before and immediately
  *       after, so it is exact even when the mutation tears the list down.
  *
  *   remember() + hold()
- *       A layout change you CANNOT bracket — an image decoding, a font arriving,
- *       a re-parse triggered from a promise. `remember()` runs from the view's
- *       scroll handler, so the anchor is always the reader's own last position;
- *       `hold()` puts that position back whenever something settles.
- *
- * The staleness rule is what makes the unbracketed half safe. A layout change
- * above the viewport does NOT change scrollTop — the browser preserves it, which
- * is precisely why the content appears to jump. So a remembered anchor is still
- * valid exactly while `box.scrollTop` equals the value it was captured at. If it
- * differs, something moved the box on purpose (the user scrolled, a clamp fired,
- * or the browser's own scroll anchoring already compensated), and `hold()`
- * re-captures rather than dragging the reader back to a position they left.
+ *       A layout change you CANNOT bracket: an image decoding, a font arriving, a
+ *       re-parse from a promise. remember() runs from the view's scroll handler,
+ *       so the anchor is always the reader's own last position.
+ *
+ * hold() is not an exception to the rule, and the staleness check is why. A height
+ * change above the viewport does NOT change scrollTop; the browser preserves it,
+ * which is precisely why the content appears to jump. So the remembered anchor is
+ * valid exactly while `box.scrollTop` still equals the value it was captured at,
+ * i.e. while nothing at all has moved the box. The instant that stops being true
+ * it is re-measured, never replayed. hold() can therefore only ever undo a height
+ * change that just happened, and can never carry out an old intention.
+ *
+ * Two more consequences worth stating, because both were once done the other way:
+ *
+ *   NO FREEZE. Compensation runs whether or not the tab is visible. Layout and
+ *   getBoundingClientRect are live in a hidden tab; only painting and rAF stop.
+ *   Suspending compensation while hidden is what created the need to restore
+ *   something afterwards.
+ *
+ *   A CLAMP IS ACCEPTED. If the content below the reader shrank, their line is
+ *   genuinely unreachable and the browser truncates the correction. Retrying that
+ *   later is how a correction turns into an ambush.
  *
  * DOM-free like the rest of the engine: the element shapes below are structural,
  * so real DOM nodes satisfy them while this file imports nothing from lib.dom.
@@ -1914,21 +1936,6 @@ 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.
      *
@@ -1951,33 +1958,8 @@ 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

@@ -2580,7 +2580,6 @@ 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;
@@ -2592,13 +2591,24 @@ function createScrollAnchor(options) {
     var kids = box.children;
     var fallback = null;
     var fallbackAt = -1;
+    var behind = [];
     for (var i = 0; i < kids.length; i++) {
       var el = kids[i];
       if (!el || typeof el.getAttribute !== "function") continue;
       var key = el.getAttribute(ROW_KEY_ATTR);
       if (!key) continue;
       var top = el.getBoundingClientRect().top - boxTop;
-      if (top + el.offsetHeight <= 0) continue;
+      if (top + el.offsetHeight <= 0) {
+        var bpos = el.getAttribute(ROW_POS_ATTR);
+        behind.push({
+          key,
+          top,
+          pos: bpos === null ? null : bpos || UNKNOWN_ROW_POS,
+          el
+        });
+        if (behind.length > MAX_ALTS) behind.shift();
+        continue;
+      }
       if (top >= box.clientHeight) break;
       var rawPos = el.getAttribute(ROW_POS_ATTR);
       var pos = rawPos === null ? null : rawPos || UNKNOWN_ROW_POS;
@@ -2611,7 +2621,7 @@ function createScrollAnchor(options) {
         el
       };
       if (rawPos === null) {
-        cand.alts = collectAlts(box, boxTop, i + 1);
+        cand.alts = withBehind(collectAlts(box, boxTop, i + 1), behind);
         return cand;
       }
       if (!fallback) {
@@ -2620,7 +2630,10 @@ function createScrollAnchor(options) {
       }
     }
     if (fallback) {
-      fallback.alts = collectAlts(box, boxTop, fallbackAt + 1, true);
+      fallback.alts = withBehind(
+        collectAlts(box, boxTop, fallbackAt + 1, true) || collectAlts(box, boxTop, fallbackAt + 1),
+        behind
+      );
       return fallback;
     }
     return {
@@ -2652,6 +2665,10 @@ function createScrollAnchor(options) {
     }
     return out.length ? out : void 0;
   }
+  function withBehind(forward, behind) {
+    var out = (forward || []).concat(behind.slice().reverse());
+    return out.length ? out : void 0;
+  }
   function findRow(box, anchor) {
     var el = anchor.el;
     if (el && el.parentNode === box) return el;
@@ -2664,21 +2681,7 @@ function createScrollAnchor(options) {
     }
     return null;
   }
-  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;
+  function restore(anchor) {
     var box = options.getBox();
     if (!box || !anchor || options.isStuck()) return;
     var el = findRow(box, anchor);
@@ -2690,32 +2693,36 @@ function createScrollAnchor(options) {
       var boxTop = box.getBoundingClientRect().top;
       var delta = el.getBoundingClientRect().top - boxTop - anchor.top;
       var slack = Math.abs(box.scrollHeight - anchor.scrollHeight) + box.clientHeight;
-      if (!unbounded && (delta > slack || delta < -slack)) {
-        lost(box, anchor);
+      var moved = delta - (anchor.scrollTop - box.scrollTop);
+      if (moved > slack || moved < -slack) {
+        el = null;
+      } else {
+        if (delta >= 1 || delta <= -1) box.scrollTop += delta;
+        held = {
+          key: anchor.key,
+          top: anchor.top,
+          pos: anchor.pos,
+          scrollTop: box.scrollTop,
+          scrollHeight: box.scrollHeight,
+          el,
+          // Carried, not dropped: one successful restore used to disarm the
+          // standbys for every later hold.
+          alts: anchor.alts
+        };
         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,
-        // 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 });
+      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;
@@ -2724,12 +2731,9 @@ function createScrollAnchor(options) {
       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;
+      var amoved = adelta - (anchor.scrollTop - box.scrollTop);
+      if (amoved > aslack || amoved < -aslack) continue;
       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,
@@ -2748,13 +2752,9 @@ 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;
-      wroteTop = box.scrollTop;
-    }
+    if (options.rawFallback) box.scrollTop = anchor.scrollTop;
   }
   function preserve(mutate) {
     var anchor = capture();
@@ -2763,17 +2763,9 @@ 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;
@@ -2800,86 +2792,17 @@ 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,
@@ -2887,13 +2810,7 @@ function createScrollAnchor(options) {
     preserve,
     remember,
     hold,
-    park,
-    settleReturn,
-    isReturning,
-    release,
     pinBottom,
-    isFrozen: frozen,
-    thaw,
     absorb,
     forget
   };