@mui/x-charts-pro 9.8.0 → 9.10.0

package/internals/plugins/useChartProSampling/index.js

@@ -0,0 +1,12 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "useChartProSampling", {
+  enumerable: true,
+  get: function () {
+    return _useChartProSampling.useChartProSampling;
+  }
+});
+var _useChartProSampling = require("./useChartProSampling");

package/internals/plugins/useChartProSampling/index.mjs

@@ -0,0 +1 @@
+export { useChartProSampling } from "./useChartProSampling.mjs";

package/internals/plugins/useChartProSampling/lineSampler.d.mts

@@ -0,0 +1,8 @@
+import type { SamplingStrategy } from '@mui/x-charts/internals';
+import type { SamplingPyramid } from "./sampling.pyramid.types.mjs";
+/**
+ * Min/max LOD pyramid over the line's y values (single channel when null-free). Nulls get `+Inf`
+ * low / `-Inf` high so they never win an extremum, and go into `nullIndices` for the sampler to
+ * re-insert as line breaks.
+ */
+export declare const lineSampler: SamplingStrategy<'line', SamplingPyramid>;

package/internals/plugins/useChartProSampling/lineSampler.d.ts

@@ -0,0 +1,8 @@
+import type { SamplingStrategy } from '@mui/x-charts/internals';
+import type { SamplingPyramid } from "./sampling.pyramid.types.js";
+/**
+ * Min/max LOD pyramid over the line's y values (single channel when null-free). Nulls get `+Inf`
+ * low / `-Inf` high so they never win an extremum, and go into `nullIndices` for the sampler to
+ * re-insert as line breaks.
+ */
+export declare const lineSampler: SamplingStrategy<'line', SamplingPyramid>;

package/internals/plugins/useChartProSampling/lineSampler.js

@@ -0,0 +1,47 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.lineSampler = void 0;
+var _sampling = require("./sampling");
+var _sampling2 = require("./sampling.line");
+/**
+ * Min/max LOD pyramid over the line's y values (single channel when null-free). Nulls get `+Inf`
+ * low / `-Inf` high so they never win an extremum, and go into `nullIndices` for the sampler to
+ * re-insert as line breaks.
+ */
+const lineSampler = exports.lineSampler = {
+  build: series => {
+    const {
+      data,
+      visibleStackedData
+    } = series;
+    const length = visibleStackedData.length;
+    const values = new Float64Array(length);
+    let nullIndices = null;
+    for (let i = 0; i < length; i += 1) {
+      if (data[i] == null) {
+        (nullIndices ?? (nullIndices = [])).push(i);
+      } else {
+        values[i] = visibleStackedData[i][1];
+      }
+    }
+    if (!nullIndices) {
+      return (0, _sampling.buildSamplingPyramid)(values, values);
+    }
+
+    // Two channels only when gaps exist: nulls lose both extrema comparisons.
+    const low = values;
+    const high = Float64Array.from(values);
+    for (let i = 0; i < nullIndices.length; i += 1) {
+      low[nullIndices[i]] = Infinity;
+      high[nullIndices[i]] = -Infinity;
+    }
+    const pyramid = (0, _sampling.buildSamplingPyramid)(low, high);
+    pyramid.nullIndices = Int32Array.from(nullIndices);
+    return pyramid;
+  },
+  sample: _sampling2.sample,
+  bucketSizeAt: (span, context) => (0, _sampling.getSamplingBucketSize)(span, context.dataLength, context.availableSize, context.minSpan)
+};

package/internals/plugins/useChartProSampling/lineSampler.mjs

@@ -0,0 +1,41 @@
+import { buildSamplingPyramid, getSamplingBucketSize } from "./sampling.mjs";
+import { sample } from "./sampling.line.mjs";
+/**
+ * Min/max LOD pyramid over the line's y values (single channel when null-free). Nulls get `+Inf`
+ * low / `-Inf` high so they never win an extremum, and go into `nullIndices` for the sampler to
+ * re-insert as line breaks.
+ */
+export const lineSampler = {
+  build: series => {
+    const {
+      data,
+      visibleStackedData
+    } = series;
+    const length = visibleStackedData.length;
+    const values = new Float64Array(length);
+    let nullIndices = null;
+    for (let i = 0; i < length; i += 1) {
+      if (data[i] == null) {
+        (nullIndices ??= []).push(i);
+      } else {
+        values[i] = visibleStackedData[i][1];
+      }
+    }
+    if (!nullIndices) {
+      return buildSamplingPyramid(values, values);
+    }
+
+    // Two channels only when gaps exist: nulls lose both extrema comparisons.
+    const low = values;
+    const high = Float64Array.from(values);
+    for (let i = 0; i < nullIndices.length; i += 1) {
+      low[nullIndices[i]] = Infinity;
+      high[nullIndices[i]] = -Infinity;
+    }
+    const pyramid = buildSamplingPyramid(low, high);
+    pyramid.nullIndices = Int32Array.from(nullIndices);
+    return pyramid;
+  },
+  sample,
+  bucketSizeAt: (span, context) => getSamplingBucketSize(span, context.dataLength, context.availableSize, context.minSpan)
+};

