@zakkster/lite-charts 1.0.0 → 1.1.0

package/README.md

@@ -15,21 +15,29 @@
 > points at 60fps with sub-frame budget. Built on `@zakkster/lite-scene`
 > (Canvas2D scene graph), `@zakkster/lite-signal` (reactive core), and
 > `@zakkster/lite-axis` (tick generation). Three peer deps. ESM-only.
-> Single-file (~5k lines, three independent kernels). MIT.
-
-**Status:** v1.0.0 -- seven chart types on three independent kernels.
-Line, area, bar, bubble on the axis kernel; pie, donut on the polar
-slice kernel; radar on its own kernel. Kernel-side auto-resize via
-ResizeObserver -- omit `width` / `height` and the chart tracks its
-container. Tree-shake verified with esbuild: each chart's bundle
-contains only its kernel + renderer code. Zero runtime dependencies
-(three peers: `@zakkster/lite-signal`, `@zakkster/lite-scene`,
-`@zakkster/lite-axis`). 196/196 tests pass.
-
-See [ROADMAP.md](./ROADMAP.md) for the development history that led to
-this architecture and the forward plan (stacked bar, heatmap, scatter
-with `@zakkster/lite-delaunay` for O(log n) hit-test, log scale, pan +
-zoom).
+> ~1100 lines single file. MIT.
+
+**Status: v1.1.0** — nine chart types across four independent kernels.
+The headline addition is bar-chart layout polish (stacked bars, rounded
+corners, per-bar hover tint, all opt-in). This release also lands several
+features originally scoped for the v1.2.0 alpha train that proved stable
+enough to ship together:
+
+- **`createScatterChart`** — bubble's simpler sibling on the same axis
+  kernel; constant marker, no third dimension.
+- **`createHeatmap`** on a new `createBaseGridChart` kernel (10.5 KB
+  minified, the smallest of the nine bundles). Two band scales, flat
+  `Float32Array` cell storage, `Uint8Array` presentMask for sparse data,
+  per-cell color strings precomputed at extract for zero-allocation
+  draws. Default linear-RGB ramp; `colorFn` for custom mappings.
+- **Multi-series bubble** with per-point color via `colorKey` and a
+  global size domain across visible series.
+- **Pluggable spatial-index** (`SpatialIndex` / `SpatialIndexFactory`)
+  for O(log n) hit-test on dense point clouds.
+  `@zakkster/lite-delaunay` is the intended default but optional.
+
+**231/231 tests pass.** See [CHANGELOG.md](./CHANGELOG.md) for the full
+release contract and [ROADMAP.md](./ROADMAP.md) for the forward plan.
 
 ## Install
 
@@ -78,7 +86,7 @@ explicit re-render needed.
 | **Reactive data binding** | First-class signals | Imperative `.update()` | Imperative `.setData()` | Manual selection re-bind |
 | **100k points** | 1.4 ms / 4.7 ms p95 (CPU) | Drops frames | OK | Hand-rolled |
 | **Zero-GC steady state** | Yes (slab-based) | No | Mostly | No |
-| **Bundle (min, per-chart)** | 13-24 KB (see table) | 78 KB | 40 KB | 70+ KB |
+| **Bundle (min+gz)** | ~6 KB (alpha est.) | 78 KB | 40 KB | 70+ KB |
 | **Render substrate** | Canvas2D via lite-scene | Canvas2D | Canvas2D | SVG / Canvas |
 | **API style** | Vega-Lite middle ground | Imperative config | Hand-tuned | Composable primitives |
 | **Twitch Extension fit** | Yes (1MB / 3s budget) | No | Yes | No |
