Add histogram series support

README.md

@@ -17,7 +17,7 @@ Built on native WebGL2 with no rendering runtime dependency.
 <!-- README_PERFORMANCE_START -->
 ## Performance
 
-The core chart runtime is intentionally compact: the production build for `blazeplot` (without optional plugins) is about **149 KiB raw / 34 KiB gzip**. Optional plugins and helpers ship as separate subpath entries.
+The core chart runtime is intentionally compact: the production build for `blazeplot` (without optional plugins) is about **148 KiB raw / 34 KiB gzip**. Optional plugins and helpers ship as separate subpath entries.
 
 Latest manual headed comparison: 2026-05-22T15:20:02.565Z on AMD Ryzen 5 5600H with Radeon Graphics (12 logical CPUs), ANGLE (NVIDIA Corporation, NVIDIA GeForce RTX 3050 Laptop GPU/PCIe/SSE2, OpenGL 4.5.0), Chrome/148.0.7778.167. The harness prewarms each selected library before measured runs (317.4 ms total) and discards 1 setup warmup run(s) before each displayed row. Source: `benchmarks/latest.json`.
 
@@ -193,14 +193,14 @@ Generated from `dist/` after the package build.
 
 | Chunk | File | Size |
 |---|---|---:|
-| root entry | `dist/index.js` | 1.6 KiB |
-| core subpath entry | `dist/core.js` | 0.7 KiB |
+| root entry | `dist/index.js` | 2.3 KiB |
+| core subpath entry | `dist/core.js` | 0.8 KiB |
 | interaction subpath entry | `dist/interaction.js` | 0.1 KiB |
 | render subpath entry | `dist/render.js` | 0.3 KiB |
 | react entry | `dist/react.js` | 0.7 KiB |
 | linked entry | `dist/linked.js` | 0.4 KiB |
 | linked core entry | `dist/linked-core.js` | 0.1 KiB |
-| data entry | `dist/data.js` | 4.9 KiB |
+| data entry | `dist/data.js` | 5.1 KiB |
 | export entry | `dist/export.js` | 1.3 KiB |
 | interactions plugin | `dist/plugins/interactions.js` | 15.4 KiB |
 | annotations plugin | `dist/plugins/annotations.js` | 9.3 KiB |
@@ -210,16 +210,16 @@ Generated from `dist/` after the package build.
 | tooltip plugin entry | `dist/plugins/tooltip.js` | 0.1 KiB |
 | crosshair plugin entry | `dist/plugins/crosshair.js` | 0.1 KiB |
 | flamegraph plugin | `dist/plugins/flamegraph.js` | 20.7 KiB |
-| shared Chart chunk | `dist/Chart-BXL4MXf-.js` | 56.5 KiB |
-| shared streaming data chunk | `dist/UniformRingBuffer-C5yCnNeR.js` | 44.3 KiB |
-| shared OhlcDataset chunk | `dist/OhlcDataset-DmFKmNbM.js` | 11.2 KiB |
-| shared AxisController chunk | `dist/AxisController-CCk21uVK.js` | 13.8 KiB |
-| shared WebGL2Backend chunk | `dist/WebGL2Backend-DivtLMNz.js` | 22.0 KiB |
-| shared LinkedChartsCore chunk | `dist/LinkedChartsCore-CYBw2rB_.js` | 2.1 KiB |
-| lazy screenshot chunk | `dist/screenshot-PUXj6UGd.js` | 3.5 KiB |
-| shared OverlayUtils chunk | `dist/OverlayUtils-BoCHW3n7.js` | 3.1 KiB |
-| shared Tooltip chunk | `dist/Tooltip-D7t8uZIg.js` | 5.8 KiB |
-| shared Crosshair chunk | `dist/Crosshair-BViz8JUB.js` | 9.9 KiB |
+| shared Chart chunk | `dist/Chart-DstwTTQs.js` | 57.2 KiB |
+| shared streaming data chunk | `dist/UniformRingBuffer-DVJiaja6.js` | 44.0 KiB |
+| shared OhlcDataset chunk | `dist/OhlcDataset-BzaK030U.js` | 8.6 KiB |
+| shared AxisController chunk | `dist/AxisController-B5zX7JBz.js` | 13.8 KiB |
+| shared WebGL2Backend chunk | `dist/WebGL2Backend-DDGRc0UJ.js` | 22.0 KiB |
+| shared LinkedChartsCore chunk | `dist/LinkedChartsCore-zxImWpgT.js` | 2.1 KiB |
+| lazy screenshot chunk | `dist/screenshot-CljRIqNW.js` | 3.5 KiB |
+| shared OverlayUtils chunk | `dist/OverlayUtils-YP9KSKL4.js` | 3.1 KiB |
+| shared Tooltip chunk | `dist/Tooltip-a9NkZoPg.js` | 5.8 KiB |
+| shared Crosshair chunk | `dist/Crosshair-C426MhNr.js` | 9.9 KiB |
 
 ### All public exports
 