package/internals/plugins/useChartProSampling/sampling.d.mts

@@ -0,0 +1,38 @@
+import type { ActiveSamplingLevel, SamplingPyramid } from "./sampling.pyramid.types.mjs";
+/** Smallest element size (px) allowed before sampling kicks in. */
+export declare const MIN_ELEMENT_SIZE_PX = 6;
+/**
+ * Min zoom span (%) at which the data fills the view with `MIN_ELEMENT_SIZE_PX`-wide elements.
+ * Screen-derived, so elements never get thinner and the level count adapts to screen + data.
+ */
+export declare function getSamplingMinSpan(dataLength: number, availableSizePx: number): number;
+/**
+ * Hard ceiling on rendered elements, independent of zoom. Even at the deepest zoom (where elements
+ * would be wide enough to skip screen sampling), a view with more than this many points is still
+ * sampled enough levels to get under the cap — too many elements hurts performance whatever the size.
+ */
+export declare const MAX_RENDERED_POINTS = 2000;
+/**
+ * Builds the LOD pyramid for one series from its low/high value channels (for bars: the stacked
+ * `[base, top]` channels; for lines: the displayed `y` for both). Each bucket keeps the original
+ * index of its min (over `low`) and max (over `high`) — a min/max envelope, so spikes and troughs
+ * survive. Consumers read the values back from their own series data by index.
+ *
+ * Stored flat: all levels concatenated into `argMin`/`argMax`, with `offsets` marking level
+ * boundaries. Level 0 (no merge) is implicit; bucket indices are derived (`j * bucketSize`).
+ */
+export declare function buildSamplingPyramid(low: ArrayLike<number>, high: ArrayLike<number>): SamplingPyramid;
+/** Number of stored levels (finest `bucketSize 2` to coarsest). */
+export declare function getSamplingLevelCount(pyramid: SamplingPyramid): number;
+/**
+ * Picks the active level from the zoom span: level 0 (deepest zoom, `span <= minSpan`, or elements
+ * still wide enough) → no sampling (`null`, raw 1:1); each level up → bucket size ×2, chosen so
+ * sampled elements stay at least `MIN_ELEMENT_SIZE_PX` wide. Clamped to the pyramid depth.
+ * `bucketSize === 2 ** clampedLevel`, level buckets `offsets[clampedLevel - 1 .. clampedLevel]`.
+ */
+export declare function selectSamplingLevel(pyramid: SamplingPyramid, currentSpan: number, availableSizePx: number, minSpan: number): ActiveSamplingLevel | null;
+/**
+ * Active bucket size (`1` = no sampling) for an axis with no built pyramid (the axis highlight).
+ * Matches `selectSamplingLevel`'s `bucketSize`, derived from `dataLength` + screen + `minSpan`.
+ */
+export declare function getSamplingBucketSize(currentSpan: number, dataLength: number, availableSizePx: number, minSpan: number): number;

package/internals/plugins/useChartProSampling/sampling.d.ts

