Release v0.3.13

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 **148 KiB raw / 33 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**. 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,33 +193,33 @@ 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 |
-| 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 |
-| 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 |
-| navigator plugin | `dist/plugins/navigator.js` | 8.6 KiB |
-| selection plugin | `dist/plugins/selection.js` | 5.3 KiB |
-| legend plugin | `dist/plugins/legend.js` | 2.8 KiB |
-| 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-Bl4erFBO.js` | 55.2 KiB |
-| shared streaming data chunk | `dist/UniformRingBuffer-zewj9EWq.js` | 44.2 KiB |
-| shared OhlcDataset chunk | `dist/OhlcDataset-u2Eao8OX.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-BxD1tCts.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-D0WRT6Fj.js` | 5.7 KiB |
-| shared Crosshair chunk | `dist/Crosshair-B0iu8h16.js` | 8.8 KiB |
+| root entry | `dist/index.js` | 2 KiB |
+| core subpath entry | `dist/core.js` | 1 KiB |
+| interaction subpath entry | `dist/interaction.js` | 0 KiB |
+| render subpath entry | `dist/render.js` | 0 KiB |
+| react entry | `dist/react.js` | 1 KiB |
+| linked entry | `dist/linked.js` | 0 KiB |
+| linked core entry | `dist/linked-*.js` | 0 KiB |
+| data entry | `dist/data.js` | 5 KiB |
+| export entry | `dist/export.js` | 1 KiB |
+| interactions plugin | `dist/plugins/interactions.js` | 15 KiB |
+| annotations plugin | `dist/plugins/annotations.js` | 9 KiB |
+| navigator plugin | `dist/plugins/navigator.js` | 9 KiB |
+| selection plugin | `dist/plugins/selection.js` | 5 KiB |
+| legend plugin | `dist/plugins/legend.js` | 3 KiB |
+| tooltip plugin entry | `dist/plugins/tooltip.js` | 0 KiB |
+| crosshair plugin entry | `dist/plugins/crosshair.js` | 0 KiB |
+| flamegraph plugin | `dist/plugins/flamegraph.js` | 21 KiB |
+| shared Chart chunk | `dist/Chart-*.js` | 57 KiB |
+| shared streaming data chunk | `dist/UniformRingBuffer-*.js` | 44 KiB |
+| shared OhlcDataset chunk | `dist/OhlcDataset-*.js` | 9 KiB |
+| shared AxisController chunk | `dist/AxisController-*.js` | 14 KiB |
+| shared WebGL2Backend chunk | `dist/WebGL2Backend-*.js` | 22 KiB |
+| shared LinkedChartsCore chunk | `dist/LinkedChartsCore-*.js` | 2 KiB |
+| lazy screenshot chunk | `dist/screenshot-*.js` | 4 KiB |
+| shared OverlayUtils chunk | `dist/OverlayUtils-*.js` | 3 KiB |
+| shared Tooltip chunk | `dist/Tooltip-*.js` | 6 KiB |
+| shared Crosshair chunk | `dist/Crosshair-*.js` | 10 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. |

changelogs/v0.3.13.md

@@ -0,0 +1,32 @@
+# BlazePlot v0.3.13
+
+## Changes
+
+- Added first-class histogram helpers, chart APIs, documentation, tests, and preview coverage.
+- Improved axis tick label placement so endpoint labels stay readable and overlapping labels are suppressed.
+- Improved crosshair overlays with interval-aware highlights, configurable label placement, and line rendering below chart content.
+- Added a large-scale 1M-bin histogram website preview with an initial 1k-bin viewport.
+
+## Benchmarks
+
+## 2026-05-28T18:52:51.646Z
+
+Command: `bun run bench:report --scenario ci-smoke --measure-ms 750 --warmup-ms 100 --width 800 --height 450 --top 12 --setup-timeout-ms 60000 --out-md changelogs/v0.3.13.md`
+
+| Scenario | Browser | Canvas | Renderer | RAF FPS | RAF p95 ms | Chart p50 ms | Chart p95 ms | Points | Draws | Batched | Upload KB |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| ci-smoke | brave | 748x341 | mixed | 60.0 | 16.80 | 2.20 | 2.70 | 5,265 | 4 | 0 | 41.4 |
+
+### CPU hot spots: ci-smoke
+
+| Function | Self ms | Total ms | Location |
+|---|---:|---:|---|
+| (idle) | 576.0 | 576.0 | runtime |
+| updateAxis | 71.6 | 72.7 | AxisOverlay.ts:72 |
+| (program) | 43.8 | 43.8 | runtime |
+| measure | 41.9 | 50.0 | main.ts:287 |
+| queryPhysicalMinMax | 7.8 | 7.8 | RingBuffer.ts:205 |
+| (garbage collector) | 5.6 | 5.6 | runtime |
+| render | 3.9 | 110.8 | Chart.ts:981 |
+| getLinearTickValues | 3.4 | 5.6 | AxisController.ts:291 |
+