@zakkster/lite-charts 1.0.0 → 1.1.0

package/llms.txt

@@ -1,30 +1,49 @@
 # @zakkster/lite-charts
 
 > Reactive, zero-GC chart library built on @zakkster/lite-scene. Signals
-> for data, dimensions, theme, series visibility. v1.0.0 ships 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 boundaries are strict and verified with esbuild tree-
-> shaking: line bundle = 24 KB minified, bubble = 22 KB, pie = 14 KB,
-> radar = 13 KB. Importing only radar drops every axis-chart AND every
-> polar-slice helper. Importing only bubble drops every polar AND radar
-> helper. Etc. Kernel-side auto-resize: omit width / height from config
-> and the chart observes its mount container via ResizeObserver,
-> updating through the existing reactive graph (synchronous initial read
-> avoids size pop; rAF-throttled updates coalesce burst events). Falls
-> back gracefully (keeps default size) when ResizeObserver is absent.
-> Bubble uses sqrt size scale by default (area-proportional, Tukey
-> convention): r = sqrt(rMin^2 + t*(rMax^2 - rMin^2)). Radar precomputes
-> cos/sin per axis into Float64 tables -- polygons, grid rings, and
-> spokes share them, zero per-frame trig. Hit detection is nearest-vertex
-> within 12 px across visible series. Pie and donut share SLICE_RENDERER;
-> only innerRadius default differs (0 vs 0.5). Polar angles use Float64
-> (Float32(PI/2) widens enough to misclassify boundary hits). 196/196
-> tests pass. ESM-only. Single-file ~4.9k lines. Three peer deps
-> (lite-signal, lite-scene, lite-axis), zero runtime deps. MIT.
-> See ROADMAP.md for forward plan: v1.1 stacked bar + SVG export, v1.2
-> heatmap + scatter + @zakkster/lite-delaunay for dense hit-test, v1.3
-> log scale + pan/zoom, v1.4 time-series + annotations.
+> for data, dimensions, theme, series visibility. v1.1.0 ships NINE
+> chart types on FOUR independent kernels: line/area/bar/bubble/scatter
+> on the axis kernel, pie/donut on the polar slice kernel, radar on its
+> own kernel, and heatmap on its own grid kernel. Kernel boundaries are
+> strict and verified with esbuild tree-shaking: line bundle = 23 KB
+> minified, bar = 25 KB (stacked + rounded + hover), bubble = 25 KB
+> (spatial-index + multi-series + per-point color), scatter = 22 KB,
+> pie = 13 KB, radar = 13 KB, **heatmap = 10.5 KB (the smallest)**.
+> all-nine total: ~70 KB. Kernel-side auto-resize: omit width / height
+> from config and the chart observes its mount container via
+> ResizeObserver.
+> Heatmap: createHeatmap rides createBaseGridChart -- a kernel that
+> knows nothing about axis / polar / radar code. Two band scales (x +
+> y) reuse makeBandScale math; the y band scale uses the same +y-down
+> convention so yBand.leftEdge(0) is the topmost cell. Cell storage:
+> flat Float32Array indexed yIdx*nx + xIdx; Uint8Array presentMask
+> for sparse data (missing cells render as empty space, hit-test
+> returns null for them). Per-cell colors precomputed at extract into
+> state.cellColors: string[] so the draw loop is just
+> fillStyle = cellColors[i]; fillRect(...) -- zero alloc per cell.
+> Default ramp is linear RGB interpolation between two endpoint hex
+> colors via _parseHexColor + _lerpRGBString. The colorFn(v, vMin,
+> vMax) -> css config overrides entirely for OKLCH ramps, quantile
+> binning, diverging schemes. Hit-test is O(1) -- one xBand.invert +
+> one yBand.invert + a presence-mask check. chart.hover is a
+> signal-style reactive accessor with .peek() escape hatch. Mouse
+> events on canvas drive moveHover / hideHover automatically.
+> Bar polish (this release): postExtract hook for stacked layout,
+> native ctx.roundRect with arcTo fallback for rounded corners,
+> per-bar hover tint via reusable cached tinted-color strings.
+> Multi-series bubble: per-point color via colorKey, global size
+> domain across visible series so equal sizes render at equal radii
+> regardless of which series owns the point.
+> Pluggable spatial index: SpatialIndex / SpatialIndexFactory
+> contract auto-engages at ~1000 points for bubble + scatter
+> hit-test; @zakkster/lite-delaunay is the intended default but
+> optional. 231/231 tests pass.
+> ESM-only. Single-file ~6.2k lines. Four peer deps (lite-signal,
+> lite-scene, lite-axis required; lite-delaunay optional), zero
+> runtime deps. MIT.
+> See ROADMAP.md for forward plan: v1.2 heatmap polish (per-row /
+> per-column highlight, quantile binning), v1.3 SVG export, v1.4 log
+> scale + pan/zoom, v1.5 time-series + annotations.
 
 ## Why use this library
 