@@ -278,6 +278,7 @@ Generated from `dist/index.d.ts` after the package build.
 | `createChart` | function | `./createChart` | Create a chart from a compact declarative config. This helper is intentionally thin: it returns the underlying `Chart` instance, so advanced code can still use the full imperative API after setup. |
 | `CreateChartArraySeries` | interface | `./createChart` | Declarative series backed by parallel X and Y arrays. |
 | `CreateChartDatasetSeries` | interface | `./createChart` | Declarative series backed by an existing BlazePlot dataset. |
+| `CreateChartHistogramSeries` | type | `./createChart` | Declarative histogram series backed by raw one-dimensional values. |
 | `CreateChartObjectSeries` | interface | `./createChart` | Declarative series backed by object rows and field selectors. |
 | `CreateChartOptions` | interface | `./createChart` | High-level chart configuration for common first-render cases. Use `createChart(...)` when you have static arrays, object rows, or a simple streaming buffer and want BlazePlot to create the chart, add series, fit the initial viewport, and start rendering in one call. |
 | `CreateChartSeries` | type | `./createChart` | Any series shape accepted by `createChart`. |
@@ -293,6 +294,15 @@ Generated from `dist/index.d.ts` after the package build.
 | `GpuCapabilities` | interface | `./render/types` | Feature flags reported by a GPU backend. |
 | `GpuProgram` | interface | `./render/types` | Opaque handle for a linked GPU program. |
 | `GpuResource` | type | `./render/types` | GPU resource accepted by backend disposal. |
+| `histogram` | function | `./core/Histogram` | Convert one-dimensional finite values into histogram bins. |
+| `HistogramBin` | interface | `./core/Histogram` | One histogram bucket, suitable for rendering as a bar centered at `x`. |
+| `HistogramBinThresholds` | type | `./core/Histogram` | Explicit bin edges, or a requested number of equal-width bins. |
+| `histogramDataset` | function | `./core/Histogram` | Build a StaticDataset from histogram bucket centers and normalized counts. |
+| `HistogramDataset` | class | `./core/Histogram` | Static histogram dataset that preserves each bucket's X interval for picks and tooltips. |
+| `HistogramNormalization` | type | `./core/Histogram` | Histogram value normalization modes. |
+| `HistogramOptions` | interface | `./core/Histogram` | Options for converting one-dimensional values into histogram bins. |
+| `HistogramResult` | interface | `./core/Histogram` | Result of a histogram transform. |
+| `HistogramSeriesConfig` | interface | `./ui/Chart` | Series configuration for `Chart.addHistogram(...)` from raw one-dimensional values. |
 | `isWebGL2Available` | function | `./render/WebGL2Backend` | Return whether the current environment can create a WebGL2 context. |
 | `LODBucket` | interface | `./core/types` | Min/max aggregate for a contiguous X range. |
 | `LODStrategy` | type | `./core/types` | Downsampling strategy used when a series is denser than the plot. |
@@ -304,6 +314,7 @@ Generated from `dist/index.d.ts` after the package build.
 | `OhlcRingBuffer` | class | `./core/OhlcDataset` | Fixed-capacity streaming buffer for OHLC/candlestick data. |
 | `OhlcRingBufferOptions` | interface | `./core/OhlcDataset` | Options for `OhlcRingBuffer`. |
 | `PanIntent` | interface | `./interaction/types` | Pan request expressed in data units or screen pixels. |
