openalgo-charts 1.2.0 → 1.3.0

package/README.md

@@ -4,12 +4,12 @@
 
 **A from-scratch, dependency-free HTML5-canvas charting engine for OpenAlgo.**
 
-Professional interactive charts, indicators, drawing tools, order flow, and on-chart trading — six lazy-loaded tiers, zero runtime dependencies, ~37 KB Brotli for the base engine.
+Professional interactive charts, indicators, drawing tools, order flow, market replay, and on-chart trading. Six lazy-loaded tiers, zero runtime dependencies, ~49 KB Brotli for the base engine.
 
 [![npm version](https://img.shields.io/npm/v/openalgo-charts.svg?color=cb3837&label=npm)](https://www.npmjs.com/package/openalgo-charts)
 [![license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
-[![bundle](https://img.shields.io/badge/brotli-37%20KB%20base%20%C2%B7%2088%20KB%20all%20tiers-brightgreen.svg)](#size-budget)
-[![tests](https://img.shields.io/badge/tests-1001%20passing-brightgreen.svg)](#develop)
+[![bundle](https://img.shields.io/badge/brotli-49%20KB%20base%20%C2%B7%20106%20KB%20all%20tiers-brightgreen.svg)](#size-budget)
+[![tests](https://img.shields.io/badge/tests-1543%20passing-brightgreen.svg)](#develop)
 [![dependencies](https://img.shields.io/badge/runtime%20deps-0-brightgreen.svg)](#principles)
 
 [**Documentation**](https://marketcalls.github.io/openalgo-charts/)  ·  [**Live examples**](https://marketcalls.github.io/openalgo-charts/examples)  ·  [**Getting started**](./docs/getting-started.md)  ·  [**Architecture**](./ARCHITECTURE.md)
@@ -60,14 +60,14 @@ Import only what you use. Each tier is a separate bundle that registers into the
 
 | Import | Contents | Brotli |
 |---|---|---|
-| `openalgo-charts` | Engine, 13 chart types, panes & scales, primitives, registries, chart state, trading overlay, OpenAlgo feeds | 37.0 KB |
-| `openalgo-charts/indicators` | 91 built-in indicators + the Tier-2 (external-data) contract | 24.7 KB |
+| `openalgo-charts` | Engine, 13 chart types, panes & scales, primitives, registries, chart state, trading overlay, OpenAlgo feeds | 49.4 KB |
+| `openalgo-charts/indicators` | 91 built-in indicators + the Tier-2 (external-data) contract | 24.9 KB |
 | `openalgo-charts/draw` | 43 drawing tools + a headless drawing controller | 11.7 KB |
 | `openalgo-charts/transform` | Heikin Ashi, Renko, Range bars, Line Break, Point & Figure, Kagi | 2.7 KB |
-| `openalgo-charts/profile` | Volume Profile, Market Profile (TPO), Footprint, order flow | 10.1 KB |
+| `openalgo-charts/profile` | Volume Profile, Market Profile (TPO), Footprint, order flow | 10.7 KB |
 | `openalgo-charts/trade` | Order / position / bracket tools + DOM ladder | 6.6 KB |
 
-Everything together is **88.2 KB Brotli**. Figures are the measured `size-limit` output; the trade tier is a delta over the base, which is why base + trade (43.6 KB) is less than their listed sum.
+Everything together is **105.9 KB Brotli**. Figures are the measured `size-limit` output; the trade tier is a delta over the base, which is why base + trade (56.0 KB) is less than their listed sum.
 
 ## What's built
 
@@ -101,8 +101,61 @@ draw.setTool('trend-line');   // the next two clicks place it
 
 Headless by design — no toolbar, no dialogs. Placement with live preview, selection, whole-shape and per-anchor dragging, magnet snap to O/H/L/C, undo/redo (a drag is one step), and persistence. Anchors are `{ time, price }`, never pixels, so they survive zoom and resolve inside collapsed session gaps and past the last bar.
 
-### Panes & legends
-Draggable pane dividers, move / maximize / remove, and pane legends showing one reading per plot in that plot's own colour, with inline show-hide / settings / move / delete controls revealed on hover.
+### Panes, scales & legends
+Draggable pane dividers, move / maximize / remove, and pane legends showing one reading per plot in that plot's own colour, with inline show-hide / settings / move / delete controls revealed on hover. The status line is switchable field by field (logo, title, market status, OHLC, bar change, volume, last day change, last value) over a host-supplied data source.
+
+Each pane carries a right, a left and a hidden overlay price scale, in four modes: linear, logarithmic, and the two rebasing modes **percentage** (`+3.42%`) and **indexed-to-100** (`103.42`), which quote every price against a baseline taken from the first visible bar, so panning re-bases the axis.
+
+### Reference levels and axis chrome
+
+```ts
+import { PriceLevels } from 'openalgo-charts';
+
+const levels = new PriceLevels({
+  levels: { previousClose: { line: true, label: true }, sessionHigh: { line: true, label: false } },
+});
+chart.addPrimitive(levels, 0);
+levels.available('bid');   // false until a quote is fed: render that control disabled, not hidden
+```
+
+One primitive over ten levels: previous close, session high and low, last price, the four extended-hours opens and closes, and bid and ask. Each level's line across the plot and its tag on the price axis are two flags in the same options group, so they cannot drift apart. The session comes from the gaps in the bars rather than from a calendar midnight, and the session in view follows the viewport's right edge, so scrolling back through history moves the previous close back with it. A level with no data is `null`, never `0`: nothing draws at zero, and `available(kind)` is the signal to render that control disabled with its state visible instead of hiding it.
+
+Axis chrome is off until a chart asks for it. `createChart(el, { axisChrome: { sessionClock: true, barCountdown: true } })` puts a live clock in the corner where the two axis strips meet, in the chart's own timezone with the zone's UTC offset under it, and a countdown to the current bar's close as a second row inside the last-price tag, with the interval read back off the bars so a timeframe switch is followed. Tick labels that the last-price tag would cover are dropped rather than drawn through it, on a priority order that puts the crosshair above the last price, above a price line, above a session level.
+
+### Timezones
+
+```ts
+const chart = createChart(el, { timezone: 'America/New_York' });
+chart.setTimezone('Europe/London');    // relabels and recomputes on the next frame
+```
+
+An IANA name, never a fixed offset, so daylight saving is followed rather than approximated. The zone drives the time axis (including which ticks escalate to a day, month or year label), the crosshair time tag, and every calendar-anchored study (VWAP and TWAP anchors, CPR's weekly and monthly frames, the month a Seasonality bar counts in), and it rides along in `getState()`. Profile session windows carry their own zone, so `TRADING_HOURS['us-regular']` reads as 09:30-16:00 `America/New_York` whatever the chart is displayed in. The default is `Asia/Kolkata` on the same fixed-offset arithmetic it always used, so a chart that names no zone labels and computes exactly as before.
+
+### Market replay
+
+```ts
+import { ReplayController } from 'openalgo-charts';
+
+const replay = new ReplayController(chart, { bars, startIndex: 200, barMs: 500 });
+replay.play({ speed: 2 });          // emits replay:frame per bar
+```
+
+Headless: the controller owns the playhead and ships no DOM, so the transport bar is yours to draw from `state()` and the `replay:*` events. Each step hands the series a prefix of the session through the ordinary `setData` path, which is what makes every indicator, level, fill, marker and legend row reconstruct itself as it stood at that bar. `stop()` puts the full history and the exact viewport back.
+
+### Symbol comparison
+
+```ts
+import { addComparison } from 'openalgo-charts';
+
+const bn = addComparison(chart, { symbol: 'BANKNIFTY', bars });
+```
+
+The comparison rides the pane's hidden overlay scale in its own real prices, the pane rebases to percentage (or indexed-to-100), and the overlay's range is mirrored from the primary's, so equal percentage moves land on equal pixels instead of each line filling the pane. Alignment is by timestamp: a comparison print with no primary bar is dropped, a primary bar with no print becomes a gap.
+
+### Settings & context menu
+`chartSettingsSchema(chart)` describes a full settings dialog as tabs of controls, in the same descriptor vocabulary the indicator settings form already uses; `readChartSettings` and `applyChartSettings` are its round trip over flat, JSON-safe keys. Five tabs (Price, Readout, Axes, Appearance, Trading), and a bullish/bearish pair is **one** `colorPair` row carrying its switch and both swatches instead of two stacked rows. Grid, crosshair, scale text, plot margins, status-line fields, the chart timezone, trading colours and the primary series' own style are all real options behind it, so no control in the schema is inert.
+
+`chart.on('contextmenu', ...)` reports the pane, price, time, logical index and what sits under the pointer: a drawing, an indicator instance, a legend, a primitive, a series, a price scale (with the side and the scale id it names), the time scale, or empty plot. For a menu raised on a price axis, `chart.priceAxisState(pane, scaleId)` reads back every item that menu draws (auto-fit, invert, scale mode, price-per-bar lock, whether the axis is movable) and `setPriceAxisOptions`, `setPriceAxisAutoFit`, `setPriceAxisLockRatio` and `movePriceAxis` act on it, so no row is ticked with nothing behind it.
 
 ### Trading
 Order, position, and bracket lines with live P&L, one-click and drag-to-modify, OCO, validation, an order state machine, analyzer (sandbox) mode, and a depth-of-market ladder (5 to 200 levels).
@@ -111,10 +164,10 @@ Order, position, and bracket lines with live P&L, one-click and drag-to-modi
 Volume Profile, Market Profile (TPO), Footprint, and cumulative delta.
 
 ### State
-`chart.getState()` / `chart.restoreState()` capture the viewport, grid, panes, price scales, indicator instances, and drawings as one JSON payload — saved layouts and templates with no extra storage plumbing.
+`chart.getState()` / `chart.restoreState()` capture the viewport, grid, panes, price scales, indicator instances, drawings, and the whole settings block (canvas, status line, trading colours, event filters) as one JSON payload: saved layouts and templates with no extra storage plumbing.
 
 ### Data
-OpenAlgo REST history + WebSocket ticks with auto-reconnect and resubscribe, live candle aggregation, tick/volume bars, a unified `chart.on(...)` event bus, markers and signals, earnings/dividend/expiry event markers, and custom price/time formatters.
+OpenAlgo REST history + WebSocket ticks with auto-reconnect and resubscribe, live candle aggregation, tick/volume bars, a unified `chart.on(...)` event bus, markers and signals, earnings/dividend/expiry event markers, an IANA chart timezone, and custom price/time formatters.
 
 ## Size budget
 
@@ -122,13 +175,13 @@ Enforced in CI by [`size-limit`](./.size-limit.json) — nothing is excluded, be
 
 | Bundle | Limit | Actual |
 |---|---|---|
-| Base engine | 40 KB | 37.04 KB |
-| Base + trade | 47 KB | 43.62 KB |
-| Indicators tier | 21 KB | 20.09 KB |
+| Base engine | 55 KB | 49.37 KB |
+| Base + trade | 62 KB | 55.95 KB |
+| Indicators tier | 27 KB | 24.88 KB |
 | Draw tier | 14 KB | 11.73 KB |
 | Transform tier | 5 KB | 2.66 KB |
-| Profile tier | 11 KB | 10.12 KB |
-| **Everything** | **90 KB** | **88.21 KB** |
+| Profile tier | 11 KB | 10.66 KB |
+| **Everything** | **120 KB** | **105.88 KB** |
 
 ## Documentation
 
@@ -151,7 +204,7 @@ Teach your AI coding assistant this library:
 npx skills add https://github.com/marketcalls/openalgo-charts
 ```
 
-Installs six skills from [`.github/skills/`](./.github/skills) - a reference hub with 18 deep-dive files covering the whole API surface and its foot-guns, plus task skills for scaffolding a chart, adding indicators, building a terminal, writing a plugin, and debugging. Works with Claude Code, Cursor, Codex, Copilot, Gemini CLI and the rest of the `skills` CLI's supported agents.
+Installs six skills from [`.github/skills/`](./.github/skills) - a reference hub with 20 deep-dive files covering the whole API surface and its foot-guns, plus task skills for scaffolding a chart, adding indicators, building a terminal, writing a plugin, and debugging. Works with Claude Code, Cursor, Codex, Copilot, Gemini CLI and the rest of the `skills` CLI's supported agents.
 
 ## Examples
 
@@ -168,7 +221,7 @@ cd examples/yfinance && pip install -r requirements.txt && python server.py
 ```bash
 npm install        # install dev toolchain
 npm run typecheck  # strict TypeScript check
-npm test           # unit tests (vitest) - 1001 across 61 files
+npm test           # unit tests (vitest) - 1543 across 81 files
 npm run build      # Rollup -> dist/ (minified ESM per tier + types)
 npm run size       # size-limit (Brotli) against the budget
 npm run e2e        # Playwright Chromium smoke tests
@@ -185,14 +238,14 @@ npm run verify     # typecheck + test + build + size
 
 ## Status & limitations
 
-Version **1.1.0**. All engine build phases are implemented with 1001 unit tests across 61 files.
+Version **1.3.0**. All engine build phases are implemented with 1558 unit tests across 84 files.
 
 Known gaps, stated plainly:
 
 - **Footprint and order flow need trade-by-trade data classified bid/ask.** OpenAlgo does not store this by default, so it is live-session-only unless you add a tick recorder — `FootprintAggregator` is the live path. See [`ARCHITECTURE.md`](./ARCHITECTURE.md) §6A.
 - **Only `Footprint` is theme-aware among the profile primitives.** `VolumeProfile`, `MarketProfile` and `HorizontalProfile` never read `rc.theme`; their defaults are dark-tuned, so a light theme needs explicit colours. `HorizontalProfile` also hardcodes its POC / value-area line colours and has no `setOptions`.
 - The OpenAlgo **WS/trade adapter wire schemas** ship with injectable transports and offline tests, but the exact field names should be verified against your running OpenAlgo build.
-- Price-scale **`percentage`** and **`indexed-to-100`** modes are not implemented. (Hidden overlay scales *are* — add a series with `priceScaleId: ''`.)
+- **A pane has exactly one hidden overlay scale**, so every symbol comparison on a pane shares one baseline. That is right for a single comparison, the common case, but a second one on the same pane is quoted against the first instrument's price; put further instruments on their own pane with `paneIndex` until the overlay scales are keyed.
 - An optional **DOM chrome package** (toolbar, dialogs, command palette, objects panel) is the next planned piece; today that UI lives in the examples.
 
 See [`ARCHITECTURE.md`](./ARCHITECTURE.md) §13a for the full deferred list.