@@ -0,0 +1,38 @@
+import type { ActiveSamplingLevel, SamplingPyramid } from "./sampling.pyramid.types.js";
+/** Smallest element size (px) allowed before sampling kicks in. */
+export declare const MIN_ELEMENT_SIZE_PX = 6;
+/**
+ * Min zoom span (%) at which the data fills the view with `MIN_ELEMENT_SIZE_PX`-wide elements.
+ * Screen-derived, so elements never get thinner and the level count adapts to screen + data.
+ */
+export declare function getSamplingMinSpan(dataLength: number, availableSizePx: number): number;
+/**
+ * Hard ceiling on rendered elements, independent of zoom. Even at the deepest zoom (where elements
+ * would be wide enough to skip screen sampling), a view with more than this many points is still
+ * sampled enough levels to get under the cap — too many elements hurts performance whatever the size.
+ */
+export declare const MAX_RENDERED_POINTS = 2000;
+/**
+ * Builds the LOD pyramid for one series from its low/high value channels (for bars: the stacked
+ * `[base, top]` channels; for lines: the displayed `y` for both). Each bucket keeps the original
+ * index of its min (over `low`) and max (over `high`) — a min/max envelope, so spikes and troughs
+ * survive. Consumers read the values back from their own series data by index.
+ *
+ * Stored flat: all levels concatenated into `argMin`/`argMax`, with `offsets` marking level
+ * boundaries. Level 0 (no merge) is implicit; bucket indices are derived (`j * bucketSize`).
+ */
+export declare function buildSamplingPyramid(low: ArrayLike<number>, high: ArrayLike<number>): SamplingPyramid;
+/** Number of stored levels (finest `bucketSize 2` to coarsest). */
+export declare function getSamplingLevelCount(pyramid: SamplingPyramid): number;
+/**
+ * Picks the active level from the zoom span: level 0 (deepest zoom, `span <= minSpan`, or elements
+ * still wide enough) → no sampling (`null`, raw 1:1); each level up → bucket size ×2, chosen so
+ * sampled elements stay at least `MIN_ELEMENT_SIZE_PX` wide. Clamped to the pyramid depth.
+ * `bucketSize === 2 ** clampedLevel`, level buckets `offsets[clampedLevel - 1 .. clampedLevel]`.
+ */
+export declare function selectSamplingLevel(pyramid: SamplingPyramid, currentSpan: number, availableSizePx: number, minSpan: number): ActiveSamplingLevel | null;
+/**
+ * Active bucket size (`1` = no sampling) for an axis with no built pyramid (the axis highlight).
+ * Matches `selectSamplingLevel`'s `bucketSize`, derived from `dataLength` + screen + `minSpan`.
+ */
+export declare function getSamplingBucketSize(currentSpan: number, dataLength: number, availableSizePx: number, minSpan: number): number;

package/internals/plugins/useChartProSampling/sampling.js

