@svgrid/grid 3.0.2 → 3.0.4

package/src/SvGrid.controller.svelte.ts

@@ -25,7 +25,13 @@ import {
     type TableFeatures,
     type ChartType,
     type ChartSpec,
+    type ChartReducer,
+    type ChartTimeBucket,
     type ChartValueFormat,
+    type ChartZoomWindow,
+    type ChartPanelIndicator,
+    type ChartFormatState,
+    type OhlcColumns,
   } from "./index";
 import {
   createRowScrollScaling,
@@ -53,6 +59,8 @@ import {
     rawToNumber,
   } from "./SvGrid.helpers";
 import { createFeatures } from "./features";
+import { pushHistory, type HistoryStep as SharedHistoryStep } from "./history";
+import { buildMergeIndex } from "./merges";
 import {
     createScrollSync,
   } from "./scroll-sync";
@@ -373,7 +381,12 @@ export function createSvGridController<
   let pendingScrollTop = 0;
   let pendingScrollLeft = 0;
   let scrollSyncRaf: number | null = null;
-  let selectionRange = $state<SelectionRange>({ anchor: null, focus: null });
+  // `$state.raw`: every writer replaces the whole object, and every rendered
+  // cell's selection derived reads it. Under a deep proxy each of those ~300
+  // deriveds tracked the nested anchor/focus row/col signals separately (six
+  // dependencies per cell to mark and re-check on every arrow key) where one
+  // will do.
+  let selectionRange = $state.raw<SelectionRange>({ 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.
@@ -418,20 +431,21 @@ export function createSvGridController<
   // 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<{ rowId: string; draft: Record<string, unknown> } | null>(null);
-  let editedCellValues = $state<Record<string, unknown>>({});
+  // `$state.raw`, not `$state`: every writer replaces the whole object, and
+  // the render path asks `key in editedCellValues` once per rendered cell. On
+  // a deep proxy that `in` check, run inside an effect, creates and keeps a
+  // per-key signal for every cell that ever scrolls into view - a leak that
+  // grows with rows x columns and a Map lookup per cell per render.
+  let editedCellValues = $state.raw<Record<string, unknown>>({});
 
   // ---- Undo / redo (history + pointer model) ---------------------------
   // VSCode-style: one ordered history array, plus a pointer to the index
   // of the NEXT undo step. Avoids the dual-stack edge cases where
   // multiple undo-redo cycles can lose entries.
-  // exported for the editing slice (undo/redo)
-  type HistoryStep = {
-    rowId: string
-    columnId: string
-    field: string
-    before: unknown
-    after: unknown
-  }
+  // exported for the editing slice (undo/redo). The shape lives in history.ts
+  // so the controller, editing.ts and clipboard.ts cannot drift apart - they
+  // previously declared it twice and open-coded the push in three places.
+  type HistoryStep = SharedHistoryStep
   const UNDO_LIMIT = 200
   let history    = $state<HistoryStep[]>([])
   /** Index in `history` of the LAST applied step. -1 means "nothing applied".
@@ -441,6 +455,11 @@ export function createSvGridController<
   /** Bumps on every undo / redo / record so $derived consumers can
    *  observe via the api without subscribing to history directly. */
   let historyVersion = $state(0)
+  /** Set while a `runHistoryGroup` call is on the stack, so every step pushed
+   *  inside one action shares a group id and undoes together. Deliberately not
+   *  $state: it is written and read synchronously inside a single call and
+   *  nothing renders from it. */
+  let historyGroupId: string | undefined = undefined
 
   // ---- Hover tooltip (custom popover, not native title=) ---------------
   // Triggered by per-column `tooltip` field OR per-cell `notes` prop.
@@ -479,6 +498,24 @@ export function createSvGridController<
   let editorSelectAll = true;
   /** Per-column width overrides set by the resize handles. */
   let columnWidths = $state<Record<string, number>>({});
+  /**
+   * Columns folded to nothing, the way a sheet hides a column: the column
+   * keeps its index, its cells and its width for later, and takes no room.
+   * Distinct from `hiddenColumns`, which takes a column out of the model
+   * and shifts every index after it; a spreadsheet's formulas and formats
+   * are keyed by index and could not follow that.
+   */
+  let collapsedColumns = $state<Record<string, boolean>>({});
+  function setColumnCollapsed(columnId: string, collapsed: boolean): void {
+    if (!!collapsedColumns[columnId] === collapsed) return;
+    if (collapsed) {
+      collapsedColumns = { ...collapsedColumns, [columnId]: true };
+    } else {
+      const next = { ...collapsedColumns };
+      delete next[columnId];
+      collapsedColumns = next;
+    }
+  }
   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
@@ -570,26 +607,54 @@ export function createSvGridController<
     const hb = column.columnDef?.hideBelow;
     return hb != null && viewportWidth > 0 && viewportWidth < hb;
   }
-  const scrollMetrics = $derived.by(function scrollMetrics_d() {
+  /**
+   * Live scroll geometry of the scroll container (feeds the custom
+   * scrollbars and `hasVerticalOverflow`).
+   *
+   * Measured from a plain `$effect`, NOT inside a `$derived`, on purpose.
+   * `scrollTop` / `scrollHeight` / `scrollWidth` reads force a synchronous
+   * layout whenever the tree is dirty. As a derived this was pulled by the
+   * shell's `class:sv-grid-has-vscroll` at the very start of every scroll
+   * flush - before the recycled rows had been rewritten - so it forced a
+   * full table layout that the row writes then invalidated again, and the
+   * browser laid the table out a second time before painting. Two table
+   * layouts per arrow key on a large grid. An effect runs after the flush
+   * has written the DOM, so the reads below land on a tree the browser has
+   * to lay out anyway, and the pre-paint pass is incremental.
+   *
+   * The version reads keep the same triggers the derived had: a scroll
+   * tick, a shell resize, and either virtualizer's window/size change (data
+   * load, row / column count change) - without those the scrollbar kept a
+   * stale `content-size` ≈ 0, its hidden-check tripped, it set
+   * `pointer-events: none`, and the user could not drag it.
+   */
+  let scrollMetrics = $state.raw({
+    scrollTop: 0,
+    scrollLeft: 0,
+    scrollHeight: 0,
+    scrollWidth: 0,
+  });
+  $effect(function scrollMetrics_e() {
     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,
-    };
+    const el = scrollContainer;
+    if (!el) return;
+    const scrollTop = el.scrollTop;
+    const scrollLeft = el.scrollLeft;
+    const scrollHeight = el.scrollHeight;
+    const scrollWidth = el.scrollWidth;
+    const prev = untrack(() => scrollMetrics);
+    if (
+      prev.scrollTop === scrollTop &&
+      prev.scrollLeft === scrollLeft &&
+      prev.scrollHeight === scrollHeight &&
+      prev.scrollWidth === scrollWidth
+    ) {
+      return;
+    }
+    scrollMetrics = { scrollTop, scrollLeft, scrollHeight, scrollWidth };
   });
   /** Vertical overflow from the virtualizer's authoritative total size,
    *  NOT from `scrollMetrics.scrollHeight` alone. Reading DOM dimensions
@@ -1697,8 +1762,14 @@ export function createSvGridController<
   const paginationPageSize = $derived(
     externalPaginationEnabled ? (props.pageSize ?? 10) : paginationState.pageSize,
   );
+  // Tracks `dataStateVersion`, which the store subscription bumps when the
+  // rowSelection slice (among others) changes - NOT the catch-all
+  // `gridStateVersion`, which also bumps on every active-cell move. Every
+  // rendered row and cell reads this (`sv-grid-row-selected`, `aria-selected`),
+  // so on the catch-all each arrow key re-marked and re-checked ~400 effects
+  // to find the same object.
   const rowSelectionState = $derived.by(function rowSelectionState_d() {
-    gridStateVersion;
+    dataStateVersion;
     return grid.getState().rowSelection ?? {};
   });
 
@@ -2017,6 +2088,7 @@ export function createSvGridController<
   let chartAiHandler = $state<
     ((prompt: string) => Promise<Record<string, unknown> | null>) | null
   >(null);
+  let chartExplainHandler = $state<(() => Promise<{ summary: string; insights: string[] } | null>) | null>(null);
 
   // Multiple charts, each an independently-configured working set switched by a
   // tab strip. Pickers / spec read the ACTIVE chart.
@@ -2024,7 +2096,7 @@ export function createSvGridController<
     id: string;
     title: string;
     type: ChartType;
-    reduce: "sum" | "avg" | "count";
+    reduce: ChartReducer;
     dimensionId: string | null;
     measureId: string | null;
     seriesId: string | null | undefined;
@@ -2045,8 +2117,28 @@ export function createSvGridController<
     logScale: boolean | null;
     timeAxis: boolean | null;
     valueFormat: ChartValueFormat | null;
+    /** Calendar unit a date dimension is grouped by. Null = exact values. */
+    bucket: ChartTimeBucket | null;
+    /** Histogram bin count. Null = Sturges' rule. */
+    bins: number | null;
+    funnelShape: "trapezoid" | "pyramid" | "cone" | null;
+    candleStyle: "classic" | "hollow" | "heikin-ashi" | null;
+    /** The chart's zoom window (category index range), kept per tab. */
+    zoom: ChartZoomWindow | null;
+    /** Candlestick / OHLC: which columns hold the prices (column ids). Null
+     *  guesses from the column names. */
+    ohlc: { open: string | null; high: string | null; low: string | null; close: string | null; volume: string | null } | null;
+    /** Indicators: panes under the price (volume, rsi, macd, stochastic,
+     *  atr, obv) and overlays on it (sma, ema, bb, vwap). */
+    indicators: ChartPanelIndicator[];
+    /** The builder's Format tab: titles, axes, legend, per-series style. */
+    format: ChartFormatState | null;
+    /** An unlinked chart: the spec it was frozen with and when. */
+    frozen: { spec: ChartSpec; at: string } | null;
   };
   let chartSeq = 0;
+  const isZoomWindow = (v: unknown): v is ChartZoomWindow =>
+    !!v && typeof v === "object" && Number.isInteger((v as ChartZoomWindow).i0) && Number.isInteger((v as ChartZoomWindow).i1);
   const makeChart = (title: string): ChartTabState => ({
     id: `chart-${chartSeq++}`,
     title,
@@ -2067,10 +2159,49 @@ export function createSvGridController<
     logScale: null,
     timeAxis: null,
     valueFormat: null,
+    bucket: null,
+    bins: null,
+    funnelShape: null,
+    candleStyle: null,
+    zoom: null,
+    ohlc: null,
+    indicators: [],
+    format: null,
+    frozen: null,
   });
+  // The saved view (`GridState.charts[i]`) names four fields differently
+  // from the tab; everything else is the tab's own key.
+  const TAB_ALIASES: Record<string, string> = { dimensionId: "dimension", measureId: "measure", seriesId: "series", measure2Id: "measure2" };
+  /** A tab as the saved view carries it, without the runtime id. */
+  const tabToState = (c: ChartTabState): Record<string, unknown> => {
+    const out: Record<string, unknown> = {};
+    for (const k in c) if (k !== "id") out[TAB_ALIASES[k] ?? k] = k === "seriesId" ? (c.seriesId ?? null) : c[k as keyof ChartTabState];
+    return out;
+  };
+  /** A tab from a saved-view snapshot: a fresh tab with every known field
+   *  the snapshot carries, and the shape-checked ones dropped when malformed. */
+  const tabFromState = (c: Record<string, unknown>, i: number): ChartTabState => {
+    const t = makeChart(typeof c.title === "string" ? c.title : `Chart ${i + 1}`) as unknown as Record<string, unknown>;
+    for (const k in t) {
+      const v = c[TAB_ALIASES[k] ?? k];
+      if (k !== "id" && k !== "title" && v !== undefined) t[k] = v;
+    }
+    if (!isZoomWindow(t.zoom)) t.zoom = null;
+    if (!Array.isArray(t.indicators)) t.indicators = [];
+    if (typeof t.bins !== "number") t.bins = null;
+    if (!t.frozen || typeof t.frozen !== "object" || !(t.frozen as { spec?: unknown }).spec) t.frozen = null;
+    return t as unknown as ChartTabState;
+  };
   // svelte-ignore state_referenced_locally
   let charts = $state<ChartTabState[]>([makeChart("Chart 1")]);
   let activeChartIndex = $state(0);
+  /**
+   * Named chart configurations the user keeps: a tab's whole state under a
+   * name, applied to any tab later. Part of the saved view (`GridState.savedCharts`)
+   * only when there is one, so existing snapshots do not change.
+   */
+  type SavedChartEntry = { name: string; savedAt: string; tab: Record<string, unknown> };
+  let savedCharts = $state<SavedChartEntry[]>([]);
   const activeChart = $derived(
     (charts[Math.min(activeChartIndex, charts.length - 1)] ?? charts[0])!,
   );
@@ -2083,6 +2214,10 @@ export function createSvGridController<
   const chartDataLabels = $derived(activeChart.dataLabels);
   const chartLogScale = $derived(activeChart.logScale);
   const chartTimeAxis = $derived(activeChart.timeAxis);
+  const chartBucket = $derived(activeChart.bucket);
+  const chartBins = $derived(activeChart.bins);
+  const chartFunnelShape = $derived(activeChart.funnelShape);
+  const chartCandleStyle = $derived(activeChart.candleStyle);
   const chartValueFormat = $derived(activeChart.valueFormat);
 
   const asMeasureList = (m: string | string[] | undefined): string[] =>
@@ -2198,9 +2333,13 @@ export function createSvGridController<
     const col = allColumns.find((c) => c.id === effectiveChartMeasureId);
     const label = col ? columnLabel(col) : "";
     if (!label) return undefined;
-    return chartReduce === "count"
-      ? "Count"
-      : `${chartReduce === "avg" ? "Average" : "Sum"} of ${label}`;
+    const word: Record<string, string> = {
+      sum: "Sum", avg: "Average", min: "Min", max: "Max", median: "Median",
+      first: "First", last: "Last", countDistinct: "Distinct",
+    };
+    if (chartReduce === "count") return "Count";
+    const w = word[chartReduce] ?? (chartReduce.startsWith("p") ? `P${chartReduce.slice(1)}` : "Sum");
+    return `${w} of ${label}`;
   });
   /**
    * Does this column hold dates? Declared type first, then a probe of the
@@ -2223,6 +2362,41 @@ export function createSvGridController<
   const chartDimensionIsDate = $derived.by<boolean>(() =>
     columnIsDate(allColumns.find((c) => c.id === effectiveChartDimensionId)),
   );
+  // The chart derivation engine (rowsToChartSpec) is loaded lazily the first time
+  // charting is enabled, keeping chart.ts (~11 KB gzip) out of the base <SvGrid>
+  // bundle - it rides in the same lazy chunk as the chart panel. `chartSpec` stays
+  // null until it resolves, a tick after the panel itself starts loading (which it
+  // already does). The `getAggregate` server path uses the local bucketsToSpec and
+  // does not need the engine.
+  // The whole module, not just `rowsToChartSpec`: the panel can now reach
+  // every chart type, and the ones that do not read a categories-by-series
+  // grid (scatter, gauge, treemap, calendar, sankey) need their own builders
+  // from the same lazy chunk. Same `import()`, same boundary.
+  let chartEngine = $state<typeof import("./chart") | null>(null);
+  $effect(() => {
+    if (chartingEnabled && !chartEngine)
+      import("./chart").then((m) => (chartEngine = m));
+  });
+
+  const chartIsOhlc = $derived(chartType === "candlestick" || chartType === "ohlc");
+  /** The price columns: what the reader picked, else the engine's guess
+   *  from the column names (nothing until the engine chunk has loaded). */
+  const effectiveChartOhlc = $derived<OhlcColumns>(
+    chartEngine
+      ? chartEngine.guessOhlcColumns(chartableColumns.measures, activeChart.ohlc)
+      : { open: null, high: null, low: null, close: null, volume: null, ...activeChart.ohlc },
+  );
+  /** The date column a candlestick reads: the picked dimension when it is a
+   *  date, else the first date column. */
+  const effectiveChartOhlcDateId = $derived(
+    chartDimensionIsDate ? effectiveChartDimensionId : (chartableColumns.dates[0]?.id ?? null),
+  );
+  const chartIndicators = $derived(activeChart.indicators);
+  /** The panes under a price chart and the overlay on it, split by the engine. */
+  const chartIndicatorSplit = $derived(
+    chartIsOhlc && chartEngine ? chartEngine.splitPanelIndicators(chartIndicators) : { panes: [], overlay: null },
+  );
+  const chartIndicatorPanes = $derived(chartIndicatorSplit.panes);
   const chartRows = $derived.by<TData[]>(() => {
     const rects = getSelectionRects();
     const pushLeaf = (out: TData[], row: Row<TData> | undefined) => {
@@ -2272,52 +2446,6 @@ export function createSvGridController<
         if (seq === chartReqSeq) chartServerBuckets = [];
       });
   });
