mnfst 0.5.157 → 0.5.158

package/lib/manifest.virtual.js

@@ -1,54 +1,58 @@
-/* Manifest Virtual — variable-height list virtualization for Alpine.
+/* Manifest Virtual — in-flow list/table/grid/gallery virtualization for Alpine.
  *
  * Renders only the rows visible in the scroll viewport (plus an overscan
- * buffer), so a list of tens of thousands of rows can scroll smoothly with
- * a low DOM count. Row heights are measured on render and the spacer
- * recalculates, so authors aren't bound to a fixed row height.
+ * buffer). Rows stay in NORMAL FLOW between a top + bottom spacer whose heights
+ * stand in for the rows above/below the window — so the same markup + CSS works
+ * virtualized or not. No absolute positioning, so shared columns (native
+ * <table> and .grid-table), sticky cells, and flex-wrap all behave normally.
  *
- * Usage — wrap an x-for template with x-virtual on the scrolling container:
+ * Usage — wrap an x-for template in the scrolling container:
  *
  *   <div x-virtual style="height: 600px; overflow: auto">
  *     <template x-for="row in $x.customers" :key="row.id">
- *       <div class="row">
- *         <span x-text="row.name"></span>
- *       </div>
+ *       <div class="grid-row"> … cells … </div>
  *     </template>
  *   </div>
  *
+ * The template may be nested (e.g. inside <table><tbody>); the plugin finds it
+ * and hosts spacers/rows in its parent.
+ *
  * Options (object expression on the directive):
  *
- *   <div x-virtual="{ estimate: 48, overscan: 5 }" style="height: 600px">
+ *   estimate   Initial per-row height in px (default 50), or { width, height }
+ *              for galleries. Used for unmeasured rows; closer = less drift.
+ *   overscan   Rows/lines to render above/below the window (default 3).
+ *   mode       'table' | 'grid' | 'flex' | 'block'. Auto-detected if omitted.
  *
- *     estimate   Initial per-row height in px (default 50). Used for rows
- *                that haven't been measured yet. Closer estimates mean
- *                less scroll-position drift on first render.
- *     overscan   Rows to render above/below the visible window (default 3).
- *                Higher = smoother scroll, more DOM.
+ * Modes:
+ *   block  — one item per line, full width (default for stacked divs).
+ *   table  — native <table>; spacer is a <tr>. One item per line.
+ *   grid   — .grid-table (display:grid + display:contents rows); spacer spans
+ *            grid-column 1 / -1. One logical row per line.
+ *   flex   — flex-wrap gallery; items pack N per line, whole lines render so
+ *            flex sizing stays correct. Ragged width + height supported.
  *
  * Notes:
- *
- *   - Only one template child is supported. It must have x-for and :key.
- *   - The container element must have a bounded height (CSS height /
- *     max-height) and scroll. The plugin sets overflow: auto + position:
- *     relative if not already set.
- *   - Heights are remeasured automatically if a row's content changes.
+ *   - Column widths should be content-independent (table-layout: fixed, fixed/%
+ *     grid tracks) or columns shift as the window changes. Stripe by data index,
+ *     not :nth-child. See the docs for these table caveats.
  */
 
 function initializeVirtualPlugin() {
 
-    Alpine.directive('virtual', (el, { expression }, { effect, evaluate, evaluateLater, cleanup }) => {
+    Alpine.directive('virtual', (el, { expression }, { evaluate, evaluateLater, effect, cleanup }) => {
 
-        // --- Find and parse the template ---
-        const template = el.querySelector(':scope > template');
-        if (!template) {
-            console.warn('[x-virtual] expects a child <template> with x-for, e.g. <template x-for="row in $x.items" :key="row.id">…');
+        // --- Find the template (may be nested, e.g. table > tbody > template) ---
+        const template = el.querySelector('template[x-for]') || el.querySelector(':scope template');
+        if (!template || !template.getAttribute('x-for')) {
+            // Stay quiet on re-init of an already-virtualized container (x-for was
+            // stripped on the first pass); only warn on genuine misuse.
+            if (!el.querySelector('[data-virtual-spacer]')) {
+                console.warn('[x-virtual] expects a descendant <template> with x-for, e.g. <template x-for="row in $x.items" :key="row.id">…');
+            }
             return;
         }
         const forExpr = template.getAttribute('x-for');
-        if (!forExpr) {
-            console.warn('[x-virtual] child <template> must have x-for');
-            return;
-        }
         const m = /^\s*(\S+|\(\s*\S+\s*,\s*\S+\s*\))\s+(?:in|of)\s+(.+?)\s*$/.exec(forExpr);
         if (!m) {
             console.warn('[x-virtual] could not parse x-for expression: ' + forExpr);
@@ -56,230 +60,462 @@ function initializeVirtualPlugin() {
         }
         const itemName = m[1].trim();
         const sourceExpr = m[2].trim();
-        const keyExpr =
-            template.getAttribute(':key') ||
-            template.getAttribute('x-bind:key') ||
-            `${itemName}.id`;
-
-        // Remove x-for/:key so Alpine doesn't try to render the full list, but
-        // KEEP the template in the DOM as our render source. We'll clone its
-        // contents per visible row.
+        const keyExpr = template.getAttribute(':key') || template.getAttribute('x-bind:key') || `${itemName}.id`;
+
+        // Strip x-for/:key so Alpine doesn't render the full list; keep the
+        // template in the DOM as our clone source.
         template.removeAttribute('x-for');
         template.removeAttribute(':key');
         template.removeAttribute('x-bind:key');
 
         // --- Options ---
-        const options = expression ? evaluate(expression) || {} : {};
-        const initialEstimate = Number(options.estimate) > 0 ? Number(options.estimate) : 50;
+        const options = expression ? (evaluate(expression) || {}) : {};
+        const est = options.estimate;
+        const estimateH = (est && typeof est === 'object') ? (Number(est.height) || 50) : (Number(est) > 0 ? Number(est) : 50);
+        const estimateW = (est && typeof est === 'object') ? (Number(est.width) || 120) : 120;
         const overscan = Number.isFinite(options.overscan) && options.overscan >= 0 ? Number(options.overscan) : 3;
 
-        // --- Container setup ---
-        const cs = getComputedStyle(el);
-        if (cs.overflow === 'visible' && cs.overflowY === 'visible') el.style.overflow = 'auto';
-        if (cs.position === 'static') el.style.position = 'relative';
+        // --- Elements & mode ---
+        const scrollEl = el;                          // the bounded scroll viewport
+        const host = template.parentElement;          // where spacers + rows live
+        const cs = getComputedStyle(scrollEl);
+        if (cs.overflow === 'visible' && cs.overflowY === 'visible') scrollEl.style.overflow = 'auto';
 
-        // The spacer holds the rendered (absolutely positioned) rows and sizes
-        // itself to the total virtual height so the scrollbar is correct.
-        const spacer = document.createElement('div');
-        spacer.dataset.virtualSpacer = '';
-        spacer.style.position = 'relative';
-        spacer.style.width = '100%';
-        spacer.style.height = '0px';
-        el.appendChild(spacer);
+        const mode = options.mode || detectMode(host);
+        const isFlex = mode === 'flex';
+        const isMasonry = mode === 'masonry';
+
+        // Masonry options: fixed `columns` or target `columnWidth`; optional
+        // per-item `span` (cols) and `height` (px) fns from data for ~zero
+        // settling; `gap` px (falls back to CSS gap).
+        const colsOpt = Number(options.columns) > 0 ? Math.floor(options.columns) : 0;
+        const colWidthOpt = Number(options.columnWidth) > 0 ? Number(options.columnWidth) : 0;
+        const spanFn = typeof options.span === 'function' ? options.span : null;
+        const heightFn = typeof options.height === 'function' ? options.height : null;
+        const masonryGap = Number.isFinite(options.gap) ? Number(options.gap) : (parseFloat(cs.gap) || 0);
+        if (isMasonry && cs.position === 'static') scrollEl.style.position = 'relative';
+
+        // Column count for table spacer colspan (so it doesn't disturb columns).
+        const colCount = template.content.firstElementChild
+            ? template.content.firstElementChild.children.length : 1;
+
+        // --- Spacers (line modes) / sizer (masonry) ---
+        let topSpacer, botSpacer, sizer;
+        if (isMasonry) {
+            sizer = document.createElement('div');
+            sizer.dataset.virtualSpacer = '';
+            sizer.setAttribute('aria-hidden', 'true');
+            sizer.style.cssText = 'position:absolute;top:0;left:0;width:1px;height:0;pointer-events:none';
+            host.appendChild(sizer);
+        } else {
+            topSpacer = makeSpacer(mode, colCount);
+            botSpacer = makeSpacer(mode, colCount);
+            host.insertBefore(topSpacer, template);
+            host.insertBefore(botSpacer, template);
+        }
+        const anchor = isMasonry ? sizer : botSpacer;   // rows insert before this
 
         // --- State ---
-        // heights: key -> measured pixel height (only for rows that have been
-        // mounted at least once and measured).
-        const heights = new Map();
-        let measuredSum = 0;
-        let measuredCount = 0;
-        // rendered: key -> wrapper element currently in the DOM
-        const rendered = new Map();
-        // data: latest snapshot of the source array
+        const heights = new Map();   // key -> measured line/row height
+        const widths = new Map();    // key -> measured item width (flex only)
+        let measuredSum = 0, measuredCount = 0;
+        const rendered = new Map();  // key -> { node, scope, removeScope }
         let data = [];
-        // Cached cumulative offsets — index i holds the sum of heights of rows
-        // 0..(i-1). Length is data.length + 1; final entry is total height.
-        let cumulative = new Float64Array(1);
-
-        const getAvg = () => (measuredCount > 0 ? measuredSum / measuredCount : initialEstimate);
-        const rowHeightFor = (key) => heights.get(key) ?? getAvg();
+        let cumulative = new Float64Array(1);  // line-top offsets; last = total
+        let lines = [];                        // flex: [{ start, end, height }]
+        let pos = [];                          // masonry: per-index { x, y, w, h }
+        let sortedTop = [];                    // masonry: indices sorted by y
+        let totalHeight = 0;                   // masonry: packed content height
+        let maxItemH = 0;                      // masonry: back-scan bound
+        let ready = false;                     // becomes true once container is sized
 
-        // Evaluate the key expression against an item without going through
-        // Alpine — `new Function` is fast and isolates from the surrounding
-        // scope. Expression usually looks like `row.id` or `row.$id`.
         const keyFn = buildKeyFn(itemName, keyExpr);
+        const avgH = () => (measuredCount > 0 ? measuredSum / measuredCount : estimateH);
+        const heightFor = (k) => heights.get(k) ?? avgH();
+        const widthFor = (k) => widths.get(k) ?? estimateW;
+        const heightForItem = (item) => heightFn ? (Number(heightFn(item)) || estimateH) : heightFor(keyFn(item));
 
-        function rebuildCumulative() {
+        // ---- Cumulative offset model ----
+
+        function rebuild() {
+            if (isMasonry) rebuildMasonry();
+            else if (isFlex) rebuildFlex();
+            else rebuildSingle();
+        }
+
+        // Skyline packer: place each item in the column band (of `span` width)
+        // with the lowest top. Sizes are independent; only positions depend on
+        // order — so the whole layout is computed here in JS, no rendering.
+        function rebuildMasonry() {
+            const cw = contentWidth();
+            const g = masonryGap;
+            let cols = colsOpt || (colWidthOpt ? Math.max(1, Math.floor((cw + g) / (colWidthOpt + g))) : 3);
+            const colW = (cw - (cols - 1) * g) / cols;
+            const bottom = new Float64Array(cols);
+            const n = data.length;
+            pos = new Array(n);
+            maxItemH = 0;
+            for (let i = 0; i < n; i++) {
+                const item = data[i];
+                let span = spanFn ? (spanFn(item) | 0) : 1;
+                if (span < 1) span = 1; else if (span > cols) span = cols;
+                const h = heightForItem(item);
+                let bestC = 0, bestY = Infinity;
+                for (let c = 0; c + span <= cols; c++) {
+                    let y = 0;
+                    for (let d = 0; d < span; d++) if (bottom[c + d] > y) y = bottom[c + d];
+                    if (y < bestY) { bestY = y; bestC = c; }
+                }
+                const w = span * colW + (span - 1) * g;
+                pos[i] = { x: bestC * (colW + g), y: bestY, w, h };
+                const nb = bestY + h + g;
+                for (let d = 0; d < span; d++) bottom[bestC + d] = nb;
+                if (h > maxItemH) maxItemH = h;
+            }
+            let t = 0;
+            for (let c = 0; c < cols; c++) if (bottom[c] > t) t = bottom[c];
+            totalHeight = t > 0 ? t - g : 0;
+            sortedTop = Array.from({ length: n }, (_, i) => i).sort((a, b) => pos[a].y - pos[b].y);
+        }
+
+        function rebuildSingle() {
             const n = data.length;
             cumulative = new Float64Array(n + 1);
             let y = 0;
             for (let i = 0; i < n; i++) {
                 cumulative[i] = y;
-                const k = keyFn(data[i]);
-                y += rowHeightFor(k);
+                y += heightFor(keyFn(data[i]));
             }
             cumulative[n] = y;
-            spacer.style.height = y + 'px';
         }
 
-        // Find the first index whose offset is >= scrollTop. Cumulative is
-        // monotonic so binary search works.
-        function findStartIndex(scrollTop) {
-            let lo = 0, hi = data.length;
+        function rebuildFlex() {
+            const cw = contentWidth();
+            const gx = gapX(), gy = gapY();
+            lines = [];
+            let i = 0;
+            const n = data.length;
+            while (i < n) {
+                const start = i;
+                let lineW = 0, h = 0;
+                while (i < n) {
+                    const k = keyFn(data[i]);
+                    const w = widthFor(k);
+                    const add = lineW === 0 ? w : gx + w;
+                    if (lineW > 0 && lineW + add > cw) break;   // wrap
+                    lineW += add;
+                    h = Math.max(h, heightFor(k));
+                    i++;
+                }
+                if (i === start) i++;                            // item wider than row
+                lines.push({ start, end: i, height: h });
+            }
+            cumulative = new Float64Array(lines.length + 1);
+            let y = 0;
+            for (let l = 0; l < lines.length; l++) {
+                cumulative[l] = y;
+                y += lines[l].height + gy;
+            }
+            cumulative[lines.length] = lines.length ? y - gy : 0;
+        }
+
+        // Binary search: first line/row whose END offset exceeds `pos`.
+        function findStart(pos, count) {
+            let lo = 0, hi = count;
             while (lo < hi) {
                 const mid = (lo + hi) >>> 1;
-                if (cumulative[mid + 1] <= scrollTop) lo = mid + 1;
+                if (cumulative[mid + 1] <= pos) lo = mid + 1;
                 else hi = mid;
             }
-            return Math.max(0, lo - overscan);
+            return lo;
         }
 
-        function findEndIndex(scrollBottom, startHint) {
-            let i = startHint;
-            const n = data.length;
-            while (i < n && cumulative[i] < scrollBottom) i++;
-            return Math.min(n, i + overscan);
-        }
+        // ---- Render ----
 
-        function renderVisible() {
-            if (!data.length) {
-                for (const [, node] of rendered) node.remove();
-                rendered.clear();
-                return;
-            }
-            const scrollTop = el.scrollTop;
-            const viewportHeight = el.clientHeight;
-            const start = findStartIndex(scrollTop);
-            const end = findEndIndex(scrollTop + viewportHeight, start);
-
-            // Track which keys remain visible
-            const stillVisible = new Set();
-            for (let i = start; i < end; i++) {
+        function render() {
+            if (isMasonry) return renderMasonry();
+            const total = isFlex ? lines.length : data.length;
+            if (!total) { clearRows(); setHeight(topSpacer, 0); setHeight(botSpacer, 0); return; }
+            const vh = scrollEl.clientHeight;
+            if (!vh) return;                                     // defer until sized
+            ready = true;
+
+            const eff = Math.max(0, scrollEl.scrollTop - regionTop());
+            let startUnit = findStart(eff, total) - overscan;
+            if (startUnit < 0) startUnit = 0;
+            let endUnit = findStart(eff + vh, total) + 1 + overscan;
+            if (endUnit > total) endUnit = total;
+
+            setHeight(topSpacer, cumulative[startUnit]);
+            setHeight(botSpacer, cumulative[total] - cumulative[endUnit]);
+
+            // Resolve the item range for these units.
+            const startItem = isFlex ? lines[startUnit].start : startUnit;
+            const endItem = isFlex ? lines[endUnit - 1].end : endUnit;
+
+            const visible = new Set();
+            const keys = [];
+            for (let i = startItem; i < endItem; i++) {
                 const item = data[i];
                 if (item == null) continue;
                 const key = keyFn(item);
-                if (key == null) continue; // skip un-keyable rows
-                stillVisible.add(key);
-
-                let node = rendered.get(key);
-                if (!node) {
-                    node = mountRow(i);
-                    if (!node) continue;
-                    rendered.set(key, node);
-                    spacer.appendChild(node);
-                    // x-data on the row needs the parent scope (where the
-                    // source array lives) to resolve, so we MUST init after
-                    // append, not before.
-                    Alpine.initTree(node);
-                    // Measure on next frame so Alpine has bound everything.
-                    requestAnimationFrame(() => measureRow(key, node));
-                }
-                node.style.top = cumulative[i] + 'px';
-                node.dataset.virtualIndex = i;
+                if (key == null) continue;
+                visible.add(key);
+                keys.push(key);
+                let entry = rendered.get(key);
+                if (!entry) entry = mountRow(item, key);
+                else if (entry.scope[itemName] !== item) entry.scope[itemName] = item;  // rebind by key
+                host.insertBefore(entry.node, botSpacer);        // keep DOM order = data order
+            }
+            for (const [key, entry] of rendered) {
+                if (!visible.has(key)) removeRow(key, entry);
             }
 
-            // Remove rows no longer in the window
-            for (const [key, node] of rendered) {
-                if (!stillVisible.has(key)) {
-                    node.remove();
-                    rendered.delete(key);
-                }
+            // Measure anything not yet measured, then reconcile offsets once.
+            scheduleMeasure(keys);
+        }
+
+        // Masonry: render items whose packed box intersects the viewport,
+        // absolutely positioned at their computed (x, y, w).
+        function renderMasonry() {
+            if (!data.length) { clearRows(); sizer.style.height = '0px'; return; }
+            const vh = scrollEl.clientHeight;
+            if (!vh) return;                                     // defer until sized
+            ready = true;
+            sizer.style.height = totalHeight + 'px';
+
+            const opx = overscan * avgH();
+            const winTop = scrollEl.scrollTop - opx;
+            const winBot = scrollEl.scrollTop + vh + opx;
+            // First candidate whose top could reach the window (bounded by tallest item).
+            let lo = 0, hi = sortedTop.length;
+            const target = winTop - maxItemH;
+            while (lo < hi) { const mid = (lo + hi) >>> 1; if (pos[sortedTop[mid]].y < target) lo = mid + 1; else hi = mid; }
+
+            const visible = new Set();
+            const keys = [];
+            for (let k = lo; k < sortedTop.length; k++) {
+                const i = sortedTop[k];
+                const p = pos[i];
+                if (p.y > winBot) break;
+                if (p.y + p.h < winTop) continue;
+                const item = data[i];
+                if (item == null) continue;
+                const key = keyFn(item);
+                if (key == null) continue;
+                visible.add(key);
+                keys.push(key);
+                let entry = rendered.get(key);
+                if (!entry) entry = mountRow(item, key);
+                else if (entry.scope[itemName] !== item) entry.scope[itemName] = item;
+                const s = entry.node.style;
+                s.position = 'absolute';
+                s.left = p.x + 'px';
+                s.top = p.y + 'px';
+                s.width = p.w + 'px';
+            }
+            for (const [key, entry] of rendered) {
+                if (!visible.has(key)) removeRow(key, entry);
             }
+            scheduleMeasure(keys);
         }
 
-        function mountRow(index) {
-            const tplChild = template.content.firstElementChild;
-            if (!tplChild) return null;
-            const node = tplChild.cloneNode(true);
-            node.style.position = 'absolute';
-            node.style.left = '0';
-            node.style.right = '0';
-            // Inject a per-row Alpine scope. Because we reference the source
-            // expression with the index baked in via a getter, Alpine tracks
-            // the dependency and re-renders this row when its data updates.
-            const scopeExpr = `{ get ${itemName}() { return (${sourceExpr})[${index}]; } }`;
-            // Merge with any existing x-data on the cloned root.
-            const existing = node.getAttribute('x-data');
-            node.setAttribute('x-data', existing ? `Object.assign({}, ${scopeExpr}, ${existing})` : scopeExpr);
-            // Note: caller must Alpine.initTree(node) AFTER appending to the
-            // DOM, otherwise the scope can't resolve identifiers (e.g. the
-            // source array) from outer x-data contexts.
-            return node;
+        function mountRow(item, key) {
+            const tpl = template.content.firstElementChild;
+            const node = tpl.cloneNode(true);
+            host.insertBefore(node, anchor);                     // connect before init
+            const scope = Alpine.reactive({ [itemName]: item });
+            const removeScope = Alpine.addScopeToNode(node, scope);
+            Alpine.initTree(node);
+            const entry = { node, scope, removeScope };
+            rendered.set(key, entry);
+            return entry;
+        }
+
+        function removeRow(key, entry) {
+            entry.removeScope && entry.removeScope();
+            Alpine.destroyTree && Alpine.destroyTree(entry.node);
+            entry.node.remove();
+            rendered.delete(key);
+        }
+
+        function clearRows() {
+            for (const [key, entry] of rendered) removeRow(key, entry);
+        }
+
+        // ---- Measurement ----
+
+        let measureScheduled = false;
+        function scheduleMeasure(keys) {
+            if (isMasonry && heightFn) return;                   // heights known from data
+            // Only measure rows we haven't sized yet.
+            const pending = [];
+            for (const key of keys) {
+                const need = isFlex ? (!heights.has(key) || !widths.has(key)) : !heights.has(key);
+                if (need && rendered.has(key)) pending.push(key);
+            }
+            if (!pending.length || measureScheduled) return;
+            measureScheduled = true;
+            requestAnimationFrame(() => {
+                measureScheduled = false;
+                let changed = false;
+                for (const key of pending) {
+                    const entry = rendered.get(key);
+                    if (entry && measureRow(key, entry.node)) changed = true;
+                }
+                if (changed) { rebuild(); render(); }
+            });
         }
 
         function measureRow(key, node) {
-            if (!node.isConnected) return;
-            const h = node.offsetHeight;
-            if (!h) return;
+            if (!node.isConnected) return false;
+            const h = measureHeight(node);
+            if (!h) return false;
+            let changed = false;
             const prev = heights.get(key);
-            if (prev === h) return;
-            if (prev !== undefined) measuredSum -= prev;
-            else measuredCount++;
-            measuredSum += h;
-            heights.set(key, h);
-            // Recompute cumulative offsets and re-render so positions reflect
-            // the new heights AND any rows now in/out of the visible window.
-            rebuildCumulative();
-            renderVisible();
+            if (prev !== h) {
+                if (prev !== undefined) measuredSum -= prev;
+                else measuredCount++;
+                measuredSum += h;
+                heights.set(key, h);
+                changed = true;
+            }
+            if (isFlex) {
+                const w = node.offsetWidth;
+                if (w && widths.get(key) !== w) { widths.set(key, w); changed = true; }
+            }
+            return changed;
+        }
+
+        // display:contents rows (grid-table) have no box — measure the union of
+        // their cells. Everything else uses offsetHeight.
+        function measureHeight(node) {
+            if (getComputedStyle(node).display === 'contents') {
+                let top = Infinity, bottom = -Infinity;
+                for (const c of node.children) {
+                    const r = c.getBoundingClientRect();
+                    if (r.top < top) top = r.top;
+                    if (r.bottom > bottom) bottom = r.bottom;
+                }
+                return bottom > top ? bottom - top : 0;
+            }
+            return node.offsetHeight;
+        }
+
+        // ---- Geometry helpers ----
+
+        // Scroll-content position where the virtualized region begins (accounts
+        // for a static/sticky header above the rows).
+        function regionTop() {
+            const s = scrollEl.getBoundingClientRect();
+            const t = topSpacer.getBoundingClientRect();
+            return t.top - s.top + scrollEl.scrollTop;
+        }
+        function contentWidth() {
+            const c = getComputedStyle(scrollEl);
+            return scrollEl.clientWidth - parseFloat(c.paddingLeft || 0) - parseFloat(c.paddingRight || 0);
         }
+        function gapX() {
+            const g = getComputedStyle(scrollEl);
+            return parseFloat(g.columnGap || g.gap || 0) || 0;
+        }
+        function gapY() {
+            const g = getComputedStyle(scrollEl);
+            return parseFloat(g.rowGap || g.gap || 0) || 0;
+        }
+
+        // ---- Reactive source ----
 
-        // --- Reactive data source subscription ---
-        const sourceGetter = evaluateLater(sourceExpr);
+        const getSource = evaluateLater(sourceExpr);
         effect(() => {
-            sourceGetter((value) => {
+            getSource((value) => {
                 data = Array.isArray(value) ? value : (value ? Array.from(value) : []);
-                // When the data identity or length changes, drop any rendered
-                // rows whose keys no longer exist in the new data.
-                const validKeys = new Set();
-                for (const item of data) {
-                    if (item != null) validKeys.add(keyFn(item));
-                }
-                for (const [key, node] of rendered) {
-                    if (!validKeys.has(key)) {
-                        node.remove();
-                        rendered.delete(key);
-                    }
-                }
-                rebuildCumulative();
-                renderVisible();
+                // Drop rendered rows whose key no longer exists.
+                const valid = new Set();
+                for (const item of data) if (item != null) valid.add(keyFn(item));
+                for (const [key, entry] of rendered) if (!valid.has(key)) removeRow(key, entry);
+                rebuild();
+                render();
             });
         });
 
-        // --- Scroll + resize handlers ---
+        // ---- Scroll / resize ----
+
         let scrollScheduled = false;
         const onScroll = () => {
             if (scrollScheduled) return;
             scrollScheduled = true;
-            requestAnimationFrame(() => {
-                scrollScheduled = false;
-                renderVisible();
-            });
+            requestAnimationFrame(() => { scrollScheduled = false; render(); });
         };
-        el.addEventListener('scroll', onScroll, { passive: true });
+        scrollEl.addEventListener('scroll', onScroll, { passive: true });
 
-        const ro = new ResizeObserver(() => renderVisible());
-        ro.observe(el);
+        let resizeTimer = null;
+        const ro = new ResizeObserver(() => {
+            if (!ready) { render(); return; }                    // first paint once sized
+            clearTimeout(resizeTimer);
+            resizeTimer = setTimeout(() => { rebuild(); render(); }, 100);  // debounced re-pack
+        });
+        ro.observe(scrollEl);
 
         cleanup(() => {
-            el.removeEventListener('scroll', onScroll);
+            scrollEl.removeEventListener('scroll', onScroll);
             ro.disconnect();
-            for (const [, node] of rendered) node.remove();
-            rendered.clear();
-            spacer.remove();
+            clearTimeout(resizeTimer);
+            clearRows();
+            if (isMasonry) sizer.remove();
+            else { topSpacer.remove(); botSpacer.remove(); }
         });
     });
 
 }
 
-// Build a key-evaluator function for a given itemName + keyExpr.
-// `keyFn(item)` returns the row's key. Falls back to identity if it fails.
+// ---- Module helpers ----
+
+function detectMode(host) {
+    const tag = host.tagName;
+    if (tag === 'TBODY' || tag === 'THEAD' || tag === 'TFOOT' || tag === 'TABLE') return 'table';
+    const disp = getComputedStyle(host).display;
+    if (disp.includes('grid')) return 'grid';
+    if (disp.includes('flex')) return 'flex';
+    return 'block';
+}
+
+function makeSpacer(mode, colCount) {
+    let s;
+    if (mode === 'table') {
+        s = document.createElement('tr');
+        const td = document.createElement('td');
+        if (colCount > 1) td.colSpan = colCount;
+        td.style.cssText = 'padding:0;border:0;height:0';
+        s.appendChild(td);
+    } else {
+        s = document.createElement('div');
+        if (mode === 'grid') s.style.gridColumn = '1 / -1';
+        else if (mode === 'flex') s.style.flex = '0 0 100%';
+        s.style.width = '100%';
+    }
+    s.dataset.virtualSpacer = '';
+    s.setAttribute('aria-hidden', 'true');
+    s.style.height = '0px';
+    s.style.padding = '0';
+    s.style.margin = '0';
+    s.style.border = '0';
+    s.style.background = 'none';
+    s.style.pointerEvents = 'none';
+    return s;
+}
+
+function setHeight(spacer, px) {
+    const h = Math.max(0, px) + 'px';
+    spacer.style.height = h;
+    if (spacer.firstElementChild && spacer.tagName === 'TR') spacer.firstElementChild.style.height = h;
+}
+
+// keyFn(item) returns the row's key. Falls back to identity on failure.
 function buildKeyFn(itemName, keyExpr) {
     try {
-        // eslint-disable-next-line no-new-func
         const fn = new Function(itemName, `return (${keyExpr});`);
-        return (item) => {
-            try { return fn(item); } catch { return item; }
-        };
+        return (item) => { try { return fn(item); } catch { return item; } };
     } catch {
         return (item) => item;
     }
@@ -295,17 +531,14 @@ function ensureVirtualPluginInitialized() {
     initializeVirtualPlugin();
 }
 
-// Expose on window for loader to call if needed
 window.ensureVirtualPluginInitialized = ensureVirtualPluginInitialized;
 
-// Handle both DOMContentLoaded and alpine:init
 if (document.readyState === 'loading') {
     document.addEventListener('DOMContentLoaded', ensureVirtualPluginInitialized);
 }
 
 document.addEventListener('alpine:init', ensureVirtualPluginInitialized);
 
-// If Alpine is already initialized when this script loads, initialize immediately
 if (window.Alpine && typeof window.Alpine.directive === 'function') {
     setTimeout(ensureVirtualPluginInitialized, 0);
 } else {