@@ -0,0 +1,175 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.MIN_ELEMENT_SIZE_PX = exports.MAX_RENDERED_POINTS = void 0;
+exports.buildSamplingPyramid = buildSamplingPyramid;
+exports.getSamplingBucketSize = getSamplingBucketSize;
+exports.getSamplingLevelCount = getSamplingLevelCount;
+exports.getSamplingMinSpan = getSamplingMinSpan;
+exports.selectSamplingLevel = selectSamplingLevel;
+/** Smallest element size (px) allowed before sampling kicks in. */
+const MIN_ELEMENT_SIZE_PX = exports.MIN_ELEMENT_SIZE_PX = 6;
+
+/**
+ * Min zoom span (%) at which the data fills the view with `MIN_ELEMENT_SIZE_PX`-wide elements.
+ * Screen-derived, so elements never get thinner and the level count adapts to screen + data.
+ */
+function getSamplingMinSpan(dataLength, availableSizePx) {
+  return 100 * availableSizePx / (MIN_ELEMENT_SIZE_PX * dataLength);
+}
+const EMPTY_PYRAMID_OFFSETS = new Int32Array(1);
+
+/**
+ * Level 0 (raw) extends this factor above `minSpan` before the first sampled level kicks in — a
+ * half-octave of wiggle room so the deepest zoom stays unsampled without a knife-edge transition.
+ */
+const RAW_LEVEL_SPAN_FACTOR = Math.SQRT2;
+
+/**
+ * Hard ceiling on rendered elements, independent of zoom. Even at the deepest zoom (where elements
+ * would be wide enough to skip screen sampling), a view with more than this many points is still
+ * sampled enough levels to get under the cap — too many elements hurts performance whatever the size.
+ */
+const MAX_RENDERED_POINTS = exports.MAX_RENDERED_POINTS = 2000;
+
+/** Levels of sampling needed to bring `visiblePoints` under `MAX_RENDERED_POINTS` (0 if under). */
+function pointCapLevel(visiblePoints) {
+  return visiblePoints > MAX_RENDERED_POINTS ? Math.ceil(Math.log2(visiblePoints / MAX_RENDERED_POINTS)) : 0;
+}
+
+/**
+ * Builds the LOD pyramid for one series from its low/high value channels (for bars: the stacked
+ * `[base, top]` channels; for lines: the displayed `y` for both). Each bucket keeps the original
+ * index of its min (over `low`) and max (over `high`) — a min/max envelope, so spikes and troughs
+ * survive. Consumers read the values back from their own series data by index.
+ *
+ * Stored flat: all levels concatenated into `argMin`/`argMax`, with `offsets` marking level
+ * boundaries. Level 0 (no merge) is implicit; bucket indices are derived (`j * bucketSize`).
+ */
+function buildSamplingPyramid(low, high) {
+  const dataLength = low.length;
+  if (dataLength <= 1) {
+    return {
+      dataLength,
+      argMin: new Int32Array(0),
+      argMax: new Int32Array(0),
+      offsets: EMPTY_PYRAMID_OFFSETS
+    };
+  }
+  const levelCount = Math.ceil(Math.log2(dataLength));
+
+  // Level start offsets into the shared buffers; each level halves the previous count (round up).
+  const offsets = new Int32Array(levelCount + 1);
+  for (let levelIndex = 0, count = dataLength; levelIndex < levelCount; levelIndex += 1) {
+    count = Math.ceil(count / 2);
+    offsets[levelIndex + 1] = offsets[levelIndex] + count;
+  }
+  const argMin = new Int32Array(offsets[levelCount]);
+  const argMax = new Int32Array(offsets[levelCount]);
+
+  // Level 0 (bucketSize 2) merges adjacent raw points; the only level that scans raw data.
+  for (let j = 0, i = 0; i < dataLength; j += 1, i += 2) {
+    const next = i + 1;
+    let lo = i;
+    let hi = i;
+    if (next < dataLength) {
+      if (low[next] < low[i]) {
+        lo = next;
+      }
+      if (high[next] > high[i]) {
+        hi = next;
+      }
+    }
+    argMin[j] = lo;
+    argMax[j] = hi;
+  }
+
+  // Higher levels merge pairs of buckets from the level below (argMin/argMax are associative via
+  // value compare, so the result equals re-scanning raw data). n/2 + n/4 + ... → O(n) build.
+  for (let levelIndex = 1; levelIndex < levelCount; levelIndex += 1) {
+    const prevStart = offsets[levelIndex - 1];
+    const prevCount = offsets[levelIndex] - prevStart;
+    const start = offsets[levelIndex];
+    for (let i = 0, j = 0; i < prevCount; i += 2, j += 1) {
+      const a = prevStart + i;
+      const w = start + j;
+      if (i + 1 >= prevCount) {
+        argMin[w] = argMin[a];
+        argMax[w] = argMax[a];
+      } else {
+        const b = a + 1;
+        argMin[w] = low[argMin[a]] <= low[argMin[b]] ? argMin[a] : argMin[b];
+        argMax[w] = high[argMax[a]] >= high[argMax[b]] ? argMax[a] : argMax[b];
+      }
+    }
+  }
+  return {
+    dataLength,
+    argMin,
+    argMax,
+    offsets
+  };
+}
+
+/** Number of stored levels (finest `bucketSize 2` to coarsest). */
+function getSamplingLevelCount(pyramid) {
+  return pyramid.offsets.length - 1;
+}
+
+/**
+ * Level-of-detail index for the current zoom:
+ * - Level 0 (no sampling, raw) at the deepest zoom (`currentSpan <= minSpan * RAW_LEVEL_SPAN_FACTOR`),
+ *   whatever the bar size — fully zoomed in shows every point, up to `MAX_RENDERED_POINTS`.
+ * - Above that, the level is screen-defined: bucket size keeps elements at least
+ *   `MIN_ELEMENT_SIZE_PX` wide (+1 per span doubling past that pixel threshold).
+ * - The `MAX_RENDERED_POINTS` cap applies at every zoom: a view with too many points is always
+ *   sampled, even in the raw zone where the screen rule alone would render it untouched.
+ */
+function levelIndexFor(currentSpan, dataLength, availableSizePx, minSpan) {
+  if (!(currentSpan > 0)) {
+    return 0;
+  }
+  const capLevel = pointCapLevel(dataLength * Math.min(currentSpan, 100) / 100);
+  if (currentSpan <= minSpan * RAW_LEVEL_SPAN_FACTOR) {
+    return capLevel; // raw zone, but still bounded by the point cap
+  }
+  const screenMinSpan = getSamplingMinSpan(dataLength, availableSizePx);
+  if (!(screenMinSpan > 0)) {
+    return capLevel;
+  }
+  return Math.max(capLevel, Math.round(Math.log2(currentSpan / screenMinSpan)));
+}
+
+/**
+ * Picks the active level from the zoom span: level 0 (deepest zoom, `span <= minSpan`, or elements
+ * still wide enough) → no sampling (`null`, raw 1:1); each level up → bucket size ×2, chosen so
+ * sampled elements stay at least `MIN_ELEMENT_SIZE_PX` wide. Clamped to the pyramid depth.
+ * `bucketSize === 2 ** clampedLevel`, level buckets `offsets[clampedLevel - 1 .. clampedLevel]`.
+ */
+function selectSamplingLevel(pyramid, currentSpan, availableSizePx, minSpan) {
+  const levelCount = pyramid.offsets.length - 1;
+  const levelIndex = levelIndexFor(currentSpan, pyramid.dataLength, availableSizePx, minSpan);
+  if (levelIndex <= 0 || levelCount === 0) {
+    return null;
+  }
+  const clampedLevel = Math.min(levelIndex, levelCount);
+  return {
+    bucketSize: 2 ** clampedLevel,
+    start: pyramid.offsets[clampedLevel - 1],
+    end: pyramid.offsets[clampedLevel]
+  };
+}
+
+/**
+ * Active bucket size (`1` = no sampling) for an axis with no built pyramid (the axis highlight).
+ * Matches `selectSamplingLevel`'s `bucketSize`, derived from `dataLength` + screen + `minSpan`.
+ */
+function getSamplingBucketSize(currentSpan, dataLength, availableSizePx, minSpan) {
+  const levelIndex = levelIndexFor(currentSpan, dataLength, availableSizePx, minSpan);
+  if (levelIndex <= 0 || dataLength <= 1) {
+    return 1;
+  }
+  return 2 ** Math.min(levelIndex, Math.ceil(Math.log2(dataLength)));
+}

