blazeplot 0.2.2 → 0.3.1

package/README.md

@@ -21,21 +21,23 @@ bun install blazeplot
 
 ## Quick start
 
+A chart only needs a host element. For regular arrays, wrap your data in a `StaticDataset`; `capacity` is only needed when you want a streaming ring buffer.
+
 ```html
 <div id="chart" style="width:100%;height:400px"></div>
 
 <script type="module">
-  import { Chart } from "blazeplot";
+  import { Chart, StaticDataset } from "blazeplot";
 
-  const chart = new Chart(document.getElementById("chart"));
-  const wave = chart.addLine({ capacity: 10_000, downsample: "minmax" });
+  const el = document.getElementById("chart");
+  if (!el) throw new Error("Missing #chart element");
 
-  wave.append(
-    Float64Array.from({ length: 1000 }, (_, i) => i),
-    Float32Array.from({ length: 1000 }, (_, i) => Math.sin(i * 0.02)),
-  );
+  const x = Array.from({ length: 1000 }, (_, i) => i);
+  const y = x.map((value) => Math.sin(value * 0.02));
 
-  chart.setViewport({ xMin: 0, xMax: 1000, yMin: -1.5, yMax: 1.5 });
+  const chart = new Chart(el);
+  chart.addLine({ dataset: new StaticDataset(x, y), name: "sine" });
+  chart.setViewport({ xMin: x[0], xMax: x[x.length - 1], yMin: -1.5, yMax: 1.5 });
   chart.start();
 </script>
 ```
@@ -55,186 +57,423 @@ bun install blazeplot
 | **Benchmark overlay** | Built-in fps, frame time, vertex count, draw calls. |
 | **ResizeObserver** | Automatic DPR-aware canvas sizing. |
 