-  const bucketsToSpec = (
-    buckets: ReadonlyArray<{ category: string; series?: string; value: number }>,
-    type: ChartType,
-    hasSeries: boolean,
-  ): ChartSpec => {
-    const cats: string[] = [];
-    const catIdx = new Map<string, number>();
-    const ensureCat = (c: string) => {
-      let i = catIdx.get(c);
-      if (i === undefined) { i = cats.length; catIdx.set(c, i); cats.push(c); }
-      return i;
-    };
-    const seriesMap = new Map<string, number[]>();
-    for (const b of buckets) {
-      const ci = ensureCat(b.category);
-      const key = hasSeries ? (b.series ?? "") : "value";
-      let arr = seriesMap.get(key);
-      if (!arr) { arr = []; seriesMap.set(key, arr); }
-      arr[ci] = (arr[ci] ?? 0) + b.value;
-    }
-    return {
-      type,
-      categories: cats,
-      series: [...seriesMap.entries()].map(([label, values]) => ({
-        label,
-        values: cats.map((_, i) => values[i] ?? 0),
-      })),
-    };
-  };
-
-  // The chart derivation engine (rowsToChartSpec) is loaded lazily the first time
-  // charting is enabled, keeping chart.ts (~11 KB gzip) out of the base <SvGrid>
-  // bundle - it rides in the same lazy chunk as the chart panel. `chartSpec` stays
-  // null until it resolves, a tick after the panel itself starts loading (which it
-  // already does). The `getAggregate` server path uses the local bucketsToSpec and
-  // does not need the engine.
-  // The whole module, not just `rowsToChartSpec`: the panel can now reach
-  // every chart type, and the ones that do not read a categories-by-series
-  // grid (scatter, gauge, treemap, calendar, sankey) need their own builders
-  // from the same lazy chunk. Same `import()`, same boundary.
-  let chartEngine = $state<typeof import("./chart") | null>(null);
-  $effect(() => {
-    if (chartingEnabled && !chartEngine)
-      import("./chart").then((m) => (chartEngine = m));
-  });
-
   /** Put the chart's numbers in the same locale as the grid's. A grid that set
    *  `localization.locale` has already said which locale its data is in, and a
    *  chart of that data reading in a different one is a bug nobody would think
@@ -2329,27 +2457,52 @@ export function createSvGridController<
     if (chartCfg?.currency) spec.currency = chartCfg.currency;
   };
 
-  const chartSpec = $derived.by<ChartSpec | null>(() => {
+  const chartSpecLive = $derived.by<ChartSpec | null>(() => {
     if (!chartingEnabled || !chartCfg) return null;
     if (chartCfg.getAggregate) {
-      if (!chartServerBuckets) return null;
-      const spec = bucketsToSpec(chartServerBuckets, chartType, !!effectiveChartSeriesId);
+      if (!chartServerBuckets || !chartEngine) return null;
+      const spec = chartEngine.bucketsToChartSpec(chartServerBuckets, chartType, !!effectiveChartSeriesId);
       if (effectiveChartStacked || chartCfg.stacked100) spec.stacked = true;
       if (chartCfg.stacked100) spec.stacked100 = true;
       if (chartCfg.palette) spec.palette = chartCfg.palette;
       if (effectiveChartTimeAxis) spec.xType = "time";
+    else if (chartBucket && chartDimensionIsDate) spec.xType = "ordinal-time";
       if (effectiveChartLogScale) spec.yScale = "log";
       if (effectiveChartValueFormat) spec.valueFormat = effectiveChartValueFormat;
       applyChartLocale(spec);
       return spec;
     }
     if (chartCfg.buildSpec) return chartCfg.buildSpec(chartRows) ?? null;
+    // Engine not loaded yet (lazy): render nothing until it resolves.
+    if (!chartEngine) return null;
+    // Shared by the direct and aggregated paths so the two cannot drift apart
+    // again - which is how these came to be skipped for scatter, gauge and
+    // boxplot in the first place. Declared here, at the derived's own scope:
+    // a function declaration inside the `else` block below is block-scoped,
+    // and the aggregated path calls it after that block has closed.
+    function applyChartValueSettings<T extends {
+      xType?: string; yScale?: string; valueFormat?: unknown;
+    }>(spec: T): T {
+      if (effectiveChartTimeAxis) spec.xType = "time";
+      if (effectiveChartLogScale) spec.yScale = "log";
+      if (effectiveChartValueFormat) spec.valueFormat = effectiveChartValueFormat;
+      applyChartLocale(spec as never);
+      return spec;
+    }
 
+    // Pivot mode: the pivot on screen is the chart, rows as categories and
+    // columns as series; the pickers have nothing to choose.
+    let spec: ChartSpec;
+    if (pivotResult) {
+      spec = chartEngine.pivotResultToChartSpec(pivotResult, {
+        type: chartType, stacked: effectiveChartStacked, stacked100: effectiveChartStacked100,
+        measures: pivotConfig!.values,
+        ...(effectiveChartPalette ? { palette: effectiveChartPalette } : {}),
+      });
+    } else {
     const category = fieldOf(effectiveChartDimensionId);
     const values = effectiveChartMeasureIds.map((id) => fieldOf(id)).filter((f): f is string => !!f);
-    if (!category || !values.length) return null;
-    // Engine not loaded yet (lazy): render nothing until it resolves.
-    if (!chartEngine) return null;
+    if (!chartIsOhlc && (!category || !values.length)) return null;
     const seriesField = fieldOf(effectiveChartSeriesId);
     const rowsForChart = chartRows as Array<Record<string, unknown>>;
 
@@ -2360,26 +2513,51 @@ export function createSvGridController<
     // base bundle, which every grid pays for whether or not it ever charts.
     // Everything else falls through to the aggregation below and is reshaped
     // afterwards, so reduce / sort / topN / "Other" keep working for all of it.
+    const ohlcOpts = chartIsOhlc
+      ? chartEngine.ohlcDirectOptions(fieldOf, effectiveChartOhlcDateId, effectiveChartOhlc, { bucket: chartBucket, candleStyle: chartCandleStyle })
+      : null;
     const direct = chartEngine.rowsToDirectSpec(chartType, rowsForChart, {
-      category: category as string,
+      ...(ohlcOpts ?? {}),
+      category: ohlcOpts?.category ?? (category as string),
       ...(values[0] ? { value: values[0] } : {}),
       ...(fieldOf(effectiveChartMeasure2Id) ? { value2: fieldOf(effectiveChartMeasure2Id)! } : {}),
       ...(seriesField ? { series: seriesField } : {}),
       reduce: chartReduce,
+      ...(chartBins ? { bins: chartBins } : {}),
       ...(effectiveChartPalette ? { palette: effectiveChartPalette } : {}),
     });
-    if (direct) return direct;
+    // Number formatting and the scale/axis-type settings are about how values
+    // READ, so they apply to a scatter or a gauge exactly as they do to a bar
+    // chart. They used to live only on the aggregated path below, so setting
+    // `valueFormat` or `logScale` on a direct type silently did nothing.
+    //
+    // The series-shaped settings (trend, averageLine, seriesTypes) stay on the
+    // aggregated path: a direct spec does not have the series shape they read.
+    if (direct) {
+      if (chartIsOhlc) {
+        // Overlays ride on the price series; the panes are composed by the
+        // panel body from `chartIndicatorPanes`.
+        const overlay = chartIndicatorSplit.overlay;
+        if (overlay && direct.series[0]) direct.series[0].overlay = overlay;
+      }
+      return applyChartValueSettings(direct);
+    }
     // A direct type that could not build (scatter with no Y picked yet, for
     // instance) must not fall through to the bar-chart path and draw the wrong
     // chart - it renders the panel's empty state instead.
-    if (chartType === "scatter" || chartType === "gauge" || chartType === "boxplot") return null;
+    if (
+      chartType === "scatter" || chartType === "gauge" || chartType === "boxplot" ||
+      chartType === "histogram" || chartType === "range-bar" || chartType === "range-area" ||
+      chartType === "dumbbell" || chartType === "bullet" || chartIsOhlc
+    ) return null;
 
-    const spec = chartEngine.rowsToChartSpec<Record<string, unknown>>(rowsForChart, {
+    spec = chartEngine.rowsToChartSpec<Record<string, unknown>>(rowsForChart, {
       type: chartType,
       category: category as string,
       value: values.length === 1 ? values[0]! : values,
       ...(seriesField ? { series: seriesField } : {}),
       reduce: chartReduce,
+      ...(chartBucket && chartDimensionIsDate ? { bucket: chartBucket } : {}),
       stacked: effectiveChartStacked || effectiveChartStacked100,
       stacked100: effectiveChartStacked100,
       ...(effectiveChartPalette ? { palette: effectiveChartPalette } : {}),
@@ -2388,10 +2566,16 @@ export function createSvGridController<
       ...(chartCfg.sort ? { sort: chartCfg.sort } : {}),
     });
 
+    }
     // Reshape the aggregated grid into whatever this type actually reads.
     // These run AFTER the aggregation so grouping, reduce, sort, topN and the
     // "Other" bucket apply to them exactly as they do to a bar chart.
-    if (chartType === "treemap") spec.treemap = chartEngine.specToTreemap(spec);
+    if (chartType === "treemap" || chartType === "sunburst") spec.treemap = chartEngine.specToTreemap(spec);
+    else if (chartType === "chord") {
+      const flow = chartEngine.specToSankey(spec);
+      spec.sankeyNodes = flow.nodes;
+      spec.sankeyLinks = flow.links;
+    }
     else if (chartType === "calendar") spec.calendarValues = chartEngine.specToCalendar(spec);
     else if (chartType === "sankey") {
       const flow = chartEngine.specToSankey(spec);
@@ -2400,10 +2584,7 @@ export function createSvGridController<
     }
 
     if (effectiveChartOrientation === "horizontal") spec.orientation = "horizontal";
-    if (effectiveChartTimeAxis) spec.xType = "time";
-    if (effectiveChartLogScale) spec.yScale = "log";
-    if (effectiveChartValueFormat) spec.valueFormat = effectiveChartValueFormat;
-    applyChartLocale(spec);
+    applyChartValueSettings(spec);
     if (chartType !== "pie" && spec.orientation !== "horizontal" && !spec.yAxisTitle && chartAutoYAxisTitle) {
       spec.yAxisTitle = chartAutoYAxisTitle;
     }
@@ -2413,6 +2594,11 @@ export function createSvGridController<
     }
     if (chartCfg.annotations) spec.annotations = chartCfg.annotations;
     if (chartCfg.patternFallback) spec.patternFallback = true;
+    if (chartFunnelShape && chartType === "funnel") spec.funnelShape = chartFunnelShape;
+    if (chartCandleStyle && (chartType === "candlestick" || chartType === "ohlc")) spec.candleStyle = chartCandleStyle;
+    // A stream is a stacked area on a wiggle baseline; the picker's Stacked
+    // box has nothing to add, so the offset is applied here outright.
+    if (chartType === "stream") { spec.stacked = true; spec.stackOffset = "wiggle"; }
     const refLines = [...(chartCfg.referenceLines ?? [])];
     if (chartCfg.averageLine && spec.series[0]?.values.length) {
       const vals = spec.series[0].values;
@@ -2421,7 +2607,10 @@ export function createSvGridController<
     }
     if (refLines.length) spec.referenceLines = refLines;
     for (const s of spec.series) {
-      if (chartCfg.trend) s.overlay = chartCfg.trend === "linear" ? "linear" : `${chartCfg.trend}:7`;
+      if (chartCfg.trend) {
+        const t = chartCfg.trend;
+        s.overlay = t === "sma" || t === "ema" ? `${t}:7` : t === "poly" ? "poly:2" : t;
+      }
       if (chartCfg.smooth) s.smooth = true;
       if (chartCfg.seriesTypes?.[s.label]) s.type = chartCfg.seriesTypes[s.label];
       if (chartCfg.seriesAxes?.[s.label]) s.axis = chartCfg.seriesAxes[s.label];
@@ -2429,6 +2618,43 @@ export function createSvGridController<
     return spec;
   });
 
+  /**
+   * What the panel renders: an unlinked chart's frozen snapshot, else the live
+   * derivation with the builder's format applied. The format runs through
+   * the lazy engine so its code stays out of the base bundle.
+   */
+  const chartSpec = $derived.by<ChartSpec | null>(() => {
+    if (activeChart.frozen) return activeChart.frozen.spec;
+    const live = chartSpecLive;
+    if (!live || !activeChart.format || !chartEngine) return live;
+    return chartEngine.applyChartFormat(live, activeChart.format);
+  });
+  let announcedFirstChart = false;
+  $effect(() => {
+    if (!chartPanelOpen || announcedFirstChart || !chartCfg?.onChartCreated) return;
+    announcedFirstChart = true;
+    const c = charts[0]!;
+    untrack(() => chartCfg?.onChartCreated?.({ index: 0, title: c.title, type: c.type, spec: null }));
+  });
+  // Lifecycle: one `onChartChanged` per burst of spec changes.
+  let chartChangeTimer: ReturnType<typeof setTimeout> | null = null;
+  $effect(() => {
+    const cb = chartCfg?.onChartChanged;
+    const spec = chartSpec;
+    const index = activeChartIndex;
+    if (!cb) return;
+    untrack(() => {
+      if (chartChangeTimer) clearTimeout(chartChangeTimer);
+      chartChangeTimer = setTimeout(() => {
+        chartChangeTimer = null;
+        const c = charts[index] ?? activeChart;
+        cb({ index, title: c.title, type: c.type, spec });
+      }, 150);
+    });
+    return () => {
+      if (chartChangeTimer) { clearTimeout(chartChangeTimer); chartChangeTimer = null; }
+    };
+  });
   /**
    * Can a click on this chart be turned back into a grid filter?
    *
@@ -2438,12 +2664,19 @@ export function createSvGridController<
    * at all), or a scatter (the mark carries a point label, not a group).
    */
   const chartCrossFilterable = $derived(
-    chartType !== "sankey" && chartType !== "gauge" && chartType !== "scatter",
+    chartType !== "sankey" && chartType !== "gauge" && chartType !== "scatter" &&
+      // A chord's arcs are both ends of a flow, a sunburst's are a hierarchy
+      // and a histogram's are bins: none maps a click back to one dimension value.
+      chartType !== "chord" && chartType !== "sunburst" && chartType !== "histogram",
   );
 