package/internals/plugins/useChartProSampling/sampling.line.d.mts

@@ -0,0 +1,22 @@
+import type { LineSamplingAlgorithm, SampleContext, SampledBucket } from '@mui/x-charts/internals';
+import type { SamplingPyramid } from "./sampling.pyramid.types.mjs";
+/**
+ * The active level of detail as buckets for the current zoom, or `null` for no sampling. Each bucket
+ * carries its original-index span plus the ascending indices to render. The same output feeds both
+ * series types: lines flatten the indices into a polyline, bars draw one merged rect per bucket.
+ *
+ * `minmax` (default; bars use it) keeps {min, max} per bucket; `m4` also brackets them with the
+ * bucket's first/last (pixel-accurate); both read the shared `SamplingPyramid`. `lttb` ignores
+ * the pyramid and reduces on demand, reading raw values from `getValues` (called only for `lttb`)
+ * as a single whole-range bucket. Its budget matches the envelope methods' point density so it
+ * isn't visually sparser at the same zoom.
+ */
+export declare function sampleBuckets(pyramid: SamplingPyramid, currentSpan: number, availableSizePx: number, minSpan: number, algorithm?: LineSamplingAlgorithm, getValues?: () => ArrayLike<number>): SampledBucket[] | null;
+/** Shared `sample` for every series type; the per-type build feeds the channels into the pyramid. */
+export declare function sample(context: SampleContext): SampledBucket[] | null;
+/**
+ * Largest-Triangle-Three-Buckets downsampling. Returns `threshold` original indices (including the
+ * first and last) chosen to preserve the line's visual shape. Uses the data index as the x channel.
+ * @see https://skemman.is/handle/1946/15343 (Sveinn Steinarsson, 2013)
+ */
+export declare function largestTriangleThreeBuckets(values: ArrayLike<number>, threshold: number): Int32Array;

package/internals/plugins/useChartProSampling/sampling.line.d.ts

