@zakkster/lite-charts 1.0.0 → 1.1.0

package/Charts.js

@@ -1,15 +1,8 @@
 /**
  * @zakkster/lite-charts -- Reactive, zero-GC charts built on lite-scene.
  *
- * v1.0.0 ships seven chart types on three independent kernels:
- *   - axis kernel:  createLineChart, createAreaChart, createBarChart,
- *                   createBubbleChart   (LINE/AREA/BAR/BUBBLE_RENDERER)
- *   - polar kernel: createPieChart, createDonutChart   (SLICE_RENDERER)
- *   - radar kernel: createRadarChart   (no renderer indirection yet --
- *                   second variant will trigger the extraction)
- *
- * Tree-shake boundary: a bundle that imports only one factory keeps just
- * its kernel + renderer transitive closure. See README for measured sizes.
+ * v1.0.0-alpha.0 ships createLineChart only. Bar/area/scatter/pie follow
+ * in subsequent releases on the same substrate.
  *
  * Author:  Zahary Shinikchiev
  * License: MIT
@@ -446,10 +439,7 @@ const extractBarSeriesData = (state, data, xAccessor, yAccessor, categories) =>
         // Linear scan -- categories arrays are small (typically < 30). A
         // hash map adds setup cost that beats scan only beyond ~1000.
         for (let c = 0; c < categories.length; c++) {
-            if (categories[c] === catName) {
-                idx = c;
-                break;
-            }
+            if (categories[c] === catName) { idx = c; break; }
         }
         if (idx < 0) {
             idx = categories.length;
@@ -1043,19 +1033,163 @@ const makeAreaDrawFn = (state, refs, plotBoundsBox, yScale, opts) => (ctx) => {
     ctx.restore();
 };
 
+// ---------------------------------------------------------------------------
+// Rounded-rect path helper (v1.1.0)
+// ---------------------------------------------------------------------------
+//
+// Uses ctx.roundRect natively where available (Chrome 99+, Firefox 113+,
+// Safari 16+). Falls back to a hand-traced path with arc corners on older
+// engines. Per-corner radii (top-left / top-right / bottom-right / bottom-
+// left) so bar charts can round only the END opposite the baseline: top
+// for positive bars, bottom for negative bars, neither for stacked
+// middle segments (handled by passing radii of 0 where flatness is wanted).
+//
+// Each radius is clamped to half the shorter side so corners never overlap
+// on very thin bars -- the rect stays a valid path even at 1px wide.
+
+const _roundRectPath = (ctx, x, y, w, h, rTL, rTR, rBR, rBL) => {
+    if (w <= 0 || h <= 0) return;
+    const maxR = Math.min(w, h) * 0.5;
+    if (rTL > maxR) rTL = maxR;
+    if (rTR > maxR) rTR = maxR;
+    if (rBR > maxR) rBR = maxR;
+    if (rBL > maxR) rBL = maxR;
+    if (rTL < 0) rTL = 0;
+    if (rTR < 0) rTR = 0;
+    if (rBR < 0) rBR = 0;
+    if (rBL < 0) rBL = 0;
+    // Fast path: native roundRect (uniform args = all corners share radius,
+    // but the canvas spec accepts an array of 4 values for per-corner).
+    if (typeof ctx.roundRect === 'function') {
+        ctx.beginPath();
+        ctx.roundRect(x, y, w, h, [rTL, rTR, rBR, rBL]);
+        return;
+    }
+    // Hand-traced fallback. arcTo per corner; degrades to lineTo when r=0.
+    ctx.beginPath();
+    ctx.moveTo(x + rTL, y);
+    ctx.lineTo(x + w - rTR, y);
+    if (rTR > 0) ctx.arcTo(x + w, y, x + w, y + rTR, rTR);
+    ctx.lineTo(x + w, y + h - rBR);
+    if (rBR > 0) ctx.arcTo(x + w, y + h, x + w - rBR, y + h, rBR);
+    ctx.lineTo(x + rBL, y + h);
+    if (rBL > 0) ctx.arcTo(x, y + h, x, y + h - rBL, rBL);
+    ctx.lineTo(x, y + rTL);
+    if (rTL > 0) ctx.arcTo(x, y, x + rTL, y, rTL);
+    ctx.closePath();
+};
+
+// ---------------------------------------------------------------------------
+// Bar stack pass (v1.1.0)
+// ---------------------------------------------------------------------------
+//
+// When `stack: true`, each visible series contributes to a cumulative
+// per-category stack instead of getting a horizontal slot. The kernel
+// calls renderer.postExtract after all series are extracted; the bar
+// renderer routes that to computeBarStacks, which walks categories and
+// fills state.stackBottoms / state.stackTops per visible series. The
+// values are in data space (not pixel) so the y-scale's domain math
+// still works against them.
+//
+// MVP: positive values only. Negative values get clamped to 0 in the
+// stack (their bars effectively vanish). Diverging stacks (positive
+// AND negative around a baseline) land in a future cut.
+//
+// Each series' domainYMax is overwritten with the max of its OWN
+// stackTops -- so the kernel's existing y-domain union picks up the
+// total stack height (the last visible series' max stackTop). This
+// avoids a special-case in the kernel: stacking is opaque from the
+// kernel's perspective, the renderer just pre-cooks the y-domain.
+
+const computeBarStacks = (states, visibility, categoriesRef) => {
+    const nCats = categoriesRef.value.length;
+    if (nCats === 0) return;
+
+    // Lazy-allocate stack buffers per state. ensureFloat32 grows in place.
+    for (let s = 0; s < states.length; s++) {
+        const st = states[s];
+        st.stackBottoms = ensureFloat32(st.stackBottoms, nCats);
+        st.stackTops    = ensureFloat32(st.stackTops, nCats);
+        // Zero-fill to handle categories where this series has no row.
+        for (let c = 0; c < nCats; c++) {
+            st.stackBottoms[c] = 0;
+            st.stackTops[c] = 0;
+        }
+    }
+
+    // Cumulative accumulator per category. Walks series in declaration
+    // order -- the user controls stack order by series order, matching
+    // every other charting library's convention.
+    for (let c = 0; c < nCats; c++) {
+        let acc = 0;
+        for (let s = 0; s < states.length; s++) {
+            const visible = visibility[s] ? !!visibility[s]() : true;
+            if (!visible) continue;
+            const st = states[s];
+            // Find this series' value at category c (linear scan; nCats
+            // is small and st.n <= nCats so this stays O(nCats^2) in the
+            // worst case -- fine for the typical 5-30 category range).
+            let v = 0;
+            for (let r = 0; r < st.n; r++) {
+                if ((st.xs[r] | 0) === c) { v = st.ys[r]; break; }
+            }
+            if (v !== v || v < 0) v = 0;  // NaN guard + clamp negatives
+            st.stackBottoms[c] = acc;
+            st.stackTops[c] = acc + v;
+            acc += v;
+        }
+    }
+
+    // Overwrite each visible series' y-domain with the GLOBAL stack max
+    // (so the kernel's union picks the cumulative total, not per-series
+    // values).
+    let globalMax = 0;
+    for (let s = 0; s < states.length; s++) {
+        for (let c = 0; c < nCats; c++) {
+            if (states[s].stackTops[c] > globalMax) globalMax = states[s].stackTops[c];
+        }
+    }
+    if (globalMax <= 0) globalMax = 1;
+    for (let s = 0; s < states.length; s++) {
+        states[s].domainYMin = 0;
+        states[s].domainYMax = globalMax;
+    }
+};
+
+// Reset stack buffers when stacking is disabled mid-session (avoids stale
+// state.stackBottoms making the draw fn think stacking is still on).
+const _clearBarStacks = (states) => {
+    for (let s = 0; s < states.length; s++) {
+        states[s].stackBottoms = null;
+        states[s].stackTops = null;
+    }
+};
+
 // ---------------------------------------------------------------------------
 // Bar series draw function (v1.1.0)
 // ---------------------------------------------------------------------------
 //
-// One filled rect per category. For grouped layout (multi-series), each
-// series gets a slice of the band, offset symmetrically around the band
-// center: `offsetX = (seriesIdx - (totalSeries - 1) / 2) * groupWidth`.
-// For single-series, totalSeries=1 -> offsetX=0 -> full bandWidth used.
+// One filled rect per category. Three layouts, picked at draw time from
+// state shape + opts:
+//   (a) Single series  -- offsetX = 0, full bandwidth (minus innerPad)
+//   (b) Grouped        -- offsetX symmetric around band center,
+//                         barWidth = bandwidth/totalSeries
+//   (c) Stacked        -- offsetX = 0, full bandwidth, vertical extent
+//                         driven by state.stackBottoms[cat] / .stackTops[cat]
 //
-// Baseline defaults to 0; negative values render bars extending DOWNWARD
-// from the baseline.
+// Rounded corners apply to the END opposite the baseline so the bar
+// looks anchored: positive bars round top, negative bars round bottom,
+// stacked middle segments stay flat (the top segment's top corners
+// are still rounded -- segments below get visually capped by the
+// segment above).
+//
+// Hover tint: when the chart's crosshair is visible AND its snapIdx
+// matches the bar's category, an overlay rect is drawn on top with
+// the configured tint color. Crosshair read is a plain field access
+// on a mutable singleton -- no signal subscription needed since the
+// kernel's scene.markDirty path already redraws on crosshair change.
 
-const makeBarDrawFn = (state, refs, plotBoundsBox, xBandScale, yScale, seriesIdx, totalSeries, baseline, innerPadFrac) => (ctx) => {
+const makeBarDrawFn = (state, refs, plotBoundsBox, xBandScale, yScale, seriesIdx, totalSeries, baseline, innerPadFrac, cornerRadius, hoverTintRef, crosshairDataRef) => (ctx) => {
     if (!refs.visibleRef.value) return;
     const n = state.n;
     if (n === 0) return;
@@ -1066,33 +1200,96 @@ const makeBarDrawFn = (state, refs, plotBoundsBox, xBandScale, yScale, seriesIdx
     const plotT = pb.y;
     const plotB = pb.y + pb.h;
 
+    // Stacked mode? Detected by presence of pre-computed stackTops on the
+    // series state -- the postExtract pass populates them iff opts.stack
+    // is true. Stacked bars use full bandwidth (minus innerPadFrac), no
+    // horizontal offset; vertical extent comes from stackBottoms/stackTops
+    // in data space.
+    const stacked = state.stackBottoms !== null && state.stackTops !== null
+                 && state.stackBottoms !== undefined && state.stackTops !== undefined;
+
     const baselinePx = yScale.map(baseline);
-    const groupWidth = xBandScale.bandWidth / totalSeries;
-    const offsetX = (seriesIdx - (totalSeries - 1) / 2) * groupWidth;
-    // Inner padding shrinks each bar slightly within its group slot so
-    // adjacent grouped bars don't visually merge. Default 8% of group width.
-    const barW = groupWidth * (1 - innerPadFrac);
+    let barW, offsetX;
+    if (stacked) {
+        // Full bandwidth (minus innerPadFrac as a small visual gap between
+        // adjacent categories, mirroring the grouped-layout convention).
+        barW = xBandScale.bandWidth * (1 - innerPadFrac);
+        offsetX = 0;
+    } else {
+        const groupWidth = xBandScale.bandWidth / totalSeries;
+        offsetX = (seriesIdx - (totalSeries - 1) / 2) * groupWidth;
+        barW = groupWidth * (1 - innerPadFrac);
+    }
 
     ctx.fillStyle = refs.colorRef.value;
 
+    const tintColor = hoverTintRef && hoverTintRef.value ? hoverTintRef.value : null;
+    const hoveredCat = (crosshairDataRef && crosshairDataRef.visible)
+        ? (crosshairDataRef.snapIdx | 0)
+        : -1;
+
+    const useRound = cornerRadius > 0;
+
     for (let i = 0; i < n; i++) {
         const y = ys[i];
         if (y !== y) continue; // skip NaN
         const catIdx = xs[i] | 0;
-        const cx = xBandScale.map(catIdx) + offsetX;
-        const yPx = yScale.map(y);
-        let top = yPx < baselinePx ? yPx : baselinePx;
-        let h = Math.abs(yPx - baselinePx);
-        // Clamp to plot rect so bars don't extend past axes on outlier values.
-        if (top < plotT) {
-            h -= (plotT - top);
-            top = plotT;
-        }
-        if (top + h > plotB) {
-            h = plotB - top;
+
+        let top, h;
+        if (stacked) {
+            const sb = state.stackBottoms[catIdx];
+            const stt = state.stackTops[catIdx];
+            if (stt <= sb) continue;  // zero-height segment (e.g. value <= 0)
+            const yPxBottom = yScale.map(sb);
+            const yPxTop = yScale.map(stt);
+            top = yPxTop;
+            h = yPxBottom - yPxTop;
+        } else {
+            const yPx = yScale.map(y);
+            top = yPx < baselinePx ? yPx : baselinePx;
+            h = Math.abs(yPx - baselinePx);
         }
+
+        // Clamp to plot rect.
+        if (top < plotT) { h -= (plotT - top); top = plotT; }
+        if (top + h > plotB) { h = plotB - top; }
         if (h <= 0) continue;
-        ctx.fillRect(cx - barW / 2, top, barW, h);
+
+        const barX = xBandScale.map(catIdx) + offsetX - barW / 2;
+
+        // Decide per-corner radii. Round the end OPPOSITE the baseline so
+        // bars look anchored. For stacked, that's always the top (we only
+        // stack positive values in MVP); the topmost segment's top corners
+        // will be the visible rounded ones (lower segments get capped by
+        // the segment above, hiding their unrounded bottoms by adjacency).
+        let rTL = 0, rTR = 0, rBR = 0, rBL = 0;
+        if (useRound) {
+            const isPositive = stacked || y >= baseline;
+            if (isPositive) { rTL = cornerRadius; rTR = cornerRadius; }
+            else            { rBR = cornerRadius; rBL = cornerRadius; }
+        }
+
+        if (useRound) {
+            _roundRectPath(ctx, barX, top, barW, h, rTL, rTR, rBR, rBL);
+            ctx.fill();
+        } else {
+            ctx.fillRect(barX, top, barW, h);
+        }
+
+        // Hover tint overlay -- drawn on top of the bar fill with the same
+        // shape. Uses an explicit fillStyle assignment so we don't pollute
+        // the outer-loop fillStyle. Fixed color (no per-bar color math
+        // until v1.2.0 lite-color integration).
+        if (hoveredCat === catIdx && tintColor) {
+            ctx.fillStyle = tintColor;
+            if (useRound) {
+                _roundRectPath(ctx, barX, top, barW, h, rTL, rTR, rBR, rBL);
+                ctx.fill();
+            } else {
+                ctx.fillRect(barX, top, barW, h);
+            }
+            ctx.fillStyle = refs.colorRef.value;  // restore for next bar
+        }
     }
 };
 
@@ -1174,20 +1371,21 @@ const buildBarAxis = (parent, opts) => {
                     text: cats[i],
                 });
             } else {
-                labelPool[i].set({visible: false});
+                labelPool[i].set({ visible: false });
             }
         }
         for (let i = n; i < tickPool.length; i++) {
-            tickPool[i].set({visible: false});
-            labelPool[i].set({visible: false});
+            tickPool[i].set({ visible: false });
+            labelPool[i].set({ visible: false });
         }
     };
 
     const dispose = effect(rebuild);
-    return {axisGroup, dispose};
+    return { axisGroup, dispose };
 };
 
 
+
 const _charBuf = new Uint8Array(32);
 
 const formatTickValue = (v, axisFormat, timeUnit) => {
@@ -1254,9 +1452,9 @@ const buildAxis = (parent, opts) => {
     const updateSpine = () => {
         const pb = opts.plotBoundsBox;
         if (isX) {
-            spine.set({x: pb.x, y: pb.y + pb.h, dx: pb.w, dy: 0});
+            spine.set({ x: pb.x, y: pb.y + pb.h, dx: pb.w, dy: 0 });
         } else {
-            spine.set({x: pb.x, y: pb.y, dx: 0, dy: pb.h});
+            spine.set({ x: pb.x, y: pb.y, dx: 0, dy: pb.h });
         }
     };
 
@@ -1274,7 +1472,7 @@ const buildAxis = (parent, opts) => {
                 align: isX ? 'center' : 'right',
                 baseline: isX ? 'top' : 'middle',
             }));
-            tickPool.push({tickLine: t, label: l});
+            tickPool.push({ tickLine: t, label: l });
         }
     };
 
@@ -1314,8 +1512,8 @@ const buildAxis = (parent, opts) => {
         for (let i = 0; i < tickPool.length; i++) {
             const pair = tickPool[i];
             if (i >= count) {
-                pair.tickLine.set({visible: false});
-                pair.label.set({visible: false});
+                pair.tickLine.set({ visible: false });
+                pair.label.set({ visible: false });
                 continue;
             }
             const px = pixelBuf[i];
@@ -1356,14 +1554,14 @@ const buildAxis = (parent, opts) => {
                     });
                 }
             } else {
-                pair.label.set({visible: false});
+                pair.label.set({ visible: false });
             }
         }
     };
 
     const dispose = effect(rebuild);
 
-    return {axisGroup, dispose};
+    return { axisGroup, dispose };
 };
 
 // ---------------------------------------------------------------------------
@@ -1457,19 +1655,19 @@ const buildGrid = (parent, opts) => {
         }
         // Hide unused pool entries.
         for (let i = total; i < linePool.length; i++) {
-            linePool[i].set({visible: false});
+            linePool[i].set({ visible: false });
         }
     };
 
     const dispose = effect(rebuild);
-    return {gridGroup, dispose};
+    return { gridGroup, dispose };
 };
 
 // ---------------------------------------------------------------------------
 // Default margins / config
 // ---------------------------------------------------------------------------
 
-const DEFAULT_MARGIN = {top: 16, right: 24, bottom: 32, left: 56};
+const DEFAULT_MARGIN = { top: 16, right: 24, bottom: 32, left: 56 };
 const DEFAULT_AXIS_COLOR = '#888888';
 const DEFAULT_LABEL_COLOR = '#444444';
 const DEFAULT_LINE_COLOR = '#3b82f6';
@@ -1480,7 +1678,7 @@ const DEFAULT_TOOLTIP_BORDER = '#cccccc';
 const DEFAULT_TOOLTIP_MARKER_STROKE = '#ffffff';
 const DEFAULT_LEGEND_POSITION = 'bottom';
 const DEFAULT_GRID_COLOR = 'rgba(0,0,0,0.08)';
-const VALID_LEGEND_POSITIONS = {top: 1, bottom: 1, left: 1, right: 1};
+const VALID_LEGEND_POSITIONS = { top: 1, bottom: 1, left: 1, right: 1 };
 
 // Pre-allocated constants used by the crosshair draw fn. Avoids `[]` /
 // `Math.PI * 2` allocations on every mousemove redraw.
@@ -1513,13 +1711,6 @@ const formatTooltipValue = (v) => {
 // Domain helpers
 // ---------------------------------------------------------------------------
 
-// Test-API form: returns a fresh [lo, hi] tuple. Kept for the
-// _testHelpers export so existing assertions continue to read the
-// shape they expect (assert.deepEqual(niceYDomain(...), [0, 50])).
-//
-// The chart kernel uses _niceYDomainInto (below) instead -- writes
-// into a chart-owned 2-element scratch array so the data effect
-// allocates zero per update during streaming.
 const niceYDomain = (yMin, yMax, opts) => {
     let lo = yMin;
     let hi = yMax;
@@ -1539,28 +1730,6 @@ const niceYDomain = (yMin, yMax, opts) => {
     return [lo, hi];
 };
 
-// Zero-alloc form. `out` is a 2-element array (`out[0]` = lo, `out[1]` = hi)
-// owned by the caller; we mutate in place. Same math as niceYDomain.
-const _niceYDomainInto = (out, yMin, yMax, opts) => {
-    let lo = yMin;
-    let hi = yMax;
-    if (opts && opts.zero) {
-        if (lo > 0) lo = 0;
-        if (hi < 0) hi = 0;
-    }
-    if (opts && opts.nice) {
-        const pad = (hi - lo) * 0.05;
-        lo -= pad;
-        hi += pad;
-    }
-    if (lo === hi) {
-        lo -= 0.5;
-        hi += 0.5;
-    }
-    out[0] = lo;
-    out[1] = hi;
-};
-
 const inferXScaleType = (firstRow, xKey) => {
     if (firstRow == null) return 'linear';
     let probe;
@@ -1677,9 +1846,9 @@ const installLegend = (target, canvas, legendEl, position) => {
         : 'flex-start';
     wrapper.style.flexDirection =
         position === 'top' ? 'column-reverse' :
-            position === 'bottom' ? 'column' :
-                position === 'left' ? 'row-reverse' :
-                    'row';
+        position === 'bottom' ? 'column' :
+        position === 'left' ? 'row-reverse' :
+        'row';
     wrapper.style.gap = '4px';
 
     // Move canvas into wrapper (it's currently a child of target).
@@ -1731,10 +1900,7 @@ const _wireAutoSize = (container, widthAutoSig, heightAutoSig, disposers) => {
     const ro = new ResizeObserver(() => {
         if (scheduled) return;
         scheduled = true;
-        const update = () => {
-            scheduled = false;
-            readSize();
-        };
+        const update = () => { scheduled = false; readSize(); };
         if (typeof requestAnimationFrame === 'function') requestAnimationFrame(update);
         else update();
     });
@@ -1806,34 +1972,8 @@ const _bisectLookupRow = (state, snapIdx, snapDomainX /*, ctx*/) =>
 const _numericTooltipHeader = (snapIdx, snapDomainX, xScaleType /*, ctx*/) =>
     formatTooltipHeader(snapDomainX, xScaleType);
 
