@svgrid/grid 3.0.8 → 3.0.9

package/dist/filtering/excel-filters.js

@@ -151,6 +151,41 @@ function scanInTokens(value) {
 // pull in SvGrid.svelte, which is a runtime cost (and a bundler hazard) for
 // anything that only wants operator semantics.
 export { ALL_FILTER_OPERATORS, SET_OPERATOR_IDS, VALUELESS_OPERATOR_IDS, RANGE_OPERATOR_IDS, isSetOperator, isValuelessOperator, isRangeOperator, } from './filter-operator-catalogue.js';
+/**
+ * A text test, remembered per distinct cell text.
+ *
+ * The text operators fold every cell (lowercase, and for non-ASCII text NFD
+ * plus diacritic stripping) before comparing, and a column the user filters
+ * is usually a category - region, status, owner - with a handful of distinct
+ * values over every row. Folding each row again was most of a 1M-row filter
+ * (417 ms). The answer depends only on the cell's text, so it is kept per
+ * text. A column that turns out mostly unique (more than half of the first
+ * 2,048 lookups missed) stops remembering and tests directly, and the memo
+ * never grows past MEMO_CAP entries.
+ */
+const MEMO_CAP = 16384;
+function memoText(test) {
+    let memo = new Map();
+    let lookups = 0;
+    let hits = 0;
+    return (cellValue) => {
+        const s = typeof cellValue === 'string' ? cellValue : String(cellValue ?? '');
+        if (memo === null)
+            return test(s);
+        lookups++;
+        const known = memo.get(s);
+        if (known !== undefined) {
+            hits++;
+            return known;
+        }
+        const result = test(s);
+        if (memo.size < MEMO_CAP)
+            memo.set(s, result);
+        if (lookups >= 2048 && hits * 2 < lookups)
+            memo = null;
+        return result;
+    };
+}
 /**
  * Compile a filter once, then test many rows against it.
  *
@@ -168,23 +203,23 @@ export function compileExcelFilter(filter, options) {
     const needle = fold(filter.value);
     switch (filter.operator) {
         case 'contains':
-            return (cellValue) => fold(cellValue).includes(needle);
+            return memoText((s) => fold(s).includes(needle));
         case 'notContains':
             // An empty needle is no constraint (mirrors `contains` returning true),
             // so nothing is excluded until the user types something.
             if (needle === '')
                 return () => true;
-            return (cellValue) => !fold(cellValue).includes(needle);
+            return memoText((s) => !fold(s).includes(needle));
         case 'equals':
-            return (cellValue) => fold(cellValue) === needle;
+            return memoText((s) => fold(s) === needle);
         case 'notEquals':
             if (needle === '')
                 return () => true;
-            return (cellValue) => fold(cellValue) !== needle;
+            return memoText((s) => fold(s) !== needle);
         case 'startsWith':
-            return (cellValue) => fold(cellValue).startsWith(needle);
+            return memoText((s) => fold(s).startsWith(needle));
         case 'endsWith':
-            return (cellValue) => fold(cellValue).endsWith(needle);
+            return memoText((s) => fold(s).endsWith(needle));
         case 'regex': {
             // Case-insensitive by default (matches the accent/case-folded feel of
             // the other text operators). An invalid pattern matches nothing rather

package/dist/index.d.ts

@@ -215,6 +215,7 @@ export { createHyperFormulaSheet, type HyperFormulaSheet, type HyperFormulaSheet
 export { createCollaboration, broadcastChannelTransport, type CollabUser, type CollabCell, type CollabPresence, type CollabMessage, type CollabTransport, type Collaboration, } from './collaboration.js';
 export { createServerDataSource, type ServerDataSource, type ServerSelectionRule, type ServerRequest, type ServerResult, type ServerController, type ServerControllerOptions, type ServerState, type ServerSortModel, type ServerFilterModel, type ServerAggFn, type ServerAggregation, type ServerGroupRow, type ServerLeafRow, type ServerMoreRow, type ServerFooterRow, type ServerSkeletonRow, type ServerGrandTotalRow, type ServerPlaceholderRow, type ServerDisplayRow, type ServerDetailRow, } from './server-data-source.js';
 export { createBlockCache, createRowPlaceholder, rowPlaceholderState, type BlockCache, type BlockCacheOptions, type BlockCacheState, type BlockFetchResult, type BlockState, } from './server-block-cache.js';
+export { createWindowedData, windowedSourceOf, isWindowedData, type WindowedSource, } from './windowed-data.js';
 export { toServerFilterColumns, type GridRowModel, type GridFilterState, type GridRowModelSort, } from './row-model.js';
 export { createNamedViews, memoryViews, localStorageViews, attachAutoSavedView, type SavedView, type ViewStorage, type NamedViews, type AutoSavedViewOptions, } from './named-views.js';
 export { resolveCellFormat, computeColumnStat, lerpColor, rgba, contrastText, formatNeedsStats, formatsNeedingStats, type ConditionalFormat, type ConditionalFormatSpec, type ColorScaleFormat, type ColorScaleStop, type ScaleBounds, type DataBarFormat, type IconSetFormat, type RuleFormat, type ResolvedCellFormat, } from './conditional-formatting.js';

package/dist/index.js

@@ -255,6 +255,7 @@ export { createHyperFormulaSheet, } from './hyperformula-adapter.js';
 export { createCollaboration, broadcastChannelTransport, } from './collaboration.js';
 export { createServerDataSource, } from './server-data-source.js';
 export { createBlockCache, createRowPlaceholder, rowPlaceholderState, } from './server-block-cache.js';
+export { createWindowedData, windowedSourceOf, isWindowedData, } from './windowed-data.js';
 export { toServerFilterColumns, } from './row-model.js';
 export { createNamedViews, memoryViews, localStorageViews, attachAutoSavedView, } from './named-views.js';
 export { resolveCellFormat, computeColumnStat, lerpColor, rgba, contrastText, formatNeedsStats, formatsNeedingStats, } from './conditional-formatting.js';

package/dist/selection.d.ts

@@ -1,8 +1,8 @@
 import { type RowData, type TableFeatures } from "./index.js";
 import "./sv-grid-scrollbar.js";
 export declare function createSelection<TFeatures extends TableFeatures = TableFeatures, TData extends RowData = RowData>(ctx: any): {
-    isRowSelected: (rowId: string) => any;
-    toggleRowSelectionById: (rowId: string) => void;
+    isRowSelected: (rowId: string, original?: unknown) => any;
+    toggleRowSelectionById: (rowId: string, original?: unknown) => void;
     toggleSelectAllRows: () => void;
     setSelectAllRows: (select: boolean) => void;
     setActiveCell: (rowIndex: number, colIndex: number) => void;

package/dist/selection.js

@@ -6,21 +6,33 @@ import "./sv-grid-scrollbar.js";
 import { getColumnBaseValue, isGroupRow, } from "./cell-values.js";
 import { expandRectToMerges, originOf, endOf } from "./merges.js";
 export function createSelection(ctx) {
-    function isRowSelected(rowId) {
+    /**
+     * A selection model needs the row's data. The body passes the row it is
+     * drawing as `original`; without it the row is looked up by id, a scan of
+     * every row - on a server model's windowed million rows, once per drawn
+     * row, that scan held the page for seconds after a sort.
+     */
+    function rowOriginal(rowId) {
+        const row = ctx.allRows.find((r) => r.id === rowId);
+        return row ? { found: true, original: row.original } : { found: false };
+    }
+    function isRowSelected(rowId, original) {
         const model = ctx.props.rowSelectionModel;
         if (model) {
-            const row = ctx.allRows.find((r) => r.id === rowId);
-            return row ? model.isSelected(rowId, row.original) : false;
+            if (original !== undefined)
+                return model.isSelected(rowId, original);
+            const hit = rowOriginal(rowId);
+            return hit.found ? model.isSelected(rowId, hit.original) : false;
         }
         return Boolean(ctx.rowSelectionState[rowId]);
     }
-    function toggleRowSelectionById(rowId) {
+    function toggleRowSelectionById(rowId, original) {
         const model = ctx.props.rowSelectionModel;
         if (model) {
-            const row = ctx.allRows.find((r) => r.id === rowId);
-            if (!row)
+            const hit = original !== undefined ? { found: true, original } : rowOriginal(rowId);
+            if (!hit.found)
                 return;
-            model.toggle(rowId, row.original, !model.isSelected(rowId, row.original));
+            model.toggle(rowId, hit.original, !model.isSelected(rowId, hit.original));
             return;
         }
         ctx.grid.setRowSelection((prev) => ({ ...prev, [rowId]: !prev[rowId] }));
@@ -446,8 +458,20 @@ export function createSelection(ctx) {
     }
     /** Look up a column by id without depending on `buildApi`'s private
      *  closure (those helpers don't exist at this scope). */
+    // id -> column, rebuilt when the column list changes. Called per header
+    // cell as columns scroll into view, so a linear `find` made every scroll
+    // frame cost more the more columns the grid has.
+    let columnsById = new Map();
+    let columnsByIdFor = null;
     function findColumnById(columnId) {
-        return ctx.allColumns.find((c) => c.id === columnId);
+        const all = ctx.allColumns;
+        if (all !== columnsByIdFor) {
+            columnsById = new Map();
+            for (const c of all)
+                columnsById.set(c.id, c);
+            columnsByIdFor = all;
+        }
+        return columnsById.get(columnId);
     }
     function onCellPointerDown(rowIndex, colIndex, event) {
         if (event.button !== 0)

package/dist/server-block-cache.d.ts

@@ -1,35 +1,3 @@
-/**
- * Block cache for server-backed rows - the engine behind infinite scrolling.
- *
- * Paging asks for "page 3". Infinite scrolling asks a different question: the
- * user is looking at rows 4,000 to 4,020 of a table with a million rows, so
- * fetch the block that covers them, keep a bounded number of recently-seen
- * blocks, and render something sensible for every row nobody has fetched yet.
- * That is all this module does, in plain TypeScript with no Svelte and no DOM.
- *
- * The shape of the problem (and most of the vocabulary) is the same one every
- * grid with a server row model solves, so the options here are deliberately
- * recognisable: `blockSize`, `maxBlocksInCache`, `maxConcurrentRequests`,
- * `blockLoadDebounceMs`, `initialRowCount`, `overflowRows`.
- *
- * Three things it takes seriously:
- *
- *   - **Unloaded rows still have to render.** `rows()` always returns a dense
- *     array, with a shared sentinel object in every slot that has no data. The
- *     grid recognises those (see {@link rowPlaceholderState}) and draws a
- *     skeleton or a retry affordance instead of an empty row, so the scrollbar
- *     never lies and scrolling never leaves a hole.
- *   - **The row count may be unknown.** A backend that cannot cheaply count
- *     says so (omit `rowCount`, or send `-1`) and the list grows by a block at
- *     a time until a short block proves where the end is.
- *   - **Requests are not free.** In-flight blocks are deduplicated, at most
- *     `maxConcurrentRequests` are open at once, a fast scroll debounces rather
- *     than firing a request per frame, and blocks abandoned by eviction or
- *     purge are aborted.
- *
- * Enterprise's server row model runs one of these per group level; the free
- * flat controller runs exactly one.
- */
 /**
  * The mark that says "this row is not data yet".
  *
@@ -155,6 +123,13 @@ export type BlockCache<TData> = {
     setViewport(startIndex: number, endIndex: number): void;
     /** The dense row array to hand the grid. Placeholders fill unloaded slots. */
     rows(): ReadonlyArray<TData>;
+    /**
+     * The same rows as windowed data (see windowed-data.ts): `length` is the
+     * row count and each entry is read through `getRow` when the grid asks for
+     * it, so handing it over costs O(1) whatever the count. A new array per
+     * change, like `rows()`.
+     */
+    windowedRows(): ReadonlyArray<TData>;
     /** One row, without building the array. Returns a placeholder when unloaded. */
     getRow(index: number): TData | typeof LOADING_ROW | typeof FAILED_ROW;
     rowCount(): number | null;

package/dist/server-block-cache.js

@@ -30,6 +30,7 @@
  * Enterprise's server row model runs one of these per group level; the free
  * flat controller runs exactly one.
  */
+import { createWindowedData } from './windowed-data.js';
 /**
  * The mark that says "this row is not data yet".
  *
@@ -99,6 +100,7 @@ export function createBlockCache(options) {
     let debounceTimer = null;
     let emitScheduled = false;
     let rowsCache = null;
+    let windowedCache = null;
     const blockOf = (rowIndex) => Math.floor(rowIndex / blockSize);
     const startOf = (blockIndex) => blockIndex * blockSize;
     /**
@@ -156,7 +158,7 @@ export function createBlockCache(options) {
      * mutations notifies once. Every mutating path ends here.
      */
     function emit() {
-        rowsCache = null; // rebuilt lazily, on the next read
+        rowsCache = windowedCache = null; // rebuilt lazily, on the next read
         if (disposed || emitScheduled)
             return;
         emitScheduled = true;
@@ -281,6 +283,15 @@ export function createBlockCache(options) {
                 ensureBlock(i);
         }
     }
+    function rowAt(index) {
+        const block = blocks.get(blockOf(index));
+        if (!block)
+            return LOADING_ROW;
+        if (block.status === 'failed')
+            return FAILED_ROW;
+        const row = block.rows[index - startOf(blockOf(index))];
+        return row ?? LOADING_ROW;
+    }
     function abortAll() {
         for (const block of blocks.values())
             block.controller?.abort();
@@ -330,15 +341,13 @@ export function createBlockCache(options) {
             rowsCache = out;
             return out;
         },
-        getRow(index) {
-            const block = blocks.get(blockOf(index));
-            if (!block)
-                return LOADING_ROW;
-            if (block.status === 'failed')
-                return FAILED_ROW;
-            const row = block.rows[index - startOf(blockOf(index))];
-            return row ?? LOADING_ROW;
+        windowedRows() {
+            if (windowedCache)
+                return windowedCache;
+            windowedCache = createWindowedData(currentLength(), (i) => rowAt(i));
+            return windowedCache;
         },
+        getRow: rowAt,
         rowCount: () => (countKnown ? count : null),
         lastRowKnown: () => countKnown,
         retryFailed() {
@@ -376,7 +385,7 @@ export function createBlockCache(options) {
             blocks.clear();
             count = null;
             countKnown = false;
-            rowsCache = null;
+            rowsCache = windowedCache = null;
             fetchViewport();
             emit();
         },
@@ -524,7 +533,7 @@ export function createBlockCache(options) {
                 controller: null,
             });
         }
-        rowsCache = null;
+        rowsCache = windowedCache = null;
     }
     /** Forget every block from `fromBlock` on, aborting any in flight. */
     function dropLoadedFrom(fromBlock) {
@@ -534,6 +543,6 @@ export function createBlockCache(options) {
             block.controller?.abort();
             blocks.delete(index);
         }
-        rowsCache = null;
+        rowsCache = windowedCache = null;
     }
 }

package/dist/server-data-source.js

@@ -53,7 +53,9 @@ export function createServerDataSource(source, options) {
     function emitFromCache() {
         if (!cache || disposed)
             return;
-        const rows = cache.rows();
+        // Windowed: the grid reads only the rows it shows, so a block landing
+        // costs the same at 100M rows as at 10K.
+        const rows = cache.windowedRows();
         state.rows = rows;
         state.rowCount = cache.rowCount();
         state.lastRowKnown = cache.lastRowKnown();

package/dist/server.d.ts

@@ -10,4 +10,5 @@
  */
 export { createServerDataSource, type ServerDataSource, type ServerSelectionRule, type ServerRequest, type ServerResult, type ServerController, type ServerControllerOptions, type ServerState, type ServerSortModel, type ServerFilterModel, type ServerAggFn, type ServerAggregation, type ServerGroupRow, type ServerLeafRow, type ServerMoreRow, type ServerFooterRow, type ServerSkeletonRow, type ServerGrandTotalRow, type ServerPlaceholderRow, type ServerDisplayRow, type ServerDetailRow, } from './server-data-source.js';
 export { createBlockCache, createRowPlaceholder, rowPlaceholderState, type BlockCache, type BlockCacheOptions, type BlockCacheState, type BlockFetchResult, type BlockState, } from './server-block-cache.js';
+export { createWindowedData, windowedSourceOf, isWindowedData, type WindowedSource, } from './windowed-data.js';
 export { toServerFilterColumns, type GridRowModel, type GridFilterState, type GridRowModelSort, } from './row-model.js';

package/dist/server.js

@@ -10,4 +10,5 @@
  */
 export { createServerDataSource, } from './server-data-source.js';
 export { createBlockCache, createRowPlaceholder, rowPlaceholderState, } from './server-block-cache.js';
+export { createWindowedData, windowedSourceOf, isWindowedData, } from './windowed-data.js';
 export { toServerFilterColumns, } from './row-model.js';

package/dist/spreadsheet.js

@@ -88,6 +88,13 @@ const OVERLAY_CLASS = 'sv-cell-border-overlay';
  *  every relevant DOM mutation inside the grid, and whenever the action
  *  options update. */
 function apply(root, opts) {
+    // Merges here are colspan / rowspan on the rendered cells, which only the
+    // table algorithm honours: keep this grid's rows in table layout (the
+    // flex-row rules in SvGrid.css skip a table marked this way).
+    for (const table of root.querySelectorAll('table.sv-grid-table')) {
+        if (table.getAttribute('data-row-layout') !== 'table')
+            table.setAttribute('data-row-layout', 'table');
+    }
     // ---- 1. Clean up anything the LAST run added -----------------------
     for (const td of root.querySelectorAll(`td[${MARK}]`)) {
         td.removeAttribute('colspan');

package/dist/validate.js

@@ -155,17 +155,9 @@ export function validateGridConfig(input) {
             'so summary bars will under-report. Remove `treeData` and set ' +
             '`gantt.parentField` instead.');
     }
-    // ---- 7. Pinning that column virtualization will hide ----------------------
-    // Documented incompatibility: the virtualizer recycles column DOM nodes, so
-    // sticky pinning cannot survive it. `columnVirtualization` defaults to ON,
-    // which means the natural way to write this silently does nothing.
-    const pinned = (input.initialColumnPinning?.left?.length ?? 0) +
-        (input.initialColumnPinning?.right?.length ?? 0);
-    if (pinned > 0 && input.columnVirtualization !== false) {
-        messages.push('[svgrid] `initialColumnPinning` is set while column virtualization is on ' +
-            '(its default), so the pinned columns will not stick - the virtualizer ' +
-            'recycles column nodes. Add `columnVirtualization={false}`.');
-    }
+    // (7. was "pinning versus column virtualization". Pinned columns now render
+    // as their own runs beside the virtual window, so the pair is supported and
+    // there is nothing to warn about.)
     // ---- 8. Server-mode contracts left half-wired -----------------------------
     // Each of these makes the grid hand control to the consumer. Miss the other
     // half and the feature looks broken rather than unconfigured.

package/dist/virtualization/column-virtualizer.d.ts

@@ -4,6 +4,10 @@ export declare function createColumnVirtualizer(input: {
     viewportWidth: number;
     scrollOffset?: number;
     overscan?: number;
+    /** Columns kept behind the scroll direction; defaults to `overscan`. */
+    overscanBehind?: number;
+    /** Fewest columns left ahead of a scroll before the window moves. */
+    overscanMin?: number;
     /** Either a uniform size (number) or a per-column size function. */
     estimateSize?: number | ColumnSizeEstimator;
 }): {

package/dist/virtualization/column-virtualizer.js

@@ -6,6 +6,8 @@ export function createColumnVirtualizer(input) {
         viewportHeight: input.viewportWidth,
         scrollOffset: input.scrollOffset ?? 0,
         overscan: input.overscan ?? 4,
+        overscanBehind: input.overscanBehind,
+        overscanMin: input.overscanMin,
     });
     return {
         ...virtualizer,

package/dist/virtualization/types.d.ts

@@ -15,8 +15,28 @@ export type VirtualizerOptions = {
      */
     estimateSize: number | ((index: number) => number);
     overscan?: number;
+    /**
+     * Items kept on the side the scroll is moving away from (`overscan` is kept
+     * ahead of it). Defaults to `overscan`, a symmetric window. Before the
+     * first scroll there is no direction and both sides get `overscan`.
+     */
+    overscanBehind?: number;
+    /**
+     * Keep the rendered window while a scroll leaves at least this many items
+     * rendered ahead of it, and move the window only when the scroll runs past
+     * that: the window is then rebuilt with the full `overscan` ahead, so it
+     * moves `overscan - overscanMin + 1` items at a time instead of one. Each
+     * move costs about the same whether one item enters or several, so fewer,
+     * larger moves are less work, and the scroll frames in between change
+     * nothing. A window built at rest, or after a jump to items outside the
+     * rendered window, carries `overscanMin` instead of `overscan`. Undefined
+     * moves the window on every item boundary, always with `overscan`.
+     */
+    overscanMin?: number;
     viewportHeight: number;
     scrollOffset?: number;
+    /** Internal: the sign of the last scroll movement (-1, 0, 1). */
+    scrollDirection?: number;
 };
 export type VirtualizerState = {
     items: Array<VirtualItem>;

package/dist/virtualization/virtualizer.js

@@ -5,6 +5,8 @@ function sameOptions(a, b) {
     return (a.count === b.count &&
         a.estimateSize === b.estimateSize &&
         (a.overscan ?? 6) === (b.overscan ?? 6) &&
+        a.overscanBehind === b.overscanBehind &&
+        a.overscanMin === b.overscanMin &&
         a.viewportHeight === b.viewportHeight &&
         (a.scrollOffset ?? 0) === (b.scrollOffset ?? 0));
 }
@@ -107,11 +109,12 @@ function buildVariableItems(startIndex, endIndex, offsets) {
     }
     return items;
 }
-function createState(options, 
+/** The items under the viewport at the current scroll offset, before any
+ *  overscan. */
+function visibleRange(options, 
 /** Pre-built cumulative offsets for the variable-size path. */
 offsets) {
     const count = Math.max(options.count, 0);
-    const overscan = Math.max(options.overscan ?? 6, 0);
     const viewportHeight = Math.max(options.viewportHeight, 0);
     if (typeof options.estimateSize === 'function' && offsets) {
         const totalSize = offsets[count] ?? 0;
@@ -140,29 +143,47 @@ offsets) {
                 hi = mid;
         }
         const visibleEnd = Math.max(lo - 1, visibleStart);
-        const startIndex = count === 0 ? 0 : clamp(visibleStart - overscan, 0, count - 1);
-        const endIndex = count === 0 ? -1 : clamp(visibleEnd + overscan, 0, count - 1);
-        return {
-            items: endIndex >= startIndex ? buildVariableItems(startIndex, endIndex, offsets) : [],
-            totalSize,
-            startIndex,
-            endIndex,
-            scrollOffset,
-            viewportHeight,
-        };
+        return { count, viewportHeight, totalSize, scrollOffset, visibleStart, visibleEnd, uniformSize: 0 };
     }
     // Uniform-size fast path (original behavior).
-    const estimateSize = Math.max(typeof options.estimateSize === 'number' ? options.estimateSize : 1, 1);
-    const totalSize = count * estimateSize;
+    const uniformSize = Math.max(typeof options.estimateSize === 'number' ? options.estimateSize : 1, 1);
+    const totalSize = count * uniformSize;
     const maxOffset = Math.max(totalSize - viewportHeight, 0);
     const scrollOffset = clamp(options.scrollOffset ?? 0, 0, maxOffset);
-    const visibleStart = Math.floor(scrollOffset / estimateSize);
-    const visibleCount = Math.ceil(viewportHeight / estimateSize);
+    const visibleStart = Math.floor(scrollOffset / uniformSize);
+    const visibleCount = Math.ceil(viewportHeight / uniformSize);
     const visibleEnd = Math.min(visibleStart + visibleCount, Math.max(count - 1, 0));
-    const startIndex = count === 0 ? 0 : clamp(visibleStart - overscan, 0, count - 1);
-    const endIndex = count === 0 ? -1 : clamp(visibleEnd + overscan, 0, count - 1);
+    return { count, viewportHeight, totalSize, scrollOffset, visibleStart, visibleEnd, uniformSize };
+}
+function createState(options, 
+/** Pre-built cumulative offsets for the variable-size path. */
+offsets, 
+/** The scroll moved on from the window already rendered. With
+ *  `overscanMin`, only then does the full `overscan` go ahead; a window
+ *  built at rest or after a jump carries `overscanMin`, so a thumb drag
+ *  that jumps every frame renders no more than it needs. */
+scrolling = false) {
+    const full = Math.max(options.overscan ?? 6, 0);
+    const overscan = options.overscanMin === undefined || scrolling ? full : clamp(options.overscanMin, 0, full);
+    // The overscan goes ahead of the scroll and `overscanBehind` behind it:
+    // items behind the movement were just scrolled past, and a horizontal
+    // scroll that kept three columns on each side drew ~40% more cells than it
+    // needed to (350 vs 275 in the wide benchmark).
+    const behind = Math.min(Math.max(options.overscanBehind ?? full, 0), overscan);
+    const direction = options.scrollDirection ?? 0;
+    const overscanBefore = direction > 0 ? behind : overscan;
+    const overscanAfter = direction < 0 ? behind : overscan;
+    const { count, viewportHeight, totalSize, scrollOffset, visibleStart, visibleEnd, uniformSize } = visibleRange(options, offsets);
+    const startIndex = count === 0 ? 0 : clamp(visibleStart - overscanBefore, 0, count - 1);
+    const endIndex = count === 0 ? -1 : clamp(visibleEnd + overscanAfter, 0, count - 1);
+    let items = [];
+    if (endIndex >= startIndex) {
+        items = uniformSize > 0
+            ? buildUniformItems(startIndex, endIndex, uniformSize)
+            : buildVariableItems(startIndex, endIndex, offsets);
+    }
     return {
-        items: endIndex >= startIndex ? buildUniformItems(startIndex, endIndex, estimateSize) : [],
+        items,
         totalSize,
         startIndex,
         endIndex,
@@ -200,13 +221,54 @@ export function createVirtualizer(initial) {
     function emit() {
         listeners.forEach((listener) => listener());
     }
-    function recalc() {
-        const next = createState(options, getOffsets());
+    function recalc(scrolling = false) {
+        const next = createState(options, getOffsets(), scrolling);
         if (sameState(state, next))
             return;
+        // Hand back the previous item object for a row whose index, offset, size
+        // and slot did not change. The grid's row {#each} is keyed by slot, so a
+        // row that stays in the window keeps its <tr>, but a new item object
+        // still invalidated everything that row and its cells derive from it:
+        // every scroll frame re-checked ~300 cells to render the two that came
+        // into view, and Svelte's dependency marking was most of the frame's
+        // script time (measured 4.8 of 8.3 ms on a 100k-row grid).
+        if (state.items.length > 0 && next.items.length > 0) {
+            const first = state.items[0].index;
+            const items = next.items;
+            for (let i = 0; i < items.length; i += 1) {
+                const item = items[i];
+                const prev = state.items[item.index - first];
+                if (prev && prev.index === item.index && prev.start === item.start && prev.size === item.size && prev.key === item.key) {
+                    items[i] = prev;
+                }
+            }
+        }
         state = next;
         emit();
     }
+    /**
+     * What a scroll does to the window already rendered, with `overscanMin`:
+     * 'hold' while that window still covers the visible items plus
+     * `overscanMin` ahead of the scroll, 'move' once the scroll runs past that
+     * (the window moves on with the full overscan ahead), and 'jump' when the
+     * visible items are nowhere in it. Without `overscanMin` every scroll moves
+     * the window.
+     */
+    function scrollStep() {
+        const min = options.overscanMin;
+        if (min === undefined || state.items.length === 0)
+            return 'move';
+        const ahead = clamp(min, 0, Math.max(options.overscan ?? 6, 0));
+        const { count, viewportHeight, totalSize, visibleStart, visibleEnd } = visibleRange(options, getOffsets());
+        if (count === 0 || viewportHeight !== state.viewportHeight || totalSize !== state.totalSize)
+            return 'jump';
+        if (visibleStart > state.endIndex || visibleEnd < state.startIndex)
+            return 'jump';
+        const direction = options.scrollDirection ?? 0;
+        const needStart = Math.max(visibleStart - (direction < 0 ? ahead : 0), 0);
+        const needEnd = Math.min(visibleEnd + (direction > 0 ? ahead : 0), count - 1);
+        return state.startIndex <= needStart && state.endIndex >= needEnd ? 'hold' : 'move';
+    }
     return {
         setOptions(next) {
             const merged = { ...options, ...next };
@@ -229,10 +291,14 @@ export function createVirtualizer(initial) {
             recalc();
         },
         setScrollOffset(scrollOffset) {
-            if ((options.scrollOffset ?? 0) === scrollOffset)
+            const previous = options.scrollOffset ?? 0;
+            if (previous === scrollOffset)
                 return;
-            options = { ...options, scrollOffset };
-            recalc();
+            options = { ...options, scrollOffset, scrollDirection: scrollOffset > previous ? 1 : -1 };
+            const step = scrollStep();
+            if (step === 'hold')
+                return;
+            recalc(step === 'move');
         },
         setViewportHeight(viewportHeight) {
             if (options.viewportHeight === viewportHeight)

package/dist/windowed-brand.d.ts

@@ -0,0 +1,22 @@
+/**
+ * What marks an array as windowed data, and how to tell (windowed-data.ts has
+ * the full story). Kept apart from createWindowedData so code that only asks
+ * "is this windowed?" - the controller, the core's per-update paths - does not
+ * pull in the windowed row model that createWindowedData installs.
+ */
+export type WindowedSource<T> = {
+    /** The number of rows, loaded or not. */
+    readonly length: number;
+    /** The entry at `index`: a loaded row, a placeholder, or undefined. */
+    at(index: number): T | undefined;
+};
+/**
+ * An array of `length` entries read through `at(i)`: a real `Array` (a Proxy
+ * over an empty one) carrying the windowed mark. Each call returns a new
+ * array identity, which is how a source tells the grid its rows changed.
+ */
+export declare function makeWindowedArray<T>(length: number, at: (index: number) => T | undefined): T[];
+/** The source behind windowed data, or null for an ordinary array. */
+export declare function windowedSourceOf<T>(data: unknown): WindowedSource<T> | null;
+/** True for windowed data. */
+export declare function isWindowedData(data: unknown): boolean;