@@ -0,0 +1,22 @@
+import type { LineSamplingAlgorithm, SampleContext, SampledBucket } from '@mui/x-charts/internals';
+import type { SamplingPyramid } from "./sampling.pyramid.types.js";
+/**
+ * The active level of detail as buckets for the current zoom, or `null` for no sampling. Each bucket
+ * carries its original-index span plus the ascending indices to render. The same output feeds both
+ * series types: lines flatten the indices into a polyline, bars draw one merged rect per bucket.
+ *
+ * `minmax` (default; bars use it) keeps {min, max} per bucket; `m4` also brackets them with the
+ * bucket's first/last (pixel-accurate); both read the shared `SamplingPyramid`. `lttb` ignores
+ * the pyramid and reduces on demand, reading raw values from `getValues` (called only for `lttb`)
+ * as a single whole-range bucket. Its budget matches the envelope methods' point density so it
+ * isn't visually sparser at the same zoom.
+ */
+export declare function sampleBuckets(pyramid: SamplingPyramid, currentSpan: number, availableSizePx: number, minSpan: number, algorithm?: LineSamplingAlgorithm, getValues?: () => ArrayLike<number>): SampledBucket[] | null;
+/** Shared `sample` for every series type; the per-type build feeds the channels into the pyramid. */
+export declare function sample(context: SampleContext): SampledBucket[] | null;
+/**
+ * Largest-Triangle-Three-Buckets downsampling. Returns `threshold` original indices (including the
+ * first and last) chosen to preserve the line's visual shape. Uses the data index as the x channel.
+ * @see https://skemman.is/handle/1946/15343 (Sveinn Steinarsson, 2013)
+ */
+export declare function largestTriangleThreeBuckets(values: ArrayLike<number>, threshold: number): Int32Array;

package/internals/plugins/useChartProSampling/sampling.line.js