+  /** The column a chart click filters: the picked dimension, or in pivot mode the innermost row dimension when it is a grid column. */
+  const chartFilterDimId = $derived(
+    pivotResult ? (chartEngine?.pivotFilterColumn(pivotConfig!.rows, chartableColumns.dims, fieldOf) ?? null) : effectiveChartDimensionId,
+  );
   function applyChartCrossFilter(category: string) {
     if (!chartCrossFilterable) return;
-    const dimId = effectiveChartDimensionId;
+    const dimId = chartFilterDimId;
     if (!dimId) return;
     const existing = valueFilters[dimId];
     const next = new Set(existing && existing.has(category) ? existing : []);
@@ -2452,7 +2685,7 @@ export function createSvGridController<
     valueFilters = { ...valueFilters, [dimId]: next };
   }
   function clearChartCrossFilter() {
-    const dimId = effectiveChartDimensionId;
+    const dimId = chartFilterDimId;
     if (!dimId) return;
     const next = { ...valueFilters };
     delete next[dimId];
@@ -2647,9 +2880,46 @@ export function createSvGridController<
     const logical = virtualizer.getState().scrollOffset;
     return logical - rowScrollScaling.logicalToDom(logical);
   });
+  /**
+   * The first `frozenRows` rows are rendered ahead of the virtual window
+   * and stick under the header. The virtualizer still counts them, so its
+   * offsets stay in row-index space and nothing downstream has to translate;
+   * the window skips them, and the top spacer gives back the height they
+   * already occupy in the flow.
+   */
+  const frozenRowCount = $derived(
+    Math.max(0, Math.min(Math.floor(props.frozenRows ?? 0), allRows.length)),
+  );
+  const frozenRowList = $derived(frozenRowCount ? allRows.slice(0, frozenRowCount) : []);
+  /** The merged cells, indexed; null (the usual case) costs nothing. */
+  const mergeIndex = $derived(buildMergeIndex(props.mergedCells));
+  const frozenBandHeight = $derived.by(() => {
+    if (!frozenRowCount) return 0;
+    rowResizeVersion;
+    autoRowHeightVersion;
+    let total = 0;
+    for (let i = 0; i < frozenRowCount; i += 1) total += rowSizePxOf(i);
+    return total;
+  });
+  /** The declared or dragged height of one row; measured under auto height. */
+  function rowSizePxOf(i: number): number {
+    if (isRowCollapsed(i)) return 0;
+    if (autoRowHeightOn) return measuredRowHeights.get(i) ?? autoRowHeightFallback;
+    const own = rowResizeHeightPx(i);
+    if (own != null) return own;
+    const rh = props.rowHeight;
+    return typeof rh === "function" ? rh(i) : (rh ?? 30);
+  }
+  /** Where frozen row i sticks: under the header and the frozen rows above it. */
+  function frozenRowTop(i: number): number {
+    let top = headerHeight;
+    for (let k = 0; k < i; k += 1) top += rowSizePxOf(k);
+    return top;
+  }
   // Spacer heights in DOM space. With scaling inert these equal the original
