wick-charts 0.3.0 → 0.4.0

package/README.md

@@ -21,6 +21,7 @@ npm install wick-charts
   - [Reading chart state](#reading-chart-state)
   - [Loading more history on demand](#loading-more-history-on-demand)
   - [Extending: plugins](#extending-plugins)
+  - [Multi-pane indicators](#multi-pane-indicators)
   - [Cleanup](#cleanup)
 - [Architecture](#architecture)
 - [Development](#development)
@@ -354,6 +355,58 @@ or validated for uniqueness, just compared with `===` when you call `setPluginVi
 plugin with no `id` still works exactly as before; it just can't be targeted that way, only by
 holding onto its reference and calling `removePlugin` directly.
 
+### Multi-pane indicators
+
+An oscillator like RSI or MACD has a value domain that has nothing to do with price (RSI's
+fixed `[0, 100]`, say) — drawing it as a `ChartPlugin` overlay in the price pane would either
+get swamped by the candles or need a hand-rolled rescale hack. `addPane` reserves a horizontal
+strip below the main price pane with its own independent value axis, and a plugin's `paneId`
+routes its `draw()` there instead of the price pane:
+
+```ts
+chart.addPane({
+  id: 'rsi',
+  heightRatio: 0.25, // share of the total plotting height this pane occupies; defaults to 0.25
+  getValueRange: () => ({ min: 0, max: 100 }), // this pane's own value-axis domain, called every frame
+});
+
+chart.addPlugin({
+  paneId: 'rsi', // routes this plugin into the 'rsi' pane instead of the price pane
+  draw({ ctx, allPoints, visibleStartIndex, visibleEndIndex, xForIndex, yForValue }) {
+    const rsi = computeRsi(allPoints.map((c) => c.close), 14); // your own indicator math — see below
+    ctx.strokeStyle = '#bb86fc';
+    ctx.beginPath();
+    for (let i = visibleStartIndex; i < visibleEndIndex; i++) {
+      const x = xForIndex(i);
+      const y = yForValue(rsi[i]); // mapped against *this pane's* [0, 100], not price
+      i === visibleStartIndex ? ctx.moveTo(x, y) : ctx.lineTo(x, y);
+    }
+    ctx.stroke();
+  },
+});
+```
+
+The pane itself draws nothing but a separator line and its own right-side axis (ticks resolved
+from `getValueRange()`, styled through the same `axis` options as the price axis) — exactly the
+same "core provides layout, the app provides the math" split plugins already use for indicator
+*overlays*, just for indicators that need their own scale instead of sharing the price one. See
+`demo/index.html` for a complete worked example (an RSI pane built entirely in the demo's own
+code, same as the moving-average overlay above it — see "Indicators" below for why neither
+ships in the library itself).
+
+Every declared pane stacks below the previous one in call order, each shrinking the main
+pane's share of the plotting height; `removePane(id)` gives that space back. A plugin whose
+`paneId` doesn't match any currently-added pane falls back to drawing in the price pane rather
+than silently disappearing — useful if you remove a pane before removing the plugins that
+targeted it. `getPanes()` returns every declared pane's `id`/`heightRatio`, the same
+snapshot-for-building-a-management-UI idea `getPlugins()` already offers for plugins.
+
+The hover crosshair's dashed vertical line spans every pane so a hovered candle lines up
+across the whole stack; the horizontal line, price-label chip, and OHLC legend stay scoped to
+the price pane — an indicator pane's own hover readout, if you want one, is something its own
+plugin draws (it has the same `xForIndex`/`yForValue` a price-pane plugin does, just mapped
+against that pane's own value domain and pixel rect).
+
 ### Cleanup
 
 Call `chart.destroy()` when you're done with a chart (component unmount, etc.) — it removes a
@@ -469,6 +522,18 @@ two things `draw()` alone can't give it, both added specifically to make that bu
   `ChartRenderer.render` uses, recomputed on demand since pointer events happen between
   frames, not during one.
 
+`ChartPlugin.paneId` is a third, narrower option on top of the two above — it doesn't change
+what a plugin implements, only which pane's `PluginRenderApi` it receives. `ChartRenderer`
+builds one `PluginRenderApi` per pane per frame (`buildPluginApi`, sharing a `FrameGeometry` for
+the parts every pane has in common — the time axis and the frame-ended guard) and routes each
+plugin to the one matching its `paneId`, defaulting to the main pane. A pane-targeted plugin's
+`yForValue`/`valueForY` are pane-local (mapped against that pane's own `getValueRange()`) but
+still return/accept absolute canvas pixels, exactly like the main pane's — so a plugin never
+needs to know whether it's drawing in the price pane or a declared one, only which `paneId` it
+was given. Pointer gestures (`onPointerDown`/etc.) aren't pane-aware yet: they're still offered
+chart-wide the same way regardless of any plugin's `paneId`, matching the mechanism's original
+scope (drawing tools on the price series) rather than a limitation specific to panes.
+
 ### Indicators (moving averages, Bollinger Bands, ...): deliberately not included
 
 wick-charts ships the extension point (`ChartPlugin`, `allPoints`, `xForIndex`/`yForValue`)
@@ -537,8 +602,11 @@ it. Candlestick is the only registered series type so far; the plugin extension
 overlays plus, now, claimable pointer gestures for interactive tools — see "Plugins" above)
 has no built-in users (see "Indicators" above for why) beyond `demo/index.html`'s example. No
 concrete drawing tool ships yet, only the mechanism a trend line or similar would be built
-on. No multi-pane support yet (volume shares the candlestick pane rather than getting its
-own). See [CHANGELOG.md](./CHANGELOG.md) for what shipped in each release.
+on. `addPane`/`removePane` let a plugin-drawn indicator (RSI, MACD, ...) reserve its own
+horizontal strip with an independent value axis — see "Multi-pane indicators" above; volume
+still shares the candlestick pane rather than getting its own, since it draws through the
+series itself, not a pane-targeted plugin. See [CHANGELOG.md](./CHANGELOG.md) for what shipped
+in each release.
 
 ## License
 

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import type { DataLoader } from './dataSource.js';
 import type { ChartPlugin } from './plugins/types.js';
 import type { CandlestickStyle } from './series/candlestick.js';
-import type { Candle, WickChartOptions, SeriesPoint, ValueRange } from './types.js';
-export type { BusinessDay, Candle, WickChartOptions, WickTime, SeriesPoint, UnixMillis, ValueRange } from './types.js';
+import type { Candle, PaneOptions, WickChartOptions, SeriesPoint, ValueRange } from './types.js';
+export type { BusinessDay, Candle, PaneOptions, WickChartOptions, WickTime, SeriesPoint, UnixMillis, ValueRange, } from './types.js';
 export type { DataLoader, DataRequest } from './dataSource.js';
 export type { ChartPlugin, ChartPointerEvent, PluginRenderApi } from './plugins/types.js';
 export { distanceToSegment, hitTestPoint, hitTestSegment } from './hitTest.js';
@@ -41,6 +41,11 @@ export declare class WickChart<TPoint extends SeriesPoint = Candle> {
      * motionless while the pointer moves within that candle's column). */
     private hoverY;
     private plugins;
+    /** Indicator/oscillator panes declared via `addPane`, defaults already
+     * resolved — see `ResolvedPaneOptions`. Empty until an app adds one; a
+     * chart that never calls `addPane` renders exactly as it did before
+     * panes existed (single price pane filling the whole plotting height). */
+    private panes;
     /** The plugin whose `onPointerDown` returned `true` for the pointer
      * currently down, or `null` when no plugin has claimed the current
      * gesture (the common case — the chart handles it itself). */
@@ -95,6 +100,35 @@ export declare class WickChart<TPoint extends SeriesPoint = Candle> {
      * and re-renders. A no-op, not an error, if nothing matches — plugins
      * with no `id` set are never matched. */
     setPluginVisible(id: string, visible: boolean): this;
+    /**
+     * Reserves a horizontal strip below the main price pane (and below any
+     * previously-added pane — panes stack in call order) for an indicator or
+     * oscillator, drawn entirely by `ChartPlugin`s registered with a
+     * matching `paneId` (see `ChartPlugin.paneId`). The pane itself computes
+     * nothing: `options.getValueRange` supplies whatever value-axis domain
+     * makes sense for what will be plotted into it (a fixed `[0, 100]` for
+     * RSI, an auto-fit range closed over a MACD series a plugin already
+     * tracks, ...) — the same "core provides layout, the app provides the
+     * math" split `addPlugin` already uses for indicator overlays on the
+     * main pane. A no-op on layout until at least one plugin actually
+     * targets this pane's `id`; an empty pane still reserves its space and
+     * draws its own axis, just with nothing inside it.
+     */
+    addPane(options: PaneOptions): this;
+    /** Removes a previously-added pane by `id` and re-renders. A no-op, not
+     * an error, if nothing matches. Plugins still targeting the removed
+     * pane's `id` via `ChartPlugin.paneId` fall back to drawing in the main
+     * pane rather than being silently dropped — see the doc comment on
+     * `ChartPlugin.paneId`. */
+    removePane(id: string): this;
+    /** Every currently-declared pane's `id` and resolved `heightRatio`, in
+     * stacking order (top to bottom, main pane excluded since it always
+     * exists and always sits first) — for an app building a management UI
+     * around indicator panes without maintaining its own parallel list. */
+    getPanes(): readonly {
+        id: string;
+        heightRatio: number;
+    }[];
     render(): void;
     /** Coalesces render() calls into at most one per animation frame. Mouse
      * events (drag, wheel) can fire far faster than the display refreshes —
@@ -163,6 +197,17 @@ export declare class WickChart<TPoint extends SeriesPoint = Candle> {
      * on-demand (`valueForY`, dispatched pointer events) rather than only
      * during `render()`. `null` when there's nothing to compute one from. */
     private frameValueRange;
+    /** The main price pane's own pixel height for the *next* render — as
+     * opposed to `this.renderer.chartHeight`, which is the whole pane
+     * stack's height (main pane plus every declared indicator pane below
+     * it). Every pixel<->value conversion outside of `ChartRenderer.render`
+     * itself (price-axis drag-to-scale, `ChartPointerEvent.value`, ...) is
+     * about the main pane specifically — pointer gestures and price-axis
+     * dragging aren't pane-aware yet, so they only ever mean the main price
+     * pane — and has to divide by this, not the full stack, or dragging
+     * would run at the wrong speed (or a hovered value would come out
+     * wrong) as soon as an app adds its first indicator pane. */
+    private mainPaneHeight;
     /** y pixel -> value in the range the next render would use. `null` if
      * there's no data or no usable chart area to compute one against — see
      * `ChartPointerEvent.value`. */

package/dist/index.js

@@ -1,4 +1,5 @@
 import { mergeSeriesPoints } from './mergeSeries.js';
+import { computePaneLayout } from './paneLayout.js';
 import { ChartRenderer } from './renderer.js';
 import { getSeries } from './series/registry.js';
 import { toUnixSeconds } from './time.js';
@@ -26,6 +27,14 @@ const DEFAULT_VISIBLE_POINTS = 120;
 /** How close (in points) the visible window has to get to either edge of
  * the loaded data before `setDataLoader`'s loader is asked for more. */
 const DEFAULT_LOAD_THRESHOLD = 20;
+/** `PaneOptions.heightRatio`'s default — see `addPane`. */
+const DEFAULT_PANE_HEIGHT_RATIO = 0.25;
+/** `PaneOptions.getValueRange`'s default — see `addPane`. Fixed at
+ * `[0, 1]` rather than auto-fitting to anything, since the pane has no
+ * data of its own to fit to: only a plugin drawing into it knows what
+ * range makes sense, which is exactly why `getValueRange` exists to be
+ * overridden. */
+const DEFAULT_PANE_VALUE_RANGE = { min: 0, max: 1 };
 /** How long a single finger has to stay down before a still-in-progress
  * 'pan' touch switches to 'scrub' mode (touch has no hover, so this is its
  * substitute — hold to inspect a point instead of panning past it). */
@@ -57,6 +66,11 @@ export class WickChart {
          * motionless while the pointer moves within that candle's column). */
         this.hoverY = null;
         this.plugins = [];
+        /** Indicator/oscillator panes declared via `addPane`, defaults already
+         * resolved — see `ResolvedPaneOptions`. Empty until an app adds one; a
+         * chart that never calls `addPane` renders exactly as it did before
+         * panes existed (single price pane filling the whole plotting height). */
+        this.panes = [];
         /** The plugin whose `onPointerDown` returned `true` for the pointer
          * currently down, or `null` when no plugin has claimed the current
          * gesture (the common case — the chart handles it itself). */
@@ -353,6 +367,46 @@ export class WickChart {
         this.scheduleRender();
         return this;
     }
+    /**
+     * Reserves a horizontal strip below the main price pane (and below any
+     * previously-added pane — panes stack in call order) for an indicator or
+     * oscillator, drawn entirely by `ChartPlugin`s registered with a
+     * matching `paneId` (see `ChartPlugin.paneId`). The pane itself computes
+     * nothing: `options.getValueRange` supplies whatever value-axis domain
+     * makes sense for what will be plotted into it (a fixed `[0, 100]` for
+     * RSI, an auto-fit range closed over a MACD series a plugin already
+     * tracks, ...) — the same "core provides layout, the app provides the
+     * math" split `addPlugin` already uses for indicator overlays on the
+     * main pane. A no-op on layout until at least one plugin actually
+     * targets this pane's `id`; an empty pane still reserves its space and
+     * draws its own axis, just with nothing inside it.
+     */
+    addPane(options) {
+        this.panes.push({
+            id: options.id,
+            heightRatio: options.heightRatio ?? DEFAULT_PANE_HEIGHT_RATIO,
+            getValueRange: options.getValueRange ?? (() => DEFAULT_PANE_VALUE_RANGE),
+        });
+        this.scheduleRender();
+        return this;
+    }
+    /** Removes a previously-added pane by `id` and re-renders. A no-op, not
+     * an error, if nothing matches. Plugins still targeting the removed
+     * pane's `id` via `ChartPlugin.paneId` fall back to drawing in the main
+     * pane rather than being silently dropped — see the doc comment on
+     * `ChartPlugin.paneId`. */
+    removePane(id) {
+        this.panes = this.panes.filter((pane) => pane.id !== id);
+        this.scheduleRender();
+        return this;
+    }
+    /** Every currently-declared pane's `id` and resolved `heightRatio`, in
+     * stacking order (top to bottom, main pane excluded since it always
+     * exists and always sits first) — for an app building a management UI
+     * around indicator panes without maintaining its own parallel list. */
+    getPanes() {
+        return this.panes.map(({ id, heightRatio }) => ({ id, heightRatio }));
+    }
     render() {
         this.renderer.render({
             sorted: this.sorted,
@@ -361,6 +415,7 @@ export class WickChart {
             hoverIndex: this.hoverIndex,
             hoverY: this.hoverY,
             plugins: this.plugins,
+            panes: this.panes,
         });
         this.maybeLoadMore();
     }
@@ -463,7 +518,7 @@ export class WickChart {
             // have opposite sign.
             this.viewport.pan(-deltaXDevice / slotWidth, this.sorted.length);
         }
-        const chartHeight = this.renderer.chartHeight;
+        const chartHeight = this.mainPaneHeight();
         if (chartHeight > 0 && this.viewport.valueRangeOverride) {
             const deltaYDevice = deltaYCss * this.devicePixelScaleY();
             const { min, max } = this.viewport.valueRangeOverride;
@@ -597,12 +652,25 @@ export class WickChart {
             return null;
         return this.seriesDefinition.getValueRange(visible, this.viewport.valueScaleFactor);
     }
+    /** The main price pane's own pixel height for the *next* render — as
+     * opposed to `this.renderer.chartHeight`, which is the whole pane
+     * stack's height (main pane plus every declared indicator pane below
+     * it). Every pixel<->value conversion outside of `ChartRenderer.render`
+     * itself (price-axis drag-to-scale, `ChartPointerEvent.value`, ...) is
+     * about the main pane specifically — pointer gestures and price-axis
+     * dragging aren't pane-aware yet, so they only ever mean the main price
+     * pane — and has to divide by this, not the full stack, or dragging
+     * would run at the wrong speed (or a hovered value would come out
+     * wrong) as soon as an app adds its first indicator pane. */
+    mainPaneHeight() {
+        return computePaneLayout(this.panes, this.renderer.chartHeight).main.height;
+    }
     /** y pixel -> value in the range the next render would use. `null` if
      * there's no data or no usable chart area to compute one against — see
      * `ChartPointerEvent.value`. */
     valueForY(y) {
         const range = this.frameValueRange();
-        const chartHeight = this.renderer.chartHeight;
+        const chartHeight = this.mainPaneHeight();
         if (!range || chartHeight <= 0)
             return null;
         return range.min + (1 - y / chartHeight) * (range.max - range.min);
@@ -630,7 +698,7 @@ export class WickChart {
      * `valueForY` returns `null` for. */
     yForValue(value) {
         const range = this.frameValueRange();
-        const chartHeight = this.renderer.chartHeight;
+        const chartHeight = this.mainPaneHeight();
         if (!range || chartHeight <= 0)
             return null;
         return chartHeight * (1 - (value - range.min) / (range.max - range.min));

package/dist/paneLayout.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Pure layout math for stacking a chart's panes vertically — no canvas, no
+ * DOM, fully unit-testable in isolation from `ChartRenderer`. The main
+ * (price) pane is never passed in here: it's whatever height remains after
+ * every declared pane's `heightRatio` share of the total plotting height
+ * (canvas height minus the time-axis strip) is subtracted, which is why it
+ * always exists even with zero declared panes.
+ */
+/** One caller-declared pane's layout inputs — a subset of `PaneOptions`
+ * (see `src/types.ts`), kept separate so this module doesn't need to know
+ * about `getValueRange`/`valueRange` at all. */
+export interface PaneLayoutInput {
+    id: string;
+    /** Fraction of the total plotting height this pane occupies, before
+     * clamping. Clamped into `[MIN_PANE_HEIGHT_RATIO, MAX_TOTAL_PANE_RATIO]`
+     * as a share of the whole stack — see `computePaneLayout`. */
+    heightRatio: number;
+}
+/** One pane's resolved pixel rect within the plotting area (i.e. relative
+ * to the top of the chart, above the time-axis strip — the same origin
+ * `ChartRenderer.chartHeight` already uses). */
+export interface PaneRect {
+    id: string;
+    top: number;
+    height: number;
+}
+/**
+ * Resolves every declared pane's pixel rect plus the main pane's, stacked
+ * top (price pane) to bottom (declared panes, in call order) inside
+ * `totalHeight` px. Declared ratios are scaled down proportionally (not
+ * clamped one by one, which would silently change the relative sizing
+ * between panes) whenever their sum would leave the main pane below
+ * `MIN_PANE_HEIGHT_RATIO` of the stack.
+ */
+export declare function computePaneLayout(panes: PaneLayoutInput[], totalHeight: number): {
+    main: PaneRect;
+    panes: PaneRect[];
+};

package/dist/paneLayout.js

@@ -0,0 +1,49 @@
+/**
+ * Pure layout math for stacking a chart's panes vertically — no canvas, no
+ * DOM, fully unit-testable in isolation from `ChartRenderer`. The main
+ * (price) pane is never passed in here: it's whatever height remains after
+ * every declared pane's `heightRatio` share of the total plotting height
+ * (canvas height minus the time-axis strip) is subtracted, which is why it
+ * always exists even with zero declared panes.
+ */
+/** Floor on any single pane's share of the stack, main pane included — a
+ * pane asked to render at near-zero height is worse than one slightly
+ * taller than requested; nothing usable can be drawn (axis ticks, a
+ * legible plot) below this. */
+const MIN_PANE_HEIGHT_RATIO = 0.05;
+/** Ceiling on how much of the total plotting height every declared pane
+ * *combined* may claim, leaving at least this much for the main pane even
+ * if the sum of requested ratios would otherwise consume it entirely. */
+const MAX_TOTAL_PANE_RATIO = 0.8;
+/**
+ * Resolves every declared pane's pixel rect plus the main pane's, stacked
+ * top (price pane) to bottom (declared panes, in call order) inside
+ * `totalHeight` px. Declared ratios are scaled down proportionally (not
+ * clamped one by one, which would silently change the relative sizing
+ * between panes) whenever their sum would leave the main pane below
+ * `MIN_PANE_HEIGHT_RATIO` of the stack.
+ */
+export function computePaneLayout(panes, totalHeight) {
+    const height = Math.max(0, totalHeight);
+    if (panes.length === 0) {
+        return { main: { id: 'main', top: 0, height }, panes: [] };
+    }
+    const rawRatios = panes.map((p) => Math.max(MIN_PANE_HEIGHT_RATIO, p.heightRatio));
+    const rawTotal = rawRatios.reduce((sum, r) => sum + r, 0);
+    // Scale every declared pane down by the same factor if together they'd
+    // eat more than MAX_TOTAL_PANE_RATIO of the stack — proportional, so a
+    // pane asking for twice another's height still ends up twice as tall.
+    const scale = rawTotal > MAX_TOTAL_PANE_RATIO ? MAX_TOTAL_PANE_RATIO / rawTotal : 1;
+    const ratios = rawRatios.map((r) => r * scale);
+    let top = 0;
+    const mainHeight = height * (1 - ratios.reduce((sum, r) => sum + r, 0));
+    const main = { id: 'main', top, height: mainHeight };
+    top += mainHeight;
+    const rects = panes.map((pane, i) => {
+        const paneHeight = height * ratios[i];
+        const rect = { id: pane.id, top, height: paneHeight };
+        top += paneHeight;
+        return rect;
+    });
+    return { main, panes: rects };
+}

package/dist/plugins/types.d.ts

@@ -117,6 +117,17 @@ export interface ChartPlugin<TPoint extends SeriesPoint = SeriesPoint> {
      * directly and call `chart.render()`.
      */
     visible?: boolean;
+    /**
+     * Routes this plugin's `draw()` into a specific pane instead of the main
+     * price pane — the id must match one passed to `WickChart.addPane` (see
+     * `PaneOptions.id` in `src/types.ts`). Omitted, or set to `'main'`,
+     * keeps today's behavior: the plugin draws in the main price pane. A
+     * `paneId` that doesn't match any currently-added pane is treated the
+     * same as `'main'` (a plugin never silently stops drawing just because
+     * its pane was removed before it was) — call `removePlugin` yourself if
+     * that's not what you want when a pane goes away.
+     */
+    paneId?: string;
     draw(api: PluginRenderApi<TPoint>): void;
     /**
      * Called on pointer down inside the chart's plotting area (not the

package/dist/renderer.d.ts

@@ -1,6 +1,6 @@
 import type { ChartPlugin } from './plugins/types.js';
 import type { SeriesDefinition } from './series/types.js';
-import type { WickChartOptions, SeriesPoint } from './types.js';
+import type { ResolvedPaneOptions, WickChartOptions, SeriesPoint } from './types.js';
 import type { Viewport } from './viewport.js';
 export interface RenderInput<TPoint extends SeriesPoint> {
     /** Every point, sorted ascending by normalized time. */
@@ -16,6 +16,11 @@ export interface RenderInput<TPoint extends SeriesPoint> {
      * position rather than any property of the hovered point itself. */
     hoverY: number | null;
     plugins: ChartPlugin<TPoint>[];
+    /** Indicator/oscillator panes declared via `WickChart.addPane`, resolved
+     * (defaults applied) — see `ResolvedPaneOptions`. Empty by default, in
+     * which case the main pane alone fills the whole plotting height exactly
+     * as it did before panes existed. */
+    panes: ResolvedPaneOptions[];
 }
 /**
  * The chart engine's renderer: canvas lifecycle, axes, crosshair, and
@@ -53,11 +58,32 @@ export declare class ChartRenderer<TPoint extends SeriesPoint> {
     private axisFont;
     private legendFont;
     render(input: RenderInput<TPoint>): void;
+    /**
+     * Builds the `PluginRenderApi` for one pane — the main price pane or a
+     * declared indicator pane, identical shape either way — from that pane's
+     * own rect/value-domain/scale plus whatever `geometry` every pane shares
+     * for this frame (shared because there is only one time axis, and one
+     * frame-ended flag, for the whole stack; see `FrameGeometry`).
+     */
+    private buildPluginApi;
     /** The decimal precision `formatPrice` should use for the current price
      * range — shared by the axis ticks and the crosshair's price label so
      * both display the same value with the same rounding. */
     private currentPriceStep;
+    /**
+     * Draws one pane's right-side value axis: boundary line, horizontal grid
+     * lines, and tick labels. Used for both the main price pane and every
+     * indicator pane — `topOffset` shifts everything down by that pane's own
+     * position in the stack (0 for the main pane, which sits at the top), so
+     * `yScale` only ever has to know about its own pane-local [0, chartHeight]
+     * range and never about where that pane lives in the full canvas.
+     */
     private renderPriceAxis;
+    /** The horizontal rule separating an indicator pane from whatever sits
+     * above it (the main pane, or the previous indicator pane) — the same
+     * `axis.lineColor` boundary style `renderTimeAxis` already draws between
+     * the plotting area and the time-axis strip. */
+    private renderPaneSeparator;
     private renderTimeAxis;
     private renderCrosshairAndLegend;
     /** The OHLC(+volume) tooltip — floats near the hovered pixel like a

package/dist/renderer.js

@@ -1,5 +1,6 @@
 import { formatAxisLabel, formatHoverTime, pickTickIndices } from './axis.js';
 import { createScale } from './hybridScale.js';
+import { computePaneLayout } from './paneLayout.js';
 import { formatPrice, niceTicks } from './priceAxis.js';
 const DEFAULT_BACKGROUND = 'transparent';
 const DEFAULT_FONT = {
@@ -81,18 +82,25 @@ export class ChartRenderer {
     }
     render(input) {
         const { ctx, canvas, background, seriesDefinition, style } = this;
-        const { sorted, times, viewport, hoverIndex, hoverY, plugins } = input;
+        const { sorted, times, viewport, hoverIndex, hoverY, plugins, panes } = input;
         const width = canvas.width;
         const height = canvas.height;
         const chartWidth = this.chartWidth;
-        const chartHeight = this.chartHeight;
+        // Full stack height: the main price pane plus every declared indicator
+        // pane below it. `this.chartHeight` predates panes and named what's
+        // now only true with zero of them — kept as the property name (public
+        // API reads it through) but renamed locally here since most of this
+        // method cares about one pane's height, not the stack's.
+        const stackHeight = this.chartHeight;
         ctx.clearRect(0, 0, width, height);
         if (background !== 'transparent') {
             ctx.fillStyle = background;
             ctx.fillRect(0, 0, width, height);
         }
-        if (sorted.length === 0 || chartWidth <= 0 || chartHeight <= 0)
+        if (sorted.length === 0 || chartWidth <= 0 || stackHeight <= 0)
             return;
+        const { main: mainRect, panes: paneRects } = computePaneLayout(panes, stackHeight);
+        const chartHeight = mainRect.height;
         const startIdx = Math.max(0, Math.floor(viewport.startIndex));
         const endIdx = Math.min(sorted.length, Math.ceil(viewport.endIndex));
         const visible = sorted.slice(startIdx, endIdx);
@@ -105,51 +113,78 @@ export class ChartRenderer {
         // Whichever it picks, `dispose()` must run once we're done reading
         // from it (a no-op on the JS path, a real WASM memory free otherwise).
         const { scale: yScale, dispose: disposeYScale } = createScale(valueMin, valueMax, chartHeight, 0, visible.length);
-        // Flipped in `finally`, right before `disposeYScale()` frees the WASM
-        // scale's backing memory (a no-op on the JS path). Guards `yForValue`
-        // below so a plugin that stashes it and calls it later gets a clear
-        // thrown error instead of touching freed WASM memory — see the
-        // interface-level warning on `PluginRenderApi`.
-        let frameEnded = false;
+        // Every indicator pane gets the exact same treatment as the main pane
+        // — its own value domain (from `PaneOptions.getValueRange`) and its
+        // own JS/WASM scale over its own pixel height — kept alive for the
+        // whole frame alongside `yScale`, since plugins targeting a pane draw
+        // only after every pane's axis has already been rendered.
+        const paneScales = paneRects.map((rect, i) => {
+            const pane = panes[i];
+            const { min, max } = pane.getValueRange();
+            const { scale, dispose } = createScale(min, max, rect.height, 0, visible.length);
+            return { pane, rect, min, max, scale, dispose };
+        });
+        // Flipped in `finally`, right before every scale above frees its WASM
+        // backing memory (a no-op on the JS path). Guards `yForValue` below so
+        // a plugin that stashes it and calls it later gets a clear thrown
+        // error instead of touching freed memory — see the interface-level
+        // warning on `PluginRenderApi`. An object (not a plain `let`) so every
+        // pane's plugin-api closure, built by `buildPluginApi` below, shares
+        // the same flag instead of each capturing its own.
+        const frameState = { ended: false };
         try {
             const slotWidth = chartWidth / viewport.visibleCount;
             // x position for a *global* sorted-array index — honors the (possibly
             // fractional) viewport.startIndex so panning is pixel-smooth, not
-            // stepped a whole point at a time.
+            // stepped a whole point at a time. Shared by every pane: there is
+            // only one time axis for the whole stack.
             const xForIndex = (globalIndex) => (globalIndex - viewport.startIndex) * slotWidth + slotWidth / 2;
+            // Exact inverse of xForIndex above — solving
+            // `x = (index - viewport.startIndex) * slotWidth + slotWidth / 2` for `index`.
+            const indexForX = (x) => viewport.startIndex + (x - slotWidth / 2) / slotWidth;
             seriesDefinition.draw({ ctx, visible, startIndex: startIdx, xForIndex, slotWidth, yScale, chartHeight }, style);
             const priceStep = this.currentPriceStep(valueMin, valueMax);
-            this.renderPriceAxis(valueMin, valueMax, priceStep, yScale, chartWidth, chartHeight);
-            this.renderTimeAxis(times, startIdx, visible.length, chartHeight, chartWidth, xForIndex);
+            this.renderPriceAxis(valueMin, valueMax, priceStep, yScale, chartWidth, chartHeight, mainRect.top);
+            for (const { rect, min, max, scale } of paneScales) {
+                this.renderPaneSeparator(rect.top, chartWidth);
+                const step = this.currentPriceStep(min, max);
+                this.renderPriceAxis(min, max, step, scale, chartWidth, rect.height, rect.top);
+            }
+            this.renderTimeAxis(times, startIdx, visible.length, stackHeight, chartWidth, xForIndex);
             if (hoverIndex !== null && hoverIndex >= startIdx && hoverIndex < endIdx) {
-                this.renderCrosshairAndLegend(sorted[hoverIndex], xForIndex(hoverIndex), times[hoverIndex], hoverY, valueMin, valueMax, priceStep, chartWidth, chartHeight);
+                // The dashed vertical line spans the whole stack (every pane); the
+                // horizontal line, price-label chip, and OHLC legend stay scoped
+                // to the main pane only — an indicator pane's own hover readout,
+                // if it wants one, is the job of whatever plugin draws into it.
+                this.renderCrosshairAndLegend(sorted[hoverIndex], xForIndex(hoverIndex), times[hoverIndex], hoverY, valueMin, valueMax, priceStep, chartWidth, chartHeight, stackHeight);
             }
             if (plugins.length > 0) {
-                const api = {
-                    ctx,
+                // Everything every pane's PluginRenderApi shares — only the pane's
+                // own rect/value-domain/scale differ between `buildPluginApi`
+                // calls, so bundling the rest here keeps that call to a handful of
+                // pane-specific arguments instead of ten positional ones repeated
+                // per pane.
+                const frameGeometry = {
                     chartWidth,
-                    chartHeight,
                     xForIndex,
-                    yForValue: (value) => {
-                        if (frameEnded) {
-                            throw new Error('wick-charts: PluginRenderApi.yForValue called after its frame ended — ' +
-                                'only call it synchronously inside ChartPlugin.draw()');
-                        }
-                        return yScale.map(value);
-                    },
-                    // Exact inverse of xForIndex above — solving
-                    // `x = (index - viewport.startIndex) * slotWidth + slotWidth / 2` for `index`.
-                    indexForX: (x) => viewport.startIndex + (x - slotWidth / 2) / slotWidth,
-                    // Exact inverse of the value->y mapping createScale set up for this
-                    // frame (domain [valueMin, valueMax] -> range [chartHeight, 0]).
-                    valueForY: (y) => valueMin + (1 - y / chartHeight) * (valueMax - valueMin),
+                    indexForX,
                     visibleStartIndex: startIdx,
                     visibleEndIndex: endIdx,
                     allPoints: sorted,
+                    frameState,
                 };
+                const mainApi = this.buildPluginApi(mainRect, valueMin, valueMax, yScale, frameGeometry);
+                const paneApiById = new Map();
+                for (const { pane, rect, min, max, scale } of paneScales) {
+                    paneApiById.set(pane.id, this.buildPluginApi(rect, min, max, scale, frameGeometry));
+                }
                 for (const plugin of plugins) {
                     if (plugin.visible === false)
                         continue;
+                    // A paneId with no matching pane (e.g. the pane it targeted was
+                    // since removed) falls back to the main pane rather than being
+                    // silently skipped — see the doc comment on `ChartPlugin.paneId`.
+                    const api = plugin.paneId && plugin.paneId !== 'main' ? (paneApiById.get(plugin.paneId) ?? mainApi) : mainApi;
                     // save/restore isolates each plugin's canvas state (strokeStyle,
                     // lineDash, ...) from the next one — a plugin that forgets to
                     // clean up after itself can't bleed style into whatever draws
@@ -169,10 +204,45 @@ export class ChartRenderer {
             }
         }
         finally {
-            frameEnded = true;
+            frameState.ended = true;
             disposeYScale();
+            for (const { dispose } of paneScales)
+                dispose();
         }
     }
+    /**
+     * Builds the `PluginRenderApi` for one pane — the main price pane or a
+     * declared indicator pane, identical shape either way — from that pane's
+     * own rect/value-domain/scale plus whatever `geometry` every pane shares
+     * for this frame (shared because there is only one time axis, and one
+     * frame-ended flag, for the whole stack; see `FrameGeometry`).
+     */
+    buildPluginApi(rect, valueMin, valueMax, scale, geometry) {
+        const { chartWidth, xForIndex, indexForX, visibleStartIndex, visibleEndIndex, allPoints, frameState } = geometry;
+        return {
+            ctx: this.ctx,
+            chartWidth,
+            chartHeight: rect.height,
+            xForIndex,
+            yForValue: (value) => {
+                if (frameState.ended) {
+                    throw new Error('wick-charts: PluginRenderApi.yForValue called after its frame ended — ' +
+                        'only call it synchronously inside ChartPlugin.draw()');
+                }
+                // Local pane-space y (scale's range is [rect.height, 0]) shifted
+                // into absolute canvas pixels by the pane's own top offset.
+                return rect.top + scale.map(value);
+            },
+            indexForX,
+            // Exact inverse of the mapping above: subtract the pane's top offset
+            // before inverting the same [valueMin, valueMax] -> [rect.height, 0]
+            // mapping createScale set up for it.
+            valueForY: (y) => valueMin + (1 - (y - rect.top) / rect.height) * (valueMax - valueMin),
+            visibleStartIndex,
+            visibleEndIndex,
+            allPoints,
+        };
+    }
     /** The decimal precision `formatPrice` should use for the current price
      * range — shared by the axis ticks and the crosshair's price label so
      * both display the same value with the same rounding. */
@@ -180,21 +250,30 @@ export class ChartRenderer {
         const ticks = niceTicks(priceMin, priceMax, this.axis.priceTickCount);
         return ticks.length > 1 ? ticks[1] - ticks[0] : 0;
     }
-    renderPriceAxis(priceMin, priceMax, step, yScale, chartWidth, chartHeight) {
+    /**
+     * Draws one pane's right-side value axis: boundary line, horizontal grid
+     * lines, and tick labels. Used for both the main price pane and every
+     * indicator pane — `topOffset` shifts everything down by that pane's own
+     * position in the stack (0 for the main pane, which sits at the top), so
+     * `yScale` only ever has to know about its own pane-local [0, chartHeight]
+     * range and never about where that pane lives in the full canvas.
+     */
+    renderPriceAxis(priceMin, priceMax, step, yScale, chartWidth, chartHeight, topOffset) {
         const { ctx, axis } = this;
         const ticks = niceTicks(priceMin, priceMax, axis.priceTickCount);
         ctx.strokeStyle = axis.lineColor;
         ctx.beginPath();
-        ctx.moveTo(chartWidth + 0.5, 0);
-        ctx.lineTo(chartWidth + 0.5, chartHeight);
+        ctx.moveTo(chartWidth + 0.5, topOffset);
+        ctx.lineTo(chartWidth + 0.5, topOffset + chartHeight);
         ctx.stroke();
         ctx.font = this.axisFont();
         ctx.textAlign = 'left';
         ctx.textBaseline = 'middle';
         for (const value of ticks) {
-            const y = yScale.map(value);
-            if (y < 0 || y > chartHeight)
+            const localY = yScale.map(value);
+            if (localY < 0 || localY > chartHeight)
                 continue;
+            const y = topOffset + localY;
             ctx.strokeStyle = axis.gridLineColor;
             ctx.beginPath();
             ctx.moveTo(0, y + 0.5);
@@ -204,6 +283,18 @@ export class ChartRenderer {
             ctx.fillText(formatPrice(value, step), chartWidth + 6, y);
         }
     }
+    /** The horizontal rule separating an indicator pane from whatever sits
+     * above it (the main pane, or the previous indicator pane) — the same
+     * `axis.lineColor` boundary style `renderTimeAxis` already draws between
+     * the plotting area and the time-axis strip. */
+    renderPaneSeparator(top, chartWidth) {
+        const { ctx, axis } = this;
+        ctx.strokeStyle = axis.lineColor;
+        ctx.beginPath();
+        ctx.moveTo(0, top + 0.5);
+        ctx.lineTo(chartWidth, top + 0.5);
+        ctx.stroke();
+    }
     renderTimeAxis(times, startIdx, visibleCount, chartHeight, chartWidth, xForIndex) {
         const { ctx, axis } = this;
         const visibleTimes = times.slice(startIdx, startIdx + visibleCount);
@@ -223,14 +314,18 @@ export class ChartRenderer {
             ctx.fillText(label, x, chartHeight + 6);
         }
     }
-    renderCrosshairAndLegend(point, x, timeSeconds, hoverY, valueMin, valueMax, priceStep, chartWidth, chartHeight) {
+    renderCrosshairAndLegend(point, x, timeSeconds, hoverY, valueMin, valueMax, priceStep, chartWidth, chartHeight, stackHeight) {
         const { ctx, canvas, seriesDefinition, style, crosshair } = this;
         ctx.save();
         ctx.strokeStyle = crosshair.lineColor;
         ctx.setLineDash([4, 4]);
+        // Spans the whole pane stack (not just the main pane's own
+        // chartHeight) so hovering a candle lines up with the same column
+        // across every indicator pane below it — see the call site's comment
+        // in `render()` for why the horizontal line/legend don't follow suit.
         ctx.beginPath();
         ctx.moveTo(x, 0);
-        ctx.lineTo(x, chartHeight);
+        ctx.lineTo(x, stackHeight);
         ctx.stroke();
         // The horizontal line follows the actual cursor/finger position, not
         // any property of the hovered point — pinning it to (say) the candle's

package/dist/types.d.ts

@@ -118,6 +118,45 @@ export interface ChartLegendOptions {
      * Defaults to 12. */
     cursorGap?: number;
 }
+/**
+ * Declares one indicator/oscillator pane — a horizontal strip reserved
+ * below the main price pane, with its own value-axis domain independent of
+ * price (an RSI pane's fixed `[0, 100]`, a MACD pane auto-fit to whatever
+ * it's plotting). The pane itself draws nothing: content comes entirely
+ * from `ChartPlugin`s registered with a matching `paneId` (see
+ * `ChartPlugin.paneId` and `WickChart.addPane`) — the same "core provides
+ * layout, the app provides the math" split the plugin system already uses
+ * for indicator overlays on the main pane.
+ */
+export interface PaneOptions {
+    /** Stable identifier — matched against `ChartPlugin.paneId` to route a
+     * plugin's `draw()` into this pane instead of the main price pane.
+     * Uniqueness is the caller's responsibility; `addPane` doesn't enforce it. */
+    id: string;
+    /** Share of the total plotting height (canvas height minus the
+     * time-axis strip) this pane occupies. Every declared pane is scaled
+     * down proportionally (never one at a time, which would change their
+     * relative sizing) if their combined ratio would leave the main pane
+     * less than a fifth of the stack. Defaults to 0.25. */
+    heightRatio?: number;
+    /**
+     * This pane's own value-axis domain for the current frame, called once
+     * per render. Defaults to a fixed `{ min: 0, max: 1 }` if omitted, which
+     * is almost never meaningful — supply this for any real indicator pane
+     * (e.g. `() => ({ min: 0, max: 100 })` for RSI, or a closure over
+     * whatever series your own plugin is tracking for something auto-fit
+     * like MACD).
+     */
+    getValueRange?: () => ValueRange;
+}
+/** `PaneOptions` with every optional field defaulted — what `WickChart`
+ * actually stores and hands to `ChartRenderer`, so the renderer never has
+ * to re-apply `??` defaults on every frame. */
+export interface ResolvedPaneOptions {
+    id: string;
+    heightRatio: number;
+    getValueRange: () => ValueRange;
+}
 export interface WickChartOptions {
     /**
      * Which registered series type to render this chart as (see

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wick-charts",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "An open-source financial charting library — WASM (Rust) for compute, Canvas2D for rendering.",
   "license": "MIT",
   "author": "eatnows",