@jinntec/fore 3.3.2 → 4.0.0

package/src/ui/fx-repeat.js

@@ -10,6 +10,7 @@ import { UIElement } from './UIElement.js';
 import { getPath } from '../xpath-path.js';
 import { FxModel } from '../fx-model.js';
 import { FxBind } from '../fx-bind.js';
+import { DependencyNotifyingDomFacade } from '../DependencyNotifyingDomFacade.js';
 
 /**
  * `fx-repeat`
@@ -59,10 +60,38 @@ export class FxRepeat extends withDraggability(UIElement, false) {
     this.nodeset = [];
     this.inited = false;
     this.index = 1;
-    this.repeatSize = 0;
     this.attachShadow({ mode: 'open', delegatesFocus: true });
     this.opNum = 0; // global number of operations
 
+    // Progressive rendering (size cap + IntersectionObserver sentinel).
+    // `_sentinel !== null` is the single source of truth for "a cap is active and there
+    // is more to reveal" - see _syncSentinels().
+    this._sizeLimit = Infinity;
+    this._renderTarget = 0;
+    this._sentinel = null;
+    this._sentinelObserver = null;
+
+    // True windowed virtualization (opt-in via `virtual` attribute + `size`).
+    // `_windowStart` is the 0-based logical index of the first RENDERED row; it is always 0
+    // when `_virtual` is false, which is what makes every `+ this._windowStart` offset below
+    // degenerate to exactly today's prefix-window math for non-virtual repeats.
+    this._virtual = false;
+    this._windowStart = 0;
+    this._topSentinel = null;
+    this._topSentinelObserver = null;
+
+    // Continuous scroll-driven trim (virtual mode only). The sentinels only fire once the
+    // window's leading/trailing edge is reached, which (given the sentinel sits at the very
+    // end of whatever was just rendered) forces scrolling through almost a full window's
+    // worth of content before a slide+evict happens - see _trimWindow() for why that alone
+    // lets the rendered count settle well above `size`. This listener evicts confirmed
+    // off-screen rows continuously as the user scrolls, so the window keeps converging on
+    // `size` instead of only trimming in bursts tied to sentinel crossings.
+    this._scrollTrimRoot = null;
+    this._scrollTrimHandler = null;
+    this._scrollTrimLastTop = 0;
+    this._trimScheduled = false;
+
     this.handleInsertHandler = null;
     this.handleDeleteHandler = null;
 
@@ -139,6 +168,37 @@ export class FxRepeat extends withDraggability(UIElement, false) {
     return true;
   }
 
+  // ------------------------------------------------------------
+  // Progressive rendering (size cap)
+  // ------------------------------------------------------------
+
+  _getSizeLimit() {
+    const attr = this.getAttribute('size');
+    if (!attr) return Infinity;
+    const n = parseInt(attr, 10);
+    return Number.isFinite(n) && n > 0 ? n : Infinity;
+  }
+
+  /**
+   * True windowed virtualization is opt-in via `virtual`, and only meaningful together with
+   * a finite `size` (which becomes the window size rather than a prefix cap). `virtual`
+   * without `size` degenerates to fully uncapped, exactly like `size` being absent.
+   */
+  _isVirtual() {
+    return this.hasAttribute('virtual') && this._getSizeLimit() !== Infinity;
+  }
+
+  /**
+   * Upper bound on how many rows _evictFromTop()/_evictFromBottom() remove in a single call.
+   * A quarter of `size` (floor 4) keeps a single correction small no matter how large a
+   * backlog a caller asks to clear - see the comment on _evictFromTop() for why an uncapped
+   * batch turns into a scroll-speed-proportional scrollTop jump. Any excess beyond this cap
+   * simply drains on the next call (there always is one while scrolling continues).
+   */
+  _maxEvictBatch() {
+    return Math.max(4, Math.ceil(this._sizeLimit / 4));
+  }
+
   connectedCallback() {
     super.connectedCallback();
     this.template = this.querySelector('template');
@@ -209,6 +269,7 @@ export class FxRepeat extends withDraggability(UIElement, false) {
 
       const inserted = detail.insertedNodes;
       const insertionIndex = this.nodeset.indexOf(inserted) + 1; // 1-based
+      const relIdx = insertionIndex - 1; // 0-based logical index of the inserted row
 
       const repeatItems = Array.from(
         this.querySelectorAll(
@@ -216,32 +277,86 @@ export class FxRepeat extends withDraggability(UIElement, false) {
         ),
       );
 
-      const newRepeatItem = this._createNewRepeatItem();
-
-      const beforeNode = repeatItems[insertionIndex - 1] ?? null;
-      this.insertBefore(newRepeatItem, beforeNode);
-      newRepeatItem.index = insertionIndex;
-      this._initVariables(newRepeatItem);
-
-      newRepeatItem.nodeset = inserted;
+      // Uncapped repeats always materialize immediately: `_renderTarget` is only resynced to
+      // the full nodeset length inside refresh(), which may not have run yet between two
+      // synchronous inserts, so it can't be trusted as a window boundary when uncapped.
+      // Zone B (within window): today's "within window" case, offset by `_windowStart`.
+      const withinWindow =
+        this._sizeLimit === Infinity ||
+        (relIdx >= this._windowStart && relIdx < this._renderTarget);
+      // Zone A (before window): only reachable in virtual mode - `_windowStart` is always 0
+      // off virtual mode, so `relIdx < 0` never holds.
+      const beforeWindow = this._virtual && relIdx < this._windowStart;
+
+      if (withinWindow) {
+        const relativePos = relIdx - this._windowStart;
+        const newRepeatItem = this._createNewRepeatItem();
+
+        const beforeNode = repeatItems[relativePos] ?? this._sentinel ?? null;
+        this.insertBefore(newRepeatItem, beforeNode);
+        newRepeatItem.index = insertionIndex;
+        this._initVariables(newRepeatItem);
+
+        newRepeatItem.nodeset = inserted;
+
+        for (let i = relativePos; i < repeatItems.length; ++i) {
+          repeatItems[i].index += 1;
+        }
 
-      for (let i = insertionIndex - 1; i < repeatItems.length; ++i) {
-        repeatItems[i].index += 1;
+        this._renderTarget += 1;
+        // In virtual mode, an in-window insert momentarily grows the window past `size` -
+        // evict one row from the opposite (bottom) end to restore window size. This is a
+        // local, in-place insert, not a scroll-driven slide, so no scrollTop correction is
+        // needed either way (known limitation: this always evicts from the bottom regardless
+        // of where in the window the insert landed - see plan's "known limitation" note).
+        if (this._virtual && this._renderTarget - this._windowStart > this._sizeLimit) {
+          this._evictFromBottom(1);
+        }
+        this._syncSentinels();
+
+        this.opNum++;
+        let parentModelItem = FxBind.createModelItem(this.ref, inserted, newRepeatItem, this.opNum);
+        // IMPORTANT: registerModelItem may return an existing canonical ModelItem for the same path.
+        // Always keep using the returned instance to avoid "ghost" ModelItems that still notify.
+        parentModelItem = this.getModel().registerModelItem(parentModelItem);
+        newRepeatItem.modelItem = parentModelItem;
+
+        this._createModelItemsRecursively(newRepeatItem, parentModelItem);
+
+        fore.scanForNewTemplateExpressionsNextRefresh();
+        fore.addToBatchedNotifications(newRepeatItem);
+      } else if (beforeWindow) {
+        // Zone A: inserted above the rendered window. The rendered rows are still correct
+        // (same node identities) - only their logical position shifted by one. No DOM
+        // change; just shift the window's bookkeeping to match.
+        this._windowStart += 1;
+        this._renderTarget += 1;
+        this._reindexRenderedRows();
+        this._syncSentinels();
+
+        // IMPORTANT: do NOT fall through to the shared setIndex(insertionIndex) below, and do
+        // NOT route the index bump through setIndex() either - both would run the
+        // window-membership check and, since `this.index` (still pointing wherever it did
+        // before this insert - raw scrolling never updates it, only setIndex() does) may now
+        // resolve to a position outside the window we just deliberately left untouched,
+        // trigger an unwanted seek-jump that destroys/rebuilds this exact window. Nothing
+        // rendered actually moved (Zone A never touches DOM), so only the numeric index
+        // needs to shift to keep pointing at the same logical row - update the attribute
+        // directly. Known limitation: index()-dependents elsewhere in the form aren't
+        // notified of this silent renumbering (no 'item-changed' dispatch) - acceptable since
+        // Zone A only fires for inserts above an actively-scrolled-away window, an already
+        // rare interaction.
+        if (this.index >= insertionIndex) {
+          this.index += 1;
+        }
+        return;
       }
+      // else: Zone C - inserted beyond the rendered window. this.nodeset already reflects
+      // the insert (re-evaluated above) - there's no DOM row to create yet. setIndex() below
+      // triggers growth-on-demand (non-virtual) or a seek jump (virtual) if navigation
+      // reaches that far.
 
       this.setIndex(insertionIndex);
-
-      this.opNum++;
-      let parentModelItem = FxBind.createModelItem(this.ref, inserted, newRepeatItem, this.opNum);
-      // IMPORTANT: registerModelItem may return an existing canonical ModelItem for the same path.
-      // Always keep using the returned instance to avoid "ghost" ModelItems that still notify.
-      parentModelItem = this.getModel().registerModelItem(parentModelItem);
-      newRepeatItem.modelItem = parentModelItem;
-
-      this._createModelItemsRecursively(newRepeatItem, parentModelItem);
-
-      fore.scanForNewTemplateExpressionsNextRefresh();
-      fore.addToBatchedNotifications(newRepeatItem);
     };
 
     // ----------------
@@ -332,16 +447,36 @@ export class FxRepeat extends withDraggability(UIElement, false) {
           -webkit-animation: fade-out-bottom 0.7s cubic-bezier(0.250, 0.460, 0.450, 0.940) both;
           animation: fade-out-bottom 0.7s cubic-bezier(0.250, 0.460, 0.450, 0.940) both;
       }
+      /* A bare <slot> renders as display:contents (layout-transparent), so demos that put
+         display:flex/grid on the fx-repeat host (e.g. demo/kanban.html's #column) get their
+         fx-repeatitems as direct flex/grid items. The [part=list] wrapper below must stay
+         equally transparent or it becomes the sole flex/grid item and items collapse into a
+         block stack inside it. role="list" survives display:contents in all supported browsers. */
+      [part="list"]{
+          display: contents;
+      }
    `;
+    // `role="list"` sits on a wrapper around the default slot only, not on the host itself:
+    // a named `slot="header"` (e.g. a `<table>` used as a column header row, see demo/api.html)
+    // is real, non-listitem content that would otherwise become an accessibility-tree child of
+    // the list and fail axe's aria-required-children check. Keeping it outside the wrapper avoids
+    // that while still giving the repeated `fx-repeatitem`s (each `role="listitem"`) a `list`
+    // parent.
     const html = `
           <slot name="header"></slot>
-          <slot></slot>
+          <div part="list" role="list"><slot></slot></div>
   `;
 
-    this.shadowRoot.innerHTML = `
+    const sheet = Fore.getSharedStyleSheet(style);
+    if (sheet) {
+      this.shadowRoot.innerHTML = html;
+      this.shadowRoot.adoptedStyleSheets = [sheet];
+    } else {
+      this.shadowRoot.innerHTML = `
       <style>${style}</style>
       ${html}
   `;
+    }
   }
 
   /**
@@ -379,40 +514,76 @@ export class FxRepeat extends withDraggability(UIElement, false) {
     insertionIndex1 = Math.max(1, Math.min(insertionIndex1, newLen));
     const pos0 = insertionIndex1 - 1;
 
-    // 3) Insert DOM row: set nodeset/index BEFORE inserting into DOM.
-    const before = repeatItems();
-    const beforeNode = before[pos0] ?? null;
+    // See the equivalent comment in the XML insert handler above.
+    const withinWindow =
+      this._sizeLimit === Infinity || (pos0 >= this._windowStart && pos0 < this._renderTarget);
+    const beforeWindow = this._virtual && pos0 < this._windowStart;
 
-    const newRepeatItem = this._createNewRepeatItem();
-    newRepeatItem.index = pos0 + 1;
-    this._initVariables(newRepeatItem);
-    newRepeatItem.nodeset = this.nodeset[pos0];
+    if (withinWindow) {
+      const relativePos = pos0 - this._windowStart;
 
-    this.insertBefore(newRepeatItem, beforeNode);
+      // 3) Insert DOM row: set nodeset/index BEFORE inserting into DOM.
+      const before = repeatItems();
+      const beforeNode = before[relativePos] ?? this._sentinel ?? null;
 
-    // Ensure it gets initialized/rendered
-    fore.registerLazyElement(newRepeatItem);
-    if (fore.createNodes) {
-      fore.initData(newRepeatItem);
-    }
-    fore.scanForNewTemplateExpressionsNextRefresh();
-    fore.addToBatchedNotifications(newRepeatItem);
+      const newRepeatItem = this._createNewRepeatItem();
+      newRepeatItem.index = pos0 + 1;
+      this._initVariables(newRepeatItem);
+      newRepeatItem.nodeset = this.nodeset[pos0];
 
-    // 4) Rebind shifted rows (pos0+1..end) and refresh only those.
-    const after = repeatItems();
+      this.insertBefore(newRepeatItem, beforeNode);
 
-    for (let i = pos0 + 1; i < after.length; i++) {
-      const ri = after[i];
-      ri.index = i + 1;
+      // Ensure it gets initialized/rendered
+      fore.registerLazyElement(newRepeatItem);
+      if (fore.createNodes) {
+        fore.initData(newRepeatItem);
+      }
+      fore.scanForNewTemplateExpressionsNextRefresh();
+      fore.addToBatchedNotifications(newRepeatItem);
 
-      const newNode = this.nodeset[i];
-      if (ri.nodeset !== newNode) {
-        ri.nodeset = newNode;
-        if (fore.createNodes) fore.initData(ri);
+      this._renderTarget += 1;
+      // See the equivalent comment in the XML insert handler above.
+      if (this._virtual && this._renderTarget - this._windowStart > this._sizeLimit) {
+        this._evictFromBottom(1);
       }
+      this._syncSentinels();
 
-      fore.addToBatchedNotifications(ri);
+      // 4) Rebind shifted rows (relativePos+1..end) and refresh only those.
+      const after = repeatItems();
+
+      for (let i = relativePos + 1; i < after.length; i++) {
+        const ri = after[i];
+        const logicalIdx = this._windowStart + i;
+        ri.index = logicalIdx + 1;
+
+        const newNode = this.nodeset[logicalIdx];
+        if (ri.nodeset !== newNode) {
+          ri.nodeset = newNode;
+          if (fore.createNodes) fore.initData(ri);
+        }
+
+        fore.addToBatchedNotifications(ri);
+      }
+    } else if (beforeWindow) {
+      // Zone A: see the equivalent comment in the XML insert handler above - must NOT go
+      // through setIndex() at all (neither for pos0+1 nor for an adjusted value), since
+      // `this.index` may already point outside this deliberately-untouched window (raw
+      // scrolling never updates it) and setIndex()'s window-membership check would treat
+      // that as an out-of-window navigation, triggering an unwanted seek-jump.
+      this._windowStart += 1;
+      this._renderTarget += 1;
+      this._reindexRenderedRows();
+      this._syncSentinels();
+
+      // insertionIndex1 (outer scope) already equals pos0 + 1.
+      if (this.index >= insertionIndex1) {
+        this.index += 1;
+      }
+      return;
     }
+    // else: Zone C - inserted beyond the rendered window - no DOM row to create, nothing to
+    // rebind. setIndex() below triggers growth-on-demand (non-virtual) or a seek jump
+    // (virtual) if navigation reaches that far.
 
     // Select inserted row
     this.setIndex(pos0 + 1);
@@ -435,6 +606,24 @@ export class FxRepeat extends withDraggability(UIElement, false) {
 
     document.removeEventListener('deleted', this.handleDeleteHandler, true);
     document.removeEventListener('insert', this.handleInsertHandler, true);
+
+    if (this._sentinelObserver) {
+      this._sentinelObserver.disconnect();
+      this._sentinelObserver = null;
+    }
+    this._sentinel = null;
+
+    if (this._topSentinelObserver) {
+      this._topSentinelObserver.disconnect();
+      this._topSentinelObserver = null;
+    }
+    this._topSentinel = null;
+
+    if (this._scrollTrimHandler && this._scrollTrimRoot) {
+      this._scrollTrimRoot.removeEventListener('scroll', this._scrollTrimHandler);
+    }
+    this._scrollTrimRoot = null;
+    this._scrollTrimHandler = null;
   }
 
   get repeatSize() {
@@ -442,14 +631,33 @@ export class FxRepeat extends withDraggability(UIElement, false) {
   }
 
   set repeatSize(size) {
-    this.size = size;
+    if (!size) {
+      this.removeAttribute('size');
+    } else {
+      this.setAttribute('size', size);
+    }
   }
 
-  setIndex(index) {
+  setIndex(index, notifyDependents = true) {
     this.index = index;
 
+    if (this._sizeLimit !== Infinity && Number.isFinite(index) && index >= 1) {
+      if (this._virtual) {
+        // Sliding window: navigation to an index outside the window can't be front-filled
+        // (there's no stable prefix to grow from) - it's a hard jump instead. See
+        // _seekWindowTo(). Navigation to an index already inside the window is a no-op here.
+        const logicalIdx = index - 1;
+        const inWindow = logicalIdx >= this._windowStart && logicalIdx < this._renderTarget;
+        if (!inWindow) this._seekWindowTo(logicalIdx);
+      } else {
+        // Growth-on-demand: navigation (keyboard, index('id') dependents, programmatic) to
+        // an index beyond the currently rendered window front-fills up through it.
+        this._growRenderTarget(index);
+      }
+    }
+
     const rItems = this.querySelectorAll(':scope > fx-repeatitem');
-    const selected = rItems[this.index - 1];
+    const selected = rItems[this.index - 1 - this._windowStart];
 
     this.applyIndex(selected);
 
@@ -458,7 +666,9 @@ export class FxRepeat extends withDraggability(UIElement, false) {
     //
     // When setIndex is invoked as a reaction to a repeatitem click/focus,
     // the repeatitem already dispatched item-changed and dependents already react.
-    if (!this._settingIndexFromItemChanged) {
+    // refresh() passes notifyDependents=false when neither the index nor the node at
+    // the index changed — a repeat refresh alone is not an index change.
+    if (!this._settingIndexFromItemChanged && notifyDependents) {
       this.dispatchEvent(
         new CustomEvent('item-changed', {
           composed: false,
@@ -512,7 +722,10 @@ export class FxRepeat extends withDraggability(UIElement, false) {
 
       if (mi.path.startsWith(`${parentBaseInChildStyle}_`)) return;
 
-      mi.path = `${parentBaseInChildStyle}_${op}${mi.path.slice(parentBaseInChildStyle.length)}`;
+      this.getModel()._setModelItemPath(
+        mi,
+        `${parentBaseInChildStyle}_${op}${mi.path.slice(parentBaseInChildStyle.length)}`,
+      );
     };
 
     Array.from(parentNode.children).forEach(child => {
@@ -581,28 +794,59 @@ export class FxRepeat extends withDraggability(UIElement, false) {
       if (nextIndex1 > d1) nextIndex1 -= 1;
     }
 
+    // Three-zone split against [_windowStart, _renderTarget), using PRE-delete indices
+    // (indices0 already are pre-delete, via detail.deletedIndexes0 - no ordering hazard here,
+    // unlike the XML path's handleDelete()).
     const before = repeatItems();
-    for (const idx0 of indices0) {
-      const itemEl = before[idx0];
-      if (!itemEl) continue;
-
-      try {
-        fore?.unRegisterLazyElement?.(itemEl);
-      } catch (_e) {}
+    let windowShiftFromAbove = 0; // count of Zone-A deletions (above the window)
+    let renderedRemovedCount = 0; // count of Zone-B deletions (actually rendered)
 
-      itemEl.remove();
+    for (const idx0 of indices0) {
+      if (idx0 < this._windowStart) {
+        // Zone A: above window - rendered rows unaffected, window floor shifts down by one.
+        windowShiftFromAbove += 1;
+      } else if (idx0 < this._renderTarget) {
+        // Zone B: rendered.
+        const domPos = idx0 - this._windowStart;
+        const itemEl = before[domPos];
+        if (itemEl) {
+          try {
+            fore?.unRegisterLazyElement?.(itemEl);
+          } catch (_e) {}
+
+          itemEl.remove();
+          renderedRemovedCount += 1;
+        }
+      }
+      // else: Zone C - below window, no DOM row.
     }
 
     this._evalNodeset();
 
-    const start0 = Math.min(...indices0);
-    const after = repeatItems();
+    this._windowStart = Math.max(0, this._windowStart - windowShiftFromAbove);
+    this._renderTarget = this._windowStart + (before.length - renderedRemovedCount);
+    const totalAfterDelete = Array.isArray(this.nodeset) ? this.nodeset.length : 0;
+    this._renderTarget = Math.min(this._renderTarget, totalAfterDelete);
+
+    // Virtual mode: a mid-window delete is not a scroll event - the user still expects a
+    // full window, so backfill from the tail if more nodeset remains below.
+    if (this._virtual) {
+      const deficit = this._sizeLimit - (this._renderTarget - this._windowStart);
+      if (deficit > 0 && this._renderTarget < totalAfterDelete) {
+        this._slideWindowDown(deficit);
+      }
+    }
+    this._syncSentinels();
 
-    for (let i = start0; i < after.length; i++) {
+    // Rebind every currently rendered row to its (possibly shifted) logical node. The
+    // `ri.nodeset !== newNode` guard below makes this cheap for rows that didn't move.
+    const after = repeatItems();
+    for (let i = 0; i < after.length; i++) {
       const ri = after[i];
-      ri.index = i + 1;
+      const logicalIdx = this._windowStart + i;
+      ri.index = logicalIdx + 1;
 
-      const newNode = Array.isArray(this.nodeset) ? this.nodeset[i] : null;
+      const newNode = Array.isArray(this.nodeset) ? this.nodeset[logicalIdx] : null;
       if (ri.nodeset !== newNode) {
         ri.nodeset = newNode;
         if (fore?.createNodes) fore.initData(ri);
@@ -611,19 +855,29 @@ export class FxRepeat extends withDraggability(UIElement, false) {
       fore?.addToBatchedNotifications?.(ri);
     }
 
-    const newLen = after.length;
-    if (newLen === 0) {
+    // Clamp against the LOGICAL total, not the rendered DOM count - under a size cap the two
+    // differ, and clamping to the rendered count would make it impossible to navigate to a
+    // not-yet-rendered logical index (setIndex()'s own growth-on-demand/seek-jump handles
+    // materializing it).
+    if (totalAfterDelete === 0) {
       this.setAttribute('index', '0');
       this.index = 0;
       this._removeIndexMarker?.();
       return;
     }
 
-    nextIndex1 = Math.max(1, Math.min(nextIndex1, newLen));
+    nextIndex1 = Math.max(1, Math.min(nextIndex1, totalAfterDelete));
     this.setIndex(nextIndex1);
   }
 
   handleDelete(deleted) {
+    // Captured BEFORE _evalNodeset() runs below, so it reflects the PRE-delete logical
+    // position - needed to distinguish "deleted row was above the window" (Zone A) from
+    // "deleted row was below the window" (Zone C) when the row isn't found among rendered
+    // items. (_evalNodeset() already reflects the post-delete instance state by the time
+    // this handler runs, since the model mutation happens before the 'deleted' event fires.)
+    const priorIdx = Array.isArray(this.nodeset) ? this.nodeset.indexOf(deleted) : -1;
+
     const items = Array.from(
       this.querySelectorAll(
         ':scope > fx-repeat-item, :scope > fx-repeatitem, :scope > .repeat-item',
@@ -632,22 +886,54 @@ export class FxRepeat extends withDraggability(UIElement, false) {
 
     this._evalNodeset();
 
+    const total = Array.isArray(this.nodeset) ? this.nodeset.length : 0;
+
     const indexToRemove = items.findIndex(item => item.nodeset === deleted);
     if (indexToRemove === -1) {
+      if (this._virtual && priorIdx >= 0 && priorIdx < this._windowStart) {
+        // Zone A: deleted row was above the window - rendered rows unaffected (same node
+        // identities), only their logical position shifted down by one. No DOM change;
+        // shift the window's bookkeeping and current index to match (mirrors the XML
+        // insert handler's Zone-A shift, in reverse). Deliberately does NOT call setIndex()
+        // - see the equivalent comment on the insert side re: `this.index` possibly already
+        // being outside this deliberately-untouched window (raw scrolling never updates it),
+        // which would make setIndex()'s window-membership check trigger an unwanted seek.
+        this._windowStart = Math.max(0, this._windowStart - 1);
+        this._renderTarget = Math.max(this._windowStart, this._renderTarget - 1);
+        this._reindexRenderedRows();
+        this._syncSentinels();
+        this.index = Math.max(1, this.index - 1);
+        return;
+      }
+      // Zone C (or non-virtual beyond-window): deleted node was never rendered - no DOM row
+      // to remove, but the window ceiling may now exceed the shrunk nodeset.
+      this._renderTarget = Math.min(this._renderTarget, total);
+      this._syncSentinels();
       return;
     }
+
+    // Zone B: rendered.
     const itemToRemove = items[indexToRemove];
     itemToRemove.remove();
 
-    const newLength = this.querySelectorAll(
-      ':scope > fx-repeat-item, :scope > fx-repeatitem, :scope > .repeat-item',
-    ).length;
+    this._renderTarget = Math.max(this._windowStart, this._renderTarget - 1);
+    // Virtual mode: a mid-window delete is not a scroll event - the user still expects a
+    // full window, so backfill from the tail if more nodeset remains below.
+    if (this._virtual) {
+      const deficit = this._sizeLimit - (this._renderTarget - this._windowStart);
+      if (deficit > 0 && this._renderTarget < total) {
+        this._slideWindowDown(deficit);
+      }
+    }
+    this._syncSentinels();
 
-    let nextIndex = indexToRemove + 1;
-    if (newLength === 0) {
+    // Clamp against the LOGICAL total, not the rendered DOM count - see the equivalent
+    // comment in _handleJsonDeleted above.
+    let nextIndex = this._windowStart + indexToRemove + 1;
+    if (total === 0) {
       nextIndex = 0;
-    } else if (nextIndex > newLength) {
-      nextIndex = newLength;
+    } else if (nextIndex > total) {
+      nextIndex = total;
     }
 
     this.setIndex(nextIndex);
@@ -666,6 +952,592 @@ export class FxRepeat extends withDraggability(UIElement, false) {
     return newItem;
   }
 
+  _materializeRepeatItem(position) {
+    const newItem = this._createNewRepeatItem();
+    this.insertBefore(newItem, this._sentinel || null);
+    this._initVariables(newItem);
+    newItem.nodeset = this.nodeset[position - 1];
+    newItem.index = position;
+    return newItem;
+  }
+
+  /**
+   * Grows the rendered window up to (at most) `desired` logical positions, materializing
+   * any not-yet-rendered rows in between. Used by the sentinel intersection callback and
+   * by setIndex() to front-fill on-demand navigation beyond the current window.
+   */
+  _growRenderTarget(desired) {
+    const total = Array.isArray(this.nodeset) ? this.nodeset.length : 0;
+    const newTarget = Math.max(this._renderTarget, Math.min(desired, total));
+    if (newTarget === this._renderTarget) return;
+
+    const fore = this.getOwnerForm();
+    for (let position = this._renderTarget + 1; position <= newTarget; position += 1) {
+      const newItem = this._materializeRepeatItem(position);
+      if (fore.createNodes) {
+        fore.initData(newItem);
+      }
+      fore.scanForNewTemplateExpressionsNextRefresh();
+      fore.registerLazyElement(newItem);
+      newItem.refresh(true);
+      Fore.dispatch(this, 'item-created', { nodeset: newItem.nodeset, pos: position });
+    }
+    this._renderTarget = newTarget;
+    this._syncSentinels();
+  }
+
+  /**
+   * Renumbers .index on every currently rendered row to match its logical position
+   * (_windowStart + DOM offset). Needed after any operation that shifts _windowStart
+   * without individually touching every row's index (prepend, eviction, Zone-A shifts).
+   */
+  _reindexRenderedRows() {
+    const rows = this.querySelectorAll(':scope > fx-repeatitem');
+    rows.forEach((row, i) => {
+      row.index = this._windowStart + i + 1;
+    });
+  }
+
+  /**
+   * Evicts up to `count` rows from the top of the rendered window, correcting scrollTop by
+   * the EXACT measured height of the removed rows (not an estimate) so the still-visible
+   * content doesn't visually jump. Only meaningful in virtual mode.
+   *
+   * Only rows CONFIRMED already scrolled a safe margin above the visible viewport are
+   * evicted, even if that's fewer than `count` - a bottom-sentinel intersection only proves
+   * the user has scrolled near the bottom of the currently rendered content, not that
+   * they've scrolled past every row in the leading edge. Evicting unconditionally would
+   * remove rows the user is still looking at, forcing a scrollTop correction bigger than the
+   * current scroll position (clamped to 0) and visibly yanking the viewport.
+   *
+   * The `_EVICT_MARGIN_PX` buffer is what keeps the freshly-created top sentinel (inserted
+   * right after eviction, at the new window's start) genuinely off-screen rather than
+   * exactly at the viewport boundary: without it, the scrollTop correction above would land
+   * precisely where content ends and the new sentinel begins, and the sentinel's very first
+   * IntersectionObserver reading (which reports the CURRENT state, not just future changes)
+   * would immediately report it as visible - triggering an instant slide back up and
+   * oscillating forever. Leaving this margin of already-scrolled-past content unevicted
+   * means the sentinel ends up genuinely above the fold, only intersecting once the user
+   * scrolls up for real.
+   */
+  _evictFromTop(count) {
+    const EVICT_MARGIN_PX = 100;
+    // Bounded regardless of how large a deficit the caller asks to clear in one go: a fast
+    // scroll (or a long stretch since the last trim) can hand this a large `count`, and since
+    // eviction here is corrected by an immediate scrollTop jump of the exact removed height,
+    // an uncapped batch means an uncapped, scroll-speed-proportional jump - the faster you
+    // scroll, the heftier the correction. Capping the batch keeps each single correction small
+    // and roughly constant; any remainder simply drains on the next trim/slide call (there's
+    // always a next one while scrolling continues, via _trimWindow's own scroll listener).
+    const boundedCount = Math.min(count, this._maxEvictBatch());
+    const scrollRoot =
+      this._findSentinelRoot() || document.scrollingElement || document.documentElement;
+    const containerTop =
+      scrollRoot && scrollRoot.getBoundingClientRect ? scrollRoot.getBoundingClientRect().top : 0;
+
+    const candidates = Array.from(this.querySelectorAll(':scope > fx-repeatitem')).slice(
+      0,
+      boundedCount,
+    );
+    const rows = [];
+    for (const row of candidates) {
+      if (row.getBoundingClientRect().bottom <= containerTop - EVICT_MARGIN_PX) rows.push(row);
+      else break;
+    }
+    if (rows.length === 0) return;
+
+    const removedHeight =
+      rows[rows.length - 1].getBoundingClientRect().bottom - rows[0].getBoundingClientRect().top;
+    // Captured BEFORE removal: removing the rows shrinks scrollHeight immediately, and the
+    // browser auto-clamps scrollTop to the new (smaller) max as a side effect of that DOM
+    // mutation - reading scrollTop again afterward (e.g. via `-=`) would read the
+    // ALREADY-CLAMPED value and double-subtract from it, overshooting past 0.
+    const scrollTopBeforeRemoval = scrollRoot ? scrollRoot.scrollTop : 0;
+
+    const fore = this.getOwnerForm();
+    rows.forEach(row => {
+      fore.unRegisterLazyElement(row);
+      row.remove();
+    });
+
+    this._windowStart += rows.length;
+    if (scrollRoot) scrollRoot.scrollTop = scrollTopBeforeRemoval - removedHeight;
+    this._reindexRenderedRows();
+  }
+
+  /**
+   * Evicts up to `count` rows from the bottom of the rendered window. Symmetric safety check
+   * to _evictFromTop: only rows CONFIRMED already below the visible viewport are evicted, so
+   * a row the user is currently looking at never disappears out from under them. No scrollTop
+   * correction is needed here - removing confirmed-below-the-fold content doesn't shift what's
+   * currently shown.
+   */
+  _evictFromBottom(count) {
+    // See the equivalent comment in _evictFromTop - same batch cap, kept symmetric even
+    // though this particular eviction needs no scrollTop correction, so a single very large
+    // batch here is cheap on its own; the cap mainly keeps top/bottom behavior consistent.
+    const boundedCount = Math.min(count, this._maxEvictBatch());
+    const scrollRoot =
+      this._findSentinelRoot() || document.scrollingElement || document.documentElement;
+    // scrollRoot always resolves to a real element (document.documentElement is the final
+    // fallback), so this always has a getBoundingClientRect - no further fallback needed.
+    const containerBottom = scrollRoot.getBoundingClientRect().bottom;
+
+    const allRows = Array.from(this.querySelectorAll(':scope > fx-repeatitem'));
+    const candidates = allRows.slice(-boundedCount);
+    const rows = [];
+    for (let i = candidates.length - 1; i >= 0; i -= 1) {
+      const row = candidates[i];
+      if (row.getBoundingClientRect().top >= containerBottom) rows.unshift(row);
+      else break;
+    }
+    if (rows.length === 0) return;
+
+    const fore = this.getOwnerForm();
+    rows.forEach(row => {
+      fore.unRegisterLazyElement(row);
+      row.remove();
+    });
+
+    this._renderTarget -= rows.length;
+  }
+
+  /**
+   * Virtual-mode bottom-sentinel response: appends the next `count` logical rows below the
+   * current window, then evicts from the top to bring the rendered count back down to
+   * `_sizeLimit`. The evict count is derived (not assumed equal to `count`) because the
+   * window may not have reached full size yet (e.g. very first slide after initial load).
+   */
+  _slideWindowDown(count) {
+    const total = Array.isArray(this.nodeset) ? this.nodeset.length : 0;
+    const oldEnd = this._renderTarget;
+    const newEnd = Math.min(oldEnd + count, total);
+    if (newEnd === oldEnd) return;
+
+    const fore = this.getOwnerForm();
+    for (let logicalIdx = oldEnd; logicalIdx < newEnd; logicalIdx += 1) {
+      const newItem = this._materializeRepeatItem(logicalIdx + 1);
+      if (fore.createNodes) fore.initData(newItem);
+      fore.scanForNewTemplateExpressionsNextRefresh();
+      fore.registerLazyElement(newItem);
+      newItem.refresh(true);
+      Fore.dispatch(this, 'item-created', { nodeset: newItem.nodeset, pos: logicalIdx + 1 });
+    }
+    this._renderTarget = newEnd;
+
+    // Deliberately NOT capped at `newEnd - oldEnd` (the count just added): a previous slide
+    // may have under-evicted (its rows weren't yet confirmed off-screen per _evictFromTop's
+    // safety margin), leaving a backlog above `_sizeLimit`. Requesting the full deficit here
+    // lets that backlog catch up once those rows really are off-screen, instead of the excess
+    // being locked in forever at whatever a single partial eviction left behind.
+    const currentRendered = this._renderTarget - this._windowStart;
+    const evictCount = Math.max(0, currentRendered - this._sizeLimit);
+    if (evictCount > 0) this._evictFromTop(evictCount);
+
+    this._syncSentinels();
+  }
+
+  /**
+   * Virtual-mode top-sentinel response: prepends the previous `count` logical rows above the
+   * current window, then evicts from the bottom to bring the rendered count back down to
+   * `_sizeLimit`. Rows are created in ASCENDING logical order and inserted before a single
+   * anchor node captured once before the loop - this builds correct DOM order in one pass
+   * without recomputing the anchor (e.g. via repeated querySelector) on every iteration.
+   *
+   * Prepending content ABOVE the current scroll position pushes the previously-visible
+   * content further down the document without changing scrollTop, which would otherwise
+   * make the viewport appear to jump to different (earlier) content. Corrected the same way
+   * _evictFromTop() corrects for removal: capture scrollTop BEFORE the mutation, measure the
+   * EXACT height of what was just inserted, and set the new absolute scrollTop afterward
+   * (not `+=`, which - mirroring the eviction fix - could read a value already perturbed by
+   * the DOM mutation itself).
+   */
+  _slideWindowUp(count) {
+    const oldStart = this._windowStart;
+    const target = Math.max(0, oldStart - count);
+    if (target === oldStart) return;
+
+    // Bounded the same way _evictFromTop()/_evictFromBottom() are (see _maxEvictBatch()): a
+    // single sentinel trigger requests sliding back a whole `size` worth at once, which would
+    // otherwise prepend that many rows and correct scrollTop forward by their full combined
+    // height in one jump. Prepending (and correcting for) only a small batch per call keeps
+    // any single jump small; the remainder is picked up by the requestAnimationFrame
+    // continuation below, converging to the same end state over a few frames instead of one.
+    const batch = Math.min(oldStart - target, this._maxEvictBatch());
+    const newStart = oldStart - batch;
+
+    const scrollRoot =
+      this._findSentinelRoot() || document.scrollingElement || document.documentElement;
+    const scrollTopBeforeInsert = scrollRoot ? scrollRoot.scrollTop : 0;
+
+    const fore = this.getOwnerForm();
+    const anchor =
+      (this._topSentinel && this._topSentinel.nextSibling) ||
+      this.firstElementChild ||
+      this._sentinel ||
+      null;
+
+    const insertedItems = [];
+    for (let logicalIdx = newStart; logicalIdx < oldStart; logicalIdx += 1) {
+      const newItem = this._createNewRepeatItem();
+      this.insertBefore(newItem, anchor);
+      this._initVariables(newItem);
+      newItem.nodeset = this.nodeset[logicalIdx];
+      newItem.index = logicalIdx + 1;
+      if (fore.createNodes) fore.initData(newItem);
+      fore.scanForNewTemplateExpressionsNextRefresh();
+      fore.registerLazyElement(newItem);
+      newItem.refresh(true);
+      Fore.dispatch(this, 'item-created', { nodeset: newItem.nodeset, pos: logicalIdx + 1 });
+      insertedItems.push(newItem);
+    }
+    this._windowStart = newStart;
+    this._reindexRenderedRows();
+
+    if (insertedItems.length > 0 && scrollRoot) {
+      const insertedHeight =
+        insertedItems[insertedItems.length - 1].getBoundingClientRect().bottom -
+        insertedItems[0].getBoundingClientRect().top;
+      scrollRoot.scrollTop = scrollTopBeforeInsert + insertedHeight;
+    }
+
+    // See the equivalent comment in _slideWindowDown - deliberately not capped at
+    // `oldStart - newStart` so a prior partial eviction's backlog can catch up here too.
+    const currentRendered = this._renderTarget - this._windowStart;
+    const evictCount = Math.max(0, currentRendered - this._sizeLimit);
+    if (evictCount > 0) this._evictFromBottom(evictCount);
+
+    this._syncSentinels();
+
+    // Batch was capped above (`batch < oldStart - target`): more prepending was requested
+    // than this call actually performed, so continue on the next frame instead of waiting for
+    // the top sentinel to re-cross (it may not - it's likely still off-screen after only a
+    // partial slide, so no new IntersectionObserver trigger would ever arrive on its own).
+    const remaining = newStart - target;
+    if (remaining > 0) {
+      requestAnimationFrame(() => this._slideWindowUp(remaining));
+    }
+  }
+
+  /**
+   * Hard jump: destroys the entire current window and renders a fresh one starting at
+   * `logicalIdx` (start-at-target, not center-on-target - simpler, matches the roadmap's
+   * wording, and avoids asymmetric clamping near either end of the nodeset that centering
+   * would require anyway), then resets scroll position to the top of the fresh window. Used
+   * when navigation (setIndex, an index('id') dependent, an insert/append past the window)
+   * targets a logical index outside the current window - no smooth-scroll illusion, no
+   * incremental front-fill (that's Phase-1's answer and doesn't fit a sliding window).
+   */
+  _seekWindowTo(logicalIdx) {
+    const total = Array.isArray(this.nodeset) ? this.nodeset.length : 0;
+    const size = this._sizeLimit;
+
+    const newStart = Math.max(0, Math.min(logicalIdx, Math.max(0, total - size)));
+    const newEnd = Math.min(total, newStart + size);
+
+    const fore = this.getOwnerForm();
+    this.querySelectorAll(':scope > fx-repeatitem').forEach(item => {
+      fore.unRegisterLazyElement(item);
+      item.remove();
+    });
+    if (this._topSentinel) this._destroyTopSentinel();
+    if (this._sentinel) this._destroySentinel();
+
+    this._windowStart = newStart;
+    this._renderTarget = newEnd;
+    for (let li = newStart; li < newEnd; li += 1) {
+      const newItem = this._materializeRepeatItem(li + 1);
+      if (fore.createNodes) fore.initData(newItem);
+      fore.scanForNewTemplateExpressionsNextRefresh();
+      fore.registerLazyElement(newItem);
+      newItem.refresh(true);
+      Fore.dispatch(this, 'item-created', { nodeset: newItem.nodeset, pos: li + 1 });
+    }
+    this._syncSentinels();
+
+    const scrollRoot =
+      this._findSentinelRoot() || document.scrollingElement || document.documentElement;
+    if (scrollRoot) scrollRoot.scrollTop = 0;
+  }
+
+  _createSentinel() {
+    const sentinel = document.createElement('div');
+    sentinel.className = 'fx-repeat-sentinel';
+    sentinel.setAttribute('aria-hidden', 'true');
+    // Needs a real box for IntersectionObserver geometry, so it can't be display:contents
+    // like fx-repeat/fx-repeatitem typically are in grid/flex host layouts. Kept visually
+    // negligible; host pages using CSS grid directly on fx-repeat's light DOM may need to
+    // give `.fx-repeat-sentinel` a `grid-column` override.
+    sentinel.style.cssText = 'height:1px;pointer-events:none;';
+    this.appendChild(sentinel);
+    this._sentinel = sentinel;
+
+    if (!this._sentinelObserver) {
+      // An explicit root pointing at the nearest scrollable ancestor, not root:null (the
+      // implicit viewport), is required: root:null does not reliably re-fire when only a
+      // *nested* scrollable container scrolls (verified reproducible in headless Chrome and
+      // Electron - the top-level viewport itself never changes, so the browser doesn't
+      // always re-evaluate intersection for a target clipped by an inner scroll container).
+      // Falls back to null when no scrollable ancestor exists, i.e. the whole page scrolls.
+      this._sentinelObserver = new IntersectionObserver(
+        entries => this._onSentinelIntersect(entries),
+        {
+          root: this._findSentinelRoot(),
+          rootMargin: '0px',
+          threshold: 0,
+        },
+      );
+    }
+    this._sentinelObserver.observe(sentinel);
+  }
+
+  _findSentinelRoot() {
+    let node = this.parentNode;
+    while (node) {
+      if (node.nodeType === Node.DOCUMENT_FRAGMENT_NODE && node.host) {
+        node = node.host;
+        continue;
+      }
+      if (node.nodeType !== Node.ELEMENT_NODE || node === document.documentElement) {
+        node = node.parentNode;
+        continue;
+      }
+      const style = getComputedStyle(node);
+      if (/(auto|scroll)/.test(style.overflowY) || /(auto|scroll)/.test(style.overflow)) {
+        return node;
+      }
+      node = node.parentNode;
+    }
+    return null;
+  }
+
+  _destroySentinel() {
+    if (this._sentinelObserver && this._sentinel) {
+      this._sentinelObserver.unobserve(this._sentinel);
+    }
+    if (this._sentinel) {
+      this._sentinel.remove();
+      this._sentinel = null;
+    }
+  }
+
+  /**
+   * Leading sentinel, symmetric to _createSentinel()/_destroySentinel() but placed as the
+   * first child instead of appended, and only ever active in virtual (windowed) mode - it
+   * signals "there is more nodeset above the rendered window", triggering a prepend+evict-
+   * from-bottom slide instead of the trailing sentinel's append+evict-from-top slide.
+   */
+  _createTopSentinel() {
+    const sentinel = document.createElement('div');
+    sentinel.className = 'fx-repeat-sentinel fx-repeat-sentinel-top';
+    sentinel.setAttribute('aria-hidden', 'true');
+    sentinel.style.cssText = 'height:1px;pointer-events:none;';
+    this.insertBefore(sentinel, this.firstElementChild || null);
+    this._topSentinel = sentinel;
+
+    if (!this._topSentinelObserver) {
+      this._topSentinelObserver = new IntersectionObserver(
+        entries => this._onTopSentinelIntersect(entries),
+        {
+          root: this._findSentinelRoot(),
+          rootMargin: '0px',
+          threshold: 0,
+        },
+      );
+    }
+    this._topSentinelObserver.observe(sentinel);
+  }
+
+  _destroyTopSentinel() {
+    if (this._topSentinelObserver && this._topSentinel) {
+      this._topSentinelObserver.unobserve(this._topSentinel);
+    }
+    if (this._topSentinel) {
+      this._topSentinel.remove();
+      this._topSentinel = null;
+    }
+  }
+
+  /**
+   * Ensures the trailing sentinel exists iff a size cap is active and there are still
+   * unrendered rows left, and (virtual mode only) the leading sentinel exists iff the window
+   * has scrolled past the start of the nodeset. Called after every operation that can change
+   * _renderTarget, _windowStart, or the nodeset length.
+   */
+  _syncSentinels() {
+    this._syncBottomSentinel();
+    this._syncTopSentinel();
+    this._ensureScrollTrimListener();
+  }
+
+  /**
+   * Suppresses the browser's native overscroll/rubber-band bounce on the actual scrolling
+   * ancestor, for ANY size-capped repeat - progressive rendering included, not just `virtual`.
+   * Both flavors can find themselves genuinely at the end of currently-rendered content while
+   * the user is still actively (momentum-)scrolling toward it - virtual mode via eviction
+   * shrinking the scrollable height out from under the scroll, progressive rendering simply
+   * because the next chunk hasn't been appended yet when the sentinel fires - and either one
+   * can trigger a visible bounce (briefly showing whatever is behind the container) right at
+   * that edge. This can't live in a shared stylesheet - the scrolling ancestor is whatever
+   * element the HOST PAGE gave `overflow: auto/scroll`, under any class name, so there's no
+   * fixed selector to hang it on. Setting it here, on the same element _findSentinelRoot()
+   * already resolves for virtual mode's scrollTop corrections, makes it automatic for any
+   * capped repeat regardless of the page's own markup - no CSS to remember. Deliberately
+   * excludes the whole-page fallback (no nested scrollable ancestor found): suppressing
+   * overscroll for the entire document would be a surprising side effect on a page that also
+   * scrolls for reasons unrelated to this repeat. Also skipped if the page already set this
+   * explicitly - never override an intentional choice.
+   */
+  _ensureOverscrollFix() {
+    if (this._sizeLimit === Infinity) return;
+
+    const root = this._findSentinelRoot();
+    if (root && getComputedStyle(root).overscrollBehaviorY === 'auto') {
+      root.style.overscrollBehavior = 'none';
+    }
+  }
+
+  /**
+   * Lazily attaches a 'scroll' listener on the nearest scrollable ancestor (virtual mode
+   * only) that keeps trimming the rendered window toward `size` as the user scrolls - see
+   * _trimWindow(). Re-attaches if the scrollable ancestor changes (e.g. repeat reparented)
+   * and detaches entirely once virtual mode is off.
+   */
+  _ensureScrollTrimListener() {
+    this._ensureOverscrollFix();
+
+    if (!this._virtual) {
+      if (this._scrollTrimHandler && this._scrollTrimRoot) {
+        this._scrollTrimRoot.removeEventListener('scroll', this._scrollTrimHandler);
+      }
+      this._scrollTrimRoot = null;
+      this._scrollTrimHandler = null;
+      return;
+    }
+
+    const root = this._findSentinelRoot() || document.scrollingElement || document.documentElement;
+    if (root === this._scrollTrimRoot && this._scrollTrimHandler) return;
+
+    if (this._scrollTrimHandler && this._scrollTrimRoot) {
+      this._scrollTrimRoot.removeEventListener('scroll', this._scrollTrimHandler);
+    }
+
+    this._scrollTrimRoot = root;
+    this._scrollTrimLastTop = root ? root.scrollTop : 0;
+    this._scrollTrimHandler = () => {
+      if (this._trimScheduled) return;
+      this._trimScheduled = true;
+      requestAnimationFrame(() => {
+        this._trimScheduled = false;
+        const cur = this._scrollTrimRoot ? this._scrollTrimRoot.scrollTop : 0;
+        const direction = cur - this._scrollTrimLastTop;
+        this._scrollTrimLastTop = cur;
+        this._trimWindow(direction);
+      });
+    };
+    root.addEventListener('scroll', this._scrollTrimHandler, { passive: true });
+  }
+
+  /**
+   * Evicts whatever is currently safely off-screen (top or bottom, via the same
+   * margin-guarded checks _slideWindowDown()/_slideWindowUp() already use) whenever the
+   * rendered count exceeds `size`. Sentinels alone only trigger a slide once the window's
+   * edge is reached - by which point almost a full window of content has already scrolled
+   * by - so the rendered count settles at roughly `size + one viewport's worth` instead of
+   * `size`. Running this continuously on scroll lets the excess drain away in small
+   * increments as it becomes confirmed off-screen, well before the next sentinel crossing.
+   *
+   * `direction` (signed scrollTop delta since the last call, 0 if unknown) picks a SINGLE
+   * side to evict from, matching which side is actually accumulating stale rows: scrolling
+   * down (positive) only makes rows above stale, scrolling up (negative) only makes rows
+   * below stale. Trying both sides unconditionally is wrong, not just redundant - while
+   * scrolling up specifically to shrink `_windowStart` back toward 0 (e.g. _slideWindowUp
+   * prepending rows), any leftover excess (from _evictFromBottom's own per-call batch cap
+   * not yet having caught up) would otherwise get partially evicted from the top here,
+   * incrementing `_windowStart` right back up and undoing part of the very prepend that
+   * just ran - directly fighting the scroll-up convergence instead of assisting it.
+   */
+  _trimWindow(direction = 0) {
+    if (!this._virtual) return;
+
+    let excess = this._renderTarget - this._windowStart - this._sizeLimit;
+    if (excess <= 0) return;
+
+    let evictedFromTop = 0;
+    let evictedFromBottom = 0;
+
+    if (direction < 0) {
+      const endBefore = this._renderTarget;
+      this._evictFromBottom(excess);
+      evictedFromBottom = endBefore - this._renderTarget;
+      excess -= evictedFromBottom;
+    } else {
+      const startBefore = this._windowStart;
+      this._evictFromTop(excess);
+      evictedFromTop = this._windowStart - startBefore;
+      excess -= evictedFromTop;
+    }
+
+    this._syncSentinels();
+
+    // `_evictFromTop`/`_evictFromBottom` cap themselves to a small batch per call (see
+    // _maxEvictBatch()), so a large backlog (e.g. after a very fast scroll) needs several
+    // passes to fully drain. While there's more to evict AND this pass actually made
+    // progress, keep draining on the next animation frame rather than waiting for another
+    // 'scroll' event that may never come if the user has already stopped scrolling. Stop
+    // once a pass evicts nothing - the remainder isn't confirmed off-screen yet, and will
+    // be picked up by the scroll listener once it is.
+    if (excess > 0 && (evictedFromTop > 0 || evictedFromBottom > 0)) {
+      requestAnimationFrame(() => this._trimWindow(direction));
+    }
+  }
+
+  _syncBottomSentinel() {
+    const total = Array.isArray(this.nodeset) ? this.nodeset.length : 0;
+    const needsSentinel = this._sizeLimit !== Infinity && this._renderTarget < total;
+
+    if (needsSentinel && !this._sentinel) {
+      this._createSentinel();
+    } else if (!needsSentinel && this._sentinel) {
+      this._destroySentinel();
+    } else if (needsSentinel && this._sentinel && this.lastElementChild !== this._sentinel) {
+      this.appendChild(this._sentinel);
+    }
+  }
+
+  /**
+   * Only ever active in virtual mode (`_windowStart` is always 0 off virtual mode, so
+   * `needsTop` is always false there) - signals there is unrendered nodeset above the window.
+   */
+  _syncTopSentinel() {
+    const needsTop = this._virtual && this._windowStart > 0;
+
+    if (needsTop && !this._topSentinel) {
+      this._createTopSentinel();
+    } else if (!needsTop && this._topSentinel) {
+      this._destroyTopSentinel();
+    } else if (needsTop && this._topSentinel && this.firstElementChild !== this._topSentinel) {
+      this.insertBefore(this._topSentinel, this.firstElementChild);
+    }
+  }
+
+  _onSentinelIntersect(entries) {
+    const last = entries[entries.length - 1];
+    if (!last || !last.isIntersecting) return;
+    if (this._virtual) {
+      this._slideWindowDown(this._sizeLimit);
+    } else {
+      this._growRenderTarget(this._renderTarget + this._sizeLimit);
+    }
+  }
+
+  _onTopSentinelIntersect(entries) {
+    const last = entries[entries.length - 1];
+    if (!last || !last.isIntersecting) return;
+    if (this._windowStart <= 0) return;
+    this._slideWindowUp(this._sizeLimit);
+  }
+
   init() {
     this._evalNodeset();
     this._initTemplate();
@@ -944,7 +1816,18 @@ export class FxRepeat extends withDraggability(UIElement, false) {
       });
     }
 
-    const rawNodeset = evaluateXPath(this.ref, inscope, this);
+    let touchedNodes = null;
+    let domFacade = null;
+    if (this._refNeedsDependencyTracking()) {
+      touchedNodes = new Set();
+      domFacade = new DependencyNotifyingDomFacade(node => touchedNodes.add(node));
+    }
+
+    const rawNodeset = evaluateXPath(this.ref, inscope, this, {}, {}, domFacade);
+
+    if (touchedNodes) {
+      this._trackRefDependencies(touchedNodes);
+    }
 
     this._observeJsonPredicateDependencies(inscope);
 
@@ -973,7 +1856,17 @@ export class FxRepeat extends withDraggability(UIElement, false) {
   async refresh(force) {
     if (!this.inited) this.init();
 
+    const prevNodeset = this.nodeset;
+
     this._evalNodeset();
+    this._sizeLimit = this._getSizeLimit();
+
+    // Captured BEFORE any forcing/reclamping below, so it reflects what the DOM is
+    // currently windowed to - used afterward to detect the rare case where the floor
+    // itself needs to move (virtual toggled off, or the tail shrank out from under it).
+    const oldWindowStart = this._windowStart;
+    this._virtual = this._isVirtual();
+    if (!this._virtual) this._windowStart = 0;
 
     let repeatItems = this.querySelectorAll(':scope > fx-repeatitem');
     let repeatItemCount = repeatItems.length;
@@ -983,10 +1876,59 @@ export class FxRepeat extends withDraggability(UIElement, false) {
       nodeCount = this.nodeset.length;
     }
 
-    const contextSize = nodeCount;
+    const total = nodeCount;
+    const prevTotal = Array.isArray(prevNodeset) ? prevNodeset.length : 1;
+
+    // Recompute the render target:
+    //  - uncapped: always track the full nodeset (identical to the pre-cap `contextSize`)
+    //  - capped, non-virtual, nodeset grew since the last refresh cycle: this only happens
+    //    through a path that didn't already update _renderTarget itself (e.g. bulk/direct
+    //    instance mutation rather than an insert/append action) - re-arm the cap by raising
+    //    the floor. Growth already tracked by insert handlers or setIndex growth-on-demand
+    //    does NOT hit this branch: by the time refresh() runs again after those, this.nodeset
+    //    was already updated by them (they call _evalNodeset() themselves), so it hasn't
+    //    grown further within *this* cycle, and _renderTarget is left exactly as they
+    //    already set it.
+    //  - capped, non-virtual, nodeset did not grow (shrank or same size): never grow the
+    //    window here, only clamp it down if it now exceeds a (possibly smaller) total.
+    //  - capped, virtual: reclamp BOTH edges to the current total, preserving window size
+    //    where possible and sliding the floor back only if the tail shrank out from under
+    //    it. Does not auto-follow nodeset growth mid-window - matches the non-virtual
+    //    branch's "don't jump the user around" philosophy.
+    if (this._sizeLimit === Infinity) {
+      this._renderTarget = total;
+      this._windowStart = 0;
+    } else if (!this._virtual) {
+      if (total > prevTotal) {
+        this._renderTarget = Math.min(Math.max(this._renderTarget, this._sizeLimit), total);
+      } else {
+        this._renderTarget = Math.min(this._renderTarget, total);
+      }
+    } else {
+      const newStart = Math.max(
+        0,
+        Math.min(this._windowStart, Math.max(0, total - this._sizeLimit)),
+      );
+      this._windowStart = newStart;
+      this._renderTarget = Math.min(total, newStart + this._sizeLimit);
+    }
+
+    if (this._windowStart !== oldWindowStart) {
+      // Rare: the window floor itself moved (virtual just turned off, or the reclamp above
+      // slid it back because the nodeset's tail shrank out from under the previous window).
+      // The tail-only shrink/grow loops below assume a stable floor and can't bridge a
+      // floor change, so rebuild the window fresh here instead of patching a partial diff.
+      repeatItems.forEach(item => {
+        item.parentNode.removeChild(item);
+        this.getOwnerForm().unRegisterLazyElement(item);
+      });
+      repeatItemCount = 0;
+    }
+
+    const goal = this._renderTarget - this._windowStart;
 
-    if (contextSize < repeatItemCount) {
-      for (let position = repeatItemCount; position > contextSize; position -= 1) {
+    if (goal < repeatItemCount) {
+      for (let position = repeatItemCount; position > goal; position -= 1) {
         const itemToRemove = repeatItems[position - 1];
         itemToRemove.parentNode.removeChild(itemToRemove);
         this.getOwnerForm().unRegisterLazyElement(itemToRemove);
@@ -997,15 +1939,11 @@ export class FxRepeat extends withDraggability(UIElement, false) {
     repeatItems = this.querySelectorAll(':scope > fx-repeatitem');
     repeatItemCount = repeatItems.length;
 
-    if (contextSize > repeatItemCount) {
-      for (let position = repeatItemCount + 1; position <= contextSize; position += 1) {
-        const newItem = this._createNewRepeatItem();
-        this.appendChild(newItem);
-
-        this._initVariables(newItem);
-
-        newItem.nodeset = this.nodeset[position - 1];
-        newItem.index = position;
+    if (goal > repeatItemCount) {
+      for (let position = repeatItemCount + 1; position <= goal; position += 1) {
+        // `position` is 1-based WITHIN the window; _materializeRepeatItem takes a 1-based
+        // LOGICAL position, so offset by _windowStart (always 0 off virtual mode).
+        const newItem = this._materializeRepeatItem(this._windowStart + position);
 
         if (this.getOwnerForm().createNodes) {
           this.getOwnerForm().initData(newItem);
@@ -1023,22 +1961,33 @@ export class FxRepeat extends withDraggability(UIElement, false) {
 
     for (let position = 0; position < repeatItemCount; position += 1) {
       const item = repeatItems[position];
+      const logicalIdx = this._windowStart + position;
       this.getOwnerForm().registerLazyElement(item);
 
-      if (item.nodeset !== this.nodeset[position]) {
-        item.nodeset = this.nodeset[position];
+      if (item.nodeset !== this.nodeset[logicalIdx]) {
+        item.nodeset = this.nodeset[logicalIdx];
         if (this.getOwnerForm().createNodes) {
           this.getOwnerForm().initData(item);
         }
       }
+      item.index = logicalIdx + 1;
     }
 
+    this._syncSentinels();
+
     const fore = this.getOwnerForm();
     if (!fore.lazyRefresh || force) {
       await Fore.refreshChildren(this, force);
     }
 
-    this.setIndex(this.index);
+    // Notify index() dependents only when THIS refresh changed the current item,
+    // i.e. re-evaluating the nodeset put a different node at the current index.
+    // Index changes made elsewhere (repeatitem click/focus, programmatic setIndex)
+    // dispatch their own 'item-changed' — comparing against them here would
+    // re-announce them, firing a spurious duplicate on every repeat refresh that
+    // overlaps a click (e.g. one triggered by the structural-change consumer).
+    const nodeAt = ns => (Array.isArray(ns) ? ns[this.index - 1] : ns);
+    this.setIndex(this.index, nodeAt(prevNodeset) !== nodeAt(this.nodeset));
   }
 
   _initTemplate() {
@@ -1077,16 +2026,28 @@ export class FxRepeat extends withDraggability(UIElement, false) {
   }
 
   _initRepeatItems() {
-    this.nodeset.forEach((item, index) => {
-      const repeatItem = this._createNewRepeatItem();
-      repeatItem.nodeset = this.nodeset[index];
-      repeatItem.index = index + 1;
+    this._sizeLimit = this._getSizeLimit();
+    this._virtual = this._isVirtual();
+    this._windowStart = 0; // initial render always starts the window at the beginning
+    const total = this.nodeset.length;
+    this._renderTarget = Math.min(total, this._sizeLimit);
 
-      this.appendChild(repeatItem);
+    for (let position = 1; position <= this._renderTarget; position += 1) {
+      const repeatItem = this._materializeRepeatItem(position);
 
       if (this.getOwnerForm().createNodes) {
         this.getOwnerForm().initData(repeatItem);
-        if (repeatItem.nodeset.nodeType) {
+
+        // `createdNodeset` is only ever read once, as an insert template for a *new* row
+        // (see fx-insert.js), so it's taken from the LAST MATERIALIZED row - cloning and
+        // clearing every earlier row's nodeset was pure waste (O(n) discarded work, e.g.
+        // 799 of 800 clones for the UNTDID 1001 codelist). It must be snapshotted AFTER
+        // initData() above, which is what actually populates create-nodes-synthesized
+        // descendants (e.g. TaxCategory/ID, TaxCategory/Percent) onto the node - cloning
+        // before that yields an empty shell. Under a size cap this may not be the true
+        // last logical nodeset entry, but it's the best representative shape available
+        // (the true last entry may never be materialized).
+        if (position === this._renderTarget && repeatItem.nodeset.nodeType) {
           const repeatItemClone = repeatItem.nodeset.cloneNode(true);
           this.clearTextValues(repeatItemClone);
           this.createdNodeset = repeatItemClone;
@@ -1097,9 +2058,10 @@ export class FxRepeat extends withDraggability(UIElement, false) {
         this.applyIndex(repeatItem);
       }
 
-      Fore.dispatch(this, 'item-created', { nodeset: repeatItem.nodeset, pos: index + 1 });
-      this._initVariables(repeatItem);
-    });
+      Fore.dispatch(this, 'item-created', { nodeset: repeatItem.nodeset, pos: position });
+    }
+
+    this._syncSentinels();
   }
 
   clearTextValues(node) {