@@ -37,48 +56,39 @@
 
 ## When NOT to use
 
-- You need SVG output -- coming v1.1. Today only `exportPNG` (canvas
-  `toDataURL`).
+- You need SVG output -- coming v1.3. Today only `exportPNG`.
 - You need server-side rendering -- the renderer is Canvas2D-bound.
-- You need stacked bars today -- only grouped multi-series in v1.0.0;
-  stacked layout lands v1.1.
-- You need heatmap or scatter today -- on the v1.2.0 roadmap with the
-  new grid kernel and the `@zakkster/lite-delaunay` integration.
-- You need legend virtualization for hundreds of series -- v1.4.0 via
-  `@zakkster/lite-virtual`.
-- You need `<2000` points and don't care about GC -- Chart.js is simpler.
+- You need `<200` points across one chart and don't care about GC --
+  Chart.js is simpler and the bundle-size argument is weaker at that
+  scale.
+- You need built-in heatmap, scatter, or polar-area charts today -- on
+  the roadmap (v1.2.0 +) but not yet shipped.
 
 ## Module shape
 
 ESM-only. Named exports from the single `Charts.js` entry:
 
 ```ts
-// Axis kernel
-function createLineChart(config: LineChartConfig):     Chart;
-function createAreaChart(config: AreaChartConfig):     Chart;
-function createBarChart(config:  BarChartConfig):      Chart;
+function createLineChart(config: LineChartConfig): Chart;
+function createAreaChart(config: AreaChartConfig): Chart;
+function createBarChart(config: BarChartConfig): Chart;
 function createBubbleChart(config: BubbleChartConfig): Chart;
-
-// Polar slice kernel (pie + donut share SLICE_RENDERER; only the
-// innerRadius default differs).
-function createPieChart(config:   PieChartConfig):     PolarChart;
-function createDonutChart(config: DonutChartConfig):   PolarChart;
-
-// Radar kernel (third independent kernel)
-function createRadarChart(config: RadarChartConfig):   RadarChart;
-
-// Stubs that throw at runtime so version mismatches surface immediately.
-// These ship in v1.2.0 on a new createBaseGridChart kernel.
-function createScatterChart(): never;
-function createHeatmap():      never;
-
-// Test-only export -- NOT part of the stable public API. Pure helpers
-// for white-box unit testing; the leading underscore signals private.
-// Production code that imports only chart factories never references
-// _testHelpers, so the bundler drops it and everything it pins.
-const _testHelpers: { /* decimateMinMax, makeBandScale, ... */ };
+function createScatterChart(config: ScatterChartConfig): Chart;
+function createPieChart(config: PieChartConfig): Chart;
+function createDonutChart(config: DonutChartConfig): Chart;
+function createRadarChart(config: RadarChartConfig): Chart;
+function createHeatmap(config: HeatmapConfig): Chart;
+
+// Public interface for the spatial-index integration (v1.2.0-alpha.0+).
+interface SpatialIndex {
+    findNearest(qx, qy, k, maxDistSq, outIndices, outDistSq): number;
+    dispose(): void;
+}
+type SpatialIndexFactory = (pxs, pys, n) => SpatialIndex;
 ```
 