+| `PrecomputedHistogramSeriesConfig` | interface | `./ui/Chart` | Series configuration for `Chart.addHistogram(...)` from precomputed bins. |
 | `RangeMinMaxDataset` | interface | `./core/types` | Dataset that can answer min/max Y queries for index ranges. |
 | `RangeSampleCopyDataset` | interface | `./core/types` | Optional high-performance extraction capability for datasets that can copy raw samples without going through repeated getX/getY calls. Implement this for very large datasets, implicit-X datasets, or remote/memory-mapped sources. |
 | `ReglBackend` | const | `./render/WebGL2Backend` | Deprecated alias for WebGL2Backend. This preserves the pre-native-backend public API. Deprecated: Effective next patch release. Use WebGL2Backend. |
@@ -355,6 +366,8 @@ Generated from `dist/index.d.ts` after the package build.
 | `VisibleSampleCopyDataset` | interface | `./core/types` | Optional high-performance stable visible sampling capability. Unlike copySamplesRange, this method may stride/downsample, but should choose samples anchored to data coordinates so streamed appends do not make existing sampled points jitter. |
 | `WebGL2Backend` | class | `./render/WebGL2Backend` | Native WebGL2 implementation of BlazePlot's GPU backend. |
 | `WebGL2UnavailableError` | class | `./render/WebGL2Backend` | Error thrown when a WebGL2 backend cannot be created. |
+| `XRange` | interface | `./core/types` | Data-domain X interval represented by one dataset sample. |
+| `XRangeDataset` | interface | `./core/types` | Dataset whose sample X values represent intervals rather than points. |
 | `YAppendableDataset` | interface | `./core/types` | Dataset that accepts appended Y samples with implicit X values. |
 | `YUpdatableDataset` | interface | `./core/types` | Dataset that supports updating existing Y values. |
 | `ZoomAxis` | type | `./interaction/types` | Axis affected by a zoom operation. |

docs/data-semantics.md

@@ -13,6 +13,7 @@ BlazePlot expects finite, sorted X values. Y values are normally finite; non-fin
 | Historical OHLC/candles | `StaticOhlcDataset` | Bounds and fitting use high/low values. |
 | Live OHLC/candles | `OhlcRingBuffer` | Rolling OHLC history with explicit time values. |
 | Server-reduced buckets | `ServerSampledDataset` | Use `downsample: "server"` for min/max buckets. |
+| One-dimensional values | `histogram(...)` / `chart.addHistogram(...)` | Converts raw values to bucket centers/counts and renders with the bar path. |
 | Custom remote/procedural data | `Dataset` or `AcceleratedDataset` | Implement sorted logical access and only the fast paths your data can answer cheaply. |
 
 ## Empty datasets
@@ -58,6 +59,14 @@ For finite-to-finite session breaks, insert an explicit gap marker sample.
 
 `UniformRingBuffer` is for fixed-rate data. It stores Y values and derives X as `xStart + index * xStep`; `xStep` must be positive. Prefer it for telemetry or signal data where every sample is evenly spaced. For chart-owned series, `chart.addLine({ capacity, xStart, xStep })` creates this dataset for you.
 
+## Histograms and X/Y binning
+
+`histogram(values, options)` bins one-dimensional finite values by value range. It skips `NaN`, infinities, and non-number values, tracks underflow/overflow outside the chosen bin edges, and can normalize bucket heights as counts, probability, percent, or density. Fixed-size bins align to origin `0` by default; pass `align` to use another origin. `chart.addHistogram(...)` and declarative `type: "histogram"` series turn those buckets into a histogram dataset and render them as bars. Each rendered sample is centered at the bucket midpoint for the bar renderer, while the dataset exposes generic X-interval metadata that tooltip and picking code can present as a range.
+
+`binSamples(samples, binSize, options)` is different: it expects existing `{ x, y }` samples and groups them by X interval with a Y reducer such as mean, sum, min, or max.
+
+Variable-width explicit histogram thresholds are supported by the pure `histogram(...)` helper. The chart helper uses one `barWidth` for the whole series, so pass an explicit `style.barWidth` or use uniform-width bins when rendering.
+
 ## Server-sampled datasets
 
 `ServerSampledDataset` is for data that was already reduced before it reached the browser.