@@ -93,30 +101,30 @@ in a 1MB bundle without GC pauses.
 
 ```mermaid
 graph TD
-    User["User config + data signal"] --> Constructor["createLineChart"]
+    User[User config + data signal] --> Constructor[createLineChart]
     Constructor --> Normalize["Normalize: data shorthand -> series[]"]
-    Normalize --> Accessors["Build accessors x/y"]
-    Accessors --> InferType["Infer x-scale type"]
-    InferType --> StateAlloc["Allocate SeriesState slabs"]
-
-    StateAlloc --> Mount["mount(container)"]
-    Mount --> Scene["createScene from lite-scene"]
-    Scene --> Effect1["Effect: width/height -> plotBounds"]
-    Scene --> Effect2["Effect: data -> SoA extract -> scale -> pixels"]
-    Scene --> Axes["buildAxis x2 / lite-axis ticks"]
-    Scene --> SeriesNodes["path nodes / one per series"]
-    SeriesNodes --> DrawFn["makeLineDrawFn closure"]
+    Normalize --> Accessors[Build accessors x/y]
+    Accessors --> InferType[Infer x-scale type]
+    InferType --> StateAlloc[Allocate SeriesState slabs]
+
+    StateAlloc --> Mount[mount(container)]
+    Mount --> Scene[createScene from lite-scene]
+    Scene --> Effect1[Effect: width/height -> plotBounds]
+    Scene --> Effect2[Effect: data -> SoA extract -> scale -> pixels]
+    Scene --> Axes[buildAxis x2 / lite-axis ticks]
+    Scene --> SeriesNodes[path nodes / one per series]
+    SeriesNodes --> DrawFn[makeLineDrawFn closure]
 
     DrawFn --> PathSelect{"n > 2*cols?"}
     PathSelect -->|yes| Decimate["decimateMinMax kernel<br/>lifted from lite-canvas-graph"]
-    PathSelect -->|no| Polyline["Direct polyline / NaN-aware"]
-    Decimate --> Stroke["ctx.stroke"]
+    PathSelect -->|no| Polyline[Direct polyline / NaN-aware]
+    Decimate --> Stroke[ctx.stroke]
     Polyline --> Stroke
 
-    Signal["Any signal write"] --> LiteSignal["lite-signal sync flush"]
-    LiteSignal --> EffectsRun["Effects re-run"]
-    EffectsRun --> DirtyBridge["scaleVersion bump -> scene.markDirty"]
-    DirtyBridge --> SceneDraw["lite-scene drawAll / coalesced via _queued"]
+    Signal[Any signal write] --> LiteSignal[lite-signal sync flush]
+    LiteSignal --> EffectsRun[Effects re-run]
+    EffectsRun --> DirtyBridge[scaleVersion bump -> scene.markDirty]
+    DirtyBridge --> SceneDraw[lite-scene drawAll / coalesced via _queued]
     SceneDraw --> DrawFn
 ```
 
@@ -217,7 +225,7 @@ const chart = createLineChart({ ..., schedule: (fn) => queueMicrotask(fn) });
 
 ## Tooltip + crosshair
 
-On by default. The crosshair vertical line snaps to the
+On by default in v1.0.0-alpha.1. The crosshair vertical line snaps to the
 nearest sample on the primary series (binary search on sorted xs); markers
 on each additional series snap independently at the same domain x. The
 tooltip is canvas-drawn (no DOM overlay), so it remains headless-testable.
@@ -265,7 +273,7 @@ against the mock canvas (no event simulation needed). The mock canvas in
 `test/harness.js` doesn't implement `addEventListener`, so the DOM listener
 is skipped in headless contexts -- the programmatic API is the only way in.
 
-## Area chart
+## Area chart (v1.0.0-alpha.2)
 
 `createAreaChart(config)` shares everything with `createLineChart` -- same
 data shape, same accessors, same scales, same reactivity, same crosshair
@@ -295,7 +303,7 @@ for sparse data, decimated per-column for dense. The decimated path fills
 to the column's upper envelope (max), matching d3-area's default behavior;
 ribbon-style min-max area is a separate primitive in v1.1+.
 
