@svgrid/grid 2.6.4 → 2.6.6

package/src/build-api.ts

@@ -1,846 +1,846 @@
-// build-api handlers extracted from the controller. Imperative event handlers
-// reading/writing controller state via the `ctx` handle; the reactive core
-// ($state/$derived/$effect) stays in the controller.
-import {
-  type RowData,
-  type SvGridApi,
-  type TableFeatures,
-} from "./index";
-import "./sv-grid-scrollbar";
-import { untrack } from "svelte";
-// The export serializers load lazily (their own chunk) so export-format.ts stays
-// out of the base bundle - it is fetched only when an export/copy method is
-// actually invoked (an explicit, already-async user action).
-import type {
-  GridExportColumn,
-  GridExportScope,
-  GridExportOptions,
-  GridClipboardOptions,
-} from "./export-format";
-import type {
-  FilterOperator,
-} from "./SvGrid.types";
-import {
-  isGroupRow,
-  getColumnAlign,
-  columnDefMatchesId,
-} from "./cell-values";
-import { hasAdvancedFilterEngine } from "./advanced-filter.svelte";
-
-export function createGridApi<
-  TFeatures extends TableFeatures = TableFeatures,
-  TData extends RowData = RowData,
->(ctx: any) {
-  function buildApi(): SvGridApi<TFeatures, TData> {
-    const findColumn = (columnId: string) =>
-      ctx.grid.getAllColumns().find((column: any) => column.id === columnId);
-
-    // --- Free data export (CSV / TSV / JSON + clipboard) helpers ----------
-    // Snapshot the VISIBLE columns (field + label + format + align) so the
-    // exporter reproduces on-screen values. Mirrors getColumns()'s visible set.
-    const exportColumns = (): GridExportColumn[] =>
-      ctx.allColumns
-        .map((c: any) => ({
-          field: (c.columnDef as { field?: string }).field as string,
-          header:
-            typeof c.columnDef.header === "string" ? c.columnDef.header : c.id,
-          format: c.columnDef.format,
-          align: getColumnAlign(c),
-        }))
-        .filter((c: GridExportColumn) => !!c.field);
-    // Rows for the requested scope: current view / checked / full dataset.
-    const exportScopeRows = (scope: GridExportScope): TData[] => {
-      if (scope === "all") return ctx.internalData as TData[];
-      const out: TData[] = [];
-      for (const row of ctx.allRows) {
-        if (isGroupRow(row)) continue;
-        if (scope === "selected" && !ctx.rowSelectionState[row.id]) continue;
-        out.push(row.original as TData);
-      }
-      return out;
-    };
-    const projectForExport = async (
-      scope: GridExportScope,
-      columns: ReadonlyArray<string> | undefined,
-      rawValues: boolean | undefined,
-    ) => {
-      const { projectGridRows } = await import("./export-format");
-      return projectGridRows(
-        exportScopeRows(scope) as ReadonlyArray<Record<string, unknown>>,
-        exportColumns(),
-        { columns, rawValues },
-      );
-    };
-
-    return {
-      getCellValue(rowIndex, columnId) {
-        const row = ctx.internalData[rowIndex];
-        const column = findColumn(columnId);
-        if (!row || !column) return undefined;
-        if (column.columnDef.fieldFn)
-          return column.columnDef.fieldFn(row);
-        if (column.columnDef.field)
-          return (row as Record<string, unknown>)[column.columnDef.field];
-        return undefined;
-      },
-      setCellValue(rowIndex, columnId, value) {
-        const row = ctx.internalData[rowIndex];
-        const column = findColumn(columnId);
-        if (!row || !column?.columnDef.field) return;
-        const next = ctx.internalData.slice() as Array<TData>;
-        next[rowIndex] = { ...row, [column.columnDef.field]: value } as TData;
-        ctx.internalData = next;
-      },
-      startEditing(rowIndex, columnId) {
-        return ctx.startEditing(rowIndex, columnId);
-      },
-      stopEditing(cancel) {
-        return ctx.stopEditing(cancel ?? false);
-      },
-      selectCells(ranges) {
-        // Multiple rectangles are supported. Empty array clears everything.
-        if (!ranges || ranges.length === 0) {
-          ctx.selectionRange = { anchor: null, focus: null };
-          ctx.selectionRanges = [];
-          return;
-        }
-        const rowCount = ctx.internalData.length;
-        const colCount = ctx.allColumns.length;
-        if (rowCount === 0 || colCount === 0) return;
-        // Clamp to the visible grid bounds so callers can pass open-ended
-        // values like `[0, 0, Infinity, Infinity]` to mean "select all".
-        const toRange = ([r1, c1, r2, c2]: readonly [number, number, number, number]) => ({
-          anchor: {
-            rowIndex: Math.max(0, Math.min(rowCount - 1, Math.min(r1, r2))),
-            colIndex: Math.max(0, Math.min(colCount - 1, Math.min(c1, c2))),
-          },
-          focus: {
-            rowIndex: Math.max(0, Math.min(rowCount - 1, Math.max(r1, r2))),
-            colIndex: Math.max(0, Math.min(colCount - 1, Math.max(c1, c2))),
-          },
-        });
-        const built = ranges.map(toRange);
-        // Last range is the active one; the rest are committed extras.
-        ctx.selectionRanges = built.slice(0, -1);
-        const active = built[built.length - 1]!;
-        ctx.selectionRange = active;
-        // Move the active cell to the last range's top-left so keyboard
-        // navigation continues from there.
-        ctx.setActiveCell(active.anchor.rowIndex, active.anchor.colIndex);
-      },
-      getSelected() {
-        return ctx
-          .getSelectionRects()
-          .map((r: { minRow: number; minCol: number; maxRow: number; maxCol: number }) =>
-            [r.minRow, r.minCol, r.maxRow, r.maxCol] as [number, number, number, number],
-          );
-      },
-      openChart() {
-        ctx.chartPanelOpen = true;
-      },
-      closeChart() {
-        ctx.chartPanelOpen = false;
-      },
-      getChartSpec() {
-        return ctx.chartSpec;
-      },
-      chartRange(ranges) {
-        if (ranges && ranges.length) this.selectCells(ranges);
-        ctx.chartPanelOpen = true;
-      },
-      configureChart(config) {
-        if (ctx.chartingEnabled) ctx.applyChartConfig(config);
-      },
-      setChartAiHandler(handler) {
-        ctx.chartAiHandler = handler ?? null;
-      },
-      addRow(row, position = "bottom") {
-        this.addRows([row], position);
-      },
-      addRows(rows, position = "bottom") {
-        const next = ctx.internalData.slice() as Array<TData>;
-        if (position === "top") next.unshift(...rows);
-        else if (position === "bottom") next.push(...rows);
-        else if (typeof position === "number")
-          next.splice(Math.max(0, Math.min(position, next.length)), 0, ...rows);
-        ctx.internalData = next;
-      },
-      removeRow(rowIndex) {
-        this.removeRows([rowIndex]);
-      },
-      removeRows(rowIndices) {
-        const drop = new Set(rowIndices);
-        ctx.internalData = ctx.internalData.filter((_: any, i: any) => !drop.has(i));
-      },
-      applyTransaction(tx) {
-        const getId = ctx.props.getRowId;
-        let next = ctx.internalData.slice() as Array<TData>;
-        let added = 0;
-        let updated = 0;
-        let removed = 0;
-
-        if (tx.remove?.length) {
-          const removeIds = new Set<string>();
-          const removeRefs = new Set<TData>();
-          for (const r of tx.remove) {
-            if (typeof r === "string") removeIds.add(r);
-            else removeRefs.add(r as TData);
-          }
-          next = next.filter((row, i) => {
-            const hit =
-              removeRefs.has(row) ||
-              (getId ? removeIds.has(getId(row, i)) : false);
-            if (hit) removed += 1;
-            return !hit;
-          });
-        }
-
-        if (tx.update?.length && getId) {
-          const byId = new Map<string, TData>();
-          for (const u of tx.update) byId.set(getId(u, 0), u);
-          next = next.map((row, i) => {
-            const u = byId.get(getId(row, i));
-            if (u) {
-              updated += 1;
-              return u;
-            }
-            return row;
-          });
-        }
-
-        if (tx.add?.length) {
-          next.push(...(tx.add as Array<TData>));
-          added += tx.add.length;
-        }
-
-        ctx.internalData = next;
-        return { added, updated, removed };
-      },
-      addColumn(column, position = "right") {
-        this.addColumns([column], position);
-      },
-      addColumns(columns, position = "right") {
-        const next = ctx.internalColumns.slice();
-        if (position === "left") next.unshift(...columns);
-        else if (position === "right") next.push(...columns);
-        else if (typeof position === "number")
-          next.splice(
-            Math.max(0, Math.min(position, next.length)),
-            0,
-            ...columns,
-          );
-        ctx.internalColumns = next;
-      },
-      removeColumn(columnId) {
-        ctx.internalColumns = ctx.internalColumns.filter(
-          (def: any) => !columnDefMatchesId(def, columnId),
-        );
-      },
-      setColumnVisible(columnId, visible) {
-        if (visible) {
-          const next = { ...ctx.hiddenColumns };
-          delete next[columnId];
-          ctx.hiddenColumns = next;
-        } else {
-          ctx.hiddenColumns = { ...ctx.hiddenColumns, [columnId]: true };
-        }
-      },
-      isColumnVisible(columnId) {
-        return !ctx.hiddenColumns[columnId];
-      },
-      setSort(columnId, direction) {
-        // Honour the column's `sortable` opt-out. Asking the engine
-        // whether the column can sort folds in both the feature toggle
-        // AND the per-column flag.
-        const col = ctx.allColumns.find((c: any) => c.id === columnId);
-        if (col && !col.getCanSort?.()) return;
-        const clauses = direction
-          ? [{ id: columnId, desc: direction === "desc" }]
-          : (ctx.grid.getState().sorting ?? []).filter(
-              (entry: { id: string }) => entry.id !== columnId,
-            );
-        ctx.grid.store.setState((prev: any) => ({ ...prev, sorting: clauses }));
-      },
-      clearSort() {
-        ctx.grid.store.setState((prev: any) => ({ ...prev, sorting: [] }));
-      },
-      setGroupBy(columnIds) {
-        ctx.grid.setGrouping([...columnIds]);
-      },
-      setOption(key, value) {
-        // Runtime prop override. Writes into the controller's `optionOverrides`
-        // store, which the effective-props proxy merges over the incoming prop, so
-        // the grid re-renders exactly as if the parent had changed that prop.
-        // `undefined` clears the override (falls back to the prop). Reassign the
-        // whole object for reliable reactivity; `untrack` per the `setFilter` note.
-        untrack(() => {
-          const next: Record<string, unknown> = { ...ctx.optionOverrides };
-          if (value === undefined) delete next[key as string];
-          else next[key as string] = value;
-          ctx.optionOverrides = next;
-        });
-      },
-      getOption(key) {
-        // The effective value: the override if set, otherwise the incoming prop.
-        return (ctx.props as Record<string, unknown>)[key as string] as never;
-      },
-      resetOptions() {
-        untrack(() => {
-          ctx.optionOverrides = {};
-        });
-      },
-      setFilter(columnId, filter) {
-        // `untrack`: these imperative mutators read the same filter state they
-        // write (read-modify-write on `filterMenuValues`). When a consumer
-        // calls them from inside a reactive `$effect`, that internal read would
-        // otherwise be captured as a dependency of the caller's effect, and the
-        // write would re-dirty it - an infinite update loop. Untracking the
-        // body keeps the API safe to drive from an effect.
-        untrack(() => {
-          // Honour the column's `filterable` opt-out. Same approach as
-          // `setSort` - `getCanFilter()` already combines the feature flag
-          // and the per-column field.
-          const col = ctx.allColumns.find((c: any) => c.id === columnId);
-          if (col && !col.getCanFilter?.()) return;
-          if (!filter) {
-            this.clearFilter(columnId);
-            return;
-          }
-          ctx.filterMenuValues = {
-            ...ctx.filterMenuValues,
-            [columnId]: {
-              operator: filter.operator,
-              value: filter.value ?? "",
-              ...(filter.operator === "between"
-                ? { valueTo: filter.valueTo ?? "" }
-                : {}),
-              // Optional second condition + join (multi-condition filtering).
-              ...(filter.operator2
-                ? {
-                    operator2: filter.operator2,
-                    value2: filter.value2 ?? "",
-                    join: filter.join ?? "AND",
-                    ...(filter.operator2 === "between"
-                      ? { valueTo2: filter.valueTo2 ?? "" }
-                      : {}),
-                  }
-                : {}),
-            },
-          };
-        });
-      },
-      setFacetFilter(columnId, values) {
-        // See `setFilter` for why the read-modify-write is untracked.
-        untrack(() => {
-          // Empty array OR null both mean "clear this column's facet" -
-          // mirrors how the column menu treats unchecking the last value.
-          if (!values || values.length === 0) {
-            if (ctx.valueFilters[columnId]) {
-              const next = { ...ctx.valueFilters };
-              delete next[columnId];
-              ctx.valueFilters = next;
-            }
-            return;
-          }
-          ctx.valueFilters = {
-            ...ctx.valueFilters,
-            [columnId]: new Set(values),
-          };
-        });
-      },
-      clearFilter(columnId) {
-        ctx.clearColumnFilter(columnId);
-      },
-      refreshEditorOptions(columnId) {
-        // Async `editorOptions` are cached per column (or per column+row for a
-        // per-row source) so opening an editor twice does not refetch. This
-        // drops those entries, so the next render re-runs the source - use it
-        // when the underlying list changed server-side.
-        if (columnId == null) {
-          ctx.asyncEditorOptions = {};
-          return;
-        }
-        const next = { ...ctx.asyncEditorOptions };
-        for (const key of Object.keys(next)) {
-          if (key === columnId || key.startsWith(`${columnId}::`)) delete next[key];
-        }
-        ctx.asyncEditorOptions = next;
-      },
-      clearAllFilters() {
-        // See `setFilter` for why the read-modify-write is untracked.
-        untrack(() => {
-          // Wipe every filter surface in one go: column-menu, filter-row, set
-          // filters, the global search box, and the advanced filter. This
-          // promises "every filter surface", so leaving the advanced one set
-          // would strand rows nobody can see a cause for.
-          ctx.filterMenuValues = {};
-          ctx.filterRowValues = {};
-          ctx.valueFilters = {};
-          if (ctx.globalFilter !== "") ctx.globalFilter = "";
-          if (ctx.advancedFilter !== null) ctx.advancedFilter = null;
-        });
-      },
-      setAdvancedFilter(expr) {
-        // See `setFilter` for why the write is untracked.
-        untrack(() => {
-          ctx.advancedFilter = expr ?? null;
-        });
-      },
-      getAdvancedFilter() {
-        return ctx.advancedFilter ?? null;
-      },
-      clearAdvancedFilter() {
-        untrack(() => {
-          ctx.advancedFilter = null;
-        });
-      },
-      isAdvancedFilterActive() {
-        return ctx.advancedFilter != null && hasAdvancedFilterEngine();
-      },
-      getFilters() {
-        // Return a defensive copy so callers can't mutate internal state.
-        const out: Record<
-          string,
-          { operator: FilterOperator; value: string; valueTo?: string }
-        > = {};
-        for (const [columnId, filter] of Object.entries(ctx.filterMenuValues as Record<string, { operator: FilterOperator; value: string; valueTo?: string }>)) {
-          out[columnId] = {
-            operator: filter.operator,
-            value: filter.value,
-            ...(filter.operator === "between" && filter.valueTo
-              ? { valueTo: filter.valueTo }
-              : {}),
-          };
-        }
-        return out;
-      },
-      getDisplayedRows() {
-        // `allRows` is the final, post-filter, post-sort, post-group,
-        // post-pagination list - exactly what the body renders. Skip group
-        // header rows (they wrap an aggregate, not a TData row).
-        //
-        // `isGroupRow` rather than a `subRows.length` test: a TREE parent also
-        // has subRows, but it is a real data row that renders its own cells, so
-        // dropping it here silently truncated every tree read - including the
-        // enterprise export, whose default row source is this method.
-        const out: TData[] = [];
-        for (const row of ctx.allRows) {
-          if (isGroupRow(row)) continue;
-          out.push(row.original as TData);
-        }
-        return out;
-      },
-      getData() {
-        return ctx.internalData;
-      },
-      getColumns() {
-        // Snapshot every column with its human-readable label and
-        // visibility flag. Used by external code (exporters, column
-        // pickers) so they don't have to re-walk the columnDef tree.
-        // Hidden columns ARE included (with `visible: false`) so a column
-        // picker can re-enable them - callers that only want what's
-        // rendered filter by `.visible` (e.g. the exporter does).
-        const describe = (c: any, visible: boolean) => ({
-          id: c.id,
-          field: (c.columnDef as { field?: string }).field,
-          header:
-            typeof c.columnDef.header === "string"
-              ? c.columnDef.header
-              : c.id,
-          visible,
-          // Surface the format + alignment so exporters can reproduce the
-          // on-screen display value (currency symbol, date pattern, etc.)
-          // instead of dumping raw values. `getColumnAlign` applies the same
-          // editorType-based default the body uses.
-          format: c.columnDef.format,
-          align: getColumnAlign(c),
-          // The column's declared value type. Lets a filter or expression UI
-          // offer the right operators (numeric ranges vs text matching) without
-          // re-walking the columnDef tree.
-          editorType: (c.columnDef as { editorType?: string }).editorType,
-        });
-        // Visible columns first, in their current visual order...
-        const out = ctx.allColumns.map((c: any) => describe(c, true));
-        // ...then any column hidden via `visible: false` / setColumnVisible.
-        // Those aren't in `allColumns` (that list is visible-only), so pull
-        // them straight from the engine's leaf set.
-        const visibleIds = new Set(out.map((c: { id: string }) => c.id));
-        for (const c of ctx.grid.getAllColumns() as any[]) {
-          if (!visibleIds.has(c.id)) out.push(describe(c, false));
-        }
-        return out;
-      },
-      // ---- Free data export (CSV / TSV / JSON + clipboard) -----------------
-      async exportCsv(options: GridExportOptions = {}) {
-        const { serializeDelimited, downloadTextFile } = await import("./export-format");
-        const { records, fields } = await projectForExport(
-          options.rows ?? "displayed",
-          options.columns,
-          options.rawValues,
-        );
-        const text = await serializeDelimited(records, fields, {
-          csv: { delimiter: ",", bom: options.bom ?? true },
-          signal: options.signal,
-          onProgress: options.onProgress,
-        });
-        if (options.download !== false)
-          downloadTextFile(text, `${options.filename ?? "grid"}.csv`, "text/csv;charset=utf-8");
-        return text;
-      },
-      async exportTsv(options: GridExportOptions = {}) {
-        const { serializeDelimited, downloadTextFile } = await import("./export-format");
-        const { records, fields } = await projectForExport(
-          options.rows ?? "displayed",
-          options.columns,
-          options.rawValues,
-        );
-        const text = await serializeDelimited(records, fields, {
-          csv: { delimiter: "\t", bom: options.bom ?? true },
-          signal: options.signal,
-          onProgress: options.onProgress,
-        });
-        if (options.download !== false)
-          downloadTextFile(text, `${options.filename ?? "grid"}.tsv`, "text/tab-separated-values;charset=utf-8");
-        return text;
-      },
-      async exportJson(options: GridExportOptions = {}) {
-        const { serializeJson, downloadTextFile } = await import("./export-format");
-        const { records, fields } = await projectForExport(
-          options.rows ?? "displayed",
-          options.columns,
-          options.rawValues,
-        );
-        const text = await serializeJson(records, fields, {
-          signal: options.signal,
-          onProgress: options.onProgress,
-        });
-        if (options.download !== false)
-          downloadTextFile(text, `${options.filename ?? "grid"}.json`, "application/json");
-        return text;
-      },
-      async copyToClipboard(options: GridClipboardOptions = {}) {
-        const { serializeDelimited, serializeMarkdown, copyTextToClipboard } = await import("./export-format");
-        const { records, fields, align } = await projectForExport(
-          options.rows ?? "displayed",
-          options.columns,
-          options.rawValues,
-        );
-        const format = options.format ?? "tsv";
-        const text =
-          format === "markdown"
-            ? await serializeMarkdown(records, fields, { align })
-            : await serializeDelimited(records, fields, {
-                csv: { delimiter: format === "csv" ? "," : "\t", bom: false },
-              });
-        await copyTextToClipboard(text);
-        return text;
-      },
-      clearRowSelection() {
-        // Wipe the internal selection map AND emit the change so any
-        // consumer holding a derived `selectedRows` resets too.
-        ctx.grid.setRowSelection(() => ({}));
-        ctx.props.onRowSelectionChange?.({}, []);
-      },
-      setColumnWidth(columnId: string, width: number) {
-        const clamped = Math.max(ctx.MIN_COLUMN_WIDTH, Math.floor(width));
-        ctx.columnWidths = { ...ctx.columnWidths, [columnId]: clamped };
-      },
-      getColumnWidths() {
-        // Resolve every column's effective width by consulting both the
-        // resize overrides (`columnWidths`) AND the columnDef defaults,
-        // so the snapshot is round-trippable through setColumnWidth.
-        const out: Record<string, number> = {};
-        for (const c of ctx.allColumns) out[c.id] = ctx.getColumnWidth(c.id);
-        return out;
-      },
-      autosizeColumn(columnId: string) {
-        ctx.autosizeColumn(columnId);
-      },
-      autosizeAllColumns() {
-        ctx.autosizeAllColumns();
-      },
-      setColumnPinning(pinning) {
-        // Defensive copy + dedupe so callers can't mutate our state.
-        const left = Array.from(new Set(pinning.left ?? []));
-        const right = Array.from(new Set(pinning.right ?? []));
-        ctx.columnPinning = { left, right };
-      },
-      getColumnPinning() {
-        return {
-          left: ctx.columnPinning.left.slice(),
-          right: ctx.columnPinning.right.slice(),
-        };
-      },
-      // ---- Column reorder
-      setColumnOrder(order) {
-        ctx.setColumnOrderInternal(order);
-      },
-      getColumnOrder() {
-        return ctx.getCurrentColumnOrder();
-      },
-      setRowExpanded(id, expanded) {
-        ctx.grid.setExpanded((prev: any) => ({ ...prev, [id]: !!expanded }));
-      },
-      expandAllGroups() {
-        // Walk the current grouped row model and flip every group node on.
-        const next: Record<string, boolean> = {};
-        const walk = (rows: ReadonlyArray<{ id: string; getCanExpand?: () => boolean; subRows?: ReadonlyArray<unknown> }>) => {
-          for (const row of rows) {
-            if (row.getCanExpand?.()) next[row.id] = true;
-            const sub = row.subRows as ReadonlyArray<{ id: string; getCanExpand?: () => boolean; subRows?: ReadonlyArray<unknown> }> | undefined;
-            if (sub && sub.length > 0) walk(sub);
-          }
-        };
-        walk(ctx.grid.getRowModel().rows as unknown as ReadonlyArray<{ id: string; getCanExpand?: () => boolean; subRows?: ReadonlyArray<unknown> }>);
-        ctx.grid.setExpanded(() => next);
-      },
-      collapseAllGroups() {
-        ctx.grid.setExpanded(() => ({}));
-      },
-      // ---- Undo / redo (history + pointer)
-      undo() {
-        if (ctx.historyPtr < 0) return false
-        const step = ctx.history[ctx.historyPtr]
-        if (!step) return false
-        ctx.applyHistoryStep(step, 'undo')
-        ctx.historyPtr -= 1
-        ctx.historyVersion += 1
-        return true
-      },
-      redo() {
-        if (ctx.historyPtr >= ctx.history.length - 1) return false
-        const step = ctx.history[ctx.historyPtr + 1]
-        if (!step) return false
-        ctx.applyHistoryStep(step, 'redo')
-        ctx.historyPtr += 1
-        ctx.historyVersion += 1
-        return true
-      },
-      canUndo() { void ctx.historyVersion; return ctx.historyPtr >= 0 },
-      canRedo() { void ctx.historyVersion; return ctx.historyPtr < ctx.history.length - 1 },
-      clearHistory() { ctx.history = []; ctx.historyPtr = -1; ctx.historyVersion += 1 },
-      // ---- Find
-      openFind()  { ctx.findOpen = true },
-      closeFind() { ctx.findOpen = false; ctx.findQuery = '' },
-      setFindQuery(q: string) { ctx.findQuery = q; ctx.findHitIndex = 0 },
-      getFindHits() { return ctx.findHits.slice() },
-      // ---- Row selection (read + write)
-      getSelectedRows() {
-        const out: TData[] = [];
-        for (const row of ctx.allRows) {
-          if (isGroupRow(row)) continue;
-          if (ctx.rowSelectionState[row.id]) out.push(row.original as TData);
-        }
-        return out;
-      },
-      getSelectedRowIds() {
-        const out: string[] = [];
-        for (const row of ctx.allRows) {
-          if (!isGroupRow(row) && ctx.rowSelectionState[row.id]) out.push(row.id);
-        }
-        return out;
-      },
-      selectRows(ids, additive = false) {
-        const set = new Set(ids);
-        ctx.grid.setRowSelection((prev: any) => {
-          const next: Record<string, boolean> = additive ? { ...prev } : {};
-          for (const id of set) next[id] = true;
-          return next;
-        });
-      },
-      selectAllRows() {
-        const next: Record<string, boolean> = {};
-        for (const row of ctx.allRows) if (!isGroupRow(row)) next[row.id] = true;
-        ctx.grid.setRowSelection(() => next);
-      },
-      toggleRowSelected(id) {
-        ctx.toggleRowSelectionById(id);
-      },
-      // ---- Pagination
-      getPageInfo() {
-        const { pageIndex, pageSize } = ctx.paginationState;
-        const total = ctx.allRowsBeforePagination.length;
-        const pageCount = Math.max(1, Math.ceil(total / Math.max(1, pageSize)));
-        return { pageIndex, pageSize, pageCount, total };
-      },
-      setPage(pageIndex) {
-        const total = ctx.allRowsBeforePagination.length;
-        const pageCount = Math.max(
-          1,
-          Math.ceil(total / Math.max(1, ctx.paginationState.pageSize)),
-        );
-        ctx.goToPage(Math.max(0, Math.min(pageIndex, pageCount - 1)));
-      },
-      nextPage() {
-        this.setPage(ctx.paginationState.pageIndex + 1);
-      },
-      prevPage() {
-        this.setPage(ctx.paginationState.pageIndex - 1);
-      },
-      firstPage() {
-        this.setPage(0);
-      },
-      lastPage() {
-        const total = ctx.allRowsBeforePagination.length;
-        const pageCount = Math.max(
-          1,
-          Math.ceil(total / Math.max(1, ctx.paginationState.pageSize)),
-        );
-        this.setPage(pageCount - 1);
-      },
-      setPageSize(size) {
-        // Calls the component-level helper (lexical scope), not this method.
-        ctx.setPageSize(Math.max(1, Math.floor(size)));
-      },
-      // ---- Navigation / scrolling
-      scrollToRow(rowIndex) {
-        if (!ctx.scrollContainer) return;
-        const maxIndex = Math.max(0, ctx.allRows.length - 1);
-        const clamped = Math.max(0, Math.min(rowIndex, maxIndex));
-        // Logical offset from the virtualizer (honors uniform OR per-row
-        // sizing), then mapped into the capped DOM scroll space so it lands
-        // correctly on huge grids where the DOM height is scaled down.
-        const logical = ctx.virtualizer.getOffsetForIndex(clamped);
-        ctx.scrollContainer.scrollTop = ctx.logicalToDomRowOffset(logical);
-        ctx.scheduleScrollSync(
-          ctx.scrollContainer.scrollTop,
-          ctx.scrollContainer.scrollLeft,
-        );
-      },
-      getActiveCell() {
-        const a = ctx.activeCell;
-        if (!a || a.rowIndex < 0 || a.colIndex < 0) return null;
-        const col = ctx.allColumns[a.colIndex];
-        return {
-          rowIndex: a.rowIndex,
-          colIndex: a.colIndex,
-          columnId: col?.id ?? "",
-        };
-      },
-      setActiveCell(rowIndex, colIndex) {
-        const r = Math.max(0, Math.min(rowIndex, Math.max(0, ctx.allRows.length - 1)));
-        const c = Math.max(
-          0,
-          Math.min(colIndex, Math.max(0, ctx.allColumns.length - 1)),
-        );
-        // Calls the component-level helper (lexical scope), not this method.
-        ctx.setActiveCell(r, c);
-      },
-      // ---- View state (save / restore)
-      getState() {
-        return {
-          sorting: (ctx.grid.getState().sorting ?? []).map(
-            (s: { id: string; desc: boolean }) => ({ id: s.id, desc: s.desc }),
-          ),
-          grouping: [...(ctx.grid.getState().grouping ?? [])],
-          pagination: {
-            pageIndex: ctx.paginationState.pageIndex,
-            pageSize: ctx.paginationState.pageSize,
-          },
-          columnWidths: this.getColumnWidths(),
-          columnPinning: this.getColumnPinning(),
-          columnOrder: ctx.getCurrentColumnOrder(),
-          hiddenColumns: Object.keys(ctx.hiddenColumns).filter(
-            (k) => ctx.hiddenColumns[k],
-          ),
-          globalFilter: ctx.globalFilter,
-          columnFilters: this.getFilters(),
-          facetFilters: Object.fromEntries(
-            Object.entries(ctx.valueFilters).map(([k, set]: [string, any]) => [
-              k,
-              Array.from(set),
-            ]),
-          ),
-          // Emitted only when set. `attachAutoSavedView` diffs
-          // JSON.stringify(getState()) on a timer, so adding an always-present
-          // key would change every existing snapshot and force one spurious
-          // save in every app on upgrade.
-          ...(ctx.advancedFilter ? { advancedFilter: ctx.advancedFilter } : {}),
-          ...(ctx.chartingEnabled
-            ? {
-                chart: {
-                  open: ctx.chartPanelOpen,
-                  type: ctx.chartType,
-                  dimension: ctx.chartDimensionId,
-                  series: ctx.chartSeriesId,
-                  measure: ctx.chartMeasureId,
-                  reduce: ctx.chartReduce,
-                  stacked: ctx.chartStacked,
-                },
-                charts: ctx.getChartsState(),
-                chartActive: ctx.activeChartIndex,
-              }
-            : {}),
-        };
-      },
-      setState(state) {
-        if (state.sorting) {
-          const sorting = state.sorting.map((s) => ({ id: s.id, desc: s.desc }));
-          ctx.grid.store.setState((prev: any) => ({ ...prev, sorting }));
-        }
-        if (state.grouping) {
-          // Drop grouping by columns that no longer exist (#53) - otherwise a
-          // saved view collapses every row into a group named 'undefined'.
-          const existing = new Set((ctx.grid.getAllColumns() as any[]).map((c) => c.id));
-          ctx.grid.setGrouping(state.grouping.filter((id: string) => existing.has(id)));
-        }
-        if (state.pagination) {
-          const p = state.pagination;
-          ctx.grid.setPagination((prev: any) => ({ ...prev, ...p }));
-        }
-        if (state.columnWidths) ctx.columnWidths = { ...state.columnWidths };
-        if (state.columnPinning)
-          ctx.columnPinning = {
-            left: [...(state.columnPinning.left ?? [])],
-            right: [...(state.columnPinning.right ?? [])],
-          };
-        if (state.columnOrder) ctx.setColumnOrderInternal(state.columnOrder);
-        if (state.hiddenColumns) {
-          // Seed from columns declared `visible: false` so a partial/empty saved
-          // state never un-hides an app-declared-hidden column (#54); then layer
-          // the saved user-driven hides on top.
-          const next: Record<string, boolean> = { ...ctx.declaredHiddenColumns };
-          for (const id of state.hiddenColumns) next[id] = true;
-          ctx.hiddenColumns = next;
-        }
-        if (state.globalFilter !== undefined) ctx.globalFilter = state.globalFilter;
-        if (state.columnFilters)
-          ctx.filterMenuValues = { ...state.columnFilters };
-        if (state.facetFilters) {
-          const next: Record<string, Set<string>> = {};
-          for (const [k, arr] of Object.entries(state.facetFilters))
-            next[k] = new Set(arr);
-          ctx.valueFilters = next;
-        }
-        // `in` rather than a truthiness check, so an explicit null clears while
-        // an absent key leaves the current filter alone (the documented
-        // "only the keys present are applied" contract).
-        if ("advancedFilter" in state) {
-          ctx.advancedFilter = state.advancedFilter ?? null;
-        }
-        if ((state.chart || state.charts) && ctx.chartingEnabled) {
-          if (Array.isArray(state.charts) && state.charts.length) {
-            ctx.applyChartsState(state.charts, state.chartActive);
-          }
-          if (state.chart) {
-            const c = state.chart;
-            ctx.chartPanelOpen = c.open;
-            ctx.chartType = c.type;
-            ctx.chartDimensionId = c.dimension;
-            ctx.chartSeriesId = c.series;
-            ctx.chartMeasureId = c.measure;
-            ctx.chartReduce = c.reduce;
-            ctx.chartStacked = c.stacked;
-          }
-        }
-      },
-      refresh() {
-        ctx.grid.store.setState((prev: any) => ({ ...prev }));
-      },
-    };
-  }
-
-  return {
-    buildApi,
-  };
-}
+// build-api handlers extracted from the controller. Imperative event handlers
+// reading/writing controller state via the `ctx` handle; the reactive core
+// ($state/$derived/$effect) stays in the controller.
+import {
+  type RowData,
+  type SvGridApi,
+  type TableFeatures,
+} from "./index";
+import "./sv-grid-scrollbar";
+import { untrack } from "svelte";
+// The export serializers load lazily (their own chunk) so export-format.ts stays
+// out of the base bundle - it is fetched only when an export/copy method is
+// actually invoked (an explicit, already-async user action).
+import type {
+  GridExportColumn,
+  GridExportScope,
+  GridExportOptions,
+  GridClipboardOptions,
+} from "./export-format";
+import type {
+  FilterOperator,
+} from "./SvGrid.types";
+import {
+  isGroupRow,
+  getColumnAlign,
+  columnDefMatchesId,
+} from "./cell-values";
+import { hasAdvancedFilterEngine } from "./advanced-filter.svelte";
+
+export function createGridApi<
+  TFeatures extends TableFeatures = TableFeatures,
+  TData extends RowData = RowData,
+>(ctx: any) {
+  function buildApi(): SvGridApi<TFeatures, TData> {
+    const findColumn = (columnId: string) =>
+      ctx.grid.getAllColumns().find((column: any) => column.id === columnId);
+
+    // --- Free data export (CSV / TSV / JSON + clipboard) helpers ----------
+    // Snapshot the VISIBLE columns (field + label + format + align) so the
+    // exporter reproduces on-screen values. Mirrors getColumns()'s visible set.
+    const exportColumns = (): GridExportColumn[] =>
+      ctx.allColumns
+        .map((c: any) => ({
+          field: (c.columnDef as { field?: string }).field as string,
+          header:
+            typeof c.columnDef.header === "string" ? c.columnDef.header : c.id,
+          format: c.columnDef.format,
+          align: getColumnAlign(c),
+        }))
+        .filter((c: GridExportColumn) => !!c.field);
+    // Rows for the requested scope: current view / checked / full dataset.
+    const exportScopeRows = (scope: GridExportScope): TData[] => {
+      if (scope === "all") return ctx.internalData as TData[];
+      const out: TData[] = [];
+      for (const row of ctx.allRows) {
+        if (isGroupRow(row)) continue;
+        if (scope === "selected" && !ctx.rowSelectionState[row.id]) continue;
+        out.push(row.original as TData);
+      }
+      return out;
+    };
+    const projectForExport = async (
+      scope: GridExportScope,
+      columns: ReadonlyArray<string> | undefined,
+      rawValues: boolean | undefined,
+    ) => {
+      const { projectGridRows } = await import("./export-format");
+      return projectGridRows(
+        exportScopeRows(scope) as ReadonlyArray<Record<string, unknown>>,
+        exportColumns(),
+        { columns, rawValues },
+      );
+    };
+
+    return {
+      getCellValue(rowIndex, columnId) {
+        const row = ctx.internalData[rowIndex];
+        const column = findColumn(columnId);
+        if (!row || !column) return undefined;
+        if (column.columnDef.fieldFn)
+          return column.columnDef.fieldFn(row);
+        if (column.columnDef.field)
+          return (row as Record<string, unknown>)[column.columnDef.field];
+        return undefined;
+      },
+      setCellValue(rowIndex, columnId, value) {
+        const row = ctx.internalData[rowIndex];
+        const column = findColumn(columnId);
+        if (!row || !column?.columnDef.field) return;
+        const next = ctx.internalData.slice() as Array<TData>;
+        next[rowIndex] = { ...row, [column.columnDef.field]: value } as TData;
+        ctx.internalData = next;
+      },
+      startEditing(rowIndex, columnId) {
+        return ctx.startEditing(rowIndex, columnId);
+      },
+      stopEditing(cancel) {
+        return ctx.stopEditing(cancel ?? false);
+      },
+      selectCells(ranges) {
+        // Multiple rectangles are supported. Empty array clears everything.
+        if (!ranges || ranges.length === 0) {
+          ctx.selectionRange = { anchor: null, focus: null };
+          ctx.selectionRanges = [];
+          return;
+        }
+        const rowCount = ctx.internalData.length;
+        const colCount = ctx.allColumns.length;
+        if (rowCount === 0 || colCount === 0) return;
+        // Clamp to the visible grid bounds so callers can pass open-ended
+        // values like `[0, 0, Infinity, Infinity]` to mean "select all".
+        const toRange = ([r1, c1, r2, c2]: readonly [number, number, number, number]) => ({
+          anchor: {
+            rowIndex: Math.max(0, Math.min(rowCount - 1, Math.min(r1, r2))),
+            colIndex: Math.max(0, Math.min(colCount - 1, Math.min(c1, c2))),
+          },
+          focus: {
+            rowIndex: Math.max(0, Math.min(rowCount - 1, Math.max(r1, r2))),
+            colIndex: Math.max(0, Math.min(colCount - 1, Math.max(c1, c2))),
+          },
+        });
+        const built = ranges.map(toRange);
+        // Last range is the active one; the rest are committed extras.
+        ctx.selectionRanges = built.slice(0, -1);
+        const active = built[built.length - 1]!;
+        ctx.selectionRange = active;
+        // Move the active cell to the last range's top-left so keyboard
+        // navigation continues from there.
+        ctx.setActiveCell(active.anchor.rowIndex, active.anchor.colIndex);
+      },
+      getSelected() {
+        return ctx
+          .getSelectionRects()
+          .map((r: { minRow: number; minCol: number; maxRow: number; maxCol: number }) =>
+            [r.minRow, r.minCol, r.maxRow, r.maxCol] as [number, number, number, number],
+          );
+      },
+      openChart() {
+        ctx.chartPanelOpen = true;
+      },
+      closeChart() {
+        ctx.chartPanelOpen = false;
+      },
+      getChartSpec() {
+        return ctx.chartSpec;
+      },
+      chartRange(ranges) {
+        if (ranges && ranges.length) this.selectCells(ranges);
+        ctx.chartPanelOpen = true;
+      },
+      configureChart(config) {
+        if (ctx.chartingEnabled) ctx.applyChartConfig(config);
+      },
+      setChartAiHandler(handler) {
+        ctx.chartAiHandler = handler ?? null;
+      },
+      addRow(row, position = "bottom") {
+        this.addRows([row], position);
+      },
+      addRows(rows, position = "bottom") {
+        const next = ctx.internalData.slice() as Array<TData>;
+        if (position === "top") next.unshift(...rows);
+        else if (position === "bottom") next.push(...rows);
+        else if (typeof position === "number")
+          next.splice(Math.max(0, Math.min(position, next.length)), 0, ...rows);
+        ctx.internalData = next;
+      },
+      removeRow(rowIndex) {
+        this.removeRows([rowIndex]);
+      },
+      removeRows(rowIndices) {
+        const drop = new Set(rowIndices);
+        ctx.internalData = ctx.internalData.filter((_: any, i: any) => !drop.has(i));
+      },
+      applyTransaction(tx) {
+        const getId = ctx.props.getRowId;
+        let next = ctx.internalData.slice() as Array<TData>;
+        let added = 0;
+        let updated = 0;
+        let removed = 0;
+
+        if (tx.remove?.length) {
+          const removeIds = new Set<string>();
+          const removeRefs = new Set<TData>();
+          for (const r of tx.remove) {
+            if (typeof r === "string") removeIds.add(r);
+            else removeRefs.add(r as TData);
+          }
+          next = next.filter((row, i) => {
+            const hit =
+              removeRefs.has(row) ||
+              (getId ? removeIds.has(getId(row, i)) : false);
+            if (hit) removed += 1;
+            return !hit;
+          });
+        }
+
+        if (tx.update?.length && getId) {
+          const byId = new Map<string, TData>();
+          for (const u of tx.update) byId.set(getId(u, 0), u);
+          next = next.map((row, i) => {
+            const u = byId.get(getId(row, i));
+            if (u) {
+              updated += 1;
+              return u;
+            }
+            return row;
+          });
+        }
+
+        if (tx.add?.length) {
+          next.push(...(tx.add as Array<TData>));
+          added += tx.add.length;
+        }
+
+        ctx.internalData = next;
+        return { added, updated, removed };
+      },
+      addColumn(column, position = "right") {
+        this.addColumns([column], position);
+      },
+      addColumns(columns, position = "right") {
+        const next = ctx.internalColumns.slice();
+        if (position === "left") next.unshift(...columns);
+        else if (position === "right") next.push(...columns);
+        else if (typeof position === "number")
+          next.splice(
+            Math.max(0, Math.min(position, next.length)),
+            0,
+            ...columns,
+          );
+        ctx.internalColumns = next;
+      },
+      removeColumn(columnId) {
+        ctx.internalColumns = ctx.internalColumns.filter(
+          (def: any) => !columnDefMatchesId(def, columnId),
+        );
+      },
+      setColumnVisible(columnId, visible) {
+        if (visible) {
+          const next = { ...ctx.hiddenColumns };
+          delete next[columnId];
+          ctx.hiddenColumns = next;
+        } else {
+          ctx.hiddenColumns = { ...ctx.hiddenColumns, [columnId]: true };
+        }
+      },
+      isColumnVisible(columnId) {
+        return !ctx.hiddenColumns[columnId];
+      },
+      setSort(columnId, direction) {
+        // Honour the column's `sortable` opt-out. Asking the engine
+        // whether the column can sort folds in both the feature toggle
+        // AND the per-column flag.
+        const col = ctx.allColumns.find((c: any) => c.id === columnId);
+        if (col && !col.getCanSort?.()) return;
+        const clauses = direction
+          ? [{ id: columnId, desc: direction === "desc" }]
+          : (ctx.grid.getState().sorting ?? []).filter(
+              (entry: { id: string }) => entry.id !== columnId,
+            );
+        ctx.grid.store.setState((prev: any) => ({ ...prev, sorting: clauses }));
+      },
+      clearSort() {
+        ctx.grid.store.setState((prev: any) => ({ ...prev, sorting: [] }));
+      },
+      setGroupBy(columnIds) {
+        ctx.grid.setGrouping([...columnIds]);
+      },
+      setOption(key, value) {
+        // Runtime prop override. Writes into the controller's `optionOverrides`
+        // store, which the effective-props proxy merges over the incoming prop, so
+        // the grid re-renders exactly as if the parent had changed that prop.
+        // `undefined` clears the override (falls back to the prop). Reassign the
+        // whole object for reliable reactivity; `untrack` per the `setFilter` note.
+        untrack(() => {
+          const next: Record<string, unknown> = { ...ctx.optionOverrides };
+          if (value === undefined) delete next[key as string];
+          else next[key as string] = value;
+          ctx.optionOverrides = next;
+        });
+      },
+      getOption(key) {
+        // The effective value: the override if set, otherwise the incoming prop.
+        return (ctx.props as Record<string, unknown>)[key as string] as never;
+      },
+      resetOptions() {
+        untrack(() => {
+          ctx.optionOverrides = {};
+        });
+      },
+      setFilter(columnId, filter) {
+        // `untrack`: these imperative mutators read the same filter state they
+        // write (read-modify-write on `filterMenuValues`). When a consumer
+        // calls them from inside a reactive `$effect`, that internal read would
+        // otherwise be captured as a dependency of the caller's effect, and the
+        // write would re-dirty it - an infinite update loop. Untracking the
+        // body keeps the API safe to drive from an effect.
+        untrack(() => {
+          // Honour the column's `filterable` opt-out. Same approach as
+          // `setSort` - `getCanFilter()` already combines the feature flag
+          // and the per-column field.
+          const col = ctx.allColumns.find((c: any) => c.id === columnId);
+          if (col && !col.getCanFilter?.()) return;
+          if (!filter) {
+            this.clearFilter(columnId);
+            return;
+          }
+          ctx.filterMenuValues = {
+            ...ctx.filterMenuValues,
+            [columnId]: {
+              operator: filter.operator,
+              value: filter.value ?? "",
+              ...(filter.operator === "between"
+                ? { valueTo: filter.valueTo ?? "" }
+                : {}),
+              // Optional second condition + join (multi-condition filtering).
+              ...(filter.operator2
+                ? {
+                    operator2: filter.operator2,
+                    value2: filter.value2 ?? "",
+                    join: filter.join ?? "AND",
+                    ...(filter.operator2 === "between"
+                      ? { valueTo2: filter.valueTo2 ?? "" }
+                      : {}),
+                  }
+                : {}),
+            },
+          };
+        });
+      },
+      setFacetFilter(columnId, values) {
+        // See `setFilter` for why the read-modify-write is untracked.
+        untrack(() => {
+          // Empty array OR null both mean "clear this column's facet" -
+          // mirrors how the column menu treats unchecking the last value.
+          if (!values || values.length === 0) {
+            if (ctx.valueFilters[columnId]) {
+              const next = { ...ctx.valueFilters };
+              delete next[columnId];
+              ctx.valueFilters = next;
+            }
+            return;
+          }
+          ctx.valueFilters = {
+            ...ctx.valueFilters,
+            [columnId]: new Set(values),
+          };
+        });
+      },
+      clearFilter(columnId) {
+        ctx.clearColumnFilter(columnId);
+      },
+      refreshEditorOptions(columnId) {
+        // Async `editorOptions` are cached per column (or per column+row for a
+        // per-row source) so opening an editor twice does not refetch. This
+        // drops those entries, so the next render re-runs the source - use it
+        // when the underlying list changed server-side.
+        if (columnId == null) {
+          ctx.asyncEditorOptions = {};
+          return;
+        }
+        const next = { ...ctx.asyncEditorOptions };
+        for (const key of Object.keys(next)) {
+          if (key === columnId || key.startsWith(`${columnId}::`)) delete next[key];
+        }
+        ctx.asyncEditorOptions = next;
+      },
+      clearAllFilters() {
+        // See `setFilter` for why the read-modify-write is untracked.
+        untrack(() => {
+          // Wipe every filter surface in one go: column-menu, filter-row, set
+          // filters, the global search box, and the advanced filter. This
+          // promises "every filter surface", so leaving the advanced one set
+          // would strand rows nobody can see a cause for.
+          ctx.filterMenuValues = {};
+          ctx.filterRowValues = {};
+          ctx.valueFilters = {};
+          if (ctx.globalFilter !== "") ctx.globalFilter = "";
+          if (ctx.advancedFilter !== null) ctx.advancedFilter = null;
+        });
+      },
+      setAdvancedFilter(expr) {
+        // See `setFilter` for why the write is untracked.
+        untrack(() => {
+          ctx.advancedFilter = expr ?? null;
+        });
+      },
+      getAdvancedFilter() {
+        return ctx.advancedFilter ?? null;
+      },
+      clearAdvancedFilter() {
+        untrack(() => {
+          ctx.advancedFilter = null;
+        });
+      },
+      isAdvancedFilterActive() {
+        return ctx.advancedFilter != null && hasAdvancedFilterEngine();
+      },
+      getFilters() {
+        // Return a defensive copy so callers can't mutate internal state.
+        const out: Record<
+          string,
+          { operator: FilterOperator; value: string; valueTo?: string }
+        > = {};
+        for (const [columnId, filter] of Object.entries(ctx.filterMenuValues as Record<string, { operator: FilterOperator; value: string; valueTo?: string }>)) {
+          out[columnId] = {
+            operator: filter.operator,
+            value: filter.value,
+            ...(filter.operator === "between" && filter.valueTo
+              ? { valueTo: filter.valueTo }
+              : {}),
+          };
+        }
+        return out;
+      },
+      getDisplayedRows() {
+        // `allRows` is the final, post-filter, post-sort, post-group,
+        // post-pagination list - exactly what the body renders. Skip group
+        // header rows (they wrap an aggregate, not a TData row).
+        //
+        // `isGroupRow` rather than a `subRows.length` test: a TREE parent also
+        // has subRows, but it is a real data row that renders its own cells, so
+        // dropping it here silently truncated every tree read - including the
+        // enterprise export, whose default row source is this method.
+        const out: TData[] = [];
+        for (const row of ctx.allRows) {
+          if (isGroupRow(row)) continue;
+          out.push(row.original as TData);
+        }
+        return out;
+      },
+      getData() {
+        return ctx.internalData;
+      },
+      getColumns() {
+        // Snapshot every column with its human-readable label and
+        // visibility flag. Used by external code (exporters, column
+        // pickers) so they don't have to re-walk the columnDef tree.
+        // Hidden columns ARE included (with `visible: false`) so a column
+        // picker can re-enable them - callers that only want what's
+        // rendered filter by `.visible` (e.g. the exporter does).
+        const describe = (c: any, visible: boolean) => ({
+          id: c.id,
+          field: (c.columnDef as { field?: string }).field,
+          header:
+            typeof c.columnDef.header === "string"
+              ? c.columnDef.header
+              : c.id,
+          visible,
+          // Surface the format + alignment so exporters can reproduce the
+          // on-screen display value (currency symbol, date pattern, etc.)
+          // instead of dumping raw values. `getColumnAlign` applies the same
+          // editorType-based default the body uses.
+          format: c.columnDef.format,
+          align: getColumnAlign(c),
+          // The column's declared value type. Lets a filter or expression UI
+          // offer the right operators (numeric ranges vs text matching) without
+          // re-walking the columnDef tree.
+          editorType: (c.columnDef as { editorType?: string }).editorType,
+        });
+        // Visible columns first, in their current visual order...
+        const out = ctx.allColumns.map((c: any) => describe(c, true));
+        // ...then any column hidden via `visible: false` / setColumnVisible.
+        // Those aren't in `allColumns` (that list is visible-only), so pull
+        // them straight from the engine's leaf set.
+        const visibleIds = new Set(out.map((c: { id: string }) => c.id));
+        for (const c of ctx.grid.getAllColumns() as any[]) {
+          if (!visibleIds.has(c.id)) out.push(describe(c, false));
+        }
+        return out;
+      },
+      // ---- Free data export (CSV / TSV / JSON + clipboard) -----------------
+      async exportCsv(options: GridExportOptions = {}) {
+        const { serializeDelimited, downloadTextFile } = await import("./export-format");
+        const { records, fields } = await projectForExport(
+          options.rows ?? "displayed",
+          options.columns,
+          options.rawValues,
+        );
+        const text = await serializeDelimited(records, fields, {
+          csv: { delimiter: ",", bom: options.bom ?? true },
+          signal: options.signal,
+          onProgress: options.onProgress,
+        });
+        if (options.download !== false)
+          downloadTextFile(text, `${options.filename ?? "grid"}.csv`, "text/csv;charset=utf-8");
+        return text;
+      },
+      async exportTsv(options: GridExportOptions = {}) {
+        const { serializeDelimited, downloadTextFile } = await import("./export-format");
+        const { records, fields } = await projectForExport(
+          options.rows ?? "displayed",
+          options.columns,
+          options.rawValues,
+        );
+        const text = await serializeDelimited(records, fields, {
+          csv: { delimiter: "\t", bom: options.bom ?? true },
+          signal: options.signal,
+          onProgress: options.onProgress,
+        });
+        if (options.download !== false)
+          downloadTextFile(text, `${options.filename ?? "grid"}.tsv`, "text/tab-separated-values;charset=utf-8");
+        return text;
+      },
+      async exportJson(options: GridExportOptions = {}) {
+        const { serializeJson, downloadTextFile } = await import("./export-format");
+        const { records, fields } = await projectForExport(
+          options.rows ?? "displayed",
+          options.columns,
+          options.rawValues,
+        );
+        const text = await serializeJson(records, fields, {
+          signal: options.signal,
+          onProgress: options.onProgress,
+        });
+        if (options.download !== false)
+          downloadTextFile(text, `${options.filename ?? "grid"}.json`, "application/json");
+        return text;
+      },
+      async copyToClipboard(options: GridClipboardOptions = {}) {
+        const { serializeDelimited, serializeMarkdown, copyTextToClipboard } = await import("./export-format");
+        const { records, fields, align } = await projectForExport(
+          options.rows ?? "displayed",
+          options.columns,
+          options.rawValues,
+        );
+        const format = options.format ?? "tsv";
+        const text =
+          format === "markdown"
+            ? await serializeMarkdown(records, fields, { align })
+            : await serializeDelimited(records, fields, {
+                csv: { delimiter: format === "csv" ? "," : "\t", bom: false },
+              });
+        await copyTextToClipboard(text);
+        return text;
+      },
+      clearRowSelection() {
+        // Wipe the internal selection map AND emit the change so any
+        // consumer holding a derived `selectedRows` resets too.
+        ctx.grid.setRowSelection(() => ({}));
+        ctx.props.onRowSelectionChange?.({}, []);
+      },
+      setColumnWidth(columnId: string, width: number) {
+        const clamped = Math.max(ctx.MIN_COLUMN_WIDTH, Math.floor(width));
+        ctx.columnWidths = { ...ctx.columnWidths, [columnId]: clamped };
+      },
+      getColumnWidths() {
+        // Resolve every column's effective width by consulting both the
+        // resize overrides (`columnWidths`) AND the columnDef defaults,
+        // so the snapshot is round-trippable through setColumnWidth.
+        const out: Record<string, number> = {};
+        for (const c of ctx.allColumns) out[c.id] = ctx.getColumnWidth(c.id);
+        return out;
+      },
+      autosizeColumn(columnId: string) {
+        ctx.autosizeColumn(columnId);
+      },
+      autosizeAllColumns() {
+        ctx.autosizeAllColumns();
+      },
+      setColumnPinning(pinning) {
+        // Defensive copy + dedupe so callers can't mutate our state.
+        const left = Array.from(new Set(pinning.left ?? []));
+        const right = Array.from(new Set(pinning.right ?? []));
+        ctx.columnPinning = { left, right };
+      },
+      getColumnPinning() {
+        return {
+          left: ctx.columnPinning.left.slice(),
+          right: ctx.columnPinning.right.slice(),
+        };
+      },
+      // ---- Column reorder
+      setColumnOrder(order) {
+        ctx.setColumnOrderInternal(order);
+      },
+      getColumnOrder() {
+        return ctx.getCurrentColumnOrder();
+      },
+      setRowExpanded(id, expanded) {
+        ctx.grid.setExpanded((prev: any) => ({ ...prev, [id]: !!expanded }));
+      },
+      expandAllGroups() {
+        // Walk the current grouped row model and flip every group node on.
+        const next: Record<string, boolean> = {};
+        const walk = (rows: ReadonlyArray<{ id: string; getCanExpand?: () => boolean; subRows?: ReadonlyArray<unknown> }>) => {
+          for (const row of rows) {
+            if (row.getCanExpand?.()) next[row.id] = true;
+            const sub = row.subRows as ReadonlyArray<{ id: string; getCanExpand?: () => boolean; subRows?: ReadonlyArray<unknown> }> | undefined;
+            if (sub && sub.length > 0) walk(sub);
+          }
+        };
+        walk(ctx.grid.getRowModel().rows as unknown as ReadonlyArray<{ id: string; getCanExpand?: () => boolean; subRows?: ReadonlyArray<unknown> }>);
+        ctx.grid.setExpanded(() => next);
+      },
+      collapseAllGroups() {
+        ctx.grid.setExpanded(() => ({}));
+      },
+      // ---- Undo / redo (history + pointer)
+      undo() {
+        if (ctx.historyPtr < 0) return false
+        const step = ctx.history[ctx.historyPtr]
+        if (!step) return false
+        ctx.applyHistoryStep(step, 'undo')
+        ctx.historyPtr -= 1
+        ctx.historyVersion += 1
+        return true
+      },
+      redo() {
+        if (ctx.historyPtr >= ctx.history.length - 1) return false
+        const step = ctx.history[ctx.historyPtr + 1]
+        if (!step) return false
+        ctx.applyHistoryStep(step, 'redo')
+        ctx.historyPtr += 1
+        ctx.historyVersion += 1
+        return true
+      },
+      canUndo() { void ctx.historyVersion; return ctx.historyPtr >= 0 },
+      canRedo() { void ctx.historyVersion; return ctx.historyPtr < ctx.history.length - 1 },
+      clearHistory() { ctx.history = []; ctx.historyPtr = -1; ctx.historyVersion += 1 },
+      // ---- Find
+      openFind()  { ctx.findOpen = true },
+      closeFind() { ctx.findOpen = false; ctx.findQuery = '' },
+      setFindQuery(q: string) { ctx.findQuery = q; ctx.findHitIndex = 0 },
+      getFindHits() { return ctx.findHits.slice() },
+      // ---- Row selection (read + write)
+      getSelectedRows() {
+        const out: TData[] = [];
+        for (const row of ctx.allRows) {
+          if (isGroupRow(row)) continue;
+          if (ctx.rowSelectionState[row.id]) out.push(row.original as TData);
+        }
+        return out;
+      },
+      getSelectedRowIds() {
+        const out: string[] = [];
+        for (const row of ctx.allRows) {
+          if (!isGroupRow(row) && ctx.rowSelectionState[row.id]) out.push(row.id);
+        }
+        return out;
+      },
+      selectRows(ids, additive = false) {
+        const set = new Set(ids);
+        ctx.grid.setRowSelection((prev: any) => {
+          const next: Record<string, boolean> = additive ? { ...prev } : {};
+          for (const id of set) next[id] = true;
+          return next;
+        });
+      },
+      selectAllRows() {
+        const next: Record<string, boolean> = {};
+        for (const row of ctx.allRows) if (!isGroupRow(row)) next[row.id] = true;
+        ctx.grid.setRowSelection(() => next);
+      },
+      toggleRowSelected(id) {
+        ctx.toggleRowSelectionById(id);
+      },
+      // ---- Pagination
+      getPageInfo() {
+        const { pageIndex, pageSize } = ctx.paginationState;
+        const total = ctx.allRowsBeforePagination.length;
+        const pageCount = Math.max(1, Math.ceil(total / Math.max(1, pageSize)));
+        return { pageIndex, pageSize, pageCount, total };
+      },
+      setPage(pageIndex) {
+        const total = ctx.allRowsBeforePagination.length;
+        const pageCount = Math.max(
+          1,
+          Math.ceil(total / Math.max(1, ctx.paginationState.pageSize)),
+        );
+        ctx.goToPage(Math.max(0, Math.min(pageIndex, pageCount - 1)));
+      },
+      nextPage() {
+        this.setPage(ctx.paginationState.pageIndex + 1);
+      },
+      prevPage() {
+        this.setPage(ctx.paginationState.pageIndex - 1);
+      },
+      firstPage() {
+        this.setPage(0);
+      },
+      lastPage() {
+        const total = ctx.allRowsBeforePagination.length;
+        const pageCount = Math.max(
+          1,
+          Math.ceil(total / Math.max(1, ctx.paginationState.pageSize)),
+        );
+        this.setPage(pageCount - 1);
+      },
+      setPageSize(size) {
+        // Calls the component-level helper (lexical scope), not this method.
+        ctx.setPageSize(Math.max(1, Math.floor(size)));
+      },
+      // ---- Navigation / scrolling
+      scrollToRow(rowIndex) {
+        if (!ctx.scrollContainer) return;
+        const maxIndex = Math.max(0, ctx.allRows.length - 1);
+        const clamped = Math.max(0, Math.min(rowIndex, maxIndex));
+        // Logical offset from the virtualizer (honors uniform OR per-row
+        // sizing), then mapped into the capped DOM scroll space so it lands
+        // correctly on huge grids where the DOM height is scaled down.
+        const logical = ctx.virtualizer.getOffsetForIndex(clamped);
+        ctx.scrollContainer.scrollTop = ctx.logicalToDomRowOffset(logical);
+        ctx.scheduleScrollSync(
+          ctx.scrollContainer.scrollTop,
+          ctx.scrollContainer.scrollLeft,
+        );
+      },
+      getActiveCell() {
+        const a = ctx.activeCell;
+        if (!a || a.rowIndex < 0 || a.colIndex < 0) return null;
+        const col = ctx.allColumns[a.colIndex];
+        return {
+          rowIndex: a.rowIndex,
+          colIndex: a.colIndex,
+          columnId: col?.id ?? "",
+        };
+      },
+      setActiveCell(rowIndex, colIndex) {
+        const r = Math.max(0, Math.min(rowIndex, Math.max(0, ctx.allRows.length - 1)));
+        const c = Math.max(
+          0,
+          Math.min(colIndex, Math.max(0, ctx.allColumns.length - 1)),
+        );
+        // Calls the component-level helper (lexical scope), not this method.
+        ctx.setActiveCell(r, c);
+      },
+      // ---- View state (save / restore)
+      getState() {
+        return {
+          sorting: (ctx.grid.getState().sorting ?? []).map(
+            (s: { id: string; desc: boolean }) => ({ id: s.id, desc: s.desc }),
+          ),
+          grouping: [...(ctx.grid.getState().grouping ?? [])],
+          pagination: {
+            pageIndex: ctx.paginationState.pageIndex,
+            pageSize: ctx.paginationState.pageSize,
+          },
+          columnWidths: this.getColumnWidths(),
+          columnPinning: this.getColumnPinning(),
+          columnOrder: ctx.getCurrentColumnOrder(),
+          hiddenColumns: Object.keys(ctx.hiddenColumns).filter(
+            (k) => ctx.hiddenColumns[k],
+          ),
+          globalFilter: ctx.globalFilter,
+          columnFilters: this.getFilters(),
+          facetFilters: Object.fromEntries(
+            Object.entries(ctx.valueFilters).map(([k, set]: [string, any]) => [
+              k,
+              Array.from(set),
+            ]),
+          ),
+          // Emitted only when set. `attachAutoSavedView` diffs
+          // JSON.stringify(getState()) on a timer, so adding an always-present
+          // key would change every existing snapshot and force one spurious
+          // save in every app on upgrade.
+          ...(ctx.advancedFilter ? { advancedFilter: ctx.advancedFilter } : {}),
+          ...(ctx.chartingEnabled
+            ? {
+                chart: {
+                  open: ctx.chartPanelOpen,
+                  type: ctx.chartType,
+                  dimension: ctx.chartDimensionId,
+                  series: ctx.chartSeriesId,
+                  measure: ctx.chartMeasureId,
+                  reduce: ctx.chartReduce,
+                  stacked: ctx.chartStacked,
+                },
+                charts: ctx.getChartsState(),
+                chartActive: ctx.activeChartIndex,
+              }
+            : {}),
+        };
+      },
+      setState(state) {
+        if (state.sorting) {
+          const sorting = state.sorting.map((s) => ({ id: s.id, desc: s.desc }));
+          ctx.grid.store.setState((prev: any) => ({ ...prev, sorting }));
+        }
+        if (state.grouping) {
+          // Drop grouping by columns that no longer exist (#53) - otherwise a
+          // saved view collapses every row into a group named 'undefined'.
+          const existing = new Set((ctx.grid.getAllColumns() as any[]).map((c) => c.id));
+          ctx.grid.setGrouping(state.grouping.filter((id: string) => existing.has(id)));
+        }
+        if (state.pagination) {
+          const p = state.pagination;
+          ctx.grid.setPagination((prev: any) => ({ ...prev, ...p }));
+        }
+        if (state.columnWidths) ctx.columnWidths = { ...state.columnWidths };
+        if (state.columnPinning)
+          ctx.columnPinning = {
+            left: [...(state.columnPinning.left ?? [])],
+            right: [...(state.columnPinning.right ?? [])],
+          };
+        if (state.columnOrder) ctx.setColumnOrderInternal(state.columnOrder);
+        if (state.hiddenColumns) {
+          // Seed from columns declared `visible: false` so a partial/empty saved
+          // state never un-hides an app-declared-hidden column (#54); then layer
+          // the saved user-driven hides on top.
+          const next: Record<string, boolean> = { ...ctx.declaredHiddenColumns };
+          for (const id of state.hiddenColumns) next[id] = true;
+          ctx.hiddenColumns = next;
+        }
+        if (state.globalFilter !== undefined) ctx.globalFilter = state.globalFilter;
+        if (state.columnFilters)
+          ctx.filterMenuValues = { ...state.columnFilters };
+        if (state.facetFilters) {
+          const next: Record<string, Set<string>> = {};
+          for (const [k, arr] of Object.entries(state.facetFilters))
+            next[k] = new Set(arr);
+          ctx.valueFilters = next;
+        }
+        // `in` rather than a truthiness check, so an explicit null clears while
+        // an absent key leaves the current filter alone (the documented
+        // "only the keys present are applied" contract).
+        if ("advancedFilter" in state) {
+          ctx.advancedFilter = state.advancedFilter ?? null;
+        }
+        if ((state.chart || state.charts) && ctx.chartingEnabled) {
+          if (Array.isArray(state.charts) && state.charts.length) {
+            ctx.applyChartsState(state.charts, state.chartActive);
+          }
+          if (state.chart) {
+            const c = state.chart;
+            ctx.chartPanelOpen = c.open;
+            ctx.chartType = c.type;
+            ctx.chartDimensionId = c.dimension;
+            ctx.chartSeriesId = c.series;
+            ctx.chartMeasureId = c.measure;
+            ctx.chartReduce = c.reduce;
+            ctx.chartStacked = c.stacked;
+          }
+        }
+      },
+      refresh() {
+        ctx.grid.store.setState((prev: any) => ({ ...prev }));
+      },
+    };
+  }
+
+  return {
+    buildApi,
+  };
+}