+Nine chart types across four strictly-independent kernels.
+
 `AreaChartConfig extends LineChartConfig` with three additional fields:
 
 ```ts
@@ -395,77 +405,217 @@ createLineChart({
   many `node.set()` calls per signal write, use
   `schedule: (fn) => queueMicrotask(fn)`. The bench documents this clearly.
 
-## Roadmap
-
-- v1.0.0-beta.0 - beta.3: line + area polish (interp, markers, theme, gridlines,
-  zero-alloc crosshair, DPR fix)
-- v1.0.0: line + area API lock
-- v1.1.0-alpha.0: createBarChart (band scale, grouped, O(1) hit detection)
-- **v1.2.0-alpha.0: architectural refactor.** _createChartImpl(config,
-  renderKind) extracted into createBaseAxisChart(config, renderer) + per-
-  chart renderer objects (LINE_RENDERER, AREA_RENDERER, BAR_RENDERER). 22
-  renderKind branches eliminated. Polymorphic dispatch via renderer
-  interface: buildXAccessor, createXScale, extractData, updateXScale,
-  buildXAxis, makeDrawFn, hitTest, lookupRow, formatTooltipHeader.
-  rendererCtx singleton (xScale, yScale, opts, categoriesRef) mutated in
-  place -- preserves zero-alloc on hot path. _testHelpers moved to separate
-  top-level export so chart._internal doesn't pin pure helpers.
-- **v1.2.0-alpha.1: pie + donut chart family.** New
-  createBasePolarChart kernel -- completely independent from
-  createBaseAxisChart. Polar state struct: parallel arrays for values
-  (Float32), labels (string[]), colors, visibility (Uint8), startAngles
-  (Float64 -- Float32 widens PI/2 enough that exact-boundary hits land in
-  wrong slice), arcAngles (Float64). extractSliceData normalizes array-of-
-  objects, parallel-arrays, or plain number arrays. computeSliceGeometry
-  centers in plot rect with configurable inner radius. sliceHitTest is
-  O(n) atan2 + linear scan inside ring (n typically 3-12; binary search
-  overkill). makeSliceDrawFn renders wedge (pie) or arc-ring (donut) per
-  slice; hovered slice expands 4px. Per-slice legend with click-to-toggle
-  visibility -- hidden slices give up their wedge, others grow to fill.
-  Pie and donut share SLICE_RENDERER; only innerRadius default differs
-  (0 vs 0.5; overridable). Pie bundle 13 KB minified (no axis kernel),
-  line bundle 23 KB (no polar kernel). 29 new tests, 148 total.
-- v1.2.0-alpha.2: slice colour resolution bug fix (raw CSS-var leaked
+## Release history (shipped)
+
+- v1.0.0-beta.0 - beta.3: line + area polish (interp, markers, theme,
+  gridlines, zero-alloc crosshair, DPR fix)
+- v1.0.0 alpha.0: architectural refactor.
+  `_createChartImpl(config, renderKind)` extracted into
+  `createBaseAxisChart(config, renderer)` + per-chart renderer objects
+  (LINE_RENDERER, AREA_RENDERER, BAR_RENDERER). 22 renderKind branches
+  eliminated. Polymorphic dispatch via renderer interface:
+  buildXAccessor, createXScale, extractData, updateXScale, buildXAxis,
+  makeDrawFn, hitTest, lookupRow, formatTooltipHeader. `rendererCtx`
+  singleton (xScale, yScale, opts, categoriesRef) mutated in place --
+  preserves zero-alloc on hot path.
+- v1.0.0 alpha.1: pie + donut chart family. New `createBasePolarChart`
+  kernel -- completely independent from `createBaseAxisChart`. Polar
+  state struct: parallel arrays for values (Float32), labels (string[]),
+  colors, visibility (Uint8), startAngles (Float64 -- Float32 widens
+  PI/2 enough that exact-boundary hits land in wrong slice), arcAngles
+  (Float64). `extractSliceData` normalizes array-of-objects, parallel-
+  arrays, or plain number arrays. `computeSliceGeometry` centers in
+  plot rect with configurable inner radius. `sliceHitTest` is O(n)
+  atan2 + linear scan inside ring (n typically 3-12). `makeSliceDrawFn`
+  renders wedge (pie) or arc-ring (donut) per slice; hovered slice
+  expands 4 px. Pie and donut share SLICE_RENDERER; only innerRadius
+  default differs (0 vs 0.5).
+- v1.0.0 alpha.2: slice colour resolution bug fix (raw CSS-var leaked
   into canvas fillStyle); demo gets ResizeObserver-backed responsive
-  sizing via a `responsiveWidth(containerId, fallback)` helper.
-- **v1.2.0-alpha.3: createBubbleChart on the axis kernel.**
-  New BUBBLE_RENDERER. Each point becomes a circle with AREA
-  proportional to a third dimension via sqrt scale (default; linear
-  available). Pixel radii computed at extract time:
-  r = sqrt(rMin^2 + t*(rMax^2 - rMin^2)). New seriesState fields rs
-  (raw sizes) and prs (pixel radii) -- both null on non-bubble series,
-  zero extra memory. extractBubbleData wraps extractSeriesData, adds
-  size extraction + computeBubbleRadii in one pass. Hit-test signature
-  on the axis kernel extended from (canvasX, primary, xScale, ctx) to
-  (canvasX, canvasY, primary, xScale, ctx) -- line/area/bar tests ignore
-  canvasY; bubble uses both for circle-containment with smallest-on-top
-  tie-breaking on overlap. Bubble bundle 22 KB minified; tree-shake
-  verified to drop all polar + bar + interp helpers. 10 new tests, 158
-  total. Single-series only -- multi-series + per-point colour encoding
-  land in v1.3.0.
-- **v1.2.0-alpha.4 (current): createRadarChart on a third independent
-  kernel.** Multi-axis polygon layout: N axes (min 3, typical 5-8)
-  spoked from a shared center; each series is a polygon connecting one
-  value-per-axis vertex. computeRadarGeometry precomputes cos/sin per
-  axis into Float64 tables -- polygons, grid rings, and spokes all
-  share them, zero per-frame trig. radarHitTest is nearest-vertex
-  within 12 px across visible series (O(series * axes), trivial).
-  Spoke labels auto-align based on angular position (cosA > 0.2 ->
-  left-align, < -0.2 -> right-align, near-vertical -> center). Three
-  drawing layers (grid -> polygons -> spokes+labels) as separate scene
-  nodes for natural z-ordering. Auto-domain anchors at 0 when min/max
-  ratio < 0.5 (scored-radar convention); explicit domain: [vMin, vMax]
-  overrides. 18 new tests, 176 total. Radar bundle 13 KB minified --
-  drops every axis-chart helper AND every polar-slice helper. The
-  three kernels (axis, polar-slice, radar) are now strictly independent.
-- v1.2.0: lock seven-chart API (line, area, bar, bubble, pie, donut, radar)
-- v1.3.0: createBaseGridChart + createHeatmap (2D categorical,
-  color-mapped); multi-series bubble + per-point colour encoding;
-  @zakkster/lite-delaunay for O(log n) nearest-point hit-test on dense
-  scatter/bubble clouds (> ~1000 points; sweepline Delaunay -> Voronoi
-  dual extraction). Scatter chart rides on the same spatial index.
-- v1.4.0: stacked bar, per-bar hover, rounded corners, SVG export
-- v1.5.0: log scale, pan + zoom, legend virtualization
+  sizing.
+- v1.0.0 alpha.3: createBubbleChart on the axis kernel. New
+  BUBBLE_RENDERER. Each point becomes a circle with AREA proportional
+  to a third dimension via sqrt scale (default; linear available).
+  Pixel radii computed at extract time:
+  r = sqrt(rMin^2 + t*(rMax^2 - rMin^2)). New seriesState fields `rs`
+  (raw sizes) and `prs` (pixel radii) -- both null on non-bubble
+  series, zero extra memory. Hit-test signature on the axis kernel
+  extended from (canvasX, primary, xScale, ctx) to (canvasX, canvasY,
+  primary, xScale, ctx) -- line/area/bar tests ignore canvasY; bubble
+  uses both for circle-containment with smallest-on-top tie-breaking
+  on overlap.
+- v1.0.0 alpha.4: createRadarChart on a third independent kernel.
+  Multi-axis polygon layout: N axes (min 3, typical 5-8) spoked from a
+  shared center; each series is a polygon connecting one value-per-axis
+  vertex. `computeRadarGeometry` precomputes cos/sin per axis into
+  Float64 tables -- polygons, grid rings, and spokes all share them,
+  zero per-frame trig. `radarHitTest` is nearest-vertex within 12 px
+  across visible series. Spoke labels auto-align based on angular
+  position. Three drawing layers (grid -> polygons -> spokes+labels) as
+  separate scene nodes for natural z-ordering.
+- v1.0.0: kernel-side auto-resize. `_wireAutoSize` shared helper; omit
+  width / height from config and the chart observes its container via
+  ResizeObserver. Three modes per dimension: explicit static, explicit
+  reactive (signal/fn), or implicit (auto-observe). Synchronous
+  initial read avoids size pop; rAF-throttled updates coalesce burst
+  events. Falls back gracefully (keeps default size) when
+  ResizeObserver is absent. 182 tests, full tree-shake verification.
+- **v1.1.0: bar layout polish.** Stacked bars via new
+  `postExtract(states, ctx)` renderer hook -- the kernel calls it
+  after the per-series extract loop, bar's hook fills per-series
+  `state.stackBottoms` / `state.stackTops` (Float32Arrays, lazy-
+  allocated via ensureFloat32) with a visibility-aware cumulative
+  accumulator in declaration order; the kernel then re-aggregates
+  y-domain to pick up the total stack height. Hidden series excluded
+  from the stack; surviving segments snap down on legend toggle.
+  Negative values clamp to 0 (diverging stacks deferred to a future
+  cut). Rounded corners on the end opposite the baseline (top for
+  positive bars, bottom for negative) via native `ctx.roundRect`
+  where available + hand-traced `arcTo` fallback for older Safari;
+  radii capped at min(w,h)/2. Per-bar hover tint as a CSS-color
+  overlay keyed on the chart's `crosshairDataRef.snapIdx`; default
+  low-alpha white works against any series color without color
+  parsing, opt out with `hoverTint: false`. All three opt-in;
+  defaults match v1.0.0 exactly. Bar bundle 25 KB (+1.6 KB);
+  line/area/bubble bundles +~300 bytes for the kernel's null-check
+  on postExtract; pie/donut/radar unchanged. Three kernels still
+  strictly independent -- verified. 196 tests.
+- **v1.2.0-alpha.0: spatial-index foundation.** Pluggable
+  nearest-neighbor index for O(log n) hit-test on dense point clouds
+  (bubble first; scatter + heatmap will ride the same interface in
+  alpha.1+). Public contract on `Charts.d.ts`:
+  `SpatialIndexFactory = (pxs, pys, n) -> SpatialIndex` where the
+  index exposes `findNearest(qx, qy, k, maxDistSq, outIndices,
+  outDistSq) -> count` (caller-owned output buffers; zero alloc per
+  query) and `dispose()`. `@zakkster/lite-delaunay` is the intended
+  default (sweepline Delaunay -> half-edge mesh -> Voronoi-dual walk
+  for the cursor's cell) but optional -- k-d tree, uniform-grid, or
+  any custom impl works equally well. lite-charts adds it as an
+  optional peer dep via `peerDependenciesMeta.optional`. New
+  `BUBBLE_RENDERER` config: `spatialIndex: factory` and
+  `spatialIndexThreshold` (default 1000). Below threshold the v1.0.0
+  linear scan stays the path. Index is lazy-built on the first hit-
+  test after extract, cached across queries, disposed on data /
+  scale change (extract calls `_disposeSpatialIndex`) AND on chart
+  unmount (via new `renderer.cleanup(states)` hook on the axis
+  kernel, symmetric with v1.1.0's `postExtract`). `k > 1` matters
+  for bubble: overlapping discs mean the nearest CENTER may not be
+  the one whose disc contains the cursor; the renderer asks for
+  `K = 8` candidates and post-filters by disc containment +
+  smallest-r tie-break, preserving v1.0.0 "visually-topmost wins on
+  overlap" semantics. Cached `state.prMaxSq` (max pixel-radius
+  squared) gives the index a tight maxDistSq upper bound.
+  `state._hitIndices` (Int32Array(8)) and `state._hitDistSq`
+  (Float32Array(8)) are stable refs that the index writes into.
+  Bubble bundle ~22 KB -> ~23 KB. Line / area / bar / pie / donut /
+  radar unchanged. 8 new tests. 204 total.
+- **v1.2.0-alpha.1: createScatterChart.** New `SCATTER_RENDERER` on
+  the axis kernel. Eighth chart type ships. Bubble's simpler sibling:
+  no size dimension, every marker the same pixel radius
+  (`markerSize`, default 4), hit-test snaps to nearest point within
+  `hitTolerance` disc (default `markerSize + 4`). Reuses the
+  spatial-index foundation from alpha.0 with `k = 1` (no overlap
+  concerns). `_extractScatterData` disposes any existing spatial
+  index per-extract so the index rebuilds lazily on data / scale
+  change. `_scatterCleanup` symmetric with bubble's: disposes
+  indices on unmount. Scatter bundle ~24 KB. Adds nothing to other
+  bundles (verified). 6 new tests. 210 total.
+- **v1.2.0-alpha.2: multi-series bubble + per-point color +
+  global size domain.** `BUBBLE_RENDERER` gains a `postExtract` hook
+  (`_bubblePostExtract`) that computes a GLOBAL size domain across
+  visible series and re-runs `computeBubbleRadii` on every state.
+  Single-series charts short-circuit -- the v1.0.0 fast path stays
+  in effect when only one series is visible. Per-series state gets
+  `state._stateIdx = i` at construction so the bubble's `lookupRow`
+  can tell which series got hit and scope the tooltip to that
+  series. Crosshair state gains `snapSeriesIdx` (default -1 --
+  non-bubble charts never set it). `_bubbleHitTest` iterates
+  `ctx.seriesStates` rather than checking only `primary`. Each
+  visible series' bubbles get tested (linear scan or spatial index,
+  per its threshold). Returns `snapSeriesIdx` along with `snapIdx`.
+  `_initBubbleOpts` gains `colorKey` (string / number / fn). The
+  accessor uses `buildRawAccessor` (not `buildAccessor`) so color
+  strings like `'#ff0000'` are not `+v`-coerced to NaN.
+  `extractBubbleData` extracts per-point colors into `state.cs`
+  (plain string Array, lazy-allocated). Colors resolve once via
+  `resolveColor` at extract time -- CSS-var values like
+  `'--c-emerald'` become concrete strings the draw fn writes to
+  `ctx.fillStyle` directly. Bubble draw fn picks `state.cs[i]` per
+  row when set, falling back to the series fill otherwise. Zero
+  hot-path cost when `colorKey` is unset. Bubble bundle ~23 KB ->
+  ~24 KB. Test infra bumped lite-signal default registry to
+  `maxNodes: 32768` for 200+ chart-creations across the suite. 9
+  new tests. 219 total.
+- **v1.2.0-alpha.3 (current): createHeatmap + fourth kernel.**
+  New `createBaseGridChart(config, renderer)` kernel. Strictly
+  independent from axis / polar / radar kernels -- no cross-kernel
+  imports either direction. Heatmap bundle is 10.5 KB minified --
+  the smallest of the nine -- because the grid kernel has none of
+  the axes / interpolation / decimation / markers / scale-math /
+  multi-series weight of the axis kernel. Two band scales (x + y)
+  reuse `makeBandScale` math; the y band scale uses the same
+  +y-down convention so `yBand.leftEdge(0)` is the topmost cell.
+  Cell storage: flat `Float32Array` indexed `yIdx * nx + xIdx`;
+  `Uint8Array` `presentMask` for sparse data (missing cells render
+  empty, hit-test returns null for them). Per-cell colors
+  precomputed at extract into `state.cellColors: string[]` so the
+  draw loop is `fillStyle = cellColors[i]; fillRect(...)` --
+  zero alloc per cell. Default ramp is linear RGB interpolation
+  between two endpoint hex colors via `_parseHexColor` +
+  `_lerpRGBString`. The `colorFn(v, vMin, vMax) -> css` config
+  overrides entirely for OKLCH ramps, quantile binning, diverging
+  schemes. Hit-test is O(1) -- one `xBand.invert` + one
+  `yBand.invert` + a presence-mask check. `chart.hover` is a
+  signal-style reactive accessor with `.peek()` escape hatch.
+  Mouse events on canvas drive `moveHover` / `hideHover`
+  automatically; tests drive them manually too. Axis labels
+  render inline (no lite-axis dep for the grid kernel since
+  categories are arbitrary strings). 12 new tests covering
+  category extraction, vMin/vMax, cell render counts (full +
+  sparse), default ramp endpoint correctness, custom colorFn,
+  hit-test (correct cell + missing + outside plot), data signal
+  reactivity, value labels, lifecycle. 231 total.
+
+## Capacity (lite-signal arena)
+
+lite-signal's default node-arena capacity is **1024 nodes**. Each
+axis-kernel chart uses ~45-60 active nodes (the dominant cost is
+the per-axis tick pool: each tick = `lineNode` + `textNode` = 2
+scene-node effects, at max 12 ticks per axis = ~24 effects per axis
+x 2 axes = ~48). Heatmap uses ~5 nodes (grid kernel renders cells
+through a single pathNode per layer). Pie / donut use ~25.
+
+**Default 1024 fits ~15-20 axis-kernel charts.** Dashboards or demos
+with more must bump the registry BEFORE constructing any chart:
+
+```js
+import { createRegistry, setDefaultRegistry } from '@zakkster/lite-signal';
+setDefaultRegistry(createRegistry({ maxNodes: 32768 }));
+```
+
+The lite-charts demo (`demo/index.html`) and the test suite both
+bump to 32768 for this reason. Bumping after charts are already
+constructed doesn't help those charts -- they read the current
+default registry at construction time.
+
+Each mount/unmount cycle leaves ~4 nodes of residue from
+construction-time signals (`widthAutoSig`, `plotBoundsSignal`,
+`scaleVersion`, etc.) that survive unmount so the chart can be
+remounted. For long-running apps that create and destroy many charts
+dynamically, this accumulates until the chart reference is dropped.
+A terminal-teardown `chart.destroy()` is on the roadmap for v1.3.
+
+## Forward plan
+
+- v1.2.0: heatmap polish -- per-row / per-column highlight on hover,
+  quantile binning, value-label auto-color (white-on-dark, dark-on-
+  light). Final v1.2.0 cut after the polish lands.
+- v1.3.0: SVG export across all nine charts. Mirrors every draw fn
+  through SVG path commands; reuses every projection function so
+  output is pixel-identical to canvas.
+- v1.4.0: log scale; pan + zoom; brushing primitives.
+- v1.5.0: time-series specialized variants; legend virtualization via
+  `@zakkster/lite-virtual`; annotation layer.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zakkster/lite-charts",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Reactive, zero-GC chart library. Signal-native data, scales, and dimensions; 60fps at 100k points; zero allocations in steady-state render. Built on @zakkster/lite-scene.",
   "type": "module",
   "main": "./Charts.js",
@@ -18,6 +18,7 @@
     "Charts.js",
     "Charts.d.ts",
     "README.md",
+    "CHANGELOG.md",
     "llms.txt",
     "LICENSE"
   ],
@@ -28,9 +29,10 @@
     "@zakkster/lite-signal": "^1.1.5"
   },
   "scripts": {
-    "test": "node --test --test-reporter=spec",
-    "test:gc": "node --expose-gc --test --test-reporter=spec",
-    "bench": "node --expose-gc bench/line-100k.mjs"
+    "test": "node --test --test-reporter=spec test/*.test.js",
+    "test:gc": "node --expose-gc --test --test-reporter=spec test/*.test.js",
+    "bench": "node --expose-gc bench/line-100k.mjs",
+    "demo": "node demo/serve.js"
   },
   "keywords": [
     "chart",