@mui/x-charts 9.4.0 → 9.5.0

package/internals/plugins/corePlugins/useChartExperimentalFeature/useChartExperimentalFeature.types.d.ts

@@ -13,7 +13,21 @@ interface LineExperimentalFeatures {
    */
   enablePositionBasedPointerInteraction?: boolean;
 }
-export type ChartExperimentalFeatures<SeriesType extends ChartSeriesType = ChartSeriesType> = 'line' extends SeriesType ? LineExperimentalFeatures : {};
+interface ScatterExperimentalFeatures {
+  /**
+   * Enables automatic progressive (batched) rendering for scatter series.
+   *
+   * When enabled and the `renderer` prop is left unset, the chart switches to
+   * the `svg-progressive` renderer above an internal point-count threshold,
+   * painting points over several animation frames to keep the main thread
+   * responsive. When disabled, the unset `renderer` keeps the synchronous
+   * `svg-single` renderer. Setting `renderer` explicitly is unaffected.
+   *
+   * This behavior will become the default in the next major version.
+   */
+  progressiveRendering?: boolean;
+}
+export type ChartExperimentalFeatures<SeriesType extends ChartSeriesType = ChartSeriesType> = ('line' extends SeriesType ? LineExperimentalFeatures : {}) & ('scatter' extends SeriesType ? ScatterExperimentalFeatures : {});
 export interface UseChartExperimentalFeaturesParameters<SeriesType extends ChartSeriesType = ChartSeriesType> {
   /**
    * Options to enable features planned for the next major.

package/internals/plugins/featurePlugins/useChartCartesianAxis/getAxisScale.js

@@ -13,14 +13,39 @@ function getRange(drawingArea, axisDirection, axis) {
   const range = axisDirection === 'x' ? [drawingArea.left, drawingArea.left + drawingArea.width] : [drawingArea.top + drawingArea.height, drawingArea.top];
   return axis.reverse ? [range[1], range[0]] : range;
 }
+
+/**
+ * Caches the normalized ordinal scale so it is not rebuilt on every pan/zoom frame. Building a
+ * band/point scale is `O(domain)` — it interns the whole domain — which is prohibitive for large
+ * category axes when zooming. The domain array (the axis `data`) is referentially stable across
+ * zoom, so it is the outer key; a `WeakMap` lets unused domains be collected. The inner key is the
+ * scale variant (type + padding), because the same domain array can back several axes (e.g. a `band`
+ * and a `point` axis sharing one `data` array), which must not share a scale. Continuous scales are
+ * not cached: they are cheap to build and their domain reference changes with zoom anyway, so a
+ * cache would only ever miss.
+ */
+const normalizedScaleCache = new WeakMap();
+function getCachedOrdinalScale(domain, variant, build) {
+  let variants = normalizedScaleCache.get(domain);
+  if (!variants) {
+    variants = new Map();
+    normalizedScaleCache.set(domain, variants);
+  }
+  let scale = variants.get(variant);
+  if (!scale) {
+    scale = build();
+    variants.set(variant, scale);
+  }
+  return scale;
+}
 function getNormalizedAxisScale(axis, domain) {
   const range = [0, 1];
   if ((0, _axis.isBandScaleConfig)(axis)) {
     const categoryGapRatio = axis.categoryGapRatio ?? DEFAULT_CATEGORY_GAP_RATIO;
-    return (0, _scales.scaleBand)(domain, range).paddingInner(categoryGapRatio).paddingOuter(categoryGapRatio / 2);
+    return getCachedOrdinalScale(domain, `band:${categoryGapRatio}`, () => (0, _scales.scaleBand)(domain, range).paddingInner(categoryGapRatio).paddingOuter(categoryGapRatio / 2));
   }
   if ((0, _axis.isPointScaleConfig)(axis)) {
-    return (0, _scales.scalePoint)(domain, range);
+    return getCachedOrdinalScale(domain, 'point', () => (0, _scales.scalePoint)(domain, range));
   }
   const scaleType = axis.scaleType ?? 'linear';
   const scale = (0, _getScale.getScale)(scaleType, domain, range);

package/internals/plugins/featurePlugins/useChartCartesianAxis/getAxisScale.mjs

@@ -6,14 +6,39 @@ export function getRange(drawingArea, axisDirection, axis) {
   const range = axisDirection === 'x' ? [drawingArea.left, drawingArea.left + drawingArea.width] : [drawingArea.top + drawingArea.height, drawingArea.top];
   return axis.reverse ? [range[1], range[0]] : range;
 }
+
+/**
+ * Caches the normalized ordinal scale so it is not rebuilt on every pan/zoom frame. Building a
+ * band/point scale is `O(domain)` — it interns the whole domain — which is prohibitive for large
+ * category axes when zooming. The domain array (the axis `data`) is referentially stable across
+ * zoom, so it is the outer key; a `WeakMap` lets unused domains be collected. The inner key is the
+ * scale variant (type + padding), because the same domain array can back several axes (e.g. a `band`
+ * and a `point` axis sharing one `data` array), which must not share a scale. Continuous scales are
+ * not cached: they are cheap to build and their domain reference changes with zoom anyway, so a
+ * cache would only ever miss.
+ */
+const normalizedScaleCache = new WeakMap();
+function getCachedOrdinalScale(domain, variant, build) {
+  let variants = normalizedScaleCache.get(domain);
+  if (!variants) {
+    variants = new Map();
+    normalizedScaleCache.set(domain, variants);
+  }
+  let scale = variants.get(variant);
+  if (!scale) {
+    scale = build();
+    variants.set(variant, scale);
+  }
+  return scale;
+}
 export function getNormalizedAxisScale(axis, domain) {
   const range = [0, 1];
   if (isBandScaleConfig(axis)) {
     const categoryGapRatio = axis.categoryGapRatio ?? DEFAULT_CATEGORY_GAP_RATIO;
-    return scaleBand(domain, range).paddingInner(categoryGapRatio).paddingOuter(categoryGapRatio / 2);
+    return getCachedOrdinalScale(domain, `band:${categoryGapRatio}`, () => scaleBand(domain, range).paddingInner(categoryGapRatio).paddingOuter(categoryGapRatio / 2));
   }
   if (isPointScaleConfig(axis)) {
-    return scalePoint(domain, range);
+    return getCachedOrdinalScale(domain, 'point', () => scalePoint(domain, range));
   }
   const scaleType = axis.scaleType ?? 'linear';
   const scale = getScale(scaleType, domain, range);

package/internals/plugins/featurePlugins/useChartCartesianAxis/useChartCartesianAxis.js

@@ -14,7 +14,6 @@ var _store = require("@mui/x-internals/store");
 var _useAssertModelConsistency = require("@mui/x-internals/useAssertModelConsistency");
 var _warning = require("@mui/x-internals/warning");
 var _colorPalettes = require("../../../../colorPalettes");
-var _useChartDimensions = require("../../corePlugins/useChartDimensions/useChartDimensions.selectors");
 var _useChartSeries = require("../../corePlugins/useChartSeries/useChartSeries.selectors");
 var _defaultizeAxis = require("./defaultizeAxis");
 var _useChartCartesianAxisRendering = require("./useChartCartesianAxisRendering.selectors");
@@ -47,7 +46,6 @@ const useChartCartesianAxis = ({
       (0, _warning.warnOnce)([`MUI X Charts: The following axis ids are duplicated: ${Array.from(duplicates).join(', ')}.`, `Please make sure that each axis has a unique id.`].join('\n'), 'error');
     }
   }
-  const drawingArea = store.use(_useChartDimensions.selectorChartDrawingArea);
   const processedSeries = store.use(_useChartSeries.selectorChartSeriesProcessed);
   const isInteractionEnabled = store.use(_useChartInteraction.selectorChartsInteractionIsInitialized);
   const {
@@ -96,7 +94,7 @@ const useChartCartesianAxis = ({
       x: (0, _defaultizeAxis.defaultizeXAxis)(xAxis, dataset, axesGap),
       y: (0, _defaultizeAxis.defaultizeYAxis)(yAxis, dataset, axesGap)
     });
-  }, [drawingArea, xAxis, yAxis, dataset, axesGap, store]);
+  }, [xAxis, yAxis, dataset, axesGap, store]);
   const usedXAxis = xAxisIds[0];
   const usedYAxis = yAxisIds[0];
   (0, _store.useStoreEffect)(store, _useChartCartesianInteraction.selectorChartAxisInteraction, (prevAxisInteraction, nextAxisInteraction) => {

package/internals/plugins/featurePlugins/useChartCartesianAxis/useChartCartesianAxis.mjs

@@ -7,7 +7,6 @@ import { useStoreEffect } from '@mui/x-internals/store';
 import { useAssertModelConsistency } from '@mui/x-internals/useAssertModelConsistency';
 import { warnOnce } from '@mui/x-internals/warning';
 import { rainbowSurgePalette } from "../../../../colorPalettes/index.mjs";
-import { selectorChartDrawingArea } from "../../corePlugins/useChartDimensions/useChartDimensions.selectors.mjs";
 import { selectorChartSeriesProcessed } from "../../corePlugins/useChartSeries/useChartSeries.selectors.mjs";
 import { defaultizeXAxis, defaultizeYAxis } from "./defaultizeAxis.mjs";
 import { selectorChartXAxis, selectorChartYAxis } from "./useChartCartesianAxisRendering.selectors.mjs";
@@ -40,7 +39,6 @@ export const useChartCartesianAxis = ({
       warnOnce([`MUI X Charts: The following axis ids are duplicated: ${Array.from(duplicates).join(', ')}.`, `Please make sure that each axis has a unique id.`].join('\n'), 'error');
     }
   }
-  const drawingArea = store.use(selectorChartDrawingArea);
   const processedSeries = store.use(selectorChartSeriesProcessed);
   const isInteractionEnabled = store.use(selectorChartsInteractionIsInitialized);
   const {
@@ -89,7 +87,7 @@ export const useChartCartesianAxis = ({
       x: defaultizeXAxis(xAxis, dataset, axesGap),
       y: defaultizeYAxis(yAxis, dataset, axesGap)
     });
-  }, [drawingArea, xAxis, yAxis, dataset, axesGap, store]);
+  }, [xAxis, yAxis, dataset, axesGap, store]);
   const usedXAxis = xAxisIds[0];
   const usedYAxis = yAxisIds[0];
   useStoreEffect(store, selectorChartAxisInteraction, (prevAxisInteraction, nextAxisInteraction) => {

package/internals/plugins/featurePlugins/useChartCartesianAxis/useChartCartesianAxisRendering.selectors.js

@@ -259,7 +259,7 @@ const selectorChartDefaultYAxisId = exports.selectorChartDefaultYAxisId = (0, _s
 const EMPTY_MAP = new Map();
 const selectorChartSeriesEmptyFlatbushMap = () => EMPTY_MAP;
 exports.selectorChartSeriesEmptyFlatbushMap = selectorChartSeriesEmptyFlatbushMap;
-const selectorChartSeriesFlatbushMap = exports.selectorChartSeriesFlatbushMap = (0, _store.createSelectorMemoized)(_useChartSeries.selectorChartSeriesProcessed, selectorChartNormalizedXScales, selectorChartNormalizedYScales, selectorChartDefaultXAxisId, selectorChartDefaultYAxisId, _useChartZAxis.selectorChartZAxis, _useChartDimensions.selectorChartDrawingArea, function selectChartSeriesFlatbushMap(allSeries, xAxesScaleMap, yAxesScaleMap, defaultXAxisId, defaultYAxisId, zAxisState) {
+const selectorChartSeriesFlatbushMap = exports.selectorChartSeriesFlatbushMap = (0, _store.createSelectorMemoized)(_useChartSeries.selectorChartSeriesProcessed, selectorChartNormalizedXScales, selectorChartNormalizedYScales, selectorChartDefaultXAxisId, selectorChartDefaultYAxisId, _useChartZAxis.selectorChartZAxis, function selectChartSeriesFlatbushMap(allSeries, xAxesScaleMap, yAxesScaleMap, defaultXAxisId, defaultYAxisId, zAxisState) {
   // FIXME: Do we want to support non-scatter series here?
   const validSeries = allSeries.scatter;
   const flatbushMap = new Map();

package/internals/plugins/featurePlugins/useChartCartesianAxis/useChartCartesianAxisRendering.selectors.mjs

@@ -250,7 +250,7 @@ export const selectorChartDefaultXAxisId = createSelector(selectorChartRawXAxis,
 export const selectorChartDefaultYAxisId = createSelector(selectorChartRawYAxis, yAxes => yAxes[0].id);
 const EMPTY_MAP = new Map();
 export const selectorChartSeriesEmptyFlatbushMap = () => EMPTY_MAP;
-export const selectorChartSeriesFlatbushMap = createSelectorMemoized(selectorChartSeriesProcessed, selectorChartNormalizedXScales, selectorChartNormalizedYScales, selectorChartDefaultXAxisId, selectorChartDefaultYAxisId, selectorChartZAxis, selectorChartDrawingArea, function selectChartSeriesFlatbushMap(allSeries, xAxesScaleMap, yAxesScaleMap, defaultXAxisId, defaultYAxisId, zAxisState) {
+export const selectorChartSeriesFlatbushMap = createSelectorMemoized(selectorChartSeriesProcessed, selectorChartNormalizedXScales, selectorChartNormalizedYScales, selectorChartDefaultXAxisId, selectorChartDefaultYAxisId, selectorChartZAxis, function selectChartSeriesFlatbushMap(allSeries, xAxesScaleMap, yAxesScaleMap, defaultXAxisId, defaultYAxisId, zAxisState) {
   // FIXME: Do we want to support non-scatter series here?
   const validSeries = allSeries.scatter;
   const flatbushMap = new Map();

package/internals/plugins/featurePlugins/useProgressiveRendering/index.d.mts

@@ -0,0 +1,3 @@
+export { useProgressiveRendering } from "./useProgressiveRendering.mjs";
+export type { UseProgressiveRenderingSignature, UseProgressiveRenderingInstance, UseProgressiveRenderingState } from "./useProgressiveRendering.types.mjs";
+export * from "./useProgressiveRendering.selectors.mjs";

package/internals/plugins/featurePlugins/useProgressiveRendering/index.d.ts

@@ -0,0 +1,3 @@
+export { useProgressiveRendering } from "./useProgressiveRendering.js";
+export type { UseProgressiveRenderingSignature, UseProgressiveRenderingInstance, UseProgressiveRenderingState } from "./useProgressiveRendering.types.js";
+export * from "./useProgressiveRendering.selectors.js";

package/internals/plugins/featurePlugins/useProgressiveRendering/index.js

@@ -0,0 +1,27 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+var _exportNames = {
+  useProgressiveRendering: true
+};
+Object.defineProperty(exports, "useProgressiveRendering", {
+  enumerable: true,
+  get: function () {
+    return _useProgressiveRendering.useProgressiveRendering;
+  }
+});
+var _useProgressiveRendering = require("./useProgressiveRendering");
+var _useProgressiveRendering2 = require("./useProgressiveRendering.selectors");
+Object.keys(_useProgressiveRendering2).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return;
+  if (key in exports && exports[key] === _useProgressiveRendering2[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _useProgressiveRendering2[key];
+    }
+  });
+});

package/internals/plugins/featurePlugins/useProgressiveRendering/index.mjs

@@ -0,0 +1,2 @@
+export { useProgressiveRendering } from "./useProgressiveRendering.mjs";
+export * from "./useProgressiveRendering.selectors.mjs";

package/internals/plugins/featurePlugins/useProgressiveRendering/useProgressiveRendering.d.mts

@@ -0,0 +1,13 @@
+import { type ChartPlugin } from "../../models/index.mjs";
+import { type UseProgressiveRenderingSignature } from "./useProgressiveRendering.types.mjs";
+/**
+ * Chart-wide progressive rendering coordinator.
+ *
+ * Lives on the chart store, so every renderer composed into the same chart
+ * (e.g. several `ScatterPlot` instances under one `ChartsContainer`) shares
+ * the same scheduler. Each renderer registers a plan via
+ * `setProgressivePlan(plotId, plan)`; the plugin aggregates them, computes a
+ * single per-tick budget, and ramps a global "rounds" counter — one round
+ * adds one batch in every registered series at once.
+ */
+export declare const useProgressiveRendering: ChartPlugin<UseProgressiveRenderingSignature>;

package/internals/plugins/featurePlugins/useProgressiveRendering/useProgressiveRendering.d.ts

@@ -0,0 +1,13 @@
+import { type ChartPlugin } from "../../models/index.js";
+import { type UseProgressiveRenderingSignature } from "./useProgressiveRendering.types.js";
+/**
+ * Chart-wide progressive rendering coordinator.
+ *
+ * Lives on the chart store, so every renderer composed into the same chart
+ * (e.g. several `ScatterPlot` instances under one `ChartsContainer`) shares
+ * the same scheduler. Each renderer registers a plan via
+ * `setProgressivePlan(plotId, plan)`; the plugin aggregates them, computes a
+ * single per-tick budget, and ramps a global "rounds" counter — one round
+ * adds one batch in every registered series at once.
+ */
+export declare const useProgressiveRendering: ChartPlugin<UseProgressiveRenderingSignature>;

package/internals/plugins/featurePlugins/useProgressiveRendering/useProgressiveRendering.js

@@ -0,0 +1,136 @@
+"use strict";
+'use client';
+
+var _interopRequireWildcard = require("@babel/runtime/helpers/interopRequireWildcard").default;
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useProgressiveRendering = void 0;
+var _extends2 = _interopRequireDefault(require("@babel/runtime/helpers/extends"));
+var React = _interopRequireWildcard(require("react"));
+var _useEventCallback = _interopRequireDefault(require("@mui/utils/useEventCallback"));
+var _useProgressiveRendering = require("./useProgressiveRendering.selectors");
+const EMPTY_PLANS = new Map();
+
+/**
+ * How many *rounds* are revealed per reveal tick once the render data is ready.
+ * A round reveals one batch in every series simultaneously, so the chart looks
+ * complete from the first paint rather than appearing series-by-series. Lower
+ * spreads the paint over more ticks (smoother, more visibly progressive);
+ * higher finishes sooner.
+ */
+const REVEAL_ROUNDS_PER_FRAME = 1;
+
+/**
+ * How many animation frames are skipped between two reveal ticks. `0` reveals
+ * on every frame; `1` reveals every other frame, leaving the browser an idle
+ * frame for layout, paint and input handling between commits. Higher values
+ * give the browser more CPU headroom at the cost of a slower paint.
+ */
+const REVEAL_FRAMES_SKIPPED = 0;
+
+/**
+ * Chart-wide progressive rendering coordinator.
+ *
+ * Lives on the chart store, so every renderer composed into the same chart
+ * (e.g. several `ScatterPlot` instances under one `ChartsContainer`) shares
+ * the same scheduler. Each renderer registers a plan via
+ * `setProgressivePlan(plotId, plan)`; the plugin aggregates them, computes a
+ * single per-tick budget, and ramps a global "rounds" counter — one round
+ * adds one batch in every registered series at once.
+ */
+const useProgressiveRendering = ({
+  store
+}) => {
+  const registerProgressivePlan = (0, _useEventCallback.default)((plotId, seriesIds, renderer) => {
+    if (!(0, _useProgressiveRendering.selectorShouldUseProgressiveRenderer)(store.state, seriesIds, renderer)) {
+      return undefined;
+    }
+    const current = store.state.progressiveRendering.plans.get(plotId);
+    if (!(0, _useProgressiveRendering.sameSeriesIds)(current, seriesIds)) {
+      const nextPlans = new Map(store.state.progressiveRendering.plans);
+      nextPlans.set(plotId, seriesIds);
+      // A real plan change restarts the progressive paint.
+      store.set('progressiveRendering', {
+        plans: nextPlans,
+        revealedRounds: 0
+      });
+    }
+    return () => {
+      if (!store.state.progressiveRendering.plans.has(plotId)) {
+        return;
+      }
+      const nextPlans = new Map(store.state.progressiveRendering.plans);
+      nextPlans.delete(plotId);
+      store.set('progressiveRendering', (0, _extends2.default)({}, store.state.progressiveRendering, {
+        plans: nextPlans
+      }));
+    };
+  });
+  const plans = store.use(_useProgressiveRendering.selectorProgressivePlans) ?? EMPTY_PLANS;
+  React.useEffect(() => {
+    const startTotal = (0, _useProgressiveRendering.selectorProgressiveTotalRounds)(store.state);
+    if (startTotal === 0) {
+      return undefined;
+    }
+    if (typeof requestAnimationFrame !== 'function') {
+      store.set('progressiveRendering', (0, _extends2.default)({}, store.state.progressiveRendering, {
+        revealedRounds: startTotal
+      }));
+      return undefined;
+    }
+    let frame = 0;
+    let cancelled = false;
+    // Tracked in a closure variable, not derived inside a state updater (those
+    // must be pure and StrictMode double-invokes them, which would schedule
+    // the animation-frame chain twice).
+    let revealed = 0;
+    function scheduleNext() {
+      let remaining = REVEAL_FRAMES_SKIPPED;
+      const tick = () => {
+        if (cancelled) {
+          return;
+        }
+        if (remaining > 0) {
+          remaining -= 1;
+          frame = requestAnimationFrame(tick);
+          return;
+        }
+        step();
+      };
+      frame = requestAnimationFrame(tick);
+    }
+    function step() {
+      if (cancelled) {
+        return;
+      }
+      const total = (0, _useProgressiveRendering.selectorProgressiveTotalRounds)(store.state);
+      revealed = Math.min(total, revealed + REVEAL_ROUNDS_PER_FRAME);
+      store.set('progressiveRendering', (0, _extends2.default)({}, store.state.progressiveRendering, {
+        revealedRounds: revealed
+      }));
+      if (revealed < total) {
+        scheduleNext();
+      }
+    }
+    frame = requestAnimationFrame(step);
+    return () => {
+      cancelled = true;
+      cancelAnimationFrame(frame);
+    };
+  }, [plans, store]);
+  return {
+    instance: {
+      registerProgressivePlan
+    }
+  };
+};
+exports.useProgressiveRendering = useProgressiveRendering;
+useProgressiveRendering.params = {};
+useProgressiveRendering.getInitialState = () => ({
+  progressiveRendering: {
+    plans: EMPTY_PLANS,
+    revealedRounds: 0
+  }
+});

package/internals/plugins/featurePlugins/useProgressiveRendering/useProgressiveRendering.mjs

@@ -0,0 +1,128 @@
+'use client';
+
+import _extends from "@babel/runtime/helpers/esm/extends";
+import * as React from 'react';
+import useEventCallback from '@mui/utils/useEventCallback';
+import { sameSeriesIds, selectorProgressivePlans, selectorProgressiveTotalRounds, selectorShouldUseProgressiveRenderer } from "./useProgressiveRendering.selectors.mjs";
+const EMPTY_PLANS = new Map();
+
+/**
+ * How many *rounds* are revealed per reveal tick once the render data is ready.
+ * A round reveals one batch in every series simultaneously, so the chart looks
+ * complete from the first paint rather than appearing series-by-series. Lower
+ * spreads the paint over more ticks (smoother, more visibly progressive);
+ * higher finishes sooner.
+ */
+const REVEAL_ROUNDS_PER_FRAME = 1;
+
+/**
+ * How many animation frames are skipped between two reveal ticks. `0` reveals
+ * on every frame; `1` reveals every other frame, leaving the browser an idle
+ * frame for layout, paint and input handling between commits. Higher values
+ * give the browser more CPU headroom at the cost of a slower paint.
+ */
+const REVEAL_FRAMES_SKIPPED = 0;
+
+/**
+ * Chart-wide progressive rendering coordinator.
+ *
+ * Lives on the chart store, so every renderer composed into the same chart
+ * (e.g. several `ScatterPlot` instances under one `ChartsContainer`) shares
+ * the same scheduler. Each renderer registers a plan via
+ * `setProgressivePlan(plotId, plan)`; the plugin aggregates them, computes a
+ * single per-tick budget, and ramps a global "rounds" counter — one round
+ * adds one batch in every registered series at once.
+ */
+export const useProgressiveRendering = ({
+  store
+}) => {
+  const registerProgressivePlan = useEventCallback((plotId, seriesIds, renderer) => {
+    if (!selectorShouldUseProgressiveRenderer(store.state, seriesIds, renderer)) {
+      return undefined;
+    }
+    const current = store.state.progressiveRendering.plans.get(plotId);
+    if (!sameSeriesIds(current, seriesIds)) {
+      const nextPlans = new Map(store.state.progressiveRendering.plans);
+      nextPlans.set(plotId, seriesIds);
+      // A real plan change restarts the progressive paint.
+      store.set('progressiveRendering', {
+        plans: nextPlans,
+        revealedRounds: 0
+      });
+    }
+    return () => {
+      if (!store.state.progressiveRendering.plans.has(plotId)) {
+        return;
+      }
+      const nextPlans = new Map(store.state.progressiveRendering.plans);
+      nextPlans.delete(plotId);
+      store.set('progressiveRendering', _extends({}, store.state.progressiveRendering, {
+        plans: nextPlans
+      }));
+    };
+  });
+  const plans = store.use(selectorProgressivePlans) ?? EMPTY_PLANS;
+  React.useEffect(() => {
+    const startTotal = selectorProgressiveTotalRounds(store.state);
+    if (startTotal === 0) {
+      return undefined;
+    }
+    if (typeof requestAnimationFrame !== 'function') {
+      store.set('progressiveRendering', _extends({}, store.state.progressiveRendering, {
+        revealedRounds: startTotal
+      }));
+      return undefined;
+    }
+    let frame = 0;
+    let cancelled = false;
+    // Tracked in a closure variable, not derived inside a state updater (those
+    // must be pure and StrictMode double-invokes them, which would schedule
+    // the animation-frame chain twice).
+    let revealed = 0;
+    function scheduleNext() {
+      let remaining = REVEAL_FRAMES_SKIPPED;
+      const tick = () => {
+        if (cancelled) {
+          return;
+        }
+        if (remaining > 0) {
+          remaining -= 1;
+          frame = requestAnimationFrame(tick);
+          return;
+        }
+        step();
+      };
+      frame = requestAnimationFrame(tick);
+    }
+    function step() {
+      if (cancelled) {
+        return;
+      }
+      const total = selectorProgressiveTotalRounds(store.state);
+      revealed = Math.min(total, revealed + REVEAL_ROUNDS_PER_FRAME);
+      store.set('progressiveRendering', _extends({}, store.state.progressiveRendering, {
+        revealedRounds: revealed
+      }));
+      if (revealed < total) {
+        scheduleNext();
+      }
+    }
+    frame = requestAnimationFrame(step);
+    return () => {
+      cancelled = true;
+      cancelAnimationFrame(frame);
+    };
+  }, [plans, store]);
+  return {
+    instance: {
+      registerProgressivePlan
+    }
+  };
+};
+useProgressiveRendering.params = {};
+useProgressiveRendering.getInitialState = () => ({
+  progressiveRendering: {
+    plans: EMPTY_PLANS,
+    revealedRounds: 0
+  }
+});

package/internals/plugins/featurePlugins/useProgressiveRendering/useProgressiveRendering.selectors.d.mts

@@ -0,0 +1,42 @@
+import { type SeriesId } from "../../../../models/seriesType/common.mjs";
+import type { RendererType } from "../../../../ScatterChart/index.mjs";
+/** Map of registered plots → their set of series ids. */
+export declare const selectorProgressivePlans: (args_0: import("../../corePlugins/useChartId/useChartId.types.mjs").UseChartIdState & import("../../corePlugins/useChartSeriesConfig/useChartSeriesConfig.types.mjs").UseChartSeriesConfigState<keyof import("../../../index.mjs").ChartsSeriesConfig> & import("../../corePlugins/useChartExperimentalFeature/useChartExperimentalFeature.types.mjs").UseChartExperimentalFeaturesState & import("../../corePlugins/useChartDimensions/useChartDimensions.types.mjs").UseChartDimensionsState & import("../../corePlugins/useChartSeries/useChartSeries.types.mjs").UseChartSeriesState<keyof import("../../../index.mjs").ChartsSeriesConfig> & import("../../corePlugins/useChartAnimation/useChartAnimation.types.mjs").UseChartAnimationState & import("../../../index.mjs").UseChartInteractionListenerState & Partial<import("./useProgressiveRendering.types.mjs").UseProgressiveRenderingState> & {
+  cacheKey: import("../../models/index.mjs").ChartStateCacheKey;
+}) => ReadonlyMap<string, readonly string[]> | undefined;
+/** Total number of rounds revealed across all plots so far. */
+export declare const selectorProgressiveRevealedRounds: (args_0: import("../../corePlugins/useChartId/useChartId.types.mjs").UseChartIdState & import("../../corePlugins/useChartSeriesConfig/useChartSeriesConfig.types.mjs").UseChartSeriesConfigState<keyof import("../../../index.mjs").ChartsSeriesConfig> & import("../../corePlugins/useChartExperimentalFeature/useChartExperimentalFeature.types.mjs").UseChartExperimentalFeaturesState & import("../../corePlugins/useChartDimensions/useChartDimensions.types.mjs").UseChartDimensionsState & import("../../corePlugins/useChartSeries/useChartSeries.types.mjs").UseChartSeriesState<keyof import("../../../index.mjs").ChartsSeriesConfig> & import("../../corePlugins/useChartAnimation/useChartAnimation.types.mjs").UseChartAnimationState & import("../../../index.mjs").UseChartInteractionListenerState & Partial<import("./useProgressiveRendering.types.mjs").UseProgressiveRenderingState> & {
+  cacheKey: import("../../models/index.mjs").ChartStateCacheKey;
+}) => number;
+/**
+ * Aggregated view of every registered plan: the per-series batch counts, the
+ * total number of rounds, and the per-series batch size (so every consumer
+ * sizes its batches the same way). Point counts are read straight from the
+ * processed series rather than carried by the registration.
+ */
+export declare const selectorProgressiveAggregate: (args_0: import("../../corePlugins/useChartId/useChartId.types.mjs").UseChartIdState & import("../../corePlugins/useChartSeriesConfig/useChartSeriesConfig.types.mjs").UseChartSeriesConfigState<keyof import("../../../index.mjs").ChartsSeriesConfig> & import("../../corePlugins/useChartExperimentalFeature/useChartExperimentalFeature.types.mjs").UseChartExperimentalFeaturesState & import("../../corePlugins/useChartDimensions/useChartDimensions.types.mjs").UseChartDimensionsState & import("../../corePlugins/useChartSeries/useChartSeries.types.mjs").UseChartSeriesState<keyof import("../../../index.mjs").ChartsSeriesConfig> & import("../../corePlugins/useChartAnimation/useChartAnimation.types.mjs").UseChartAnimationState & import("../../../index.mjs").UseChartInteractionListenerState & Partial<import("./useProgressiveRendering.types.mjs").UseProgressiveRenderingState> & {
+  cacheKey: import("../../models/index.mjs").ChartStateCacheKey;
+}) => {
+  nBatchesBySeries: Map<string, number>;
+  totalRounds: number;
+  batchSize: number;
+};
+export declare const selectorProgressiveBatchSize: (args_0: import("../../corePlugins/useChartId/useChartId.types.mjs").UseChartIdState & import("../../corePlugins/useChartSeriesConfig/useChartSeriesConfig.types.mjs").UseChartSeriesConfigState<keyof import("../../../index.mjs").ChartsSeriesConfig> & import("../../corePlugins/useChartExperimentalFeature/useChartExperimentalFeature.types.mjs").UseChartExperimentalFeaturesState & import("../../corePlugins/useChartDimensions/useChartDimensions.types.mjs").UseChartDimensionsState & import("../../corePlugins/useChartSeries/useChartSeries.types.mjs").UseChartSeriesState<keyof import("../../../index.mjs").ChartsSeriesConfig> & import("../../corePlugins/useChartAnimation/useChartAnimation.types.mjs").UseChartAnimationState & import("../../../index.mjs").UseChartInteractionListenerState & Partial<import("./useProgressiveRendering.types.mjs").UseProgressiveRenderingState> & {
+  cacheKey: import("../../models/index.mjs").ChartStateCacheKey;
+}) => number;
+export declare const selectorProgressiveTotalRounds: (args_0: import("../../corePlugins/useChartId/useChartId.types.mjs").UseChartIdState & import("../../corePlugins/useChartSeriesConfig/useChartSeriesConfig.types.mjs").UseChartSeriesConfigState<keyof import("../../../index.mjs").ChartsSeriesConfig> & import("../../corePlugins/useChartExperimentalFeature/useChartExperimentalFeature.types.mjs").UseChartExperimentalFeaturesState & import("../../corePlugins/useChartDimensions/useChartDimensions.types.mjs").UseChartDimensionsState & import("../../corePlugins/useChartSeries/useChartSeries.types.mjs").UseChartSeriesState<keyof import("../../../index.mjs").ChartsSeriesConfig> & import("../../corePlugins/useChartAnimation/useChartAnimation.types.mjs").UseChartAnimationState & import("../../../index.mjs").UseChartInteractionListenerState & Partial<import("./useProgressiveRendering.types.mjs").UseProgressiveRenderingState> & {
+  cacheKey: import("../../models/index.mjs").ChartStateCacheKey;
+}) => number;
+/**
+ * How many of `seriesId`'s own batches are revealed so far. Capped at that
+ * series' total batch count, so series with fewer batches simply stop
+ * progressing while longer ones keep filling in.
+ */
+export declare const selectorProgressiveSeriesRevealedBatches: (args_0: import("../../corePlugins/useChartId/useChartId.types.mjs").UseChartIdState & import("../../corePlugins/useChartSeriesConfig/useChartSeriesConfig.types.mjs").UseChartSeriesConfigState<keyof import("../../../index.mjs").ChartsSeriesConfig> & import("../../corePlugins/useChartExperimentalFeature/useChartExperimentalFeature.types.mjs").UseChartExperimentalFeaturesState & import("../../corePlugins/useChartDimensions/useChartDimensions.types.mjs").UseChartDimensionsState & import("../../corePlugins/useChartSeries/useChartSeries.types.mjs").UseChartSeriesState<keyof import("../../../index.mjs").ChartsSeriesConfig> & import("../../corePlugins/useChartAnimation/useChartAnimation.types.mjs").UseChartAnimationState & import("../../../index.mjs").UseChartInteractionListenerState & Partial<import("./useProgressiveRendering.types.mjs").UseProgressiveRenderingState> & {
+  cacheKey: import("../../models/index.mjs").ChartStateCacheKey;
+}, seriesId: string) => number;
+export declare const selectorShouldUseProgressiveRenderer: (args_0: import("../../corePlugins/useChartId/useChartId.types.mjs").UseChartIdState & import("../../corePlugins/useChartSeriesConfig/useChartSeriesConfig.types.mjs").UseChartSeriesConfigState<keyof import("../../../index.mjs").ChartsSeriesConfig> & import("../../corePlugins/useChartExperimentalFeature/useChartExperimentalFeature.types.mjs").UseChartExperimentalFeaturesState & import("../../corePlugins/useChartDimensions/useChartDimensions.types.mjs").UseChartDimensionsState & import("../../corePlugins/useChartSeries/useChartSeries.types.mjs").UseChartSeriesState<keyof import("../../../index.mjs").ChartsSeriesConfig> & import("../../corePlugins/useChartAnimation/useChartAnimation.types.mjs").UseChartAnimationState & import("../../../index.mjs").UseChartInteractionListenerState & Partial<{}> & {
+  cacheKey: import("../../models/index.mjs").ChartStateCacheKey;
+}, seriesIds: readonly string[], renderer: RendererType | "svg-progressive" | undefined) => boolean;
+/** Order-sensitive equality between two registered series-id sets. */
+export declare function sameSeriesIds(a: readonly SeriesId[] | undefined, b: readonly SeriesId[]): boolean;

package/internals/plugins/featurePlugins/useProgressiveRendering/useProgressiveRendering.selectors.d.ts

@@ -0,0 +1,42 @@
+import { type SeriesId } from "../../../../models/seriesType/common.js";
+import type { RendererType } from "../../../../ScatterChart/index.js";
+/** Map of registered plots → their set of series ids. */
+export declare const selectorProgressivePlans: (args_0: import("../../corePlugins/useChartId/useChartId.types.js").UseChartIdState & import("../../corePlugins/useChartSeriesConfig/useChartSeriesConfig.types.js").UseChartSeriesConfigState<keyof import("../../../index.js").ChartsSeriesConfig> & import("../../corePlugins/useChartExperimentalFeature/useChartExperimentalFeature.types.js").UseChartExperimentalFeaturesState & import("../../corePlugins/useChartDimensions/useChartDimensions.types.js").UseChartDimensionsState & import("../../corePlugins/useChartSeries/useChartSeries.types.js").UseChartSeriesState<keyof import("../../../index.js").ChartsSeriesConfig> & import("../../corePlugins/useChartAnimation/useChartAnimation.types.js").UseChartAnimationState & import("../../../index.js").UseChartInteractionListenerState & Partial<import("./useProgressiveRendering.types.js").UseProgressiveRenderingState> & {
+  cacheKey: import("../../models/index.js").ChartStateCacheKey;
+}) => ReadonlyMap<string, readonly string[]> | undefined;
+/** Total number of rounds revealed across all plots so far. */
+export declare const selectorProgressiveRevealedRounds: (args_0: import("../../corePlugins/useChartId/useChartId.types.js").UseChartIdState & import("../../corePlugins/useChartSeriesConfig/useChartSeriesConfig.types.js").UseChartSeriesConfigState<keyof import("../../../index.js").ChartsSeriesConfig> & import("../../corePlugins/useChartExperimentalFeature/useChartExperimentalFeature.types.js").UseChartExperimentalFeaturesState & import("../../corePlugins/useChartDimensions/useChartDimensions.types.js").UseChartDimensionsState & import("../../corePlugins/useChartSeries/useChartSeries.types.js").UseChartSeriesState<keyof import("../../../index.js").ChartsSeriesConfig> & import("../../corePlugins/useChartAnimation/useChartAnimation.types.js").UseChartAnimationState & import("../../../index.js").UseChartInteractionListenerState & Partial<import("./useProgressiveRendering.types.js").UseProgressiveRenderingState> & {
+  cacheKey: import("../../models/index.js").ChartStateCacheKey;
+}) => number;
+/**
+ * Aggregated view of every registered plan: the per-series batch counts, the
+ * total number of rounds, and the per-series batch size (so every consumer
+ * sizes its batches the same way). Point counts are read straight from the
+ * processed series rather than carried by the registration.
+ */
+export declare const selectorProgressiveAggregate: (args_0: import("../../corePlugins/useChartId/useChartId.types.js").UseChartIdState & import("../../corePlugins/useChartSeriesConfig/useChartSeriesConfig.types.js").UseChartSeriesConfigState<keyof import("../../../index.js").ChartsSeriesConfig> & import("../../corePlugins/useChartExperimentalFeature/useChartExperimentalFeature.types.js").UseChartExperimentalFeaturesState & import("../../corePlugins/useChartDimensions/useChartDimensions.types.js").UseChartDimensionsState & import("../../corePlugins/useChartSeries/useChartSeries.types.js").UseChartSeriesState<keyof import("../../../index.js").ChartsSeriesConfig> & import("../../corePlugins/useChartAnimation/useChartAnimation.types.js").UseChartAnimationState & import("../../../index.js").UseChartInteractionListenerState & Partial<import("./useProgressiveRendering.types.js").UseProgressiveRenderingState> & {
+  cacheKey: import("../../models/index.js").ChartStateCacheKey;
+}) => {
+  nBatchesBySeries: Map<string, number>;
+  totalRounds: number;
+  batchSize: number;
+};
+export declare const selectorProgressiveBatchSize: (args_0: import("../../corePlugins/useChartId/useChartId.types.js").UseChartIdState & import("../../corePlugins/useChartSeriesConfig/useChartSeriesConfig.types.js").UseChartSeriesConfigState<keyof import("../../../index.js").ChartsSeriesConfig> & import("../../corePlugins/useChartExperimentalFeature/useChartExperimentalFeature.types.js").UseChartExperimentalFeaturesState & import("../../corePlugins/useChartDimensions/useChartDimensions.types.js").UseChartDimensionsState & import("../../corePlugins/useChartSeries/useChartSeries.types.js").UseChartSeriesState<keyof import("../../../index.js").ChartsSeriesConfig> & import("../../corePlugins/useChartAnimation/useChartAnimation.types.js").UseChartAnimationState & import("../../../index.js").UseChartInteractionListenerState & Partial<import("./useProgressiveRendering.types.js").UseProgressiveRenderingState> & {
+  cacheKey: import("../../models/index.js").ChartStateCacheKey;
+}) => number;
+export declare const selectorProgressiveTotalRounds: (args_0: import("../../corePlugins/useChartId/useChartId.types.js").UseChartIdState & import("../../corePlugins/useChartSeriesConfig/useChartSeriesConfig.types.js").UseChartSeriesConfigState<keyof import("../../../index.js").ChartsSeriesConfig> & import("../../corePlugins/useChartExperimentalFeature/useChartExperimentalFeature.types.js").UseChartExperimentalFeaturesState & import("../../corePlugins/useChartDimensions/useChartDimensions.types.js").UseChartDimensionsState & import("../../corePlugins/useChartSeries/useChartSeries.types.js").UseChartSeriesState<keyof import("../../../index.js").ChartsSeriesConfig> & import("../../corePlugins/useChartAnimation/useChartAnimation.types.js").UseChartAnimationState & import("../../../index.js").UseChartInteractionListenerState & Partial<import("./useProgressiveRendering.types.js").UseProgressiveRenderingState> & {
+  cacheKey: import("../../models/index.js").ChartStateCacheKey;
+}) => number;
+/**
+ * How many of `seriesId`'s own batches are revealed so far. Capped at that
+ * series' total batch count, so series with fewer batches simply stop
+ * progressing while longer ones keep filling in.
+ */
+export declare const selectorProgressiveSeriesRevealedBatches: (args_0: import("../../corePlugins/useChartId/useChartId.types.js").UseChartIdState & import("../../corePlugins/useChartSeriesConfig/useChartSeriesConfig.types.js").UseChartSeriesConfigState<keyof import("../../../index.js").ChartsSeriesConfig> & import("../../corePlugins/useChartExperimentalFeature/useChartExperimentalFeature.types.js").UseChartExperimentalFeaturesState & import("../../corePlugins/useChartDimensions/useChartDimensions.types.js").UseChartDimensionsState & import("../../corePlugins/useChartSeries/useChartSeries.types.js").UseChartSeriesState<keyof import("../../../index.js").ChartsSeriesConfig> & import("../../corePlugins/useChartAnimation/useChartAnimation.types.js").UseChartAnimationState & import("../../../index.js").UseChartInteractionListenerState & Partial<import("./useProgressiveRendering.types.js").UseProgressiveRenderingState> & {
+  cacheKey: import("../../models/index.js").ChartStateCacheKey;
+}, seriesId: string) => number;
+export declare const selectorShouldUseProgressiveRenderer: (args_0: import("../../corePlugins/useChartId/useChartId.types.js").UseChartIdState & import("../../corePlugins/useChartSeriesConfig/useChartSeriesConfig.types.js").UseChartSeriesConfigState<keyof import("../../../index.js").ChartsSeriesConfig> & import("../../corePlugins/useChartExperimentalFeature/useChartExperimentalFeature.types.js").UseChartExperimentalFeaturesState & import("../../corePlugins/useChartDimensions/useChartDimensions.types.js").UseChartDimensionsState & import("../../corePlugins/useChartSeries/useChartSeries.types.js").UseChartSeriesState<keyof import("../../../index.js").ChartsSeriesConfig> & import("../../corePlugins/useChartAnimation/useChartAnimation.types.js").UseChartAnimationState & import("../../../index.js").UseChartInteractionListenerState & Partial<{}> & {
+  cacheKey: import("../../models/index.js").ChartStateCacheKey;
+}, seriesIds: readonly string[], renderer: RendererType | "svg-progressive" | undefined) => boolean;
+/** Order-sensitive equality between two registered series-id sets. */
+export declare function sameSeriesIds(a: readonly SeriesId[] | undefined, b: readonly SeriesId[]): boolean;