@livo-build/charts 0.2.1 → 0.2.3

package/README.md

@@ -1,14 +1,19 @@
 # @livo-build/charts (livo-charts)
 
+> **Live demos + docs: [charts.livo.build](https://charts.livo.build)** — interactive
+> examples with copy-paste code, plus agent-friendly [llms.txt](https://charts.livo.build/llms.txt)
+> / [llms-full.txt](https://charts.livo.build/llms-full.txt).
+
 A lightweight, **dependency-free** canvas charting library. The core renders to a
 `<canvas>` with zero runtime dependencies; a thin, self-styled React wrapper is
 shipped under a separate entry so non-React consumers never pull React into their
 bundle.
 
-It ships a **TradingView-style trading chart**: candlesticks **or** a line series, a
-**volume panel**, a **crosshair with price + time axis labels**, an **OHLCV legend**,
-independent **X and Y zoom** (+ pan), and a toolbar for **intervals, USD/ETH,
-price/market-cap and fullscreen**. The architecture (a framework-agnostic `Chart`
+It ships a **TradingView-style trading chart**: candlesticks, a line, a two-tone
+**baseline** area **or Heikin-Ashi** candles, a **volume panel**, a **volume-by-price
+profile**, a **crosshair with price + time axis labels**, an **OHLCV legend**, independent
+**X and Y zoom** (+ pan, plus touch/pinch), and a toolbar for **intervals, USD/ETH,
+price/market-cap, log scale and fullscreen**. The architecture (a framework-agnostic `Chart`
 controller + a pure `draw()` pass) is built to keep growing — indicators, overlays,
 multiple panes — without touching consumers.
 
@@ -28,8 +33,7 @@ import { PriceChart } from "@livo-build/charts/react";
 <PriceChart
   swaps={trades}          // [{ t: unixSeconds, p: priceUsd, v: usdVolume }, …]
   ethUsd={1711.81}        // enables the USD↔ETH toggle
-  tokenAddress="0x…"      // enables the Price↔MCap toggle (reads totalSupply())
-  decimals={18}
+  supply={1_000_000_000}  // enables the Price↔MCap toggle (or tokenAddress to read it)
   symbol="PEPE"
   quote="WETH"
   height={420}
@@ -37,14 +41,27 @@ import { PriceChart } from "@livo-build/charts/react";
 ```
 
 `swaps` are aggregated into OHLC+volume candles client-side. The toolbar
-(`1s 1m 5m 15m 1h 4h 1d`, candle/line, Price/MCap, USD/ETH, flip, fullscreen) and the
+(`1s 1m 5m 15m 1h 4h 1d`, candle/line, Price/MCap, USD/ETH, flip, log, fullscreen) and the
 OHLCV legend are built in. The canvas is long-lived, so zoom/pan survive prop updates
 (streaming trades won't reset the user's view). The wrapper is styled inline — no CSS
 framework required.
 
-Market cap = `price × totalSupply()`, fetched once via `rpcUrl` (default
-`https://cloudflare-eth.com`) and cached; it silently falls back to price if the RPC
-is unavailable.
+`PriceChart` only aggregates the `swaps` you give it — it doesn't fetch more, so panning
+stops at the oldest trade. For **infinite back-history**, pass `onLoadOlder` (fires when the
+user pans/zooms within ~one viewport of the start) and prepend older trades to `swaps`; the
+right-anchored view keeps the position stable. Scope the toolbar to intervals your data
+covers with `intervals={[["1m", 60], ["5m", 300]]}` (a thin series bucketed at `1h`
+collapses into a couple of candles), and react to interval changes with `onIntervalChange`.
+For a turnkey lazy-loading chart, use a feed (`HyperliquidChart` / `connectFeed`) instead.
+
+The default **visible span** is `initialBars × interval`. To open on, say, the last 7 days at
+1h candles, give it a week of data and `defaultInterval={3600}` + `options={{ initialBars: 168 }}`
+(168 × 1h = 7 days). The user can still zoom/scroll out from there.
+
+Market cap = `price × supply`. Pass `supply` directly, or pass `tokenAddress` (+`decimals`)
+to read `totalSupply()` once via `rpcUrl` (default `https://cloudflare-eth.com`, cached).
+The **Price/MCap toggle only appears when one of those is set** — otherwise it's hidden
+(no dead button), and it falls back to price if the RPC read fails.
 
 ### Live Hyperliquid chart
 
@@ -68,15 +85,151 @@ import { HyperliquidChart } from "@livo-build/charts/react";
 history loads lazily as the user scrolls left (infinite back-scroll) — both with no
 API key. Zoom/pan survive every update.
 
+### Live Polymarket & Signal Radar charts
+
+Two more turnkey, key-free live charts wrap the framework-agnostic `Chart`:
+
+```tsx
+import { PolymarketChart, SignalsChart } from "@livo-build/charts/react";
+
+// A prediction-market outcome (probabilities → a % y-axis), from the public CLOB.
+<PolymarketChart tokenId={yesTokenId} bucketSeconds={3600} label="Yes" />
+
+// A token tracked by the Livo signals engine ("Signal Radar") — real indexed history.
+<SignalsChart token="PEPE" bucketSeconds={300} indicators={[{ type: "ema", period: 21 }]} />
+```
+
+Both are `ChartFeed`s under the hood — drive the core directly with `connectFeed`:
+
+```ts
+import { Chart, connectFeed, polymarketFeed, signalsFeed } from "@livo-build/charts";
+
+connectFeed(new Chart(el), polymarketFeed({ tokenId, bucketSeconds: 3600 }), { interval: 3600 });
+connectFeed(new Chart(el2), signalsFeed({ token: "PEPE", bucketSeconds: 300 }), { interval: 300 });
+```
+
+- **`polymarketFeed`** — bucketed OHLC from the public Polymarket CLOB `prices-history`
+  endpoint, polled for a building candle. Prices are probabilities in [0, 1] (no volume).
+  `fetchPolymarketPriceHistory` is exported for custom fetching.
+- **`signalsFeed`** — real OHLC from the Signal Radar **index**: it queries `/graphql`
+  (`allSwaps` for the pool) and buckets the swaps into candles at any interval, paging older
+  swaps in as you scroll — so 1m / 5m candles go days deep (the index has no TTL), and 1h/4h/1d
+  just zoom out in time. The live candle is polled from `/data` (current price). If `/graphql`
+  is unreachable (e.g. cross-origin CORS) or you pass `history: "spark"`, it falls back to the
+  snapshot's `spark`. `fetchSignalsSwaps` / `fetchSignalsMarket` / `sparkCandles` are exported.
+  (Cross-origin use needs `/graphql` CORS-enabled on the engine; same-origin always works.)
+
 ### Indicators
 
 `PriceChart` and `HyperliquidChart` accept `indicators` — overlays drawn on the price
-pane. Each is `{ type: "sma" | "ema" | "wma" | "vwap", period, color?, source? }`
-(`source` defaults to `close`; `vwap` is cumulative and ignores period/source).
+pane. Each is `{ type: "sma" | "ema" | "wma" | "vwap" | "bollinger", period, color?, source?, mult? }`
+(`source` defaults to `close`; `vwap` is cumulative; `bollinger` draws a 3-line band at
+`mult` std-devs, default 2).
 Colors fall back to a built-in palette by position. The pure
 `sma`/`ema`/`wma`/`vwap`/`bollingerBands`/`computeIndicator` helpers are exported from
 the core (e.g. feed `bollingerBands(values).{upper,mid,lower}` as three overlays).
 
+**Oscillators (RSI / MACD / Stochastic / ATR)** render in their own **stacked sub-panes**
+below the volume panel — pass `oscillators`:
+
+```tsx
+<PriceChart
+  swaps={trades}
+  indicators={[{ type: "ema", period: 21 }]}   // on the price pane
+  oscillators={[
+    { type: "rsi", period: 14 },               // 0–100 band with 70/30 rails
+    { type: "macd", fast: 12, slow: 26, signal: 9 },  // line + signal + histogram
+    { type: "stoch", period: 14, dPeriod: 3, smooth: 3 }, // %K/%D, 80/20 rails
+    { type: "atr", period: 14 },               // auto-scaled volatility (price units)
+  ]}
+/>
+```
+
+Each pane defaults to 84px (`height` to override). The pure `rsi(values, period)`,
+`macd(values, fast, slow, signal) → { macd, signal, hist }`,
+`stochastic(candles, kPeriod, dPeriod, smooth) → { k, d }` and `atr(candles, period)`
+helpers are exported too.
+
+### Chart types: candle · line · baseline · Heikin-Ashi
+
+`chartType` (low-level `chart.setChartType(...)`, or the toolbar's ▮▯ / ╱ / ⎓ / HA buttons)
+switches the price series:
+
+- **`candle`** — classic OHLC candlesticks.
+- **`line`** — a close line with a soft gradient area fill.
+- **`baseline`** — a two-tone area around a reference price (green above, red below). Set the
+  reference with `baselinePrice` (defaults to the first visible close); the core exposes
+  `chart.setBaseline(price)`.
+- **`heikin`** — Heikin-Ashi candles: smoothed OHLC that filter noise and make trends easier
+  to read. Indicators/oscillators still read the **raw** closes. The pure `heikinAshi(candles)`
+  transform is exported.
+
+### Volume profile (volume-by-price)
+
+A horizontal histogram of volume per price level, drawn over the price pane (peaked at the
+**Point of Control**). Pass `volumeProfile` (or toggle **VP** in the toolbar); the core has
+`chart.setVolumeProfile(...)`:
+
+```tsx
+<PriceChart swaps={trades} volumeProfile={{ buckets: 24, width: 0.16 }} />
+```
+
+It's computed over the **visible** window, so it tracks zoom/pan. The pure
+`volumeProfile(candles, buckets) → { buckets, maxVol, poc }` helper is exported.
+
+### Fitting the container & axis styling
+
+By default `PriceChart` / `HyperliquidChart` **fit the container** (`fitContent`) — candles
+spread across the full plot width instead of clustering at a capped slot. Set
+`fitContent={false}` for the tight, right-anchored look (the low-level `Chart` defaults to
+tight; the React wrappers default to fill).
+
+The ticks are easy to style — every axis knob is a prop (and a `chart.setAxis({…})` call):
+
+```tsx
+<PriceChart
+  swaps={trades}
+  priceFormat={(v) => `$${v.toLocaleString()}`}  // y-axis labels
+  timeFormat={(t) => new Date(t * 1000).toLocaleTimeString()}
+  priceTicks={6}                                  // horizontal gridlines (default 5)
+  timeTicks={8}                                   // x-axis labels (default 7)
+  axisFont="11px Inter, sans-serif"               // label font (color = theme.axis)
+/>
+```
+
+The **default** price formatter is range-aware: it keeps just enough decimals to tell
+adjacent ticks apart, so a narrow high-value axis (e.g. WETH 1.71K–1.75K) renders
+`1.7350K / 1.7430K` instead of duplicate `1.73K`s. Tick text color comes from `theme.axis`.
+
+### Log scale & themes
+
+The price axis can be **logarithmic** — equal vertical distance = equal % move, the
+right default for assets that span orders of magnitude. `PriceChart`/`HyperliquidChart`
+expose a **Log** toolbar toggle (or pass `options={{ logScale: true }}`); the core has
+`chart.setLogScale(true)`. Log mode auto-falls back to linear if any visible low is ≤ 0.
+
+Two built-in themes ship as `DEFAULT_THEME` (dark) and `LIGHT_THEME`, also addressable
+via `THEME_PRESETS.dark` / `THEME_PRESETS.light`. Pass either (or a partial override) as
+`theme`, or call `chart.setTheme(LIGHT_THEME)`.
+
+### Drawing tools (trendlines & horizontal lines)
+
+The toolbar arms a one-shot draw: **↗** trendline (drag), **—** horizontal line (click),
+**fib** Fibonacci retracement (drag — levels 0/23.6/38.2/50/61.8/78.6/100% between the two
+prices), and **▭** rectangle (drag). Drawings are anchored in **data space**, so they stay
+pinned to their price/time across pan, zoom and live updates. In the default cursor mode,
+click a drawing to select it, drag to move it, and **double-click it to delete it**; **⌫**
+clears all.
+
+```tsx
+<PriceChart swaps={trades} onDrawingsChange={(d) => save(d)} drawings={restored} />
+```
+
+Drive it from the core too: `chart.setDrawMode("trendline" | "hline" | "none")`,
+`getDrawings()` / `setDrawings()` / `removeDrawing(id)` / `clearDrawings()`, and the
+`onDrawingsChange` callback. Pass `hideDrawingTools` to drop the buttons. The
+`computeProjection(input)` helper exposes the same pixel↔data mapping for custom tools.
+
 ### Realtime feeds + lazy history (any data source)
 
 Connect a chart to a **feed** — a source that serves paged OHLCV history *and* live
@@ -105,7 +258,10 @@ const feed = {
 ```
 
 The chart's right-anchored view means prepending history keeps the visible window
-stable, and the controller only asks for more when you scroll near the start.
+stable. The controller prefetches the next page once the view's left edge comes within
+~one viewport of the oldest loaded candle (see the exported `needsHistory` helper) — so
+**zooming out keeps deepening the window with real data** instead of stalling at the
+oldest bar. It advances one page per data length and stops when the feed runs dry.
 
 ## Vanilla / framework-agnostic
 
@@ -132,8 +288,16 @@ chart.destroy();
 | `new Chart(container, options?)` | Creates a `<canvas>`, wires interaction, observes resize. |
 | `setCandles(candles)` | Replace the series (each candle has `vol`) and redraw. |
 | `setInterval(seconds)` | Bucket interval — drives time-axis label granularity. |
-| `setChartType("candle" \| "line")` | Switch series style. |
+| `setChartType("candle" \| "line" \| "baseline" \| "heikin")` | Switch series style. |
+| `setShowVolume(on)` | Show / hide the volume panel (the price pane reclaims the space). |
+| `setVolumeProfile(config)` | Show/configure (or hide with `false`) the volume-by-price histogram. |
+| `setBaseline(price?)` | Reference price for the `baseline` type (undefined = first visible close). |
+| `setLogScale(on)` | Toggle the logarithmic price axis (auto-falls back to linear if any low ≤ 0). |
+| `setAxis({ fitContent, priceFormat, timeFormat, priceTicks, timeTicks, axisFont })` | Style the axes — only the provided keys change. |
 | `setIndicators(indicators)` | Set the moving-average overlays and redraw. |
+| `setOscillators(oscillators)` | Set the RSI / MACD sub-panes and redraw. |
+| `setDrawMode(mode)` | Arm a drawing tool (`"trendline"` / `"hline"`) or `"none"`. |
+| `setDrawings` / `getDrawings` / `removeDrawing(id)` / `clearDrawings()` | Manage drawings. |
 | `setNeedHistory(cb)` | Callback fired when the view nears the start of loaded data (lazy history). |
 | `setHeight(px)` / `setTheme(partial)` | Resize / merge theme overrides. |
 | `resetView()` | Reset zoom/pan (same as double-click). |
@@ -142,30 +306,55 @@ chart.destroy();
 `ChartOptions`: `height`, `theme`, `initialBars` (120), `minBars` (20),
 `maxBarWidth` (18 — caps candle spacing so sparse series stay tight, right-anchored),
 `volumeRatio` (0.18), `rightPad`/`bottomPad`/`topPad`, `onCrosshair`, `indicators`,
-and `onNeedHistory`.
+`oscillators`, `drawings`, `showVolume` (true), `volumeProfile`, `baselinePrice`,
+`logScale` (false), `fitContent` (false),
+`maxBarWidth` (18) / `maxBodyWidth` (40), `priceFormat`/`timeFormat`, `priceTicks` (5) /
+`timeTicks` (7), `axisFont`, and `onNeedHistory`.
 
 ### Helpers
 
 - `buildOHLC(points, interval, transform?)` — bucket priced trades into OHLC+volume
   candles. `transform` = `{ denom, ethUsd, flip, supply }` (`supply` → market cap).
 - `transformPrice(p, transform?)` — apply the transform to one price.
-- `sma` / `ema` / `wma` / `vwap` / `bollingerBands` / `computeIndicator` — pure
-  indicator math (aligned to input, null until the window fills).
+- `sma` / `ema` / `wma` / `vwap` / `bollingerBands` / `rsi` / `macd` / `stochastic` / `atr`
+  / `volumeProfile` / `heikinAshi` / `computeIndicator` — pure indicator + transform math
+  (aligned to input, null until the window fills).
 - `connectFeed(chart, feed, opts)` — wire a `ChartFeed` (paged history + live stream)
   to a chart: latest page, lazy older history, live merge. Returns `{ disconnect }`.
 - `hyperliquidFeed({ coin, interval, testnet })` — a ready `ChartFeed` (REST history +
   WebSocket live). `fetchHyperliquidCandles` / `fetchHlCandleWindow` / `mapHlCandles` /
   `HL_INTERVAL_SECONDS` are exported for custom fetching.
+- `polymarketFeed({ tokenId, bucketSeconds })` — a `ChartFeed` for a Polymarket outcome
+  (CLOB price-history + polling). `fetchPolymarketPriceHistory` is exported.
+- `signalsFeed({ token, bucketSeconds })` — a `ChartFeed` for a Signal Radar token: indexed
+  `allSwaps` → OHLC (lazy older pages) + a `/data`-polled live candle, spark fallback.
+  `fetchSignalsSwaps` / `fetchSignalsMarket` / `sparkCandles` are exported.
 - `draw(input)` — the pure render pass (exported for custom hosts/tests); returns the
   crosshair candle.
-- `DEFAULT_THEME`, `formatValue`, `formatVolume`, `formatTime`.
+- `DEFAULT_THEME` / `LIGHT_THEME` / `THEME_PRESETS`, `formatValue`, `formatAxisValue`
+  (range-aware tick labels), `formatVolume`, `formatTime`.
+- `slotWidth(plotW, count, maxBarWidth, fitContent?)` — candle slot-width math (exported
+  for custom hosts).
+- `computeProjection(input)` / `priceScale` / `timeScale` / `windowOf` — the pixel↔data
+  mapping the renderer and drawing tools share (returns `{ xOfTime, timeOfX, yOfPrice,
+  priceOfY, … }`).
 
 ## Interaction
 
 - **Scroll** over the plot → zoom time; over the price axis → zoom price.
-- **Drag** the plot → pan; drag the time axis → zoom X; drag the price axis → zoom Y.
+- **Scroll horizontally** (trackpad swipe / shift+wheel) → pan through time; scrolling
+  back into history lazy-loads older candles from the feed.
+- **Drag** the plot → pan; drag the time axis → zoom X; drag the price axis → zoom Y. Panning
+  pins the oldest candle to the left edge (no dragging into empty space on the left); on a feed,
+  or with `PriceChart`'s `onLoadOlder`, reaching that edge streams in older history instead. You
+  *can* scroll past the newest candle into the future — drag it up to halfway across to leave
+  right-edge whitespace (so the current price isn't pinned to the edge).
 - **Hover** → crosshair + price/time axis labels + the OHLCV legend.
-- **Double-click** → reset zoom/pan.
+- **Double-click** → reset zoom/pan (or delete a drawing when one is under the cursor).
+- **Touch** → one finger pans (or zooms an axis from its gutter); two-finger pinch
+  zooms time (horizontal spread) and price (vertical spread) together.
+- **Drawing tools** → arm trendline/h-line from the toolbar; select + drag to move,
+  double-click to delete.
 
 ## Design notes
 

package/dist/core/chart.d.ts

@@ -1,4 +1,17 @@
-import type { Candle, ChartOptions, ChartTheme, ChartType, Indicator } from "./types";
+import type { AxisOptions, Candle, ChartOptions, ChartTheme, ChartType, DrawMode, Drawing, Indicator, Oscillator } from "./types";
+/**
+ * Whether a feed should be asked for older candles, given the loaded length and the
+ * current view. Returns true when the visible window's left edge is within ~one screen
+ * (`max(floor, visibleCount)`) of the start of loaded data — so zooming out / panning
+ * left keeps deepening the window (prefetching a viewport of buffer) instead of hitting
+ * a wall at the oldest loaded candle and just fattening the bars. Pure + exported so the
+ * prefetch trigger is testable without a DOM.
+ */
+export declare function needsHistory(length: number, count: number, offset: number, floor?: number): boolean;
+/** Largest pan offset that still fills the window — pins the OLDEST candle to the left edge
+ *  so a left-drag can't expose empty space past the start of the data. Pure + exported for
+ *  testing; the controller clamps every pan/zoom to it. */
+export declare function maxPanOffset(length: number, count: number): number;
 /**
  * Framework-agnostic candlestick/line chart with a volume panel. Creates and owns a
  * `<canvas>` inside the given container and wires the interactions:
@@ -23,17 +36,42 @@ export declare class Chart {
     private readonly ro;
     private readonly pads;
     private readonly minBars;
-    private readonly maxBarWidth;
+    private maxBarWidth;
+    private maxBodyWidth?;
     private readonly volumeRatio;
     private readonly onCrosshair?;
     private theme;
     private height;
     private candles;
+    /** Price-series candles (Heikin-Ashi in "heikin" mode), precomputed on data/type change
+     *  so the O(n) transform doesn't run every frame. */
+    private priceCandles;
     private indicators;
+    private oscillators;
+    private drawings;
+    private drawMode;
+    private selectedDrawing;
+    /** in-progress trendline (drag from anchor A to B). */
+    private draftDrawing;
+    /** active move of an existing drawing: its id + the data-space grab anchor + originals. */
+    private drawingDrag;
+    private onDrawingsChange?;
+    private onDrawModeChange?;
     /** Indicator values precomputed on data/indicator change (not per frame). */
     private overlays;
     private interval;
     private type;
+    private showVolume;
+    private logScale;
+    private emptyText?;
+    private baselinePrice?;
+    private volumeProfile?;
+    private fitContent;
+    private priceFormat?;
+    private timeFormat?;
+    private priceTicks?;
+    private timeTicks?;
+    private axisFont?;
     /** requestAnimationFrame handle coalescing high-frequency redraws (0 = none queued). */
     private raf;
     private onNeedHistory?;
@@ -44,12 +82,44 @@ export declare class Chart {
     private yZoom;
     private hover;
     private drag;
+    /** two-finger pinch baseline: finger spreads + view at gesture start. */
+    private pinch;
     private lastActive;
     constructor(container: HTMLElement, opts?: ChartOptions);
     setCandles(candles: Candle[]): this;
     setInterval(interval: number): this;
     setChartType(type: ChartType): this;
+    /** Show or hide the volume panel (the price pane reclaims the space when hidden). */
+    setShowVolume(on: boolean): this;
+    /** Toggle the logarithmic price axis (equal pixels = equal % move). */
+    setLogScale(on: boolean): this;
+    /** Set the empty-state text (e.g. "Loading…" while a feed's first page is in flight; "" hides it). */
+    setEmptyText(text: string | undefined): this;
+    /** Set the reference price for the `baseline` chart type (undefined = first visible close). */
+    setBaseline(price: number | undefined): this;
+    /** Show/configure (or hide, with `false`) the volume-by-price histogram. */
+    setVolumeProfile(config: ChartOptions["volumeProfile"]): this;
+    /** Style the axes: fill-vs-tight candle spacing, custom price/time label formatters,
+     *  tick counts, and the label font. Only the provided keys change. */
+    setAxis(opts: AxisOptions): this;
     setIndicators(indicators: Indicator[]): this;
+    /** Set the oscillator sub-panes (RSI / MACD) drawn below the volume panel. */
+    setOscillators(oscillators: Oscillator[]): this;
+    /** Arm a drawing tool ("trendline" / "hline"), or "none" for pan/zoom + select/move.
+     *  Drawing tools are one-shot: after one drawing the mode auto-resets to "none". */
+    setDrawMode(mode: DrawMode): this;
+    /** Replace all drawings (does not fire onDrawingsChange). */
+    setDrawings(drawings: Drawing[]): this;
+    /** Current drawings (a copy). */
+    getDrawings(): Drawing[];
+    /** Remove a drawing by id. */
+    removeDrawing(id: string): this;
+    /** Remove the currently selected drawing, if any. */
+    deleteSelected(): this;
+    /** Remove all drawings. */
+    clearDrawings(): this;
+    private emitDrawings;
+    private exitDrawMode;
     /** Register a callback fired when the user pans/zooms near the start of loaded data
      *  (so a feed can lazily load older candles). See connectFeed. */
     setNeedHistory(cb: (() => void) | undefined): this;
@@ -60,22 +130,53 @@ export declare class Chart {
     private get volH();
     private get plotW();
     private measure;
+    /** Largest pan offset that still fills the window — pins the OLDEST candle to the left
+     *  edge instead of letting a left-drag expose empty space past the start of the data.
+     *  (When a feed is attached, reaching this edge trips the older-history load, so the
+     *  data deepens and this max grows; without one, the pan simply stops here.) */
+    private maxOffset;
+    /** Most-negative offset — how far the view may scroll PAST the newest candle into the
+     *  future (empty space on the right), so the user can pull the current price toward the
+     *  centre. Capped at half the visible window. */
+    private minOffset;
     private clampView;
+    /** Assemble the {@link RenderInput} from current state — shared by render() and projection(). */
+    private buildInput;
+    /** Pixel↔data projection for the current frame (null when there are no candles). */
+    private projection;
     private render;
     /** Coalesce high-frequency redraws (drag/hover/wheel) into one per animation frame. */
     private scheduleRender;
     /** Recompute indicator value-series once when data or config changes (not per frame). */
     private recomputeOverlays;
-    /** When the view nears the start of loaded data, ask the feed for older candles
-     *  (once per data length, so it stops at the end of history). */
+    /** Recompute the price-series candles (Heikin-Ashi transform) on data/type change, so the
+     *  O(n) pass doesn't run on every redraw or projection lookup. */
+    private recomputePriceCandles;
+    /** When the view nears the start of loaded data, ask the feed for older candles. Fires
+     *  at most once per data length, so it advances page-by-page and stops at the end of
+     *  history. The trigger leads the left edge by ~one viewport (see {@link needsHistory}),
+     *  so zooming out keeps loading deeper data rather than stalling at the oldest candle. */
     private maybeRequestHistory;
     private region;
     private readonly onWheel;
+    /** Pan the time axis by a horizontal pixel delta (wheel/trackpad). Scrolling right
+     *  (`dx > 0`) moves toward newer candles; scrolling left walks back into history. */
+    private panByPixels;
     /** Zoom the time axis by factor `f`, keeping the candle under `cursorX` anchored. */
     private zoomTimeAt;
+    /** Topmost drawing under the pointer (within tolerance), or null. */
+    private hitTest;
     private readonly onDown;
     private readonly onMove;
+    /** Translate the dragged drawing by the pointer's data-space delta from the grab anchor. */
+    private applyDrawingDrag;
+    /** Apply an in-progress drag (pan or axis-zoom) from the current pointer position.
+     *  Shared by mouse-move and single-finger touch-move. Returns true if a drag is active. */
+    private applyDrag;
     private readonly onUp;
     private readonly onLeave;
     private readonly onDouble;
+    private readonly onTouchStart;
+    private readonly onTouchMove;
+    private readonly onTouchEnd;
 }