acttrader-charts 1.3.0-beta.3 → 1.3.0-beta.30

package/README.md

@@ -58,12 +58,15 @@ chart.on('durationChange', ({ duration, timeframe }) => {
 ```ts
 const chart = new ChartEngine({
     container,
-    dataLoader: async ({ start, end, interval }) => {
-        const res = await fetch(`/api/bars?from=${start.getTime()}&to=${end.getTime()}&tf=${interval}`);
+    dataLoader: async ({ start, end, interval, priceSource }) => {
+        // `priceSource` ('bid' | 'ask' | 'ltp') is the candle source the chart is showing —
+        // pass it to your history API so the bars match (dealing feeds: LTP vs BID candles).
+        const res = await fetch(`/api/bars?from=${start.getTime()}&to=${end.getTime()}&tf=${interval}&source=${priceSource}`);
         return res.json(); // OHLCVBar[]
     },
 });
-// No manual loadData() needed — the engine calls dataLoader on start and on timeframe/duration changes.
+// No manual loadData() needed — the engine calls dataLoader on start, on timeframe/duration
+// changes, and (unless `reloadOnPriceSourceChange: false`) whenever the price source changes.
 ```
 
 If the first fetch returns fewer than `minInitialBars` (default `10`), the engine automatically widens the lookback window and calls `dataLoader` again — up to the `maxLookbackMs` ceiling (default 365 days). This keeps the chart useful on weekends, holidays, or for instruments that just listed. If retries still yield zero bars, the engine shows a **"No data available"** overlay (customise the text via `labels.chart.noData`).
@@ -152,6 +155,9 @@ const dealingChart = new ChartEngine({
     container,
     // "Show chart by" toggle: 'ltp' | 'ask' | 'bid' (candle close/high/low source)
     tickClosePriceSource: 'ltp',
+    // Header dropdown so the user can switch the source on the chart itself
+    // (rendered next to the timeframe dropdown; omit to hide):
+    priceSourceSelector: ['ltp', 'bid'],
     // Chart line checkboxes — each price line is independent:
     showAskLine: true,   // Show AskLine
     showBidLine: true,   // Show BidLine
@@ -161,8 +167,15 @@ const dealingChart = new ChartEngine({
 dealingChart.setShowAskLine(false);   // hide the ask line
 dealingChart.setShowBidLine(true);    // show the bid line
 dealingChart.setShowLtpPrice(true);   // show the LTP line
+// Switch the candle source programmatically (e.g. from a trade-settings page);
+// the header dropdown label follows automatically:
+dealingChart.setTickClosePriceSource('bid');
+// A user pick from the dropdown emits `priceSourceChange` — persist it:
+dealingChart.on('priceSourceChange', ({ source }) => saveTradeSetting(source));
 ```
 
+**History follows the source.** Switching the source (dropdown pick or `setTickClosePriceSource()`) does not just change how live ticks extend the last candle — the engine re-runs your `dataLoader` with `params.priceSource` set to the new value and replaces the loaded bars, keeping the visible time window. Forward `priceSource` to your charting API (e.g. as a query parameter) so it returns LTP-built or BID-built candles accordingly; without it the API keeps serving the old source and the chart cannot change. Set `reloadOnPriceSourceChange: false` to opt out of the re-fetch.
+
 ### Compare symbols
 
 Overlay one or more comparison instruments on the main chart, normalized to
@@ -249,6 +262,12 @@ chart.setLevels(
 );
 ```
 
+**Trailing stop:** a trade with a trail always has a working stop, so keep passing its price as `stopLossPrice` and set `stopLossTrailing: true`. The line renders as usual but its pill reads **TSL** instead of SL, and it is read-only on the chart — no drag handle, no × — because the trail is a pip distance edited from the host's own panel. The level's TP stays fully editable.
+
+```ts
+{ label: 'POS-2', price: 1.0850, side: 'buy', lots: 1, stopLossPrice: 1.0800, stopLossTrailing: true }
+```
+
 **Bracket orders via `ToClose`** — link a separate SL/TP pending order to a parent level:
 
 ```ts
@@ -333,13 +352,15 @@ When `enableTrading` is on and live BID/ASK data is streaming, hovering / activa
 
 ### Horizontal (time-axis) order-line dragging
 
-Opt-in via `features.orderLineTimeDrag` (off by default; enable it per broker from the host app — e.g. only for Hankotrade users). When enabled, any level flagged `timeDraggable: true` can have its **info-box badge** dragged left/right to re-anchor the order to a different candle. The **price line stays locked** — only the time anchor moves. Grab the badge for horizontal drag (`grab` / `grabbing` cursor); the price line itself still drags vertically as before.
+Opt-in via `features.orderLineTimeDrag` (off by default; enable it per broker from the host app — e.g. only for Hankotrade users). When enabled, any level flagged `timeDraggable: true` — open positions **and pending orders** alike — can have its **info-box badge** dragged left/right to re-anchor the order to a different candle. During a horizontal drag the **price line stays locked** — only the time anchor moves. A fixed-price position's badge grabs horizontally at once (`grab` / `grabbing` cursor). A pending order (or entry-editable position) keeps its price drag: its badge shows a `move` cursor and the **first movement decides the axis** — sideways moves the time anchor, up/down moves the entry price exactly as before, and the full-width line still drags vertically.
 
 ```ts
 const chart = new ChartEngine({
   container,
   features: { orderLineTimeDrag: true }, // host enables this only for the gated broker
   orderLineDragSnap: true,               // snap to nearest candle on release (default)
+  orderLineAnchorPersistence: true,      // remember dropped positions in localStorage (default)
+  orderLineDefaultAnchor: 'center',      // un-dragged badges start mid-chart (default: 'timestamp')
 });
 
 chart.setLevels(
@@ -354,13 +375,101 @@ chart.on('orderLineMoved', ({ label, fromTimestamp, toTimestamp, data }) => {
 ```
 
 - **Bounds:** the badge is clamped to the visible viewport — it can't be dragged past the left/right edge.
+- **Pending orders:** flag them `timeDraggable: true` too. The pill follows the drag direction — a sideways pull re-anchors the order in time (price locked, `orderLineMoved` on release), a vertical pull moves the entry price and its SL/TP brackets as usual (`tradeLevelDrag` / `tradeLevelEdit`). The axis is fixed after about 6px of movement and does not change mid-drag. Touch follows the same rule, and a tap that never moves still opens the edit form.
 - **Snap:** controlled by `orderLineDragSnap` (default `true`); set `false` to keep the exact released time.
 - **Escape / touch-cancel:** reverts the badge to its starting candle without emitting `orderLineMoved`.
 - **Stays put after release:** the chart holds the dropped position across `setLevels` refreshes until you echo the new `timestamp` back (auto-released on match).
+- **Survives reloads:** with `orderLineAnchorPersistence` (default `true`) the dropped candle time is saved in `localStorage` under `finchart.orderLineTimeAnchors`, keyed by the level's label. After a page reload the badge returns to that candle even if your `setLevels()` payload still carries the order's original `timestamp` — the persisted anchor wins until the badge is dragged again. Capped at the 500 most recently dragged labels; set `false` if you persist anchors server-side instead.
+- **New orders at the center:** with `orderLineDefaultAnchor: 'center'` a `timeDraggable` level that has never been dragged ignores its `timestamp` and renders mid-chart — so a freshly filled market order arrives in the middle of the chart rather than pinned to the latest candle at the right edge. Levels that are not `timeDraggable` still honor `timestamp`. Default `'timestamp'` keeps the previous behavior.
 - A level **without** `timestamp` renders exactly as before (badge centered), so existing consumers are unaffected.
 
 ---
 
+### Trade action bar — `features.tradeActionBar`
+
+With the flag on, the floating trade button opens a segmented bar at the clicked
+price instead of the two-row Buy/Sell popup:
+
+```
+Alert | Pending | SL | TP | TSL | ×
+```
+
+- No price readout — the axis already shows the price at that point.
+- **Alert** calls `onAddAlert(price)`. The chip is only rendered when that callback is set. The same callback also backs the **Alert** entry of the advanced header's ⋯ menu (`headerOverflowMenu`), which passes the current market price (live ask, else bid, else last close) so the host opens the same form.
+- **Pending** opens a sub-menu just above the bar — an `Above · 1.17586` / `Below · …`
+  header, then the two orders that make sense at that price (`Buy Limit` / `Sell Stop`
+  below the market, `Sell Limit` / `Buy Stop` above), each with its `@ price`. Picking a
+  row creates the draft order exactly as before and closes both.
+- **SL / TP / TSL** emit `bulkLevelsRequested` with `{ kind, price }` and close the
+  bar — the host opens its Bulk Levels dialog pre-focused on that kind. The chart
+  never calls a broker. The chips grey out, with a tooltip saying why, when the
+  symbol has no open positions or has buys and sells open at once — one stop or
+  target price cannot sit on the right side of the market for both directions.
+- **×**, a click elsewhere, Escape, TFC off and `dismissAllUI()` all close it.
+
+Chip labels and the × tooltip live under `labels.trade` (`actionAlert`, `actionPending`,
+`actionSl`, `actionTp`, `actionTsl`, `actionCloseTitle`).
+
+### On-chart P/L pill — `features.pnlPill`
+
+A floating summary of the open positions on the chart, for the trader who wants
+the total without opening the positions panel:
+
+```
+⋮⋮  3 POS  +72.65 USD  |  ◎  ✕
+```
+
+- **`3 POS`** — how many position levels are on the chart. Pending orders,
+  position-style entry orders (`entryPriceEditable`) and an unconfirmed draft
+  are not counted.
+- **`+72.65 USD`** — the sum of the numeric `pnl` those levels carry, i.e. the
+  `pnlKey` column you pass to `setLevels`. The chart computes no money itself;
+  while no position has a `pnl` yet the pill shows `—`. Profit is drawn in the
+  buy colour, loss in the sell colour.
+- **Click the body** (the grip, the count or the amount) to fan every position
+  badge out on the chart — clustered levels expand, and TFC is switched on if it
+  was off — with an accent ring on the pill while they are shown. Click again to
+  collapse.
+- **◎** (the same target glyph as the Bulk Levels dialog header) emits
+  `bulkLevelsRequested` with `source: 'pill'` and a `null` price, so your Bulk Levels
+  dialog opens pre-scoped to every open position on the symbol. Tooltip:
+  "Set SL · TP · TSL on all N {symbol} positions". Greyed out while buys and sells are
+  both open ("Bulk levels need all N {symbol} positions in one direction").
+- **✕** (amber) emits `pnlPillCloseAll` with every counted position. Your app
+  confirms and closes them; the chart never calls a broker.
+
+The pill sits top-right of the plot, clear of the price axis. Drag it anywhere
+inside the plot; double-click puts it back. It hides itself while the chart has
+no positions and follows the chart theme. Every element sits on one shared row
+height, and the grip and both buttons have fixed widths, so a long or negative
+amount never shifts or squeezes them.
+
+With the feature on, the header (advanced toolbar and default top bar) also gets a
+**P/L** switch — wallet icon, `P/L`, the same 24px `rounded-sm` button tinted while the
+pill is shown. It hides or shows the pill on the user's say-so, wins over the position
+count, and emits `pnlPillToggle` so you can persist the choice; `pnlPill.visible` seeds
+it and `setPnlPillVisible()` drives it from code.
+
+```ts
+const chart = new ChartEngine({
+    container,
+    features: { pnlPill: true },
+    pnlPill:  { currency: 'USD' },   // → "+72.65 USD"; or format: (pnl) => myMoney(pnl)
+});
+
+chart.setLevels(positions, 'TradeID', 'Price', 'position', 'pnl', 'pnlText');
+
+chart.on('pnlPillCloseAll', async ({ count, pnl, data }) => {
+    if (!(await confirmDialog(`Close all ${count} positions?`))) return;
+    for (const row of data) closeTrade(row);
+});
+```
+
+Labels live under `labels.pnlPill`: `positionsAbbrev` (`'POS'`), `showPositionsTitle`,
+`hidePositionsTitle`, `bulkLevelsTitle`, `closeAllTitle` — titles may
+use `{symbol}` and `{count}`. The maths behind the pill is exported as
+`summarisePositionLevels(levels, draftLabel?)` and `formatPnlPillValue(pnl, currency?)`.
+
 ## Default Configuration
 
 ### `ChartConfig`
@@ -375,9 +484,13 @@ chart.on('orderLineMoved', ({ label, fromTimestamp, toTimestamp, data }) => {
 | `hideHeader` | | `false` | Hide only the chart header (TopBar / AdvancedToolbar / CompactToolbar, per `headerLayout`). Bottom bar, left drawing tools, and on-canvas overlays remain on their own flags. Drive the chart from your own UI via `setTimeframe(tf)`, `setSeries(type)`, `addIndicatorByName(name)`, `removeIndicator(name)` |
 | `showDrawingTools` | | `true` | Show drawing toolbar and pencil button |
 | `showFullscreenButton` | | `true` | Show the fullscreen toggle button in the top bar. Set to `false` to hide it entirely. Mobile wrappers (Android / iOS) default this to `false` |
-| `timeframe` | | `"1D"` | Initial timeframe |
+| `timeframe` | | `"1D"` | Initial timeframe. Values: `1m` `3m` `4m` `5m` `10m` `15m` `30m` `1h` `2h` `4h` `8h` `1D` `1W` `1M`; `3m` / `4m` / `10m` / `30m` are requested from `dataLoader` as `3min` / `4min` / `10min` / `30min`. If your API lacks them, point `aggregateFrom` at a finer interval it does serve, e.g. `{ '3m': '1m', '4m': '1m', '10m': '5m', '30m': '15m' }` — the chart merges the candles |
+| `timeframes` | | classic set | Timeframes offered in the header, in order: the advanced row's pills, the classic dropdown, and the rest of the reference header's ⌄ menu after its six fixed pills. Omit to keep `1m 5m 15m 1h 4h 1D 1W` (row) / `… 30m 2h 8h 1M` (dropdown, ⌄), so the newer minute timeframes only appear for hosts that list them |
 | `duration` | | — | Initial active duration button |
 | `symbol` | | — | Symbol name shown in the top bar |
+| `features` | | `{}` | Opt-in feature gates. See [Feature flags](#feature-flags) |
+| `instrument` | | — | Contract specs for `symbol` — pip size, contract size, money conversion. See [`InstrumentSpec`](#instrumentspec) |
+| `account` | | — | Account equity and per-trade risk used to size the position tools. See [`AccountSpec`](#accountspec) |
 | `isins` | | — | Symbol list for the picker modal |
 | `onIsinSelect` | | — | Called when user picks a symbol from the picker modal |
 | `padding` | | `{top:8,right:0,bottom:0,left:0}` | Canvas padding (px) |
@@ -394,7 +507,7 @@ chart.on('orderLineMoved', ({ label, fromTimestamp, toTimestamp, data }) => {
 | `momentumMaxVelocity` | | `6.0` | Max launch velocity (px/ms) — caps hard-flick speed |
 | `targetCandleWidth` | | `10` | Target px width per candle for auto-calculating initial bar count |
 | `durationTimeframeMap` | | *(see below)* | Override duration → timeframe pairings |
-| `dataLoader` | | — | `(params) => Promise<OHLCVBar[]>` auto-called on load / change |
+| `dataLoader` | | — | `({ start, end, interval, priceSource }) => Promise<OHLCVBar[]>` auto-called on load, timeframe/duration change, and price-source change. `priceSource` is the candle source to fetch (`'bid'`, `'ask'` or `'ltp'`) |
 | `compareDataLoader` | | — | `({ symbol, start, end, interval }) => Promise<OHLCVBar[]>` — fetches bars for a compare symbol. Set this to enable the library-owned Compare flow. |
 | `initialCompares` | | — | Symbols to auto-add as compares once the initial primary range is loaded |
 | `maxCompares` | | `8` | Maximum concurrent compare symbols. Adding beyond emits `compareError` |
@@ -403,6 +516,8 @@ chart.on('orderLineMoved', ({ label, fromTimestamp, toTimestamp, data }) => {
 | `labels` | | `DEFAULT_LABELS` | Deep-partial string overrides for i18n/translation |
 | `tickClosePriceSource` | | `"bid"` | Which price drives live tick close/high/low: `"bid"`, `"ask"`, or `"ltp"` (build candles from the last traded price — exchange/dealing feeds; ticks without a valid LTP fall back to the bid) |
 | `showLtpPrice` | | unset | Show the LTP marker (dashed price line + axis tag). Unset: shown only in `"ltp"` mode. `true`: always shown when the feed supplies an LTP. `false`: hidden even in `"ltp"` mode (candles still build from the LTP). Toggle at runtime with `chart.setShowLtpPrice(show)` |
+| `priceSourceSelector` | | unset | Show a price-source dropdown in the chart header listing the given sources, e.g. `["ltp", "bid"]` (dealing feeds). A user pick switches the candle source, re-fetches history via `dataLoader` (see `reloadOnPriceSourceChange`) and emits `priceSourceChange`; sync it programmatically with `chart.setTickClosePriceSource(source)`. Hidden when unset/empty. Default header layout only |
+| `reloadOnPriceSourceChange` | | `true` | Re-run `dataLoader` with the new `params.priceSource` whenever the candle price source changes, so historical candles are rebuilt from the selected price (LTP vs BID) and not only the live one. The visible time window is preserved. Set `false` to keep only live ticks following the new source |
 | `showBidAskLines` | | `false` | **Deprecated** — show both bid and ask as dashed lines during a live stream. Prefer the per-line checks `showAskLine` / `showBidLine`, which override it when set |
 | `showAskLine` | | unset | Show the Ask price line (dashed line + axis tag) independently. Unset: legacy `showBidAskLines` behavior. Toggle at runtime with `chart.setShowAskLine(show)` |
 | `showBidLine` | | unset | Show the Bid price line (dashed line + axis tag) independently. Unset: legacy `showBidAskLines` behavior. Toggle at runtime with `chart.setShowBidLine(show)` |
@@ -412,31 +527,150 @@ chart.on('orderLineMoved', ({ label, fromTimestamp, toTimestamp, data }) => {
 | `showPriceAxisCountdown` | | `false` | Show candle countdown timer on the right price axis, just below the live price tag. Honours `candleCountdownTimeframes`. Toggleable from the Settings dialog (Appearance tab). |
 | `maxSubPanes` | | `3` | Max simultaneous oscillator sub-panes |
 | `tradeDisplayFilter` | | `"all"` | Which TFC levels are visible: `"all"` · `"positions"` · `"orders"` · `"none"` |
+| `pnlPill` | | — | `{ currency?, format?, visible? }` for the on-chart P/L pill — currency code appended to the amount, or your own formatter. Only read when `features.pnlPill` is on |
 | `positionRenderStyle` | | auto | Force position render style: `"line"` or `"dot"` |
 | `hideLevelConfirmCancel` | | `false` | Hide on-canvas ✓/✗ confirm-cancel buttons for TFC level edits |
 | `deselectActiveOnOutsideClick` | | `false` | When `true`, clicking/tapping anywhere outside a selected trade level dismisses it (reverting any pending edits, mirroring ✗ Cancel). Default `false` keeps the level active so incidental clicks — price-axis resize, taps outside the QTY input — don't drop an in-progress edit. The level can still be dismissed via ✓/✗, tapping the level again, or `setLevels()` removing it |
 | `showTradeLevelsAlways` | | `false` | Always render SL/TP bracket lines + price pills, even when the parent level is not hovered or selected. The close (×) button stays hover-only so the chart isn't cluttered. Toggleable from the Settings dialog (Trading tab). Persisted in `localStorage`. |
+| `revealNewBrackets` | | `false` | When a level gains a **new** SL/TP — placed from the host's order panel, so it arrives via `setLevels()`, `updateLevelBracket()` or `updateDraftOrderBracket()` — whose price sits outside the visible price range, widen (compress) the price axis so the new line comes into view together with the candles already on screen. Animated, and the trader can drag or reset the axis afterwards as usual. A bracket dragged on the chart is visible by construction and never triggers it. Inert in compare (percent) mode |
 | `tradeLevelButtonScale` | | `1` | Multiplier for trade-level Confirm/Cancel/Edit/Close button radii and gaps. Scales visuals **and** hit/drag areas together — raise it on touch devices for larger tap targets. Clamped to `[1, 3]`. Also settable at runtime via `chart.setTradeLevelButtonScale(scale)` |
+| `tradeLevelBadgeScale` | | `1` | Shrinks the on-chart position / order tag — font, padding, grip, ✎ × buttons and their hit areas together. `0.6` is about half the default area. Clamped `[0.5, 1]` |
+| `tradeLevelBadgeAnchor` | | `"auto"` | `"left"` homes the tag at the plot's left edge like an axis label, whatever the open price or time anchor, so it never covers candles until the trader drags it. With `features.orderLineTimeDrag` the tag stays draggable along the time axis and the drop is remembered as before |
 | `tfcEnabled` | | `true` | Enable the TFC toggle button in the top bar. When `false`, TFC is completely disabled — the toggle button is hidden and all trade levels, draft orders, and the floating trade button are suppressed |
-| `features.orderLineTimeDrag` | | `false` | Enable **horizontal (time-axis) order-line dragging**. A level with `timeDraggable: true` can have its info-box badge dragged left/right to re-anchor the order to a different candle — **price stays locked**. Emits `orderLineMoved` on release. Off by default; intended to be enabled per broker (e.g. Hankotrade) by the host app |
+| `crosshairEnabled` | | `true` | Draw the mouse crosshair. `false` hides it **and** the floating "place order at this price" button that rides on its horizontal line, ignores mirrored `setCrosshair()` calls and keeps the mobile long-press crosshair from arming. Trade levels, drawings and TFC are unaffected. Runtime: `chart.setCrosshairEnabled(enabled)` |
+| `enableCrossHairHeader` | | `false` | Crosshair on/off switch in the header (advanced toolbar, default top bar, the compact per-pane strip and the mobile header): the reference `rounded-sm` button. The crosshair is on by default, so the icon starts tinted; a click hides the crosshair (and the trade button riding on it) and drops the icon to its plain state, the next click brings both back. Calls `setCrosshairEnabled()` and emits `crosshairToggle` so the host can persist the choice — see [Header crosshair switch](#header-crosshair-switch--enablecrosshairheader) |
+| `enableCrosshairToggle` | | `false` | **Deprecated** — alias of `enableCrossHairHeader`; either flag renders the switch |
+| `headerOverflowMenu` | | `false` | Advanced header only: the reference Hanko header. A 32px bar with six lowercase timeframe pills (`1m 5m 15m 1h 4h 1d`) and a ⌄ for the rest, then crosshair · P/L · Layout (grid icon) · ⋯ · fullscreen at 24px. Draw, Chart type, Indicators, Compare, Snapshot and Chart settings fold into the ⋯ menu; each keeps its behaviour. With `onAddAlert` set the menu also offers **Alert** (own group, before Snapshot) at the current market price |
+| `features.orderLineTimeDrag` | | `false` | Enable **horizontal (time-axis) order-line dragging**. A level with `timeDraggable: true` (position or pending order) can have its info-box badge dragged left/right to re-anchor the order to a different candle — **price stays locked** while dragging sideways. Pending orders keep their vertical price drag: the badge's first movement picks the axis. Emits `orderLineMoved` on release. Off by default; intended to be enabled per broker (e.g. Hankotrade) by the host app |
 | `orderLineDragSnap` | | `true` | When horizontal dragging is enabled, snap the badge to the nearest candle on release. Set `false` to keep the exact released time |
+| `orderLineAnchorPersistence` | | `true` | When horizontal dragging is enabled, remember where each badge was dropped in `localStorage` (key `finchart.orderLineTimeAnchors`, keyed by level label) so it comes back to the same candle after a reload. A persisted anchor overrides the level's `timestamp` until the badge is dragged again. Set `false` to persist anchors yourself |
+| `orderLineDefaultAnchor` | | `'timestamp'` | Where an un-dragged `timeDraggable` badge sits: `'timestamp'` = over the candle at the level's `timestamp`; `'center'` = the chart's horizontal center (ignores `timestamp`), so a new market order lands mid-chart. Non-draggable levels always honor `timestamp` |
 | `levelClusteringEnabled` | | `true` | Enable trade-level fan-out clustering; overlapping levels group into expandable badges |
 | `clusterThresholdDistance` | | `20` | Pixel proximity threshold for clustering (only when `levelClusteringEnabled` is `true`) |
 | `hideSymbolAndTick` | | `false` | Hide the symbol name and tick-activity (streaming) dot in the top-left overlay. Does **not** affect the OHLC(V) strip — use `hideOHLCV` for that |
 | `hideOHLCV` | | `false` | Hide the OHLC(V) data strip (`O: H: L: C: V:`) in the top-left overlay. Independent of `hideSymbolAndTick` — set both to `true` to hide the entire overlay |
 | `showBottomBar` | | `false` | Show the bottom duration-selector bar |
+| `features.enableScaleControls` | | `false` | Bottom-bar **Go to date**, **timezone** and **%** / **log** / **auto** cluster, left of the duration buttons. Needs `showBottomBar: true`. Off by default — see [Bottom Bar & Price Scale](#bottom-bar--price-scale) |
+| `features.enableSidePanels` | | `false` | Right-hand docked **Data Window** / **Objects** panel (232px out of the plot). Off by default; toggle at runtime with `setSidePanelVisible()` — see [Side Panels](#side-panels) |
 | `hideQtyButton` | | `false` | Hide the floating Qty input overlay on draft orders |
 | `showQuantityField` | | `false` | Render an editable QTY pill at the left of the draft order info box. Clicking the pill opens a flyout input to edit the quantity before submitting |
 | `quantityFieldConfig` | | — | Constraints for the draft order QTY field (only relevant when `showQuantityField` is `true`). Object: `{ minLots?: number, maxLots?: number }`. `minLots` also sets the initial quantity and the step value for the flyout input (default: `1`). `maxLots` caps the input (default: `100`) |
 | `tradesThresholdForHorizontalLine` | | `2` | Level count above which render auto-switches to `"dot"` mode |
 | `timezone` | | `"UTC"` | IANA timezone string for time-axis and crosshair labels. `"UTC"` (default), `"local"` (browser/device timezone), or any IANA string (`"America/New_York"`, `"Europe/London"`, etc.) |
-| `canvasColors` | | — | Per-theme canvas background color overrides (persisted from Settings dialog) |
+| `canvasColors` | | — | Per-theme colour overrides for the **canvas only** (persisted from the Settings dialog; runtime: `chart.setCanvasColors()`). The surface picks — `background`, `grid`, `axisText`, `axisBorder`, `crosshair` — repaint the chart canvas and leave the chart chrome (top/bottom/left bars, dialogs, popovers) on the theme from `themeOverrides`. Series picks (`candleUp`/`candleDown`/`wickUp`/`wickDown`/`borderUp`/`borderDown`/`volumeUp`/`volumeDown`) apply everywhere, so legends and indicator pills keep tracking them |
 | `aggregateFrom` | | — | Fetch finer-grained data and aggregate client-side per timeframe |
 | `onOrderSubmit` | | — | Called when user submits a trade via the floating button |
 | `onLevelEdit` | | — | Called when user confirms a TFC level edit |
 | `onLotsChange` | | — | Called when user changes qty on a draft order |
 | `onLevelDragEnd` | | — | *(deprecated — use `onLevelEdit`)* |
 
+### `InstrumentSpec`
+
+The chart reads prices, never contract specs — so a tool that reports a distance
+in **pips**, or converts one to money, has to be told how. Pass `instrument` at
+construction and swap it with `setInstrument()` whenever the symbol changes.
+
+```ts
+const chart = new ChartEngine({
+    container,
+    symbol: 'EURUSD',
+    instrument: {
+        pipSize:        0.0001,   // 0.01 for JPY crosses
+        contractSize:   100_000,  // units per lot
+        valuePerPoint:  1,        // account-currency value of one price unit per unit
+        currencySymbol: '$',
+    },
+});
+
+chart.setSymbol('USDJPY').setInstrument({ pipSize: 0.01, contractSize: 100_000 });
+```
+
+| Field | Default | Description |
+|---|---|---|
+| `pipSize` | inferred | Price distance counted as one pip |
+| `contractSize` | `1` | Units per lot (`100` for XAUUSD, `100000` for most FX pairs) |
+| `valuePerPoint` | `1` | Account-currency value of one price unit per contract unit |
+| `currencySymbol` | `'$'` | Prefixed to money figures |
+
+**Every field is optional and the whole block can be omitted** — tools fall back
+to price-only readouts, so existing integrations keep working untouched.
+
+When `pipSize` is absent it is inferred from how many decimals the feed quotes:
+five-decimal (`1.08531`) and three-decimal (`151.234`) feeds carry fractional
+pips, so the pip is the second-to-last digit; two- and four-decimal feeds quote
+whole pips. **That convention is wrong for metals, indices and crypto** — pass
+`pipSize` explicitly if pips matter.
+
+The same fallbacks are exported for hosts that want to compute alongside the
+chart:
+
+```ts
+import { resolveInstrument, inferPipSize, toPips, toMoney } from 'acttrader-charts';
+```
+
+> Per-position values still travel on the individual `TradeLevel`
+> (`contractSize` / `valuePerPoint`). `InstrumentSpec` is the chart-wide default
+> for tools that aren't attached to a position.
+
+### Feature flags
+
+Newer tools ship behind `ChartConfig.features` so each host opts in. **Every flag
+defaults to `false`** — a chart that sets none behaves exactly as it did before
+the flag existed, including its toolbar contents.
+
+```ts
+const chart = new ChartEngine({
+    container,
+    features: { enableForecasting: true },
+});
+```
+
+| Flag | Default | What it changes |
+|---|---|---|
+| `enableForecasting` | `false` | The reworked drawing tools, as one switch — see below |
+| `orderLineTimeDrag` | `false` | Horizontal (time-axis) order-line dragging for positions and pending orders — see [Horizontal order-line dragging](#horizontal-time-axis-order-line-dragging) |
+| `pnlPill` | `false` | Floating on-chart P/L pill — count and summed P/L of the positions on the chart — see [On-chart P/L pill](#on-chart-pl-pill--featurespnlpill) |
+| `tradeActionBar` | `false` | The trade button opens a segmented `Alert · Pending · SL · TP · TSL · ×` bar at the clicked price instead of the two-row Buy/Sell popup — see [Trade action bar](#trade-action-bar--featurestradeactionbar) |
+
+`enableForecasting` turns on three things together:
+
+- **Long Position** / **Short Position** in a new **Forecasting** group in the
+  drawing toolbar. With the flag off the group is not rendered at all.
+- **Brush** and **Highlighter** draw freehand — press, drag, release. Off, they
+  keep the click-per-point gesture ended by a double-click.
+- **Ruler** reports percent, pips, calendar duration and volume. Off, it reports
+  the bar count and raw price delta as before.
+
+They share one flag because they ship and roll back together: a broker either has
+the reworked drawing tools or it doesn't.
+
+Related config, independent of the flag: the position tools show quantity and
+money only when [`account`](#accountspec) is supplied, and pips on both the
+position tools and the ruler come from [`instrument`](#instrumentspec) — without
+it, pip size is inferred from the feed's decimal count.
+
+### `AccountSpec`
+
+What the **Long / Short position** tools size themselves against.
+
+TradingView asks the user to type these because it has no broker connection. We
+do have one — so pass real equity and keep it current.
+
+```ts
+chart.setAccount({ size: 10_000, riskPercent: 1 });
+```
+
+| Field | Default | Description |
+|---|---|---|
+| `size` | — | Account equity in the account currency |
+| `riskPercent` | `1` | Percent of the account risked per trade |
+
+Omit the block and the position tools still draw — price, percent, pips and
+risk/reward all render; only the quantity and money amounts are left out.
+
+> A sketch drawn against a stale balance reports the wrong quantity rather than
+> failing visibly, so push `setAccount()` whenever equity moves.
+
 ### `OHLCVBar`
 
 | Field | Required | Type | Description |
@@ -477,7 +711,7 @@ import { DEFAULT_UI_CONFIG } from 'acttrader-charts';
 
 | Component key | Configurable properties |
 |---|---|
-| `drawingToolbar` | `iconBtnSize`, `iconFontSize`, `iconFontFamily`, `flyoutLabelFontSize`, `flyoutLabelFontFamily`, `shortcutFontSize`, `soonBadgeFontSize`, `flyoutHeadingFontSize`, `flyoutHeadingLetterSpacing`, `scrollBtnHeight`, `scrollBtnFontSize`, `barPadding`, `btnGap` |
+| `drawingToolbar` | `iconBtnSize`, `iconFontSize`, `iconFontFamily`, `flyoutLabelFontSize`, `flyoutLabelFontFamily`, `shortcutFontSize`, `soonBadgeFontSize`, `flyoutHeadingFontSize`, `flyoutHeadingLetterSpacing`, `scrollBtnHeight`, `scrollBtnFontSize`, `barPadding`, `btnGap`, `modernIcons`, `actionsButtonIcon` (`'default'` \| `'lock'` — lock glyph on the Actions button, for hosts that relabel Lock All as "Save Charts") |
 | `topBar` | `height`, `dropBtnFontSize`, `dropBtnFontFamily`, `drawBtnSize`, `drawBtnIconFontSize`, `iconBtnSize`, `mobileIconBtnSize`, `mobileDrawBtnIconSize`, `flyoutRowFontSize`, `flyoutRowFontFamily`, `flyoutCategoryFontSize`, `flyoutCategoryLetterSpacing`, `flyoutCheckFontSize`, `streamDotSize` |
 | `bottomBar` | `height`, `btnFontSize`, `btnFontFamily` |
 | `priceAxis` | `fontSize`, `fontFamily` |
@@ -555,6 +789,11 @@ new ChartEngine({
 | `topBar.series` | `area` | `'Area'` | |
 | `topBar` | `indicatorsBtn` | `'Indicators'` | Indicators button (no active) |
 | `topBar` | `indicatorsBtnActive` | `'Indicators ({count})'` | `{count}` replaced at runtime |
+| `topBar` | `disableCrosshairTitle` | `'Disable crosshair'` | Header crosshair switch tooltip while on (`enableCrossHairHeader`) |
+| `topBar` | `enableCrosshairTitle` | `'Enable crosshair'` | Header crosshair switch tooltip while off |
+| `topBar` | `pnlPillBtn` | `'P/L'` | Header P/L pill switch label (`features.pnlPill`) |
+| `topBar` | `hidePnlPillTitle` | `'Hide P/L pill for {symbol}'` | P/L switch tooltip while the pill is shown |
+| `topBar` | `showPnlPillTitle` | `'Show P/L pill for {symbol}'` | P/L switch tooltip while the pill is hidden |
 | `topBar` | `toggleDrawingTitle` | `'Toggle Drawing Tools'` | Toolbar toggle tooltip |
 | `topBar` | `toggleFullscreenTitle` | `'Toggle Fullscreen'` | Fullscreen button tooltip |
 | `topBar` | `exitFullscreenTitle` | `'Exit Fullscreen'` | |
@@ -597,6 +836,16 @@ new ChartEngine({
 | `trade` | `market` | `'Market'` | |
 | `trade` | `qty` | `'Qty'` | Draft order qty input label |
 | `trade` | `placeOrderTitle` | `'Place order at this price'` | Trade button tooltip |
+| `trade` | `actionAlert` … `actionTsl` | `'Alert'`, `'Pending'`, `'SL'`, `'TP'`, `'TSL'` | Trade action bar chips (`features.tradeActionBar`) |
+| `trade` | `actionCloseTitle` | `'Close'` | Trade action bar × tooltip |
+| `trade` | `directionAbove`, `directionBelow` | `'Above'`, `'Below'` | Pending sub-menu header — side of the market the clicked price is on |
+| `trade` | `actionBulkNoPositionsTitle`, `actionBulkMixedTitle` | `'No open {symbol} positions'`, `'Bulk levels need all {symbol} positions in one direction'` | SL / TP / TSL chips greyed out — why |
+| `pnlPill` | `positionsAbbrev` | `'POS'` | On-chart P/L pill — word after the count (`3 POS`), shown uppercase |
+| `pnlPill` | `showPositionsTitle` | `'Show positions on chart · drag handle to move · double-click to reset'` | Pill tooltip while collapsed — a body click fans the positions out |
+| `pnlPill` | `hidePositionsTitle` | `'Hide positions on chart · drag handle to move · double-click to reset'` | Pill tooltip while fanned out |
+| `pnlPill` | `bulkLevelsTitle` | `'Set SL · TP · TSL on all {count} {symbol} positions'` | ◎ tooltip — opens the host's Bulk Levels dialog |
+| `pnlPill` | `bulkLevelsMixedTitle` | `'Bulk levels need all {count} {symbol} positions in one direction'` | ◎ tooltip while greyed out for mixed sides |
+| `pnlPill` | `closeAllTitle` | `'Close all {symbol} positions'` | Amber ✕ tooltip; `{symbol}` and `{count}` are filled in |
 | `dialogs.settings` | `title` | `'Chart Settings'` | Dialog title |
 | `dialogs.settings` | `tfcSection` | `'Trade from Charts'` | Section heading |
 | `dialogs.settings` | `showLabel` | `'Show'` | Radio group label |
@@ -637,8 +886,8 @@ chart.setTheme('light');
 |---|---|---|
 | `background` | `string` | Canvas background color |
 | `grid` | `string` | Grid line color |
-| `axisText` | `string` | Axis tick label color |
-| `axisBorder` | `string` | Axis border / separator color |
+| `axisText` | `string` | Axis tick label color. Also the default label colour for the chart chrome (dialog text, toolbar labels) — set it via `themeOverrides` to restyle both, or via the Settings dialog to restyle the canvas axis alone |
+| `axisBorder` | `string` | Axis border / separator color. Also the default border colour for the chart chrome (dialog frames, toolbar dividers) — same split as `axisText` |
 | `crosshair` | `string` | Crosshair line color |
 | `tooltip` | `{background, text, border}` | Floating label colors |
 | `candle` | `{up, down, wickUp, wickDown}` | Candlestick colors |
@@ -673,7 +922,7 @@ chart.resetData(): this
 
 **Symbol switch pattern:**
 ```ts
-chart.setSymbol('GBPUSD').resetData();
+chart.setSymbol('GBPUSD').setInstrument({ pipSize: 0.0001 }).resetData();
 // … fetch new bars …
 chart.loadData(newBars);
 ```
@@ -682,9 +931,17 @@ chart.loadData(newBars);
 
 ```ts
 chart.setSeries(series: SeriesType): this
+chart.setInstrument(spec: InstrumentSpec | undefined): this     // contract specs for pips / money readouts
+chart.getInstrument(): ResolvedInstrument                       // specs with fallbacks applied
+chart.setAccount(account: AccountSpec | undefined): this        // equity + risk for the position tools
+chart.getAccount(): AccountSpec | undefined
 chart.setTheme('dark' | 'light'): this
 chart.setTimeframe(tf: Timeframe): this                         // change timeframe and reload data
-chart.setThemeOverrides(overrides: ThemeOverrides): this               // update per-theme color overrides at runtime
+chart.setDuration(d: Duration, timeframe?: Timeframe): this     // select a duration; pairs the timeframe and reloads
+chart.getDuration(): Duration | null                            // currently selected duration
+chart.setBracketLabelMode(mode, currencySymbol?): this          // SL/TP pills: 'price' (default) or 'amount'
+chart.setThemeOverrides(overrides: ThemeOverrides): this               // update per-theme color overrides at runtime — canvas AND chrome
+chart.setCanvasColors(colors: ChartConfig['canvasColors'] | null): this // recolour the canvas only at runtime (same picks as the Settings dialog); null clears
 chart.setTimezone(tz: string): this                                // change display timezone at runtime
 chart.setVolume(show: boolean): this
 ```
@@ -722,6 +979,7 @@ chart.cancelCurrentEdit(): this   // cancel the active draft order or any in-pro
 chart.addLevelBracket(label: string, bracketType: 'sl' | 'tp'): this   // auto-place a SL or TP bracket at a default offset; emits tradeLevelBracketActivated with the computed price
 chart.setDraftBracketPnl(bracketType: 'sl' | 'tp', pnlText: string | null): this   // set estimated P&L text on the active bracket host — the draft order while drafting, or the currently selected existing pending order / position while modifying; pass null to clear
 chart.setTfcActive(enabled: boolean): this   // toggle TFC on/off at runtime; hides/shows all trade levels, draft orders, and floating trade button; fires tfcToggle event
+chart.setPnlPillVisible(visible: boolean): this   // show/hide the on-chart P/L pill (features.pnlPill) — what the header's P/L switch does; emits pnlPillToggle
 ```
 
 > **Staging semantics for `updateLevelMainPrice` / `updateLevelBracket`.** Calls to these methods register the change in the chart's pending-edit buffer (the same buffer chart-initiated drags use), so the edit stays visible even when the host app keeps pushing fresh server state via `setLevels` (e.g. per-tick PnL refreshes). When the server echoes back the new price in a later `setLevels` call, the staged edit is auto-released (mobile, i.e. `hideLevelConfirmCancel: true`). If a panel closes without submitting, call `cancelLevelEdit(label)` or `cancelCurrentEdit()` to drop the staged edit — otherwise it will keep overriding server state on the chart.
@@ -730,8 +988,39 @@ chart.setTfcActive(enabled: boolean): this   // toggle TFC on/off at runtime; hi
 
 ```ts
 chart.setOrderLots(lots: number): void   // update default qty at runtime
+chart.setCrosshairEnabled(enabled: boolean): this   // off hides the crosshair AND this button — it rides on the crosshair line, so it has no place once the line is gone
+```
+
+The button follows the crosshair's horizontal line, so it is only ever shown while the
+crosshair is (`crosshairEnabled`, default `true`). Hosts with a crosshair on/off control
+should call `setCrosshairEnabled()` rather than painting the crosshair transparent — the
+latter leaves the button riding an invisible line.
+
+### Header crosshair switch — `enableCrossHairHeader`
+
+```ts
+const chart = new ChartEngine({
+  container,
+  enableCrossHairHeader: true, // crosshair icon in the header; the crosshair itself starts on
+});
+chart.on('crosshairToggle', ({ enabled }) => saveUserPref('crosshair', enabled));
 ```
 
+With the flag on, a crosshair icon sits in the header's right cluster (advanced toolbar and
+default top bar) or at the end of the compact per-pane strip (`headerLayout: 'compact'`). The chart crosshair is shown as usual on load and the icon is tinted. Clicking
+the icon hides the crosshair — and the floating trade button that rides on it — and the icon
+drops to its plain state; clicking again brings both back. Each click goes through
+`setCrosshairEnabled()` and emits `crosshairToggle`, so a host can persist the choice and seed
+it on the next load with `crosshairEnabled: false`. `enableCrosshairToggle` is the deprecated
+name of the same flag and still works. Native wrappers get the same switch via their
+`enableCrossHairHeader` init option, the `onCrosshairToggle` callback and `setCrosshairEnabled()`.
+
+### Native UI catalog (webview bridge only)
+
+The webview bridge used by the Android and iOS wrappers posts a **`catalog`** event right after every `init` command, and again on the **`getCatalog`** command (which also works before `init`). It lists everything a native app needs to build its own header, drawing-tools sheet, indicators list and chart-settings screen: timeframes, chart types, cursors, drawing tool groups (with point counts and style fields), drawing-toolbar options, indicators (with pane and editable settings fields), the Chart Settings dialog (tabs → sections → items with types, options and defaults), canvas colour keys, price sources and limits. Every entry carries `available` (`true` = works in this version, `false` = planned). `catalogVersion` is the library version, stamped at build time.
+
+Source: `src/core/mobileCatalog.ts`. `src/__tests__/mobileCatalog.test.ts` fails the build if an `available: true` id does not exist in the engine, or an engine tool / indicator is missing from the catalog — update the catalog together with any new chart type, tool or indicator. The web `ChartEngine` API is unchanged.
+
 ### Viewport
 
 ```ts
@@ -888,6 +1177,39 @@ Sub-pane heights are user-resizable by dragging the separator between panes.
 | `flatChannel` | Flat Channel | 2 clicks |
 | `disjointChannel` | Disjoint Channel | 3 clicks |
 
+### SL/TP bracket labels — price or amount
+
+By default an SL/TP pill reads `SL @4159.00` — the currency sign is never shown on
+a price. With `bracketLabelMode: 'amount'` it reads `SL -$290.80` — the money the
+position gains or loses if that bracket is hit, currency symbol in front and a
+minus only on a loss. `'priceAndAmount'` shows `SL @4159.00` at rest and
+`SL @4159.00 -$290.80` while the bracket is dragged.
+
+The chart has no access to contract specs or the account currency, so each level
+supplies what the maths needs:
+
+```ts
+new ChartEngine({ container, bracketLabelMode: 'amount', currencySymbol: '$' });
+
+chart.setLevels([{
+  label: 'POS-1', price: 4173.54, side: 'buy', lots: 0.20,
+  stopLossPrice: 4159.00, takeProfitPrice: 4183.00,
+  contractSize: 100,     // units per lot (100 for XAUUSD, 100000 for most FX)
+  valuePerPoint: 1,      // account-currency value of one price unit
+  currencySymbol: '$',   // optional per-level override
+}], 'label', 'price', 'position');
+// pills render: SL -$290.80   TP $189.20
+```
+
+```
+amount = (bracket − entry) × direction × lots × contractSize × valuePerPoint
+```
+
+`valuePerPoint` is where a quote → account currency conversion goes. A level
+missing `lots` or `contractSize` keeps showing its price, so a partial rollout
+degrades level by level rather than rendering `NaN`. Toggle at runtime with
+`chart.setBracketLabelMode('amount')`.
+
 ### Fibonacci & Gann
 
 `fibRetracement` · `fibExtension` · `fibChannel` · `fibTimezone` · `fibCircles` · `fibSpiral` · `fibFan` · `fibProjection` · `gannFan` · `gannSquare` · `gannBox`
@@ -920,10 +1242,78 @@ In a **per-drawing** style (`SerializedDrawing.style.levels`), a level may also
 
 `rectangle` · `rotatedRectangle` · `ellipse` · `triangle` · `circle` · `arc` · `polyline` · `path` · `brush` · `highlighter`
 
+**`brush` and `highlighter` draw freehand** when `features.enableForecasting` is on
+(see [Feature flags](#feature-flags)): press, drag, release — the pointer
+path is sampled continuously and the finished stroke is thinned to the points
+that carry its shape. (`polyline` and `path` remain click-per-point, ended with a
+double-click.)
+
 ### Measurements & Annotations
 
 `priceRange` · `dateRange` · `datePriceRange` · `ruler` · `priceLabel` · `priceNote` · `priceProjection` · `projection` · `arrowUp` · `arrowDown` · `arrowMarker` · `text` · `callout` · `anchoredNote` · `flag` · `sineLine` · `regressionTrend` · `ghostFeed`
 
+**`ruler`**, with `features.enableForecasting` on (see [Feature flags](#feature-flags)),
+draws a direction-tinted box over the span it measures and reports:
+
+```
+0.00455 (0.80%) 45.5
+43 bars, 9d 4h
+Vol 102.27K
+```
+
+Price delta, percent, and **pips**; bar count and calendar duration; volume
+traded across the span.
+
+A pip figure is always shown — but it is only *correct* when the host supplies
+[`instrument.pipSize`](#instrumentspec). Without it the chart infers pip size
+from how many decimals the feed quotes, which follows the usual FX convention
+and is wrong for metals, indices and crypto.
+
+Duration needs bar timestamps, and the volume line is omitted entirely when the
+bars carry no volume, rather than showing a `0` that would read as "no volume
+traded".
+
+The box takes its colour from `candle.up` / `candle.down` so a measurement never
+disagrees with the candles underneath it; picking a colour in the style popover
+overrides that. All four corners resize.
+
+With the flag off it reports the bar count and raw price delta, as it always has.
+
+### Forecasting
+
+`longPosition` · `shortPosition`
+
+> Requires `features.enableForecasting` — see [Feature flags](#feature-flags).
+> With the flag off the group is not rendered, on the desktop toolbar or in the
+> mobile tools sheet.
+>
+> `ghostFeed` and `projection` stay in **Advanced Tools** and are ungated — they
+> predate this group.
+
+**`longPosition` / `shortPosition`** sketch a trade that hasn't been placed: a
+green profit zone from entry to target, a red risk zone from entry to stop, and
+live readouts.
+
+```
+Target: 0.00313 (0.549%) 31.3, Amount: 5622.13
+Open PnL: 0.00146, Qty: 11323
+Risk/reward ratio: 1.84
+Stop: 0.00170 (0.298%) 17.0, Amount: 2887.5
+```
+
+Two clicks place it — entry, then target — and the stop lands at a 2:1
+reward:risk for you to drag. All three prices have handles.
+
+Quantity is sized so that hitting the stop costs exactly `riskPercent` of the
+account, which needs [`account`](#accountspec); the money amounts and pips also
+need [`instrument`](#instrumentspec). Without them the tool still draws and still
+reports price, percent and risk/reward.
+
+> **This is a drawing, not an order.** Trade-From-Chart (`setLevels`) is what
+> puts real broker orders on the chart — see [Trade From Chart
+> (TFC)](#trade-from-chart-tfc--setlevels). Nothing on a position tool reaches
+> the broker.
+
 ### Volume Profile
 
 `volumeProfile` · `anchoredVP` · `fixedRangeVP`
@@ -932,6 +1322,10 @@ In a **per-drawing** style (`SerializedDrawing.style.levels`), a level may also
 
 `cyclicLines` · `timeCycles`
 
+> `ghostFeed` and `projection` remain here and are ungated. TradingView files
+> them under Forecasting, but moving them would have reshuffled the toolbar for
+> hosts that never enabled the new group.
+
 ### Harmonic & Elliott Patterns
 
 `abcdPattern` · `headShoulders` · `trianglePattern` · `batPattern` · `butterflyPattern` · `crabPattern` · `gartleyPattern` · `cypherPattern` · `sharkPattern` · `threeDrives` · `elliottImpulse` · `elliottCorrective` · `elliottTriangle` · `elliottCombination` · `elliottWxy`
@@ -952,8 +1346,9 @@ chart.on('pan',            ({ viewport }) => {});
 chart.on('timeframeChange',({ timeframe }) => {});
 chart.on('durationChange', ({ duration, timeframe }) => {});
 chart.on('seriesChange',   ({ series }) => {});
+chart.on('priceSourceChange', ({ source }) => {});   // header BID/ASK/LTP dropdown pick
 chart.on('streamStatus',   ({ status }) => {}); // 'connected' | 'reconnecting' | 'disconnected'
-chart.on('dataLoaded',     ({ timeframe, interval, start, end }) => {});
+chart.on('dataLoaded',     ({ timeframe, interval, start, end, priceSource }) => {});
 chart.on('newBar',         ({ completedBar, openingBar, intervalMs }) => {});
 chart.on('indicatorAdded',   ({ instanceId, shortName, params }) => {}); // a study instance was added — keep instanceId to remove it later
 chart.on('indicatorRemoved', ({ instanceId, shortName }) => {});
@@ -976,6 +1371,10 @@ chart.on('tradeLevelEditCancelled', ({ label, type, isFullscreen }) => {}); // E
 chart.on('draftInitiated',     ({ side, price, orderType, isFullscreen }) => {}); // new draft order shown — open buy/sell form
 chart.on('draftCancelled',     ({ label, isFullscreen }) => {}); // draft order dismissed without confirming
 chart.on('tfcToggle',         ({ enabled }) => {}); // TFC toggled on or off via top bar button or setTfcActive()
+chart.on('crosshairToggle',   ({ enabled }) => {}); // crosshair switched on or off — header switch (enableCrossHairHeader) or setCrosshairEnabled(); persist it here
+chart.on('pnlPillCloseAll',   ({ count, pnl, labels, data, isFullscreen }) => {}); // the on-chart P/L pill's ✕ — close these positions (features.pnlPill)
+chart.on('pnlPillToggle',     ({ visible }) => {}); // the header's P/L switch showed or hid the pill — persist it here (features.pnlPill)
+chart.on('bulkLevelsRequested', ({ kind, price, source, isFullscreen }) => {}); // action-bar chip (price) or the P/L pill's ◎ (price null) — open your Bulk Levels dialog for `kind`
 chart.on('tradeLevelDragEnd',  ({ label, type, newPrice, data }) => {}); // deprecated — use tradeLevelEdit
 chart.on('tradeLevelBracketDrag', ({ label, bracketType, newPrice, data }) => {}); // deprecated
 
@@ -984,8 +1383,8 @@ chart.on('tradeLevelBracketDrag', ({ label, bracketType, newPrice, data }) => {}
 chart.on('orderLineMoveStart', ({ label, fromTimestamp, fromBarIndex, isFullscreen }) => {});
 chart.on('orderLineMoving',    ({ label, toTimestamp, toBarIndex, isFullscreen }) => {}); // fires on every move
 chart.on('orderLineMoved',     ({ label, fromTimestamp, toTimestamp, fromBarIndex, toBarIndex, data, isFullscreen }) => {
-    // Persist the new time anchor for this order. Echo `timestamp: toTimestamp` back in your
-    // next setLevels() payload so the badge stays put across refreshes.
+    // The chart already remembers the drop in localStorage (orderLineAnchorPersistence, default on).
+    // Hook here only if you also want to persist the new time anchor server-side.
 });
 
 // Fires after addLevelBracket() auto-places a bracket, delivering the computed price back to the caller
@@ -1126,45 +1525,1505 @@ The composite excludes trade levels (positions, SL/TP) — same rule as `chart.t
 
 ---
 
-## Custom Indicator
+## Icons & Drawing Toolbar Options
 
-Implement `IIndicator` and pass it to `addIndicator()`:
+### Icons, Emojis & Stickers — `'icon'`
+
+A glyph placed at a bar and price, behind `features.enableIconTools`. **One tool,
+not three**: emojis, stickers and icons are the same drawing with a different
+character, so the picker chooses the glyph and the glyph lives in `text` like any
+other annotation's content. They serialise, re-anchor and re-style through
+machinery that already exists rather than needing three parallel implementations.
 
 ```ts
-import type { IIndicator, OHLCVBar, IndicatorResult } from 'acttrader-charts';
+const chart = new ChartEngine({
+    container,
+    features: { enableIconTools: true },
+});
+chart.setDrawingTool('icon');   // uses the last glyph picked
+```
 
-class MyIndicator implements IIndicator {
-    name       = 'MyInd';
-    color      = '#e91e63';
-    pane       = 'sub' as const;  // 'main' = overlay, 'sub' = dedicated pane
-    paneHeight = 80;
+#### The picker
 
-    compute(data: OHLCVBar[]): IndicatorResult[] {
-        return data.map((bar, i) => ({ index: i, value: bar.close }));
-    }
+Opening the **Icons & Emojis** group gives a panel, not a list of rows: a row per
+glyph is unusable past a couple of dozen, and this is the one category whose
+items *are* the icon rather than being labelled by one.
 
-    render(ctx, results, scale, viewport, chartHeight) {
-        // draw with ctx (Canvas 2D)
-    }
-}
+```
+┌────────────────────────────────┐
+│ 😊 🐻 🍔 🏀 🚀 💡 ❤️ 🏳️        │  category tabs
+├────────────────────────────────┤
+│ 😀 😃 😄 😁 😆 😅 🤣 😂         │
+│ 🙂 🙃 😉 😊 😇 🥰 😍 🤩         │  scrolling grid
+├────────────────────────────────┤
+│   Emojis   Stickers   Icons    │  kind tabs
+└────────────────────────────────┘
+```
 
-chart.addIndicator(new MyIndicator());
+The three bottom tabs are not three copies of the same thing:
+
+| Tab | Holds | Draws as |
+| --- | --- | --- |
+| **Emojis** | ~900 across the eight Unicode groups | System colour font, 22px |
+| **Stickers** | Trading-flavoured sets — bull & bear, reactions, money, warnings, awards | The same characters at 44px |
+| **Icons** | Monochrome arrows, shapes, marks, currency | Takes the drawing's colour |
+
+That last row is why **Icons** is worth having at all. An emoji is a colour
+bitmap in the system font: it ignores `fillStyle`, so it can never be recoloured
+to match a palette or printed legibly in mono. Everything under Icons is a plain
+text character, and does tint.
+
+The panel renders into the toolbar's existing flyout rather than adding a second
+floating layer, so it inherits that popover's positioning, outside-click
+dismissal and teardown. It remembers the tab and category per session — reopening
+a picker to find yourself back on the first page of smileys is the single most
+irritating thing a picker can do.
+
+#### Resizing
+
+A placed icon is selectable and **resizable by dragging any of its four corner
+handles**. Size is also in the style popover, which offers a colour swatch and a
+px picker rather than the default stroke/width/style — three controls that would
+do nothing to a glyph.
+
+```ts
+chart.getDrawings()
+     .filter(d => d.type === 'icon')
+     .forEach(d => { d.style = { ...d.style, fontSize: 64 }; });
+```
+
+**The size is in pixels, not price.** It does not rescale when the chart is
+zoomed. Deriving it from two data points would have fit the existing drag
+machinery with no new concepts, but a pin dropped on a bar would then become a
+billboard three zoom steps out and vanish three steps in — and the user would
+have to resize it again every time they changed the view. So `DrawingHandle`
+grew a `mode: 'size'`, and handles marked that way route to
+`IDrawing.resizeToPixel(px, py)` instead of the point writer.
+
+`resizeToPixel` takes pixels because the size it sets is in pixels — converting
+through price and back would make the result depend on the zoom level it was
+dragged at. It measures against the anchor position cached during `render`,
+which is the only place a drawing is handed the scale.
+
+The new size is the larger of the two axis distances, not the diagonal, so
+pulling straight out sideways grows the glyph as much as pulling corner to
+corner. A glyph is square; a user dragging one edge means "bigger", not "bigger
+by cos 45°". Clamped to 10–400px and rounded, since the value is shown in a px
+picker and round-trips through JSON.
+
+Glyphs render through the system emoji font, so colour emoji stay colour on every
+platform that has them.
+
+### Drawing toolbar options
+
+Five toggles in the toolbar's actions menu (⋯).
+
+| Option | What it does |
+| --- | --- |
+| **Magnet Mode** | Drawing points snap to the nearest open/high/low/close of the bar under the cursor. |
+| **Keep Drawing Mode** | The tool stays armed after each drawing, so a series can be placed without returning to the toolbar. |
+| **Copy to All Charts** | New drawings are announced for replication across a layout. |
+| **Hide Drawings Toolbar** | Hides the toolbar at runtime; bring it back with `setDrawingToolbarVisible(true)`. |
+| **Zoom In** | In the Cursors group — drag a box and the chart zooms to it. |
+
+```ts
+const chart = new ChartEngine({
+    container,
+    magnetMode: true,
+    keepDrawingMode: true,
+    copyDrawingsToAllCharts: true,
+});
+
+chart.setMagnetMode(false);
+chart.on('magnetModeChange', ({ enabled }) => persist(enabled));
+```
+
+**Magnet snaps within a pixel threshold, not always.** A trend line deliberately
+drawn through the middle of a range should stay there. The threshold is in
+pixels rather than price so it feels identical at every zoom — a price-space
+tolerance would snap from far away on a zoomed-out chart and never trigger on a
+zoomed-in one.
+
+**Keep-drawing mode routes through one place.** There are four separate
+completion paths in the drawing manager; a mode that held for only some of them
+would look broken in exactly the cases a user reached for it.
+
+**Copy-to-all is announced, not performed.** The chart emits `drawingCreated`
+with `copyToAll`, because only the host knows which other panes exist:
+
+```ts
+chart.on('drawingCreated', ({ drawing, copyToAll }) => {
+    if (copyToAll) group.broadcastDrawing(drawing, thisPaneId);
+});
 ```
 
+`ChartGroup.broadcastDrawing(drawing, fromPaneId?)` hands the payload to every
+other pane's `ChartEngine.addDrawing(drawing)`. Unlike `broadcastSymbol` there
+is no `LayoutSyncState` flag gating it — the toggle already lives on the chart
+the user drew on, and that is what `copyToAll` reports.
+
+`addDrawing` **appends and is undoable**, where `setState` would replace the
+list and flatten the target pane's history. Each pane's copy also gets a fresh
+id, so dragging the mirrored drawing in one pane leaves the others alone.
+
+**Zoom In is a drawing internally.** It reuses the two-point press-preview-release
+gesture rather than duplicating it as a bespoke drag mode, then applies the zoom
+and removes itself — so nothing is left on the chart and it never reaches
+`ChartState`. It sets *both* axes: zooming only time would leave the chosen
+prices no larger than before, which is not what dragging a box asks for.
+
+### Native wrapper parity
+
+`'icon'` and `'zoomIn'` are `DrawingToolType` strings and need no wrapper change.
+The toolbar options are new bridge commands — see
+[charts-android](../charts-android) and [charts-ios](../charts-ios).
+
 ---
 
-## Build & Dev
+## Notes & Text
 
-```bash
-npm run dev        # Vite dev server with demo chart
-npm run build      # ESM + CJS via tsup → dist/
-npm run test       # Vitest unit tests
-npm run typecheck  # tsc --noEmit
-npm run lint       # ESLint
+Six annotation tools, all single-click: place, then type.
+
+| Tool | `DrawingToolType` | Form |
+| --- | --- | --- |
+| **Anchored Text** | `'anchoredText'` | Free text with a dot on the bar and price it refers to. |
+| **Note** | `'note'` | A compact page marker with the text beside it. |
+| **Pin** | `'pin'` | A teardrop whose **tip** sits exactly on the price. |
+| **Table** | `'table'` | Rows of text in a bordered grid. |
+| **Comment** | `'comment'` | A rounded speech bubble with its tail on the anchor. |
+| **Signpost** | `'signpost'` | A plaque on a post, rising clear of the candles. |
+
+```ts
+chart.setDrawingTool('signpost');
+```
+
+All six anchor to a bar and price like every other drawing, so they re-anchor
+correctly after a data reload and serialise into `ChartState` unchanged.
+
+### Editing
+
+| | |
+| --- | --- |
+| **Place** | Click — the editor opens focused |
+| **Re-edit** | Select, then double-click |
+| **New line** | `Enter` (multi-line tools) |
+| **Commit** | `Ctrl`/`⌘`+`Enter`, or click away |
+| **Discard** | `Escape` |
+
+**Anchored Text, Note, Table, Comment and Signpost get a multi-line editor**;
+Text, Callout, Anchored Note and Pin keep the single-line field where `Enter`
+commits, exactly as before. A Table is unusable without this — its rows *are*
+newlines, so `Enter` has to insert one.
+
+The box grows with its content as you type, so adding rows is visible rather
+than feeling like it has a row limit.
+
+### Why these are separate tools rather than one with options
+
+The shape *is* the choice. Someone reaching for a Pin wants a precise marker at
+a level; someone reaching for a Signpost wants a dated flag that does not cover
+the candles; someone reaching for a Table wants several values at once.
+Collapsing them into "text with a style dropdown" would make each one harder to
+reach than the thing it replaced.
+
+### Details worth knowing
+
+**Table syntax** — newlines are rows and `|` separates columns, so a table is
+typed into the same single text field as everything else rather than needing a
+bespoke editor. The first row is tinted as a header; short rows are padded so the
+grid stays rectangular, and empty cells are kept (clearing a value is editing the
+table, not asking for the column to vanish).
+
+**A new table arrives already a grid** — four rows by two columns, with the
+syntax visible in the editor:
+
+```
+Level | Price
+Entry |
+Stop |
+Target |
 ```
 
+That is deliberate. An empty table rendered a single placeholder row and opened a
+blank editor, so nothing told you rows are newlines and columns are `|` — the
+tool looked as though it had no rows or columns at all. Overtyping a grid is also
+faster than building one from nothing.
+
+**Pin anchors by its tip, not its centre.** A marker whose middle sits on the
+level is ambiguous about which price it means.
+
+**Anchored Text vs Text** — plain `text` floats with no indication of what it
+refers to. Anchored Text draws its anchor, so a note about one specific candle
+still points at that candle after panning and zooming.
+
+**Comment vs Callout** — `callout` is a square-cornered box with a straight
+pointer; `comment` is the softer rounded bubble. Both are kept because the
+difference is exactly what the user is choosing between.
+
+Empty tools render a placeholder (`Text`, `Note`, `Event`…) rather than nothing,
+so a drawing placed but not yet typed into is still visible and selectable.
+
+### Native wrapper parity
+
+All six are `DrawingToolType` strings, so `setDrawingTool('pin')` works on
+[charts-android](../charts-android) and [charts-ios](../charts-ios) with no
+wrapper change.
+
 ---
 
-## License
+## Indicator Library
 
-MIT
+**78 studies added**, taking the library from 30 to 108.
+
+```ts
+chart.addIndicatorByName('TRIX');
+chart.addIndicatorByName('Vortex');
+```
+
+They appear in the Indicators flyout alongside the originals, grouped by the
+same categories, and each is configurable through the settings dialog.
+
+### How they are registered
+
+The original thirty are registered by hand in three places — a preset list, a
+param-schema list, and `indicators.json`. Repeating that seventy-eight times
+would be seventy-eight chances to register an indicator in two places and not
+the third, which fails *silently*: the tool appears in the menu and does
+nothing, or computes and never appears.
+
+So each new indicator is declared once in `indicators/registry.ts` and the three
+views are derived:
+
+```ts
+{
+    shortName: 'TRIX', name: 'TRIX', type: 'Momentum',
+    fields: [periodField(18), colorField('#00BFA5'), sourceField()],
+    factory: (p) => new SimpleOscillator('TRIX', p.color, …),
+}
+```
+
+### Shared foundations
+
+| Module | What it holds |
+| --- | --- |
+| `indicators/math.ts` | `sma`, `ema`, `rma`, `wma`, `hma`, `vwma`, `alma`, `dema`, `tema`, `mcginley`, `lsma`, `stdev`, `standardError`, `correlation`, `atr`, … |
+| `indicators/base.ts` | `LineIndicatorBase`, `BandIndicatorBase`, `HistogramIndicatorBase` |
+
+All exported, so a host can compute the same series off-chart.
+
+Two conventions the maths holds to throughout:
+
+- **`null` means undefined and propagates.** An EMA of an RSI is null wherever
+  the RSI is. Returning `0` instead would draw a line through a period where the
+  indicator does not exist, which reads as data and is not.
+- **`stdev` is the population form**, because Bollinger Bands and everything
+  derived from them are defined that way; using `n−1` shifts every band visibly
+  on short periods.
+
+### The comparative studies
+
+**Correlation Coefficient**, **Correlation – Log**, **Ratio**, **Spread** and
+**Advance/Decline** are undefined against a single series — they need a second
+instrument. `IIndicator.compute` gained an optional second argument for this:
+
+```ts
+compute(data: OHLCVBar[], context?: IndicatorComputeContext): IndicatorResult[]
+```
+
+`context.compares` carries the bars for each symbol added through the Compare
+feature. The parameter is optional, so every existing indicator is unaffected.
+
+**With no compare symbol added, these draw nothing.** Substituting a stand-in
+series — correlating price against its own average, say — would produce a
+confident-looking line answering a different question than the indicator's name
+promises.
+
+### Two things worth knowing
+
+**Volume Profile Visible Range** distributes each bar's real volume across the
+price levels that bar actually traded through, and marks the Point of Control.
+The existing `anchoredVP` *drawing tool* is a different thing: its bar heights
+come from a hardcoded bell curve, not from the feed.
+
+**`maxSubPanes` caps concurrent sub-pane indicators.** Most of these 78 live in
+their own pane, so adding many at once silently stops at the cap. Raise
+`maxSubPanes` if you need more on screen together.
+
+### Native wrapper parity
+
+All 78 are reachable through the existing `addIndicator` bridge command by short
+name — no wrapper change:
+
+```kotlin
+chartView.addIndicatorByName("TRIX")
+```
+
+### What was added
+
+| Group | Studies |
+| --- | --- |
+| Moving averages (14) | ALMA, DEMA, TEMA, LSMA, McGinley, SMMA, VWMA, Hamming, Adaptive (KAMA), MA Channel, MA Double, MA Triple, MA Multiple, Guppy |
+| Momentum (23) | Accelerator, ASI, Balance of Power, CMO, Connors RSI, Coppock, DPO, Fisher, KST, Majority Rule, Momentum, Price Oscillator, Rank Correlation, Relative Vigor, SMI Ergodic, TRIX, TSI, Ultimate, Correlation, Correlation Log, + crosses |
+| Volatility (16) | %B, BB Width, Historical, Close-to-Close, Zero Trend, O-H-L-C, Volatility Index, StdDev, StdError, StdError Bands, Choppiness, Chop Zone, Chaikin Volatility, Mass Index, RVI, Envelopes |
+| Trend (12) | Aroon, DMI, Vortex, Trend Strength, LinReg Slope, Price Channel, Chande Kroll, 52W H/L, Alligator, Fractal, Zig Zag, MA/EMA crosses |
+| Volume (9) | Ease of Movement, Elder's Force, Klinger, Volume Oscillator, Net Volume, PVT, Chaikin Oscillator, Advance/Decline, VPVR |
+| Price transforms (4) | Average Price, Median Price, Typical Price, Ratio, Spread |
+
+---
+
+## Shapes & Arrows
+
+### Already shipped: the line arrow
+
+**`'arrowMarker'`** is TradingView's Arrow — a line from tail to tip with a
+filled arrowhead. It was only ever *labelled* "Arrow Marker", which hid it. The
+label now reads **Arrow**.
+
+The `DrawingToolType` string is unchanged, and labels are i18n-overridable
+through `labels.drawingToolbar.tools`, so nothing breaks — but it is a
+user-visible string change worth knowing about.
+
+### Arrow Mark Left / Right — `'arrowMarkLeft'`, `'arrowMarkRight'`
+
+Single-click marks that point *at* a price level from the side — the horizontal
+siblings of `arrowUp` / `arrowDown`. Where those call out a move's direction,
+these call out a level: the arm runs along the price, so the mark reads as "this
+price, from the left" rather than "up from here".
+
+Fixed pixel geometry, not price-space — a marker is chrome and should stay the
+same size whatever the axis is doing. The hit box covers the whole glyph, stem
+and head, so you grab what you can see.
+
+### Curve — `'curve'`
+
+Two endpoints and a handle that bends the line between them: a **quadratic
+Bézier**, not a circular arc.
+
+The existing `'arc'` tool fits a circle through three points, and a circle's
+curvature is constant — it cannot leave one endpoint steeply and arrive at the
+other gently. A Bézier can, which is what you want for sketching a rounding top
+or a decelerating trend.
+
+One handle is exactly what a quadratic takes, so every position you can drag to
+maps to a curve, and every curve the tool can draw is reachable by dragging. A
+cubic would need a second handle to be fully controllable, or would hide half its
+shape. The handle and its guides are drawn only while selected.
+
+### Double Curve — `'doubleCurve'`
+
+An S, from the same three clicks as a single Curve. The chord is split at its
+midpoint and each half gets its own quadratic, bent by equal and **opposite**
+offsets — so one handle controls both bends, and dragging across the chord
+inverts the S.
+
+Deriving the second bend from the first, rather than asking for a fourth click,
+is the point: an S whose halves are set independently is just two curves. The
+shape only reads as one gesture if the halves stay symmetric, and making that
+automatic is cheaper for the user than making it their job.
+
+### Curve maths
+
+Exported, so a host can reproduce the same geometry:
+
+```ts
+import { quadraticAt, controlFromOffset, offsetFromHandle } from 'acttrader-charts';
+```
+
+`controlFromOffset` and `offsetFromHandle` are **true inverses**, both speaking
+in *apex* distance — how far the curve itself lands from the chord, not how far
+the control point does. A quadratic's apex sits halfway between chord and
+control, so the conversion doubles in one direction and halves in the other.
+
+### Native wrapper parity
+
+All four are `DrawingToolType` strings, so `setDrawingTool('doubleCurve')` works
+on [charts-android](../charts-android) and [charts-ios](../charts-ios) with no
+wrapper change.
+
+---
+
+## Projection & Measurement
+
+### Already shipped: Long Position / Short Position
+
+`'longPosition'` and `'shortPosition'` exist today and are complete risk/reward
+tools: three prices (entry, target, stop) drawn as a green profit zone and a red
+risk zone, with the money and quantity the account's risk budget implies. You
+place entry and target; the stop is materialised from the default reward:risk, so
+the common case is two clicks rather than three.
+
+They are gated behind `features.enableForecasting` and need `account` for money
+and quantity, and `instrument` for pips:
+
+```ts
+new ChartEngine({
+    container,
+    features: { enableForecasting: true },
+    account: { equity: 50_000, riskPercent: 1 },
+});
+```
+
+Deliberately **not** Trade-From-Chart — `setLevels` draws real broker orders and
+committing one sends it. These are drawings; nothing here reaches the broker.
+
+### Anchored VWAP — `'anchoredVwap'`
+
+Volume-weighted average price accumulated from a bar you pick: the average price
+everyone who traded since the anchor actually paid, which is what turns a swing
+high or an earnings gap into support.
+
+**This is not the existing `'anchoredVP'`.** That one is Anchored Volume
+*Profile* — a horizontal histogram of volume by price level, and its bar heights
+come from a hardcoded bell curve rather than from the feed. Anchored VWAP is a
+single line computed from real volume.
+
+Placed with one click, re-accumulating as data streams in. The series is
+exported:
+
+```ts
+import { anchoredVwapSeries } from 'acttrader-charts';
+
+const vwap = anchoredVwapSeries(bars, anchorIndex); // number[] | null
+```
+
+Two deliberate behaviours:
+
+- It uses the **(H+L+C)/3 typical price**, the convention VWAP is defined on —
+  not the close, which would make it a volume-weighted close.
+- It returns **`null` when the span carries no volume**, and the chart draws no
+  line. A VWAP without volume silently degrades into a running mean of typical
+  prices: it looks like a VWAP and is not one. A volume-less feed gets no line
+  rather than a plausible wrong one. The anchor dot is still drawn, so the
+  drawing stays selectable and deletable.
+
+### Forecast — `'forecast'`
+
+Three points: p1→p2 is what happened, p2→p3 is what you expect next. The base is
+solid, the forecast dashed, and a shaded cone opens from zero at p2 to half the
+base move's size at p3 — because a projection is exact where it starts and vague
+where it ends, and a bare line implies a precision no forecast has. A readout
+gives the projected change in price, percent and bars.
+
+That cone is what separates it from the existing `'projection'` tool, which
+extrapolates a trend line to the right edge with no second leg you control and no
+statement of confidence.
+
+### Bars Pattern — `'barsPattern'`
+
+Three points: p1 and p2 bracket the bars to copy, p3 anchors the copy. It draws
+real candles from the source bars, re-based by price **offset** rather than ratio
+— the tool is for asking "the same move, from here", not "a proportional move".
+
+The copy is drawn at reduced alpha inside a dashed bounding box. Without that it
+renders in the chart's own candle colours and becomes indistinguishable from real
+data, which is worse than useless.
+
+### Native wrapper parity
+
+All three new tools are `DrawingToolType` strings, so `setDrawingTool('forecast')`
+works on [charts-android](../charts-android) and [charts-ios](../charts-ios) with
+no wrapper change. Long/Short Position need `enableForecasting` in the native
+`init` payload, which both wrappers already expose.
+
+---
+
+## Patterns
+
+### XABCD Pattern — `'xabcdPattern'`
+
+The free-form harmonic, and the only one that shows its working.
+
+Every named harmonic in the library — Gartley, Bat, Butterfly, Crab, Shark,
+Cypher — draws the identical X→A→B→C→D zigzag and dashed XD line, differing only
+in colour. None of them measures or validates anything. XABCD assumes nothing
+instead: you place five pivots and it reports the ratios those pivots actually
+produce, so you can decide which harmonic the structure matches.
+
+That measurement is the whole point. Without it this would be an existing tool
+under a new name.
+
+| Ratio | Measured against | Why it matters |
+| --- | --- | --- |
+| `AB/XA` | the initial leg | the first retracement |
+| `BC/AB` | the AB leg | the counter-move |
+| `CD/BC` | the BC leg | the final leg's extension |
+| `AD/XA` | the whole XA move | what separates a Gartley (0.786) from a Butterfly (1.27) |
+
+It also shades the XAB and BCD triangles, which is what makes the shape readable
+at a glance — the zigzag alone is just four lines.
+
+The arithmetic is exported, so a host can auto-classify a pattern with the same
+numbers the chart draws:
+
+```ts
+import { xabcdRatios } from 'acttrader-charts';
+
+const chips = xabcdRatios(drawing.points);
+// → [{ from: 1, to: 2, text: 'AB/XA 0.600' }, …]
+```
+
+A leg of zero length has no defined ratio against it, so that entry is **omitted**
+rather than printed as `Infinity` or `NaN`, and ratios for pivots you have not
+placed yet simply do not appear.
+
+### Elliott Triple Combo (WXYXZ) — `'elliottTripleCombo'`
+
+The triple three: three corrective structures joined by two X waves, six points
+from an origin.
+
+There are now three neighbouring tools and the distinction is exact:
+
+| Tool | Points | Labels |
+| --- | --- | --- |
+| `'elliottWxy'` | 4 | the **double** three — W, X, Y |
+| `'elliottCombination'` | 7 | W, X, Y, X2, Z, X3, end |
+| `'elliottTripleCombo'` | 6 | 0, W, X, Y, X, Z |
+
+You asked whether the existing Combination tool already covers this. It partly
+does — but it takes **seven** points where a triple three has six, and numbers its
+connectors `X2`/`X3` where Elliott notation leaves both as `X`. A trader counting
+a triple three places five waves after the origin, and a tool demanding six
+leaves them with a pivot to park somewhere meaningless. This tool matches the
+count and the notation; the Combination tool is unchanged.
+
+Wave labels sit above a peak and below a trough, so they never land on the line
+that produced them.
+
+### Native wrapper parity
+
+Both are new `DrawingToolType` strings, so `setDrawingTool('xabcdPattern')` works
+on [charts-android](../charts-android) and [charts-ios](../charts-ios) with no
+wrapper change.
+
+---
+
+## Fibonacci & Gann
+
+Five tools added for TradingView parity. Each exists because it answers a
+question an existing tool in the same group cannot.
+
+| Tool | `DrawingToolType` | Points | vs. its neighbour |
+| --- | --- | --- | --- |
+| **Trend-Based Fib Time** | `'trendBasedFibTime'` | 3 | Fib Timezone measures from its own origin. This projects one leg's *duration* onto a different starting bar. |
+| **Fib Speed Resistance Arcs** | `'fibSpeedResistanceArcs'` | 2 | The Fan projects straight lines, so implied support stays proportional forever. Arcs curve, so it decays with distance. |
+| **Fib Wedge** | `'fibWedge'` | 3 | Fib Circles sweep a full turn from one centre. A wedge is bounded by two user-drawn rays. |
+| **Pitchfan** | `'pitchfan'` | 3 | A Pitchfork's tines run parallel — a fixed channel. A Pitchfan's radiate, so they spread with distance. |
+| **Gann Square Fixed** | `'gannSquareFixed'` | 2 | The plain Gann Square stretches to the drag box, so its diagonal is only 45° at one zoom. |
+
+```ts
+chart.setDrawingTool('fibWedge');
+```
+
+### Details that matter
+
+**Trend-Based Fib Time** — p1→p2 is the base leg and p3 is where projection
+starts, so the verticals answer *"if this leg took N bars, when do the Fibonacci
+multiples of N fall from here?"*. Lines outside the viewport are skipped rather
+than stroked and clipped. It stays inert until the third point lands and when the
+base leg has zero duration — there is nothing to project in either case.
+
+**Fib Speed Resistance Arcs** — drawn as **ellipses**, not circles, with the x and
+y radii taken separately from the trend's run and rise. A pixel-space circle
+would change shape the moment the price axis was rescaled, which makes the tool
+meaningless on a chart the user has zoomed. Only the half facing the trend is
+drawn; the half behind the origin would imply resistance before the move began.
+
+**Fib Wedge** — the sweep always takes the short way round, so a wedge never
+flips to the reflex angle when an edge crosses the ±π seam. Hit testing checks
+the angular span first, so a click at a matching radius but outside the wedge
+correctly misses.
+
+**Pitchfan** — rays are extended *forward* past the base, since that is the only
+part anyone trades off. Handle and base are dashed: construction, not signal.
+
+**Gann Square Fixed** — takes the **longer** side of the drag and uses it for
+both, so the 45° diagonal really is 45°. That is the premise of Gann's angles and
+worthless if the shape skews with the axes. The cost is that the box no longer
+matches the drag exactly — "fixed" means fixed *proportion*, not fixed size.
+
+### Native wrapper parity
+
+All five are new `DrawingToolType` strings, so `setDrawingTool('pitchfan')` works
+on [charts-android](../charts-android) and [charts-ios](../charts-ios) with no
+wrapper change.
+
+---
+
+## Cursors & Line Tools
+
+### Extending lines
+
+Four tools that differ from a Trend Line only in where they stop being drawn —
+which is exactly why they exist as separate tools rather than a style option.
+
+| Tool | `DrawingToolType` | What it does |
+| --- | --- | --- |
+| **Ray** | `'ray'` | Two anchors; continues past the second. |
+| **Extended Line** | `'extendedLine'` | Two anchors; continues past both. |
+| **Horizontal Ray** | `'horizontalRay'` | One click; a level that runs **forward only**. |
+| **Info Line** | `'infoLine'` | A trend line that permanently reports what it spans. |
+
+```ts
+chart.setDrawingTool('ray');
+```
+
+The extension is recomputed against the canvas every frame, so panning and
+zooming re-extend the line instead of dragging a stale endpoint around. Hit
+testing uses the *extended* segment, so the infinite part is clickable too — the
+user can grab what they can see. Anchor dots are drawn only at the anchors,
+never at the extended ends, because a dot at the canvas edge reads as a handle
+and there is nothing there to grab.
+
+**Horizontal Ray vs Horizontal Line** is the one worth calling out: a level drawn
+from the swing high that formed it should not be painted back across the history
+that preceded it, because that implies support which did not yet exist.
+
+**Info Line vs Ruler**: the Ruler is a transient measurement — drawn, read,
+discarded. An Info Line is a drawing you keep, so its readout travels with it and
+updates as either end is dragged. It reports price delta, percent, bar count,
+and — when `instrument` and bar timestamps are available — pips and calendar
+duration. Each is omitted rather than shown as a zero when it cannot be computed.
+
+### Cursors
+
+Pointer behaviour over the plot, **independent of the drawing tool**: switching
+mode never cancels a drawing in progress, and arming a tool never changes the
+mode.
+
+| `CursorMode` | Behaviour |
+| --- | --- |
+| `'cross'` | The default crosshair with its axis readouts. |
+| `'dot'` | A dot follows the pointer instead of two lines cutting across the candles. |
+| `'arrow'` | A plain pointer, no crosshair. |
+| `'demonstration'` | A laser trail that fades behind the pointer, for screen-sharing. Draws nothing permanent and creates no drawing. |
+| `'eraser'` | A click deletes the drawing under it. |
+
+```ts
+const chart = new ChartEngine({
+    container,
+    cursorMode: 'cross',                        // initial mode
+    features: { enableCursorModes: true },      // adds the Cursors group to the toolbar
+});
+
+chart.setCursorMode('eraser');
+chart.on('cursorModeChange', ({ mode }) => persist(mode));
+```
+
+`features.enableCursorModes` is a gate because it adds a **category** to a
+toolbar that hosts have laid out around its current contents. With it off the
+group is absent and the toolbar is exactly what it was — and the modes are still
+reachable from `setCursorMode()`, so a host can drive them from its own chrome
+without taking the group.
+
+Two details worth knowing:
+
+- **A drawing tool owns the cursor while armed.** It needs crosshair precision
+  whatever the mode says; clearing the tool hands the cursor back to the mode.
+- **The eraser consumes every click**, hit or miss. A miss must not fall through
+  to selecting or panning — that would be a surprising thing to do with an eraser
+  in hand. It deletes via select-then-delete, so it shares the undo history with
+  every other delete.
+
+### Value tooltip on long press
+
+```ts
+const chart = new ChartEngine({ container, valueTooltip: true });
+```
+
+A floating OHLCV readout beside a long press, on top of the crosshair that
+gesture already arms. The OHLC strip at the top of the chart carries the same
+numbers, but on a phone it is at the opposite end of the screen from the finger —
+the user has to look away from the thing they are pointing at.
+
+It flips to the other side of the touch rather than running off an edge, never
+takes pointer events (the drag is still in progress), and omits volume rather
+than printing a zero when the feed carries none. Default `false`.
+
+### Native wrapper parity
+
+The four line tools are new `DrawingToolType` strings, so `setDrawingTool('ray')`
+works on [charts-android](../charts-android) and [charts-ios](../charts-ios)
+unchanged.
+
+| JS | Android | iOS |
+| --- | --- | --- |
+| `setCursorMode(m)` | `setCursorMode(m)` | `setCursorMode(_:)` |
+| `cursorModeChange` | `BridgeEvent.CursorModeChange` | `.cursorModeChange` |
+| `cursorMode` at init | `Init(cursorMode = "…")` | `cursorMode:` argument |
+| `valueTooltip` | `Init(valueTooltip = true)` | `valueTooltip:` argument |
+| `features.enableCursorModes` | `Init(enableCursorModes = true)` | `enableCursorModes:` argument |
+
+---
+
+## Chart Types
+
+Thirteen time-based types plus five added for TradingView parity. The five split
+into two kinds, and the difference matters more than the list suggests.
+
+### HLC bars — `'hlc'`
+
+An ordinary per-bar series: the high-low range with a close tick and no open
+stub. Halves the ink of an OHLC bar, which is the point — on a dense chart the
+closes stay legible where full bars smear. Colour still comes from open vs close.
+
+### Price-transform types — `'renko'`, `'linebreak'`, `'kagi'`, `'pointfigure'`
+
+These are **not drawn per time bar.** A brick, block, kagi segment or P&F column
+forms when *price* moves far enough, which may take fifty bars or none at all.
+365 daily candles might be 24 Renko bricks or 15 P&F columns.
+
+So they are not renderers — the bar array itself is rebuilt. Each transform turns
+raw OHLCV into **synthetic** bars, one per visual element, which the rest of the
+chart then treats as ordinary bars. That is what keeps the feature small:
+viewport, zoom, price range, crosshair, the time axis, indicators and drawings
+all keep working unchanged. It also means **an indicator on a Renko chart is
+computed over the bricks**, not the underlying candles — same as TradingView.
+
+Three consequences worth knowing:
+
+- **The time axis is non-linear.** Labels show when each element *completed*.
+  Several elements completing on one bar get timestamps one millisecond apart so
+  drawing anchors and viewport restore keep working.
+- **Switching in or out refits the view**, because the old viewport indexes a
+  different number of elements.
+- **Market price still comes off the raw feed.** Trade levels and P&L price
+  against the real last close, never a brick top.
+
+### Parameters
+
+```ts
+const chart = new ChartEngine({
+    container,
+    series: 'renko',
+    seriesOptions: {
+        renko:       { boxSize: { kind: 'atr', length: 14 } },   // the default
+        lineBreak:   { lines: 3 },
+        kagi:        { reversal: { kind: 'percent', percent: 2 } },
+        pointFigure: { boxSize: { kind: 'fixed', size: 0.5 }, reversal: 3 },
+    },
+});
+
+chart.setSeriesOptions({ renko: { boxSize: { kind: 'fixed', size: 5 } } });
+```
+
+Every box/reversal size defaults to **ATR(14)**, not a fixed price, because a
+fixed box is meaningless until you know the instrument: ten points is noise on an
+index and a lifetime on a forex pair. `setSeriesOptions` merges, so retuning
+Renko leaves Kagi and P&F alone.
+
+| `BoxSizeMode` | Meaning |
+| --- | --- |
+| `{ kind: 'atr', length }` | Wilder ATR over the last `length` bars. Default `14`. |
+| `{ kind: 'fixed', size }` | A fixed price distance. |
+| `{ kind: 'percent', percent }` | A percentage of the latest close. |
+
+When a box cannot be sized — fewer than `length + 1` bars for the ATR, or a
+non-positive size — the transform returns **no elements** rather than guessing. A
+wrong box size does not look wrong; it looks like a different market.
+
+### The rules each type implements
+
+| Type | Rule |
+| --- | --- |
+| **Renko** | A brick prints when price closes a full box past the last brick's edge. Reversals need **two** boxes, not one — that two-box rule is what filters the noise. `source: 'highlow'` lets a bar's extremes print bricks instead of its close. |
+| **Line Break** | A block prints when the close clears the extreme of the last `lines` blocks (default 3). No box size at all — the reversal distance is whatever recent blocks span, so it widens automatically in volatile stretches. |
+| **Kagi** | **Direction** flips on a retrace of the reversal amount. **Thickness** flips on a break of the prior shoulder or waist. These are independent: a line can reverse repeatedly without ever changing thickness. |
+| **Point & Figure** | Columns of X's and O's on a box grid, built from each bar's **high and low** — high first in an X column, low first in an O column, so a bar that both extended and reversed is read in the order it happened. A new column needs `reversal` boxes (default 3). |
+
+### Using the transforms off-chart
+
+They are exported as pure functions, so a backtest or a server-side render gets
+byte-identical elements:
+
+```ts
+import { toRenko, toKagi, atrValue } from 'acttrader-charts';
+
+const { bars, meta } = toRenko(ohlcv, { boxSize: { kind: 'fixed', size: 5 } });
+```
+
+Each returns `{ bars, meta }`. `meta[i]` carries what cannot be read off the
+synthetic bar: Kagi's `thick`, P&F's `boxSize`, and `sourceBars` / `startTime`
+for every type.
+
+### Native wrapper parity
+
+The five types are new values of the same `series` string, so `setSeries('renko')`
+works on [charts-android](../charts-android) and [charts-ios](../charts-ios)
+unchanged. Parameters travel as a JSON object:
+
+| JS | Android | iOS |
+| --- | --- | --- |
+| `seriesOptions` at init | `Init(seriesOptionsJson = "…")` | `seriesOptionsJson:` init argument |
+| `setSeriesOptions(o)` | `setSeriesOptions(json)` | `setSeriesOptions(_:)` |
+
+---
+
+## Top-Toolbar Features
+
+Four opt-in features that bring the header in line with TradingView's: **indicator
+templates**, **saved chart layouts**, **Quick Search**, and **chart-settings
+templates with "Apply to all charts"**. Compare and Snapshot already shipped — see
+[Multi-Pane Layouts](#multi-pane-layouts) and the Compare section.
+
+Two rules apply to all of them:
+
+- **Nothing moves.** Every gate defaults to `false`, and with them off the chart's
+  DOM is unchanged. When enabled, each feature extends a flyout, popover or dialog
+  that already exists — no feature adds a header button (Quick Search can, but only
+  if you ask for one).
+- **The library persists nothing.** Saving emits an event carrying the complete
+  object; your app stores it and seeds it back. This is the same contract
+  `stateChange` follows, and it is what lets Android and iOS reuse the feature
+  without reimplementing storage twice.
+
+### Indicator templates
+
+Named, reusable indicator sets, listed in a **Templates** block at the foot of the
+indicators flyout.
+
+```ts
+const chart = new ChartEngine({
+    container,
+    enableIndicatorTemplates: true,
+    indicatorTemplates: loadFromStorage(),   // what you saved last session
+});
+
+chart.on('indicatorTemplateSaved', ({ template }) => persist(template));
+chart.on('indicatorTemplateDeleted', ({ id }) => forget(id));
+```
+
+| API | Does |
+| --- | --- |
+| `captureIndicatorTemplate(name)` | Saves the active indicators; emits `indicatorTemplateSaved`. Returns the template or `null`. |
+| `applyIndicatorTemplate(idOrName)` | Replaces the active indicators with the template's. Returns `false` if nothing matched. |
+| `deleteIndicatorTemplate(idOrName)` | Removes it; emits `indicatorTemplateDeleted`. |
+| `setIndicatorTemplates(list)` | Replaces the list the flyout shows. |
+| `getIndicatorTemplates()` | Reads it back (copies). |
+
+Saving twice under one name yields two templates — ids are de-duplicated
+(`my-set`, `my-set-2`), which is what users expect from "Save as".
+
+Rendered by the default `TopBar` and by `AdvancedToolbar`. The compact per-pane
+strip and the mobile header have no full indicators flyout, so they skip it.
+
+### Saved chart layouts
+
+A **saved layout** is a grid preset *plus* every pane's full `ChartState` — symbol,
+timeframe, series, indicators, drawings, viewport, compares. That is the difference
+from the preset grid already in the layout popover, which only picks a *shape*.
+
+Requires `enableMultipleLayouts`, since the section renders inside that popover.
+
+```ts
+const chart = new ChartEngine({
+    container,
+    enableMultipleLayouts: true,
+    enableSavedLayouts: true,
+    savedLayouts: loadFromStorage(),
+});
+
+chart.on('layoutSaved', ({ layout }) => persist(layout));
+chart.on('layoutApplied', ({ layout }) => mountPanes(layout));  // multi-pane hosts
+```
+
+| API | Does |
+| --- | --- |
+| `captureSavedLayout(name, paneId?)` | Saves the preset + this chart's state. Single-engine: one pane. |
+| `applySavedLayout(idOrName, paneId?)` | Applies the preset (emits `layoutChange`) then this pane's state. |
+| `deleteSavedLayout(idOrName)` | Removes it; emits `layoutDeleted`. |
+| `setSavedLayouts(list)` / `getSavedLayouts()` | Replace / read the list. |
+
+For a real multi-pane grid use `ChartGroup`, which sees every pane:
+
+```ts
+const layout = group.captureLayout('My Desk', chart.getLayoutPreset());
+persist(layout);
+for (const [, engine] of group.entries()) engine.setSavedLayouts(allLayouts);
+
+// restoring: mount the grid for layout.presetId yourself, then
+const { applied, missing } = group.applyLayout(layout);
+```
+
+`applyLayout` skips panes that aren't registered yet and returns them in `missing`,
+so a host that mounts lazily can create them and call again. Registered panes that
+the layout doesn't mention are left alone rather than cleared.
+
+### Quick Search
+
+A command palette over everything the chart can do: series types, timeframes,
+durations, indicators, drawing tools, saved templates and layouts, and the header
+actions.
+
+```ts
+const chart = new ChartEngine({ container, enableQuickSearch: true });
+```
+
+Opened with **Ctrl/⌘+K**, with **`/`**, or by `chart.openQuickSearch()`. It is
+keyboard-first and **adds no header button** — pass
+`quickSearch: { showButton: true }` if you want one. A bare `/` is ignored while
+the user is typing in any input, textarea, select, or contenteditable.
+
+Add your own commands beside the built-ins:
+
+```ts
+chart.registerCommand({
+    id:    'myapp.openTicket',
+    label: 'Open order ticket',
+    group: 'My App',
+    keywords: ['buy', 'sell', 'trade'],
+    run:   () => openTicket(),
+});
+
+chart.on('quickSearchCommand', ({ id }) => track(id));
+```
+
+Namespace your ids so a future built-in can't collide. `matchCommands`,
+`scoreCommand` and `groupCommands` are exported if you want the same ranking in
+your own UI: exact label beats prefix beats word-start beats substring, with
+keyword and group hits last, and ties keep their original order so the list never
+reshuffles unpredictably as the user types.
+
+### Chart-settings templates + Apply to all charts
+
+Named snapshots of everything the Chart Settings dialog edits, plus a switch to
+push the current settings to every other chart. Both render in the dialog's
+footer — no new button anywhere.
+
+```ts
+const chart = new ChartEngine({
+    container,
+    enableSettingsTemplates: true,
+    settingsTemplates: loadFromStorage(),
+});
+
+chart.on('settingsTemplateSaved', ({ template }) => persist(template));
+
+chart.on('chartSettingsApplied', ({ settings, applyToAll }) => {
+    // This chart already applied them. Only the fan-out is yours:
+    if (applyToAll) group.applySettingsToAll(settings, thisPaneId);
+});
+```
+
+| API | Does |
+| --- | --- |
+| `getChartSettings()` / `applyChartSettings(s)` | Read / apply a settings snapshot. Every route — dialog, template, apply-to-all, bridge — goes through `applyChartSettings`. |
+| `captureSettingsTemplate(name)` | Saves the current settings; emits `settingsTemplateSaved`. |
+| `applySettingsTemplate(idOrName)` | Applies a saved one. |
+| `deleteSettingsTemplate(idOrName)` | Removes it. |
+| `setSettingsTemplates(list)` / `getSettingsTemplates()` | Replace / read the list. |
+| `ChartGroup.applySettingsToAll(settings, fromPaneId?)` | Applies to every other pane. Not gated on a `sync` toggle — it is an explicit one-shot action, not continuous mirroring. |
+
+### Native wrapper parity
+
+All four features, plus snapshot capture, are exposed by
+[charts-android](../charts-android) and [charts-ios](../charts-ios). Templates and
+layouts cross the bridge as opaque JSON strings: the app stores what the chart
+handed it and sends the same string back, so neither Kotlin nor Swift has to mirror
+a `ChartState` that only the chart interprets.
+
+| JS | Android | iOS |
+| --- | --- | --- |
+| `enableIndicatorTemplates` | `Init(enableIndicatorTemplates = true)` | `HeaderFeatures(enableIndicatorTemplates: true)` |
+| `captureIndicatorTemplate(name)` | `captureIndicatorTemplate(name)` | `captureIndicatorTemplate(_:)` |
+| `enableSavedLayouts` | `Init(enableSavedLayouts = true)` | `HeaderFeatures(enableSavedLayouts: true)` |
+| `enableQuickSearch` / `openQuickSearch()` | `openQuickSearch()` | `openQuickSearch()` |
+| `enableSettingsTemplates` | `Init(enableSettingsTemplates = true)` | `HeaderFeatures(enableSettingsTemplates: true)` |
+| `chartSettingsApplied` event | `BridgeEvent.ChartSettingsApplied` | `.chartSettingsApplied` |
+| `chart.toDataUrl()` | `requestSnapshot()` → `BridgeEvent.Snapshot` | `requestSnapshot()` → `.snapshot` |
+
+On mobile there is no Ctrl/⌘+K, so Quick Search is opened with the
+`openQuickSearch` command from your own toolbar.
+
+---
+
+## Chart Settings
+
+Six settings TradingView has and ActCharts did not, behind
+`features.enableChartSettings`. The gate adds three tabs — **Status Line**,
+**Scales**, **Canvas** — to the Chart Settings dialog and a bar-colouring choice
+to Appearance. Every one of them is also a `ChartConfig` option and a
+`ChartEngine` method, so a host can drive them from its own chrome and leave the
+dialog as it was.
+
+```ts
+const chart = new ChartEngine({
+    container,
+    features: { enableChartSettings: true },
+    statusLine: { barChange: true },
+    scales: { highLowLabels: true, pricePrecision: 4, timezone: 'Asia/Tokyo' },
+    canvas: { gridVertical: false, watermarkVisible: true },
+    barColorSource: 'previousClose',
+});
+```
+
+### Status line
+
+What the legend above the chart shows.
+
+| Field | Default | Shows |
+| --- | --- | --- |
+| `symbol` | `true` | The instrument name and its stream dot |
+| `ohlc` | `true` | O / H / L / C of the hovered bar |
+| `barChange` | **`false`** | Absolute and percent change, e.g. `+1.68 (+0.96%)` |
+| `volume` | `true` | V, when the feed carries it |
+
+`barChange` is the one default of `false`: it is a new readout, and turning it on
+by itself would change a legend hosts have laid out around. **Change is measured
+against the previous bar's close**, which is what "the change" means on every
+quote screen — against this bar's open it would only restate the candle's colour.
+
+### Scales and lines
+
+```ts
+chart.setScalesSettings({ lastPriceLabel: false, highLowLabels: true });
+```
+
+| Field | Default | Effect |
+| --- | --- | --- |
+| `lastPriceLabel` | `true` | The live price tag and its dashed line |
+| `bidLabel` / `askLabel` | follows config | The bid / ask tags |
+| `highLowLabels` | `false` | Tags at the extremes of the **visible** range |
+| `timeAxisCountdown` | follows `showCandleCountdown` | Countdown on the time axis |
+| `pricePrecision` | `null` | Decimal places; null infers from the feed |
+| `timezone` | `'UTC'` | IANA name for axis, crosshair and tooltips |
+
+Bid and ask fall through to the `showBidLine` / `showAskLine` config they
+duplicate, so the dialog and the existing runtime setters stay **one switch**
+rather than two that can disagree.
+
+High/low are measured over what is on screen, not the whole dataset: a tag for a
+high six months out of view marks a line the user cannot see and cannot scroll
+to without losing it.
+
+### Price precision
+
+```ts
+chart.setPricePrecision(4);     // pin
+chart.setPricePrecision(null);  // back to inferring from the feed
+```
+
+One accessor feeds all eleven places the chart writes a price — axis, legend,
+tooltips, crosshair, drawings, trade levels — so an override cannot apply to
+some and not others. A price axis reading `1.2345` beside a tooltip reading
+`1.23` is worse than either choice on its own.
+
+**It deliberately does not move pip size.** A pip is a property of the contract;
+asking the axis for fewer decimals is a display choice, and the Ruler must keep
+saying what a move is actually worth. Pip size still comes from `InstrumentSpec`
+and, failing that, from the precision *inferred* from the data.
+
+### Timezone
+
+`setTimezone(tz)` already existed; it is now in the dialog, carried in
+`ChartSettingsSnapshot`, and emits `timezoneChange`. `'local'` resolves to the
+device zone immediately, so `getTimezone()` always returns a real IANA name.
+
+### Canvas
+
+```ts
+chart.setCanvasOptions({ gridVertical: false, watermarkVisible: true, watermarkSize: 128 });
+```
+
+| Field | Default |
+| --- | --- |
+| `gridHorizontal` / `gridVertical` | `true` |
+| `watermarkVisible` | `false` |
+| `watermarkText` | `''` — empty uses the current symbol |
+| `watermarkSize` / `watermarkOpacity` | `72` / `0.06` |
+| `crosshairStyle` | `'dashed'` |
+| `crosshairWidth` | `1` |
+
+Colours stay in `setCanvasColors`, which was already plumbed per theme;
+`gridVertical` and `watermark` are new entries in `CanvasColorSettings` and fall
+back to `grid` and `axisText`.
+
+**The watermark draws above the grid and below everything else.** Painted after
+the series it would tint the candles, and the point of it is to sit behind them.
+Crosshair dash lengths scale with the width, or a 4px dash on a 4px line reads as
+a solid bar.
+
+### Colour bars based on previous close
+
+```ts
+chart.setBarColorSource('previousClose');
+```
+
+Whether a bar is "up" against its own open (the default) or against the previous
+bar's close. The two disagree constantly — a gap-up bar that sells off all
+session is up on one rule and down on the other — which is why it is a setting
+and not a fix.
+
+Applies to candles, hollow candles, bars, HLC bars, columns **and the volume
+pane together**: they are one reading of the same market, and a volume pane
+disagreeing with the candles above it is a bug, not a setting. Heikin Ashi,
+Renko, Kagi and Point & Figure are unaffected — direction is intrinsic to what
+those transforms compute.
+
+Eight series each carried their own `close >= open`; they now share
+`computeUpFlags()`, which the engine calls once per frame. It takes the bar
+*before* the visible slice, because the renderers only ever see what is on
+screen — without it the leftmost bar would have nothing to compare against and
+would flip colour as the user panned it into view. At the very start of the data,
+where no earlier bar exists, that one bar falls back to open-vs-close.
+
+### Persistence
+
+All six ride in `ChartSettingsSnapshot`, so they are covered by settings
+templates and "Apply to all charts" for free. **Absent is meaningful**: a
+template saved before these fields existed applies as "change nothing", not as
+"reset everything to its default" — otherwise re-applying an old template would
+silently rearrange the chart.
+
+
+## Bottom Bar & Price Scale
+
+Five TradingView controls, behind `features.enableScaleControls`. The gate adds
+a cluster to the left of the duration buttons — **Go to date**, a **timezone**
+selector, and **%**, **log**, **auto** — and needs `showBottomBar: true`, since
+the duration bar is off by default. Each is also a `ChartEngine` method, so a
+host can drive them from its own chrome and leave the bar as it was.
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│  📅  │  UTC ⌄  │  %  log  auto          1D 5D 1M 3M 6M 1Y 5Y All      │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+All five are ordinary buttons styled like the duration buttons beside them, and
+the two that need input open a themed popover above the bar. **No native
+`<input type="date">` or `<select>`**: both take their colours from the
+operating system, so in a dark chart they rendered as pale boxes with a browser
+calendar glyph — the one part of the bar that could not be themed. The menus
+open *upward*, since the bar is the last row on screen.
+
+```ts
+const chart = new ChartEngine({
+    container,
+    showBottomBar: true,
+    features: { enableScaleControls: true },
+    priceScaleMode: 'log',
+    autoScale: true,
+});
+```
+
+### Go to a specific date
+
+```ts
+chart.goToDate('2024-03-01');      // ISO, a Date, or unix ms
+```
+
+The calendar button opens a date field and a **Go**; the method behind it
+centres the **nearest** bar and returns its index, or `null` when there is no
+data. Nearest rather than exact because the date a user types is rarely a bar —
+it falls on a weekend, a holiday, or between two intraday bars — and refusing to
+move is a worse answer than landing beside it. Binary search, so it costs
+nothing on a long history. Emits `goToDate` with the bar it settled on.
+
+### Timezone selector
+
+The bottom-bar button shows the current zone's short name and opens a checked
+list. It writes through `setTimezone()`, the same path the Scales tab and the
+config option use, so all three stay in step. `'local'` resolves to
+the device zone immediately — `getTimezone()` always returns a real IANA name.
+
+### Price scale modes
+
+```ts
+chart.setPriceScaleMode('log');      // 'normal' | 'log' | 'percent'
+```
+
+**One choice, not three flags.** Log and percent are different answers to the
+same question, and a chart in both at once has no meaning. Clicking the active
+button returns to `'normal'`, so the pair works as a toggle rather than a trap.
+
+#### Logarithmic
+
+Equal ratios get equal height: a move from 10 to 20 occupies the same space as
+one from 100 to 200. On a series running 1 → 1000 the pixel gaps between the
+decade marks go from **49.8px and 497.3px** linear to **156.4px and 156.4px**
+log, and an exponential series renders as a straight line.
+
+The mode is carried on the **`PriceRange`**, not on the `ScaleManager`:
+
+```ts
+interface PriceRange { min: number; max: number; log?: boolean }
+```
+
+One manager serves the price pane and every sub-pane, and an RSI drawn on a log
+axis would be nonsense. Every price→pixel call already passes a range, so putting
+the flag there made series, drawings, indicators, the crosshair and hit-testing
+all log-aware **without changing a single call site**.
+
+**Log needs a positive range.** `isLogRange()` falls back to linear when `min <= 0`
+rather than refusing to draw, so an instrument that trades through zero quietly
+keeps working. A manual zoom-out that drags the displayed minimum below zero is
+clamped instead, because falling back there would make the chart snap between two
+mappings in the middle of a drag.
+
+**Ticks are the 1/2/5 × 10ⁿ series per decade**, thinned by *pixel* distance
+rather than by value — a decade occupies the same height whether it runs 1→10 or
+1000→10000. A range inside a single decade falls back to the linear generator,
+since over a span that narrow the two mappings are within a pixel of each other
+and linear ticks read better.
+
+Label precision is computed **per tick** from its own neighbours. One precision
+taken from the first pair would render `500` as `500.0` and `0.2` as `0.2` in the
+same column.
+
+#### Percent
+
+Every price re-expressed as percent change from the first visible bar's close,
+with `+0.00%` emphasised on the axis. It reuses the transform compare mode
+already had, with no second series to combine against, so panning re-bases the
+way TradingView's percent scale does rather than pinning to the start of history.
+
+### Auto scale
+
+```ts
+chart.setAutoScale(false);   // freeze the Y range
+```
+
+Switching it off freezes whatever is on screen *now*, so the chart does not jump
+at the moment the user asks it to stop moving. A manual axis drag still wins —
+turning auto off should not also take away the ability to move the axis by hand.
+
+This is separate from the implicit manual mode a price-axis drag already
+produced: that one is entered by dragging and left by resetting, while this is a
+switch the user holds across pans and timeframe changes.
+
+
+## Side Panels
+
+A right-hand docked panel with two tabs, behind `features.enableSidePanels`.
+
+```
+┌──────────────────────────┐
+│ Data Window │ Objects │✕ │
+├──────────────────────────┤
+│ Date          12 Aug 2026│
+│ Open               149.73│
+│ Close              148.56│
+│ Change    -1.17 (-0.78%) │
+│ MA(20)             150.56│
+│ MACD(12, 26, 9)          │
+│   MACD               1.22│
+│   Signal             1.84│
+│   Histogram         -0.62│
+└──────────────────────────┘
+```
+
+```ts
+const chart = new ChartEngine({
+    container,
+    features: { enableSidePanels: true },
+});
+
+chart.setSidePanelTab('objects');
+chart.setSidePanelVisible(false);     // the ✕ does this too
+```
+
+The panel is **docked, not floating**: both tabs are read while looking at the
+chart, and a floating window would cover the candles the numbers describe.
+
+**Closing it collapses it to an icon rail, it does not hide it.**
+
+```
+ expanded (232px)          collapsed (30px)
+┌──────────────────┐             ┌──┐
+│ Data │ Objects │✕│             │ ▦ │  ← Data Window
+├──────────────────┤             │ ◈ │  ← Objects
+│ …                │             │   │
+└──────────────────┘             └──┘
+```
+
+A panel that vanished completely would leave nothing to click to get it back,
+stranding the feature behind a command palette. The rail keeps 30px and gives
+the chart the other 202px; the `ResizeObserver` already watching `canvasWrap`
+resizes the canvases for free. Each rail icon opens straight onto *its* tab
+rather than reopening whatever was last showing, and the last-opened one stays
+marked so reopening is a single click on the icon already highlighted.
+
+`setSidePanelVisible(false)` is the same operation as the ✕ — expanded versus
+rail. `features.enableSidePanels` is what removes the panel entirely.
+
+### Data Window
+
+The bar under the cursor — or the last bar when the cursor is off the plot —
+followed by one block per visible indicator, refreshed from the render pass so
+it coalesces with the animation frame instead of firing on every pointer event.
+
+Values come from the engine's existing per-instance result cache, which is a
+full-length array indexed by bar, so nothing is recomputed to fill the panel.
+Only indicators that are actually being recomputed are listed: a hidden or
+timeframe-locked instance holds a stale cache and showing it would present old
+numbers as current.
+
+**Indicator fields are named by what they are.** `IndicatorResult` has five
+fixed slots — `value`, `upper`, `lower`, `signal`, `histogram` — and indicators
+do not agree on what they mean. MACD puts its signal line in `upper` and its
+histogram in `lower`, where Bollinger puts bands in both, so labelling the slots
+generically would print `Upper 1.84` for a MACD signal. A small table names the
+ones that differ; everything else falls back.
+
+A single-line indicator renders as one `MA(20): 150.56` row rather than a
+heading with one orphan beneath it. One still warming up shows a dash, because
+omitting the block would read as the indicator having been removed.
+
+Rows use tabular figures so the value column does not jitter as digits change
+under a moving crosshair, and the panel **reconciles rather than rebuilds** —
+it keys on the row labels and, when they are unchanged, writes only the text.
+
+### Object Tree
+
+Everything on the chart, grouped, with per-row show/hide, lock and remove.
+Clicking a drawing row selects it; clicking an indicator row opens its settings.
+Empty groups are omitted rather than shown as a zero.
+
+Drawing names come from `labels.drawingToolbar.tools` — the toolbar's own label
+map, so the tree is localised by the same override a host already supplies. A
+text tool shows its first line beside the type name, clipped, since a Table or
+Note carries several and the rest would push every other row off the panel.
+
+Indicators get **no lock control**: there is nothing to lock. The panel reads an
+absent `locked` as exactly that rather than needing a flag.
+
+### New per-object primitives
+
+The manager only had bulk operations, so these are new:
+
+```ts
+chart.setDrawingVisible(id, false);
+chart.setDrawingLocked(id, true);
+chart.deleteDrawing(id);            // not "select it, then delete"
+chart.selectDrawing(id);            // null clears
+chart.toggleIndicatorVisibility(instanceId);
+```
+
+`deleteDrawing` is separate from `deleteSelected()` on purpose: selecting fires
+`onSelectionChange`, which opens the style popover on a drawing that is about to
+disappear. Hiding or locking the selected drawing deselects it, the way the bulk
+operations already did — a selection box floating over nothing, with a popover
+attached, is worse than losing the selection. All three take an undo snapshot.
+
+### Reopening
+
+Click either rail icon. Three Quick Search commands do the same from the
+keyboard: **Open Data Window**, **Open Object Tree**, **Toggle side panel**.
+
+### Rendering the data yourself
+
+`buildDataWindow()` and `buildObjectTree()` are exported as pure functions, and
+`SidePanel` takes their output. A host can render the same rows in its own
+chrome, or feed the panel from somewhere other than the chart.
+
+
+## Custom Indicator
+
+Implement `IIndicator` and pass it to `addIndicator()`:
+
+```ts
+import type { IIndicator, OHLCVBar, IndicatorResult } from 'acttrader-charts';
+
+class MyIndicator implements IIndicator {
+    name       = 'MyInd';
+    color      = '#e91e63';
+    pane       = 'sub' as const;  // 'main' = overlay, 'sub' = dedicated pane
+    paneHeight = 80;
+
+    compute(data: OHLCVBar[]): IndicatorResult[] {
+        return data.map((bar, i) => ({ index: i, value: bar.close }));
+    }
+
+    render(ctx, results, scale, viewport, chartHeight) {
+        // draw with ctx (Canvas 2D)
+    }
+}
+
+chart.addIndicator(new MyIndicator());
+```
+
+---
+
+## Build & Dev
+
+```bash
+npm run dev        # Vite dev server with demo chart
+npm run build      # ESM + CJS via tsup → dist/
+npm run test       # Vitest unit tests
+npm run typecheck  # tsc --noEmit
+npm run lint       # ESLint
+```
+
+---
+
+## License
+
+MIT
+
+## Bar Replay
+
+Replay history bar by bar, as TradingView does. `enableReplay: true` adds a
+**Replay** button to the header (simple and advanced layouts); it opens a
+control strip under the chart:
+
+```
+⇤ Select bar ▾ │ ▷  ▷|  1x  1D │ ▷▷|                                        ✕
+```
+
+- **Select bar** — a cut line with a scissors badge follows the pointer; click
+  a bar and everything from it onward is hidden. The ▾ menu also offers
+  **Select date…**, **First available date** and **Random bar**.
+- **▷ / ▷|** — play at the chosen speed (`0.1x` – `10x` bars per second) or
+  step one bar forward. Keyboard: `Shift+→` step, `Shift+↓` play/pause,
+  `Esc` leaves select mode.
+- **▷▷|** — jump to real time: every hidden bar comes back, including live
+  bars built while the replay ran. **✕** closes the strip.
+
+Live ticks keep updating the hidden series during a replay, so nothing is
+lost; a `loadData()` during a replay (timeframe or symbol change) keeps the
+replay date. Default `false`; without it nothing changes.
+
+```ts
+const chart = new ChartEngine({ container, enableReplay: true });
+
+// Drive it from code (works without the header button too):
+chart.openReplay();                 // show the strip, arm "Select bar"
+chart.startReplay('2026-06-01');    // hide bars after this date (number | Date | string)
+chart.setReplaySpeed(3);            // bars per second
+chart.playReplay(); chart.pauseReplay(); chart.replayStepForward();
+chart.exitReplay();                 // back to real time, strip stays open
+chart.closeReplay();                // back to real time and close the strip
+chart.isReplayActive();
+
+chart.on('replayStart', ({ time }) => { /* bars after `time` are hidden */ });
+chart.on('replayStep',  ({ time }) => { /* one more bar revealed */ });
+chart.on('replayEnd',   ({ time }) => { /* last hidden bar revealed */ });
+chart.on('replayExit',  () => { /* live chart is back */ });
+```
+
+On Android and iOS the same controls are bridge commands — `openReplay`,
+`closeReplay`, `startReplay { time }`, `playReplay`, `pauseReplay`,
+`replayStepForward`, `setReplaySpeed { barsPerSecond }`, `exitReplay` — with
+`enableReplay` on `init`; the four events above arrive through the bridge and the
+mobile header gets its own Replay button. See the `charts-android` and
+`charts-ios` READMEs for the Kotlin / Swift calls.
+
+## Two-finger measure (mobile)
+
+Hold two fingers on the chart and it shows what the TradingView app shows: a
+pill over the range with the **close and date under each finger** and, between
+them, the **change in price and percent**, coloured by direction; a vertical
+line and a dot on the close mark each finger and the range is tinted. Moving
+the fingers moves the measurement; lifting either finger ends it. Pinch still
+zooms — the measure only starts once both fingers have rested for ~0.3 s.
+
+```ts
+new ChartEngine({ container, enableTwoFingerMeasure: true });
+
+chart.on('twoFingerMeasure', ({ phase, startTime, endTime, startClose, endClose, change, changePercent, bars }) => {
+  // phase: 'start' | 'update' | 'end'
+});
+```
+
+Touch-only, so desktop is unaffected. Default `false`. On Android / iOS set
+`enableTwoFingerMeasure` on `init`; the event arrives through the bridge.