wick-charts 0.3.0 → 0.5.0

package/README.md

@@ -17,10 +17,12 @@ npm install wick-charts
   - [Install](#install)
   - [Quick start](#quick-start)
   - [Candle data](#candle-data)
+  - [Line charts](#line-charts)
   - [Styling](#styling)
   - [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)
@@ -135,6 +137,39 @@ it — a dataset with no `volume` at all renders exactly as if the feature didn'
 array) is safe. It resets pan/zoom/hover state — call it for a genuinely new dataset, and use
 `setDataLoader()` (below) to extend the current one instead.
 
+### Line charts
+
+For a plain time series with no OHLC shape — an equity curve, a metric over time, anything
+that's just one number per point — `createLineChart` is the line-series equivalent of
+`createCandlestickChart` above. A line point is `{ time, value }`:
+
+```ts
+import { createLineChart } from 'wick-charts';
+
+const chart = createLineChart(canvas, {
+  style: { lineColor: '#2196f3', lineWidth: 1.5 }, // both shown here are the defaults
+});
+
+chart.setData([
+  { time: '2024-01-01T00:00:00Z', value: 100 },
+  { time: '2024-01-02T00:00:00Z', value: 103.4 },
+  { time: '2024-01-03T00:00:00Z', value: 101.8 },
+  // ...
+]);
+
+chart.render();
+```
+
+Everything else — pan/zoom/hover, `setDataLoader`, `addPlugin`, `addPane`, `background`/
+`font`/`axis`/`crosshair`/`legend` styling — works exactly as it does for a candlestick chart,
+since none of it is specific to what's actually plotted (see "Series types" under
+Architecture). `value` accepts `NaN` (or any non-finite number) as an explicit gap: the line
+breaks there and resumes at the next real value, rather than plotting a bogus point or
+throwing — useful for a series with missing data at some points without pre-filtering it
+yourself. The hover legend shows `Value <number>` (or `Value —` for a hovered gap) in place of
+candlestick's OHLC breakdown; `new WickChart(canvas, { type: 'line' })` also works, the same
+untyped escape hatch `type: 'candlestick'` has, if you'd rather not import the factory.
+
 ### Styling
 
 Every visual aspect of the chart is an option — nothing is a fixed constant you can't reach.
@@ -354,6 +389,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
@@ -402,31 +489,35 @@ for *this* series (a line series wouldn't have a body width or volume bars to co
 
 ### Series types
 
-Candlesticks are the only chart type today, but nothing above `src/series/` knows that.
-`WickChart` and `ChartRenderer` are generic over a point shape (`SeriesPoint` — just a
-`time`) and delegate every type-specific decision — how to compute the value-axis range,
-how to draw the visible points, what a hover legend says — to a
+Candlestick and line are the two chart types today, and nothing above `src/series/` treats
+either specially. `WickChart` and `ChartRenderer` are generic over a point shape
+(`SeriesPoint` — just a `time`) and delegate every type-specific decision — how to compute
+the value-axis range, how to draw the visible points, what a hover legend says — to a
 `SeriesDefinition` (see `src/series/types.ts`) resolved at construction time from
 `options.type` via a small registry (`src/series/registry.ts`). `src/series/candlestick.ts`
-is the reference implementation: it registers itself as `'candlestick'` on import, which is
-why importing `wick-charts` at all is enough to make that type available without the caller
-registering anything.
-
-Adding a second chart type (line, area, bar, ...) means writing one new file that
-implements `SeriesDefinition<TPoint, TStyle>` and calling `registerSeries` on it — `Viewport`,
-event handling, data loading, and WASM scale dispatch are all untouched, and existing
-`type: 'candlestick'` charts keep working exactly as before. This is the extension point the
-`type` option and `style` option are built around: `style` is whatever shape the chosen
-series's `defaultStyle` declares (candlestick's is `{ upColor, downColor }`), merged over
-that default rather than hardcoded into the chart itself.
+and `src/series/line.ts` both register themselves (as `'candlestick'`/`'line'`) on import,
+which is why importing `wick-charts` at all is enough to make either type available without
+the caller registering anything.
+
+Adding a chart type (area, bar, ...) means writing one new file that implements
+`SeriesDefinition<TPoint, TStyle>` and calling `registerSeries` on it — `Viewport`, event
+handling, data loading, and WASM scale dispatch are all untouched, and every existing chart
+of another type keeps working exactly as before; `src/series/line.ts` is a second, smaller
+worked example of this alongside candlestick's own. This is the extension point the `type`
+option and `style` option are built around: `style` is whatever shape the chosen series's
+`defaultStyle` declares (candlestick's is `{ upColor, downColor, ... }`, line's is `{
+lineColor, lineWidth }`), merged over that default rather than hardcoded into the chart
+itself.
 
 `options.type` is a plain string the registry resolves at runtime, so `new WickChart(canvas,
 { type: 'candlestick', style: {...} })` type-checks even if `style` has nothing to do with
 `CandlestickStyle` — nothing ties a runtime string to a specific `TPoint`/`TStyle` pair at the
-type level. `createCandlestickChart()` (in `src/index.ts`) is the fix for the one built-in
-type: a thin wrapper that pins both generics so its `style` is fully checked. A new series
-should export an equivalent `create<Name>Chart` next to it rather than widening
-`WickChartOptions` itself, so each series's style shape stays independent of every other's.
+type level. `createCandlestickChart()`/`createLineChart()` (both in `src/index.ts`) are the
+fix for the two built-in types: a thin wrapper per series that pins both generics so its
+`style` is fully checked. A new series should export an equivalent `create<Name>Chart` next
+to it rather than widening `WickChartOptions` itself, so each series's style shape stays
+independent of every other's — line's factory is the second proof this pattern holds up, not
+just a one-off written for candlestick.
 
 ### Plugins (markers, annotations, drawing tools)
 
@@ -469,6 +560,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`)
@@ -533,12 +636,16 @@ hover state — and on-demand history loading via `setDataLoader`. Per-candle vo
 the bottom fifth of the chart when a candle has `volume`, and are entirely omitted (nothing
 drawn, nothing reserved) for data that doesn't.
 Coordinate scaling runs on WASM once a frame's point count crosses the threshold, JS below
-it. Candlestick is the only registered series type so far; the plugin extension point (draw
+it. Candlestick and line are the two registered series types so far (`createCandlestickChart`/
+`createLineChart`); the plugin extension point (draw
 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,9 @@
 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 { LineStyle } from './series/line.js';
+import type { Candle, LinePoint, PaneOptions, WickChartOptions, SeriesPoint, ValueRange } from './types.js';
+export type { BusinessDay, Candle, LinePoint, 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';
@@ -11,7 +12,9 @@ export { mergeSeriesPoints } from './mergeSeries.js';
 export { registerSeries, getSeries } from './series/registry.js';
 export type { SeriesDefinition, SeriesDrawContext } from './series/types.js';
 export type { CandlestickStyle } from './series/candlestick.js';
+export type { LineStyle } from './series/line.js';
 export { candlestickSeries } from './series/candlestick.js';
+export { lineSeries } from './series/line.js';
 export { LinearScale } from './scale.js';
 export { toUnixSeconds } from './time.js';
 export { Viewport } from './viewport.js';
@@ -41,6 +44,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 +103,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 +200,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`. */
@@ -223,3 +271,13 @@ export declare class WickChart<TPoint extends SeriesPoint = Candle> {
 export declare function createCandlestickChart(canvas: HTMLCanvasElement, options?: Omit<WickChartOptions, 'type' | 'style'> & {
     style?: Partial<CandlestickStyle>;
 }): WickChart<Candle>;
+/**
+ * The second series type's equivalent of `createCandlestickChart` above —
+ * pins `TPoint` (`LinePoint`) and `TStyle` (`LineStyle`) so `style` is
+ * fully checked here the same way, rather than accepted as the untyped
+ * `Record<string, unknown>` `WickChartOptions.style` allows for `new
+ * WickChart(canvas, { type: 'line', style })`.
+ */
+export declare function createLineChart(canvas: HTMLCanvasElement, options?: Omit<WickChartOptions, 'type' | 'style'> & {
+    style?: Partial<LineStyle>;
+}): WickChart<LinePoint>;

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';
@@ -8,13 +9,14 @@ import { importRealWasm } from './wasmImporter.js';
 export { distanceToSegment, hitTestPoint, hitTestSegment } from './hitTest.js';
 export { mergeSeriesPoints } from './mergeSeries.js';
 export { registerSeries, getSeries } from './series/registry.js';
-// Also registers the 'candlestick' type as a module-load side effect — see
-// src/series/candlestick.ts and src/series/registry.ts. A new series type
-// gets the same treatment: implement SeriesDefinition, export it here (or
-// have the consuming app import it directly before constructing a chart of
-// that type), and `type: '<its key>'` becomes usable with no other change
-// to this file.
+// Also registers 'candlestick'/'line' as a module-load side effect — see
+// src/series/candlestick.ts, src/series/line.ts, and src/series/registry.ts.
+// A new series type gets the same treatment: implement SeriesDefinition,
+// export it here (or have the consuming app import it directly before
+// constructing a chart of that type), and `type: '<its key>'` becomes
+// usable with no other change to this file.
 export { candlestickSeries } from './series/candlestick.js';
+export { lineSeries } from './series/line.js';
 export { LinearScale } from './scale.js';
 export { toUnixSeconds } from './time.js';
 export { Viewport } from './viewport.js';
@@ -26,6 +28,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 +67,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 +368,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 +416,7 @@ export class WickChart {
             hoverIndex: this.hoverIndex,
             hoverY: this.hoverY,
             plugins: this.plugins,
+            panes: this.panes,
         });
         this.maybeLoadMore();
     }
@@ -463,7 +519,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 +653,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 +699,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));
@@ -713,3 +782,13 @@ export class WickChart {
 export function createCandlestickChart(canvas, options) {
     return new WickChart(canvas, { ...options, type: 'candlestick' });
 }
+/**
+ * The second series type's equivalent of `createCandlestickChart` above —
+ * pins `TPoint` (`LinePoint`) and `TStyle` (`LineStyle`) so `style` is
+ * fully checked here the same way, rather than accepted as the untyped
+ * `Record<string, unknown>` `WickChartOptions.style` allows for `new
+ * WickChart(canvas, { type: 'line', style })`.
+ */
+export function createLineChart(canvas, options) {
+    return new WickChart(canvas, { ...options, type: 'line' });
+}

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,92 @@ 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;
-            seriesDefinition.draw({ ctx, visible, startIndex: startIdx, xForIndex, slotWidth, yScale, chartHeight }, style);
+            // Exact inverse of xForIndex above — solving
+            // `x = (index - viewport.startIndex) * slotWidth + slotWidth / 2` for `index`.
+            const indexForX = (x) => viewport.startIndex + (x - slotWidth / 2) / slotWidth;
+            // save/restore isolates whatever canvas state a series's draw()
+            // touches (lineWidth, line dash, ...) from the axis/crosshair/plugin
+            // drawing that follows — the same isolation each plugin already gets
+            // around its own draw() call below. Without this, a property no
+            // series happened to set before (lineSeries.draw() is the first
+            // built-in one to set ctx.lineWidth) would silently leak into every
+            // subsequent stroke() this frame, including axis boundary lines,
+            // grid lines, and the crosshair.
+            ctx.save();
+            try {
+                seriesDefinition.draw({ ctx, visible, startIndex: startIdx, xForIndex, slotWidth, yScale, chartHeight }, style);
+            }
+            finally {
+                ctx.restore();
+            }
             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 +218,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 +264,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 +297,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 +328,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/series/line.d.ts

@@ -0,0 +1,14 @@
+import type { LinePoint } from '../types.js';
+import type { SeriesDefinition } from './types.js';
+/** The second built-in series type — a plain single-value line, the
+ * simplest possible `SeriesDefinition` beyond candlestick's OHLC. Exists as
+ * much to exercise the registry with a genuinely different `TPoint`/`TStyle`
+ * pair as to be useful on its own; see `src/series/candlestick.ts` for the
+ * reference implementation this mirrors. */
+export interface LineStyle {
+    /** Stroke color. Defaults to `'#2196f3'`. */
+    lineColor: string;
+    /** Stroke width, in px. Defaults to 1.5. */
+    lineWidth: number;
+}
+export declare const lineSeries: SeriesDefinition<LinePoint, LineStyle>;

package/dist/series/line.js

@@ -0,0 +1,65 @@
+import { fitRange } from '../priceRange.js';
+import { registerSeries } from './registry.js';
+const DEFAULT_STYLE = {
+    lineColor: '#2196f3',
+    lineWidth: 1.5,
+};
+/** Falls back to a fixed `[0, 1]` range when every visible point is a gap
+ * (`NaN`/non-finite `value`) — `Math.min()`/`Math.max()` over an empty
+ * array are `Infinity`/`-Infinity`, which would otherwise feed `fitRange`
+ * a `NaN` midpoint. Candlestick never needs this: `Candle`'s OHLC fields
+ * aren't optional or gap-tolerant the way a line point's `value` is. */
+function getValueRange(visible, scaleFactor) {
+    const values = visible.map((p) => p.value).filter((v) => Number.isFinite(v));
+    if (values.length === 0)
+        return { min: 0, max: 1 };
+    return fitRange(Math.min(...values), Math.max(...values), scaleFactor);
+}
+function draw(context, style) {
+    const { ctx, visible, startIndex, xForIndex, yScale } = context;
+    if (visible.length === 0)
+        return;
+    // Batched through mapMany (one call per array) rather than once per
+    // point in the loop below — same reasoning as candlestick's draw(): it's
+    // what lets the WASM path pay the JS<->WASM boundary cost once per frame.
+    // NaN values map to NaN here, harmlessly — skipped below rather than
+    // filtered out first, so `ys[i]` still lines up with `visible[i]`.
+    const ys = yScale.mapMany(visible.map((p) => p.value));
+    ctx.strokeStyle = style.lineColor;
+    ctx.lineWidth = style.lineWidth;
+    ctx.beginPath();
+    // `drawing` tracks whether the path is mid-segment — a non-finite value
+    // (a gap in the data) breaks it, and the line resumes fresh at the next
+    // real value rather than jumping straight across the gap.
+    let drawing = false;
+    visible.forEach((point, i) => {
+        if (!Number.isFinite(point.value)) {
+            drawing = false;
+            return;
+        }
+        const x = xForIndex(startIndex + i);
+        const y = ys[i];
+        if (drawing) {
+            ctx.lineTo(x, y);
+        }
+        else {
+            ctx.moveTo(x, y);
+            drawing = true;
+        }
+    });
+    ctx.stroke();
+}
+function formatLegend(point) {
+    return [`Value ${Number.isFinite(point.value) ? point.value.toLocaleString('en-US') : '—'}`];
+}
+export const lineSeries = {
+    type: 'line',
+    defaultStyle: DEFAULT_STYLE,
+    getValueRange,
+    draw,
+    formatLegend,
+};
+// Registered as a module-level side effect, same as candlestickSeries — see
+// src/series/candlestick.ts for why. src/index.ts imports this file so
+// 'line' is available the moment the package itself is imported.
+registerSeries(lineSeries);

package/dist/types.d.ts

@@ -57,6 +57,18 @@ export interface Candle extends SeriesPoint {
     close: number;
     volume?: number;
 }
+/**
+ * A single value plotted against time — the point shape for the built-in
+ * `'line'` series (see `src/series/line.ts`), and the simplest possible
+ * instance of `SeriesPoint` beyond `Candle`: a plain time series with
+ * nothing OHLC-specific about it. `value` is `NaN`-tolerant: a `NaN`
+ * (or non-finite) value is treated as a gap — the line breaks there and
+ * resumes at the next real value, rather than plotting a bogus point or
+ * throwing.
+ */
+export interface LinePoint extends SeriesPoint {
+    value: number;
+}
 /** Text styling shared by every label the chart draws — axis ticks,
  * crosshair axis labels, and the hover legend. `axisSize`/`legendSize` are
  * separate since the legend has historically been drawn one px larger to
@@ -118,6 +130,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.5.0",
   "description": "An open-source financial charting library — WASM (Rust) for compute, Canvas2D for rendering.",
   "license": "MIT",
   "author": "eatnows",