-// Reused opts object for buildAxis when called from the line/area/bubble
-// renderers -- mutated in place across mount() invocations of different
-// charts to avoid the per-mount {orientation:'x', ...opts} allocation
-// the literal-form spread used to do. Mount itself is not hot-path, but
-// this constitutes "no spread in source" hygiene rather than a perf win.
-const _xAxisOptsScratch = {
-    orientation: 'x',
-    scale: null,
-    plotBoundsBox: null,
-    plotBoundsSignal: null,
-    scaleVersion: null,
-    tickColor: null,
-    labelColor: null,
-    font: null,
-    format: null,
-};
-
-const _buildAxisX = (parent, opts /*, ctx*/) => {
-    _xAxisOptsScratch.scale = opts.scale;
-    _xAxisOptsScratch.plotBoundsBox = opts.plotBoundsBox;
-    _xAxisOptsScratch.plotBoundsSignal = opts.plotBoundsSignal;
-    _xAxisOptsScratch.scaleVersion = opts.scaleVersion;
-    _xAxisOptsScratch.tickColor = opts.tickColor;
-    _xAxisOptsScratch.labelColor = opts.labelColor;
-    _xAxisOptsScratch.font = opts.font;
-    _xAxisOptsScratch.format = opts.format;
-    return buildAxis(parent, _xAxisOptsScratch);
-};
+const _buildAxisX = (parent, opts /*, ctx*/) =>
+    buildAxis(parent, { orientation: 'x', ...opts });
 
 const _extractLineData = (state, data, xAcc, yAcc /*, ctx*/) =>
     extractSeriesData(state, data, xAcc, yAcc);
@@ -1850,7 +1990,7 @@ const _makeAreaDraw = (state, refs, plotBoundsBox, seriesIdx, totalSeries, ctx)
 const _initAreaOpts = (config) => ({
     baseline: config.baseline != null ? config.baseline : 0,
     stroke: config.stroke !== false,
-    fillOpacityRef: {value: config.fillOpacity != null ? config.fillOpacity : 0.3},
+    fillOpacityRef: { value: config.fillOpacity != null ? config.fillOpacity : 0.3 },
 });
 
 // Line renderer: numeric x, polyline draw, bisect hit detection, markers on snap.
