@svgrid/grid 1.0.2 → 1.1.1

package/dist/SvGrid.controller.svelte.js

@@ -0,0 +1,1917 @@
+import { applyExcelFilter, normalizeForFilter, createColumnVirtualizer, createCoreRowModel, createExpandedRowModel, createFilteredRowModel, createGroupedRowModel, createSvelteVirtualizer, createSortedRowModel, createSvGrid, getGridCellDomId, sortFns, } from "./index";
+import { createRowScrollScaling, resolveMaxDomHeight, } from "./virtualization/scroll-scaling";
+import "./sv-grid-scrollbar";
+import { computeColumnStat, formatsNeedingStats, } from "./conditional-formatting";
+import { rawToNumber, } from "./SvGrid.helpers";
+import { createFeatures } from "./features";
+import { createScrollSync, } from "./scroll-sync";
+import { createKeyboard, } from "./keyboard-handlers";
+import { createSummaries, } from "./summaries";
+import { createMenus, } from "./menus";
+import { createCellRender, } from "./cell-render";
+import { createEditing, } from "./editing";
+import { createSelection, } from "./selection";
+import { createColumns, } from "./columns";
+import { createRowDrag, } from "./row-drag";
+import { createAlignedGrids, } from "./aligned-grids";
+import { resolveColumnTypes, } from "./column-types";
+import { computeColumnGroupMeta, hiddenLeavesForCollapse, } from "./column-groups";
+import { createGridApi, } from "./build-api";
+import { createClipboard, } from "./clipboard";
+import { filterOperatorOptions, fallbackOperatorOption, TEXT_OPERATORS, NUMBER_OPERATORS, DATE_OPERATORS, CHECKBOX_OPERATORS, operatorOption, operatorsForColumn, defaultOperatorFor, operatorLabelFor, } from "./filter-operators";
+import { isBucketableColumn, buildBuckets, isInBucket, } from "./facet-buckets";
+import { getColumnBaseValue, isGroupRow, toolPanelHeaderLabel, formatSummaryNumeric, getColumnAlign, getPinnedCellValue, getColumnAccessorValue, columnDefMatchesId, } from "./cell-values";
+/**
+ * Conservative fallback for the browser's max element height, used during SSR
+ * or if runtime detection fails. 8M is below every known engine cap (Firefox
+ * ~17.9M, Chrome/Safari ~33.5M) so it is always safe, if coarser than needed.
+ */
+const MAX_DOM_SCROLL_HEIGHT_FALLBACK = 8000000;
+/**
+ * The browser's actual maximum *scrollable* element height in CSS px. Browsers
+ * clamp how tall a single element may be, and the cap is lower on mobile /
+ * high-DPR devices (the physical limit is in device px, so a 3x-DPR phone has
+ * ~1/3 the CSS-px cap of a 1x desktop). Past that cap a scroll container
+ * silently clamps its `scrollHeight` and the tail rows of a huge virtualized
+ * grid become unreachable.
+ *
+ * We measure two signals from one offscreen probe and keep the smaller (see
+ * `resolveMaxDomHeight`): the probe's clamped `offsetHeight`, AND the
+ * `scrollHeight` a real `overflow:auto` container exposes for it. The second
+ * matters because mobile WebKit/Blink can report a generous `offsetHeight` yet
+ * expose a smaller scrollable range - trusting the layout height alone is what
+ * stranded the last rows on phones. Using a real scroll container also folds in
+ * DPR clamping for free. Cached for the page lifetime; constant per browser.
+ */
+let detectedMaxDomHeight = null;
+/**
+ * Seed the `hiddenColumns` map from any column def marked `visible: false`.
+ * Walks groups so a hidden group hides all of its leaf columns. Keyed by the
+ * same id `setColumnVisible` uses (`id ?? field`), so user toggles afterward
+ * stay consistent. Run once at mount; prop changes don't re-apply it.
+ */
+function initialHiddenColumns(defs) {
+    const hidden = {};
+    const walk = (cols, inheritedHidden) => {
+        for (const def of cols) {
+            const hide = inheritedHidden || def.visible === false;
+            if (def.columns?.length) {
+                walk(def.columns, hide);
+            }
+            else if (hide) {
+                const id = def.id ?? def.field;
+                if (id)
+                    hidden[id] = true;
+            }
+        }
+    };
+    walk(defs, false);
+    return hidden;
+}
+function getMaxDomScrollHeight() {
+    // Escape hatch: a page may pin the cap via `window.__svgridMaxDomHeight`.
+    // Checked before the cache so it always wins. Two uses: reproducing a
+    // phone's lower element-height limit on desktop (and our e2e coverage of
+    // the huge-list path), and overriding detection on a device where it reads
+    // wrong. A non-positive / non-finite value is ignored.
+    if (typeof window !== "undefined") {
+        const forced = window
+            .__svgridMaxDomHeight;
+        if (typeof forced === "number" && Number.isFinite(forced) && forced > 0) {
+            return forced;
+        }
+    }
+    if (detectedMaxDomHeight != null)
+        return detectedMaxDomHeight;
+    if (typeof document === "undefined" || !document.body) {
+        return MAX_DOM_SCROLL_HEIGHT_FALLBACK;
+    }
+    try {
+        // The wrapper is itself an `overflow:auto` scroll container (kept tiny and
+        // offscreen so it never affects page layout or scroll), so we can read the
+        // height it actually exposes as scrollable - not just the probe's layout
+        // height. On high-DPR mobile the two diverge and the scrollable one is the
+        // limit that matters.
+        const wrap = document.createElement("div");
+        wrap.style.cssText =
+            "position:fixed;top:0;left:-9999px;width:1px;height:100px;overflow:auto;visibility:hidden;pointer-events:none;";
+        const probe = document.createElement("div");
+        probe.style.cssText = "width:1px;height:1000000000px;";
+        wrap.appendChild(probe);
+        document.body.appendChild(wrap);
+        const layoutCap = probe.offsetHeight;
+        const scrollCap = wrap.scrollHeight;
+        document.body.removeChild(wrap);
+        detectedMaxDomHeight = resolveMaxDomHeight(layoutCap, scrollCap, MAX_DOM_SCROLL_HEIGHT_FALLBACK);
+    }
+    catch {
+        detectedMaxDomHeight = MAX_DOM_SCROLL_HEIGHT_FALLBACK;
+    }
+    return detectedMaxDomHeight;
+}
+export function createSvGridController(props) {
+    // Resolved capability gates. Capabilities are OFF by default - a bare
+    // grid is a plain read-only table, and each power feature is opted into
+    // via its shortcut (`editable` / `pageable` / `groupable`) or the matching
+    // fine-grained prop (`enableInlineEditing` / `showPagination` /
+    // `showGroupingControls`). The shortcut wins when set; otherwise the
+    // fine-grained prop wins; otherwise the capability is off. (Sorting and
+    // filtering follow the same opt-in model already - they require their
+    // feature, injected by `sortable` / `filterable`.)
+    const editingEnabled = $derived(props.editable ?? props.enableInlineEditing ?? false);
+    const paginationEnabled = $derived(props.pageable ?? props.showPagination ?? false);
+    const groupingControlsEnabled = $derived(props.groupable ?? props.showGroupingControls ?? false);
+    let globalFilter = $state("");
+    let scrollContainer = $state(null);
+    let gridRootEl = $state(null);
+    let filterRowValues = $state({});
+    let filterMenuValues = $state({});
+    let verticalScrollbarEl = $state(null);
+    let horizontalScrollbarEl = $state(null);
+    let scrollVersion = $state(0);
+    /**
+     * Separate state from `scrollVersion`: only bumped by the ResizeObserver
+     * when the shell's CSS size changes. The virtualizer effects below depend
+     * on this instead of `scrollVersion` so they DON'T re-run on every scroll
+     * event - `scrollVersion` fires constantly during a drag.
+     */
+    let viewportVersion = $state(0);
+    let lastResetSignature = "";
+    let pendingScrollTop = 0;
+    let pendingScrollLeft = 0;
+    let scrollSyncRaf = null;
+    let selectionRange = $state({ anchor: null, focus: null });
+    // Extra committed ranges for multi-range (Ctrl+drag) selection. The
+    // `selectionRange` above is always the ACTIVE range being manipulated; these
+    // are the finished ones. Full selection = these + the active range.
+    let selectionRanges = $state.raw([]);
+    let isDraggingSelection = $state(false);
+    /** Excel-style fill handle drag state. While non-null we paint a "fill
+     *  preview" overlay on cells between the source range and the pointer
+     *  cell; on pointerup we extrapolate the source pattern into them. */
+    let fillDrag = $state(null);
+    let activeAtPointerDown = null;
+    let editingCell = $state(null);
+    // Full-row editing: the row currently in whole-row edit + its per-column
+    // draft (keyed by column id). Null when not in full-row mode.
+    let fullRowEdit = $state(null);
+    let editedCellValues = $state({});
+    const UNDO_LIMIT = 200;
+    let history = $state([]);
+    /** Index in `history` of the LAST applied step. -1 means "nothing applied".
+     *  undo() decrements; redo() increments. New edits truncate everything
+     *  past the pointer (the classic "you can't redo after editing" rule). */
+    let historyPtr = $state(-1);
+    /** Bumps on every undo / redo / record so $derived consumers can
+     *  observe via the api without subscribing to history directly. */
+    let historyVersion = $state(0);
+    let tooltip = $state(null);
+    let tooltipTimer = null;
+    // ---- Find-in-grid ----------------------------------------------------
+    let findOpen = $state(false);
+    let findQuery = $state('');
+    let findHitIndex = $state(0);
+    const findHits = $derived.by(() => {
+        const q = findQuery.trim().toLowerCase();
+        if (!q || !findOpen)
+            return [];
+        const out = [];
+        for (let r = 0; r < allRows.length; r += 1) {
+            const row = allRows[r];
+            if (!row)
+                continue;
+            for (let c = 0; c < allColumns.length; c += 1) {
+                const col = allColumns[c];
+                if (!col)
+                    continue;
+                const v = row.getCellValueByColumnId(col.id);
+                if (v == null)
+                    continue;
+                const s = String(v).toLowerCase();
+                if (s.includes(q))
+                    out.push({ rowIndex: r, colIndex: c, columnId: col.id });
+            }
+        }
+        return out;
+    });
+    let theadEl = $state(null);
+    let headerHeight = $state(0);
+    /** When an edit starts: true selects all text, false places the caret at the end. */
+    let editorSelectAll = true;
+    /** Per-column width overrides set by the resize handles. */
+    let columnWidths = $state({});
+    let resizingColumnId = $state(null);
+    let resizeStartX = 0;
+    let resizeStartWidth = 0;
+    const MIN_COLUMN_WIDTH = 40;
+    /** Columns pinned to the left or right edge of the grid (sticky positioning).
+     *  Seeded from `props.initialColumnPinning` so demos / tests can show the
+     *  feature on first render without driving the column menu in JS. */
+    let columnPinning = $state({
+        left: [...(props.initialColumnPinning?.left ?? [])],
+        right: [...(props.initialColumnPinning?.right ?? [])],
+    });
+    let columnVirtualizerVersion = $state(0);
+    let gridStateVersion = $state(0);
+    const selectionColumnWidth = 44;
+    const rowNumberColumnWidth = $derived(props.rowNumberWidth ?? 56);
+    const showRowNumbersEffective = $derived(props.showRowNumbers ?? false);
+    let columnMenuFor = $state(null);
+    let columnMenuTab = $state("general");
+    let columnMenuPos = $state({ x: 0, y: 0 });
+    let columnMenuSearch = $state("");
+    let filterMenuFor = $state(null);
+    let filterMenuPos = $state({ x: 0, y: 0 });
+    let operatorMenuFor = $state(null);
+    let operatorMenuPos = $state({ x: 0, y: 0 });
+    let chooseColumnsPos = $state(null);
+    let contextMenuFor = $state(null);
+    let contextMenuPos = $state({ x: 0, y: 0 });
+    // Editable comments: internal overlay (rowId -> columnId -> note) merged on
+    // top of props.notes for immediate feedback, plus the open-editor state.
+    let noteOverrides = $state({});
+    let commentEditFor = $state(null);
+    let commentDraft = $state("");
+    let valueFilters = $state({});
+    const viewportWidth = $derived.by(() => {
+        viewportVersion;
+        return scrollContainer ? scrollContainer.clientWidth : 0;
+    });
+    const viewportHeight = $derived.by(() => {
+        viewportVersion;
+        return scrollContainer ? scrollContainer.clientHeight : 0;
+    });
+    const scrollMetrics = $derived.by(() => {
+        scrollVersion;
+        viewportVersion;
+        // Track the virtualizers' versions too so when data loads or row /
+        // column counts change, scrollMetrics re-reads the DOM's grown
+        // scrollHeight / scrollWidth. Without these deps the scrollbar
+        // receives a stale `content-size` ≈ 0, its hidden-check trips, it
+        // sets `pointer-events: none`, and the user can't drag it. The
+        // identifiers below are declared further down - derived callbacks
+        // run lazily, so by the time this fires they're in scope.
+        virtualizer.version;
+        columnVirtualizerVersion;
+        return {
+            scrollTop: scrollContainer?.scrollTop ?? 0,
+            scrollLeft: scrollContainer?.scrollLeft ?? 0,
+            clientHeight: scrollContainer?.clientHeight ?? 0,
+            clientWidth: scrollContainer?.clientWidth ?? 0,
+            scrollHeight: scrollContainer?.scrollHeight ?? 0,
+            scrollWidth: scrollContainer?.scrollWidth ?? 0,
+        };
+    });
+    /** Vertical overflow from the virtualizer's authoritative total size,
+     *  NOT from `scrollMetrics.scrollHeight`. Reading DOM dimensions
+     *  during a Svelte derived runs BEFORE the browser paints - the table
+     *  hasn't laid out the new rows yet, so `scrollHeight` is briefly 0
+     *  even after data loads. That made the overflow flag return false,
+     *  hid the scrollbar, and broke dragging. */
+    const hasVerticalOverflow = $derived.by(() => {
+        virtualizer.version;
+        return virtualizer.getTotalSize() > viewportHeight + 1;
+    });
+    // Effective filter-UI flags. Each show* prop wins when explicitly set;
+    // otherwise the `filterMode` prop (default 'menu') picks exactly one surface.
+    const showGlobalFilterEffective = $derived(props.showGlobalFilter ?? (props.filterMode ?? "menu") === "global");
+    const showFilterRowEffective = $derived(props.showFilterRow ?? (props.filterMode ?? "menu") === "row");
+    const showColumnFiltersEffective = $derived(props.showColumnFilters ?? (props.filterMode ?? "menu") === "menu");
+    // The inline "floating filter" input under each header duplicates the
+    // column menu's funnel popover when both are active, so it requires an
+    // explicit opt-in via the `showColumnFilters` prop.
+    const showInlineColumnFilterEffective = $derived(props.showColumnFilters === true);
+    // Effective selection-surface flags. `selectionMode` defaults to 'both' so
+    // existing consumers keep their current behaviour.
+    const showRowSelectionEffective = $derived(props.showRowSelection ??
+        ((props.selectionMode ?? "both") === "row" ||
+            (props.selectionMode ?? "both") === "both"));
+    const enableCellSelectionEffective = $derived(props.enableCellSelection ??
+        ((props.selectionMode ?? "both") === "cell" ||
+            (props.selectionMode ?? "both") === "both"));
+    // Internal source-of-truth for data and column defs. Seeded from props and
+    // re-synced whenever the parent passes a new array; the imperative API
+    // mutates these so add/remove operations don't need a callback round-trip.
+    // svelte-ignore state_referenced_locally
+    let internalData = $state.raw(props.data);
+    // Resolve `cellDataType` / `inferColumnTypes` into concrete editorType +
+    // format defaults once, up front, so every downstream reader sees a normal
+    // column. Explicit fields on the ColumnDef always win.
+    // svelte-ignore state_referenced_locally
+    const resolveCols = (cols) => resolveColumnTypes(cols, props.data?.[0], props.inferColumnTypes === true);
+    // svelte-ignore state_referenced_locally
+    let internalColumns = $state.raw(resolveCols(props.columns));
+    // svelte-ignore state_referenced_locally
+    let hiddenColumns = $state(initialHiddenColumns(props.columns));
+    // Collapsible column groups (columnGroupShow). Meta is derived from the tree;
+    // `collapsedColumnGroups` is the live set of collapsed group ids, seeded once
+    // from each collapsible group's `openByDefault` (default: collapsed).
+    const columnGroupMeta = $derived(computeColumnGroupMeta(props.columns));
+    // svelte-ignore state_referenced_locally
+    let collapsedColumnGroups = $state((() => {
+        const meta = computeColumnGroupMeta(props.columns);
+        const s = new Set();
+        for (const id of meta.collapsibleGroupIds)
+            if (!meta.defaultOpen.get(id))
+                s.add(id);
+        return s;
+    })());
+    // Leaf ids hidden right now because their group is collapsed/expanded.
+    const hiddenByGroupCollapse = $derived(hiddenLeavesForCollapse(columnGroupMeta, collapsedColumnGroups));
+    function toggleColumnGroup(groupId) {
+        const next = new Set(collapsedColumnGroups);
+        if (next.has(groupId))
+            next.delete(groupId);
+        else
+            next.add(groupId);
+        collapsedColumnGroups = next;
+    }
+    function isColumnGroupCollapsed(groupId) {
+        return collapsedColumnGroups.has(groupId);
+    }
+    $effect(() => {
+        // When the consumer replaces `data` (e.g. a "Reset" button), drop any
+        // accumulated cell-edit overrides - otherwise `getCellDisplayValue`
+        // would keep returning the old edited values from `editedCellValues`
+        // even though the underlying data has been replaced.
+        internalData = props.data;
+        editedCellValues = {};
+    });
+    $effect(() => {
+        internalColumns = resolveCols(props.columns);
+    });
+    // Captured ONCE at mount: `externalSort` is a structural choice (tree vs
+    // flat data) so toggling it after mount is not supported. Reading it here
+    // - outside the getter below - guarantees the pass-through sort is wired
+    // in before `createSvGrid` first reads `_rowModels`.
+    // svelte-ignore state_referenced_locally
+    const externalSortEnabled = props.externalSort === true;
+    // Same one-shot capture for external filtering. Server-side mode means
+    // the wrapper records filter state but does not actually filter rows.
+    // svelte-ignore state_referenced_locally
+    const externalFilterEnabled = props.externalFilter === true;
+    const passthroughSortedRowModel = ({ rows }) => rows;
+    const grid = createSvGrid({
+        get _features() {
+            return resolveEffectiveFeatures();
+        },
+        get _rowModels() {
+            // Pagination is intentionally NOT in the grid's row-model pipeline.
+            // The wrapper applies its own filters (filterMenuValues, globalFilter,
+            // valueFilters) on top of `grid.getRowModel().rows`. If pagination
+            // ran first, those filters would only see the visible page. Instead
+            // the wrapper paginates last - see `allRows` below.
+            return {
+                coreRowModel: createCoreRowModel(),
+                filteredRowModel: createFilteredRowModel(),
+                // External-sort mode: pass the rows through untouched so the consumer
+                // controls ordering (e.g. tree data that must preserve hierarchy).
+                sortedRowModel: externalSortEnabled
+                    ? passthroughSortedRowModel
+                    : createSortedRowModel(sortFns),
+                groupedRowModel: createGroupedRowModel(),
+                expandedRowModel: createExpandedRowModel(),
+            };
+        },
+        get columns() {
+            return internalColumns;
+        },
+        get data() {
+            return internalData;
+        },
+        get getRowId() {
+            return props.getRowId;
+        },
+        state: {
+            columnFilters: [],
+            grouping: [],
+            sorting: [],
+            // svelte-ignore state_referenced_locally
+            pagination: { pageIndex: 0, pageSize: props.pageSize ?? 10 },
+            rowSelection: {},
+            expanded: {},
+            activeCell: { rowIndex: 0, colIndex: 0, cellId: null },
+        },
+    });
+    $effect(() => {
+        const unsubscribe = grid.store.subscribe(() => {
+            gridStateVersion += 1;
+        });
+        return unsubscribe;
+    });
+    /**
+     * The grid's columns reordered so left-pinned columns come first and
+     * right-pinned columns come last. All other code (rendering, keyboard nav,
+     * active cell) operates on this ordered view.
+     */
+    /**
+     * User-driven column order (drag-to-reorder OR `api.setColumnOrder`).
+     * Stored as a flat list of column ids. Empty = use the natural order
+     * from the columns prop. The pin grouping is applied on top of this.
+     */
+    let userColumnOrder = $state([...(props.columnOrder ?? [])]);
+    // Re-seed on prop change so consumers can drive order from outside.
+    let lastSeededOrder = "";
+    $effect(() => {
+        const incoming = props.columnOrder
+            ? [...props.columnOrder].join("|")
+            : "";
+        if (incoming === lastSeededOrder)
+            return;
+        lastSeededOrder = incoming;
+        userColumnOrder = props.columnOrder ? [...props.columnOrder] : [];
+    });
+    const allColumns = $derived.by(() => {
+        let raw = grid
+            .getAllColumns()
+            .filter((column) => !hiddenColumns[column.id] && !hiddenByGroupCollapse[column.id]);
+        // Apply user reorder (if any). Unknown ids in userColumnOrder are
+        // skipped; columns not in userColumnOrder keep their original
+        // relative order after the user-ordered ones.
+        if (userColumnOrder.length > 0) {
+            const byId = new Map(raw.map((c) => [c.id, c]));
+            const seen = new Set();
+            const ordered = [];
+            for (const id of userColumnOrder) {
+                const c = byId.get(id);
+                if (c && !seen.has(id)) {
+                    ordered.push(c);
+                    seen.add(id);
+                }
+            }
+            for (const c of raw) {
+                if (!seen.has(c.id))
+                    ordered.push(c);
+            }
+            raw = ordered;
+        }
+        const leftIds = columnPinning.left;
+        const rightIds = columnPinning.right;
+        if (!leftIds.length && !rightIds.length)
+            return raw;
+        const pinned = new Set([...leftIds, ...rightIds]);
+        const findById = (id) => raw.find((column) => column.id === id);
+        const left = leftIds
+            .map(findById)
+            .filter((c) => Boolean(c));
+        const right = rightIds
+            .map(findById)
+            .filter((c) => Boolean(c));
+        const unpinned = raw.filter((column) => !pinned.has(column.id));
+        return [...left, ...unpinned, ...right];
+    });
+    /** Header groups reordered to match {@link allColumns}. */
+    const headerGroups = $derived.by(() => {
+        const base = grid.getHeaderGroups();
+        if (!base.length)
+            return base;
+        const byId = new Map(base[0].headers.map((header) => [header.column.id, header]));
+        const headers = [];
+        for (const column of allColumns) {
+            const header = byId.get(column.id);
+            if (header)
+                headers.push(header);
+        }
+        return [{ id: base[0].id, headers }];
+    });
+    const groupHeaderRows = $derived.by(() => {
+        const userCols = props.columns ?? [];
+        // 1. Find max depth in the user-provided column tree.
+        function maxDepth(defs) {
+            let m = 0;
+            for (const d of defs) {
+                if (d.columns?.length) {
+                    m = Math.max(m, 1 + maxDepth(d.columns));
+                }
+            }
+            return m;
+        }
+        const depth = maxDepth(userCols);
+        if (depth === 0)
+            return [];
+        const leafEntries = [];
+        function buildId(def, parentId, fallbackIx) {
+            return def.id ?? def.field ?? `${parentId ?? 'col'}_d_${fallbackIx}`;
+        }
+        // Leaves hidden by a collapsed/expanded group are skipped everywhere here,
+        // so group colSpan + widthPx exclude them and stay aligned with the leaves
+        // the body actually renders.
+        const hiddenLeaf = hiddenByGroupCollapse;
+        function collectLeaves(defs, parentId, depthHere) {
+            defs.forEach((def, ix) => {
+                const id = buildId(def, parentId, ix);
+                if (def.columns?.length) {
+                    collectLeaves(def.columns, id, depthHere + 1);
+                }
+                else if (!hiddenLeaf[id]) {
+                    leafEntries.push({ id, widthPx: getColumnWidth(id) });
+                }
+            });
+        }
+        collectLeaves(userCols, undefined, 0);
+        function indexTree(defs, parentId, cursor) {
+            const nodes = [];
+            for (const def of defs) {
+                const id = buildId(def, parentId, nodes.length);
+                // Skip leaves the collapse state hides, so leaf indices/colSpans match
+                // `leafEntries` (and the body's rendered columns) exactly.
+                if (!def.columns?.length && hiddenLeaf[id])
+                    continue;
+                const leafStart = cursor.leaf;
+                if (def.columns?.length) {
+                    indexTree(def.columns, id, cursor);
+                }
+                else {
+                    cursor.leaf += 1;
+                }
+                const leafEnd = cursor.leaf;
+                nodes.push({ def, id, leafStart, leafEnd });
+            }
+            return nodes;
+        }
+        const cursor = { leaf: 0 };
+        const topNodes = indexTree(userCols, undefined, cursor);
+        function nodesAtDepth(nodes, currentDepth, targetDepth) {
+            if (currentDepth === targetDepth)
+                return nodes;
+            const out = [];
+            for (const n of nodes) {
+                if (n.def.columns?.length) {
+                    const childCursor = { leaf: n.leafStart };
+                    const children = indexTree(n.def.columns, n.id, childCursor);
+                    out.push(...nodesAtDepth(children, currentDepth + 1, targetDepth));
+                }
+                else {
+                    // Leaf reached early - emit a placeholder at this row so the
+                    // column above it stays empty (the leaf itself renders in the
+                    // bottom leaf-header row, not here).
+                    out.push(n);
+                }
+            }
+            return out;
+        }
+        function sumLeafWidths(from, to) {
+            let sum = 0;
+            for (let i = from; i < to; i += 1)
+                sum += leafEntries[i]?.widthPx ?? 0;
+            return sum;
+        }
+        const rows = [];
+        for (let d = 0; d < depth; d += 1) {
+            const at = nodesAtDepth(topNodes, 0, d);
+            const cells = at.map((n) => {
+                const isLeafEarly = !n.def.columns?.length;
+                const headerText = typeof n.def.header === 'string' ? n.def.header : '';
+                const collapsible = columnGroupMeta.collapsibleGroupIds.has(n.id);
+                return {
+                    key: `${n.id}_d${d}`,
+                    label: isLeafEarly ? '' : headerText,
+                    colSpan: Math.max(1, n.leafEnd - n.leafStart),
+                    widthPx: sumLeafWidths(n.leafStart, n.leafEnd),
+                    firstLeafIndex: n.leafStart,
+                    isPlaceholder: isLeafEarly,
+                    groupId: collapsible ? n.id : undefined,
+                    collapsible,
+                    collapsed: collapsible && collapsedColumnGroups.has(n.id),
+                };
+            });
+            rows.push({ id: `gh_${d}`, cells });
+        }
+        return rows;
+    });
+    /** Cumulative pixel offsets for left- and right-pinned columns. */
+    const pinnedOffsets = $derived.by(() => {
+        const rowNumberWidth = showRowNumbersEffective ? rowNumberColumnWidth : 0;
+        const selectionWidth = showRowSelectionEffective ? selectionColumnWidth : 0;
+        const left = {};
+        let leftAcc = rowNumberWidth + selectionWidth;
+        for (const id of columnPinning.left) {
+            left[id] = leftAcc;
+            leftAcc += getColumnWidth(id);
+        }
+        const right = {};
+        let rightAcc = 0;
+        for (let i = columnPinning.right.length - 1; i >= 0; i -= 1) {
+            const id = columnPinning.right[i];
+            if (!id)
+                continue;
+            right[id] = rightAcc;
+            rightAcc += getColumnWidth(id);
+        }
+        return { left, right };
+    });
+    // ---- Column reorder (drag headers) ----------------------------------
+    // Live drag state for the built-in header drag-to-reorder. Only set
+    // when `props.enableColumnReorder` is true.
+    let colDragId = $state(null);
+    let colDropOnId = $state(null);
+    let colDropSide = $state(null);
+    // Live drag state for managed row dragging. Only meaningful while a row is
+    // being dragged (`props.rowDragManaged`). `rowDropIndex` is the visible row
+    // index currently hovered; `rowDropSide` says which edge the drop line paints.
+    let rowDragActive = $state(false);
+    let rowDropIndex = $state(null);
+    let rowDropSide = $state(null);
+    // ---- Conditional formatting --------------------------------------------
+    // True when the feature is in use; gates the per-cell positioning context
+    // (cells are otherwise non-relative for scroll performance).
+    const hasConditionalFormats = $derived((props.conditionalFormats?.length ?? 0) > 0);
+    // Per-column numeric min/max, needed only by colorScale / dataBar formats.
+    // Lazy: this derived never runs unless `conditionalFormats` is set.
+    const conditionalColumnStats = $derived.by(() => {
+        const map = new Map();
+        const formats = props.conditionalFormats;
+        if (!formats?.length || !formatsNeedingStats(formats))
+            return map;
+        for (const column of allColumns) {
+            const needs = formats.some((f) => (f.type === "colorScale" || f.type === "dataBar") &&
+                (!f.columns || f.columns.includes(column.id)));
+            if (!needs)
+                continue;
+            const def = column.columnDef;
+            const accessorFn = def.accessorFn;
+            const field = def.field;
+            const stat = computeColumnStat((function* () {
+                for (const row of allRows) {
+                    yield accessorFn
+                        ? accessorFn(row.original)
+                        : field
+                            ? row.original[field]
+                            : row.getCellValueByColumnId(column.id);
+                }
+            })());
+            if (stat)
+                map.set(column.id, stat);
+        }
+        return map;
+    });
+    const sortDirectionByColumn = $derived.by(() => {
+        gridStateVersion;
+        const directions = {};
+        for (const column of allColumns)
+            directions[column.id] = column.getIsSorted();
+        return directions;
+    });
+    const groupingColumns = $derived.by(() => {
+        gridStateVersion;
+        return grid.getState().grouping ?? [];
+    });
+    const paginationState = $derived.by(() => {
+        gridStateVersion;
+        return grid.getState().pagination ?? { pageIndex: 0, pageSize: 10 };
+    });
+    /**
+     * Rows AFTER all filtering but BEFORE pagination. Used by the pager to
+     * compute the correct "X to Y of Z" range and total page count when
+     * filters reduce the dataset.
+     */
+    const allRowsBeforePagination = $derived.by(() => {
+        gridStateVersion;
+        // Touch internalData + internalColumns so the row model re-derives when
+        // the consumer replaces the data array (e.g. via a "Reset" button).
+        void internalData;
+        void internalColumns;
+        const rawRows = grid.getRowModel().rows;
+        // External-filter mode: the consumer fetched / pre-filtered the rows
+        // themselves (server-side data sources). Skip every local filter pass
+        // so the data isn't double-filtered against the visible page.
+        if (externalFilterEnabled)
+            return rawRows;
+        let rows = rawRows;
+        if (globalFilter.trim()) {
+            const needle = normalizeForFilter(globalFilter, props.filterLocale);
+            rows = rows.filter((row) => row
+                .getAllCells()
+                .some((cell) => normalizeForFilter(String(cell.getValue() ?? ""), props.filterLocale)
+                .includes(needle)));
+        }
+        // A single condition is "active" if it has the value(s) it needs.
+        const condActive = (op, value, valueTo) => {
+            if (op === "isBlank")
+                return true;
+            if (op === "between")
+                return value.trim().length > 0 && (valueTo ?? "").trim().length > 0;
+            return value.trim().length > 0;
+        };
+        const evalCond = (cellValue, columnId, op, value, valueTo) => applyExcelFilter(cellValue, { id: columnId, operator: op, value, valueTo: op === "between" ? valueTo : undefined }, { locale: props.filterLocale });
+        // A column filter is active if either of its (up to two) conditions is.
+        const menuFilters = Object.entries(filterMenuValues).filter(([_, f]) => {
+            const a = condActive(f.operator, f.value, f.valueTo);
+            const b = !!f.operator2 && condActive(f.operator2, f.value2 ?? "", f.valueTo2);
+            return a || b;
+        });
+        if (menuFilters.length) {
+            rows = rows.filter((row) => menuFilters.every(([columnId, f]) => {
+                const cellValue = getRowColumnValue(row, columnId);
+                const aActive = condActive(f.operator, f.value, f.valueTo);
+                const bActive = !!f.operator2 && condActive(f.operator2, f.value2 ?? "", f.valueTo2);
+                const ra = aActive ? evalCond(cellValue, columnId, f.operator, f.value, f.valueTo) : null;
+                const rb = bActive
+                    ? evalCond(cellValue, columnId, f.operator2, f.value2 ?? "", f.valueTo2)
+                    : null;
+                if (ra === null)
+                    return rb ?? true;
+                if (rb === null)
+                    return ra;
+                return f.join === "OR" ? ra || rb : ra && rb;
+            }));
+        }
+        const valueFilterEntries = Object.entries(valueFilters);
+        if (valueFilterEntries.length) {
+            // Resolve bucket defs up front so we don't re-hit the derived map
+            // for every row × column combination. Columns without bucketing
+            // map to `null` here and fall through to exact-value matching.
+            const bucketEntries = valueFilterEntries.map(([columnId, allowed]) => ({
+                columnId,
+                allowed,
+                buckets: facetBucketsByColumn.get(columnId) ?? null,
+            }));
+            rows = rows.filter((row) => bucketEntries.every(({ columnId, allowed, buckets }) => {
+                const raw = getRowColumnValue(row, columnId);
+                if (buckets) {
+                    // Range-bucketed filter: find which bucket this row's value
+                    // falls into and check whether that bucket's label is allowed.
+                    const isDate = buckets[0].isDate;
+                    const num = rawToNumber(raw, isDate);
+                    if (!Number.isFinite(num))
+                        return false;
+                    for (const bucket of buckets) {
+                        if (isInBucket(num, bucket))
+                            return allowed.has(bucket.label);
+                    }
+                    return false;
+                }
+                return allowed.has(String(raw ?? ""));
+            }));
+        }
+        return rows;
+    });
+    /**
+     * Visible rows for the current page. Applied last so filters operate on
+     * the full dataset rather than the current page (see the comment above
+     * `_rowModels`).
+     */
+    const allRows = $derived.by(() => {
+        const rows = allRowsBeforePagination;
+        if (!paginationEnabled)
+            return rows;
+        const { pageIndex, pageSize } = paginationState;
+        const start = pageIndex * pageSize;
+        return rows.slice(start, start + pageSize);
+    });
+    const rowSelectionState = $derived.by(() => {
+        gridStateVersion;
+        return grid.getState().rowSelection ?? {};
+    });
+    // Forward selection changes to the consumer. Skips the very first invocation
+    // (the initial empty state) so consumers don't get a spurious callback on mount.
+    let lastSelectionSerialized = "";
+    $effect(() => {
+        const serialized = JSON.stringify(rowSelectionState);
+        if (serialized === lastSelectionSerialized)
+            return;
+        lastSelectionSerialized = serialized;
+        const callback = props.onRowSelectionChange;
+        if (!callback)
+            return;
+        const data = internalData;
+        const selectedRows = [];
+        for (let i = 0; i < data.length; i++) {
+            if (rowSelectionState[String(i)])
+                selectedRows.push(data[i]);
+        }
+        callback(rowSelectionState, selectedRows);
+    });
+    // Forward cell-selection rectangle changes to the consumer. Same
+    // dedupe pattern - fires only when the serialized rectangle changes
+    // so consumers don't see spurious callbacks during re-renders.
+    let lastCellRangeSerialized = "";
+    $effect(() => {
+        const a = selectionRange.anchor;
+        const f = selectionRange.focus;
+        const ranges = a && f
+            ? [[
+                    Math.min(a.rowIndex, f.rowIndex),
+                    Math.min(a.colIndex, f.colIndex),
+                    Math.max(a.rowIndex, f.rowIndex),
+                    Math.max(a.colIndex, f.colIndex),
+                ]]
+            : [];
+        const serialized = JSON.stringify(ranges);
+        if (serialized === lastCellRangeSerialized)
+            return;
+        lastCellRangeSerialized = serialized;
+        props.onCellSelectionChange?.(ranges);
+    });
+    // ---- Status bar: live aggregates of the selected cell range -----------
+    const statusBarEnabled = $derived(props.statusBar != null && props.statusBar !== false);
+    const statusBarAggregates = $derived(typeof props.statusBar === "object" && props.statusBar.aggregates
+        ? props.statusBar.aggregates
+        : ["count", "sum", "avg", "min", "max"]);
+    const statusBarStats = $derived.by(() => {
+        if (!statusBarEnabled)
+            return null;
+        const a = selectionRange.anchor;
+        const f = selectionRange.focus;
+        if (!a || !f)
+            return null;
+        const minR = Math.min(a.rowIndex, f.rowIndex);
+        const maxR = Math.max(a.rowIndex, f.rowIndex);
+        const minC = Math.min(a.colIndex, f.colIndex);
+        const maxC = Math.max(a.colIndex, f.colIndex);
+        let count = 0;
+        let numericCount = 0;
+        let sum = 0;
+        let min = Number.POSITIVE_INFINITY;
+        let max = Number.NEGATIVE_INFINITY;
+        for (let r = minR; r <= maxR; r += 1) {
+            const row = allRows[r];
+            if (!row || isGroupRow(row))
+                continue;
+            for (let c = minC; c <= maxC; c += 1) {
+                const col = allColumns[c];
+                if (!col)
+                    continue;
+                count += 1;
+                const base = getColumnBaseValue(row, col);
+                const v = getCellDisplayValue(row.id, col.id, base);
+                if (v == null || v === "")
+                    continue;
+                const n = Number(v);
+                if (!Number.isFinite(n))
+                    continue;
+                numericCount += 1;
+                sum += n;
+                if (n < min)
+                    min = n;
+                if (n > max)
+                    max = n;
+            }
+        }
+        if (count <= 1)
+            return null;
+        return {
+            count,
+            numericCount,
+            sum,
+            avg: numericCount ? sum / numericCount : 0,
+            min: numericCount ? min : 0,
+            max: numericCount ? max : 0,
+        };
+    });
+    // ---- Tool panel (docked columns sidebar) -------------------------------
+    // svelte-ignore state_referenced_locally
+    let toolPanelOpen = $state(props.toolPanelDefaultOpen === true);
+    // svelte-ignore state_referenced_locally
+    let toolPanelTab = $state(props.toolPanelDefaultTab ?? "columns");
+    const toolPanelEnabled = $derived(props.toolPanel === true);
+    // Every column (including hidden ones) in the user's current order, so the
+    // panel can toggle/reorder anything. Group columns are flagged live.
+    const toolPanelColumns = $derived.by(() => {
+        gridStateVersion;
+        const all = grid.getAllColumns();
+        if (!userColumnOrder.length)
+            return all;
+        const byId = new Map(all.map((c) => [c.id, c]));
+        const ordered = [];
+        const seen = new Set();
+        for (const id of userColumnOrder) {
+            const c = byId.get(id);
+            if (c && !seen.has(id)) {
+                ordered.push(c);
+                seen.add(id);
+            }
+        }
+        for (const c of all)
+            if (!seen.has(c.id))
+                ordered.push(c);
+        return ordered;
+    });
+    // Forward sort-clause changes to the consumer. Same dedupe pattern as the
+    // selection callback above - fires only when the serialized clauses change.
+    let lastSortingSerialized = "";
+    $effect(() => {
+        gridStateVersion;
+        const sorting = (grid.getState().sorting ?? []);
+        const serialized = JSON.stringify(sorting);
+        if (serialized === lastSortingSerialized)
+            return;
+        lastSortingSerialized = serialized;
+        props.onSortingChange?.(sorting);
+    });
+    // Forward filter-state changes to the consumer. Consolidates the three
+    // wrapper-managed filter stores (global text, per-column operator filters,
+    // facet checklists) into one shape so server-side consumers can build a
+    // single query. Skipped entirely when no callback is registered to avoid
+    // serializing on every keystroke.
+    let lastFiltersSerialized = "";
+    $effect(() => {
+        if (!props.onFiltersChange)
+            return;
+        const menuEntries = Object.entries(filterMenuValues)
+            .filter(([, f]) => {
+            if (f.operator === "isBlank")
+                return true;
+            if (f.operator === "between") {
+                return f.value.trim().length > 0 && (f.valueTo ?? "").trim().length > 0;
+            }
+            return f.value.trim().length > 0;
+        })
+            .map(([id, f]) => ({
+            id,
+            operator: f.operator,
+            value: f.value,
+            ...(f.operator === "between" && f.valueTo
+                ? { valueTo: f.valueTo }
+                : {}),
+        }));
+        const valueEntries = Object.entries(valueFilters).map(([id, allowed]) => ({
+            id,
+            operator: "equals",
+            value: "",
+            selectedValues: Array.from(allowed).sort(),
+        }));
+        const merged = new Map();
+        for (const entry of menuEntries)
+            merged.set(entry.id, entry);
+        for (const entry of valueEntries) {
+            const existing = merged.get(entry.id);
+            merged.set(entry.id, existing
+                ? { ...existing, selectedValues: entry.selectedValues }
+                : entry);
+        }
+        const payload = {
+            global: globalFilter,
+            columns: Array.from(merged.values()),
+        };
+        const serialized = JSON.stringify(payload);
+        if (serialized === lastFiltersSerialized)
+            return;
+        lastFiltersSerialized = serialized;
+        props.onFiltersChange(payload);
+    });
+    const virtualizer = createSvelteVirtualizer({
+        count: 0,
+        estimateSize: 36,
+        overscan: 8,
+        viewportHeight: 520,
+        scrollOffset: 0,
+    });
+    const columnVirtualizer = createColumnVirtualizer({
+        count: 0,
+        viewportWidth: 0,
+        overscan: 3,
+        estimateSize: () => 140,
+    });
+    columnVirtualizer.subscribe(() => {
+        columnVirtualizerVersion += 1;
+    });
+    const rowVirtualizationEnabled = $derived((props.virtualization ?? true) && allRows.length > 0);
+    const columnVirtualizationEnabled = $derived((props.columnVirtualization ?? true) && allColumns.length > 0);
+    const virtualRows = $derived.by(() => {
+        virtualizer.version;
+        return virtualizer.getVirtualItems();
+    });
+    const virtualRowTotalSize = $derived.by(() => {
+        virtualizer.version;
+        return virtualizer.getTotalSize();
+    });
+    const virtualRowStart = $derived.by(() => virtualRows[0]?.start ?? 0);
+    const virtualRowEnd = $derived.by(() => virtualRows[virtualRows.length - 1]?.end ?? 0);
+    const virtualRowBottomSpacer = $derived.by(() => Math.max(virtualRowTotalSize - virtualRowEnd, 0));
+    // --- Huge-list scroll scaling -----------------------------------------
+    // Browsers cap how tall a single element may be, and mobile caps sit well
+    // below desktop. Past a few hundred thousand rows the true content height
+    // (count * rowHeight) exceeds that cap, the scroll container silently
+    // clamps its scrollHeight, and the last rows become unreachable - e.g. a
+    // 1,000,000-row grid that only scrolls to ~994,000 on a phone.
+    //
+    // When the true height exceeds the browser's max element height we cap the
+    // DOM scroll height and map between the limited DOM scroll range and the
+    // full logical range (the "scaling" technique from react-virtualized): the
+    // spacers are sized in the capped DOM space, while the virtualizer keeps
+    // working in true logical pixels. We detect the real per-browser cap at
+    // runtime (Chrome ~33.5M, Firefox ~17.9M, mobile lower) rather than guess a
+    // constant, so scaling activates only when genuinely needed and stays as
+    // fine-grained as the browser allows. For normal-sized grids scaling is
+    // inert and every value below reduces to the original behavior.
+    // Build the scaling mapping from the current true height + detected browser
+    // cap + viewport. The pure, unit-tested math lives in
+    // ./virtualization/scroll-scaling; here we only feed it reactive inputs.
+    // Inert (identity) for normal-sized grids.
+    const rowScrollScaling = $derived(createRowScrollScaling(virtualRowTotalSize, getMaxDomScrollHeight(), viewportHeight));
+    const rowDomTotalSize = $derived(rowScrollScaling.domTotal);
+    const rowScrollScalingActive = $derived(rowScrollScaling.active);
+    // Map a DOM scrollTop to the virtualizer's logical scroll offset, and back.
+    function domToLogicalRowOffset(domTop) {
+        return rowScrollScaling.domToLogical(domTop);
+    }
+    function logicalToDomRowOffset(logical) {
+        return rowScrollScaling.logicalToDom(logical);
+    }
+    // px the logical row positions must shift to land inside the capped DOM
+    // coordinate space (0 when not scaling). Derived from the virtualizer's
+    // OWN committed scroll offset - not the live DOM scrollTop - so the spacer
+    // shift and the rendered window are always computed from the same state and
+    // can never skew by a frame (which would jitter at extreme scale).
+    const rowOffsetAdjustment = $derived.by(() => {
+        if (!rowScrollScalingActive)
+            return 0;
+        virtualizer.version;
+        const logical = virtualizer.getState().scrollOffset;
+        return logical - rowScrollScaling.logicalToDom(logical);
+    });
+    // Spacer heights in DOM space. With scaling inert these equal the original
+    // virtualRowStart / virtualRowBottomSpacer.
+    const rowTopSpacer = $derived(Math.max(virtualRowStart - rowOffsetAdjustment, 0));
+    const rowBottomSpacer = $derived(Math.max(rowDomTotalSize - (virtualRowEnd - rowOffsetAdjustment), 0));
+    const virtualColumns = $derived.by(() => {
+        columnVirtualizerVersion;
+        return columnVirtualizer.getVirtualItems();
+    });
+    const virtualColumnTotalSize = $derived.by(() => {
+        columnVirtualizerVersion;
+        return columnVirtualizer.getTotalSize();
+    });
+    const renderedColumnItems = $derived.by(() => {
+        if (columnVirtualizationEnabled)
+            return virtualColumns;
+        let start = 0;
+        return allColumns.map((column, index) => {
+            const size = getColumnWidth(column.id);
+            const item = { index, key: index, size, start, end: start + size };
+            start += size;
+            return item;
+        });
+    });
+    const renderedColumns = $derived.by(() => renderedColumnItems
+        .map((item) => ({ item, column: allColumns[item.index] }))
+        .filter(hasRenderedColumn));
+    const totalColumnWidth = $derived.by(() => {
+        if (columnVirtualizationEnabled)
+            return virtualColumnTotalSize;
+        let total = 0;
+        for (const column of allColumns)
+            total += getColumnWidth(column.id);
+        return total;
+    });
+    /** Horizontal overflow derived from the SOURCE OF TRUTH (column widths
+     *  + leading sticky columns) compared to the viewport. We can't use
+     *  `totalColumnWidth` here when column virtualization is on - that
+     *  returns the column virtualizer's cached total, which only updates
+     *  on `setOptions()` / scroll, NOT when `fittedColumnWidths` finishes
+     *  scaling on first measure. Reading `getColumnWidth(c.id)` for every
+     *  column instead is reactive to both `columnWidths` and
+     *  `fittedColumnWidths`, so the overflow decision settles in the same
+     *  render where fit-scaling lands - no race, no scrollbar flash. */
+    const hasHorizontalOverflow = $derived.by(() => {
+        const fixedCols = (showRowNumbersEffective ? rowNumberColumnWidth : 0) +
+            (showRowSelectionEffective ? selectionColumnWidth : 0);
+        let total = fixedCols;
+        for (const column of allColumns)
+            total += getColumnWidth(column.id);
+        // +1 to tolerate sub-pixel rounding residue from `fitColumns`.
+        return total > viewportWidth + 1;
+    });
+    const columnWindowStart = $derived.by(() => renderedColumnItems[0]?.start ?? 0);
+    const columnWindowEnd = $derived.by(() => renderedColumnItems[renderedColumnItems.length - 1]?.end ?? 0);
+    const columnWindowRightSpacer = $derived.by(() => Math.max(totalColumnWidth - columnWindowEnd, 0));
+    const activeCell = $derived.by(() => {
+        gridStateVersion;
+        return (grid.getState().activeCell ?? { rowIndex: 0, colIndex: 0, cellId: null });
+    });
+    const activeDescendantId = $derived.by(() => {
+        const active = activeCell;
+        const inRows = active.rowIndex >= 0 && active.rowIndex < allRows.length;
+        const inCols = active.colIndex >= 0 && active.colIndex < allColumns.length;
+        if (!inRows || !inCols)
+            return null;
+        return getGridCellDomId("svgrid", active.rowIndex, active.colIndex);
+    });
+    // Above this many cells (rows x columns) the summary aggregation is
+    // deferred one animation frame so it never blocks first paint - a
+    // 100k x 50 grid would otherwise spend seconds summing reactive cells
+    // before the grid ever appears. Smaller grids compute inline so the
+    // footer is correct on the first frame (no flicker).
+    const SUMMARY_DEFER_CELL_LIMIT = 50000;
+    let summaryByColumn = $state({});
+    $effect(() => {
+        // Re-aggregate whenever the visible data, columns, edits, or any
+        // state that reorders/filters rows changes.
+        gridStateVersion;
+        void editedCellValues;
+        const rows = allRows;
+        const columns = allColumns;
+        if (!(props.enableRowSummaries ?? true)) {
+            summaryByColumn = {};
+            return;
+        }
+        if (rows.length * columns.length <= SUMMARY_DEFER_CELL_LIMIT ||
+            typeof requestAnimationFrame === "undefined") {
+            summaryByColumn = computeSummaries(rows, columns);
+            return;
+        }
+        // Large grid: paint first, total a frame later.
+        let cancelled = false;
+        const handle = requestAnimationFrame(() => {
+            if (!cancelled)
+                summaryByColumn = computeSummaries(rows, columns);
+        });
+        return () => {
+            cancelled = true;
+            cancelAnimationFrame(handle);
+        };
+    });
+    $effect(() => {
+        if (!theadEl)
+            return;
+        headerHeight = theadEl.offsetHeight;
+        const observer = new ResizeObserver(() => {
+            headerHeight = theadEl?.offsetHeight ?? 0;
+        });
+        observer.observe(theadEl);
+        return () => observer.disconnect();
+    });
+    // Bump scrollVersion when the table's layout size changes so scrollbar
+    // visibility (and the thumb math that depends on scroll metrics) updates
+    // after column resize / show-hide / add-remove.
+    $effect(() => {
+        if (!gridRootEl)
+            return;
+        const observer = new ResizeObserver(() => {
+            scrollVersion += 1;
+        });
+        observer.observe(gridRootEl);
+        return () => observer.disconnect();
+    });
+    $effect(() => {
+        if (!allRows.length || !allColumns.length)
+            return;
+        const active = grid.getState().activeCell;
+        if (active?.cellId)
+            return;
+        grid.setActiveCell({
+            rowIndex: 0,
+            colIndex: 0,
+            cellId: getGridCellDomId("svgrid", 0, 0),
+        });
+    });
+    $effect(() => {
+        // Only reset scroll + selection + editing when the COLUMN SCHEMA
+        // changes. Data length is too weak a signal:
+        //   - Streaming inserts grow the length and shouldn't move scroll.
+        //   - Filter / delete events shrink the length and shouldn't either
+        //     (the user's spot in the data is what they care about).
+        //   - Sort changes preserve length but mean "start from the top",
+        //     so callers who want that should drive it explicitly via
+        //     api.scrollToTop() (or the equivalent).
+        // The columns ARE a schema change: existing scroll/selection
+        // coordinates are no longer meaningful when the grid's column set
+        // is replaced, so we still reset there.
+        const colCount = props.columns.length;
+        const nextSignature = `cols:${colCount}`;
+        if (nextSignature === lastResetSignature)
+            return;
+        const isFirstRender = lastResetSignature === "";
+        lastResetSignature = nextSignature;
+        if (isFirstRender)
+            return;
+        selectionRange = { anchor: null, focus: null };
+        selectionRanges = [];
+        editingCell = null;
+        if (scrollContainer) {
+            scrollContainer.scrollTop = 0;
+            scrollContainer.scrollLeft = 0;
+            scrollVersion += 1;
+        }
+        virtualizer.setScrollOffset(0);
+        columnVirtualizer.setHorizontalOffset(0);
+    });
+    // Wire scroll-change listeners SEPARATELY for each scrollbar - bundling
+    // them in one effect with `if (!vertical || !horizontal) return` was
+    // the bug behind "vertical scrollbar can't be dragged": with overflow
+    // gating, demos without horizontal overflow never mount the horizontal
+    // scrollbar, the combined guard tripped, and the vertical listener
+    // never got attached either. Each scrollbar is now independent.
+    $effect(() => {
+        if (!scrollContainer || !verticalScrollbarEl)
+            return;
+        const el = verticalScrollbarEl;
+        const onVertical = (event) => {
+            const container = scrollContainer;
+            if (!container)
+                return;
+            const customEvent = event;
+            container.scrollTop = customEvent.detail.value;
+            scheduleScrollSync(container.scrollTop, container.scrollLeft);
+        };
+        el.addEventListener("scroll-change", onVertical);
+        return () => el.removeEventListener("scroll-change", onVertical);
+    });
+    $effect(() => {
+        if (!scrollContainer || !horizontalScrollbarEl)
+            return;
+        const el = horizontalScrollbarEl;
+        const onHorizontal = (event) => {
+            const container = scrollContainer;
+            if (!container)
+                return;
+            const customEvent = event;
+            container.scrollLeft = customEvent.detail.value;
+            scheduleScrollSync(container.scrollTop, container.scrollLeft);
+        };
+        el.addEventListener("scroll-change", onHorizontal);
+        return () => el.removeEventListener("scroll-change", onHorizontal);
+    });
+    $effect(() => {
+        // When containerHeight is a string (e.g. "100%") the actual pixel height
+        // depends on the parent layout - read it from the live scroll container.
+        // We track `viewportVersion` (only bumped by the ResizeObserver below)
+        // instead of `scrollVersion` so this effect does NOT re-run on every
+        // scroll event - which would otherwise re-call setOptions hundreds of
+        // times during a drag.
+        viewportVersion;
+        const viewportHeight = typeof props.containerHeight === "string"
+            ? (scrollContainer?.clientHeight ?? 520)
+            : (props.containerHeight ?? 520);
+        const rh = props.rowHeight;
+        virtualizer.setOptions({
+            count: allRows.length,
+            estimateSize: typeof rh === "function" ? rh : (rh ?? 30),
+            overscan: props.overscan ?? 8,
+            viewportHeight,
+        });
+    });
+    // Track size changes of the shell so the virtualizer's viewport, the
+    // fit-columns scale, and anything else that depends on the container
+    // width/height stays in sync. Always attached (window resize / parent
+    // layout shift / sidebar collapse can change the size whether the
+    // consumer passed a numeric or "100%" containerHeight).
+    /** True after the first ResizeObserver tick - i.e. once the grid has
+     *  measured its real container size and `fitColumns` has had a chance
+     *  to scale the columns to that width. Used to gate the scrollbar
+     *  visibility: rendering it before this flips paints a horizontal
+     *  scrollbar for ONE frame (based on the base column widths summing
+     *  larger than the viewport), then immediately hides it once fit
+     *  scaling kicks in - visible as a "flashing horizontal scrollbar"
+     *  every time a demo first loads. */
+    let hasMeasured = $state(false);
+    $effect(() => {
+        if (!scrollContainer)
+            return;
+        const observer = new ResizeObserver(() => {
+            viewportVersion += 1;
+            if (!hasMeasured)
+                hasMeasured = true;
+        });
+        observer.observe(scrollContainer);
+        return () => observer.disconnect();
+    });
+    $effect(() => {
+        // Reading columnWidths here registers it as a reactive dependency so
+        // the effect re-runs when the user resizes a column. We pass a fresh
+        // closure each run; the virtualizer sees a new function reference and
+        // re-derives its layout from the current per-column widths.
+        columnWidths;
+        columnVirtualizer.setOptions({
+            count: allColumns.length,
+            estimateSize: (index) => {
+                const column = allColumns[index];
+                return column ? getColumnWidth(column.id) : (props.columnWidth ?? 140);
+            },
+            overscan: props.columnOverscan ?? 3,
+            viewportHeight: viewportWidth,
+        });
+    });
+    $effect(() => {
+        if (!scrollContainer)
+            return;
+        if (rowVirtualizationEnabled)
+            virtualizer.setScrollOffset(domToLogicalRowOffset(scrollContainer.scrollTop));
+        if (columnVirtualizationEnabled)
+            columnVirtualizer.setHorizontalOffset(scrollContainer.scrollLeft);
+    });
+    // Re-arms once the user scrolls away from the bottom, so a long lazy-load
+    // run only fires `onScrollBottomReached` once per arrival at the end.
+    let scrollBottomArmed = true;
+    /** Cached normalized options keyed by columnId - only used when the column
+     *  has a static (non-function) `editorOptions`. Dynamic (per-row) options
+     *  are resolved on every call because they can change as other cells in
+     *  the same row change (the whole point of cascading editors). */
+    const editorOptionsCache = {};
+    const headerSelectionState = $derived.by(() => {
+        gridStateVersion;
+        const selectable = allRows.filter((row) => !isGroupRow(row));
+        if (!selectable.length)
+            return "none";
+        let selected = 0;
+        for (const row of selectable)
+            if (rowSelectionState[row.id])
+                selected += 1;
+        if (selected === 0)
+            return "none";
+        return selected === selectable.length ? "all" : "some";
+    });
+    /** True once a real interaction (click, keyboard nav, or a public-API
+     *  call) has activated a cell. Distinct from `activeCell.cellId`, which
+     *  the on-mount seed effect populates straight on the grid state without
+     *  going through `setActiveCell` - so it can't tell a seeded (0,0) apart
+     *  from a user-focused (0,0). The fill handle keys off this flag so it
+     *  stays hidden until the user actually selects something. */
+    let userHasActivatedCell = $state(false);
+    /**
+     * Per-column fitted widths when `fitColumns` is on. Computed in one pass
+     * so the LAST auto-sized column can absorb the rounding residue and make
+     * the total match the target viewport width exactly. Without this the
+     * per-column `Math.round` calls leave a 2-6 px residue and the user sees
+     * a small horizontal scrollbar even though every column is "fitted".
+     *
+     * User-resized columns (entries in `columnWidths`) are taken at face
+     * value and only the auto-sized columns share the scale + residue.
+     *
+     * Returns `null` when fit scaling is not in effect (off, no room, total
+     * already >= target). Callers then fall back to the base width.
+     */
+    const fittedColumnWidths = $derived.by(() => {
+        // Track viewport size (not scrollVersion) so we don't recompute on
+        // every scroll - only when the container actually resizes.
+        viewportVersion;
+        if (!props.fitColumns)
+            return null;
+        const cols = grid.getAllColumns().filter((c) => !hiddenColumns[c.id]);
+        if (!cols.length)
+            return null;
+        const rowNumberWidth = showRowNumbersEffective ? rowNumberColumnWidth : 0;
+        const selectionWidth = showRowSelectionEffective ? selectionColumnWidth : 0;
+        // Reserve the custom vertical scrollbar's width when it's visible. It
+        // overlays the right 16px of the viewport (absolute, z-index 40) and
+        // does NOT shrink clientWidth, so without this the last fitted column
+        // slides under it and its right-aligned content (e.g. a number column)
+        // is hidden behind the opaque scrollbar.
+        const scrollbarWidth = hasVerticalOverflow ? 16 : 0;
+        const target = (scrollContainer?.clientWidth ?? 0) -
+            rowNumberWidth -
+            selectionWidth -
+            scrollbarWidth;
+        if (target <= 0)
+            return null;
+        // Split base widths into pinned (user-resized) and scalable.
+        let pinnedTotal = 0;
+        let scalableBase = 0;
+        const scalableIds = [];
+        for (const c of cols) {
+            const w = getColumnBaseWidth(c.id);
+            if (columnWidths[c.id] !== undefined)
+                pinnedTotal += w;
+            else {
+                scalableBase += w;
+                scalableIds.push(c.id);
+            }
+        }
+        const scalableTarget = target - pinnedTotal;
+        if (scalableTarget <= 0 || scalableBase <= 0)
+            return null;
+        // Within 1px of target - no scaling needed.
+        if (Math.abs(scalableBase - scalableTarget) <= 1)
+            return null;
+        // Shrink only by a modest amount (≥85% of natural). Beyond that, leave
+        // natural widths and let the user scroll - squashing every column
+        // tighter would hide content.
+        const scale = scalableTarget / scalableBase;
+        if (scale < 0.85)
+            return null;
+        const widths = {};
+        let runningSum = 0;
+        for (let i = 0; i < scalableIds.length - 1; i += 1) {
+            const id = scalableIds[i];
+            const w = Math.max(MIN_COLUMN_WIDTH, Math.round(getColumnBaseWidth(id) * scale));
+            widths[id] = w;
+            runningSum += w;
+        }
+        // The last scalable column absorbs whatever the previous rounding left
+        // behind, so `sum(widths) === scalableTarget` exactly.
+        const lastId = scalableIds[scalableIds.length - 1];
+        widths[lastId] = Math.max(MIN_COLUMN_WIDTH, scalableTarget - runningSum);
+        return widths;
+    });
+    let resizePendingWidth = 0;
+    let resizeRaf = null;
+    /** Where the fill handle should render: the bottom-right cell of the
+     *  selection range (or the active cell if there's no range). Returns
+     *  null when cell selection is off or there is no anchored selection. */
+    const fillHandleCell = $derived.by(() => {
+        if (!(props.enableCellSelection ?? false))
+            return null;
+        const anchor = selectionRange.anchor;
+        const focus = selectionRange.focus;
+        if (anchor && focus) {
+            return {
+                rowIndex: Math.max(anchor.rowIndex, focus.rowIndex),
+                colIndex: Math.max(anchor.colIndex, focus.colIndex),
+            };
+        }
+        const a = activeCell;
+        // Only show the handle once the user (or the public API) has actually
+        // activated a cell. The on-mount seed writes activeCell (0,0) directly
+        // to the grid state, so `cellId` alone can't gate this - see
+        // `userHasActivatedCell`.
+        if (!userHasActivatedCell || !a)
+            return null;
+        return { rowIndex: a.rowIndex, colIndex: a.colIndex };
+    });
+    /**
+     * Lazily-created canvas used to measure text width via the 2D context.
+     * Canvas measurement bypasses the cell's `overflow: hidden; white-space:
+     * nowrap` constraint, which makes the body's `scrollWidth` useless here.
+     */
+    let measureCanvas = null;
+    /**
+     * Range buckets for the value-facet list.
+     *
+     * Numeric and date columns with many distinct values would otherwise
+     * paint thousands of single-value checkboxes in the filter menu -
+     * unusable. When a column's `editorType` is `'number' | 'date' |
+     * 'datetime'` AND it has more than BUCKET_THRESHOLD distinct values,
+     * we collapse the facet list into BUCKET_COUNT equal-width ranges
+     * (e.g. "1,000 - 1,500") and let the user check those.
+     *
+     * The bucket structure carries the numeric bounds so the row filter
+     * can re-test each row's value against the selected ranges without
+     * re-doing the bucket math.
+     */
+    /** Buckets for every column that should be bucketed, computed once and
+     *  reused by both the facet UI and the row filter. Computing them lazily
+     *  in a $derived means columns with no filter menu open and no active
+     *  filter never pay the iteration cost. */
+    const facetBucketsByColumn = $derived.by(() => {
+        const map = new Map();
+        for (const column of allColumns) {
+            const meta = isBucketableColumn(column);
+            if (!meta)
+                continue;
+            const buckets = buildBuckets(column, meta.isDate, props.data, getColumnAccessorValue);
+            if (buckets)
+                map.set(column.id, buckets);
+        }
+        return map;
+    });
+    const columnMenuFacetValues = $derived.by(() => {
+        // The funnel popover drives via `filterMenuFor`; the column menu's Filter
+        // tab drives via `columnMenuFor`. Support whichever is open.
+        const columnId = filterMenuFor ?? columnMenuFor;
+        if (!columnId)
+            return [];
+        const column = allColumns.find((entry) => entry.id === columnId);
+        if (!column)
+            return [];
+        // Range-bucketed facets for numeric / date columns with many values.
+        const buckets = facetBucketsByColumn.get(columnId);
+        if (buckets)
+            return buckets.map((b) => b.label);
+        // Default: distinct-value facets.
+        const seen = new Set();
+        for (const rowData of props.data) {
+            seen.add(String(getColumnAccessorValue(rowData, column) ?? ""));
+        }
+        return Array.from(seen).sort((a, b) => a.localeCompare(b, undefined, { numeric: true }));
+    });
+    const columnMenuVisibleFacets = $derived.by(() => {
+        const query = columnMenuSearch.trim().toLowerCase();
+        if (!query)
+            return columnMenuFacetValues;
+        return columnMenuFacetValues.filter((value) => value.toLowerCase().includes(query));
+    });
+    // Fire onApiReady exactly once when the grid is first ready. Wrapping in
+    // an effect that tracks `props.onApiReady` was racy - every parent render
+    // creates a new inline arrow, the effect re-fired, and any synchronous
+    // state mutation inside the callback (e.g. `api.setGroupBy(...)`) created
+    // an infinite update loop. Now it's a true mount-once notification.
+    let apiNotified = false;
+    $effect(() => {
+        if (apiNotified)
+            return;
+        const cb = props.onApiReady;
+        if (!cb)
+            return;
+        apiNotified = true;
+        cb(buildApi());
+    });
+    const ctx = {
+        get props() { return props; },
+        get editingEnabled() { return editingEnabled; },
+        get paginationEnabled() { return paginationEnabled; },
+        get groupingControlsEnabled() { return groupingControlsEnabled; },
+        get globalFilter() { return globalFilter; },
+        set globalFilter(v) { globalFilter = v; },
+        get scrollContainer() { return scrollContainer; },
+        set scrollContainer(v) { scrollContainer = v; },
+        get gridRootEl() { return gridRootEl; },
+        set gridRootEl(v) { gridRootEl = v; },
+        get filterRowValues() { return filterRowValues; },
+        set filterRowValues(v) { filterRowValues = v; },
+        get filterMenuValues() { return filterMenuValues; },
+        set filterMenuValues(v) { filterMenuValues = v; },
+        get verticalScrollbarEl() { return verticalScrollbarEl; },
+        set verticalScrollbarEl(v) { verticalScrollbarEl = v; },
+        get horizontalScrollbarEl() { return horizontalScrollbarEl; },
+        set horizontalScrollbarEl(v) { horizontalScrollbarEl = v; },
+        get scrollVersion() { return scrollVersion; },
+        set scrollVersion(v) { scrollVersion = v; },
+        get viewportVersion() { return viewportVersion; },
+        set viewportVersion(v) { viewportVersion = v; },
+        get lastResetSignature() { return lastResetSignature; },
+        set lastResetSignature(v) { lastResetSignature = v; },
+        get pendingScrollTop() { return pendingScrollTop; },
+        set pendingScrollTop(v) { pendingScrollTop = v; },
+        get pendingScrollLeft() { return pendingScrollLeft; },
+        set pendingScrollLeft(v) { pendingScrollLeft = v; },
+        get scrollSyncRaf() { return scrollSyncRaf; },
+        set scrollSyncRaf(v) { scrollSyncRaf = v; },
+        get selectionRange() { return selectionRange; },
+        set selectionRange(v) { selectionRange = v; },
+        get selectionRanges() { return selectionRanges; },
+        set selectionRanges(v) { selectionRanges = v; },
+        get isDraggingSelection() { return isDraggingSelection; },
+        set isDraggingSelection(v) { isDraggingSelection = v; },
+        get fillDrag() { return fillDrag; },
+        set fillDrag(v) { fillDrag = v; },
+        get activeAtPointerDown() { return activeAtPointerDown; },
+        set activeAtPointerDown(v) { activeAtPointerDown = v; },
+        get editingCell() { return editingCell; },
+        set editingCell(v) { editingCell = v; },
+        get fullRowEdit() { return fullRowEdit; },
+        set fullRowEdit(v) { fullRowEdit = v; },
+        get editedCellValues() { return editedCellValues; },
+        set editedCellValues(v) { editedCellValues = v; },
+        get UNDO_LIMIT() { return UNDO_LIMIT; },
+        get history() { return history; },
+        set history(v) { history = v; },
+        get historyPtr() { return historyPtr; },
+        set historyPtr(v) { historyPtr = v; },
+        get historyVersion() { return historyVersion; },
+        set historyVersion(v) { historyVersion = v; },
+        get tooltip() { return tooltip; },
+        set tooltip(v) { tooltip = v; },
+        get tooltipTimer() { return tooltipTimer; },
+        set tooltipTimer(v) { tooltipTimer = v; },
+        get showTooltipFor() { return showTooltipFor; },
+        get hideTooltip() { return hideTooltip; },
+        get findOpen() { return findOpen; },
+        set findOpen(v) { findOpen = v; },
+        get findQuery() { return findQuery; },
+        set findQuery(v) { findQuery = v; },
+        get findHitIndex() { return findHitIndex; },
+        set findHitIndex(v) { findHitIndex = v; },
+        get findHits() { return findHits; },
+        get theadEl() { return theadEl; },
+        set theadEl(v) { theadEl = v; },
+        get headerHeight() { return headerHeight; },
+        set headerHeight(v) { headerHeight = v; },
+        get editorSelectAll() { return editorSelectAll; },
+        set editorSelectAll(v) { editorSelectAll = v; },
+        get columnWidths() { return columnWidths; },
+        set columnWidths(v) { columnWidths = v; },
+        get resizingColumnId() { return resizingColumnId; },
+        set resizingColumnId(v) { resizingColumnId = v; },
+        get resizeStartX() { return resizeStartX; },
+        set resizeStartX(v) { resizeStartX = v; },
+        get resizeStartWidth() { return resizeStartWidth; },
+        set resizeStartWidth(v) { resizeStartWidth = v; },
+        get MIN_COLUMN_WIDTH() { return MIN_COLUMN_WIDTH; },
+        get columnPinning() { return columnPinning; },
+        set columnPinning(v) { columnPinning = v; },
+        get columnVirtualizerVersion() { return columnVirtualizerVersion; },
+        set columnVirtualizerVersion(v) { columnVirtualizerVersion = v; },
+        get gridStateVersion() { return gridStateVersion; },
+        set gridStateVersion(v) { gridStateVersion = v; },
+        get selectionColumnWidth() { return selectionColumnWidth; },
+        get rowNumberColumnWidth() { return rowNumberColumnWidth; },
+        get showRowNumbersEffective() { return showRowNumbersEffective; },
+        get filterOperatorOptions() { return filterOperatorOptions; },
+        get TEXT_OPERATORS() { return TEXT_OPERATORS; },
+        get NUMBER_OPERATORS() { return NUMBER_OPERATORS; },
+        get DATE_OPERATORS() { return DATE_OPERATORS; },
+        get CHECKBOX_OPERATORS() { return CHECKBOX_OPERATORS; },
+        get columnMenuFor() { return columnMenuFor; },
+        get columnMenuTab() { return columnMenuTab; },
+        set columnMenuTab(v) { columnMenuTab = v; },
+        set columnMenuFor(v) { columnMenuFor = v; },
+        get columnMenuPos() { return columnMenuPos; },
+        set columnMenuPos(v) { columnMenuPos = v; },
+        get columnMenuSearch() { return columnMenuSearch; },
+        set columnMenuSearch(v) { columnMenuSearch = v; },
+        get filterMenuFor() { return filterMenuFor; },
+        set filterMenuFor(v) { filterMenuFor = v; },
+        get filterMenuPos() { return filterMenuPos; },
+        set filterMenuPos(v) { filterMenuPos = v; },
+        get operatorMenuFor() { return operatorMenuFor; },
+        set operatorMenuFor(v) { operatorMenuFor = v; },
+        get operatorMenuPos() { return operatorMenuPos; },
+        set operatorMenuPos(v) { operatorMenuPos = v; },
+        get chooseColumnsPos() { return chooseColumnsPos; },
+        set chooseColumnsPos(v) { chooseColumnsPos = v; },
+        get contextMenuFor() { return contextMenuFor; },
+        set contextMenuFor(v) { contextMenuFor = v; },
+        get contextMenuPos() { return contextMenuPos; },
+        set contextMenuPos(v) { contextMenuPos = v; },
+        get noteOverrides() { return noteOverrides; },
+        set noteOverrides(v) { noteOverrides = v; },
+        get commentEditFor() { return commentEditFor; },
+        set commentEditFor(v) { commentEditFor = v; },
+        get commentDraft() { return commentDraft; },
+        set commentDraft(v) { commentDraft = v; },
+        get valueFilters() { return valueFilters; },
+        set valueFilters(v) { valueFilters = v; },
+        get viewportWidth() { return viewportWidth; },
+        get viewportHeight() { return viewportHeight; },
+        get scrollMetrics() { return scrollMetrics; },
+        get hasVerticalOverflow() { return hasVerticalOverflow; },
+        get showGlobalFilterEffective() { return showGlobalFilterEffective; },
+        get showFilterRowEffective() { return showFilterRowEffective; },
+        get showColumnFiltersEffective() { return showColumnFiltersEffective; },
+        get showInlineColumnFilterEffective() { return showInlineColumnFilterEffective; },
+        get showRowSelectionEffective() { return showRowSelectionEffective; },
+        get enableCellSelectionEffective() { return enableCellSelectionEffective; },
+        get flushScheduledScrollSync() { return flushScheduledScrollSync; },
+        get scheduleScrollSync() { return scheduleScrollSync; },
+        get internalData() { return internalData; },
+        set internalData(v) { internalData = v; },
+        get internalColumns() { return internalColumns; },
+        set internalColumns(v) { internalColumns = v; },
+        get hiddenColumns() { return hiddenColumns; },
+        set hiddenColumns(v) { hiddenColumns = v; },
+        get toggleColumnGroup() { return toggleColumnGroup; },
+        get isColumnGroupCollapsed() { return isColumnGroupCollapsed; },
+        get externalSortEnabled() { return externalSortEnabled; },
+        get externalFilterEnabled() { return externalFilterEnabled; },
+        get passthroughSortedRowModel() { return passthroughSortedRowModel; },
+        get resolveEffectiveFeatures() { return resolveEffectiveFeatures; },
+        get grid() { return grid; },
+        get userColumnOrder() { return userColumnOrder; },
+        set userColumnOrder(v) { userColumnOrder = v; },
+        get lastSeededOrder() { return lastSeededOrder; },
+        set lastSeededOrder(v) { lastSeededOrder = v; },
+        get allColumns() { return allColumns; },
+        get headerGroups() { return headerGroups; },
+        get groupHeaderRows() { return groupHeaderRows; },
+        get pinnedOffsets() { return pinnedOffsets; },
+        get cellPinStyle() { return cellPinStyle; },
+        get isColumnPinned() { return isColumnPinned; },
+        get colDragId() { return colDragId; },
+        set colDragId(v) { colDragId = v; },
+        get colDropOnId() { return colDropOnId; },
+        set colDropOnId(v) { colDropOnId = v; },
+        get colDropSide() { return colDropSide; },
+        set colDropSide(v) { colDropSide = v; },
+        get rowDragActive() { return rowDragActive; },
+        set rowDragActive(v) { rowDragActive = v; },
+        get rowDropIndex() { return rowDropIndex; },
+        set rowDropIndex(v) { rowDropIndex = v; },
+        get rowDropSide() { return rowDropSide; },
+        set rowDropSide(v) { rowDropSide = v; },
+        get onRowDragStart() { return onRowDragStart; },
+        get onRowDragOver() { return onRowDragOver; },
+        get onRowDragLeave() { return onRowDragLeave; },
+        get onRowDrop() { return onRowDrop; },
+        get onRowsContainerDragOver() { return onRowsContainerDragOver; },
+        get onRowsContainerDrop() { return onRowsContainerDrop; },
+        get onRowDragEnd() { return onRowDragEnd; },
+        get broadcastAlignedScroll() { return broadcastAlignedScroll; },
+        get getCurrentColumnOrder() { return getCurrentColumnOrder; },
+        get emitColumnOrder() { return emitColumnOrder; },
+        get setColumnOrderInternal() { return setColumnOrderInternal; },
+        get applyColumnDrop() { return applyColumnDrop; },
+        get onColumnHeaderDragStart() { return onColumnHeaderDragStart; },
+        get onColumnHeaderDragOver() { return onColumnHeaderDragOver; },
+        get onColumnHeaderDragLeave() { return onColumnHeaderDragLeave; },
+        get onColumnHeaderDrop() { return onColumnHeaderDrop; },
+        get onColumnHeaderDragEnd() { return onColumnHeaderDragEnd; },
+        get pinColumnLeft() { return pinColumnLeft; },
+        get pinColumnRight() { return pinColumnRight; },
+        get unpinColumn() { return unpinColumn; },
+        get getColumnBaseValue() { return getColumnBaseValue; },
+        get hasConditionalFormats() { return hasConditionalFormats; },
+        get conditionalColumnStats() { return conditionalColumnStats; },
+        get cellConditionalFormat() { return cellConditionalFormat; },
+        get isGroupRow() { return isGroupRow; },
+        get isCellEditable() { return isCellEditable; },
+        get isCellEditableAt() { return isCellEditableAt; },
+        get sortDirectionByColumn() { return sortDirectionByColumn; },
+        get groupingColumns() { return groupingColumns; },
+        get paginationState() { return paginationState; },
+        get getRowColumnValue() { return getRowColumnValue; },
+        get allRowsBeforePagination() { return allRowsBeforePagination; },
+        get allRows() { return allRows; },
+        get rowSelectionState() { return rowSelectionState; },
+        get lastSelectionSerialized() { return lastSelectionSerialized; },
+        set lastSelectionSerialized(v) { lastSelectionSerialized = v; },
+        get lastCellRangeSerialized() { return lastCellRangeSerialized; },
+        set lastCellRangeSerialized(v) { lastCellRangeSerialized = v; },
+        get statusBarEnabled() { return statusBarEnabled; },
+        get statusBarAggregates() { return statusBarAggregates; },
+        get statusBarStats() { return statusBarStats; },
+        get toolPanelOpen() { return toolPanelOpen; },
+        set toolPanelOpen(v) { toolPanelOpen = v; },
+        get toolPanelTab() { return toolPanelTab; },
+        set toolPanelTab(v) { toolPanelTab = v; },
+        get toolPanelEnabled() { return toolPanelEnabled; },
+        get toolPanelColumns() { return toolPanelColumns; },
+        get toolPanelHeaderLabel() { return toolPanelHeaderLabel; },
+        get toggleColumnVisibleInPanel() { return toggleColumnVisibleInPanel; },
+        get moveColumnInPanel() { return moveColumnInPanel; },
+        get toggleGroupInPanel() { return toggleGroupInPanel; },
+        get lastSortingSerialized() { return lastSortingSerialized; },
+        set lastSortingSerialized(v) { lastSortingSerialized = v; },
+        get lastFiltersSerialized() { return lastFiltersSerialized; },
+        set lastFiltersSerialized(v) { lastFiltersSerialized = v; },
+        get virtualizer() { return virtualizer; },
+        get columnVirtualizer() { return columnVirtualizer; },
+        get rowVirtualizationEnabled() { return rowVirtualizationEnabled; },
+        get columnVirtualizationEnabled() { return columnVirtualizationEnabled; },
+        get virtualRows() { return virtualRows; },
+        get virtualRowTotalSize() { return virtualRowTotalSize; },
+        get virtualRowStart() { return virtualRowStart; },
+        get virtualRowEnd() { return virtualRowEnd; },
+        get virtualRowBottomSpacer() { return virtualRowBottomSpacer; },
+        get rowDomTotalSize() { return rowDomTotalSize; },
+        get rowScrollScalingActive() { return rowScrollScalingActive; },
+        get rowTopSpacer() { return rowTopSpacer; },
+        get rowBottomSpacer() { return rowBottomSpacer; },
+        get domToLogicalRowOffset() { return domToLogicalRowOffset; },
+        get logicalToDomRowOffset() { return logicalToDomRowOffset; },
+        get virtualColumns() { return virtualColumns; },
+        get virtualColumnTotalSize() { return virtualColumnTotalSize; },
+        get renderedColumnItems() { return renderedColumnItems; },
+        get hasRenderedColumn() { return hasRenderedColumn; },
+        get renderedColumns() { return renderedColumns; },
+        get totalColumnWidth() { return totalColumnWidth; },
+        get hasHorizontalOverflow() { return hasHorizontalOverflow; },
+        get columnWindowStart() { return columnWindowStart; },
+        get columnWindowEnd() { return columnWindowEnd; },
+        get columnWindowRightSpacer() { return columnWindowRightSpacer; },
+        get activeCell() { return activeCell; },
+        get activeDescendantId() { return activeDescendantId; },
+        get formatSummaryNumeric() { return formatSummaryNumeric; },
+        get computeSummaries() { return computeSummaries; },
+        get SUMMARY_DEFER_CELL_LIMIT() { return SUMMARY_DEFER_CELL_LIMIT; },
+        get summaryByColumn() { return summaryByColumn; },
+        set summaryByColumn(v) { summaryByColumn = v; },
+        get hasMeasured() { return hasMeasured; },
+        set hasMeasured(v) { hasMeasured = v; },
+        get scrollBottomArmed() { return scrollBottomArmed; },
+        set scrollBottomArmed(v) { scrollBottomArmed = v; },
+        get onBodyScroll() { return onBodyScroll; },
+        get computeRowClass() { return computeRowClass; },
+        get computeCellClass() { return computeCellClass; },
+        get computeCellTooltip() { return computeCellTooltip; },
+        get computeCellNote() { return computeCellNote; },
+        get getCellDisplayValue() { return getCellDisplayValue; },
+        get getColumnAlign() { return getColumnAlign; },
+        get editorOptionsCache() { return editorOptionsCache; },
+        get getColumnEditorOptions() { return getColumnEditorOptions; },
+        get formatListCellValue() { return formatListCellValue; },
+        get formatCellValue() { return formatCellValue; },
+        get getPinnedCellValue() { return getPinnedCellValue; },
+        get formatPinnedValue() { return formatPinnedValue; },
+        get computePinnedCellClass() { return computePinnedCellClass; },
+        get isRowSelected() { return isRowSelected; },
+        get toggleRowSelectionById() { return toggleRowSelectionById; },
+        get headerSelectionState() { return headerSelectionState; },
+        get toggleSelectAllRows() { return toggleSelectAllRows; },
+        get userHasActivatedCell() { return userHasActivatedCell; },
+        set userHasActivatedCell(v) { userHasActivatedCell = v; },
+        get setActiveCell() { return setActiveCell; },
+        get scrollActiveCellIntoView() { return scrollActiveCellIntoView; },
+        get getColumnBaseWidth() { return getColumnBaseWidth; },
+        get fittedColumnWidths() { return fittedColumnWidths; },
+        get getColumnWidth() { return getColumnWidth; },
+        get resizePendingWidth() { return resizePendingWidth; },
+        set resizePendingWidth(v) { resizePendingWidth = v; },
+        get resizeRaf() { return resizeRaf; },
+        set resizeRaf(v) { resizeRaf = v; },
+        get startColumnResize() { return startColumnResize; },
+        get onColumnResizeMove() { return onColumnResizeMove; },
+        get endColumnResize() { return endColumnResize; },
+        get setSelection() { return setSelection; },
+        get extendSelection() { return extendSelection; },
+        get isCellInSelectedRange() { return isCellInSelectedRange; },
+        get getCellRangeEdges() { return getCellRangeEdges; },
+        get getSelectionRects() { return getSelectionRects; },
+        get fillHandleCell() { return fillHandleCell; },
+        get isInFillPreview() { return isInFillPreview; },
+        get findColumnById() { return findColumnById; },
+        get readCellRaw() { return readCellRaw; },
+        get writeCellRaw() { return writeCellRaw; },
+        get applyFillPattern() { return applyFillPattern; },
+        get clearSelectedCellValues() { return clearSelectedCellValues; },
+        get startFillDrag() { return startFillDrag; },
+        get onFillPointerMove() { return onFillPointerMove; },
+        get onFillPointerUp() { return onFillPointerUp; },
+        get toggleBooleanCell() { return toggleBooleanCell; },
+        get onCellPointerDown() { return onCellPointerDown; },
+        get onCellPointerEnter() { return onCellPointerEnter; },
+        get endDragSelection() { return endDragSelection; },
+        get onWindowPointerMove() { return onWindowPointerMove; },
+        get onCellClick() { return onCellClick; },
+        get emitCellDoubleClick() { return emitCellDoubleClick; },
+        get copySelectionToClipboard() { return copySelectionToClipboard; },
+        get cutSelectionToClipboard() { return cutSelectionToClipboard; },
+        get pasteFromClipboard() { return pasteFromClipboard; },
+        get onGridPaste() { return onGridPaste; },
+        get clearSelectedCells() { return clearSelectedCells; },
+        get onCellDoubleClick() { return onCellDoubleClick; },
+        get startEditingWithChar() { return startEditingWithChar; },
+        get startEditing() { return startEditing; },
+        get stopEditing() { return stopEditing; },
+        get startFullRowEdit() { return startFullRowEdit; },
+        get setFullRowDraft() { return setFullRowDraft; },
+        get commitFullRowEdit() { return commitFullRowEdit; },
+        get cancelFullRowEdit() { return cancelFullRowEdit; },
+        get saveEditingCell() { return saveEditingCell; },
+        get applyHistoryStep() { return applyHistoryStep; },
+        get updateEditingCellValue() { return updateEditingCellValue; },
+        get onEditorKeyDown() { return onEditorKeyDown; },
+        get focusOnMount() { return focusOnMount; },
+        get onHeaderSortClick() { return onHeaderSortClick; },
+        get onGridKeyDown() { return onGridKeyDown; },
+        get changePage() { return changePage; },
+        get goToPage() { return goToPage; },
+        get setPageSize() { return setPageSize; },
+        get openContextMenu() { return openContextMenu; },
+        get closeContextMenu() { return closeContextMenu; },
+        get contextMenuItems() { return contextMenuItems; },
+        get saveComment() { return saveComment; },
+        get removeComment() { return removeComment; },
+        get closeCommentEditor() { return closeCommentEditor; },
+        get updateFilterRow() { return updateFilterRow; },
+        get updateFilterOperator() { return updateFilterOperator; },
+        get updateFilterMenuValue() { return updateFilterMenuValue; },
+        get updateFilterMenuValueTo() { return updateFilterMenuValueTo; },
+        get toggleCheckboxWithKeyboard() { return toggleCheckboxWithKeyboard; },
+        get getColumnAccessorValue() { return getColumnAccessorValue; },
+        get fallbackOperatorOption() { return fallbackOperatorOption; },
+        get operatorOption() { return operatorOption; },
+        get operatorsForColumn() { return operatorsForColumn; },
+        get defaultOperatorFor() { return defaultOperatorFor; },
+        get operatorLabelFor() { return operatorLabelFor; },
+        get isColumnFiltered() { return isColumnFiltered; },
+        get closeMenus() { return closeMenus; },
+        get measureCanvas() { return measureCanvas; },
+        set measureCanvas(v) { measureCanvas = v; },
+        get measureText() { return measureText; },
+        get autosizeColumn() { return autosizeColumn; },
+        get autosizeAllColumns() { return autosizeAllColumns; },
+        get resetColumns() { return resetColumns; },
+        get openChooseColumns() { return openChooseColumns; },
+        get openColumnMenu() { return openColumnMenu; },
+        get openFilterMenu() { return openFilterMenu; },
+        get openOperatorMenu() { return openOperatorMenu; },
+        get sortColumnFromMenu() { return sortColumnFromMenu; },
+        get clearColumnSort() { return clearColumnSort; },
+        get groupByColumnFromMenu() { return groupByColumnFromMenu; },
+        get clearGroupingFromMenu() { return clearGroupingFromMenu; },
+        get isBucketableColumn() { return isBucketableColumn; },
+        get buildBuckets() { return buildBuckets; },
+        get isInBucket() { return isInBucket; },
+        get facetBucketsByColumn() { return facetBucketsByColumn; },
+        get columnMenuFacetValues() { return columnMenuFacetValues; },
+        get columnMenuVisibleFacets() { return columnMenuVisibleFacets; },
+        get isFacetChecked() { return isFacetChecked; },
+        get toggleFacetValue() { return toggleFacetValue; },
+        get isAllFacetsChecked() { return isAllFacetsChecked; },
+        get toggleAllFacets() { return toggleAllFacets; },
+        get clearColumnFilter() { return clearColumnFilter; },
+        get onWindowKeydown() { return onWindowKeydown; },
+        get columnDefMatchesId() { return columnDefMatchesId; },
+        get buildApi() { return buildApi; },
+        get apiNotified() { return apiNotified; },
+        set apiNotified(v) { apiNotified = v; },
+    };
+    const { resolveEffectiveFeatures } = createFeatures(ctx);
+    const { showTooltipFor, hideTooltip, flushScheduledScrollSync, scheduleScrollSync, onBodyScroll } = createScrollSync(ctx);
+    const { onGridKeyDown, onWindowKeydown, onHeaderSortClick } = createKeyboard(ctx);
+    const { computeSummaries, hasRenderedColumn } = createSummaries(ctx);
+    const { updateFilterRow, updateFilterOperator, updateFilterMenuValue, updateFilterMenuValueTo, toggleCheckboxWithKeyboard, isColumnFiltered, closeMenus, openChooseColumns, openColumnMenu, openFilterMenu, openOperatorMenu, sortColumnFromMenu, clearColumnSort, groupByColumnFromMenu, clearGroupingFromMenu, isFacetChecked, toggleFacetValue, isAllFacetsChecked, toggleAllFacets, clearColumnFilter, changePage, goToPage, setPageSize, openContextMenu, closeContextMenu, contextMenuItems, saveComment, removeComment, closeCommentEditor } = createMenus(ctx);
+    const { cellConditionalFormat, computeRowClass, computeCellClass, computeCellTooltip, computeCellNote, getColumnEditorOptions, formatListCellValue, formatCellValue, formatPinnedValue, computePinnedCellClass } = createCellRender(ctx);
+    const { isCellEditable, isCellEditableAt, getRowColumnValue, getCellDisplayValue, startEditingWithChar, startEditing, stopEditing, startFullRowEdit, setFullRowDraft, commitFullRowEdit, cancelFullRowEdit, saveEditingCell, applyHistoryStep, updateEditingCellValue, onEditorKeyDown, focusOnMount, onCellDoubleClick, pasteFromClipboard, onGridPaste } = createEditing(ctx);
+    const { isRowSelected, toggleRowSelectionById, toggleSelectAllRows, setActiveCell, scrollActiveCellIntoView, setSelection, extendSelection, isCellInSelectedRange, getCellRangeEdges, getSelectionRects, isInFillPreview, findColumnById, onCellPointerDown, onCellPointerEnter, endDragSelection, onWindowPointerMove, onCellClick, emitCellDoubleClick } = createSelection(ctx);
+    const { cellPinStyle, isColumnPinned, getCurrentColumnOrder, emitColumnOrder, setColumnOrderInternal, applyColumnDrop, onColumnHeaderDragStart, onColumnHeaderDragOver, onColumnHeaderDragLeave, onColumnHeaderDrop, onColumnHeaderDragEnd, pinColumnLeft, pinColumnRight, unpinColumn, toggleColumnVisibleInPanel, moveColumnInPanel, toggleGroupInPanel, getColumnBaseWidth, getColumnWidth, startColumnResize, onColumnResizeMove, endColumnResize, measureText, autosizeColumn, autosizeAllColumns, resetColumns } = createColumns(ctx);
+    const { onRowDragStart, onRowDragOver, onRowDragLeave, onRowDrop, onRowsContainerDragOver, onRowsContainerDrop, onRowDragEnd } = createRowDrag(ctx);
+    const { register: registerAlignedGrid, broadcastScroll: broadcastAlignedScroll, broadcastWidths: broadcastAlignedWidths } = createAlignedGrids(ctx);
+    const { buildApi } = createGridApi(ctx);
+    const { readCellRaw, writeCellRaw, applyFillPattern, clearSelectedCellValues, startFillDrag, onFillPointerMove, onFillPointerUp, toggleBooleanCell, copySelectionToClipboard, clearSelectedCells, cutSelectionToClipboard } = createClipboard(ctx);
+    // Aligned grids: register in the shared group on mount, and mirror column
+    // resizes to peers whenever columnWidths changes. Horizontal-scroll mirroring
+    // is driven from onBodyScroll (via ctx.broadcastAlignedScroll).
+    $effect(() => {
+        if (props.alignedGridGroup == null)
+            return;
+        return registerAlignedGrid();
+    });
+    $effect(() => {
+        // Track columnWidths reactively, then broadcast to aligned peers.
+        void columnWidths;
+        broadcastAlignedWidths();
+    });
+    return ctx;
+}