-## Legend
+## Legend (v1.0.0-alpha.3)
 
 Rendered as a DOM element (sibling of the canvas, inside an auto-created
 flex wrapper), so it's keyboard-accessible (each row is a `<button>` with
@@ -354,10 +362,9 @@ const showOnly = (idx) => {
 };
 ```
 
-## Path interpolation
+## Path interpolation (v1.0.0)
 
-Six modes (seven names -- `'step'` is an alias for `'step-after'`).
-Default is `'linear'` (the polyline). Three step variants for
+Seven modes. Default is `'linear'` (the polyline). Three step variants for
 discrete data (telemetry, state machines, financial OHLC). Two smoothing
 modes for continuous data.
 
@@ -394,7 +401,7 @@ the direct path.
 renders independently). Smoothing modes assume contiguous data; if you need
 gaps, use linear or step.
 
-## Markers
+## Markers (v1.0.0)
 
 Marker dots at each sample point. Distinct from crosshair markers (those
 appear only on hover).
@@ -425,7 +432,7 @@ createLineChart({ data: dense, markers: { everyN: 10 } });
 **Decimation interaction:** markers are suppressed when the decimated path
 runs (>2x plot width). They'd be unreadable.
 
-## Theme reactivity
+## Theme reactivity (v1.0.0)
 
 Colors passed as `'--token-name'` get resolved against the container's
 computed style at mount. When you switch themes (dark mode, brand swap),
@@ -455,7 +462,7 @@ re-resolve. Legend swatches update too.
 > `chart.refreshTheme()`, or pair it with whatever theme-change event your
 > framework emits.
 
-## Bar chart
+## Bar chart (v1.1.0-alpha.0)
 
 ```javascript
 import { createBarChart } from '@zakkster/lite-charts';
@@ -508,7 +515,7 @@ multi-series (which is the right default -- stacked introduces design
 choices around shared y-domain and tooltip ordering that are worth a
 dedicated session).
 
-## Tree-shakeable architecture
+## Tree-shakeable architecture (v1.2.0)
 
 `lite-charts` is built on a tiny shared kernel that's parameterized by a
 **renderer object** per chart type:
@@ -535,17 +542,22 @@ rest, along with all their renderer-specific helpers.
 | Entry | Bundle size | What's included |
 |---|---|---|
 | `import { createLineChart }`    | **24 KB** | Line renderer + interp helpers + decimation + shared axis kernel + auto-resize |
-| `import { createAreaChart }`    | **24 KB** | Area renderer + interp helpers + decimation + shared axis kernel + auto-resize |
-| `import { createBarChart }`     | **23 KB** | Bar renderer + bandScale + bar helpers + shared axis kernel + auto-resize |
-| `import { createBubbleChart }`  | **22 KB** | Bubble renderer + sqrt size scale + distance hit-test + axis kernel + auto-resize |
-| `import { createPieChart }`     | **14 KB** | Slice renderer + polar kernel (no axes / scales / interp / decimation) + auto-resize |
-| `import { createDonutChart }`   | **14 KB** | Same as pie (shared renderer; only innerRadius default differs) |
+| `import { createAreaChart }`    | **25 KB** | Area renderer + interp helpers + decimation + shared axis kernel + auto-resize |
+| `import { createBarChart }`     | **25 KB** | Bar renderer + bandScale + bar helpers + shared axis kernel + auto-resize + **stack / rounded / hover (v1.1.0)** |
+| `import { createBubbleChart }`  | **25 KB** | Bubble renderer + sqrt size scale + distance hit-test + axis kernel + auto-resize + **spatial-index hook (v1.2.0-alpha.0)** + **multi-series + per-point color (v1.2.0-alpha.2)** |
+| `import { createScatterChart }` | **22 KB** | Scatter renderer + axis kernel + spatial-index hook (v1.2.0-alpha.1) |
+| `import { createPieChart }`     | **13 KB** | Slice renderer + polar kernel (no axes / scales / interp / decimation) + auto-resize |
+| `import { createDonutChart }`   | **13 KB** | Same as pie (shared renderer; only innerRadius default differs) |
 | `import { createRadarChart }`   | **13 KB** | Radar kernel (cos/sin tables, polygon draw, spokes, grid rings, vertex hit-test) -- zero axis/polar code |
