@svgrid/enterprise 3.0.2 → 3.1.0

package/dist/server/server-row-model.js

@@ -0,0 +1,1551 @@
+/**
+ * The Server-Side Row Model.
+ *
+ * One `getRows` contract, any depth of grouping or tree, and every level
+ * scrolls: the top level is one block cache, each expanded group is another,
+ * and the rows the user has not scrolled to are placeholders that cost
+ * nothing to hold. Sorting, filtering, expanding, refreshing, transactions
+ * (Phase 4) and selection across rows that were never loaded (Phase 5) all
+ * hang off this one object, and `<SvGrid rowModel={ctl} />` wires the lot.
+ *
+ * What the free grid gives it: the datasource contract (`ServerRequest` /
+ * `ServerResult`), the block cache (`createBlockCache`), the placeholder mark
+ * (`createRowPlaceholder`) and the four seams `rowModel` plugs into. What this
+ * file adds is the TREE: a store per route, a flatten that splices expanded
+ * groups' children into one display list, and the rules for which stores a
+ * sort, a filter or a refresh actually touches.
+ *
+ * Headless and framework-agnostic on purpose. Nothing here imports Svelte;
+ * `onChange` and `subscribe` are how the outside learns anything changed.
+ *
+ * `createServerGroupModel` (the previous model, block-append with a "Load N
+ * more" button) is still exported for anyone on it; this one supersedes it.
+ */
+import { createBlockCache, createRowPlaceholder, rowPlaceholderState, toServerFilterColumns,
+// The subpath, not the root: the root re-exports SvGrid.svelte, which
+// would land in every bundle and test that touches this model.
+ } from '@svgrid/grid/server';
+import { nudgeServerRowModel } from './enable.js';
+import { buildPivotResultColumns } from './server-pivot.js';
+import { fillMessage, resolveServerGroupMessages } from './messages.js';
+import { createServerSelectionModel, } from './server-selection.js';
+import { fromCallbackSelectionState, isCallbackSelectionState, } from './svgrid-adapter.js';
+const routeKey = (route) => JSON.stringify(route);
+const LOADING_ROW = createRowPlaceholder('loading', {
+    kind: 'placeholder',
+    state: 'loading',
+});
+const FAILED_ROW = createRowPlaceholder('failed', {
+    kind: 'placeholder',
+    state: 'failed',
+});
+/** The fixed id of the grand-total display row, so a transaction can address it. */
+export const GRAND_TOTAL_ROW_ID = 'sv-grand-total';
+/** The prefix of a group footer's id; the rest is the group route. */
+export const GROUP_TOTAL_ROW_ID_PREFIX = 'sv-group-total:';
+/** Plain type-aware ordering for `clientSideSort`. */
+function compareValues(a, b) {
+    if (a == null && b == null)
+        return 0;
+    if (a == null)
+        return 1;
+    if (b == null)
+        return -1;
+    if (typeof a === 'number' && typeof b === 'number')
+        return a - b;
+    if (a instanceof Date && b instanceof Date)
+        return a.getTime() - b.getTime();
+    return String(a).localeCompare(String(b), undefined, { numeric: true });
+}
+/**
+ * Build the Server-Side Row Model over a `ServerDataSource`: lazy grouping
+ * and tree data one level at a time, a block cache per level, aggregates,
+ * child counts, grand totals, pivot, paging, transactions and a selection
+ * that reaches rows the grid never loaded. Hand the result to
+ * `<SvGrid rowModel>`. Enterprise: nudges when no licence key is set.
+ */
+export function createServerRowModel(source, options) {
+    // Runs without a key; shows the watermark + one console notice.
+    nudgeServerRowModel();
+    let groupBy = [...(options.groupBy ?? [])];
+    let aggregations = [...(options.aggregations ?? [])];
+    let pivotBy = [...(options.pivotBy ?? [])];
+    let pivotMode = !!options.pivotMode;
+    let pivotRowTotals = options.pivotRowTotals ?? false;
+    const pivotSeparator = options.pivotFieldSeparator ?? '_';
+    /** The union of every `pivotResultFields` seen since the last reset, in order. */
+    let pivotFields = [];
+    /** Verbatim column defs from the backend, when it sent them instead of fields. */
+    let pivotColumnsFromSource = null;
+    const treeData = !!options.treeData;
+    if (treeData && (!options.getRowId || !options.hasChildren)) {
+        throw new Error('createServerRowModel: treeData requires getRowId and hasChildren');
+    }
+    const getRowId = options.getRowId;
+    const hasChildren = options.hasChildren;
+    const childCountOf = options.childCount;
+    const skeletonRows = Math.max(1, options.skeletonRows ?? 3);
+    const paging = options.pagination ?? null;
+    let pageIndex = 0;
+    let pageSize = Math.max(1, paging?.pageSize ?? 100);
+    /** Rows the pager counts, as of the last flatten. */
+    let pagerRowCount = 0;
+    const groupFooters = !!options.groupFooters;
+    const grandTotalRow = options.grandTotalRow;
+    const debug = !!options.debug;
+    let sortModel = [];
+    let filterModel = {};
+    const stores = new Map();
+    const expanded = new Set();
+    /** Group routes that have been through `isGroupOpenByDefault` once. */
+    const seenGroups = new Set();
+    let autoExpand = false;
+    let grandTotal = undefined;
+    /**
+     * The grand total on hand is from before an in-place refresh of the top
+     * level or a bulk edit, so the next root block asks for a fresh one. The
+     * old one stays on screen until it lands rather than blinking out.
+     */
+    let grandTotalStale = false;
+    /** Leaves whose detail panel is open, by the id `getRowId` gives them. */
+    const openDetails = new Set();
+    let rootError = null;
+    let disposed = false;
+    /** Writes the server has not answered yet; `saving` is "any". */
+    let writesInFlight = 0;
+    // Generation guard: bumped on any reset so responses for the previous shape
+    // are discarded when they land.
+    let generation = 0;
+    // A single in-flight budget across every level. The block cache caps
+    // concurrency per instance; with one instance per route that would let ten
+    // open groups fire twenty requests, so the gate lives here.
+    const maxConcurrent = Math.max(1, options.maxConcurrentRequests ?? 2);
+    let inFlight = 0;
+    const waiting = [];
+    const acquire = () => {
+        if (inFlight < maxConcurrent) {
+            inFlight += 1;
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => waiting.push(() => { inFlight += 1; resolve(); }));
+    };
+    const release = () => {
+        inFlight -= 1;
+        waiting.shift()?.();
+    };
+    const subscribers = new Set();
+    let lastViewport = [0, 0];
+    let segments = [];
+    let emitScheduled = false;
+    // ----------------------------------------------------------- stores
+    function levelOf(route) {
+        return route.length;
+    }
+    function isLeafLevel(level) {
+        return !treeData && level >= groupBy.length;
+    }
+    /** The group row `route` names, if its parent level has it loaded. */
+    function parentRowOf(route) {
+        if (route.length === 0)
+            return undefined;
+        const parent = stores.get(routeKey(route.slice(0, -1)));
+        if (!parent)
+            return undefined;
+        const key = route[route.length - 1];
+        const rows = parent.cache.rows();
+        for (const child of rows) {
+            if (rowPlaceholderState(child))
+                continue;
+            if (child.kind === 'group' && child.key === key)
+                return child.data;
+        }
+        return undefined;
+    }
+    function toChildren(route, startRow, rows) {
+        const level = levelOf(route);
+        const groupField = groupBy[level];
+        const storeKey = routeKey(route);
+        return rows.map((data, i) => {
+            const isGroup = treeData ? hasChildren(data) : level < groupBy.length;
+            if (isGroup) {
+                const key = treeData
+                    ? getRowId(data)
+                    : ((v) => (v == null ? '' : String(v)))(data[groupField]);
+                const agg = {};
+                for (const a of aggregations)
+                    agg[a.col] = data[a.col];
+                return {
+                    kind: 'group',
+                    key,
+                    field: treeData ? '' : groupField,
+                    aggregates: agg,
+                    childCount: childCountOf?.(data),
+                    data,
+                };
+            }
+            const id = getRowId ? `${storeKey}:${getRowId(data)}` : `${storeKey}:${startRow + i}`;
+            return { kind: 'leaf', id, data };
+        });
+    }
+    function createStore(route) {
+        const level = levelOf(route);
+        const params = options.levelParams?.(level, route) ?? {};
+        const blockSize = Math.max(1, params.blockSize ?? options.blockSize ?? 100);
+        const loadMore = !!params.loadMore;
+        const infinite = !loadMore && params.infinite !== false;
+        const key = routeKey(route);
+        const gen = generation;
+        const store = {
+            route,
+            key,
+            level,
+            infinite,
+            loadMore,
+            blockSize,
+            refreshPending: false,
+            seenBlocks: new Map(),
+            cache: null,
+        };
+        store.cache = createBlockCache({
+            blockSize,
+            maxBlocksInCache: params.maxBlocksInCache ?? options.maxBlocksInCache,
+            // The model gates concurrency itself, across levels.
+            maxConcurrentRequests: Number.MAX_SAFE_INTEGER,
+            blockLoadDebounceMs: options.blockLoadDebounceMs,
+            initialRowCount: Math.max(1, params.initialRowCount ?? skeletonRows),
+            fetch: async (startRow, endRow, signal) => {
+                await acquire();
+                try {
+                    if (disposed || gen !== generation || signal.aborted) {
+                        throw new Error('stale');
+                    }
+                    const needsGrandTotal = route.length === 0 && grandTotalRow != null && (grandTotal === undefined || grandTotalStale);
+                    const request = {
+                        startRow,
+                        endRow,
+                        pageIndex: Math.floor(startRow / blockSize),
+                        pageSize: blockSize,
+                        sortModel,
+                        filterModel,
+                        groupBy,
+                        groupKeys: route,
+                        aggregations,
+                        ...(pivotMode ? { pivotBy, pivotMode: true } : {}),
+                        ...(needsGrandTotal ? { needsGrandTotal: true } : {}),
+                        ...(route.length ? { parentRow: parentRowOf(route) } : {}),
+                        ...(options.context !== undefined ? { context: options.context } : {}),
+                        signal,
+                    };
+                    let result;
+                    try {
+                        result = await source.getRows(request);
+                    }
+                    catch (err) {
+                        if (!disposed && gen === generation) {
+                            if (route.length === 0)
+                                rootError = err;
+                            options.onLoadError?.(route, err);
+                        }
+                        throw err;
+                    }
+                    if (disposed || gen !== generation)
+                        throw new Error('stale');
+                    if (route.length === 0) {
+                        rootError = null;
+                        if ('grandTotal' in result) {
+                            grandTotal = result.grandTotal ?? null;
+                            grandTotalStale = false;
+                        }
+                    }
+                    if (pivotMode) {
+                        if (result.pivotResultColumns)
+                            pivotColumnsFromSource = result.pivotResultColumns;
+                        for (const f of result.pivotResultFields ?? []) {
+                            if (!pivotFields.includes(f))
+                                pivotFields.push(f);
+                        }
+                    }
+                    return {
+                        rows: toChildren(route, startRow, result.rows),
+                        rowCount: result.rowCount >= 0 ? result.rowCount : undefined,
+                    };
+                }
+                finally {
+                    release();
+                }
+            },
+            onChange: (s) => {
+                if (disposed || gen !== generation)
+                    return;
+                // Runs once per block that just landed: open-by-default, and the
+                // debug log. Scanning only those blocks keeps this O(blockSize)
+                // rather than O(rows) on every change.
+                for (const index of diffBlocks(store))
+                    openByDefaultIn(store, index);
+                if (store.refreshPending && !s.loading) {
+                    store.refreshPending = false;
+                    options.onStoreRefreshed?.(route);
+                }
+                // A level that is not infinite loads itself completely once it knows
+                // how big it is.
+                if (!infinite && !loadMore && s.lastRowKnown && s.rowCount != null) {
+                    store.cache.setViewport(0, Math.max(0, s.rowCount - 1));
+                }
+                scheduleEmit();
+            },
+        });
+        stores.set(key, store);
+        return store;
+    }
+    function ensureStore(route) {
+        return stores.get(routeKey(route)) ?? createStore(route);
+    }
+    function dropSubtree(route) {
+        const prefix = routeKey(route);
+        for (const [key, store] of [...stores]) {
+            if (key === prefix || isUnder(key, route)) {
+                store.cache.dispose();
+                stores.delete(key);
+            }
+        }
+    }
+    function isUnder(key, route) {
+        // Routes are JSON arrays; a descendant's key starts with the parent's
+        // elements. Compare structurally rather than by string prefix so that
+        // ["a"] is not mistaken for a parent of ["ab"].
+        const parsed = JSON.parse(key);
+        if (parsed.length <= route.length)
+            return false;
+        return route.every((seg, i) => parsed[i] === seg);
+    }
+    /** Block indices that became `loaded` since the last call. Logs when `debug`. */
+    function diffBlocks(store) {
+        const now = new Map(store.cache.getCacheState().map((b) => [b.blockIndex, b.status]));
+        const landed = [];
+        for (const [index, status] of now) {
+            const before = store.seenBlocks.get(index);
+            if (before === status)
+                continue;
+            if (status === 'loaded')
+                landed.push(index);
+            // eslint-disable-next-line no-console -- opt-in diagnostics, see the debug option
+            if (debug)
+                console.debug(`[svgrid ssrm] ${routeKey(store.route)} block ${index}: ${status}`);
+        }
+        if (debug) {
+            for (const index of store.seenBlocks.keys()) {
+                // eslint-disable-next-line no-console -- opt-in diagnostics, see the debug option
+                if (!now.has(index))
+                    console.debug(`[svgrid ssrm] ${routeKey(store.route)} block ${index}: evicted`);
+            }
+        }
+        store.seenBlocks = now;
+        return landed;
+    }
+    /**
+     * Open the groups in a freshly landed block that should start open: by
+     * `isGroupOpenByDefault`, by an `expandAll({ includeUnloaded })` in force,
+     * or because they are unbalanced. Once per group, so a block that is
+     * re-fetched does not re-open something the user closed.
+     */
+    function openByDefaultIn(store, blockIndex) {
+        const start = blockIndex * store.blockSize;
+        for (let i = start; i < start + store.blockSize; i += 1) {
+            const raw = store.cache.getRow(i);
+            if (rowPlaceholderState(raw))
+                continue;
+            const child = raw;
+            if (child.kind !== 'group')
+                continue;
+            const childRoute = [...store.route, child.key];
+            const ck = routeKey(childRoute);
+            if (seenGroups.has(ck))
+                continue;
+            seenGroups.add(ck);
+            const unbalanced = !!options.allowUnbalancedGroups && child.key === '';
+            if (unbalanced || autoExpand || options.isGroupOpenByDefault?.(childRoute, child.data)) {
+                expandGroup(childRoute);
+            }
+        }
+    }
+    // ---------------------------------------------------------- flatten
+    function flatten() {
+        const display = [];
+        const grid = [];
+        segments = [];
+        const pushRow = (d, data) => {
+            display.push(d);
+            grid.push(toGridRow(d, data));
+        };
+        if (grandTotalRow === 'top' && grandTotal)
+            pushRow(grandTotalDisplay(grandTotal), grandTotal);
+        const bodyStart = display.length;
+        /**
+         * A `loadMore` level shows its loaded prefix and a "more" row; rows
+         * past the first placeholder are not the grid's to scroll into.
+         */
+        const loadedPrefix = (rows) => {
+            let n = 0;
+            while (n < rows.length && !rowPlaceholderState(rows[n]))
+                n += 1;
+            return n;
+        };
+        const walk = (store, from = 0, to = Number.POSITIVE_INFINITY) => {
+            const rows = store.cache.rows();
+            const end = Math.min(rows.length, to, store.loadMore ? loadedPrefix(rows) : Number.POSITIVE_INFINITY);
+            let segStart = from;
+            let dispStart = display.length;
+            const flushSegment = (upTo) => {
+                if (upTo > segStart) {
+                    segments.push({ store, displayStart: dispStart, storeStart: segStart, length: upTo - segStart });
+                }
+            };
+            for (let i = from; i < end; i += 1) {
+                const child = rows[i];
+                const ph = rowPlaceholderState(child);
+                if (ph) {
+                    pushRow(ph === 'failed' ? FAILED_ROW : LOADING_ROW);
+                    continue;
+                }
+                if (child.kind === 'leaf') {
+                    pushRow({ kind: 'leaf', id: child.id, level: store.level, route: store.route, data: child.data }, child.data);
+                    if (openDetails.size) {
+                        const masterId = childId(child);
+                        if (openDetails.has(masterId)) {
+                            pushRow({ kind: 'detail', id: `${child.id}:detail`, level: store.level, route: store.route, masterId, master: child.data }, child.data);
+                        }
+                    }
+                    continue;
+                }
+                const childRoute = [...store.route, child.key];
+                const ck = routeKey(childRoute);
+                const childStore = stores.get(ck);
+                const isExp = expanded.has(ck);
+                const unbalanced = !!options.allowUnbalancedGroups && child.key === '';
+                const hidden = isExp && (unbalanced || !!options.hideOpenParents);
+                if (!hidden) {
+                    pushRow({
+                        kind: 'group',
+                        id: ck,
+                        path: childRoute,
+                        field: child.field,
+                        key: child.key,
+                        level: store.level,
+                        expanded: isExp,
+                        ...(pivotMode && !treeData && childRoute.length >= groupBy.length ? { expandable: false } : {}),
+                        // The expander shows a spinner for the level opening, not for
+                        // a block far down an open level that a deep scroll asked for.
+                        loading: !!childStore && childStore.cache.getCacheState().some((b) => b.blockIndex === 0 && b.status === 'loading'),
+                        aggregates: child.aggregates,
+                        ...(child.childCount != null ? { childCount: child.childCount } : {}),
+                        data: child.data,
+                    }, child.data);
+                }
+                if (isExp && childStore) {
+                    // This store's run ends here; the child's rows follow, then a new
+                    // run of this store begins.
+                    flushSegment(i + 1);
+                    walk(childStore);
+                    if (groupFooters && !hidden) {
+                        pushRow({
+                            kind: 'footer',
+                            id: GROUP_TOTAL_ROW_ID_PREFIX + ck,
+                            level: store.level + 1,
+                            path: childRoute,
+                            key: child.key,
+                            aggregates: child.aggregates,
+                            data: child.data,
+                        }, child.data);
+                    }
+                    segStart = i + 1;
+                    dispStart = display.length;
+                }
+            }
+            flushSegment(end);
+            if (store.loadMore) {
+                const count = store.cache.rowCount();
+                const loaded = end;
+                if (count == null || loaded < count) {
+                    pushRow({
+                        kind: 'more',
+                        id: `sv-more:${store.key}`,
+                        level: store.level,
+                        path: store.route,
+                        remaining: count == null ? store.blockSize : count - loaded,
+                        loading: store.cache.getCacheState().some((b) => b.status === 'loading'),
+                    });
+                }
+            }
+        };
+        const root = stores.get(routeKey([]));
+        if (root) {
+            if (paging && !paging.paginateChildRows) {
+                // A page of top-level rows. The root rows array is already sized to
+                // the count (placeholders for what has not loaded), so the page
+                // exists before its block does.
+                const count = root.cache.rowCount() ?? root.cache.rows().length;
+                pagerRowCount = count;
+                const start = Math.min(pageIndex * pageSize, Math.max(0, count - 1));
+                walk(root, start, start + pageSize);
+            }
+            else {
+                walk(root);
+            }
+        }
+        if (paging?.paginateChildRows) {
+            // A page of the flattened tree. Cut the body and re-base the segments
+            // that cross into the page; the grand total stays on every page.
+            const bodyLength = display.length - bodyStart;
+            pagerRowCount = bodyLength;
+            const start = Math.min(pageIndex * pageSize, Math.max(0, bodyLength - 1));
+            const stop = Math.min(bodyLength, start + pageSize);
+            display.splice(bodyStart + stop);
+            display.splice(bodyStart, start);
+            grid.splice(bodyStart + stop);
+            grid.splice(bodyStart, start);
+            const cut = [];
+            for (const seg of segments) {
+                const a = Math.max(seg.displayStart, bodyStart + start);
+                const b = Math.min(seg.displayStart + seg.length, bodyStart + stop);
+                if (b <= a)
+                    continue;
+                cut.push({
+                    store: seg.store,
+                    displayStart: a - start,
+                    storeStart: seg.storeStart + (a - seg.displayStart),
+                    length: b - a,
+                });
+            }
+            segments = cut;
+        }
+        if (grandTotalRow === 'bottom' && grandTotal)
+            pushRow(grandTotalDisplay(grandTotal), grandTotal);
+        return { display, grid };
+    }
+    function pagination() {
+        if (!paging)
+            return null;
+        return {
+            pageIndex,
+            pageSize,
+            rowCount: pagerRowCount,
+            pageCount: Math.max(1, Math.ceil(pagerRowCount / pageSize)),
+        };
+    }
+    /**
+     * A display row as the grid sees it: the row's own fields at the top
+     * level plus the `__group` marker. Footers and the grand total also carry
+     * the flags the grid keys its `sv-grid-group-footer-row` /
+     * `sv-grid-grand-total-row` styling on, so they look like the client
+     * model's totals rather than like ordinary rows.
+     */
+    function toGridRow(d, data) {
+        if (d.kind === 'placeholder')
+            return d;
+        const row = { ...data, __group: d };
+        if (d.kind === 'footer')
+            row.__groupFooter = true;
+        if (d.kind === 'grandTotal') {
+            row.__groupFooter = true;
+            row.__grandTotal = true;
+        }
+        return row;
+    }
+    function grandTotalDisplay(data) {
+        const agg = {};
+        for (const a of aggregations)
+            agg[a.col] = data[a.col];
+        return { kind: 'grandTotal', id: GRAND_TOTAL_ROW_ID, level: 0, aggregates: agg, data };
+    }
+    function pinnedGrandTotal() {
+        if (!grandTotal)
+            return undefined;
+        return [toGridRow(grandTotalDisplay(grandTotal), grandTotal)];
+    }
+    // ------------------------------------------------------------- state
+    let current = {
+        displayRows: [],
+        gridRows: [],
+        groupBy: [...groupBy],
+        aggregations: [...aggregations],
+        rowCount: null,
+        loading: true,
+        saving: false,
+        error: null,
+        sortModel,
+        filterModel,
+        expandedGroups: [],
+        openDetails: [],
+        grandTotal: null,
+        pivotBy: [...pivotBy],
+        pivotMode,
+        pivotResultFields: [],
+        pagination: pagination(),
+    };
+    function buildState() {
+        const root = stores.get(routeKey([]));
+        const { display, grid } = flatten();
+        const rootLoaded = !!root && root.cache.getCacheState().some((b) => b.status === 'loaded');
+        return {
+            displayRows: display,
+            gridRows: grid,
+            groupBy: [...groupBy],
+            aggregations: [...aggregations],
+            rowCount: root?.cache.rowCount() ?? null,
+            loading: !!root && !rootLoaded && root.cache.getCacheState().some((b) => b.status === 'loading'),
+            saving: writesInFlight > 0,
+            error: rootError,
+            sortModel,
+            filterModel,
+            expandedGroups: [...expanded],
+            openDetails: [...openDetails],
+            grandTotal: grandTotal ?? null,
+            pivotBy: [...pivotBy],
+            pivotMode,
+            pivotResultFields: [...pivotFields],
+            pagination: pagination(),
+        };
+    }
+    function scheduleEmit() {
+        if (disposed || emitScheduled)
+            return;
+        emitScheduled = true;
+        queueMicrotask(() => {
+            emitScheduled = false;
+            if (disposed)
+                return;
+            current = buildState();
+            options.onChange?.(current);
+            for (const notify of subscribers)
+                notify();
+        });
+    }
+    // ------------------------------------------------------- operations
+    function applyViewport() {
+        const [start, end] = lastViewport;
+        for (const seg of segments) {
+            if (seg.store.loadMore)
+                continue;
+            const segEnd = seg.displayStart + seg.length - 1;
+            if (segEnd < start || seg.displayStart > end)
+                continue;
+            const from = Math.max(start, seg.displayStart) - seg.displayStart + seg.storeStart;
+            const to = Math.min(end, segEnd) - seg.displayStart + seg.storeStart;
+            seg.store.cache.setViewport(from, to);
+        }
+    }
+    /** Ask a level for its first block, so it shows something before any scroll. */
+    function primeStore(store) {
+        if (store.loadMore) {
+            store.cache.setViewport(0, store.blockSize - 1);
+            return;
+        }
+        const from = store.level === 0 && paging && !paging.paginateChildRows ? pageIndex * pageSize : 0;
+        store.cache.setViewport(from, from + Math.min(store.blockSize, skeletonRows) - 1);
+    }
+    function expandGroup(route) {
+        if (disposed)
+            return;
+        // Under pivot the innermost group rows ARE the result; there is nothing
+        // beneath them to fetch.
+        if (pivotMode && !treeData && route.length >= groupBy.length)
+            return;
+        const key = routeKey(route);
+        if (expanded.has(key))
+            return;
+        expanded.add(key);
+        const store = ensureStore(route);
+        // A known child count sizes the scrollbar (and the skeletons) right away.
+        const parent = parentRowOf(route);
+        const known = parent !== undefined ? childCountOf?.(parent) : undefined;
+        if (known != null && store.cache.rowCount() == null)
+            store.cache.setRowCount(known, true);
+        primeStore(store);
+        options.onGroupOpened?.(route);
+        scheduleEmit();
+    }
+    function collapseGroup(route) {
+        const key = routeKey(route);
+        if (!expanded.delete(key))
+            return;
+        if (options.purgeClosedGroups)
+            dropSubtree(route);
+        scheduleEmit();
+    }
+    /** Start over below `route` (or everywhere), keeping the expansion set. */
+    function rebuild(route = []) {
+        if (route.length === 0) {
+            // A full reset. Disposing every cache aborts every request, and the
+            // generation bump discards any that slipped past the abort.
+            generation += 1;
+            for (const s of stores.values())
+                s.cache.dispose();
+            stores.clear();
+            grandTotal = undefined;
+            grandTotalStale = false;
+            pivotFields = [];
+            pivotColumnsFromSource = null;
+        }
+        else {
+            dropSubtree(route);
+        }
+        const target = ensureStore(route);
+        primeStore(target);
+        // Expanded descendants come back too, each priming its own first block.
+        for (const key of expanded) {
+            const r = JSON.parse(key);
+            if (r.length > route.length && route.every((seg, i) => r[i] === seg))
+                primeStore(ensureStore(r));
+        }
+        scheduleEmit();
+    }
+    /** Which stores a sort touches, under the selective rules. */
+    function storesAffectedBySort(next) {
+        const all = [...stores.values()];
+        if (options.sortAllLevels || treeData)
+            return all;
+        const aggCols = new Set(aggregations.map((a) => a.col));
+        const levels = new Set();
+        let everything = false;
+        let leaves = false;
+        for (const s of next) {
+            const gi = groupBy.indexOf(s.id);
+            if (aggCols.has(s.id))
+                everything = true;
+            else if (gi >= 0)
+                levels.add(gi);
+            else
+                leaves = true;
+        }
+        // Clearing the sort has to put every level back to server order.
+        if (next.length === 0)
+            everything = true;
+        if (everything)
+            return all;
+        return all.filter((s) => levels.has(s.level) || (leaves && isLeafLevel(s.level)));
+    }
+    function sortLocally(store) {
+        const st = store.cache.getCacheState();
+        const count = store.cache.rowCount();
+        if (!store.cache.lastRowKnown() || count == null)
+            return false;
+        const loaded = st.filter((b) => b.status === 'loaded').length;
+        if (loaded * store.blockSize < count)
+            return false;
+        const rows = store.cache.rows().filter((r) => !rowPlaceholderState(r));
+        if (rows.length !== count)
+            return false;
+        const valueOf = (c, col) => c.data[col];
+        rows.sort((a, b) => {
+            for (const s of sortModel) {
+                const cmp = compareValues(valueOf(a, s.id), valueOf(b, s.id));
+                if (cmp !== 0)
+                    return s.desc ? -cmp : cmp;
+            }
+            return 0;
+        });
+        store.cache.applyRows(0, rows, count);
+        return true;
+    }
+    function setSort(next) {
+        sortModel = next;
+        for (const store of storesAffectedBySort(next)) {
+            if (options.clientSideSort && sortLocally(store))
+                continue;
+            store.refreshPending = true;
+            store.cache.refresh();
+        }
+        scheduleEmit();
+    }
+    function setFilter(next) {
+        const previous = filterModel;
+        filterModel = Array.isArray(next.columns)
+            ? { global: next.global, columns: toServerFilterColumns(next) }
+            : next;
+        if (!options.onlyRefreshFilteredGroups)
+            return rebuild();
+        // Selective: the levels whose column changed. Everything else keeps its
+        // stale counts, which is the documented trade.
+        const changed = new Set();
+        const prevCols = previous.columns ?? {};
+        const nextCols = filterModel.columns ?? {};
+        for (const c of new Set([...Object.keys(prevCols), ...Object.keys(nextCols)])) {
+            if (JSON.stringify(prevCols[c]) !== JSON.stringify(nextCols[c]))
+                changed.add(c);
+        }
+        const globalChanged = (previous.global ?? '') !== (filterModel.global ?? '');
+        const exprChanged = JSON.stringify(previous.expression) !== JSON.stringify(filterModel.expression);
+        const aggCols = new Set(aggregations.map((a) => a.col));
+        if (globalChanged || exprChanged || [...changed].some((c) => aggCols.has(c)))
+            return rebuild();
+        const levels = new Set();
+        let leaves = false;
+        for (const c of changed) {
+            const gi = groupBy.indexOf(c);
+            if (gi >= 0)
+                levels.add(gi);
+            else
+                leaves = true;
+        }
+        for (const store of stores.values()) {
+            if (levels.has(store.level) || (leaves && isLeafLevel(store.level))) {
+                store.refreshPending = true;
+                store.cache.refresh();
+            }
+        }
+        scheduleEmit();
+    }
+    function levelState(store) {
+        const blocks = store.cache.getCacheState();
+        return {
+            route: store.route,
+            level: store.level,
+            rowCount: store.cache.rowCount(),
+            lastRowKnown: store.cache.lastRowKnown(),
+            loading: blocks.some((b) => b.status === 'loading'),
+            failedBlocks: blocks.filter((b) => b.status === 'failed').map((b) => b.blockIndex),
+            blocks,
+        };
+    }
+    // ------------------------------------------------------ transactions
+    /** The id a transaction row goes by at a level: key at a group level, row id at a leaf level. */
+    function transactionId(store, row) {
+        if (typeof row === 'string')
+            return row;
+        if (getRowId) {
+            const id = getRowId(row);
+            if (id === GRAND_TOTAL_ROW_ID)
+                return id;
+        }
+        if (isLeafLevel(store.level) || treeData) {
+            if (!getRowId)
+                throw new Error('createServerRowModel: transactions need getRowId');
+            return getRowId(row);
+        }
+        const field = groupBy[store.level];
+        const v = row[field];
+        return v == null ? '' : String(v);
+    }
+    /** The id a CACHED child goes by, in the same terms. */
+    function childId(child) {
+        if (child.kind === 'group')
+            return child.key;
+        // Leaf ids are `${storeKey}:${rowId}`; the row id is the tail.
+        return getRowId ? getRowId(child.data) : child.id.slice(child.id.lastIndexOf(':') + 1);
+    }
+    function storeStatus(store) {
+        const blocks = store.cache.getCacheState();
+        if (blocks.length === 0)
+            return 'storeWaitingToLoad';
+        if (blocks.some((b) => b.status === 'loaded'))
+            return 'applied';
+        if (blocks.some((b) => b.status === 'loading'))
+            return 'storeLoading';
+        return 'storeLoadingFailed';
+    }
+    function applyTransaction(tx) {
+        const result = { status: 'applied', add: [], update: [], remove: [] };
+        if (disposed)
+            return { ...result, status: 'storeNotFound' };
+        if (options.isApplyTransaction && !options.isApplyTransaction(tx)) {
+            return { ...result, status: 'cancelled' };
+        }
+        const route = tx.route ?? [];
+        const store = stores.get(routeKey(route));
+        if (!store)
+            return { ...result, status: 'storeNotFound' };
+        const status = storeStatus(store);
+        if (status !== 'applied')
+            return { ...result, status };
+        // The grand total answers to its fixed id, on the root route only.
+        const isTotal = (row) => route.length === 0 && typeof row !== 'string' && !!getRowId && getRowId(row) === GRAND_TOTAL_ROW_ID;
+        for (const row of tx.update ?? []) {
+            if (isTotal(row)) {
+                grandTotal = row;
+                result.update.push(GRAND_TOTAL_ROW_ID);
+                continue;
+            }
+            const id = transactionId(store, row);
+            const index = store.cache.findIndex((c) => childId(c) === id);
+            if (index < 0)
+                continue;
+            const [child] = toChildren(route, index, [row]);
+            store.cache.patch(index, child);
+            result.update.push(id);
+        }
+        for (const row of tx.remove ?? []) {
+            if (isTotal(row)) {
+                grandTotal = null;
+                result.remove.push(GRAND_TOTAL_ROW_ID);
+                continue;
+            }
+            const id = transactionId(store, row);
+            const index = store.cache.findIndex((c) => childId(c) === id);
+            // Outside the cache means outside what we can show; when the count is
+            // known the row is simply not here, and the count stands until the
+            // caller says otherwise with `rowCount`.
+            if (index < 0)
+                continue;
+            const wasGroup = store.cache.getRow(index).kind === 'group';
+            if (store.cache.remove(index, 1) > 0) {
+                result.remove.push(id);
+                // A removed group takes its expansion and its cached children with it.
+                if (wasGroup) {
+                    const childRoute = [...route, id];
+                    expanded.delete(routeKey(childRoute));
+                    dropSubtree(childRoute);
+                }
+            }
+        }
+        if (tx.add && tx.add.length) {
+            const total = store.cache.rowCount();
+            const at = tx.addIndex ?? (total ?? store.cache.rows().length);
+            const children = toChildren(route, at, tx.add);
+            const placed = store.cache.insert(at, children);
+            if (placed)
+                for (const c of children)
+                    result.add.push(childId(c));
+            // Adding the grand total means setting it.
+            for (const row of tx.add)
+                if (isTotal(row))
+                    grandTotal = row;
+        }
+        if (typeof tx.rowCount === 'number')
+            store.cache.setRowCount(tx.rowCount, true);
+        // The parent group row shows this level's count beside its key; adds
+        // and removes move it by the net change. Aggregates stay as they were:
+        // a refresh of the parent recomputes them, as documented.
+        const delta = result.add.length - result.remove.length;
+        if (delta !== 0 && route.length > 0)
+            adjustChildCount(route, delta);
+        scheduleEmit();
+        return result;
+    }
+    function adjustChildCount(route, delta) {
+        const parent = stores.get(routeKey(route.slice(0, -1)));
+        if (!parent)
+            return;
+        const key = route[route.length - 1];
+        const index = parent.cache.findIndex((c) => c.kind === 'group' && c.key === key);
+        if (index < 0)
+            return;
+        const child = parent.cache.getRow(index);
+        if (child.kind !== 'group' || child.childCount == null)
+            return;
+        parent.cache.patch(index, { ...child, childCount: Math.max(0, child.childCount + delta) });
+    }
+    const asyncQueue = [];
+    let asyncTimer = null;
+    function flushAsyncTransactions() {
+        if (asyncTimer)
+            clearTimeout(asyncTimer);
+        asyncTimer = null;
+        if (asyncQueue.length === 0)
+            return;
+        const batch = asyncQueue.splice(0);
+        const results = [];
+        for (const item of batch) {
+            const result = applyTransaction(item.tx);
+            // A level still loading gets its transaction back in the queue for
+            // the next flush; nothing else is retried.
+            if (result.status === 'storeLoading' || result.status === 'storeWaitingToLoad') {
+                asyncQueue.push(item);
+                continue;
+            }
+            results.push(result);
+            item.callback?.(result);
+        }
+        if (results.length)
+            options.onAsyncTransactionsFlushed?.(results);
+        if (asyncQueue.length)
+            scheduleAsyncFlush();
+    }
+    function scheduleAsyncFlush() {
+        if (asyncTimer || disposed)
+            return;
+        asyncTimer = setTimeout(() => {
+            asyncTimer = null;
+            flushAsyncTransactions();
+        }, options.asyncTransactionWaitMs ?? 50);
+    }
+    /** Run one write with `saving` raised around it; the flag is "any write in flight". */
+    async function saving(write) {
+        writesInFlight += 1;
+        scheduleEmit();
+        try {
+            return await write();
+        }
+        finally {
+            writesInFlight -= 1;
+            scheduleEmit();
+        }
+    }
+    /** The level and index holding a leaf row with this id, searching loaded rows only. */
+    function locate(id) {
+        for (const store of stores.values()) {
+            const index = store.cache.findIndex((c) => childId(c) === id);
+            if (index >= 0)
+                return { store, index };
+        }
+        return null;
+    }
+    function updateRowData(id, patch, opts) {
+        const hit = locate(id);
+        if (!hit)
+            return false;
+        const current = hit.store.cache.getRow(hit.index);
+        const next = (opts?.replace ? patch : { ...current.data, ...patch });
+        const [child] = toChildren(hit.store.route, hit.index, [next]);
+        hit.store.cache.patch(hit.index, child);
+        scheduleEmit();
+        return true;
+    }
+    // --------------------------------------------------------- selection
+    const selectionModel = options.selection
+        ? createServerSelectionModel({
+            groupSelects: options.selection.groupSelects,
+            // The grid re-derives the header checkbox and the row ticks from a
+            // row-model notification, so a selection change is one.
+            onChange: scheduleEmit,
+            leafCount: groupLeafCount,
+        })
+        : null;
+    /**
+     * Leaves under a loaded group row, from its `count` aggregate (the same
+     * one `leafTotal` reads on the grand total); null without one, or when
+     * the group row is not loaded.
+     */
+    function groupLeafCount(route) {
+        const counter = aggregations.find((a) => a.fn === 'count');
+        if (!counter || route.length === 0)
+            return null;
+        const parent = stores.get(routeKey(route.slice(0, -1)));
+        if (!parent)
+            return null;
+        const key = route[route.length - 1];
+        const index = parent.cache.findIndex((c) => c.kind === 'group' && c.key === key);
+        if (index < 0)
+            return null;
+        const child = parent.cache.getRow(index);
+        if (child.kind !== 'group')
+            return null;
+        const n = Number(child.aggregates[counter.col]);
+        return Number.isFinite(n) ? n : null;
+    }
+    /** Where a grid row lives in selection terms: its parent route and its own id. */
+    function locateForSelection(row) {
+        const d = row.__group;
+        if (!d)
+            return null;
+        if (d.kind === 'group')
+            return { route: d.path.slice(0, -1), id: d.key, isGroup: true };
+        if (d.kind === 'leaf') {
+            return { route: d.route ?? [], id: getRowId ? getRowId(d.data) : d.id, isGroup: false };
+        }
+        return null;
+    }
+    /**
+     * How many leaves the whole result holds, for an honest select-all count:
+     * the root count when nothing is grouped, else the `count` aggregation
+     * on the grand total (the only place the server says it), else unknown.
+     */
+    function leafTotal() {
+        if (treeData || groupBy.length === 0)
+            return current.rowCount;
+        const counter = aggregations.find((a) => a.fn === 'count');
+        if (!counter || !grandTotal)
+            return null;
+        const n = Number(grandTotal[counter.col]);
+        return Number.isFinite(n) ? n : null;
+    }
+    const selectionAdapter = selectionModel
+        ? {
+            isSelected: (_rowId, row) => {
+                const at = locateForSelection(row);
+                return at ? selectionModel.isSelected(at.route, at.id) : false;
+            },
+            headerState: () => selectionModel.headerState(),
+            toggle: (_rowId, row, next) => {
+                const at = locateForSelection(row);
+                if (at)
+                    selectionModel.toggle(at.route, at.id, next, at.isGroup);
+            },
+            toggleAll: (next) => selectionModel.setAll(next),
+            selectedCount: () => selectionModel.selectedCount(leafTotal()),
+            bulkUpdate: (patch) => bulkUpdate(patch),
+        }
+        : undefined;
+    async function bulkUpdate(patch) {
+        if (!selectionModel)
+            throw new Error('createServerRowModel: bulkUpdate needs the `selection` option');
+        if (!source.updateWhere) {
+            throw new Error('createServerRowModel: the datasource does not implement updateWhere(), so a bulk edit ' +
+                'cannot reach rows the grid has not loaded');
+        }
+        const rule = selectionModel.getState();
+        // A nested rule is keyed level by level by the group columns; say which.
+        const changed = await source.updateWhere(filterModel, patch, 'selectAllChildren' in rule ? { ...rule, groupBy: [...groupBy] } : rule);
+        if (disposed)
+            return changed;
+        // Every level may have changed rows AND aggregates; reload them in place.
+        for (const store of stores.values()) {
+            store.refreshPending = true;
+            store.cache.refresh();
+        }
+        grandTotalStale = true;
+        scheduleEmit();
+        return changed;
+    }
+    // ------------------------------------------------------------ pivot
+    /**
+     * The columns that replace the grid's own while pivoting: the leading
+     * columns the app named, then one header group per pivot key with a value
+     * column per aggregation under it. Null outside pivot mode, or before the
+     * first pivoted response has said what fields exist.
+     */
+    function pivotResultColumns() {
+        if (!pivotMode)
+            return null;
+        const leading = options.pivotLeadingColumns ?? [];
+        if (pivotColumnsFromSource)
+            return [...leading, ...pivotColumnsFromSource];
+        if (pivotFields.length === 0)
+            return null;
+        return [
+            ...leading,
+            ...buildPivotResultColumns(pivotFields, aggregations, {
+                separator: pivotSeparator,
+                pivotResultColumn: options.pivotResultColumn,
+                rowTotals: pivotRowTotals,
+            }),
+        ];
+    }
+    // ---------------------------------------------------- the controller
+    // The id a leaf's detail is kept under: the app's row id, else the leaf's own.
+    const leafDetailId = (g) => (getRowId ? getRowId(g.data) : g.id.slice(g.id.lastIndexOf(':') + 1));
+    const nav = {
+        isGroup: (row) => row.__group?.kind === 'group',
+        level: (row) => row.__group && 'level' in row.__group ? row.__group.level : 0,
+        expanded: (row) => row.__group?.kind === 'group' ? row.__group.expanded : false,
+        onToggle: (row) => {
+            if (row.__group?.kind === 'group')
+                model.toggleGroup(row.__group);
+            else if (row.__group?.kind === 'more')
+                model.loadMoreChildren(row.__group.path);
+        },
+        // A leaf's detail, by the id the app gave the row; a detail row toggles its master.
+        toggleDetail: (row) => {
+            const g = row.__group;
+            if (g?.kind === 'leaf')
+                model.toggleDetail(leafDetailId(g));
+            else if (g?.kind === 'detail')
+                model.toggleDetail(g.masterId);
+        },
+        // Only a leaf has a detail to open; a group's expander is in the group column.
+        hasDetail: (row) => row.__group?.kind === 'leaf',
+        detailOpen: (row) => {
+            const g = row.__group;
+            return g?.kind === 'leaf' ? model.isDetailOpen(leafDetailId(g)) : false;
+        },
+    };
+    const model = {
+        refresh(opts) {
+            if (disposed)
+                return;
+            const route = opts?.route ?? [];
+            const store = stores.get(routeKey(route));
+            if (opts?.purge || !store)
+                return rebuild(route);
+            store.refreshPending = true;
+            // The top level re-read in place brings its aggregates back fresh;
+            // the grand total is one of them.
+            if (route.length === 0)
+                grandTotalStale = true;
+            store.cache.refresh();
+            scheduleEmit();
+        },
+        retryLoads() {
+            for (const store of stores.values())
+                store.cache.retryFailed();
+        },
+        setSort,
+        setFilter,
+        setGroupBy(next) {
+            model.setLayout({ groupBy: next });
+        },
+        setAggregations(next) {
+            model.setLayout({ aggregations: next });
+        },
+        setPivot(next) {
+            model.setLayout(next);
+        },
+        setLayout(next) {
+            if (disposed)
+                return;
+            const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+            const groupChanged = next.groupBy !== undefined && !same(next.groupBy, groupBy);
+            const aggChanged = next.aggregations !== undefined && !same(next.aggregations, aggregations);
+            const pivotChanged = (next.pivotBy !== undefined && !same(next.pivotBy, pivotBy)) ||
+                (next.pivotMode !== undefined && next.pivotMode !== pivotMode);
+            // The totals group is built from what is already loaded: no request.
+            if (next.pivotRowTotals !== undefined && next.pivotRowTotals !== pivotRowTotals) {
+                pivotRowTotals = next.pivotRowTotals;
+                if (!groupChanged && !aggChanged && !pivotChanged) {
+                    scheduleEmit();
+                    return;
+                }
+            }
+            if (!groupChanged && !aggChanged && !pivotChanged)
+                return;
+            if (next.groupBy)
+                groupBy = [...next.groupBy];
+            if (next.aggregations)
+                aggregations = [...next.aggregations];
+            if (next.pivotBy)
+                pivotBy = [...next.pivotBy];
+            if (next.pivotMode !== undefined)
+                pivotMode = next.pivotMode;
+            // New group columns make new rows, and pivoted group rows and plain
+            // group rows are different rows: neither keeps its open state. A
+            // change of aggregations alone keeps the tree open and refetches it.
+            if (groupChanged || pivotChanged) {
+                expanded.clear();
+                seenGroups.clear();
+            }
+            rebuild();
+        },
+        toggleGroup(row) {
+            if (expanded.has(row.id))
+                collapseGroup(row.path);
+            else
+                expandGroup(row.path);
+        },
+        expandGroup,
+        collapseGroup,
+        toggleDetail(id, open) {
+            const next = open ?? !openDetails.has(id);
+            if (next === openDetails.has(id))
+                return;
+            if (next)
+                openDetails.add(id);
+            else
+                openDetails.delete(id);
+            scheduleEmit();
+        },
+        isDetailOpen(id) {
+            return openDetails.has(id);
+        },
+        closeAllDetails() {
+            if (!openDetails.size)
+                return;
+            openDetails.clear();
+            scheduleEmit();
+        },
+        expandAll(opts) {
+            autoExpand = !!opts?.includeUnloaded;
+            for (const store of [...stores.values()]) {
+                for (const child of store.cache.rows()) {
+                    if (rowPlaceholderState(child) || child.kind !== 'group')
+                        continue;
+                    expandGroup([...store.route, child.key]);
+                }
+            }
+        },
+        collapseAll() {
+            autoExpand = false;
+            const open = [...expanded].map((k) => JSON.parse(k));
+            expanded.clear();
+            if (options.purgeClosedGroups)
+                for (const r of open)
+                    dropSubtree(r);
+            scheduleEmit();
+        },
+        isExpanded: (route) => expanded.has(routeKey(route)),
+        applyRowData({ route = [], rows, rowCount, startRow = 0 }) {
+            if (disposed)
+                return;
+            const store = ensureStore(route);
+            store.cache.applyRows(startRow, toChildren(route, startRow, rows), rowCount);
+            scheduleEmit();
+        },
+        applyTransaction,
+        applyTransactionAsync(tx, callback) {
+            asyncQueue.push({ tx, callback });
+            scheduleAsyncFlush();
+        },
+        flushAsyncTransactions,
+        updateRowData,
+        async createRow(input, route = [], addIndex) {
+            if (!source.createRow)
+                throw new Error('createServerRowModel: the datasource does not implement createRow()');
+            const saved = await saving(() => source.createRow(input));
+            if (disposed)
+                return saved;
+            applyTransaction({ route, add: [saved], ...(addIndex !== undefined ? { addIndex } : {}) });
+            return saved;
+        },
+        async updateRow(id, patch) {
+            if (!source.updateRow)
+                throw new Error('createServerRowModel: the datasource does not implement updateRow()');
+            const before = options.optimistic ? locate(id) : null;
+            const previous = before ? before.store.cache.getRow(before.index).data : null;
+            // Show the patch now; the server answer replaces it, a rejection restores it.
+            if (previous)
+                updateRowData(id, patch);
+            let saved;
+            try {
+                saved = await saving(() => source.updateRow(id, patch));
+            }
+            catch (err) {
+                if (previous && !disposed)
+                    updateRowData(id, previous, { replace: true });
+                throw err;
+            }
+            if (disposed)
+                return saved;
+            const hit = locate(id);
+            if (hit)
+                applyTransaction({ route: hit.store.route, update: [saved] });
+            return saved;
+        },
+        async moveRow(id, toRoute, opts = {}) {
+            const from = locate(id);
+            if (!from)
+                throw new Error(`createServerRowModel: moveRow: row ${id} is not loaded`);
+            const child = from.store.cache.getRow(from.index);
+            let row = child.data;
+            if (opts.patch) {
+                if (!source.updateRow)
+                    throw new Error('createServerRowModel: the datasource does not implement updateRow()');
+                row = await saving(() => source.updateRow(id, opts.patch));
+                if (disposed)
+                    return { row, status: 'cancelled' };
+            }
+            const fromRoute = [...from.store.route];
+            // A moved group's children were cached under its old route.
+            if (child.kind === 'group')
+                dropSubtree([...fromRoute, child.key]);
+            applyTransaction({ route: fromRoute, remove: [id] });
+            const res = applyTransaction({
+                route: [...toRoute],
+                add: [row],
+                ...(opts.addIndex !== undefined ? { addIndex: opts.addIndex } : {}),
+            });
+            // A target level nothing has opened cannot take the row, but its group
+            // row is on screen and the row did go there: the badge follows now
+            // rather than at the next refresh.
+            if (res.status === 'storeNotFound' && toRoute.length)
+                adjustChildCount([...toRoute], 1);
+            return { row, status: res.status };
+        },
+        async deleteRow(id) {
+            if (!source.deleteRow)
+                throw new Error('createServerRowModel: the datasource does not implement deleteRow()');
+            const before = options.optimistic ? locate(id) : null;
+            const removed = before ? before.store.cache.getRow(before.index).data : null;
+            const route = before ? [...before.store.route] : [];
+            const index = before?.index ?? 0;
+            // Take the row out now; a rejection puts it back where it was.
+            if (removed)
+                applyTransaction({ route, remove: [id] });
+            try {
+                await saving(() => source.deleteRow(id));
+            }
+            catch (err) {
+                if (removed && !disposed)
+                    applyTransaction({ route, add: [removed], addIndex: index });
+                throw err;
+            }
+            if (disposed || removed)
+                return;
+            const hit = locate(id);
+            if (hit)
+                applyTransaction({ route: hit.store.route, remove: [id] });
+        },
+        setViewport(startIndex, endIndex) {
+            lastViewport = [Math.max(0, startIndex), Math.max(startIndex, endIndex)];
+            applyViewport();
+        },
+        setPage(next) {
+            if (!paging || disposed)
+                return;
+            const last = Math.max(0, Math.ceil(pagerRowCount / pageSize) - 1);
+            const clamped = Math.max(0, Math.min(Math.floor(next), last));
+            if (clamped === pageIndex)
+                return;
+            pageIndex = clamped;
+            // The grid keeps reporting the same on-screen indices from page to
+            // page, so the new page asks for its own blocks here.
+            current = buildState();
+            applyViewport();
+            const root = stores.get(routeKey([]));
+            if (root)
+                primeStore(root);
+            scheduleEmit();
+        },
+        setPageSize(next) {
+            if (!paging || disposed)
+                return;
+            const size = Math.max(1, Math.floor(next));
+            if (size === pageSize)
+                return;
+            const firstRow = pageIndex * pageSize;
+            pageSize = size;
+            pageIndex = Math.floor(firstRow / size);
+            current = buildState();
+            applyViewport();
+            const root = stores.get(routeKey([]));
+            if (root)
+                primeStore(root);
+            scheduleEmit();
+        },
+        loadMoreChildren(route) {
+            const store = stores.get(routeKey(route));
+            if (!store || disposed)
+                return;
+            const rows = store.cache.rows();
+            let loaded = 0;
+            while (loaded < rows.length && !rowPlaceholderState(rows[loaded]))
+                loaded += 1;
+            store.cache.setViewport(loaded, loaded + store.blockSize - 1);
+            scheduleEmit();
+        },
+        selectionModel,
+        getSelectionState: () => selectionModel?.getState() ?? null,
+        setSelectionState(state) {
+            selectionModel?.setState(isCallbackSelectionState(state) ? fromCallbackSelectionState(state) : state);
+        },
+        bulkUpdate,
+        getLevelState(route = []) {
+            const store = stores.get(routeKey(route));
+            return store ? levelState(store) : null;
+        },
+        levelStates: () => [...stores.values()].map(levelState),
+        getCacheState() {
+            const out = [];
+            for (const store of stores.values()) {
+                for (const b of store.cache.getCacheState())
+                    out.push({ ...b, route: store.route });
+            }
+            return out;
+        },
+        // Fresh, not the last emitted snapshot: a caller reading state straight
+        // after `collapseAll()` expects to see it collapsed, and the emit is a
+        // microtask away. `getRows()` stays on the snapshot - it is the hot path.
+        getState: () => (current = buildState()),
+        dispose() {
+            disposed = true;
+            generation += 1;
+            if (asyncTimer)
+                clearTimeout(asyncTimer);
+            asyncTimer = null;
+            asyncQueue.length = 0;
+            for (const s of stores.values())
+                s.cache.dispose();
+            stores.clear();
+            subscribers.clear();
+            source.destroy?.();
+        },
+        get pinnedTopRows() {
+            return grandTotalRow === 'pinnedTop' ? pinnedGrandTotal() : undefined;
+        },
+        get pinnedBottomRows() {
+            return grandTotalRow === 'pinnedBottom' ? pinnedGrandTotal() : undefined;
+        },
+        get pivotResultColumns() {
+            return pivotResultColumns();
+        },
+        // A getter: the grid re-reads it after every change notification.
+        get pagination() {
+            if (!paging)
+                return undefined;
+            return {
+                pageIndex,
+                pageSize,
+                rowCount: pagerRowCount,
+                setPage: (i) => model.setPage(i),
+                setPageSize: (n) => model.setPageSize(n),
+                ...(paging.pageSizes ? { pageSizes: paging.pageSizes } : {}),
+                ...(paging.autoPageSize ? { autoPageSize: true } : {}),
+            };
+        },
+        // --- GridRowModel ---------------------------------------------------
+        subscribe(onChange) {
+            subscribers.add(onChange);
+            return () => {
+                subscribers.delete(onChange);
+            };
+        },
+        getRows: () => current.gridRows,
+        isLoading: () => current.loading,
+        getRowId: (row, index) => row.__group && 'id' in row.__group ? row.__group.id : `sv-ph:${index}`,
+        rowPlaceholder: (row) => rowPlaceholderState(row),
+        retryRow(_row, rowIndex) {
+            // The block under the clicked row; every failed block only when the
+            // index maps to no level (a stale index after a layout change).
+            for (const seg of segments) {
+                if (rowIndex < seg.displayStart || rowIndex >= seg.displayStart + seg.length)
+                    continue;
+                seg.store.cache.retryFailedAt(rowIndex - seg.displayStart + seg.storeStart);
+                return;
+            }
+            for (const store of stores.values())
+                store.cache.retryFailed();
+        },
+        group: nav,
+        selection: selectionAdapter,
+        filterValues: options.filterValues,
+    };
+    return model;
+}
+/**
+ * Map a state's display rows to grid rows. `state.gridRows` already holds
+ * this; the function exists for parity with `serverGroupRows` and for code
+ * that keeps its own display list.
+ */
+export function serverRowModelRows(state) {
+    return state?.gridRows ?? [];
+}
+/** The `serverGroup` prop for a grid driven by hand rather than by `rowModel`. */
+export function serverRowModelNav(ctl) {
+    return ctl.group;
+}
+/**
+ * The group column's text for one grid row: a group's key (or its
+ * `leafField` under `treeData`, where a node's key is its id), `Total` for a
+ * footer, `Grand total` for the grand total, the `leafField` value of a leaf,
+ * and nothing for the rows that carry no data (placeholders, skeletons, the
+ * "load more" row). `SvGroupCell` draws the expander, the count and the
+ * spinner; this is the value behind it, so give the group column
+ * `fieldFn: (row) => serverGroupText(row, leafField)` and copy, export, the
+ * clipboard and a `pinnedTop` / `pinnedBottom` grand total (which the grid
+ * formats from the accessor, not from the cell renderer) all read the same
+ * text. `messages` is the map `SvGroupCell` takes, so a localized footer
+ * and grand total read the same in the cell and in a copy.
+ */
+export function serverGroupText(row, leafField, messages) {
+    const meta = row.__group;
+    if (!meta)
+        return '';
+    const m = resolveServerGroupMessages(messages);
+    switch (meta.kind) {
+        case 'group': {
+            if (meta.field !== '' || !leafField)
+                return meta.key;
+            const v = row[leafField];
+            return v == null ? meta.key : String(v);
+        }
+        case 'footer':
+            return fillMessage(m.total, { label: meta.key });
+        case 'grandTotal':
+            return m.grandTotal;
+        case 'leaf': {
+            if (!leafField)
+                return '';
+            const v = row[leafField];
+            return v == null ? '' : String(v);
+        }
+        default:
+            return '';
+    }
+}