-  // virtualRowStart / virtualRowBottomSpacer.
-  const rowTopSpacer = $derived(Math.max(virtualRowStart - rowOffsetAdjustment, 0));
+  // virtualRowStart / virtualRowBottomSpacer. The frozen band is in the flow
+  // before the spacer whatever the window shows, so it comes off the spacer.
+  const rowTopSpacer = $derived(Math.max(virtualRowStart - rowOffsetAdjustment - frozenBandHeight, 0));
   const rowBottomSpacer = $derived(
     Math.max(rowDomTotalSize - (virtualRowEnd - rowOffsetAdjustment), 0),
   );
@@ -3003,35 +3273,104 @@ export function createSvGridController<
   );
 
   // ----- Interactive row resize (`rowResize` prop) -----
-  // Heights the user has dragged, by row index. A plain Map plus a version
-  // counter, exactly like `measuredRowHeights` above and for the same reason:
-  // the reset effect below has to read this collection to know whether there is
-  // anything to clear, and if the collection were reactive that read would make
-  // every resize re-trigger the reset and wipe the height it just stored.
-  const rowResizeHeights = new Map<number, number>();
+  // Heights the user has dragged, or set through `api.setRowHeight`, keyed
+  // by ROW ID so they belong to the row rather than to a slot: the height
+  // follows its row through a sort or a filter and survives the data being
+  // replaced. They used to be keyed by index and wiped on every data change,
+  // which in a spreadsheet meant every keystroke, so a row dragged taller
+  // snapped back the moment the next cell was typed. A plain Map plus a
+  // version counter, like `measuredRowHeights` above: the readers touch the
+  // version, and the Map itself stays out of the reactive graph.
+  const rowResizeHeights = new Map<string, number>();
   let rowResizeVersion = $state(0);