-| All seven together              | **56 KB** | Axis + polar + radar kernels deduplicated; all renderers; shared utilities (resolveColor, ensureFloat32, mount/DPR, legend, auto-resize) shared once |
+| `import { createHeatmap }`      | **10.5 KB** | **Grid kernel (v1.2.0-alpha.3)** -- two band scales, Float32 cells, Uint8 presentMask, precomputed cell colors. Zero axis / polar / radar code. |
+| All nine together               | **~70 KB** | Four kernels deduplicated; all renderers; shared utilities (resolveColor, ensureFloat32, mount/DPR, legend, auto-resize) shared once |
 
-The ~400 byte uptick from earlier alphas is the kernel-side
-`ResizeObserver` helper -- shared across all kernels, inlined into
-each `mount()`.
+The v1.1.0 bar features (stacked layout, rounded corners, hover tint)
+add ~1.6 KB to the bar bundle (`computeBarStacks`, `_roundRectPath`,
+the per-bar tint overlay path). The kernel-level `postExtract` hook is
+a single null-check that minifies to a few dozen bytes; line / area /
+bubble bundles each pick up ~300 bytes for it. Pie / donut / radar are
+on different kernels and unaffected.
 
 **Auto-resize:** omit `width` / `height` from the config and the chart
 observes its mount container, updating dimensions on container resize
@@ -586,21 +598,16 @@ nearest-vertex hit-test.
 The same architecture extends to upcoming chart families:
 
 ```javascript
-// Pie + donut already ship -- shared SLICE_RENDERER on the polar kernel
-// (only the innerRadius default differs between the two factories).
+// v1.3.0 -- pie family (no axes, polar coordinates)
 const createBasePolarChart = (config, renderer) => { /* polar scaffold */ };
-export const createPieChart   = (c) => createBasePolarChart(_pieCfg(c),   SLICE_RENDERER);
-export const createDonutChart = (c) => createBasePolarChart(_donutCfg(c), SLICE_RENDERER);
+export const createPieChart   = (c) => createBasePolarChart(c, PIE_RENDERER);
+export const createDonutChart = (c) => createBasePolarChart(c, DONUT_RENDERER);
+export const createRadarChart = (c) => createBasePolarChart(c, RADAR_RENDERER);
 
-// Radar has its own kernel -- no renderer indirection in v1.0.0 because
-// there's only one radar variant. A second variant will trigger the
-// extraction into createBaseRadarChart(config, renderer).
-export const createRadarChart = (config) => { /* radar kernel inline */ };
-
-// Bubble ships too -- BUBBLE_RENDERER on the axis kernel.
+// v1.3.0 -- scatter family (extends axis chart with size dimension)
 export const createBubbleChart = (c) => createBaseAxisChart(c, BUBBLE_RENDERER);
 
-// v1.2.0 -- heatmap (2D categorical grid) lands on a new kernel.
+// v1.4.0 -- heatmap (2D categorical grid)
 const createBaseGridChart = (config, renderer) => { /* grid scaffold */ };
 export const createHeatmap = (c) => createBaseGridChart(c, HEATMAP_RENDERER);
 ```
@@ -639,37 +646,20 @@ v1.0.1) measures real paint.
 
 ### Zero-GC discipline
 