-## API
-
-### `Chart`
-
-| Signature | Description |
-|---|---|
-| `new Chart(container, options?)` | Create a chart inside an HTML container element. The chart owns the plot canvas and axis layout. |
-| `chart.addSeries(config, style?)` | Add a data series. Returns `SeriesStore`. |
-| `chart.addLine(config, style?)` / `addArea` / `addScatter` / `addBar` / `addOhlc` / `addCandlestick` | Typed helpers that set the series mode for you. `config.yAxis: "right"` maps a series to the secondary Y axis. |
-| `chart.removeSeries(series)` | Remove a previously added series. |
-| `chart.setViewport({ xMin, xMax, yMin, yMax })` | Set the visible data range on both Y axes and the shared X range. |
-| `chart.setYViewport("left" | "right", { yMin, yMax })` | Set one Y-axis viewport while preserving the shared X range. |
-| `chart.getViewport(yAxis?)` | Return the current visible data range for `"left"` or `"right"` Y axis. |
-| `chart.pan(intent)` / `chart.zoom(intent)` | Plugin-facing camera interaction helpers. |
-| `chart.clientToData(clientX, clientY, yAxis?)` / `chart.dataToPlot(x, y, yAxis?)` | Convert between client/plot coordinates and data coordinates for the selected Y axis. |
-| `chart.resize(dpr?)` | Resize the internal plot canvas to match its CSS size × DPR. |
-| `chart.start()` | Start the render loop (rAF). |
-| `chart.stop()` | Stop the render loop. |
-| `chart.canvas` | Read-only access to the internal plot canvas. |
-| `chart.xAxisElement` / `chart.yAxisElement` | Plugin-facing access to outside axis gutter elements. |
-| `chart.theme` | Resolved theme values used by the chart and built-in plugins. |
-| `chart.getFrameStats(target?)` | Copy per-frame benchmark counters into a reusable object. |
-| `chart.getSeriesState()` | Return public series metadata/state for plugins or custom UI. |
-| `chart.setSeriesVisible(series, visible)` | Toggle visibility and notify series-state subscribers. |
-| `chart.pick(clientX, clientY, options?)` | Raw-data hit test. Supports `mode: "nearest-x" | "nearest-point"`, `group: "x" | "none"`, and `maxDistancePx`; returned items include actual sample X/Y and plot/client coordinates for highlights. |
-| `chart.subscribe("hover", cb)` / `chart.subscribe("serieschange", cb)` | Subscribe to hover or series state changes. Returns an unsubscribe function. |
-| `await chart.screenshot(options?)` | Export the full chart as an image `Blob`, including the WebGL plot and built-in DOM text overlays. |
-| `chart.dispose()` | Dispose GPU resources, observers, input handlers, and owned DOM layout. |
-
-### `ChartOptions`
-
-| Property | Default | Description |
-|---|---|---|
-| `viewportPolicy?` | — | Optional `beforeRender` viewport hook. Pass the same policy to `interactionsPlugin({ viewportPolicy })` for pan/zoom hooks. |
-| `hover?` | `{ mode: "nearest-x", group: "x" }` | Default hover picking behavior. `mode` can be `"nearest-x"` or `"nearest-point"`; `group: "x"` reports one item per visible series at the selected X, while `group: "none"` reports only the selected point. |
-| `plugins?` | `[]` | Optional `ChartPlugin` instances, e.g. `legendPlugin()` and `tooltipPlugin()`. |
-| `theme?` | built-in dark theme | Override chart, axis, palette, legend, and tooltip colors/fonts. |
-| `grid?` | `true` | Show grid lines. |
-| `gridStyle?` | `{ color: theme.gridColor }` | Grid line color and width; overrides the theme grid color. |
-| `axes?` | `true` | Show axis tick labels. `true`/`false`, or per-axis `{ x?: boolean \| AxisConfig, y?: boolean \| AxisConfig, y2?: boolean \| AxisConfig }`. `y2` is the right-side secondary Y axis and is hidden by default. |
-
-### `ChartTheme`
-
-```css
-:root {
-  --plot-bg: #050816;
-  --plot-grid: rgb(148 163 184 / 0.22);
-  --plot-axis: #cbd5e1;
-  --series-a: #38bdf8;
-  --series-b: oklch(70% 0.19 22);
-}
-```
-
-```ts
-new Chart(container, {
-  theme: {
-    backgroundColor: "var(--plot-bg)",
-    gridColor: "var(--plot-grid)",
-    axisColor: "var(--plot-axis)",
-    seriesColors: ["var(--series-a)", "var(--series-b)"],
-    tooltipBackgroundColor: "rgb(4 8 16 / 0.85)",
-    legendBackgroundColor: "rgb(4 8 16 / 0.85)",
-  },
-});
-```
-
-WebGL-facing colors (`backgroundColor`, `gridColor`, `seriesColors`) accept either normalized RGBA tuples (`[r,g,b,a]`) or CSS colors, including CSS variables inherited by the chart container. BlazePlot resolves CSS colors internally to WebGL-compatible RGBA floats while preserving CSS strings for DOM styling where appropriate. Per-series styles and plugin options still override theme defaults.
-
-### `AxisConfig`
-
-| Property | Default | Description |
-|---|---|---|
-| `visible?` | `true` | Show this axis. |
-| `position?` | `"inside"` | `"inside"` draws labels over the plot; `"outside"` reserves a real DOM gutter and shrinks the plot canvas. |
-
-```ts
-// X labels outside (bottom gutter), left Y inside, right Y outside.
-const chart = new Chart(canvas, {
-  axes: { x: { position: "outside" }, y: true, y2: { position: "outside" } }
-});
-
-chart.addLine({ capacity: 10_000, yAxis: "left" });
-chart.addLine({ capacity: 10_000, yAxis: "right" });
-chart.setYViewport("right", { yMin: 0, yMax: 100 });
-```
-
-### `ChartFrameStats`
+<!-- README_DOCS_START -->
+## API reference
 
-| Field | Description |
-|---|---|
-| `fps` | Instantaneous render-loop FPS. |
-| `frameMs` | Milliseconds spent in `render()`. |
-| `pointsRendered` | Number of vertices drawn this frame. |
-| `drawCalls` | Number of GPU draw calls this frame. |
-| `uploadBytes` | Bytes uploaded to GPU this frame. |
-| `renderMode` | `"none"` / `"raw"` / `"minmax"` / `"points"` / `"bars"` / `"area"` / `"mixed"`. |
-
-### Plugins
-
-```js
-import { Chart } from "blazeplot";
-import { interactionsPlugin } from "blazeplot/plugins/interactions";
-import { legendPlugin } from "blazeplot/plugins/legend";
-import { tooltipPlugin } from "blazeplot/plugins/tooltip";
-import { annotationsPlugin } from "blazeplot/plugins/annotations";
-
-const chart = new Chart(container, {
-  hover: { mode: "nearest-x", group: "x" },
-  plugins: [
-    interactionsPlugin({ axis: "xy" }),
-    annotationsPlugin({
-      annotations: [
-        { type: "y-line", y: 0, label: "baseline" },
-        { type: "x-range", xMin: 10, xMax: 20, label: "event" },
-        { type: "point", x: 42, y: 1.2, shape: "diamond", label: "marker" },
-      ],
-    }),
-    legendPlugin(),
-    tooltipPlugin({ mode: "nearest-point", group: "none", maxDistancePx: 24 }),
-  ],
-});
-```
+This section is generated by `bun run docs:readme` from TypeScript declaration files and JSDoc comments. Do not edit it by hand.
 