@@ -0,0 +1,172 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.largestTriangleThreeBuckets = largestTriangleThreeBuckets;
+exports.sample = sample;
+exports.sampleBuckets = sampleBuckets;
+var _sampling = require("./sampling");
+/** Points the `minmax` envelope renders per bucket (min, max). Used to align the `lttb` budget. */
+const ENVELOPE_POINTS_PER_BUCKET = 2;
+
+/**
+ * The active level of detail as buckets for the current zoom, or `null` for no sampling. Each bucket
+ * carries its original-index span plus the ascending indices to render. The same output feeds both
+ * series types: lines flatten the indices into a polyline, bars draw one merged rect per bucket.
+ *
+ * `minmax` (default; bars use it) keeps {min, max} per bucket; `m4` also brackets them with the
+ * bucket's first/last (pixel-accurate); both read the shared `SamplingPyramid`. `lttb` ignores
+ * the pyramid and reduces on demand, reading raw values from `getValues` (called only for `lttb`)
+ * as a single whole-range bucket. Its budget matches the envelope methods' point density so it
+ * isn't visually sparser at the same zoom.
+ */
+function sampleBuckets(pyramid, currentSpan, availableSizePx, minSpan, algorithm = 'minmax', getValues) {
+  const level = (0, _sampling.selectSamplingLevel)(pyramid, currentSpan, availableSizePx, minSpan);
+  if (!level) {
+    return null;
+  }
+  const {
+    bucketSize,
+    start,
+    end
+  } = level;
+  const {
+    nullIndices
+  } = pyramid;
+  const maxIndex = pyramid.dataLength - 1;
+  const nullLength = nullIndices?.length ?? 0;
+
+  // Builds one bucket's render indices: the ascending `candidates` (extrema/ends or the lttb points)
+  // with this bucket's null indices merged in, deduped, so the line breaks at gaps. `nullCursor`
+  // advances monotonically since buckets partition `[0, maxIndex]` left to right.
+  let nullCursor = 0;
+  const mergeBucket = (candidates, endIndex) => {
+    const indices = [];
+    let c = 0;
+    while (c < candidates.length || nullCursor < nullLength && nullIndices[nullCursor] <= endIndex) {
+      const nextCandidate = c < candidates.length ? candidates[c] : Infinity;
+      const nextNull = nullCursor < nullLength && nullIndices[nullCursor] <= endIndex ? nullIndices[nullCursor] : Infinity;
+      const next = Math.min(nextCandidate, nextNull);
+      if (indices[indices.length - 1] !== next) {
+        indices.push(next);
+      }
+      if (next === nextCandidate) {
+        c += 1;
+      }
+      if (next === nextNull) {
+        nullCursor += 1;
+      }
+    }
+    return Int32Array.from(indices);
+  };
+  if (algorithm === 'lttb') {
+    // LTTB emits one point per bucket, vs `ENVELOPE_POINTS_PER_BUCKET` for the min/max methods.
+    // Scale the budget by that factor so LTTB isn't sparser than them at the same zoom.
+    const indices = largestTriangleThreeBuckets(getValues(), Math.ceil(ENVELOPE_POINTS_PER_BUCKET * pyramid.dataLength / bucketSize));
+    return [{
+      startIndex: 0,
+      endIndex: maxIndex,
+      indices: mergeBucket(indices, maxIndex)
+    }];
+  }
+  const {
+    argMin,
+    argMax
+  } = pyramid;
+  const withEnds = algorithm === 'm4';
+  const buckets = [];
+  for (let j = start; j < end; j += 1) {
+    const bucket = j - start;
+    const startIndex = bucket * bucketSize;
+    const endIndex = Math.min(startIndex + bucketSize - 1, maxIndex);
+    // Extrema in ascending index order; `m4` also brackets them with the bucket's first/last.
+    const extremaFirst = Math.min(argMin[j], argMax[j]);
+    const extremaLast = Math.max(argMin[j], argMax[j]);
+    const candidates = withEnds ? [startIndex, extremaFirst, extremaLast, endIndex] : [extremaFirst, extremaLast];
+    buckets.push({
+      startIndex,
+      endIndex,
+      indices: mergeBucket(candidates, endIndex)
+    });
+  }
+  return buckets;
+}
+
+/** Shared `sample` for every series type; the per-type build feeds the channels into the pyramid. */
+function sample(context) {
+  const {
+    zoom
+  } = context;
+  if (!zoom) {
+    return null;
+  }
+  return sampleBuckets(context.built, zoom.end - zoom.start, context.availableSize, context.minSpan, context.algorithm, context.getValues);
+}
+
+/**
+ * Largest-Triangle-Three-Buckets downsampling. Returns `threshold` original indices (including the
+ * first and last) chosen to preserve the line's visual shape. Uses the data index as the x channel.
+ * @see https://skemman.is/handle/1946/15343 (Sveinn Steinarsson, 2013)
+ */
+function largestTriangleThreeBuckets(values, threshold) {
+  const dataLength = values.length;
+  if (threshold >= dataLength) {
+    return Int32Array.from({
+      length: dataLength
+    }, (_, i) => i);
+  }
+  if (threshold <= 2) {
+    // Keep just the endpoints; returning every index here would bypass the rendered-point cap.
+    return Int32Array.from([0, dataLength - 1]);
+  }
+  const sampled = new Int32Array(threshold);
+  let sampledIndex = 0;
+  sampled[sampledIndex] = 0; // always keep the first point
+  sampledIndex += 1;
+
+  // Middle buckets span indices [1, dataLength - 1); the last point is fixed separately.
+  const bucketSize = (dataLength - 2) / (threshold - 2);
+  let a = 0; // index of the previously selected point
+
+  for (let i = 0; i < threshold - 2; i += 1) {
+    // Average point of the next bucket (the third triangle vertex).
+    const avgStart = Math.floor((i + 1) * bucketSize) + 1;
+    let avgEnd = Math.floor((i + 2) * bucketSize) + 1;
+    if (avgEnd > dataLength) {
+      avgEnd = dataLength;
+    }
+    let avgX = 0;
+    let avgY = 0;
+    const avgCount = avgEnd - avgStart;
+    for (let k = avgStart; k < avgEnd; k += 1) {
+      avgX += k;
+      avgY += values[k];
+    }
+    if (avgCount > 0) {
+      avgX /= avgCount;
+      avgY /= avgCount;
+    } else {
+      avgX = dataLength - 1;
+      avgY = values[dataLength - 1];
+    }
+    const rangeStart = Math.floor(i * bucketSize) + 1;
+    const rangeEnd = Math.floor((i + 1) * bucketSize) + 1;
+    const ax = a;
+    const ay = values[a];
+    let maxArea = -1;
+    let chosen = rangeStart;
+    for (let k = rangeStart; k < rangeEnd; k += 1) {
+      const area = Math.abs((ax - avgX) * (values[k] - ay) - (ax - k) * (avgY - ay));
+      if (area > maxArea) {
+        maxArea = area;
+        chosen = k;
+      }
+    }
+    sampled[sampledIndex] = chosen;
+    sampledIndex += 1;
+    a = chosen;
+  }
+  sampled[sampledIndex] = dataLength - 1; // always keep the last point
+  return sampled;
+}