-Hot-path allocation target: <100 bytes/cycle. Current measurement on
-the `bench/line-100k.mjs` full-update cycle (200-sample mean after
-`global.gc()`) sits at roughly 270-330 bytes/cycle in Node 22, which is
-within `process.memoryUsage().heapUsed` noise band but still above the
-target. The library-side accounting:
-
-- **Per-frame line draw closure: 0 bytes.** Verified by the
-  `decimateMinMax` zero-alloc test in `test/Charts.test.js` (asserts
-  <100 B/call across 200 iterations under `--expose-gc`).
-- **Per-mousemove tooltip path: 0 row objects, 0 ctx objects.** The
-  `_tooltipRowPool` and `_tooltipFormatterCtx` are chart-instance
-  scratch; only `formatTooltipValue` allocates the value string itself
-  (already minimised via the shared char buffer + `String.fromCharCode`).
-  Identity-stability is enforced by the
-  `tooltip pool zero-alloc contract` test suite.
-- **Per-data-update y-domain: 0 bytes.** `_yDomScratch` is a 2-element
-  array filled by `_niceYDomainInto`; the legacy `niceYDomain` that
-  returned a fresh `[lo, hi]` is still exported on `_testHelpers` for
-  the test API but not used by the kernel.
-- **Axis label string concatenation via `String.fromCharCode`** still
-  allocates ~5-10 B per tick label rebuild (~120 B for 20 labels), but
-  only fires on size or domain change, not per frame. Switching to a
-  shared `Uint8Array` and stringifying only when text changes is a
-  v1.1 nicety.
-- **Bench harness `{xs, ys}` wrapper** is allocated by the test rotor
-  itself (~32 B per cycle), not the library. The honest framing: most
-  of the remaining heap delta is V8 measurement noise plus the bench
-  harness's own object literal.
-
-None of these touch the per-frame draw -- they're in the data / axis
-update path that fires only on actual changes, or in the bench harness.
+Hot-path allocations target: <100 bytes/cycle. Currently measured at ~270
+bytes/cycle, attributable to:
+
+- `{xs, ys}` object literal allocated by the test rotor (~16 B)
+- `niceYDomain` returning a fresh `[lo, hi]` tuple (~40 B; fix in v1.0.1)
+- Axis label string concatenation via `String.fromCharCode` (~120 B for 20
+  labels; fix by switching to a shared `Uint8Array` and only stringifying
+  when text actually changes)
+- Promise allocations from `queueMicrotask`-based draining
+
+None of these touch the per-frame line render -- they're in the data/axis
+update path that fires only on actual changes. The line draw closure
+itself is fully allocation-free in steady state (verified by the
+`decimateMinMax` zero-GC test in `test/charts.test.js`).
 
 ### What's measured, what isn't
 
@@ -679,21 +669,85 @@ update path that fires only on actual changes, or in the bench harness.
 | Decimation kernel zero-alloc | YES | Test asserts <100 bytes/call |
 | GPU paint cost | NO | Browser bench coming v1.0.1 |
 | Cold-start overhead | NO | Single-figure ms; not yet measured |