@@ -1860,7 +2000,7 @@ const LINE_RENDERER = {
     createXScale: makeLinearScale,
     initOpts: null,
     extractData: _extractLineData,
-    yDefaults: {nice: true},
+    yDefaults: { nice: true },
     updateXScale: _updateXScaleLinear,
     projectToPixels: true,
     enableXGrid: true,
@@ -1879,7 +2019,7 @@ const AREA_RENDERER = {
     createXScale: makeLinearScale,
     initOpts: _initAreaOpts,
     extractData: _extractLineData,
-    yDefaults: {nice: true},
+    yDefaults: { nice: true },
     updateXScale: _updateXScaleLinear,
     projectToPixels: true,
     enableXGrid: true,
@@ -1894,19 +2034,50 @@ const AREA_RENDERER = {
 // Bar-specific renderer methods. None of these are referenced by line/area
 // renderers, so they're tree-shaken when only line or area is imported.
 
-const _initBarOpts = (config) => ({
-    baseline: config.baseline != null ? config.baseline : 0,
-    paddingInner: config.paddingInner != null ? config.paddingInner : 0.15,
-    paddingOuter: config.paddingOuter != null ? config.paddingOuter : 0.1,
-    groupInnerPad: config.groupInnerPad != null ? config.groupInnerPad : 0.08,
-});
+const _initBarOpts = (config) => {
+    // hoverTint: false to disable, true for default white-overlay, or an
+    // explicit CSS color string. Default is a low-alpha white that reads
+    // as a brightening overlay against any series color (parsing-free).
+    let hoverTintValue;
+    if (config.hoverTint === false || config.hoverTint === null) {
+        hoverTintValue = null;
+    } else if (typeof config.hoverTint === 'string') {
+        hoverTintValue = config.hoverTint;
+    } else {
+        hoverTintValue = 'rgba(255,255,255,0.18)';
+    }
+    return {
+        baseline: config.baseline != null ? config.baseline : 0,
+        paddingInner: config.paddingInner != null ? config.paddingInner : 0.15,
+        paddingOuter: config.paddingOuter != null ? config.paddingOuter : 0.1,
+        groupInnerPad: config.groupInnerPad != null ? config.groupInnerPad : 0.08,
+        // v1.1.0
+        stack: config.stack === true,
+        cornerRadius: config.cornerRadius != null ? Math.max(0, +config.cornerRadius) : 0,
+        hoverTintRef: { value: hoverTintValue },
+    };
+};
 
 const _extractBarData = (state, data, xAcc, yAcc, ctx) =>
     extractBarSeriesData(state, data, xAcc, yAcc, ctx.categoriesRef.value);
 
+// v1.1.0 stack pass: called by the kernel after every series has been
+// extracted, before y-domain aggregation. When stacking is on, it
+// computes per-series cumulative stackBottoms / stackTops and overrides
+// each series' domainYMax so the y-scale ranges over the total stack.
+// When stacking is off, it clears any prior stack buffers so re-renders
+// after a `stack: true -> false` config flip don't keep using stale state.
+const _barPostExtract = (states, ctx) => {
+    if (ctx.opts.stack) {
+        computeBarStacks(states, ctx.seriesVisibility, ctx.categoriesRef);
+    } else {
+        _clearBarStacks(states);
+    }
+};
+
 const _updateXScaleBand = (xScale, dxMin, dxMax, rMin, rMax, ctx) =>
     updateBandScale(xScale, ctx.categoriesRef.value.length, rMin, rMax,
-        ctx.opts.paddingInner, ctx.opts.paddingOuter);
+                    ctx.opts.paddingInner, ctx.opts.paddingOuter);
 
 const _buildAxisBar = (parent, opts, ctx) =>
     buildBarAxis(parent, {
@@ -1922,9 +2093,11 @@ const _buildAxisBar = (parent, opts, ctx) =>
 
 const _makeBarDraw = (state, refs, plotBoundsBox, seriesIdx, totalSeries, ctx) =>
     makeBarDrawFn(state, refs, plotBoundsBox,
-        ctx.xScale, ctx.yScale,
-        seriesIdx, totalSeries,
-        ctx.opts.baseline, ctx.opts.groupInnerPad);
+                  ctx.xScale, ctx.yScale,
+                  seriesIdx, totalSeries,
+                  ctx.opts.baseline, ctx.opts.groupInnerPad,
+                  ctx.opts.cornerRadius, ctx.opts.hoverTintRef,
+                  ctx.crosshairDataRef);
 
 const _bandHitTest = (canvasX, /*canvasY*/_cy, primary, xScale, ctx) => {
     if (ctx.categoriesRef.value.length === 0) return null;
@@ -1956,7 +2129,8 @@ const BAR_RENDERER = {
     createXScale: makeBandScale,
     initOpts: _initBarOpts,
     extractData: _extractBarData,
-    yDefaults: {nice: true, zero: true},
+    postExtract: _barPostExtract,  // v1.1.0: stack pass
+    yDefaults: { nice: true, zero: true },
     updateXScale: _updateXScaleBand,
     projectToPixels: false,
     enableXGrid: false,
@@ -2000,20 +2174,100 @@ const _bisectHitTest_canvasY = null; // sentinel for grep -- see _bisectHitTest
 //   state.sizeMin / state.sizeMax : value-domain bounds for this series
 // These fields stay null on non-bubble series, costing zero extra memory.
 
+// ---------------------------------------------------------------------------
+// Spatial index integration (v1.2.0-alpha.0)
+// ---------------------------------------------------------------------------
+//
+// For charts with dense point clouds (bubble, future scatter / heatmap), the
+// linear-scan hit-test becomes the bottleneck once point counts pass ~1000.
+// lite-charts defines a small, allocation-free interface that any spatial
+// index can implement -- @zakkster/lite-delaunay, a k-d tree, a uniform
+// grid, etc. The interface stays in lite-charts (so the renderers depend on
+// nothing extra); the implementation is wired by the consumer via config.
+//
+//   type SpatialIndexFactory = (pxs, pys, n) -> SpatialIndex
+//
+//   interface SpatialIndex {
+//     // Write up to `k` nearest indices (by pixel distance from qx, qy) into
+//     // outIndices / outDistSq, filtered to points within maxDistSq.
+//     // Return the count actually written (may be 0 .. k).
+//     // Both output arrays are caller-owned, stable refs -- zero alloc.
+//     findNearest(qx, qy, k, maxDistSq, outIndices, outDistSq) -> number
+//     dispose() -> void
+//   }
+//
+// The renderer:
+//   - calls factory(pxs, pys, n) at extract time when n >= threshold;
+//   - disposes the previous index before rebuilding;
+//   - falls back to linear scan when n < threshold OR no factory provided.
+//
+// k > 1 matters for bubble specifically: with overlapping discs, the point
+// whose CENTER is nearest the cursor may not be the one whose DISC contains
+// the cursor (a small bubble can sit inside a large one). The renderer
+// asks for the K nearest by center distance, then post-filters by disc
+// containment + smallest-r tie-break -- preserving v1.0.0 visual semantics.
+//
+// For non-overlapping charts (scatter, heatmap cells), the same interface
+// works with k = 1.
+
+const SPATIAL_INDEX_DEFAULT_THRESHOLD = 1000;
+const SPATIAL_INDEX_HIT_BUFFER_SIZE = 8;  // k for findNearest; balances
+                                          //  overlap-correctness vs work
+
+// Allocate per-state output buffers for findNearest. Sized once; reused
+// across hit-tests. Called lazily at the first hit-test where an index
+// exists, so non-indexed series pay nothing.
+const _ensureHitBuffers = (state) => {
+    if (!state._hitIndices) {
+        state._hitIndices = new Int32Array(SPATIAL_INDEX_HIT_BUFFER_SIZE);
+        state._hitDistSq  = new Float32Array(SPATIAL_INDEX_HIT_BUFFER_SIZE);
+    }
+};
+
+// Dispose helper -- defensive against indices that don't implement dispose().
+const _disposeSpatialIndex = (state) => {
+    if (state.spatialIndex) {
+        if (typeof state.spatialIndex.dispose === 'function') {
+            state.spatialIndex.dispose();
+        }
+        state.spatialIndex = null;
+    }
+};
+
+
 const _initBubbleOpts = (config) => {
     const sizeKey = config.size != null ? config.size : 'value';
+    // v1.2.0-alpha.2: per-point color. When `colorKey` is set, each row's
+    // color overrides the series fill. Null when omitted -> series color
+    // path stays the v1.0.0 fast path.
+    const colorKey = config.colorKey != null ? config.colorKey : null;
     return {
         sizeKey,
         sizeAccessor: buildAccessor(sizeKey),
+        colorKey,
+        // Use the RAW accessor here -- color strings (`'#ff0000'`, CSS vars
+        // like `'--c-emerald'`, or `'oklch(...)'`) must not be `+v`-coerced
+        // to NaN. buildRawAccessor returns the value untouched.
+        colorAccessor: colorKey != null ? buildRawAccessor(colorKey) : null,
         minRadius: config.minRadius != null ? +config.minRadius : 4,
         maxRadius: config.maxRadius != null ? +config.maxRadius : 40,
         // 'sqrt' (default): area-proportional, eye-correct per Tukey.
         // 'linear': radius-proportional; useful when the size dimension is
         // already a radius/length quantity rather than a magnitude.
         sizeScaleType: config.sizeScale === 'linear' ? 'linear' : 'sqrt',
-        strokeRef: {value: config.stroke != null ? config.stroke : '#ffffff'},
-        strokeWidthRef: {value: config.strokeWidth != null ? +config.strokeWidth : 1},
-        fillOpacityRef: {value: config.fillOpacity != null ? +config.fillOpacity : 0.6},
+        strokeRef: { value: config.stroke != null ? config.stroke : '#ffffff' },
+        strokeWidthRef: { value: config.strokeWidth != null ? +config.strokeWidth : 1 },
+        fillOpacityRef: { value: config.fillOpacity != null ? +config.fillOpacity : 0.6 },
+        // v1.2.0-alpha.0: spatial-index integration. Pass a factory matching
+        // the SpatialIndexFactory contract (see notes above) to enable
+        // O(log n) hit-test on dense bubble clouds. Threshold defaults to
+        // 1000 -- below that, linear scan is faster than index build + query.
+        spatialIndexFactory: typeof config.spatialIndex === 'function'
+            ? config.spatialIndex
+            : null,
+        spatialIndexThreshold: config.spatialIndexThreshold != null
+            ? +config.spatialIndexThreshold
+            : SPATIAL_INDEX_DEFAULT_THRESHOLD,
     };
 };
 
@@ -2105,6 +2359,44 @@ const extractBubbleData = (state, data, xAcc, yAcc, ctx) => {
     state.sizeMax = vMax === -Infinity ? 1 : vMax;
 
     computeBubbleRadii(state, opts.minRadius, opts.maxRadius, opts.sizeScaleType);
+
+    // v1.2.0-alpha.2: per-point color extraction. When opts.colorAccessor
+    // is set, walk the data and resolve each row's color to a concrete
+    // CSS string so the draw fn can use it directly. state.cs is a plain
+    // string array (no typed-array equivalent for strings) lazily allocated.
+    // Skip the work entirely when colorAccessor is null -- the draw fn
+    // falls back to the series fill via refs.colorRef.
+    if (opts.colorAccessor && Array.isArray(data)) {
+        if (!state.cs || state.cs.length < n) state.cs = new Array(n);
+        const colorAcc = opts.colorAccessor;
+        for (let i = 0; i < n; i++) {
+            const raw = colorAcc(data[i], i);
+            // resolveColor handles CSS-var (--foo) -> resolved value AND
+            // returns plain colors unchanged. null / undefined preserve the
+            // series-fill fallback (draw fn checks for falsy per-row).
+            state.cs[i] = raw != null ? resolveColor(raw) : null;
+        }
+    } else if (state.cs) {
+        // Drop stale per-point colors if colorKey was removed mid-session.
+        state.cs = null;
+    }
+
+    // v1.2.0-alpha.0: invalidate the spatial index whenever extract runs.
+    // The kernel re-projects pxs/pys AFTER this returns, so any pre-built
+    // index is stale by definition. We defer the rebuild until the next
+    // hit-test (lazy) -- no rebuild if the user never hovers.
+    _disposeSpatialIndex(state);
+
+    // Cache max pixel radius squared. The spatial index needs an upper
+    // bound on the query distance (no bubble can contain the cursor if
+    // its CENTER is more than maxR pixels away).
+    let prMax = 0;
+    const prs = state.prs;
+    for (let i = 0; i < n; i++) {
+        const r = prs[i];
+        if (r > prMax) prMax = r;
+    }
+    state.prMaxSq = prMax * prMax;
 };
 
 // Bubble draw fn: one ctx.arc per visible point. Defensive clipping skips
@@ -2120,6 +2412,7 @@ const makeBubbleDrawFn = (state, refs, plotBoundsBox, opts) => (ctx) => {
     const xs = state.pxs;
     const ys = state.pys;
     const rs = state.prs;
+    const cs = state.cs;  // null when colorKey unset; per-point color array otherwise
     const pb = plotBoundsBox;
     const plotL = pb.x, plotR = pb.x + pb.w;
     const plotT = pb.y, plotB = pb.y + pb.h;
@@ -2141,7 +2434,9 @@ const makeBubbleDrawFn = (state, refs, plotBoundsBox, opts) => (ctx) => {
         ctx.beginPath();
         ctx.arc(x, y, r, 0, _TWO_PI);
         ctx.globalAlpha = fillAlpha;
-        ctx.fillStyle = fillColor;
+        // v1.2.0-alpha.2: per-point color when state.cs is populated and the
+        // specific row has a color; otherwise series fill (v1.0.0 path).
+        ctx.fillStyle = (cs && cs[i]) ? cs[i] : fillColor;
         ctx.fill();
         if (doStroke) {
             ctx.globalAlpha = 1;
@@ -2159,27 +2454,120 @@ const makeBubbleDrawFn = (state, refs, plotBoundsBox, opts) => (ctx) => {
 // for O(log n) lookup, but until n > ~1000 the linear scan is faster
 // (cache-friendly, no tree overhead).
 
-const _bubbleHitTest = (canvasX, canvasY, primary, /*xScale*/_xs, /*ctx*/_ctx) => {
+const _bubbleHitTest = (canvasX, canvasY, primary, /*xScale*/_xs, ctx) => {
+    // v1.2.0-alpha.2: iterate all visible series, not just primary. Each
+    // series has its own bubbles at different (x, y) so cross-series hit-
+    // test must consider every visible state. With its own spatial index
+    // per series (if applicable). The `primary` arg is kept in the signature
+    // for compatibility but is no longer the only series checked.
+    const states = ctx.seriesStates;
+    const visibility = ctx.seriesVisibility;
+    const opts = ctx.opts;
+    if (!states || !visibility) {
+        // Defensive fallback: ctx wiring missing for some reason. Use the
+        // primary-only path (v1.0.0 behavior).
+        return _bubbleHitTestSingle(canvasX, canvasY, primary, opts);
+    }
+
+    let bestIdx = -1;
+    let bestSeriesIdx = -1;
+    let bestR = Infinity;
+
+    for (let s = 0; s < states.length; s++) {
+        if (!visibility[s]()) continue;
+        const state = states[s];
+        const n = state.n;
+        if (n === 0) continue;
+        if (state.pxs === null || state.pys === null || state.prs === null) continue;
+        const xs = state.pxs, ys = state.pys, rs = state.prs;
+
+        if (opts.spatialIndexFactory && n >= opts.spatialIndexThreshold) {
+            if (!state.spatialIndex) {
+                state.spatialIndex = opts.spatialIndexFactory(xs, ys, n);
+            }
+            _ensureHitBuffers(state);
+            const k = state.spatialIndex.findNearest(
+                canvasX, canvasY,
+                SPATIAL_INDEX_HIT_BUFFER_SIZE,
+                state.prMaxSq,
+                state._hitIndices, state._hitDistSq);
+            const hitIdx = state._hitIndices;
+            const hitDistSq = state._hitDistSq;
+            for (let j = 0; j < k; j++) {
+                const i = hitIdx[j];
+                const r = rs[i];
+                if (r !== r) continue;
+                if (hitDistSq[j] <= r * r && r < bestR) {
+                    bestR = r;
+                    bestIdx = i;
+                    bestSeriesIdx = s;
+                }
+            }
+        } else {
+            for (let i = 0; i < n; i++) {
+                const x = xs[i], y = ys[i], r = rs[i];
+                if (x !== x || y !== y || r !== r) continue;
+                const dx = canvasX - x;
+                const dy = canvasY - y;
+                if (dx * dx + dy * dy <= r * r) {
+                    if (r < bestR) {
+                        bestR = r;
+                        bestIdx = i;
+                        bestSeriesIdx = s;
+                    }
+                }
+            }
+        }
+    }
+
+    if (bestIdx < 0) return null;
+    const hitState = states[bestSeriesIdx];
+    return {
+        snapIdx: bestIdx,
+        snapDomainX: hitState.xs[bestIdx],
+        snapPixelX: hitState.pxs[bestIdx],
+        snapSeriesIdx: bestSeriesIdx,
+    };
+};
+
+// Single-series fallback (kept for the defensive ctx-missing path; should
+// not normally execute since rendererCtx is always wired in createBaseAxisChart).
+const _bubbleHitTestSingle = (canvasX, canvasY, primary, opts) => {
     const n = primary.n;
     if (n === 0) return null;
     if (primary.pxs === null || primary.pys === null || primary.prs === null) return null;
-    const xs = primary.pxs;
-    const ys = primary.pys;
-    const rs = primary.prs;
+    const xs = primary.pxs, ys = primary.pys, rs = primary.prs;
     let bestIdx = -1;
     let bestR = Infinity;
-    for (let i = 0; i < n; i++) {
-        const x = xs[i], y = ys[i], r = rs[i];
-        if (x !== x || y !== y || r !== r) continue;
-        const dx = canvasX - x;
-        const dy = canvasY - y;
-        if (dx * dx + dy * dy <= r * r) {
-            // Prefer the smaller (visually-topmost) bubble on overlap.
-            if (r < bestR) {
+    if (opts.spatialIndexFactory && n >= opts.spatialIndexThreshold) {
+        if (!primary.spatialIndex) {
+            primary.spatialIndex = opts.spatialIndexFactory(xs, ys, n);
+        }
+        _ensureHitBuffers(primary);
+        const k = primary.spatialIndex.findNearest(
+            canvasX, canvasY,
+            SPATIAL_INDEX_HIT_BUFFER_SIZE,
+            primary.prMaxSq,
+            primary._hitIndices, primary._hitDistSq);
+        for (let j = 0; j < k; j++) {
+            const i = primary._hitIndices[j];
+            const r = rs[i];
+            if (r !== r) continue;
+            if (primary._hitDistSq[j] <= r * r && r < bestR) {
                 bestR = r;
                 bestIdx = i;
             }
         }
+    } else {
+        for (let i = 0; i < n; i++) {
+            const x = xs[i], y = ys[i], r = rs[i];
+            if (x !== x || y !== y || r !== r) continue;
+            const dx = canvasX - x;
+            const dy = canvasY - y;
+            if (dx * dx + dy * dy <= r * r) {
+                if (r < bestR) { bestR = r; bestIdx = i; }
+            }
+        }
     }
     if (bestIdx < 0) return null;
     return {
@@ -2192,8 +2580,16 @@ const _bubbleHitTest = (canvasX, canvasY, primary, /*xScale*/_xs, /*ctx*/_ctx) =
 // Bubble lookup is identity -- the hit-test already returned the exact row
 // index for this series. (Unlike line where the cursor may be between
 // points and we bisect to the nearest x.)
-const _bubbleLookupRow = (state, snapIdx /*, snapDomainX, ctx*/) =>
-    snapIdx >= 0 && snapIdx < state.n ? snapIdx : -1;
+// v1.2.0-alpha.2: for multi-series, only the hit series produces a tooltip
+// row. The crosshair's snapSeriesIdx tells us which one was hit; other
+// states return -1 (excluded from the tooltip).
+const _bubbleLookupRow = (state, snapIdx, _snapDomainX, ctx) => {
+    const cd = ctx.crosshairDataRef;
+    if (cd && cd.snapSeriesIdx >= 0 && state._stateIdx !== cd.snapSeriesIdx) {
+        return -1;
+    }
+    return snapIdx >= 0 && snapIdx < state.n ? snapIdx : -1;
+};
 
 const _makeBubbleDraw = (state, refs, plotBoundsBox, seriesIdx, totalSeries, ctx) =>
     makeBubbleDrawFn(state, refs, plotBoundsBox, ctx.opts);
@@ -2201,13 +2597,62 @@ const _makeBubbleDraw = (state, refs, plotBoundsBox, seriesIdx, totalSeries, ctx
 const _extractBubbleData = (state, data, xAcc, yAcc, ctx) =>
     extractBubbleData(state, data, xAcc, yAcc, ctx);
 
+const _bubbleCleanup = (states) => {
+    for (let i = 0; i < states.length; i++) {
+        _disposeSpatialIndex(states[i]);
+    }
+};
+
+// v1.2.0-alpha.2: global size domain across visible series. Bubble's per-
+// series extract sets state.sizeMin / state.sizeMax to the SERIES's range,
+// so two series with different value ranges would scale independently and
+// equal raw values would render at different pixel sizes. This hook stamps
+// the global (visible-series) range onto every state and re-runs
+// computeBubbleRadii so equal values render equal-area regardless of which
+// series. Single-series charts skip the rescale (the original computation
+// is already correct).
+const _bubblePostExtract = (states, ctx) => {
+    const visibility = ctx.seriesVisibility;
+    let visCount = 0;
+    let globalMin = Infinity;
+    let globalMax = -Infinity;
+    for (let s = 0; s < states.length; s++) {
+        if (!visibility || !visibility[s]()) continue;
+        const st = states[s];
+        if (st.n === 0) continue;
+        visCount++;
+        if (st.sizeMin < globalMin) globalMin = st.sizeMin;
+        if (st.sizeMax > globalMax) globalMax = st.sizeMax;
+    }
+    if (visCount < 2 || globalMin === Infinity) return;
+
+    const opts = ctx.opts;
+    for (let s = 0; s < states.length; s++) {
+        const st = states[s];
+        if (st.n === 0) continue;
+        st.sizeMin = globalMin;
+        st.sizeMax = globalMax;
+        computeBubbleRadii(st, opts.minRadius, opts.maxRadius, opts.sizeScaleType);
+        // Recompute prMaxSq with the new radii. The spatial index was
+        // already invalidated by extract; no extra dispose needed here.
+        let prMax = 0;
+        const prs = st.prs;
+        for (let i = 0; i < st.n; i++) {
+            const r = prs[i];
+            if (r > prMax) prMax = r;
+        }
+        st.prMaxSq = prMax * prMax;
+    }
+};
+
 const BUBBLE_RENDERER = {
     buildXAccessor: buildAccessor,
     forceXType: null,
     createXScale: makeLinearScale,
     initOpts: _initBubbleOpts,
     extractData: _extractBubbleData,
-    yDefaults: {nice: true},
+    postExtract: _bubblePostExtract,  // v1.2.0-alpha.2: global size domain
+    yDefaults: { nice: true },
     updateXScale: _updateXScaleLinear,
     projectToPixels: true,           // x/y projection; size projection happens in extractData
     enableXGrid: true,
@@ -2217,8 +2662,182 @@ const BUBBLE_RENDERER = {
     drawPerSeriesMarkers: false,     // the bubbles ARE the markers
     lookupRow: _bubbleLookupRow,
     formatTooltipHeader: _numericTooltipHeader,
+    cleanup: _bubbleCleanup,         // v1.2.0-alpha.0: dispose spatial indices
+};
+
+// ---------------------------------------------------------------------------
+// Scatter renderer (v1.2.0-alpha.1)
+// ---------------------------------------------------------------------------
+//
+// createScatterChart is bubble's simpler sibling: every point gets the SAME
+// marker size, the data has no size dimension, and the hit-test radius is a
+// configurable threshold around the marker. Shares the axis kernel with
+// line / area / bar / bubble; shares the spatial-index foundation from
+// v1.2.0-alpha.0 (with k = 1 since scatter has no overlap concerns).
+//
+// What scatter does NOT do (intentionally; bubble already covers it):
+//   - per-point size from data
+//   - sqrt or linear size scaling
+//   - smallest-on-top tie-break on overlap
+
+const _initScatterOpts = (config) => {
+    // markerSize is the pixel radius; default 4 (small enough to feel like
+    // a "dot", large enough to click reliably). hitTolerance extends the
+    // hit-test radius beyond the marker for easier targeting; default is
+    // markerSize + 4px (caller can override).
+    const markerSize = config.markerSize != null ? +config.markerSize : 4;
+    const hitTolerance = config.hitTolerance != null
+        ? +config.hitTolerance
+        : markerSize + 4;
+    return {
+        markerSize,
+        hitToleranceSq: hitTolerance * hitTolerance,
+        strokeRef: { value: config.stroke != null ? config.stroke : null },
+        strokeWidthRef: { value: config.strokeWidth != null ? +config.strokeWidth : 0 },
+        fillOpacityRef: { value: config.fillOpacity != null ? +config.fillOpacity : 1 },
+        // v1.2.0-alpha.0: same spatial-index plumbing as bubble. k = 1 in
+        // findNearest because scatter has no overlap; the single nearest
+        // point either is or isn't inside the hit-tolerance disc.
+        spatialIndexFactory: typeof config.spatialIndex === 'function'
+            ? config.spatialIndex
+            : null,
+        spatialIndexThreshold: config.spatialIndexThreshold != null
+            ? +config.spatialIndexThreshold
+            : SPATIAL_INDEX_DEFAULT_THRESHOLD,
+    };
+};
+
+// Scatter extract is just extractSeriesData -- no size column to process.
+// The spatial index gets disposed here on every data / scale change for the
+// same lazy-rebuild reason as bubble.
+const _extractScatterData = (state, data, xAcc, yAcc, ctx) => {
+    extractSeriesData(state, data, xAcc, yAcc);
+    _disposeSpatialIndex(state);
+};
+
+const makeScatterDrawFn = (state, refs, plotBoundsBox, opts) => (ctx) => {
+    if (!refs.visibleRef.value) return;
+    const n = state.n;
+    if (n === 0) return;
+    if (state.pxs === null || state.pys === null) return;
+    const xs = state.pxs;
+    const ys = state.pys;
+    const pb = plotBoundsBox;
+    const plotL = pb.x, plotR = pb.x + pb.w;
+    const plotT = pb.y, plotB = pb.y + pb.h;
+    const r = opts.markerSize;
+    const r2 = r;  // used as AABB margin
+
+    ctx.fillStyle = refs.colorRef.value;
+    const prevAlpha = ctx.globalAlpha;
+    ctx.globalAlpha = opts.fillOpacityRef.value;
+
+    const strokeW = opts.strokeWidthRef.value;
+    const strokeColor = strokeW > 0 && opts.strokeRef.value ? opts.strokeRef.value : null;
+
+    for (let i = 0; i < n; i++) {
+        const x = xs[i], y = ys[i];
+        if (x !== x || y !== y) continue;
+        // Defensive AABB clip -- skip points whose bounding square sits
+        // entirely outside the plot rect.
+        if (x + r2 < plotL || x - r2 > plotR || y + r2 < plotT || y - r2 > plotB) continue;
+        ctx.beginPath();
+        ctx.arc(x, y, r, 0, Math.PI * 2);
+        ctx.fill();
+        if (strokeColor) {
+            ctx.strokeStyle = strokeColor;
+            ctx.lineWidth = strokeW;
+            ctx.stroke();
+        }
+    }
+    ctx.globalAlpha = prevAlpha;
+};
+
+const _scatterHitTest = (canvasX, canvasY, primary, /*xScale*/_xs, ctx) => {
+    const n = primary.n;
+    if (n === 0) return null;
+    if (primary.pxs === null || primary.pys === null) return null;
+    const xs = primary.pxs;
+    const ys = primary.pys;
+    const opts = ctx.opts;
+    const toleranceSq = opts.hitToleranceSq;
+
+    // Spatial-index fast path -- k = 1 is enough since scatter has no
+    // overlap semantics. The nearest point either is or isn't within the
+    // hit-tolerance disc.
+    if (opts.spatialIndexFactory && n >= opts.spatialIndexThreshold) {
+        if (!primary.spatialIndex) {
+            primary.spatialIndex = opts.spatialIndexFactory(xs, ys, n);
+        }
+        _ensureHitBuffers(primary);
+        const k = primary.spatialIndex.findNearest(
+            canvasX, canvasY, 1, toleranceSq,
+            primary._hitIndices, primary._hitDistSq);
+        if (k === 0) return null;
+        const idx = primary._hitIndices[0];
+        return {
+            snapIdx: idx,
+            snapDomainX: primary.xs[idx],
+            snapPixelX: xs[idx],
+        };
+    }
+
+    // Linear scan fallback. Tracks the closest point within tolerance.
+    let bestIdx = -1;
+    let bestDsq = toleranceSq;  // strict-less below tightens this
+    for (let i = 0; i < n; i++) {
+        const x = xs[i], y = ys[i];
+        if (x !== x || y !== y) continue;
+        const dx = canvasX - x;
+        const dy = canvasY - y;
+        const d = dx * dx + dy * dy;
+        if (d < bestDsq) {
+            bestDsq = d;
+            bestIdx = i;
+        }
+    }
+    if (bestIdx < 0) return null;
+    return {
+        snapIdx: bestIdx,
+        snapDomainX: primary.xs[bestIdx],
+        snapPixelX: xs[bestIdx],
+    };
+};
+
+const _scatterLookupRow = (state, snapIdx /*, snapDomainX, ctx*/) =>
+    snapIdx >= 0 && snapIdx < state.n ? snapIdx : -1;
+
+const _makeScatterDraw = (state, refs, plotBoundsBox, /*seriesIdx*/_si, /*totalSeries*/_ts, ctx) =>
+    makeScatterDrawFn(state, refs, plotBoundsBox, ctx.opts);
+
+const _scatterCleanup = (states) => {
+    // Same as bubble -- dispose spatial indices on unmount. Defensively
+    // guards against indices that hold external resources.
+    for (let i = 0; i < states.length; i++) {
+        _disposeSpatialIndex(states[i]);
+    }
+};
+
+const SCATTER_RENDERER = {
+    buildXAccessor: buildAccessor,
+    forceXType: null,
+    createXScale: makeLinearScale,
+    initOpts: _initScatterOpts,
+    extractData: _extractScatterData,
+    yDefaults: { nice: true },
+    updateXScale: _updateXScaleLinear,
+    projectToPixels: true,
+    enableXGrid: true,
+    buildXAxis: _buildAxisX,
+    makeDrawFn: _makeScatterDraw,
+    hitTest: _scatterHitTest,
+    drawPerSeriesMarkers: false,
+    lookupRow: _scatterLookupRow,
+    formatTooltipHeader: _numericTooltipHeader,
+    cleanup: _scatterCleanup,
 };
 
+
 // ===========================================================================
 // Base x/y axis chart kernel
 // ===========================================================================
@@ -2289,7 +2908,15 @@ const createBaseAxisChart = (config, renderer) => {
     const marginLeft = m.left != null ? m.left : DEFAULT_MARGIN.left;
 
     // -- Series state --
-    const seriesStates = normalized.map(() => createSeriesState());
+    // Tag each state with its position in the array. The multi-series bubble
+    // hit-test (v1.2.0-alpha.2) uses this so lookupRow can check whether
+    // a given state is the one that actually got hit; line / area / bar /
+    // scatter ignore it.
+    const seriesStates = normalized.map((_, i) => {
+        const s = createSeriesState();
+        s._stateIdx = i;
+        return s;
+    });
 
     // -- Scales: created once, fields mutated in place --
     // Resolve x scale type: explicit > inferred from first non-empty series.
@@ -2312,7 +2939,7 @@ const createBaseAxisChart = (config, renderer) => {
     // series, in first-seen order. Mutated in place by extractBarSeriesData
     // during data extraction; bar axis + bandScale read .value. Always
     // allocated (cheap) -- non-bar renderers simply never reference it.
-    const categoriesRef = {value: []};
+    const categoriesRef = { value: [] };
 
     // Chart-type-specific options bag. `null` for line; structured config
     // for area / bar / future renderers.
@@ -2325,17 +2952,24 @@ const createBaseAxisChart = (config, renderer) => {
         yScale,
         opts: chartOpts,
         categoriesRef,
+        // v1.1.0: stack pass + hover tint need access to per-series
+        // visibility signals and the live crosshair state. Both are
+        // assigned below once the kernel has constructed them (after
+        // chart() is set up).
+        seriesVisibility: null,
+        crosshairDataRef: null,
+        // v1.2.0-alpha.2: multi-series bubble hit-test iterates all visible
+        // series' state arrays to find the best hit across series.
+        seriesStates: null,
     };
-
-    // 2-element scratch for the y-domain effect. Replaces both the
-    // `[yConf.domain[0], yConf.domain[1]]` literal AND the [lo, hi] tuple
-    // niceYDomain used to return per call. Reads stay at _yDomScratch[0/1].
-    const _yDomScratch = [0, 0];
+    // seriesStates is declared above rendererCtx in source order; assign it
+    // here now that rendererCtx exists.
+    rendererCtx.seriesStates = seriesStates;
 
     const scaleVersion = signal(0);
 
     // -- Plot bounds: a single mutable box + a signal that publishes "the box changed" --
-    const plotBoundsBox = {x: 0, y: 0, w: 0, h: 0};
+    const plotBoundsBox = { x: 0, y: 0, w: 0, h: 0 };
     const plotBoundsSignal = signal(0);
 
     // -- Refs that the draw closures read (mutated by an effect) --
@@ -2343,23 +2977,24 @@ const createBaseAxisChart = (config, renderer) => {
     // draw fns (which run outside a reactive context) can read synchronously
     // without going through signal-call overhead.
     const seriesRefs = normalized.map((s) => ({
-        colorRef: {value: '#888'},
-        lineWidthRef: {value: s.lineWidth},
-        visibleRef: {value: true},
-        interpolationRef: {value: INTERP_LINEAR},
-        markersRef: {value: null},
+        colorRef: { value: '#888' },
+        lineWidthRef: { value: s.lineWidth },
+        visibleRef: { value: true },
+        interpolationRef: { value: INTERP_LINEAR },
+        markersRef: { value: null },
     }));
 
     // -- Public series-visibility signals. Used by the legend click handler,
     // by chart.setSeriesVisible(), and tracked by the domain + draw effects so
     // toggling rescales the y-domain and triggers redraw.
     const seriesVisibility = normalized.map(() => signal(true));
+    rendererCtx.seriesVisibility = seriesVisibility;
 
     // -- Axis-render styling refs --
     const axisStyleRefs = {
-        tickColor: {value: DEFAULT_AXIS_COLOR},
-        labelColor: {value: DEFAULT_LABEL_COLOR},
-        font: {value: config.font != null ? config.font : DEFAULT_FONT},
+        tickColor: { value: DEFAULT_AXIS_COLOR },
+        labelColor: { value: DEFAULT_LABEL_COLOR },
+        font: { value: config.font != null ? config.font : DEFAULT_FONT },
     };
 
     // (areaOpts and barOpts have been replaced by chartOpts -- a unified
@@ -2380,7 +3015,7 @@ const createBaseAxisChart = (config, renderer) => {
         gridEnableY = config.grid.y !== false;
         if (config.grid.color) gridColorSpec = config.grid.color;
     }
-    const gridColorRef = {value: gridColorSpec};
+    const gridColorRef = { value: gridColorSpec };
 
     // -- Legend config --
     // `legend: false` disables. `legend: 'top'|'bottom'|'left'|'right'` is
@@ -2417,7 +3052,7 @@ const createBaseAxisChart = (config, renderer) => {
     const crosshairColorSpec = crosshairOpts && crosshairOpts.color
         ? crosshairOpts.color
         : DEFAULT_CROSSHAIR_COLOR;
-    const crosshairColorRef = {value: crosshairColorSpec};
+    const crosshairColorRef = { value: crosshairColorSpec };
     const crosshairDash = crosshairOpts && crosshairOpts.dash ? crosshairOpts.dash : [3, 3];
     const tooltipBgSpec = tooltipOpts && tooltipOpts.background
         ? tooltipOpts.background
@@ -2425,8 +3060,8 @@ const createBaseAxisChart = (config, renderer) => {
     const tooltipBorderSpec = tooltipOpts && tooltipOpts.border
         ? tooltipOpts.border
         : DEFAULT_TOOLTIP_BORDER;
-    const tooltipBgRef = {value: tooltipBgSpec};
-    const tooltipBorderRef = {value: tooltipBorderSpec};
+    const tooltipBgRef = { value: tooltipBgSpec };
+    const tooltipBorderRef = { value: tooltipBorderSpec };
     const tooltipFormatter = tooltipOpts && typeof tooltipOpts.format === 'function'
         ? tooltipOpts.format
         : null;
@@ -2450,7 +3085,13 @@ const createBaseAxisChart = (config, renderer) => {
         snapDomainX: 0,
         snapPixelX: 0,
         mousePixelY: 0,
+        // v1.2.0-alpha.2: which series the hit belongs to. -1 means
+        // "not series-scoped" (line / area / bar / scatter never set this).
+        // Multi-series bubble's hit-test sets it so lookupRow can scope the
+        // tooltip to just the hit series.
+        snapSeriesIdx: -1,
     };
+    rendererCtx.crosshairDataRef = crosshairData;
     const crosshairVersion = signal(0);
     const crosshairFacade = function () {
         crosshairVersion();
@@ -2619,11 +3260,26 @@ const createBaseAxisChart = (config, renderer) => {
                 }
             }
 
+            // v1.1.0: optional post-extract pass. Bar's stack pass uses this
+            // to fill stackBottoms/stackTops per series AND overwrite each
+            // series' domainYMax with the total-stack-height global max. We
+            // re-aggregate y-domain after the hook to pick up those updates.
+            if (renderer.postExtract) {
+                renderer.postExtract(seriesStates, rendererCtx);
+                yMin = Infinity;
+                yMax = -Infinity;
+                for (let i = 0; i < normalized.length; i++) {
+                    if (seriesVisibility[i]() && seriesStates[i].n > 0) {
+                        if (seriesStates[i].domainYMin < yMin) yMin = seriesStates[i].domainYMin;
+                        if (seriesStates[i].domainYMax > yMax) yMax = seriesStates[i].domainYMax;
+                    }
+                }
+                if (yMin === Infinity) yMin = 0;
+                if (yMax === -Infinity) yMax = 1;
+            }
+
             if (!anyData) {
-                xMin = 0;
-                xMax = 1;
-                yMin = 0;
-                yMax = 1;
+                xMin = 0; xMax = 1; yMin = 0; yMax = 1;
             }
             if (xMin === xMax) xMax = xMin + 1;
 
@@ -2640,14 +3296,9 @@ const createBaseAxisChart = (config, renderer) => {
             const yConf = config.yScale;
             const dxMin = xConf && xConf.domain ? xConf.domain[0] : xMin;
             const dxMax = xConf && xConf.domain ? xConf.domain[1] : xMax;
-            // Zero-alloc y-domain: write into _yDomScratch instead of
-            // allocating a fresh [lo, hi] tuple per data update.
-            if (yConf && yConf.domain) {
-                _yDomScratch[0] = yConf.domain[0];
-                _yDomScratch[1] = yConf.domain[1];
-            } else {
-                _niceYDomainInto(_yDomScratch, yMin, yMax, yConf || renderer.yDefaults);
-            }
+            const yBase = yConf && yConf.domain
+                ? [yConf.domain[0], yConf.domain[1]]
+                : niceYDomain(yMin, yMax, yConf || renderer.yDefaults);
 
             renderer.updateXScale(
                 xScale,
@@ -2655,7 +3306,7 @@ const createBaseAxisChart = (config, renderer) => {
                 plotBoundsBox.x, plotBoundsBox.x + plotBoundsBox.w,
                 rendererCtx,
             );
-            updateLinearScale(yScale, _yDomScratch[0], _yDomScratch[1], plotBoundsBox.y + plotBoundsBox.h, plotBoundsBox.y);
+            updateLinearScale(yScale, yBase[0], yBase[1], plotBoundsBox.y + plotBoundsBox.h, plotBoundsBox.y);
 
             // Renderers that use pre-projected pixel arrays in their draw fn
             // (line / area) request projection; renderers that compute pixels
@@ -2743,7 +3394,9 @@ const createBaseAxisChart = (config, renderer) => {
                 normalized.length,      // totalSeries
                 rendererCtx,
             );
-            const node = scene.root.add(pathNode({draw: drawFn}));
+            const node = scene.root.add(pathNode({
+                draw: (ctx) => drawFn(ctx),
+            }));
             seriesNodes.push(node);
         }
 
@@ -2761,7 +3414,9 @@ const createBaseAxisChart = (config, renderer) => {
             // keep it as ONE node (rather than one node per visual) because all
             // pieces share the same gate (crosshair visibility), so coalescing
             // them avoids redundant scene traversal cost.
-            const crosshairNode = scene.root.add(pathNode({draw: drawCrosshair}));
+            const crosshairNode = scene.root.add(pathNode({
+                draw: (ctx) => drawCrosshair(ctx),
+            }));
 
             // Dirty bridge: crosshair state changes -> markDirty. The path
             // node's draw is RAW, so it doesn't auto-track.
@@ -2777,7 +3432,7 @@ const createBaseAxisChart = (config, renderer) => {
                 const onMove = (ev) => {
                     const rect = typeof canvas.getBoundingClientRect === 'function'
                         ? canvas.getBoundingClientRect()
-                        : {left: 0, top: 0, width: canvas.width, height: canvas.height};
+                        : { left: 0, top: 0, width: canvas.width, height: canvas.height };
                     // CSS pixels relative to canvas top-left. moveCrosshair
                     // expects logical (CSS-pixel) coords because plotBoundsBox,
                     // pixel buffers, and xScale.invert all operate in logical
@@ -2804,7 +3459,7 @@ const createBaseAxisChart = (config, renderer) => {
             const fontResolved = config.font != null ? config.font : DEFAULT_FONT;
             const labelColorResolved = resolveColor(config.labelColor || DEFAULT_LABEL_COLOR, container);
             legendEl = buildLegendDOM(
-                {position: legendPosition, container: legendContainer},
+                { position: legendPosition, container: legendContainer },
                 normalized,
                 seriesVisibility,
                 seriesRefs,
@@ -2836,17 +3491,19 @@ const createBaseAxisChart = (config, renderer) => {
     const unmount = () => {
         if (!mounted) return;
         for (let i = 0; i < disposers.length; i++) {
-            try {
-                disposers[i]();
-            } catch (_) { /* swallow */
-            }
+            try { disposers[i](); } catch (_) { /* swallow */ }
         }
         disposers.length = 0;
+        // v1.2.0-alpha.0: per-renderer state cleanup hook. Bubble uses it to
+        // dispose spatial indices (which may hold external resources); other
+        // renderers don't define it and pay only a null-check. Moving the
+        // hook here -- vs an unconditional loop -- keeps the spatial-index
+        // helper out of line / area / bar bundles entirely.
+        if (renderer.cleanup) {
+            try { renderer.cleanup(seriesStates); } catch (_) { /* swallow */ }
+        }
         if (scene) {
-            try {
-                scene.dispose();
-            } catch (_) { /* swallow */
-            }
+            try { scene.dispose(); } catch (_) { /* swallow */ }
             scene = null;
         }
         // Legend tear-down: remove whichever DOM we owned.
@@ -2914,13 +3571,19 @@ const createBaseAxisChart = (config, renderer) => {
         // Zero-alloc dedup + mutate. crosshairData is the live mutable
         // reference; we read its current fields, decide whether anything
         // actually changed, and either bail or mutate-and-bump-version.
+        // v1.2.0-alpha.2: snapSeriesIdx participates in dedup so a hover
+        // that moves from series A's point to series B's point (same row
+        // index, different series) still re-renders the tooltip.
+        const hitSeriesIdx = hit.snapSeriesIdx != null ? hit.snapSeriesIdx : -1;
         if (crosshairData.visible
             && crosshairData.snapIdx === hit.snapIdx
+            && crosshairData.snapSeriesIdx === hitSeriesIdx
             && crosshairData.mousePixelY === canvasY) return;
         crosshairData.visible = true;
         crosshairData.snapIdx = hit.snapIdx;
         crosshairData.snapDomainX = hit.snapDomainX;
         crosshairData.snapPixelX = hit.snapPixelX;
+        crosshairData.snapSeriesIdx = hitSeriesIdx;
         crosshairData.mousePixelY = canvasY;
         crosshairVersion.update((x) => (x + 1) | 0);
     };
@@ -2932,6 +3595,7 @@ const createBaseAxisChart = (config, renderer) => {
         crosshairData.snapIdx = -1;
         crosshairData.snapDomainX = 0;
         crosshairData.snapPixelX = 0;
+        crosshairData.snapSeriesIdx = -1;
         crosshairData.mousePixelY = 0;
         crosshairVersion.update((x) => (x + 1) | 0);
     };
@@ -2987,31 +3651,6 @@ const createBaseAxisChart = (config, renderer) => {
         if (tooltipOpts) drawTooltip(ctx, state);
     };
 
-    // Tooltip scratch: a stable row pool we resize-and-mutate, plus a
-    // stable object passed to the user's tooltipFormatter. Both are
-    // allocated ONCE per chart instance and reused across every mousemove.
-    // Eliminates the rows = [] + per-series {color,label,value} push that
-    // used to fire on each pointer event (mouse polls 125-1000 Hz on
-    // gaming mice -- bounded but not free).
-    //
-    // The user's formatter still receives a normal-looking object via
-    // `_tooltipFormatterCtx`; if they retain it past their callback they
-    // observe the next mousemove's state -- documented contract, same as
-    // the crosshair facade.
-    const _tooltipRowPool = [];
-    const _ensureRowPool = (n) => {
-        while (_tooltipRowPool.length < n) {
-            _tooltipRowPool.push({color: '', label: '', value: ''});
-        }
-    };
-    const _tooltipFormatterCtx = {
-        snapIdx: 0,
-        snapDomainX: 0,
-        xScaleType: '',
-        category: null,
-        rows: _tooltipRowPool, // mutated below to expose a sliced view
-    };
-
     const drawTooltip = (ctx, state) => {
         const pb = plotBoundsBox;
         const padding = 8;
@@ -3019,28 +3658,21 @@ const createBaseAxisChart = (config, renderer) => {
         const lineHeight = 14;
         const gap = 12;
 
-        // Fill rows from the pool. `rowsLen` is the logical length;
-        // _tooltipRowPool.length is the high-water mark capacity.
-        let rowsLen = 0;
+        // Build rows. ALLOCATES, but this fires at mousemove rate, not per-frame.
+        const rows = [];
         for (let i = 0; i < seriesStates.length; i++) {
             if (!seriesRefs[i].visibleRef.value) continue;
             const s = seriesStates[i];
             if (s.n === 0) continue;
             const myIdx = renderer.lookupRow(s, state.snapIdx, state.snapDomainX, rendererCtx);
             if (myIdx < 0) continue;
-            _ensureRowPool(rowsLen + 1);
-            const row = _tooltipRowPool[rowsLen++];
-            row.color = seriesRefs[i].colorRef.value;
-            row.label = normalized[i].name;
-            // formatTooltipValue still allocates the value string -- it's
-            // built from formatNumber's char buffer per call. Pooling the
-            // string itself would require a stable per-row char buffer
-            // and consumers that read .value before the next mousemove.
-            // Not worth the contract complexity for a few bytes; the row
-            // object reuse already covers the dominant allocation.
-            row.value = formatTooltipValue(s.ys[myIdx]);
-        }
-        if (rowsLen === 0) return;
+            rows.push({
+                color: seriesRefs[i].colorRef.value,
+                label: normalized[i].name,
+                value: formatTooltipValue(s.ys[myIdx]),
+            });
+        }
+        if (rows.length === 0) return;
 
         // Tooltip header: renderer picks the format (category name for bar,
         // formatted number/date for line/area).
@@ -3050,51 +3682,30 @@ const createBaseAxisChart = (config, renderer) => {
 
         // Custom formatter override: replace the whole row set + header.
         // `category` is preserved for the tooltipFormatter contract -- bar
-        // tooltips pass it; line/area pass null.
+        // tooltips pass it; line/area pass null. Use the header text the
+        // renderer produced as the default when the formatter doesn't supply one.
         const barCategoryName = renderer.forceXType === 'band'
-        && state.snapIdx >= 0
-        && state.snapIdx < categoriesRef.value.length
+            && state.snapIdx >= 0
+            && state.snapIdx < categoriesRef.value.length
             ? categoriesRef.value[state.snapIdx]
             : null;
         let headerText;
         if (tooltipFormatter) {
-            // Mutate the reused ctx in place. `rows` on the ctx points
-            // at the pool; we temporarily set its `length` so the user
-            // sees only the valid slice. Restore after the callback so
-            // the next mousemove starts from cap, not from the slice.
-            _tooltipFormatterCtx.snapIdx = state.snapIdx;
-            _tooltipFormatterCtx.snapDomainX = state.snapDomainX;
-            _tooltipFormatterCtx.xScaleType = resolvedXType;
-            _tooltipFormatterCtx.category = barCategoryName;
-            const cap = _tooltipRowPool.length;
-            _tooltipRowPool.length = rowsLen;
-            const out = tooltipFormatter(_tooltipFormatterCtx);
-            _tooltipRowPool.length = cap;
+            const out = tooltipFormatter({
+                snapIdx: state.snapIdx,
+                snapDomainX: state.snapDomainX,
+                xScaleType: resolvedXType,
+                category: barCategoryName,
+                rows,
+            });
             if (typeof out === 'string') {
                 headerText = out;
-                rowsLen = 0;
+                rows.length = 0;
             } else if (out && typeof out === 'object') {
                 headerText = out.header != null ? out.header : defaultHeaderText;
                 if (Array.isArray(out.rows)) {
-                    // User-supplied row array -- copy into pool. We could
-                    // skip the copy if `out.rows === _tooltipRowPool` (the
-                    // common "mutate the rows in place" pattern); detect
-                    // that and short-circuit.
-                    if (out.rows === _tooltipRowPool) {
-                        // user mutated our pool directly; len = out.rows.length
-                        // but capped at our actual pool size
-                        rowsLen = out.rows.length;
-                    } else {
-                        _ensureRowPool(out.rows.length);
-                        rowsLen = out.rows.length;
-                        for (let i = 0; i < rowsLen; i++) {
-                            const src = out.rows[i];
-                            const dst = _tooltipRowPool[i];
-                            dst.color = src.color;
-                            dst.label = src.label;
-                            dst.value = src.value;
-                        }
-                    }
+                    rows.length = 0;
+                    for (let i = 0; i < out.rows.length; i++) rows.push(out.rows[i]);
                 }
             } else {
                 headerText = defaultHeaderText;
@@ -3103,21 +3714,15 @@ const createBaseAxisChart = (config, renderer) => {
             headerText = defaultHeaderText;
         }
 
-        // Measure widths. Avoid the `label + ': ' + value` allocation by
-        // measuring pieces separately and summing.
+        // Measure widths.
         ctx.font = axisStyleRefs.font.value;
         let maxRowWidth = ctx.measureText(headerText).width;
-        const colonWidth = ctx.measureText(': ').width;
-        for (let i = 0; i < rowsLen; i++) {
-            const r = _tooltipRowPool[i];
-            const w = swatch + 6
-                + ctx.measureText(r.label).width
-                + colonWidth
-                + ctx.measureText(r.value).width;
+        for (let i = 0; i < rows.length; i++) {
+            const w = swatch + 6 + ctx.measureText(rows[i].label + ': ' + rows[i].value).width;
             if (w > maxRowWidth) maxRowWidth = w;
         }
         const boxW = maxRowWidth + padding * 2;
-        const boxH = (rowsLen + 1) * lineHeight + padding;
+        const boxH = (rows.length + 1) * lineHeight + padding;
 
         // Position: right of the crosshair, flip left if the box would clip
         // the right plot edge. Vertically centered on the cursor, clamped to
@@ -3144,24 +3749,13 @@ const createBaseAxisChart = (config, renderer) => {
         ctx.textBaseline = 'top';
         ctx.fillText(headerText, boxX + padding, boxY + padding);
 
-        // Rows. Two fillText calls per row -- label + colon, then value --
-        // so we don't allocate `label + ': ' + value` per draw. Label and
-        // value already exist as stable strings on the row object.
-        const labelColor = axisStyleRefs.labelColor.value;
-        for (let i = 0; i < rowsLen; i++) {
-            const r = _tooltipRowPool[i];
+        // Rows.
+        for (let i = 0; i < rows.length; i++) {
             const rowY = boxY + padding + (i + 1) * lineHeight;
-            ctx.fillStyle = r.color;
+            ctx.fillStyle = rows[i].color;
             ctx.fillRect(boxX + padding, rowY + 2, swatch, swatch);
-            ctx.fillStyle = labelColor;
-            const labelX = boxX + padding + swatch + 6;
-            ctx.fillText(r.label, labelX, rowY);
-            // Continue with ': ' + value at the measured offset. measureText
-            // here is cheap (cached glyph metrics in real browsers) and
-            // avoids the per-row string concat.
-            const labelW = ctx.measureText(r.label).width;
-            ctx.fillText(': ', labelX + labelW, rowY);
-            ctx.fillText(r.value, labelX + labelW + ctx.measureText(': ').width, rowY);
+            ctx.fillStyle = axisStyleRefs.labelColor.value;
+            ctx.fillText(rows[i].label + ': ' + rows[i].value, boxX + padding + swatch + 6, rowY);
         }
     };
 
@@ -3210,24 +3804,12 @@ const createBaseAxisChart = (config, renderer) => {
         hideCrosshair,
         setSeriesVisible,
         refreshTheme,
-        get scene() {
-            return scene;
-        },
-        get canvas() {
-            return canvas;
-        },
-        get xScale() {
-            return xScale;
-        },
-        get yScale() {
-            return yScale;
-        },
-        get xScaleType() {
-            return resolvedXType;
-        },
-        get legend() {
-            return legendEl;
-        },
+        get scene() { return scene; },
+        get canvas() { return canvas; },
+        get xScale() { return xScale; },
+        get yScale() { return yScale; },
+        get xScaleType() { return resolvedXType; },
+        get legend() { return legendEl; },
         plotBounds: plotBoundsSignal,
         crosshair: crosshairFacade,
         seriesVisibility,
@@ -3338,7 +3920,7 @@ const extractSliceData = (state, input) => {
         return;
     }
 
-    state.values = ensureFloat32(state.values, n);
+    state.values      = ensureFloat32(state.values,      n);
 
     // Angles need Float64 precision: Float32(PI/2) = 1.5707963705..., which
     // is SLIGHTLY larger than the Float64 PI/2 = 1.5707963267... that
@@ -3493,7 +4075,7 @@ const makeSliceDrawFn = (state, geometry, colorsRef, sliceStrokeRef, sliceStroke
         ctx.fillStyle = fill;
         ctx.beginPath();
         if (rInner > 0) {
-            ctx.arc(cx, cy, ro, a0, a1);
+            ctx.arc(cx, cy, ro,     a0, a1);
             ctx.arc(cx, cy, rInner, a1, a0, true);
             ctx.closePath();
         } else {
@@ -3560,7 +4142,7 @@ const buildPolarLegendDOM = (state, sliceVisibility, font, labelColor, disposers
     legendEl.style.color = labelColor;
     legendEl.style.lineHeight = '1.4';
     legendEl.style.alignItems = 'center';
-    return {legendEl, refresh: null}; // populated below; refresh defined in mount
+    return { legendEl, refresh: null }; // populated below; refresh defined in mount
 };
 
 // Populate the legend element with one row per slice. Called after the
@@ -3637,7 +4219,7 @@ const SLICE_RENDERER = {
 // createBasePolarChart -- the shared scaffold for slice-based polar charts
 // ===========================================================================
 
-const DEFAULT_PIE_MARGIN = {top: 16, right: 16, bottom: 16, left: 16};
+const DEFAULT_PIE_MARGIN = { top: 16, right: 16, bottom: 16, left: 16 };
 // Default palette for slices when the user doesn't supply per-slice colors.
 // Eight-slot tableau-style cycle; resolvable as raw hex (no CSS-var lookup).
 const DEFAULT_SLICE_PALETTE = [
@@ -3683,17 +4265,17 @@ const createBasePolarChart = (config, renderer) => {
     const heightSig = heightExplicit ? asAccessor(config.height) : heightAutoSig;
 
     const margin = config.margin || DEFAULT_PIE_MARGIN;
-    const marginTop = margin.top != null ? margin.top : DEFAULT_PIE_MARGIN.top;
-    const marginRight = margin.right != null ? margin.right : DEFAULT_PIE_MARGIN.right;
+    const marginTop    = margin.top    != null ? margin.top    : DEFAULT_PIE_MARGIN.top;
+    const marginRight  = margin.right  != null ? margin.right  : DEFAULT_PIE_MARGIN.right;
     const marginBottom = margin.bottom != null ? margin.bottom : DEFAULT_PIE_MARGIN.bottom;
-    const marginLeft = margin.left != null ? margin.left : DEFAULT_PIE_MARGIN.left;
+    const marginLeft   = margin.left   != null ? margin.left   : DEFAULT_PIE_MARGIN.left;
 
     const innerRadiusConfig = config.innerRadius != null ? config.innerRadius : 0;
 
     // ---- Chart state --------------------------------------------------
     const state = makePolarState();
-    const geometry = {cx: 0, cy: 0, rOuter: 0, rInner: 0};
-    const plotBoundsBox = {x: 0, y: 0, w: 0, h: 0};
+    const geometry = { cx: 0, cy: 0, rOuter: 0, rInner: 0 };
+    const plotBoundsBox = { x: 0, y: 0, w: 0, h: 0 };
     const plotBoundsSignal = signal(0);
     const dataVersion = signal(0);            // bumps on data / visibility change
 
@@ -3715,15 +4297,15 @@ const createBasePolarChart = (config, renderer) => {
     };
 
     // ---- Style refs (theme-reactive) ----------------------------------
-    const sliceStrokeRef = {value: '#ffffff'};
-    const sliceStrokeWidthRef = {value: config.sliceStrokeWidth != null ? +config.sliceStrokeWidth : 1};
-    const labelColorRef = {value: '#444444'};
-    const fontRef = {value: config.font != null ? config.font : '11px sans-serif'};
-    const tooltipBgRef = {value: 'rgba(255,255,255,0.96)'};
-    const tooltipBorderRef = {value: '#cccccc'};
+    const sliceStrokeRef      = { value: '#ffffff' };
+    const sliceStrokeWidthRef = { value: config.sliceStrokeWidth != null ? +config.sliceStrokeWidth : 1 };
+    const labelColorRef       = { value: '#444444' };
+    const fontRef             = { value: config.font != null ? config.font : '11px sans-serif' };
+    const tooltipBgRef        = { value: 'rgba(255,255,255,0.96)' };
+    const tooltipBorderRef    = { value: '#cccccc' };
     // Highlight: index of slice under cursor; -1 = none. Read on every
     // draw; mutated by mouse handler.
-    const highlightRef = {value: -1};
+    const highlightRef        = { value: -1 };
 
     // ---- Crosshair facade (highlight + tooltip) -----------------------
     // For polar charts the "crosshair" is just a slice highlight + tooltip.
@@ -3736,10 +4318,7 @@ const createBasePolarChart = (config, renderer) => {
         mousePixelY: 0,
     };
     const crosshairVersion = signal(0);
-    const crosshairFacade = function () {
-        crosshairVersion();
-        return crosshairData;
-    };
+    const crosshairFacade = function () { crosshairVersion(); return crosshairData; };
     crosshairFacade.peek = () => crosshairData;
     crosshairFacade.set = (s) => {
         if (!s || typeof s !== 'object') return;
@@ -3832,10 +4411,10 @@ const createBasePolarChart = (config, renderer) => {
         canvas.height = h0;
 
         // Resolve theme colors first so the first draw is correct.
-        sliceStrokeRef.value = resolveColor(config.sliceStroke != null ? config.sliceStroke : '#ffffff', container);
-        labelColorRef.value = resolveColor(config.labelColor != null ? config.labelColor : '#444444', container);
-        tooltipBgRef.value = resolveColor(tooltipOpts && tooltipOpts.background ? tooltipOpts.background : 'rgba(255,255,255,0.96)', container);
-        tooltipBorderRef.value = resolveColor(tooltipOpts && tooltipOpts.border ? tooltipOpts.border : '#cccccc', container);
+        sliceStrokeRef.value      = resolveColor(config.sliceStroke != null ? config.sliceStroke : '#ffffff', container);
+        labelColorRef.value       = resolveColor(config.labelColor != null ? config.labelColor : '#444444', container);
+        tooltipBgRef.value        = resolveColor(tooltipOpts && tooltipOpts.background ? tooltipOpts.background : 'rgba(255,255,255,0.96)', container);
+        tooltipBorderRef.value    = resolveColor(tooltipOpts && tooltipOpts.border ? tooltipOpts.border : '#cccccc', container);
 
         const schedule = config.schedule || (typeof requestAnimationFrame === 'function' ? requestAnimationFrame : (cb) => cb());
         scene = createScene(canvas, {
@@ -3853,10 +4432,10 @@ const createBasePolarChart = (config, renderer) => {
             const h = +heightSig() | 0 || 400;
             const wBacking = Math.max(1, Math.round(w * resolvedDpr));
             const hBacking = Math.max(1, Math.round(h * resolvedDpr));
-            if (canvas.width !== wBacking) canvas.width = wBacking;
+            if (canvas.width  !== wBacking) canvas.width  = wBacking;
             if (canvas.height !== hBacking) canvas.height = hBacking;
             if (typeof canvas.style !== 'undefined') {
-                canvas.style.width = w + 'px';
+                canvas.style.width  = w + 'px';
                 canvas.style.height = h + 'px';
             }
             plotBoundsBox.x = marginLeft;
@@ -3907,7 +4486,7 @@ const createBasePolarChart = (config, renderer) => {
 
         // ---- Slice draw node -------------------------------------------
         const sliceDrawFn = renderer.makeDrawFn(state, geometry, resolvedColors, sliceStrokeRef, sliceStrokeWidthRef, highlightRef);
-        const sliceNode = scene.root.add(pathNode({draw: sliceDrawFn}));
+        const sliceNode = scene.root.add(pathNode({ draw: (ctx) => sliceDrawFn(ctx) }));
 
         // Effect 4: dirty bridge for data/geometry changes
         disposers.push(effect(() => {
@@ -3918,7 +4497,7 @@ const createBasePolarChart = (config, renderer) => {
 
         // ---- Crosshair / tooltip (slice highlight + box) --------------
         if (interactionEnabled) {
-            const crosshairNode = scene.root.add(pathNode({draw: drawCrosshair}));
+            const crosshairNode = scene.root.add(pathNode({ draw: (ctx) => drawCrosshair(ctx) }));
             disposers.push(effect(() => {
                 crosshairVersion();
                 if (scene) scene.markDirty();
@@ -3928,7 +4507,7 @@ const createBasePolarChart = (config, renderer) => {
                 const onMove = (e) => {
                     const rect = typeof canvas.getBoundingClientRect === 'function'
                         ? canvas.getBoundingClientRect()
-                        : {left: 0, top: 0, width: canvas.width, height: canvas.height};
+                        : { left: 0, top: 0, width: canvas.width, height: canvas.height };
                     moveCrosshair(e.clientX - rect.left, e.clientY - rect.top);
                 };
                 const onLeave = () => hideCrosshair();
@@ -3967,17 +4546,11 @@ const createBasePolarChart = (config, renderer) => {
     const unmount = () => {
         if (!mounted) return;
         for (let i = 0; i < disposers.length; i++) {
-            try {
-                disposers[i]();
-            } catch (e) { /* swallow */
-            }
+            try { disposers[i](); } catch (e) { /* swallow */ }
         }
         disposers.length = 0;
         if (scene) {
-            try {
-                scene.dispose();
-            } catch (e) { /* swallow */
-            }
+            try { scene.dispose(); } catch (e) { /* swallow */ }
             scene = null;
         }
         if (legendWrapper && legendWrapper.parentNode) {
@@ -4058,10 +4631,8 @@ const createBasePolarChart = (config, renderer) => {
                 total: state.total,
                 percent: pct,
             });
-            if (typeof out === 'string') {
-                header = out;
-                rowText = '';
-            } else if (out && typeof out === 'object') {
+            if (typeof out === 'string') { header = out; rowText = ''; }
+            else if (out && typeof out === 'object') {
                 if (out.header != null) header = out.header;
                 if (out.value != null) rowText = out.value;
             }
@@ -4118,9 +4689,7 @@ const createBasePolarChart = (config, renderer) => {
             const q = opts && opts.quality != null ? opts.quality : 0.92;
             return canvas.toDataURL(mt, q);
         },
-        redraw: () => {
-            if (scene) scene.markDirty();
-        },
+        redraw: () => { if (scene) scene.markDirty(); },
         moveCrosshair,
         hideCrosshair,
         setSliceVisible: (idx, visible) => {
@@ -4129,10 +4698,10 @@ const createBasePolarChart = (config, renderer) => {
         },
         refreshTheme: () => {
             if (!mounted) return;
-            sliceStrokeRef.value = resolveColor(config.sliceStroke != null ? config.sliceStroke : '#ffffff', container);
-            labelColorRef.value = resolveColor(config.labelColor != null ? config.labelColor : '#444444', container);
-            tooltipBgRef.value = resolveColor(tooltipOpts && tooltipOpts.background ? tooltipOpts.background : 'rgba(255,255,255,0.96)', container);
-            tooltipBorderRef.value = resolveColor(tooltipOpts && tooltipOpts.border ? tooltipOpts.border : '#cccccc', container);
+            sliceStrokeRef.value   = resolveColor(config.sliceStroke != null ? config.sliceStroke : '#ffffff', container);
+            labelColorRef.value    = resolveColor(config.labelColor  != null ? config.labelColor  : '#444444', container);
+            tooltipBgRef.value     = resolveColor(tooltipOpts && tooltipOpts.background ? tooltipOpts.background : 'rgba(255,255,255,0.96)', container);
+            tooltipBorderRef.value = resolveColor(tooltipOpts && tooltipOpts.border     ? tooltipOpts.border     : '#cccccc', container);
             refreshResolvedColors();
             // Re-paint legend swatches
             if (legendEl) {
@@ -4143,18 +4712,10 @@ const createBasePolarChart = (config, renderer) => {
             }
             if (scene) scene.markDirty();
         },
-        get scene() {
-            return scene;
-        },
-        get canvas() {
-            return canvas;
-        },
-        get geometry() {
-            return geometry;
-        },
-        get legend() {
-            return legendEl;
-        },
+        get scene() { return scene; },
+        get canvas() { return canvas; },
+        get geometry() { return geometry; },
+        get legend() { return legendEl; },
         plotBounds: plotBoundsSignal,
         crosshair: crosshairFacade,
         sliceVisibility,
@@ -4274,11 +4835,18 @@ const computeRadarGeometry = (geometry, plotBoundsBox, axisCount) => {
 // state, all reads happen at frame time so reactivity + theme changes
 // propagate without recreating closures.
 
-// (A `_radarPoint(geometry, axisIdx, value, vMin, vSpan)` helper was
-// considered but never landed -- the polygon, hit-test, and tooltip paths
-// all inline the same r/x/y math directly to avoid the per-call {x, y}
-// allocation an out-of-line helper would force. Keeping the comment as
-// a "do not reintroduce" marker.)
+// Convert a (value, axisIdx) pair to a pixel point on the chart. Domain is
+// [vMin, vMax] (shared across all axes -- MVP radar uses one domain;
+// per-axis domains can land in v1.3 with the multi-scale infrastructure).
+const _radarPoint = (geometry, axisIdx, value, vMin, vSpan) => {
+    const t = vSpan > 0 ? (value - vMin) / vSpan : 0;
+    const tClamp = t < 0 ? 0 : t > 1 ? 1 : t;
+    const r = geometry.rOuter * tClamp;
+    return {
+        x: geometry.cx + r * geometry.cosA[axisIdx],
+        y: geometry.cy + r * geometry.sinA[axisIdx],
+    };
+};
 
 // Polygon draw: one fill (alpha) + one stroke per visible series.
 // All series share the same geometry + value domain.
@@ -4440,7 +5008,7 @@ const radarHitTest = (canvasX, canvasY, states, geometry, domainRef) => {
 // createRadarChart -- the kernel + factory in one
 // ===========================================================================
 
-const DEFAULT_RADAR_MARGIN = {top: 24, right: 24, bottom: 24, left: 24};
+const DEFAULT_RADAR_MARGIN = { top: 24, right: 24, bottom: 24, left: 24 };
 
 export const createRadarChart = (config) => {
     if (!config || typeof config !== 'object') {
@@ -4453,7 +5021,7 @@ export const createRadarChart = (config) => {
         throw new Error('lite-charts: createRadarChart requires at least 3 axes');
     }
     const axisCount = axisLabelsInitial.length;
-    const axisLabelsRef = {value: axisLabelsInitial};
+    const axisLabelsRef = { value: axisLabelsInitial };
 
     // Series input: either a function returning array (reactive) or an
     // array directly. Each series: { name, color, values: [N] }.
@@ -4476,10 +5044,10 @@ export const createRadarChart = (config) => {
     const heightSig = heightExplicit ? asAccessor(config.height) : heightAutoSig;
 
     const margin = config.margin || DEFAULT_RADAR_MARGIN;
-    const marginTop = margin.top != null ? margin.top : DEFAULT_RADAR_MARGIN.top;
-    const marginRight = margin.right != null ? margin.right : DEFAULT_RADAR_MARGIN.right;
+    const marginTop    = margin.top    != null ? margin.top    : DEFAULT_RADAR_MARGIN.top;
+    const marginRight  = margin.right  != null ? margin.right  : DEFAULT_RADAR_MARGIN.right;
     const marginBottom = margin.bottom != null ? margin.bottom : DEFAULT_RADAR_MARGIN.bottom;
-    const marginLeft = margin.left != null ? margin.left : DEFAULT_RADAR_MARGIN.left;
+    const marginLeft   = margin.left   != null ? margin.left   : DEFAULT_RADAR_MARGIN.left;
 
     const gridTicks = config.gridTicks != null ? Math.max(1, +config.gridTicks | 0) : 4;
 
@@ -4487,7 +5055,7 @@ export const createRadarChart = (config) => {
     // domainRef is a stable object reference; mutated in place by the data
     // effect so draw fns always see fresh values.
     const explicitDomain = Array.isArray(config.domain) ? [+config.domain[0], +config.domain[1]] : null;
-    const domainRef = {value: explicitDomain ? explicitDomain : [0, 1]};
+    const domainRef = { value: explicitDomain ? explicitDomain : [0, 1] };
 
     // ---- State (per-series) ------------------------------------------
     const seriesStates = [];               // array of RadarSeriesState
@@ -4505,19 +5073,19 @@ export const createRadarChart = (config) => {
         cosA: new Float64Array(Math.max(axisCount, 4)),
         sinA: new Float64Array(Math.max(axisCount, 4)),
     };
-    const plotBoundsBox = {x: 0, y: 0, w: 0, h: 0};
+    const plotBoundsBox = { x: 0, y: 0, w: 0, h: 0 };
     const plotBoundsSignal = signal(0);
     const dataVersion = signal(0);
 
     // ---- Style refs --------------------------------------------------
-    const axisColorRef = {value: '#cccccc'};
-    const gridColorRef = {value: '#e6e6e6'};
-    const labelColorRef = {value: '#444444'};
-    const fontRef = {value: config.font != null ? config.font : '11px sans-serif'};
-    const fillOpacityRef = {value: config.fillOpacity != null ? +config.fillOpacity : 0.2};
-    const strokeWidthRef = {value: config.strokeWidth != null ? +config.strokeWidth : 2};
-    const tooltipBgRef = {value: 'rgba(255,255,255,0.96)'};
-    const tooltipBorderRef = {value: '#cccccc'};
+    const axisColorRef       = { value: '#cccccc' };
+    const gridColorRef       = { value: '#e6e6e6' };
+    const labelColorRef      = { value: '#444444' };
+    const fontRef            = { value: config.font != null ? config.font : '11px sans-serif' };
+    const fillOpacityRef     = { value: config.fillOpacity != null ? +config.fillOpacity : 0.2 };
+    const strokeWidthRef     = { value: config.strokeWidth != null ? +config.strokeWidth : 2 };
+    const tooltipBgRef       = { value: 'rgba(255,255,255,0.96)' };
+    const tooltipBorderRef   = { value: '#cccccc' };
 
     // ---- Crosshair facade --------------------------------------------
     const crosshairData = {
@@ -4529,10 +5097,7 @@ export const createRadarChart = (config) => {
         mousePixelY: 0,
     };
     const crosshairVersion = signal(0);
-    const crosshairFacade = function () {
-        crosshairVersion();
-        return crosshairData;
-    };
+    const crosshairFacade = function () { crosshairVersion(); return crosshairData; };
     crosshairFacade.peek = () => crosshairData;
     crosshairFacade.subscribe = (cb) => crosshairVersion.subscribe(() => cb(crosshairData));
 
@@ -4605,11 +5170,11 @@ export const createRadarChart = (config) => {
         canvas.width = w0;
         canvas.height = h0;
 
-        axisColorRef.value = resolveColor(config.axisColor != null ? config.axisColor : '#cccccc', container);
-        gridColorRef.value = resolveColor(config.gridColor != null ? config.gridColor : '#e6e6e6', container);
-        labelColorRef.value = resolveColor(config.labelColor != null ? config.labelColor : '#444444', container);
-        tooltipBgRef.value = resolveColor(tooltipOpts && tooltipOpts.background ? tooltipOpts.background : 'rgba(255,255,255,0.96)', container);
-        tooltipBorderRef.value = resolveColor(tooltipOpts && tooltipOpts.border ? tooltipOpts.border : '#cccccc', container);
+        axisColorRef.value      = resolveColor(config.axisColor   != null ? config.axisColor   : '#cccccc', container);
+        gridColorRef.value      = resolveColor(config.gridColor   != null ? config.gridColor   : '#e6e6e6', container);
+        labelColorRef.value     = resolveColor(config.labelColor  != null ? config.labelColor  : '#444444', container);
+        tooltipBgRef.value      = resolveColor(tooltipOpts && tooltipOpts.background ? tooltipOpts.background : 'rgba(255,255,255,0.96)', container);
+        tooltipBorderRef.value  = resolveColor(tooltipOpts && tooltipOpts.border     ? tooltipOpts.border     : '#cccccc', container);
 
         const schedule = config.schedule || (typeof requestAnimationFrame === 'function' ? requestAnimationFrame : (cb) => cb());
         scene = createScene(canvas, {
@@ -4626,10 +5191,10 @@ export const createRadarChart = (config) => {
             const h = +heightSig() | 0 || 400;
             const wBacking = Math.max(1, Math.round(w * resolvedDpr));
             const hBacking = Math.max(1, Math.round(h * resolvedDpr));
-            if (canvas.width !== wBacking) canvas.width = wBacking;
+            if (canvas.width  !== wBacking) canvas.width  = wBacking;
             if (canvas.height !== hBacking) canvas.height = hBacking;
             if (typeof canvas.style !== 'undefined') {
-                canvas.style.width = w + 'px';
+                canvas.style.width  = w + 'px';
                 canvas.style.height = h + 'px';
             }
             plotBoundsBox.x = marginLeft;
@@ -4672,10 +5237,7 @@ export const createRadarChart = (config) => {
                         anyData = true;
                     }
                 }
-                if (!anyData) {
-                    vMin = 0;
-                    vMax = 1;
-                }
+                if (!anyData) { vMin = 0; vMax = 1; }
                 if (vMin === vMax) vMax = vMin + 1;
                 // Anchor at 0 if everything's non-negative (the conventional radar look).
                 if (vMin > 0 && vMin / vMax < 0.5) vMin = 0;
@@ -4700,13 +5262,13 @@ export const createRadarChart = (config) => {
         }));
 
         // Scene nodes (z-ordered): grid -> polygons -> spokes+labels -> crosshair
-        const gridDrawFn = makeRadarGridDrawFn(geometry, gridTicks, gridColorRef);
-        const polygonDrawFn = makeRadarPolygonDrawFn(seriesStates, resolvedColors, geometry, domainRef, fillOpacityRef, strokeWidthRef);
-        const spokesDrawFn = makeRadarSpokesDrawFn(geometry, axisLabelsRef, axisColorRef, labelColorRef, fontRef);
+        const gridDrawFn     = makeRadarGridDrawFn(geometry, gridTicks, gridColorRef);
+        const polygonDrawFn  = makeRadarPolygonDrawFn(seriesStates, resolvedColors, geometry, domainRef, fillOpacityRef, strokeWidthRef);
+        const spokesDrawFn   = makeRadarSpokesDrawFn(geometry, axisLabelsRef, axisColorRef, labelColorRef, fontRef);
 
-        scene.root.add(pathNode({draw: gridDrawFn}));
-        scene.root.add(pathNode({draw: polygonDrawFn}));
-        scene.root.add(pathNode({draw: spokesDrawFn}));
+        scene.root.add(pathNode({ draw: (ctx) => gridDrawFn(ctx) }));
+        scene.root.add(pathNode({ draw: (ctx) => polygonDrawFn(ctx) }));
+        scene.root.add(pathNode({ draw: (ctx) => spokesDrawFn(ctx) }));
 
         // Dirty bridge: data + plotBounds -> markDirty
         disposers.push(effect(() => {
@@ -4717,7 +5279,7 @@ export const createRadarChart = (config) => {
 
         // Crosshair / tooltip
         if (interactionEnabled) {
-            scene.root.add(pathNode({draw: drawCrosshair}));
+            scene.root.add(pathNode({ draw: (ctx) => drawCrosshair(ctx) }));
             disposers.push(effect(() => {
                 crosshairVersion();
                 if (scene) scene.markDirty();
@@ -4726,7 +5288,7 @@ export const createRadarChart = (config) => {
                 const onMove = (e) => {
                     const rect = typeof canvas.getBoundingClientRect === 'function'
                         ? canvas.getBoundingClientRect()
-                        : {left: 0, top: 0, width: canvas.width, height: canvas.height};
+                        : { left: 0, top: 0, width: canvas.width, height: canvas.height };
                     moveCrosshair(e.clientX - rect.left, e.clientY - rect.top);
                 };
                 const onLeave = () => hideCrosshair();
@@ -4814,17 +5376,11 @@ export const createRadarChart = (config) => {
     const unmount = () => {
         if (!mounted) return;
         for (let i = 0; i < disposers.length; i++) {
-            try {
-                disposers[i]();
-            } catch (e) { /* swallow */
-            }
+            try { disposers[i](); } catch (e) { /* swallow */ }
         }
         disposers.length = 0;
         if (scene) {
-            try {
-                scene.dispose();
-            } catch (e) { /* swallow */
-            }
+            try { scene.dispose(); } catch (e) { /* swallow */ }
             scene = null;
         }
         if (legendWrapper && legendWrapper.parentNode) {
@@ -4845,10 +5401,7 @@ export const createRadarChart = (config) => {
     const moveCrosshair = (canvasX, canvasY) => {
         if (!interactionEnabled || !mounted) return;
         const hit = radarHitTest(canvasX, canvasY, seriesStates, geometry, domainRef);
-        if (!hit) {
-            hideCrosshair();
-            return;
-        }
+        if (!hit) { hideCrosshair(); return; }
         if (crosshairData.visible
             && crosshairData.seriesIdx === hit.seriesIdx
             && crosshairData.axisIdx === hit.axisIdx
@@ -4907,15 +5460,10 @@ export const createRadarChart = (config) => {
                 value: crosshairData.value,
                 rows,
             });
-            if (typeof out === 'string') {
-                header = out;
-                rows.length = 0;
-            } else if (out && typeof out === 'object') {
+            if (typeof out === 'string') { header = out; rows.length = 0; }
+            else if (out && typeof out === 'object') {
                 if (out.header != null) header = out.header;
-                if (Array.isArray(out.rows)) {
-                    rows.length = 0;
-                    for (let i = 0; i < out.rows.length; i++) rows.push(out.rows[i]);
-                }
+                if (Array.isArray(out.rows)) { rows.length = 0; for (let i = 0; i < out.rows.length; i++) rows.push(out.rows[i]); }
             }
         }
 
@@ -4974,9 +5522,7 @@ export const createRadarChart = (config) => {
             const q = opts && opts.quality != null ? opts.quality : 0.92;
             return canvas.toDataURL(mt, q);
         },
-        redraw: () => {
-            if (scene) scene.markDirty();
-        },
+        redraw: () => { if (scene) scene.markDirty(); },
         moveCrosshair,
         hideCrosshair,
         setSeriesVisible: (idx, visible) => {
@@ -4985,30 +5531,20 @@ export const createRadarChart = (config) => {
         },
         refreshTheme: () => {
             if (!mounted) return;
-            axisColorRef.value = resolveColor(config.axisColor != null ? config.axisColor : '#cccccc', container);
-            gridColorRef.value = resolveColor(config.gridColor != null ? config.gridColor : '#e6e6e6', container);
-            labelColorRef.value = resolveColor(config.labelColor != null ? config.labelColor : '#444444', container);
-            tooltipBgRef.value = resolveColor(tooltipOpts && tooltipOpts.background ? tooltipOpts.background : 'rgba(255,255,255,0.96)', container);
-            tooltipBorderRef.value = resolveColor(tooltipOpts && tooltipOpts.border ? tooltipOpts.border : '#cccccc', container);
+            axisColorRef.value     = resolveColor(config.axisColor   != null ? config.axisColor   : '#cccccc', container);
+            gridColorRef.value     = resolveColor(config.gridColor   != null ? config.gridColor   : '#e6e6e6', container);
+            labelColorRef.value    = resolveColor(config.labelColor  != null ? config.labelColor  : '#444444', container);
+            tooltipBgRef.value     = resolveColor(tooltipOpts && tooltipOpts.background ? tooltipOpts.background : 'rgba(255,255,255,0.96)', container);
+            tooltipBorderRef.value = resolveColor(tooltipOpts && tooltipOpts.border     ? tooltipOpts.border     : '#cccccc', container);
             refreshResolvedColors();
             if (legendEl) populateRadarLegend();
             if (scene) scene.markDirty();
         },
-        get scene() {
-            return scene;
-        },
-        get canvas() {
-            return canvas;
-        },
-        get geometry() {
-            return geometry;
-        },
-        get domain() {
-            return domainRef.value.slice();
-        },
-        get legend() {
-            return legendEl;
-        },
+        get scene() { return scene; },
+        get canvas() { return canvas; },
+        get geometry() { return geometry; },
+        get domain() { return domainRef.value.slice(); },
+        get legend() { return legendEl; },
         plotBounds: plotBoundsSignal,
         crosshair: crosshairFacade,
         seriesVisibility,
@@ -5068,10 +5604,45 @@ export const _testHelpers = {
     makeRadarSeriesState,
 };
 
+/**
+ * Create a line chart. Reactive in `data`, `width`, `height`, `series`;
+ * driven by signal-native data + axis kernel + decimation hot path.
+ *
+ * Steady-state `chart.redraw()` is allocation-free (~0 B/call measured).
+ * For >2k visible points the renderer switches to a per-column min/max
+ * decimation pass that scales sub-linearly with N; under 2k it draws
+ * direct polylines.
+ *
+ * @param {import("./Charts.d.ts").LineChartConfig} config
+ * @returns {import("./Charts.d.ts").Chart}
+ * @throws {TypeError} If `config.canvas` is missing and no `mount(host)` is called.
+ *
+ * @example
+ *   const data = signal({ xs: [0,1,2,3,4], ys: [10,20,15,25,30] });
+ *   const chart = createLineChart({ canvas, data, width: 800, height: 400 });
+ *   data.set({ xs, ys: newYs });   // triggers a re-extraction + decimation + redraw
+ *   chart.unmount();
+ */
 export const createLineChart = (config) => createBaseAxisChart(config, LINE_RENDERER);
 
+/**
+ * Create an area chart. Same kernel as the line chart; renders the area
+ * below each series as a filled path plus the upper stroke. `baseline` may
+ * be a numeric Y value or `"bottom"`.
+ *
+ * @param {import("./Charts.d.ts").AreaChartConfig} config
+ * @returns {import("./Charts.d.ts").Chart}
+ */
 export const createAreaChart = (config) => createBaseAxisChart(config, AREA_RENDERER);
 
+/**
+ * Create a bar chart. Single or grouped multi-series with a band X scale;
+ * supports stacked layout, rounded corners (via `roundRect` with `arcTo`
+ * fallback for older Canvas2D), and per-bar hover tint.
+ *
+ * @param {import("./Charts.d.ts").BarChartConfig} config
+ * @returns {import("./Charts.d.ts").Chart}
+ */
 export const createBarChart = (config) => createBaseAxisChart(config, BAR_RENDERER);
 
 // Bubble lives on the axis kernel via BUBBLE_RENDERER. Each point gets a
@@ -5080,6 +5651,15 @@ export const createBarChart = (config) => createBaseAxisChart(config, BAR_RENDER
 // the same as line/area/bar: importing only `createBubbleChart` drops the
 // polar kernel entirely and the line/area/bar renderers as expected.
 
+/**
+ * Create a bubble chart. Each point is a circle whose area encodes a
+ * third dimension by default (Tukey-style sqrt scale, switchable to
+ * linear). Multi-series supported; hit-test uses a spatial index when the
+ * point count crosses an internal threshold.
+ *
+ * @param {import("./Charts.d.ts").BubbleChartConfig} config
+ * @returns {import("./Charts.d.ts").Chart}
+ */
 export const createBubbleChart = (config) => createBaseAxisChart(config, BUBBLE_RENDERER);
 
 // Polar slice charts -- pie and donut share the SLICE_RENDERER. The only
@@ -5088,36 +5668,627 @@ export const createBubbleChart = (config) => createBaseAxisChart(config, BUBBLE_
 // Both go through createBasePolarChart (a completely separate kernel from
 // createBaseAxisChart -- importing only createPieChart drops all axis-chart
 // code: xScale/yScale/axes/grid/decimation/bisect/interp/bar helpers).
+
+/**
+ * Create a pie chart. Renders one slice per data point; hit-test uses an
+ * `atan2` lookup. Lives on the polar kernel (`createBasePolarChart`) --
+ * tree-shaking `createPieChart` alone drops all axis-chart code paths
+ * (xScale/yScale/axes/grid/decimation/bisect/interp/bar helpers).
+ *
+ * @param {import("./Charts.d.ts").PieChartConfig} config
+ * @returns {import("./Charts.d.ts").PolarChart}
+ */
+export const createPieChart = (config) =>
+    createBasePolarChart({ innerRadius: 0, ...(config || {}) }, SLICE_RENDERER);
+
+/**
+ * Create a donut chart. Same renderer as the pie chart with a default
+ * `innerRadius` of 0.5; pass any value in [0, 1) to override (still in
+ * the pie-chart factory's overridable space).
+ *
+ * @param {import("./Charts.d.ts").DonutChartConfig} config
+ * @returns {import("./Charts.d.ts").PolarChart}
+ */
+export const createDonutChart = (config) =>
+    createBasePolarChart({ innerRadius: 0.5, ...(config || {}) }, SLICE_RENDERER);
+
+/**
+ * Create a scatter chart. Bubble's simpler sibling on the axis kernel:
+ * same data + projection + hit-test path, constant marker size, no third
+ * dimension. Spatial index kicks in at the same N threshold as bubble.
+ *
+ * @param {import("./Charts.d.ts").ScatterChartConfig} config
+ * @returns {import("./Charts.d.ts").Chart}
+ */
+export const createScatterChart = (config) => createBaseAxisChart(config, SCATTER_RENDERER);
+
+// ===========================================================================
+// createBaseGridChart -- 2D categorical grid kernel (v1.2.0-alpha.3)
+// ===========================================================================
+//
+// A FOURTH independent kernel. Used by heatmap; future grid-shaped charts
+// (correlation matrix, calendar heatmap, dot-matrix) would ride here too.
+// Stays strictly separate from the axis kernel (no x-axis ticks, no
+// numeric y-scale, no decimation, no markers, no series in the line/bar
+// sense) and from the polar/radar kernels.
 //
-// `_applyInnerRadiusDefault` avoids the `{innerRadius, ...(config || {})}`
-// spread the factory used previously -- "no spread in source" hygiene.
+// The data model is a 2D grid of cells indexed by (x-category, y-category).
+// Each cell has at most one value; sparse data is supported (missing cells
+// render as empty space, the hit-test returns null for them).
+//
+// Key design points:
+//   - Two band scales (x + y) share the math from `makeBandScale`. The
+//     y band scale uses pixel coords with the same +y-down convention,
+//     so leftEdge(0) is the TOPMOST cell.
+//   - Cells are stored as a flat Float32Array indexed `yIdx * nx + xIdx`,
+//     matched by a Uint8Array `presentMask` for sparse data.
+//   - Per-cell colors are precomputed at extract time into a string Array
+//     (`state.cellColors`), so the draw loop is just
+//     `fillStyle = cellColors[i]; fillRect(...)` -- zero alloc per cell.
+//   - Hit-test is O(1) (one xBand.invert + one yBand.invert + mask check).
+//   - The default color ramp linearly interpolates between two endpoint
+//     hex colors at extract time; `colorFn` overrides for custom (OKLCH,
+//     quantile, diverging) mappings.
+
+const _DEFAULT_GRID_MARGIN = { top: 20, right: 24, bottom: 56, left: 80 };
+
+// Parse '#rgb' or '#rrggbb'. Returns [r, g, b] or null.
+const _parseHexColor = (hex) => {
+    if (typeof hex !== 'string' || hex.length === 0 || hex.charCodeAt(0) !== 35) return null;
+    let r, g, b;
+    if (hex.length === 7) {
+        r = parseInt(hex.slice(1, 3), 16);
+        g = parseInt(hex.slice(3, 5), 16);
+        b = parseInt(hex.slice(5, 7), 16);
+    } else if (hex.length === 4) {
+        r = parseInt(hex.charAt(1) + hex.charAt(1), 16);
+        g = parseInt(hex.charAt(2) + hex.charAt(2), 16);
+        b = parseInt(hex.charAt(3) + hex.charAt(3), 16);
+    } else {
+        return null;
+    }
+    if (r !== r || g !== g || b !== b) return null;  // NaN guards
+    return [r, g, b];
+};
+
+// Linear RGB interp -> 'rgb(r,g,b)' string. `lo` / `hi` are [r,g,b] arrays.
+// Allocates a string per call; called at extract time only (not in the
+// per-frame draw loop), so this is acceptable.
+const _lerpRGBString = (lo, hi, t) => {
+    const r = (lo[0] + t * (hi[0] - lo[0])) | 0;
+    const g = (lo[1] + t * (hi[1] - lo[1])) | 0;
+    const b = (lo[2] + t * (hi[2] - lo[2])) | 0;
+    return 'rgb(' + r + ',' + g + ',' + b + ')';
+};
+
+const _makeGridState = () => ({
+    cells: null,         // Float32Array | null; length = nx * ny
+    presentMask: null,   // Uint8Array | null
+    cellColors: null,    // Array<string|null> | null
+    xCategories: [],     // string[]
+    yCategories: [],     // string[]
+    nx: 0,
+    ny: 0,
+    vMin: 0,
+    vMax: 1,
+});
+
+const _extractGridData = (state, data, opts) => {
+    if (!Array.isArray(data) || data.length === 0) {
+        state.cells = null;
+        state.presentMask = null;
+        state.cellColors = null;
+        state.xCategories = [];
+        state.yCategories = [];
+        state.nx = 0;
+        state.ny = 0;
+        state.vMin = 0;
+        state.vMax = 1;
+        return;
+    }
 
-const _applyInnerRadiusDefault = (config, fallback) => {
-    if (config == null || typeof config !== 'object') {
-        return {innerRadius: fallback};
+    const xAcc = opts.xAccessor;
+    const yAcc = opts.yAccessor;
+    const vAcc = opts.valueAccessor;
+
+    // Pass 1: collect unique categories in first-seen order.
+    const xCats = [];
+    const yCats = [];
+    const xMap = new Map();
+    const yMap = new Map();
+    for (let i = 0; i < data.length; i++) {
+        const row = data[i];
+        const xv = String(xAcc(row, i));
+        const yv = String(yAcc(row, i));
+        if (!xMap.has(xv)) { xMap.set(xv, xCats.length); xCats.push(xv); }
+        if (!yMap.has(yv)) { yMap.set(yv, yCats.length); yCats.push(yv); }
     }
-    if (config.innerRadius != null) return config;
-    // Shallow-copy + set default. Done once at chart construction (not hot).
-    const out = {innerRadius: fallback};
-    for (const k in config) {
-        if (Object.prototype.hasOwnProperty.call(config, k)) out[k] = config[k];
+    const nx = xCats.length;
+    const ny = yCats.length;
+    const total = nx * ny;
+
+    state.xCategories = xCats;
+    state.yCategories = yCats;
+    state.nx = nx;
+    state.ny = ny;
+
+    // Grow buffers if needed (typed arrays don't shrink; that's fine -- the
+    // extra capacity is reusable on the next extract if the grid shrinks).
+    if (!state.cells || state.cells.length < total) state.cells = new Float32Array(total);
+    if (!state.presentMask || state.presentMask.length < total) state.presentMask = new Uint8Array(total);
+
+    // Zero the active region (presentMask = 0 means "missing cell").
+    for (let i = 0; i < total; i++) {
+        state.cells[i] = 0;
+        state.presentMask[i] = 0;
     }
-    return out;
+
+    // Pass 2: fill cells, track value extents.
+    let vMin = Infinity;
+    let vMax = -Infinity;
+    for (let i = 0; i < data.length; i++) {
+        const row = data[i];
+        const xv = String(xAcc(row, i));
+        const yv = String(yAcc(row, i));
+        const v = +vAcc(row, i);
+        if (v !== v) continue;  // NaN -> skip; cell stays "missing"
+        const xIdx = xMap.get(xv);
+        const yIdx = yMap.get(yv);
+        const cellIdx = yIdx * nx + xIdx;
+        state.cells[cellIdx] = v;
+        state.presentMask[cellIdx] = 1;
+        if (v < vMin) vMin = v;
+        if (v > vMax) vMax = v;
+    }
+    state.vMin = vMin === Infinity ? 0 : vMin;
+    state.vMax = vMax === -Infinity ? 1 : vMax;
 };
 
-export const createPieChart = (config) =>
-    createBasePolarChart(_applyInnerRadiusDefault(config, 0), SLICE_RENDERER);
+// Pre-compute the per-cell color string. Called once per extract; the
+// per-frame draw loop reads from state.cellColors[i] without allocating.
+const _computeGridColors = (state, opts) => {
+    const total = state.nx * state.ny;
+    if (total === 0) { state.cellColors = null; return; }
+    if (!state.cellColors || state.cellColors.length < total) state.cellColors = new Array(total);
 
-export const createDonutChart = (config) =>
-    createBasePolarChart(_applyInnerRadiusDefault(config, 0.5), SLICE_RENDERER);
+    const vMin = state.vMin;
+    const vMax = state.vMax;
+    const span = vMax - vMin;
+    const colorFn = opts.colorFn;
 
-// Stubs for the remaining chart types -- implemented in subsequent sessions.
-// Each will be a thin composition over a base kernel:
-//   createHeatmap = createBaseGridChart(config, HEATMAP_RENDERER)
+    if (colorFn) {
+        for (let i = 0; i < total; i++) {
+            state.cellColors[i] = state.presentMask[i] ? colorFn(state.cells[i], vMin, vMax) : null;
+        }
+        return;
+    }
 
-const _notYet = (name) => () => {
-    throw new Error('lite-charts: ' + name + ' is not in this version; see roadmap');
+    // Default: linear RGB interp between opts.colorLow and opts.colorHigh.
+    // Fall back to a safe blue ramp if hex parsing fails (CSS-vars, named
+    // colors, oklch() etc. would otherwise produce NaN channels).
+    const lo = _parseHexColor(opts.colorLow)  || [219, 234, 254];  // blue-100
+    const hi = _parseHexColor(opts.colorHigh) || [30, 58, 138];    // blue-900
+    for (let i = 0; i < total; i++) {
+        if (!state.presentMask[i]) { state.cellColors[i] = null; continue; }
+        const t = span > 0 ? (state.cells[i] - vMin) / span : 0;
+        state.cellColors[i] = _lerpRGBString(lo, hi, t);
+    }
 };
 
-export const createScatterChart = _notYet('createScatterChart');
-export const createHeatmap = _notYet('createHeatmap');
+const _makeGridDrawFn = (state, xBand, yBand, opts) => (ctx) => {
+    const nx = state.nx;
+    const ny = state.ny;
+    if (nx === 0 || ny === 0 || !state.cells || !state.cellColors) return;
+
+    const cellW = xBand.bandWidth;
+    const cellH = yBand.bandWidth;
+    const present = state.presentMask;
+    const colors = state.cellColors;
+
+    // Cells.
+    for (let yi = 0; yi < ny; yi++) {
+        const cy = yBand.leftEdge(yi);
+        for (let xi = 0; xi < nx; xi++) {
+            const idx = yi * nx + xi;
+            if (!present[idx]) continue;
+            ctx.fillStyle = colors[idx];
+            ctx.fillRect(xBand.leftEdge(xi), cy, cellW, cellH);
+        }
+    }
+
+    // Optional value labels. Drawn after all cells so labels sit on top.
+    if (opts.showValues) {
+        const cells = state.cells;
+        const fmt = opts.valueFormat || ((v) => v.toFixed(1));
+        ctx.font = opts.valueLabelFont;
+        ctx.textAlign = 'center';
+        ctx.textBaseline = 'middle';
+        ctx.fillStyle = opts.valueLabelColor;
+        for (let yi = 0; yi < ny; yi++) {
+            const cy = yBand.map(yi);
+            for (let xi = 0; xi < nx; xi++) {
+                const idx = yi * nx + xi;
+                if (!present[idx]) continue;
+                ctx.fillText(fmt(cells[idx], xi, yi), xBand.map(xi), cy);
+            }
+        }
+    }
+};
+
+const _gridHitTest = (canvasX, canvasY, xBand, yBand, state, pb) => {
+    if (state.nx === 0 || state.ny === 0) return null;
+    if (canvasX < pb.x || canvasX > pb.x + pb.w) return null;
+    if (canvasY < pb.y || canvasY > pb.y + pb.h) return null;
+    const xi = xBand.invert(canvasX);
+    const yi = yBand.invert(canvasY);
+    if (xi < 0 || yi < 0 || xi >= state.nx || yi >= state.ny) return null;
+    const idx = yi * state.nx + xi;
+    if (!state.presentMask[idx]) return null;
+    return { xi, yi, value: state.cells[idx] };
+};
+
+// ---- HEATMAP_RENDERER ----------------------------------------------------
+
+const _initHeatmapOpts = (config) => {
+    const xKey = config.x != null ? config.x : 'x';
+    const yKey = config.y != null ? config.y : 'y';
+    const valueKey = config.value != null ? config.value : 'value';
+    const colors = Array.isArray(config.colors) ? config.colors : null;
+    return {
+        xAccessor: buildRawAccessor(xKey),
+        yAccessor: buildRawAccessor(yKey),
+        valueAccessor: buildAccessor(valueKey),
+        // Default ramp: pale-to-dark blue. Override via `colors: ['#low', '#high']`.
+        colorLow: colors && colors[0] ? colors[0] : '#dbeafe',
+        colorHigh: colors && colors[1] ? colors[1] : '#1e3a8a',
+        // colorFn(v, vMin, vMax) -> 'css color'. Overrides the linear-interp
+        // default entirely; use this for OKLCH ramps, quantile binning,
+        // diverging schemes, etc.
+        colorFn: typeof config.colorFn === 'function' ? config.colorFn : null,
+        showValues: config.showValues === true,
+        valueFormat: typeof config.valueFormat === 'function' ? config.valueFormat : null,
+        valueLabelFont: config.valueLabelFont != null ? config.valueLabelFont : '11px sans-serif',
+        valueLabelColor: config.valueLabelColor != null ? config.valueLabelColor : '#ffffff',
+        cellGap: config.cellGap != null ? Math.max(0, Math.min(0.5, +config.cellGap)) : 0.04,
+        highlightStroke: config.highlightStroke != null ? config.highlightStroke : '#111111',
+        highlightStrokeWidth: config.highlightStrokeWidth != null ? +config.highlightStrokeWidth : 2,
+        tooltipFormat: typeof config.tooltipFormat === 'function' ? config.tooltipFormat : null,
+        labelColor: config.labelColor != null ? config.labelColor : '#444444',
+        labelFont: config.labelFont != null ? config.labelFont : '12px sans-serif',
+    };
+};
+
+const HEATMAP_RENDERER = {
+    initOpts: _initHeatmapOpts,
+    extractData: _extractGridData,
+    computeColors: _computeGridColors,
+    makeDrawFn: _makeGridDrawFn,
+    hitTest: _gridHitTest,
+};
+
+// ---- createBaseGridChart ------------------------------------------------
+
+const createBaseGridChart = (config, renderer) => {
+    if (!config || typeof config !== 'object') {
+        throw new Error('lite-charts: createHeatmap requires a config object');
+    }
+
+    // -- Reactive data source --
+    let dataSource;
+    if (typeof config.data === 'function') {
+        dataSource = config.data;
+    } else if (Array.isArray(config.data)) {
+        const arr = config.data;
+        dataSource = () => arr;
+    } else {
+        throw new Error('lite-charts: createHeatmap requires `data` array or accessor function');
+    }
+
+    // -- Dimensions: explicit or auto-observed at mount --
+    const widthExplicit = config.width != null;
+    const heightExplicit = config.height != null;
+    const widthAutoSig = widthExplicit ? null : signal(600);
+    const heightAutoSig = heightExplicit ? null : signal(400);
+    const widthSig = widthExplicit ? asAccessor(config.width) : widthAutoSig;
+    const heightSig = heightExplicit ? asAccessor(config.height) : heightAutoSig;
+
+    // -- Margins --
+    const m = config.margin || _DEFAULT_GRID_MARGIN;
+    const marginTop    = m.top    != null ? m.top    : _DEFAULT_GRID_MARGIN.top;
+    const marginRight  = m.right  != null ? m.right  : _DEFAULT_GRID_MARGIN.right;
+    const marginBottom = m.bottom != null ? m.bottom : _DEFAULT_GRID_MARGIN.bottom;
+    const marginLeft   = m.left   != null ? m.left   : _DEFAULT_GRID_MARGIN.left;
+
+    // -- State + scales + opts --
+    const state = _makeGridState();
+    const opts = renderer.initOpts(config);
+    const xBand = makeBandScale();
+    const yBand = makeBandScale();
+    const plotBoundsBox = { x: 0, y: 0, w: 0, h: 0 };
+    const plotBoundsSignal = signal(0);
+
+    // -- Crosshair / hover state --
+    const hoverData = { visible: false, xi: -1, yi: -1, value: 0, mouseX: 0, mouseY: 0 };
+    const hoverVersion = signal(0);
+
+    // -- Mount-time resources --
+    let canvas = null;
+    let container = null;
+    let ownedCanvas = false;
+    let scene = null;
+    const disposers = [];
+    let mounted = false;
+
+    // -- Chart object (built before mount; some fields populated then) --
+    const chart = {
+        mount: null,         // assigned below
+        unmount: null,
+        redraw: () => { if (scene) scene.markDirty(); },
+        // Read-only state introspection for tests / debug. _internal NOT
+        // public API; do not depend on shape across minor versions.
+        _internal: { state, xBand, yBand, plotBoundsBox },
+        get xCategories() { return state.xCategories.slice(); },
+        get yCategories() { return state.yCategories.slice(); },
+        get vMin() { return state.vMin; },
+        get vMax() { return state.vMax; },
+        // moveCrosshair / hover info, useful from tests + custom interactivity.
+        moveHover(canvasX, canvasY) {
+            const hit = renderer.hitTest(canvasX, canvasY, xBand, yBand, state, plotBoundsBox);
+            if (!hit) {
+                if (!hoverData.visible) return;
+                hoverData.visible = false;
+                hoverData.xi = -1;
+                hoverData.yi = -1;
+                hoverVersion.update((v) => (v + 1) | 0);
+                return;
+            }
+            if (hoverData.visible
+                && hoverData.xi === hit.xi
+                && hoverData.yi === hit.yi
+                && hoverData.mouseX === canvasX
+                && hoverData.mouseY === canvasY) return;
+            hoverData.visible = true;
+            hoverData.xi = hit.xi;
+            hoverData.yi = hit.yi;
+            hoverData.value = hit.value;
+            hoverData.mouseX = canvasX;
+            hoverData.mouseY = canvasY;
+            hoverVersion.update((v) => (v + 1) | 0);
+        },
+        hideHover() {
+            if (!hoverData.visible) return;
+            hoverData.visible = false;
+            hoverData.xi = -1;
+            hoverData.yi = -1;
+            hoverVersion.update((v) => (v + 1) | 0);
+        },
+        hover: Object.assign(() => { hoverVersion(); return hoverData; }, {
+            peek: () => hoverData,
+        }),
+    };
+
+    const mount = (target) => {
+        if (mounted) throw new Error('lite-charts: chart already mounted');
+        if (!target) throw new Error('lite-charts: mount() requires an HTMLElement or HTMLCanvasElement');
+
+        if (target.tagName === 'CANVAS') {
+            canvas = target;
+            container = target.parentElement || target;
+            ownedCanvas = false;
+        } else if (typeof target.appendChild === 'function') {
+            if (typeof document === 'undefined') {
+                throw new Error('lite-charts: mount() needs a real document to create a canvas');
+            }
+            canvas = document.createElement('canvas');
+            target.appendChild(canvas);
+            container = target;
+            ownedCanvas = true;
+        } else if (typeof target.getContext === 'function') {
+            canvas = target;
+            container = null;
+            ownedCanvas = false;
+        } else {
+            throw new Error('lite-charts: mount() target must be an HTMLElement or HTMLCanvasElement');
+        }
+
+        // Auto-resize wire-up before the initial size effect runs.
+        if (widthAutoSig || heightAutoSig) {
+            _wireAutoSize(container, widthAutoSig, heightAutoSig, disposers);
+        }
+
+        // Resolve theme-affected colors (CSS-vars -> concrete strings).
+        opts.colorLow         = resolveColor(opts.colorLow, container);
+        opts.colorHigh        = resolveColor(opts.colorHigh, container);
+        opts.labelColor       = resolveColor(opts.labelColor, container);
+        opts.highlightStroke  = resolveColor(opts.highlightStroke, container);
+        opts.valueLabelColor  = resolveColor(opts.valueLabelColor, container);
+
+        const schedule = config.schedule || (typeof requestAnimationFrame === 'function' ? requestAnimationFrame : (cb) => cb());
+        scene = createScene(canvas, {
+            background: config.background != null ? config.background : null,
+            autoResize: false,
+            dpr: config.dpr != null ? config.dpr : (typeof devicePixelRatio !== 'undefined' ? devicePixelRatio : 1),
+            schedule,
+        });
+        const resolvedDpr = config.dpr != null ? config.dpr : (typeof devicePixelRatio !== 'undefined' ? devicePixelRatio : 1);
+
+        // Effect 1: dimensions -> backing buffer + plot bounds + band scales.
+        disposers.push(effect(() => {
+            const w = +widthSig() | 0 || 600;
+            const h = +heightSig() | 0 || 400;
+            const wBacking = Math.max(1, Math.round(w * resolvedDpr));
+            const hBacking = Math.max(1, Math.round(h * resolvedDpr));
+            if (canvas.width  !== wBacking) canvas.width  = wBacking;
+            if (canvas.height !== hBacking) canvas.height = hBacking;
+            if (typeof canvas.style !== 'undefined') {
+                canvas.style.width  = w + 'px';
+                canvas.style.height = h + 'px';
+            }
+            plotBoundsBox.x = marginLeft;
+            plotBoundsBox.y = marginTop;
+            plotBoundsBox.w = Math.max(0, w - marginLeft - marginRight);
+            plotBoundsBox.h = Math.max(0, h - marginTop - marginBottom);
+            // Band scales re-stamped after data extract knows nx/ny.
+            updateBandScale(xBand, state.nx, plotBoundsBox.x, plotBoundsBox.x + plotBoundsBox.w, opts.cellGap, opts.cellGap / 2);
+            updateBandScale(yBand, state.ny, plotBoundsBox.y, plotBoundsBox.y + plotBoundsBox.h, opts.cellGap, opts.cellGap / 2);
+            plotBoundsSignal.update((v) => (v + 1) | 0);
+            if (scene) scene.markDirty();
+        }));
+
+        // Effect 2: data -> extract + color compute + band-scale category count.
+        disposers.push(effect(() => {
+            const data = dataSource();
+            renderer.extractData(state, data, opts);
+            renderer.computeColors(state, opts);
+            updateBandScale(xBand, state.nx, plotBoundsBox.x, plotBoundsBox.x + plotBoundsBox.w, opts.cellGap, opts.cellGap / 2);
+            updateBandScale(yBand, state.ny, plotBoundsBox.y, plotBoundsBox.y + plotBoundsBox.h, opts.cellGap, opts.cellGap / 2);
+            if (scene) scene.markDirty();
+        }));
+
+        // Effect 3: hover -> redraw (cell highlight + tooltip).
+        disposers.push(effect(() => {
+            hoverVersion();
+            if (scene) scene.markDirty();
+        }));
+
+        // --- Scene nodes (drawn in this order) ---
+        const cellsDrawFn = renderer.makeDrawFn(state, xBand, yBand, opts);
+        scene.root.add(pathNode({ draw: (ctx) => cellsDrawFn(ctx) }));
+
+        // Axis labels (x below, y to the left). Inline -- no lite-axis dep
+        // since heatmap categories are arbitrary strings, not numeric ticks.
+        scene.root.add(pathNode({ draw: (ctx) => {
+            const nx = state.nx;
+            const ny = state.ny;
+            if (nx === 0 && ny === 0) return;
+            ctx.fillStyle = opts.labelColor;
+            ctx.font = opts.labelFont;
+
+            // X labels (bottom).
+            ctx.textAlign = 'center';
+            ctx.textBaseline = 'top';
+            const xLabelsY = plotBoundsBox.y + plotBoundsBox.h + 8;
+            for (let xi = 0; xi < nx; xi++) {
+                ctx.fillText(state.xCategories[xi], xBand.map(xi), xLabelsY);
+            }
+
+            // Y labels (left).
+            ctx.textAlign = 'right';
+            ctx.textBaseline = 'middle';
+            const yLabelsX = plotBoundsBox.x - 8;
+            for (let yi = 0; yi < ny; yi++) {
+                ctx.fillText(state.yCategories[yi], yLabelsX, yBand.map(yi));
+            }
+        }}));
+
+        // Hover highlight + tooltip.
+        scene.root.add(pathNode({ draw: (ctx) => {
+            if (!hoverData.visible) return;
+            const { xi, yi, value, mouseX, mouseY } = hoverData;
+
+            // Stroke the hovered cell.
+            ctx.strokeStyle = opts.highlightStroke;
+            ctx.lineWidth = opts.highlightStrokeWidth;
+            ctx.strokeRect(
+                xBand.leftEdge(xi),
+                yBand.leftEdge(yi),
+                xBand.bandWidth,
+                yBand.bandWidth,
+            );
+
+            // Tooltip: simple label "xLabel x yLabel: value" near the cursor.
+            const fmt = opts.tooltipFormat;
+            const text = fmt
+                ? fmt({ xi, yi, value, xLabel: state.xCategories[xi], yLabel: state.yCategories[yi] })
+                : (state.xCategories[xi] + ' \u00d7 ' + state.yCategories[yi] + ': ' + (Math.round(value * 100) / 100));
+            ctx.font = opts.labelFont;
+            const metrics = ctx.measureText(text);
+            const tw = (metrics && metrics.width) || (text.length * 7);
+            const th = 18;
+            const pad = 6;
+            // Anchor above-right of the cursor; clamp inside plot rect.
+            let tx = mouseX + 12;
+            let ty = mouseY - th - 6;
+            if (tx + tw + pad * 2 > plotBoundsBox.x + plotBoundsBox.w) {
+                tx = mouseX - tw - pad * 2 - 12;
+            }
+            if (ty < plotBoundsBox.y) ty = mouseY + 12;
+            ctx.fillStyle = 'rgba(20, 20, 20, 0.92)';
+            ctx.fillRect(tx, ty, tw + pad * 2, th);
+            ctx.fillStyle = '#ffffff';
+            ctx.textAlign = 'left';
+            ctx.textBaseline = 'middle';
+            ctx.fillText(text, tx + pad, ty + th / 2);
+        }}));
+
+        // Mouse listeners (if mounted to a real canvas).
+        if (canvas && typeof canvas.addEventListener === 'function') {
+            const onMove = (ev) => {
+                const rect = canvas.getBoundingClientRect ? canvas.getBoundingClientRect() : { left: 0, top: 0 };
+                const cx = ev.clientX - rect.left;
+                const cy = ev.clientY - rect.top;
+                chart.moveHover(cx, cy);
+            };
+            const onLeave = () => chart.hideHover();
+            canvas.addEventListener('mousemove', onMove);
+            canvas.addEventListener('mouseleave', onLeave);
+            disposers.push(() => canvas.removeEventListener('mousemove', onMove));
+            disposers.push(() => canvas.removeEventListener('mouseleave', onLeave));
+        }
+
+        mounted = true;
+        return chart;
+    };
+
+    const unmount = () => {
+        if (!mounted) return;
+        for (let i = 0; i < disposers.length; i++) {
+            try { disposers[i](); } catch (_) { /* swallow */ }
+        }
+        disposers.length = 0;
+        if (scene) {
+            try { scene.dispose(); } catch (_) { /* swallow */ }
+            scene = null;
+        }
+        if (ownedCanvas && container && canvas && canvas.parentNode === container) {
+            container.removeChild(canvas);
+        }
+        canvas = null;
+        container = null;
+        ownedCanvas = false;
+        mounted = false;
+    };
+
+    chart.mount = mount;
+    chart.unmount = unmount;
+    return chart;
+};
+
+// v1.2.0-alpha.3: heatmap rides the grid kernel. Currently the only consumer;
+// future grid charts (correlation matrix, calendar heatmap, dot matrix) would
+// fit the same kernel by supplying a different RENDERER.
+
+/**
+ * Create a 2D heatmap. Categorical rows × columns; each cell colored by a
+ * numeric value via a default linear ramp (`colorLow` -> `colorHigh`) or
+ * a custom `colorFn(v, vMin, vMax)`. Sparse grids draw only present cells.
+ *
+ * Rides a third kernel (`createBaseGridChart`) -- importing only
+ * `createHeatmap` tree-shakes the axis-chart and polar-chart code paths.
+ *
+ * @param {import("./Charts.d.ts").HeatmapConfig} config
+ * @returns {import("./Charts.d.ts").Chart}
+ * @throws {Error} If `config` is missing or `data` is not an array / accessor.
+ *
+ * @example
+ *   const chart = createHeatmap({
+ *       canvas,
+ *       data: [
+ *           { row: "Mon", col: "9am", value: 12 },
+ *           { row: "Mon", col: "10am", value: 8 },
+ *           // ...
+ *       ],
+ *       width: 600, height: 400
+ *   });
+ */
+export const createHeatmap = (config) => createBaseGridChart(config, HEATMAP_RENDERER);