-
-  function setRowResizeHeight(index: number, height: number): void {
-    if (!rowResizeOn || !Number.isFinite(index) || height <= 0) return;
-    rowResizeHeights.set(index, Math.round(height));
+  /**
+   * Rows folded to nothing, the row-side twin of `collapsedColumns`: the
+   * row keeps its index and its cells and takes no height. Keyed by row id
+   * like the heights and announced through the same version counter, so
+   * every reader of a row's size sees the change.
+   */
+  const collapsedRows = new Set<string>();
+  function isRowCollapsed(index: number): boolean {
+    rowResizeVersion;
+    const id = allRows[index]?.id;
+    return id != null && collapsedRows.has(id);
+  }
+  function setRowCollapsed(index: number, collapsed: boolean): void {
+    const id = allRows[index]?.id;
+    if (id == null) return;
+    if (collapsed === collapsedRows.has(id)) return;
+    if (collapsed) collapsedRows.add(id);
+    else collapsedRows.delete(id);
     rowResizeVersion += 1;
   }
-  /** A user-dragged height for this row, or undefined when it has not been
-   *  resized. Read by the view AND by the virtualizer's `estimateSize`. */
-  function rowResizeHeightPx(index: number): number | undefined {
-    return rowResizeOn ? rowResizeHeights.get(index) : undefined;
+
+  /**
+   * A size the user changed by hand is one undo step, as it is in a
+   * spreadsheet: Ctrl+Z after a column drag puts the width back. Recorded
+   * only for the user's gestures; the api's own setters record nothing, so
+   * a consumer restoring saved sizes does not fill the history.
+   */
+  function recordSizeUndo(undo: () => void, redo: () => void): void {
+    pushHistory(ctx, [
+      { rowId: "", columnId: "", field: "", before: undefined, after: undefined, custom: { undo, redo } },
+    ]);
+  }
+  // The undo and redo of a size step report through the same callbacks as
+  // the gesture did: a consumer keeping the sizes (a sheet saving its
+  // document) would otherwise hold the width the user dragged to while the
+  // grid showed the one Ctrl+Z put back.
+  function resizeColumnByUser(columnId: string, width: number, before: number): void {
+    const apply = (w: number) => {
+      columnWidths = { ...columnWidths, [columnId]: w };
+      props.onColumnResize?.({ columnId, width: w });
+    };
+    apply(width);
+    if (before !== width) recordSizeUndo(() => apply(before), () => apply(width));
+  }
+  function autosizeColumnByUser(columnId: string): void {
+    const before = getColumnWidth(columnId);
+    autosizeColumn(columnId);
+    const width = getColumnWidth(columnId);
+    const apply = (w: number) => {
+      columnWidths = { ...columnWidths, [columnId]: w };
+      props.onColumnResize?.({ columnId, width: w });
+    };
+    if (before !== width) recordSizeUndo(() => apply(before), () => apply(width));
+    else props.onColumnResize?.({ columnId, width });
+  }
+  function resizeRowByUser(index: number, height: number | null): void {
+    const before = rowResizeHeightPx(index) ?? null;
+    const apply = (h: number | null) => {
+      setRowResizeHeight(index, h);
+      props.onRowResize?.({ rowIndex: index, height: h });
+    };
+    apply(height);
+    if (before !== height) recordSizeUndo(() => apply(before), () => apply(height));
   }
 
-  // A row index means a different row once the data changes, so keeping the
-  // heights would size new rows by the old ones - the same reasoning as the
-  // measured-height reset below.
-  $effect(() => {
-    void allRows.length;
-    void internalData;
-    if (rowResizeHeights.size === 0) return;
-    rowResizeHeights.clear();
+  function setRowResizeHeight(index: number, height: number | null): void {
+    const id = allRows[index]?.id;
+    if (id == null) return;
+    if (height == null) {
+      if (!rowResizeHeights.delete(id)) return;
+    } else {
+      if (!Number.isFinite(height) || height <= 0) return;
+      rowResizeHeights.set(id, Math.round(height));
+    }
     rowResizeVersion += 1;
-  });
+  }
+  /** A row's own height, or undefined when it has none. Read by the view AND
+   *  by the virtualizer's `estimateSize`. Auto height wins over it: the
+   *  content decides the height there, and a manual one would be overwritten
+   *  by the next measurement. */
+  function rowResizeHeightPx(index: number): number | undefined {
+    const id = allRows[index]?.id;
+    if (id == null) return undefined;
+    // A collapsed row is 0 whatever else it has, under auto height too.
+    if (collapsedRows.has(id)) return 0;
+    if (autoRowHeightOn) return undefined;
+    return rowResizeHeights.get(id);
+  }
 
   /** Report a row's measured height. Called by the view's measuring action.
    *  Sub-pixel churn is ignored so a fractional layout can't loop. */
@@ -3056,11 +3395,19 @@ export function createSvGridController<
   function measureRowHeight(node: HTMLElement, index: number) {
     let current = index;
     let stop: (() => void) | null = null;
-    const measure = () => reportRowHeight(current, node.getBoundingClientRect().height);
+    // Read the rect only under autoRowHeight. `getBoundingClientRect` forces a
+    // synchronous layout, and the virtualizer's slot keys hand every rendered
+    // <tr> a new index on each one-row scroll, so measuring unconditionally
+    // meant ~30 forced layouts per arrow key on a fixed-height grid whose
+    // measurement `reportRowHeight` then threw away.
+    const measure = () => {
+      if (!autoRowHeightOn) return;
+      reportRowHeight(current, node.getBoundingClientRect().height);
+    };
     const attach = () => {
       stop?.();
       stop = autoRowHeightOn ? observeSizeRaf(node, measure) : null;
-      if (autoRowHeightOn) measure();
+      measure();
     };
     attach();
     return {
@@ -3112,9 +3459,9 @@ export function createSvGridController<
       : typeof rh === "function"
         ? rh
         : (rh ?? 30);
-    const estimateSize = rowResizeOn
+    const estimateSize = rowResizeHeights.size > 0 || collapsedRows.size > 0
       ? (index: number) =>
-          rowResizeHeights.get(index) ??
+          rowResizeHeightPx(index) ??
           (typeof base === "function" ? base(index) : base)
       : base;
     virtualizer.setOptions({
@@ -3175,6 +3522,7 @@ export function createSvGridController<
     // closure each run; the virtualizer sees a new function reference and
     // re-derives its layout from the current per-column widths.
     columnWidths;
+    collapsedColumns;
     columnVirtualizer.setOptions({
       count: allColumns.length,
       estimateSize: (index: number) => {
@@ -3243,8 +3591,11 @@ export function createSvGridController<
 
 
 
+  // Depends on `allRows` and `rowSelectionState` only. It used to read the
+  // catch-all `gridStateVersion` too, which made every arrow key walk all the
+  // rows (10k iterations on the large-dataset demo, 100k on its top tier) to
+  // recount a selection that had not changed.
   const headerSelectionState = $derived.by(function headerSelectionState_d() {
-    gridStateVersion;
     const selectable = allRows.filter((row) => !isGroupRow(row));
     if (!selectable.length) return "none";
     let selected = 0;
@@ -3261,6 +3612,10 @@ export function createSvGridController<
    *  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);
+  /** The column a run of Tabs began in, so the Enter that ends the run goes
+   *  down from there (`getEntryStep`). Plain, not state: nothing renders
+   *  it. `setActiveCell` clears it; the Tab and Enter paths set it back. */
+  let tabRunOrigin: number | null = null;
 
 
 
@@ -3286,7 +3641,7 @@ export function createSvGridController<
     if (!props.fitColumns || isNarrowResponsive) return null;
     // Exclude columns hidden by a collapsed group too (#57) - otherwise their
     // widths stay in the fit distribution and leave a blank gap at the edge.
-    const cols = grid.getAllColumns().filter((c) => !hiddenColumns[c.id] && !hiddenByGroupCollapse[c.id]);
+    const cols = grid.getAllColumns().filter((c) => !hiddenColumns[c.id] && !hiddenByGroupCollapse[c.id] && !collapsedColumns[c.id]);
     if (!cols.length) return null;
     const rowNumberWidth = showRowNumbersEffective ? rowNumberColumnWidth : 0;
     const selectionWidth = showRowSelectionEffective ? selectionColumnWidth : 0;
@@ -3712,12 +4067,22 @@ export function createSvGridController<
   // 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;
+  // Memoized: `buildApi()` builds a fresh object each call, and a feature pack
+  // that keys per-grid state on the api (a WeakMap in @svgrid/enterprise) needs
+  // the object the consumer received and the object a command handler sees to
+  // be the same one. Every method reads through `ctx`, so one instance stays
+  // correct for the life of the grid.
+  let apiInstance: ReturnType<typeof buildApi> | null = null;
+  function api() {
+    if (!apiInstance) apiInstance = buildApi();
+    return apiInstance;
+  }
   $effect(() => {
     if (apiNotified) return;
     const cb = props.onApiReady;
     if (!cb) return;
     apiNotified = true;
-    cb(buildApi());
+    cb(api());
   });
 
   const ctx = {
@@ -3780,6 +4145,8 @@ export function createSvGridController<
     set history(v) { history = v as never; },
     get historyPtr() { return historyPtr; },
     set historyPtr(v) { historyPtr = v as never; },
+    get historyGroupId() { return historyGroupId; },
+    set historyGroupId(v) { historyGroupId = v as never; },
     get historyVersion() { return historyVersion; },
     set historyVersion(v) { historyVersion = v as never; },
     get tooltip() { return tooltip; },
@@ -3802,6 +4169,9 @@ export function createSvGridController<
     get editorSelectAll() { return editorSelectAll; },
     set editorSelectAll(v) { editorSelectAll = v as never; },
     get columnWidths() { return columnWidths; },
+    get collapsedColumns() { return collapsedColumns; },
+    get mergeIndex() { return mergeIndex; },
+    get setColumnCollapsed() { return setColumnCollapsed; },
     set columnWidths(v) { columnWidths = v as never; },
     get MIN_COLUMN_WIDTH() { return MIN_COLUMN_WIDTH; },
     get columnPinning() { return columnPinning; },
@@ -3873,6 +4243,7 @@ export function createSvGridController<
     get moveCellsEffective() { return moveCellsEffective; },
     get flushScheduledScrollSync() { return flushScheduledScrollSync; },
     get scheduleScrollSync() { return scheduleScrollSync; },
+    get syncScrollNow() { return syncScrollNow; },
     get internalData() { return internalData; },
     set internalData(v) { internalData = v as never; },
     get internalColumns() { return internalColumns; },
@@ -3976,6 +4347,8 @@ export function createSvGridController<
     get moveColumnInPanel() { return moveColumnInPanel; },
     // ---- Localized chrome strings ----
     get messages() { return gridMessages; },
+    /** The raw `localization.text` map, for the lazy chart panel's own strings. */
+    get localizationText() { return props.localization?.text; },
     // ---- In-grid pivot mode ----
     get pivotConfig() { return pivotConfig; },
     get pivotActive() { return pivotActive; },
@@ -4008,6 +4381,32 @@ export function createSvGridController<
     set chartLogScale(v) { activeChart.logScale = v as never; },
     get chartTimeAxis() { return effectiveChartTimeAxis; },
     set chartTimeAxis(v) { activeChart.timeAxis = v as never; },
+    get chartBucket() { return chartBucket; },
+    set chartBucket(v) { activeChart.bucket = v as never; },
+    get chartBins() { return chartBins; },
+    set chartBins(v) { activeChart.bins = v as never; },
+    get chartFunnelShape() { return chartFunnelShape; },
+    set chartFunnelShape(v) { activeChart.funnelShape = v as never; },
+    get chartCandleStyle() { return chartCandleStyle; },
+    set chartCandleStyle(v) { activeChart.candleStyle = v as never; },
+    get chartFormat() { return activeChart.format; },
+    set chartFormat(v) { activeChart.format = v as never; },
+    get chartFrozen() { return activeChart.frozen; },
+    get chartIsOhlc() { return chartIsOhlc; },
+    get chartOhlc() { return effectiveChartOhlc; },
+    set chartOhlc(v) { activeChart.ohlc = v as never; },
+    get chartOhlcDateId() { return effectiveChartOhlcDateId; },
+    get chartIndicators() { return chartIndicators; },
+    set chartIndicators(v) { activeChart.indicators = v as never; },
+    get chartIndicatorPanes() { return chartIndicatorPanes; },
+    get chartZoom() { return activeChart.zoom; },
+    // The panel keeps one chart component across tabs, so "tabs share a
+    // window" is simply every tab carrying the same window: a zoom on one is
+    // written to all, and switching tabs hands the component the same value.
+    set chartZoom(v) {
+      if (chartCfg?.syncTabs) for (const c of charts) c.zoom = v as never;
+      else activeChart.zoom = v as never;
+    },
     get chartValueFormat() { return effectiveChartValueFormat ?? "number"; },
     set chartValueFormat(v) { activeChart.valueFormat = v as never; },
     get chartDimensionIsDate() { return chartDimensionIsDate; },
@@ -4028,8 +4427,21 @@ export function createSvGridController<
     get activeChartIndex() { return Math.min(activeChartIndex, charts.length - 1); },
     set activeChartIndex(v) { activeChartIndex = Math.max(0, Math.min(charts.length - 1, v as number)); },
     addChart() {
-      charts = [...charts, makeChart(`Chart ${charts.length + 1}`)];
+      const next = makeChart(`Chart ${charts.length + 1}`);
+      if (chartCfg?.syncTabs) next.zoom = activeChart.zoom;
+      charts = [...charts, next];
       activeChartIndex = charts.length - 1;
+      chartCfg?.onChartCreated?.({ index: activeChartIndex, title: next.title, type: next.type, spec: null });
+    },
+    /** Unlink the active chart from the grid: it keeps the spec it has now. */
+    freezeChart() {
+      const spec = chartSpec;
+      if (!spec) return;
+      activeChart.frozen = { spec: JSON.parse(JSON.stringify(spec)) as ChartSpec, at: new Date().toISOString() };
+    },
+    /** Link the active chart back to the grid's rows. */
+    unfreezeChart() {
+      activeChart.frozen = null;
     },
     removeChart(index?: number) {
       if (charts.length <= 1) return;
@@ -4042,48 +4454,39 @@ export function createSvGridController<
       if (c) c.title = title;
     },
     getChartsState() {
-      return charts.map((c) => ({
-        title: c.title,
-        type: c.type,
-        dimension: c.dimensionId,
-        series: c.seriesId ?? null,
-        measure: c.measureId,
-        measure2: c.measure2Id,
-        orientation: c.orientation,
-        stacked100: c.stacked100,
-        donut: c.donut,
-        palette: c.palette,
-        reduce: c.reduce,
-        stacked: c.stacked,
-        dataLabels: c.dataLabels,
-        logScale: c.logScale,
-        timeAxis: c.timeAxis,
-        valueFormat: c.valueFormat,
-      }));
+      return charts.map(tabToState);
     },
     applyChartsState(list: ReadonlyArray<Record<string, unknown>>, active?: number) {
-      const restored = list.map((c, i) => ({
-        id: `chart-${chartSeq++}`,
-        title: typeof c.title === "string" ? c.title : `Chart ${i + 1}`,
-        type: (c.type as ChartType) ?? "bar",
-        reduce: (c.reduce as "sum" | "avg" | "count") ?? "sum",
-        dimensionId: (c.dimension as string | null) ?? null,
-        measureId: (c.measure as string | null) ?? null,
-        seriesId: c.series as string | null | undefined,
-        measure2Id: (c.measure2 as string | null) ?? null,
-        orientation: (c.orientation as "vertical" | "horizontal" | null) ?? null,
-        stacked100: (c.stacked100 as boolean | null) ?? null,
-        donut: (c.donut as boolean | null) ?? null,
-        palette: (c.palette as string[] | null) ?? null,
-        stacked: (c.stacked as boolean | null) ?? null,
-        dataLabels: (c.dataLabels as boolean | null) ?? null,
-        logScale: (c.logScale as boolean | null) ?? null,
-        timeAxis: (c.timeAxis as boolean | null) ?? null,
-        valueFormat: (c.valueFormat as ChartValueFormat | null) ?? null,
-      }));
+      const restored = list.map(tabFromState);
       charts = restored.length ? restored : [makeChart("Chart 1")];
       activeChartIndex = Math.max(0, Math.min(charts.length - 1, active ?? 0));
     },
+    // ---- Saved charts ----
+    get savedCharts() { return savedCharts; },
+    /** Keep the active tab's configuration under a name (replacing a same-named one). */
+    saveChart(name: string) {
+      const entry: SavedChartEntry = { name, savedAt: new Date().toISOString(), tab: tabToState(activeChart) };
+      savedCharts = [...savedCharts.filter((s) => s.name !== name), entry];
+    },
+    /** Apply a saved chart to the active tab; the tab keeps its id and title. */
+    applySavedChart(name: string): boolean {
+      const entry = savedCharts.find((s) => s.name === name);
+      if (!entry) return false;
+      const { id: _id, title: _title, ...rest } = tabFromState(entry.tab, activeChartIndex);
+      Object.assign(activeChart, rest);
+      return true;
+    },
+    removeSavedChart(name: string) {
+      savedCharts = savedCharts.filter((s) => s.name !== name);
+    },
+    getSavedCharts() {
+      return savedCharts.map((s) => ({ ...s, tab: { ...s.tab } }));
+    },
+    applySavedCharts(list: ReadonlyArray<Record<string, unknown>>) {
+      savedCharts = list
+        .filter((s) => typeof s?.name === "string" && s.tab && typeof s.tab === "object")
+        .map((s) => ({ name: s.name as string, savedAt: String(s.savedAt ?? ""), tab: s.tab as Record<string, unknown> }));
+    },
     get chartCrossFilterable() { return chartCrossFilterable; },
     get chartOrientation() { return effectiveChartOrientation; },
     set chartOrientation(v) { activeChart.orientation = v as never; },
@@ -4098,19 +4501,40 @@ export function createSvGridController<
     get effectiveChartMeasure2Id() { return effectiveChartMeasure2Id; },
     get chartAiHandler() { return chartAiHandler; },
     set chartAiHandler(v) { chartAiHandler = v as never; },
+    get chartExplainHandler() { return chartExplainHandler; },
+    set chartExplainHandler(v) { chartExplainHandler = v as never; },
     applyChartConfig(config: {
       open?: boolean;
       type?: ChartType;
       dimension?: string | null;
       series?: string | null;
       measure?: string | null;
-      reduce?: "sum" | "avg" | "count";
+      reduce?: ChartReducer;
       stacked?: boolean;
       dataLabels?: boolean;
       logScale?: boolean;
       timeAxis?: boolean;
       valueFormat?: ChartValueFormat;
+      bucket?: ChartTimeBucket | null;
+      bins?: number | null;
+      funnelShape?: "trapezoid" | "pyramid" | "cone" | null;
+      candleStyle?: "classic" | "hollow" | "heikin-ashi" | null;
+      /** Second measure: scatter Y, range high end, bullet target. */
+      measure2?: string | null;
+      /** Candlestick / OHLC price columns (ids or fields). */
+      ohlc?: { open?: string | null; high?: string | null; low?: string | null; close?: string | null; volume?: string | null } | null;
+      /** Indicators: panes (volume, rsi, macd, stochastic, atr, obv) and
+       *  overlays (sma, ema, bb, vwap). */
+      indicators?: ChartPanelIndicator[];
+      /** The builder's format (titles, axes, legend, series style); `null` resets it. */
+      format?: ChartFormatState | null;
+      /** Unlink the chart from the grid (true) or link it back (false). */
+      frozen?: boolean;
+      /** A saved chart's name: applied to the active tab first, then the
+       *  other keys on top. */
+      saved?: string;
     }) {
+      if (config.saved) this.applySavedChart(config.saved);
       const cols = [...chartableColumns.dims, ...chartableColumns.measures];
       const resolve = (v: string | null | undefined): string | null => {
         if (v == null) return null;
@@ -4130,6 +4554,24 @@ export function createSvGridController<
       if (typeof config.logScale === "boolean") activeChart.logScale = config.logScale;
       if (typeof config.timeAxis === "boolean") activeChart.timeAxis = config.timeAxis;
       if (config.valueFormat) activeChart.valueFormat = config.valueFormat;
+      if ("bucket" in config) activeChart.bucket = config.bucket ?? null;
+      if ("bins" in config) activeChart.bins = config.bins ?? null;
+      if ("funnelShape" in config) activeChart.funnelShape = config.funnelShape ?? null;
+      if ("candleStyle" in config) activeChart.candleStyle = config.candleStyle ?? null;
+      if ("measure2" in config) activeChart.measure2Id = resolve(config.measure2);
+      if ("ohlc" in config) {
+        const o = config.ohlc;
+        activeChart.ohlc = o
+          ? { open: resolve(o.open), high: resolve(o.high), low: resolve(o.low), close: resolve(o.close), volume: resolve(o.volume) }
+          : null;
+      }
+      if (config.indicators) activeChart.indicators = [...config.indicators];
+      if ("format" in config) activeChart.format = config.format ?? null;
+      if (config.frozen === false) activeChart.frozen = null;
+      else if (config.frozen === true && !activeChart.frozen) {
+        const spec = chartSpec;
+        if (spec) activeChart.frozen = { spec: JSON.parse(JSON.stringify(spec)) as ChartSpec, at: new Date().toISOString() };
+      }
     },
     get toggleGroupInPanel() { return toggleGroupInPanel; },
     get lastSortingSerialized() { return lastSortingSerialized; },
@@ -4152,8 +4594,17 @@ export function createSvGridController<
     },
     /** True when the `rowResize` prop is on and nothing overrides it. */
     get rowResizeOn() { return rowResizeOn; },
+    get frozenRowCount() { return frozenRowCount; },
+    get frozenRowList() { return frozenRowList; },
+    get frozenBandHeight() { return frozenBandHeight; },
+    get frozenRowTop() { return frozenRowTop; },
     /** Record the height the user dragged a row to. */
     get setRowResizeHeight() { return setRowResizeHeight; },
+    get isRowCollapsed() { return isRowCollapsed; },
+    get setRowCollapsed() { return setRowCollapsed; },
+    get resizeRowByUser() { return resizeRowByUser; },
+    get resizeColumnByUser() { return resizeColumnByUser; },
+    get autosizeColumnByUser() { return autosizeColumnByUser; },
     /** A row's dragged height, or undefined when it has not been resized. */
     get rowResizeHeightPx() {
       rowResizeVersion;
@@ -4216,6 +4667,8 @@ export function createSvGridController<
     get toggleSelectAllRows() { return toggleSelectAllRows; },
     get userHasActivatedCell() { return userHasActivatedCell; },
     set userHasActivatedCell(v) { userHasActivatedCell = v as never; },
+    get tabRunOrigin() { return tabRunOrigin; },
+    set tabRunOrigin(v) { tabRunOrigin = v; },
     get setActiveCell() { return setActiveCell; },
     get scrollActiveCellIntoView() { return scrollActiveCellIntoView; },
     get getColumnBaseWidth() { return getColumnBaseWidth; },
@@ -4225,6 +4678,8 @@ export function createSvGridController<
     get extendSelection() { return extendSelection; },
     get isCellInSelectedRange() { return isCellInSelectedRange; },
     get getCellRangeEdges() { return getCellRangeEdges; },
+    get activeRangeRect() { return activeRangeRect; },
+    get cellSelectionState() { return cellSelectionState; },
     get getSelectionRects() { return getSelectionRects; },
     get fillHandleCell() { return fillHandleCell; },
     get isInFillPreview() { return isInFillPreview; },
@@ -4247,6 +4702,7 @@ export function createSvGridController<
     get startFillDrag() { return startFillDrag; },
     get onFillPointerMove() { return onFillPointerMove; },
     get onFillPointerUp() { return onFillPointerUp; },
+    get fillDownToNeighbour() { return fillDownToNeighbour; },
     get isOnMoveGrabStrip() { return isOnMoveGrabStrip; },
     get startMoveDrag() { return startMoveDrag; },
     get onMovePointerMove() { return onMovePointerMove; },
@@ -4266,6 +4722,7 @@ export function createSvGridController<
     get cutSelectionToClipboard() { return cutSelectionToClipboard; },
     get pasteFromClipboard() { return pasteFromClipboard; },
     get onGridPaste() { return onGridPaste; },
+    get armPasteFallback() { return armPasteFallback; },
     get clearSelectedCells() { return clearSelectedCells; },
     get onCellDoubleClick() { return onCellDoubleClick; },
     get startEditingWithChar() { return startEditingWithChar; },
@@ -4342,12 +4799,12 @@ export function createSvGridController<
     get clearColumnFilter() { return clearColumnFilter; },
     get onWindowKeydown() { return onWindowKeydown; },
     get columnDefMatchesId() { return columnDefMatchesId; },
-    get buildApi() { return buildApi; },
+    get buildApi() { return api; },
     get apiNotified() { return apiNotified; },
     set apiNotified(v) { apiNotified = v as never; },
   };
   const { resolveEffectiveFeatures } = createFeatures<TFeatures, TData>(ctx);
-  const { showTooltipFor, hideTooltip, flushScheduledScrollSync, scheduleScrollSync, onBodyScroll } = createScrollSync<TFeatures, TData>(ctx);
+  const { showTooltipFor, hideTooltip, flushScheduledScrollSync, scheduleScrollSync, syncScrollNow, onBodyScroll } = createScrollSync<TFeatures, TData>(ctx);
   const { onGridKeyDown, onWindowKeydown, onHeaderSortClick } = createKeyboard<TFeatures, TData>(ctx);
   const { computeSummaries, hasRenderedColumn } = createSummaries<TFeatures, TData>(ctx);
   // Hand the aggregator to `eagerSummaries` (declared above `ctx`, which this
@@ -4356,13 +4813,13 @@ export function createSvGridController<
 
   const { updateFilterRow, updateFilterOperator, updateFilterMenuValue, updateFilterMenuValueTo, addFilterToken, removeFilterToken, toggleFilterToken, toggleCheckboxWithKeyboard, isColumnFiltered, closeMenus, openInSuggest, closeInSuggest, openChooseColumns, openColumnMenu, openFilterMenu, openOperatorMenu, sortColumnFromMenu, clearColumnSort, groupByColumnFromMenu, clearGroupingFromMenu, isFacetChecked, toggleFacetValue, setFacetSelection, setFilterTokens, isAllFacetsChecked, toggleAllFacets, clearColumnFilter, changePage, goToPage, setPageSize, openContextMenu, closeContextMenu, contextMenuItems, saveComment, removeComment, closeCommentEditor } = createMenus<TFeatures, TData>(ctx);
   const { cellConditionalFormat, computeRowClass, computeCellClass, computeCellTooltip, computeCellValidity, computeCellNote, getColumnEditorOptions, areEditorOptionsLoading, formatListCellValue, formatCellValue, formatPinnedValue, computePinnedCellClass } = createCellRender<TFeatures, TData>(ctx);
-  const { isCellEditable, isCellEditableAt, getRowColumnValue, getCellDisplayValue, startEditingWithChar, startEditing, stopEditing, startFullRowEdit, setFullRowDraft, commitFullRowEdit, cancelFullRowEdit, saveEditingCell, applyHistoryStep, updateEditingCellValue, onEditorKeyDown, commitAndMoveByTab, focusOnMount, onCellDoubleClick, pasteFromClipboard, onGridPaste } = createEditing<TFeatures, TData>(ctx);
-  const { isRowSelected, toggleRowSelectionById, toggleSelectAllRows, setActiveCell, scrollActiveCellIntoView, setSelection, extendSelection, isCellInSelectedRange, getCellRangeEdges, getSelectionRects, isInFillPreview, dragPreviewRect, fillMarqueeEdges, findColumnById, onCellPointerDown, onCellPointerEnter, endDragSelection, onWindowPointerMove, onCellClick, emitCellDoubleClick } = createSelection<TFeatures, TData>(ctx);
+  const { isCellEditable, isCellEditableAt, getRowColumnValue, getCellDisplayValue, startEditingWithChar, startEditing, stopEditing, startFullRowEdit, setFullRowDraft, commitFullRowEdit, cancelFullRowEdit, saveEditingCell, applyHistoryStep, updateEditingCellValue, onEditorKeyDown, commitAndMoveByTab, focusOnMount, onCellDoubleClick, pasteFromClipboard, onGridPaste, armPasteFallback } = createEditing<TFeatures, TData>(ctx);
+  const { isRowSelected, toggleRowSelectionById, toggleSelectAllRows, setActiveCell, scrollActiveCellIntoView, setSelection, extendSelection, isCellInSelectedRange, getCellRangeEdges, activeRangeRect, cellSelectionState, getSelectionRects, isInFillPreview, dragPreviewRect, fillMarqueeEdges, findColumnById, onCellPointerDown, onCellPointerEnter, endDragSelection, onWindowPointerMove, onCellClick, emitCellDoubleClick } = createSelection<TFeatures, TData>(ctx);
   const { cellPinStyle, isColumnPinned, getCurrentColumnOrder, emitColumnOrder, setColumnOrderInternal, applyColumnDrop, onColumnHeaderDragStart, onColumnHeaderDragOver, onColumnHeaderDragLeave, onColumnHeaderDrop, onColumnHeaderDragEnd, pinColumnLeft, pinColumnRight, unpinColumn, toggleColumnVisibleInPanel, moveColumnInPanel, toggleGroupInPanel, getColumnBaseWidth, getColumnWidth, measureText, autosizeColumn, autosizeAllColumns, resetColumns } = createColumns<TFeatures, TData>(ctx);
   const { onRowDragStart, onRowDragOver, onRowDragLeave, onRowDrop, onRowsContainerDragOver, onRowsContainerDrop, onRowDragEnd, onRowPointerDown, destroyRowDrag } = createRowDrag<TFeatures, TData>(ctx);
   const { register: registerAlignedGrid, broadcastScroll: broadcastAlignedScroll, broadcastWidths: broadcastAlignedWidths } = createAlignedGrids<TFeatures, TData>(ctx);
   const { buildApi } = createGridApi<TFeatures, TData>(ctx);
-  const { readCellRaw, writeCellRaw, applyFillPattern, clearSelectedCellValues, startFillDrag, onFillPointerMove, onFillPointerUp, isOnMoveGrabStrip, startMoveDrag, onMovePointerMove, onMovePointerUp, applyMoveRange, moveDestRect, trackEdgeScroll, stopEdgeScroll, toggleBooleanCell, copySelectionToClipboard, clearSelectedCells, cutSelectionToClipboard } = createClipboard(ctx);
+  const { readCellRaw, writeCellRaw, applyFillPattern, clearSelectedCellValues, startFillDrag, onFillPointerMove, onFillPointerUp, fillDownToNeighbour, isOnMoveGrabStrip, startMoveDrag, onMovePointerMove, onMovePointerUp, applyMoveRange, moveDestRect, trackEdgeScroll, stopEdgeScroll, toggleBooleanCell, copySelectionToClipboard, clearSelectedCells, cutSelectionToClipboard } = createClipboard(ctx);
 
   // Dev-time configuration checks. Silent misconfiguration was the grid's
   // biggest usability gap - a misspelled `field` rendered a column of blank