-Built-in plugins are optional. `interactionsPlugin()` provides plain-drag box zoom, Shift+drag plot pan, wheel zoom, double-click reset, and `axis: "x" | "y" | "xy"`. When outside axes are visible, scrolling an axis zooms that axis and dragging an axis pans that axis; the plugin also applies a subtle axis hover color/filter configurable with `axisHover`, `axisHoverColor`, and `axisHoverFilter`. `annotationsPlugin()` supports common plot annotations: vertical/horizontal lines, X/Y bands, boxes, point markers, and labels. Legend/tooltip consume public APIs (`getSeriesState`, `setSeriesVisible`, `pick`, and `subscribe`) so custom UI can use the same contract. The default tooltip updates while the cursor is still on live charts and highlights the raw sample(s) it is reporting. For shared time-series tooltips, use `group: "x"`; for scatter/true point hover, use `group: "none"`.
+- [Quick start](#quick-start)
+- [Features](#features)
+- [Architecture](#architecture)
+- [Development](#development)
+- [Roadmap](ROADMAP.md)
+- [Changelog for v0.3.1](changelogs/v0.3.1.md)
 
-### `SeriesStore`
+### Package entry points
 
-| Signature | Description |
+| Import | Contents |
 |---|---|
-| `series.append(xs, ys)` | Append typed arrays of X and Y values (streaming). |
-| `series.clear()` | Clear all data and reset. |
-| `series.setVisible(v)` | Toggle visibility. |
-| `series.visible` | Current visibility state. |
-| `series.length` | Number of samples buffered. |
-
-### `SeriesConfig`
-
-| Property | Description |
-|---|---|
-| `mode` | `"line"` / `"area"` / `"scatter"` / `"bar"` / `"ohlc"` / `"candlestick"` / `"envelope"` (envelope roadmap-only). |
-| `capacity` | Ring buffer capacity (samples). |
-| `id?` / `name?` | Optional metadata exposed to plugins, legend, and tooltip rows. |
-| `yAxis?` | `"left"` or `"right"`; selects the primary or secondary Y viewport/axis for this series. |
-| `downsample` | `"minmax"` or `"none"`. Min/max LOD applies to line/bar rendering. Scatter with LOD uses a 2D viewport-aware point sampler; scatter with `"none"` renders exact 2D-culled chunks. Area renders raw sampled strips. |
-
-### `SeriesStyle`
-
-| Property | Default | Description |
-|---|---|---|
-| `color` | `[0.3, 0.6, 1.0, 1.0]` | RGBA float color. |
-| `lineWidth` | `1` | Line width in pixels. |
-| `pointSize` | `4` | Scatter point size in CSS pixels. |
-| `barWidth` | `0.8` | Bar width in data-space X units. |
-| `baseline` | `0` | Area/bar baseline in data-space Y units. |
-| `fillColor` | line color with 25% alpha | Area fill RGBA color. |
-| `tickWidth` | `barWidth` or `0.8` | OHLC open/close tick width in data-space X units. |
-| `upColor` / `downColor` | series color / translucent fill | Candlestick body colors. |
-| `wickColor` | series color | Candlestick wick color. |
-
-### High-performance dataset capabilities
-
-`Dataset` only requires `getX/getY` and X binary search. For maximum performance with huge, procedural, remote, or memory-mapped data, implement `AcceleratedDataset`.
-
-`AcceleratedDataset` is the convenience contract for all fast paths: range min/max, exact range copying, stable viewport sampling, and renderer-ready min/max buckets. BlazePlot still exports the smaller capability interfaces (`RangeMinMaxDataset`, `RangeSampleCopyDataset`, `VisibleSampleCopyDataset`, `MinMaxSegmentCopyDataset`) for advanced partial acceleration, but most high-performance custom datasets should target `AcceleratedDataset`.
-
-### `ViewportPolicy`
-
-`beforeRender` is consumed by `Chart`; `beforePan` and `beforeZoom` are consumed by `interactionsPlugin({ viewportPolicy })`.
-
-```ts
-interface ViewportPolicy {
-  beforePan?(camera: Camera2D, intent: PanIntent): PanIntent | null;
-  beforeZoom?(camera: Camera2D, intent: ZoomIntent): ZoomIntent | null;
-  beforeRender?(camera: Camera2D): void;
-}
-```
-
-### Lower-level primitives
-
-`Camera2D`, `RingBuffer`, `MinMaxPyramid`, `AxisController` are exported for advanced use cases.
+| `blazeplot` | Core chart, data, interaction, rendering types, and low-level primitives. |
+| `blazeplot/react` | React wrapper component and hooks. |
+| `blazeplot/linked` | Linked chart layout helpers. |
+| `blazeplot/plugins/legend` | Built-in legend plugin. |
+| `blazeplot/plugins/tooltip` | Built-in tooltip plugin. |
+| `blazeplot/plugins/interactions` | Built-in pan, zoom, axis interaction, and reset plugin. |
+| `blazeplot/plugins/annotations` | Built-in annotation overlay plugin. |
+| `blazeplot/plugins/selection` | Built-in brush/range selection plugin. |
+| `blazeplot/plugins/crosshair` | Built-in crosshair and ruler plugin. |
+| `blazeplot/plugins/navigator` | Built-in overview/navigator plugin. |
+
+### Selected generated declarations
+
+These member tables are generated from TypeScript declarations.
+
+<details>
+<summary>class Chart</summary>
+
+| Member |
+|---|
+| `constructor(target: HTMLElement, options?: ChartOptions)` |
+| `get canvas(): HTMLCanvasElement` |
+| `get rootElement(): HTMLElement` |
+| `get plotElement(): HTMLElement` |
+| `get xAxisElement(): HTMLElement` |
+| `get yAxisElement(): HTMLElement` |
+| `get y2AxisElement(): HTMLElement` |
+| `get theme(): ResolvedChartTheme` |
+| `getWebGLContext(): WebGL2RenderingContext \\| null` |
+| `getCamera(yAxis?: SeriesYAxis): Camera2D` |
+| `dataToPlot(x: number, y: number, yAxis?: SeriesYAxis): [ number, number ]` |
+| `clientToData(clientX: number, clientY: number, yAxis?: SeriesYAxis): [ number, number ] \\| null` |
+| `getViewport(yAxis?: SeriesYAxis): Viewport` |
+| `pan(intent: PanIntent): void` |
+| `zoom(intent: ZoomIntent): void` |
+| `addSeries(config: SeriesConfig, style?: Partial<SeriesStyle>): SeriesStore` |
+| `addLine(config: TypedSeriesConfig, style?: Partial<SeriesStyle>): SeriesStore` |
+| `addArea(config: TypedSeriesConfig, style?: Partial<SeriesStyle>): SeriesStore` |
+| `addScatter(config: TypedSeriesConfig, style?: Partial<SeriesStyle>): SeriesStore` |
+| `addBar(config: TypedSeriesConfig, style?: Partial<SeriesStyle>): SeriesStore` |
+| `addOhlc(config: TypedSeriesConfig, style?: Partial<SeriesStyle>): SeriesStore` |
+| `addCandlestick(config: TypedSeriesConfig, style?: Partial<SeriesStyle>): SeriesStore` |
+| `removeSeries(series: SeriesStore): boolean` |
+| `setSeriesVisible(series: SeriesStore, visible: boolean): boolean` |
+| `getSeriesState(): ChartSeriesState[]` |
+| `setViewport(v: { xMin?: number; xMax?: number; yMin?: number; yMax?: number; }): void` |
+| `setYViewport(yAxis: SeriesYAxis, v: { yMin?: number; yMax?: number; }): void` |
+| `resize(dpr?: number): boolean` |
+| `getFrameStats(target?: ChartFrameStats): ChartFrameStats` |
+| `getHoverState(): ChartHoverState \\| null` |
+| `setLayoutReservation(id: string, reservation: ChartLayoutReservation \\| null): void` |
+| `subscribe(event: "hover", callback: (state: ChartHoverState \\| null) => void): () => void` |
+| `subscribe(event: "serieschange", callback: () => void): () => void` |
+| `subscribe(event: "themechange", callback: () => void): () => void` |
+| `subscribe(event: "render", callback: (chart: Chart) => void): () => void` |
+| `subscribe(event: "viewportchange", callback: (event: ChartViewportChangeEvent) => void): () => void` |
+| `subscribe(event: "select", callback: (event: ChartSelectEvent) => void): () => void` |
+| `subscribe(event: "seriesclick", callback: (event: ChartSeriesClickEvent) => void): () => void` |
+| `subscribe(event: ChartPointerEventType, callback: (event: ChartPointerEventState) => void): () => void` |
+| `emitSelect(selection: unknown): void` |
+| `setTheme(theme?: ChartTheme): void` |
+| `setGridVisible(visible: boolean): void` |
+| `getGridVisible(): boolean` |
+| `setAxes(axes: ChartOptions["axes"]): void` |
+| `pick(clientX: number, clientY: number, options?: ChartPickOptions): ChartHoverState \\| null` |
+| `screenshot(options?: ChartScreenshotOptions): Promise<Blob>` |
+| `start(): void` |
+| `stop(): void` |
+| `dispose(): void` |
+
+</details>
+
+<details>
+<summary>interface ChartOptions</summary>
+
+| Member |
+|---|
+| `viewportPolicy?: ViewportPolicy` |
+| `grid?: boolean` |
+| `gridStyle?: Partial<SeriesStyle>` |
+| `axes?: boolean \\| { x?: boolean \\| AxisConfig; y?: boolean \\| AxisConfig; y2?: boolean \\| AxisConfig; }` |
+| `title?: string \\| ChartTitleConfig` |
+| `subtitle?: string \\| ChartTitleConfig` |
+| `hover?: ChartPickOptions` |
+| `plugins?: readonly ChartPlugin[]` |
+| `theme?: ChartTheme` |
+
+</details>
+
+<details>
+<summary>interface ChartTheme</summary>
+
+| Member |
+|---|
+| `backgroundColor?: ThemeColor` |
+| `gridColor?: ThemeColor` |
+| `axisColor?: string` |
+| `axisFont?: string` |
+| `seriesColors?: readonly ThemeColor[]` |
+| `tooltipBackgroundColor?: string` |
+| `tooltipTextColor?: string` |
+| `tooltipFont?: string` |
+| `legendBackgroundColor?: string` |
+| `legendBorderColor?: string` |
+| `legendTextColor?: string` |
+| `legendMutedTextColor?: string` |
+| `legendFont?: string` |
+| `titleColor?: string` |
+| `titleFont?: string` |
+| `subtitleColor?: string` |
+| `subtitleFont?: string` |
+| `axisTitleColor?: string` |
+| `axisTitleFont?: string` |
+
+</details>
+
+<details>
+<summary>interface AxisConfig</summary>
+
+| Member |
+|---|
+| `visible?: boolean` |
+| `position?: AxisPosition` |
+| `scale?: AxisScale` |
+| `tickFormat?: AxisTickFormat` |
+| `timezone?: AxisTimeZone` |
+| `title?: string \\| AxisTitleConfig` |
+
+</details>
+
+<details>
+<summary>class SeriesStore</summary>
+
+| Member |
+|---|
+| `config: SeriesConfig` |
+| `style: SeriesStyle` |
+| `constructor(dataset: Dataset, config: SeriesConfig, style: SeriesStyle)` |
+| `get hasLOD(): boolean` |
+| `get dirty(): boolean` |
+| `get length(): number` |
+| `get visible(): boolean` |
+| `setVisible(visible: boolean): void` |
+| `append(x: ArrayLike<number>, y: ArrayLike<number>): void` |
+| `appendY(y: ArrayLike<number>): void` |
+| `markDirty(): void` |
+| `clear(): void` |
+| `rebuildPyramid(): void` |
+| `query(viewport: Viewport, pixelWidth: number): LODView` |
+| `visibleSampleCount(viewport: Viewport): number` |
+| `sampleAt(index: number): SeriesSample \\| null` |
+| `nearestSampleByX(x: number, viewport?: Viewport): SeriesSample \\| null` |
+| `nearestSampleByPoint(x: number, y: number, viewport: Viewport, plotWidth: number, plotHeight: number, maxDistancePx?: number): SeriesSample \\| null` |
+| `copyRawVisible(viewport: Viewport, target: Float32Array, maxPoints: number, xOrigin?: number): number` |
+| `copyScatterVisible(viewport: Viewport, target: Float32Array, maxPoints: number, pixelWidth: number, pixelHeight: number, pointSize: number, xOrigin?: number): number` |
+| `copyScatterRange(start: number, end: number, viewport: Viewport, target: Float32Array, maxPoints: number, xOrigin?: number, pixelHeight?: number, pointSize?: number): number` |
+| `copyRawVisibleClipped(viewport: Viewport, target: Float32Array, maxPoints: number, xOrigin?: number): number` |
+| `copyRawVisibleClipSpace(viewport: Viewport, target: Float32Array, maxPoints: number): number` |
+| `copyRawRange(start: number, end: number, target: Float32Array, maxPoints: number, xOrigin?: number): number` |
+| `copyAreaVisible(viewport: Viewport, target: Float32Array, maxPoints: number, baseline?: number, xOrigin?: number): number` |
+| `copyAreaRange(start: number, end: number, target: Float32Array, maxPoints: number, baseline?: number, xOrigin?: number): number` |
+| `copyMinMaxVisible(viewport: Viewport, target: Float32Array, maxSegments: number, xOrigin?: number): number` |
+| `copyMinMaxInstanced(viewport: Viewport, target: Float32Array, maxSegments: number, xOrigin?: number): number` |
+| `copyOhlcRange(start: number, end: number, target: Float32Array, maxCandles: number, tickWidth: number, xOrigin?: number): number` |
+| `copyOhlcTuplesRange(start: number, end: number, target: Float32Array, maxCandles: number, xOrigin?: number): number` |
+| `visibleIndexRange(viewport: Viewport \\| undefined, outerPadding?: number): { start: number; end: number; }` |
+
+</details>
+
+<details>
+<summary>interface SeriesConfig</summary>
+
+| Member |
+|---|
+| `mode: SeriesMode` |
+| `capacity?: number` |
+| `downsample?: LODStrategy` |
+| `overflow?: BufferOverflowStrategy` |
+| `dataset?: Dataset` |
+| `yAxis?: SeriesYAxis` |
+| `id?: string` |
+| `name?: string` |
+
+</details>
+
+<details>
+<summary>interface SeriesStyle</summary>
+
+| Member |
+|---|
+| `color: readonly [ number, number, number, number ]` |
+| `lineWidth: number` |
+| `pointSize?: number` |
+| `barWidth?: number` |
+| `baseline?: number` |
+| `fillColor?: readonly [ number, number, number, number ]` |
+| `tickWidth?: number` |
+| `upColor?: readonly [ number, number, number, number ]` |
+| `downColor?: readonly [ number, number, number, number ]` |
+| `wickColor?: readonly [ number, number, number, number ]` |
+
+</details>
+
+<details>
+<summary>class UniformRingBuffer</summary>
+
+| Member |
+|---|
+| `capacity: number` |
+| `xStep: number` |
+| `constructor(capacity: number, options?: UniformRingBufferOptions)` |
+| `get length(): number` |
+| `get range(): TimeRange \\| null` |
+| `push(x: number, y: number): void` |
+| `append(x: ArrayLike<number>, y: ArrayLike<number>): void` |
+| `appendY(y: ArrayLike<number>): void` |
+| `clear(): void` |
+| `getX(index: number): number` |
+| `getY(index: number): number` |
+| `lowerBoundX(x: number): number` |
+| `upperBoundX(x: number): number` |
+| `rangeMinMaxY(start: number, end: number): { minY: number; maxY: number; } \\| null` |
+| `copyVisibleSamples(viewport: Viewport, target: Float32Array, maxPoints: number, layout: SampleLayout, baseline: number, xOrigin: number): number` |
+| `copySamplesRange(start: number, end: number, target: Float32Array, maxPoints: number, layout: SampleLayout, baseline: number, xOrigin: number): number` |
+| `copyMinMaxSegments(viewport: Viewport, target: Float32Array, maxSegments: number, layout: MinMaxLayout, xOrigin: number): number` |
+
+</details>
+
+<details>
+<summary>class RingBuffer</summary>
+
+| Member |
+|---|
+| `capacity: number` |
+| `constructor(capacity: number, options?: RingBufferOptions)` |
+| `get length(): number` |
+| `get range(): TimeRange \\| null` |
+| `push(x: number, y: number): void` |
+| `append(x: ArrayLike<number>, y: ArrayLike<number>): void` |
+| `get(index: number): { x: number; y: number; } \\| null` |
+| `getX(index: number): number` |
+| `getY(index: number): number` |
+| `lowerBoundX(x: number): number` |
+| `upperBoundX(x: number): number` |
+| `rangeMinMaxY(start: number, end: number): { minY: number; maxY: number; } \\| null` |
+| `clear(): void` |
+
+</details>
+
+<details>
+<summary>class StaticDataset</summary>
+
+| Member |
+|---|
+| `constructor(xData: ArrayLike<number>, yData: ArrayLike<number>)` |
+| `get length(): number` |
+| `get range(): TimeRange \\| null` |
+| `getX(index: number): number` |
+| `getY(index: number): number` |
+| `lowerBoundX(x: number): number` |
+| `upperBoundX(x: number): number` |
+
+</details>
+
+<details>
+<summary>class OhlcRingBuffer</summary>
+
+| Member |
+|---|
+| `capacity: number` |
+| `constructor(capacity: number, options?: OhlcRingBufferOptions)` |
+| `get length(): number` |
+| `get range(): TimeRange \\| null` |
+| `push(x: number, open: number, high: number, low: number, close: number): void` |
+| `append(x: ArrayLike<number>, open: ArrayLike<number>, high: ArrayLike<number>, low: ArrayLike<number>, close: ArrayLike<number>): void` |
+| `clear(): void` |
+| `getX(index: number): number` |
+| `getY(index: number): number` |
+| `getOpen(index: number): number` |
+| `getHigh(index: number): number` |
+| `getLow(index: number): number` |
+| `getClose(index: number): number` |
+| `lowerBoundX(x: number): number` |
+| `upperBoundX(x: number): number` |
+
+</details>
+
+<details>
+<summary>interface Dataset</summary>
+
+| Member |
+|---|
+| `length: number` |
+| `range: TimeRange \\| null` |
+| `getX(index: number): number` |
+| `getY(index: number): number` |
+| `lowerBoundX(x: number): number` |
+| `upperBoundX(x: number): number` |
+
+</details>
+
+<details>
+<summary>interface ViewportPolicy</summary>
+
+| Member |
+|---|
+| `beforePan(camera: Camera2D, intent: PanIntent): PanIntent \\| null` |
+| `beforeZoom(camera: Camera2D, intent: ZoomIntent): ZoomIntent \\| null` |
+| `beforeRender(camera: Camera2D): void` |
+
+</details>
+
+### All public exports
+
+<details>
+<summary>Generated from <code>dist/index.d.ts</code> after the package build</summary>
+
+| Export | Kind | Source | JSDoc summary |
+|---|---|---|---|
+| `AcceleratedDataset` | interface | `./core/types` | Convenience contract for maximum-performance custom datasets. Implement this when a dataset can provide fast exact sample copies, stable viewport sampling, range min/max queries, and renderer-ready min/max buckets. |
+| `AppendableDataset` | interface | `./core/types` | — |
+| `AxisConfig` | interface | `./ui/Chart` | — |
+| `AxisController` | class | `./interaction/AxisController` | — |
+| `AxisControllerAxisOptions` | interface | `./interaction/AxisController` | — |
+| `AxisControllerOptions` | interface | `./interaction/AxisController` | — |
+| `AxisPosition` | type | `./ui/ChartLayout` | — |
+| `AxisRenderTarget` | type | `./interaction/AxisController` | — |
+| `AxisScale` | type | `./interaction/AxisController` | — |
+| `AxisTickFormat` | type | `./interaction/AxisController` | — |
+| `AxisTickFormatter` | type | `./interaction/AxisController` | — |
+| `AxisTimeZone` | type | `./interaction/AxisController` | — |
+| `AxisTitleConfig` | interface | `./ui/Chart` | — |
+| `BufferOverflowStrategy` | type | `./core/types` | — |
+| `BuiltInAxisScale` | type | `./interaction/AxisController` | — |
+| `Camera2D` | class | `./interaction/Camera2D` | — |
+| `Chart` | class | `./ui/Chart` | — |
+| `ChartFrameStats` | interface | `./ui/Chart` | — |
+| `ChartHoverState` | interface | `./ui/Chart` | — |
+| `ChartLayoutReservation` | interface | `./ui/Chart` | — |
+| `ChartOptions` | interface | `./ui/Chart` | — |
+| `ChartPickGroup` | type | `./ui/Chart` | — |
+| `ChartPickItem` | interface | `./ui/Chart` | — |
+| `ChartPickMode` | type | `./ui/Chart` | — |
+| `ChartPickOptions` | interface | `./ui/Chart` | — |
+| `ChartPlugin` | interface | `./ui/Chart` | — |
+| `ChartPluginHandle` | interface | `./ui/Chart` | — |
+| `ChartPointerEventState` | interface | `./ui/Chart` | — |
+| `ChartPointerEventType` | type | `./ui/Chart` | — |
+| `ChartScreenshotOptions` | interface | `./ui/Chart` | — |
+| `ChartSelectEvent` | interface | `./ui/Chart` | — |
+| `ChartSeriesClickEvent` | interface | `./ui/Chart` | — |
+| `ChartSeriesState` | interface | `./ui/Chart` | — |
+| `ChartTheme` | interface | `./ui/theme` | — |
+| `ChartTitleConfig` | interface | `./ui/Chart` | — |
+| `ChartViewportChangeEvent` | interface | `./ui/Chart` | — |
+| `CssColor` | type | `./ui/theme` | — |
+| `CustomAxisScale` | interface | `./interaction/AxisController` | — |
+| `Dataset` | interface | `./core/types` | — |
+| `DEFAULT_CHART_THEME` | const | `./ui/theme` | — |
+| `LODBucket` | interface | `./core/types` | — |
+| `LODStrategy` | type | `./core/types` | — |
+| `LODView` | interface | `./core/types` | — |
+| `MinMaxPyramid` | class | `./core/MinMaxPyramid` | — |
+| `MinMaxSegmentCopyDataset` | interface | `./core/types` | Optional high-performance min/max extraction capability for dense rendering. Implementations can use pyramids, segment trees, database aggregates, or analytic/procedural envelopes to emit renderer-ready min/max buckets. |
+| `MinMaxSegmentLayout` | type | `./core/types` | — |
+| `OhlcDataset` | interface | `./core/types` | — |
+| `OhlcRingBuffer` | class | `./core/OhlcDataset` | — |
+| `OhlcRingBufferOptions` | interface | `./core/OhlcDataset` | — |
+| `PanIntent` | interface | `./interaction/types` | — |
+| `RangeMinMaxDataset` | interface | `./core/types` | — |
+| `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. |
+| `ResolvedChartTheme` | interface | `./ui/theme` | — |
+| `RgbaColor` | type | `./ui/theme` | — |
+| `RingBuffer` | class | `./core/RingBuffer` | — |
+| `RingBufferOptions` | interface | `./core/RingBuffer` | — |
+| `RingBufferOverflow` | type | `./core/RingBuffer` | — |
+| `SampleCopyLayout` | type | `./core/types` | — |
+| `SeriesConfig` | interface | `./core/types` | — |
+| `SeriesMode` | type | `./core/types` | — |
+| `SeriesSample` | interface | `./core/types` | — |
+| `SeriesStore` | class | `./core/SeriesStore` | — |
+| `SeriesStyle` | interface | `./core/types` | — |
+| `SeriesYAxis` | type | `./core/types` | — |
+| `StaticDataset` | class | `./core/StaticDataset` | — |
+| `StaticOhlcDataset` | class | `./core/OhlcDataset` | — |
+| `TextOverlayConfig` | interface | `./ui/Chart` | — |
+| `ThemeColor` | type | `./ui/theme` | — |
+| `TimeRange` | interface | `./core/types` | — |
+| `TypedSeriesConfig` | type | `./ui/Chart` | — |
+| `UniformRingBuffer` | class | `./core/UniformRingBuffer` | High-throughput ring buffer for uniformly spaced X values. Store only Y samples and derive X as `xStart + index * xStep`. This is the fastest built-in dataset for live telemetry, signals, and other fixed-rate streams because appends copy a single typed array and min/max extraction uses a block segment tree over the physical ring. |
+| `UniformRingBufferOptions` | interface | `./core/UniformRingBuffer` | — |
+| `Viewport` | interface | `./core/types` | — |
+| `ViewportPolicy` | interface | `./interaction/types` | — |
+| `VisiblePointCopyDataset` | interface | `./core/types` | Optional high-performance extraction capability for point/scatter datasets. Implementations should cull against the full 2D viewport and may sample in screen space so dense point clouds respond to both X and Y zoom. |
+| `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. |
+| `YAppendableDataset` | interface | `./core/types` | — |
+| `ZoomAxis` | type | `./interaction/types` | — |
+| `ZoomIntent` | interface | `./interaction/types` | — |
+
+</details>
+<!-- README_DOCS_END -->
 
 ## Architecture
 
@@ -246,12 +485,25 @@ src/
   ui/            # Orchestrator (Chart)
 ```
 
+## Contributing
+
+Keep pull requests small and focused. One feature or fix per PR.
+
+Branch flow:
+
+- `development` is the integration branch for regular work.
+- Open feature/fix PRs into `development`.
+- Open release PRs from `development` into `main` with the version and changelog already updated.
+- Merging an unpublished version to `main` runs CI, publishes npm, creates the `vX.Y.Z` tag, and creates the GitHub Release.
+
 ## Development
 
 ```bash
 bun install
-bun run dev          # Vite dev server → preview/
-bun run build        # Package build (JS + declarations)
-bun test             # Tests
-bun run typecheck    # TypeScript strict check
+bun run dev             # Vite dev server → preview/
+bun run ci              # Typecheck + tests + package build
+bun run build           # Package build (JS + declarations)
+bun test                # Tests
+bun run typecheck       # TypeScript strict check
+bun run version:patch   # Prepare package.json + changelog for a patch release PR
 ```