-| Bundle size minified | YES | Per-chart 13-24 KB, all seven ~56 KB (esbuild --bundle --minify) |
+| Bundle size min+gz | NO | Single-file ESM, ~6 KB estimated; not yet minified |
+
+## Capacity considerations
+
+lite-charts builds on `@zakkster/lite-signal`, which pre-allocates a
+fixed-size arena for its reactive nodes (signals + effects). The default
+capacity is **1024 nodes**, which fits a typical app with a few charts
+but can be exhausted on dashboards or demos with many simultaneous
+charts. If you see a `CapacityError: nodes capacity (1024) exceeded`,
+this is the cause.
+
+**Per-chart active node footprint** (measured against the v1.1.0
+implementation, on a chart with default options at typical sizes):
+
+| Chart | Active nodes |
+|---|---|
+| `createLineChart`    | ~43 |
+| `createAreaChart`    | ~43 |
+| `createBarChart`     | ~60 (3 series x 10 cats) |
+| `createBubbleChart`  | ~46 |
+| `createScatterChart` | ~46 |
+| `createPieChart`     | ~25 |
+| `createDonutChart`   | ~25 |
+| `createRadarChart`   | ~50 |
+| `createHeatmap`      | ~5 |
+
+The dominant cost on axis-kernel charts is the per-axis tick pool:
+each tick allocates a `lineNode` and a `textNode` (the label), each of
+which creates one lite-scene effect. At max tick count (12 per axis)
+that's ~24 effect nodes per axis x 2 axes = ~48 per chart. Heatmap is
+unusually cheap because the grid kernel renders cells through a single
+`pathNode`-per-layer rather than per-cell scene nodes.
+
+**Rule of thumb**: the default 1024-node arena fits ~15-20 axis-kernel
+charts on a single page. Multiply by the headroom you want for safety.
+
+**Bumping the arena** -- call `setDefaultRegistry` BEFORE constructing
+any chart:
+
+```js
+import { createRegistry, setDefaultRegistry } from '@zakkster/lite-signal';
+
+// 32k nodes -- comfortable headroom for dashboards or demos. The arena
+// is a few tens of KB of memory, so this is cheap.
+setDefaultRegistry(createRegistry({ maxNodes: 32768 }));
+
+// ... THEN construct your charts:
+import { createLineChart } from '@zakkster/lite-charts';
+const chart = createLineChart({ /* ... */ });
+```
+
+Order matters: charts read the *current* default registry at
+construction time. Bumping after charts are already created doesn't
+help those charts. The lite-charts demo (`demo/index.html`) bumps to
+32768 at the very top for this reason.
+
+**Mount/unmount note**: each mount/unmount cycle leaves a small
+residue (~4 reactive nodes per chart, from construction-time signals
+that aren't disposed in `unmount` so the chart can be remounted).
+For apps that create and destroy many charts dynamically over a long
+session, that residue accumulates until the chart reference is dropped
+and the lite-signal arena slots become eligible for reclamation.
+A dedicated terminal-teardown `chart.destroy()` is on the roadmap for
+v1.3.
 
 ## Roadmap
 
-v1.0.0 ships seven chart types on three independent kernels with
+v1.1.0 ships nine chart types on four independent kernels with
 kernel-side auto-resize. See [ROADMAP.md](./ROADMAP.md) for the full
 forward plan and the development history that led here. Headlines:
 
 | Version | Scope |
 |---|---|
-| **v1.0.0** (this) | Seven chart types, three kernels, auto-resize, 196 tests, full tree-shake verification |
-| v1.1.0 | Stacked + grouped bar; per-bar hover tint; rounded corners; SVG export across all charts |
-| v1.2.0 | `createHeatmap` on new grid kernel; multi-series bubble + per-point colour; `createScatterChart` with `@zakkster/lite-delaunay` for O(log n) nearest-point hit-test |
-| v1.3.0 | Log scale; pan + zoom; brushing primitives |
-| v1.4.0 | Time-series specialized variants; legend virtualization via `lite-virtual`; annotation layer |
+| **v1.0.0** | Seven chart types, three kernels, auto-resize, 182 tests, full tree-shake verification. |
+| **v1.1.0** (this release) | Bar polish (stacked, rounded corners, hover tint) **plus** the features prototyped over four internal alphas now landing in one go: pluggable spatial index for bubble hit-test (auto-engages ≥1000 points), `createScatterChart` (eighth type), multi-series bubble + per-point color + global size domain, and `createHeatmap` on a new `createBaseGridChart` kernel (10.5 KB minified, the smallest of the nine). 231 tests. |
+| v1.2.0 | Heatmap polish (per-row / per-column highlight on hover, quantile binning); doc + release notes. |
+| v1.3.0 | SVG export across all nine charts (mirrors every draw fn through SVG path commands; pixel-identical output). |
+| v1.4.0 | Log scale; pan + zoom; brushing primitives. |
+| v1.5.0 | Time-series specialized variants; legend virtualization via `lite-virtual`; annotation layer. |
 
 ## Ecosystem