acttrader-charts 1.3.0-beta.2 → 1.3.0-beta.20

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
@@ -333,13 +346,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 +369,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.
+- **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 +478,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 +501,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 +510,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,14 +521,23 @@ 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`. |
 | `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 and the compact per-pane strip): 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 |
+| `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 |
@@ -430,13 +548,120 @@ chart.on('orderLineMoved', ({ label, fromTimestamp, toTimestamp, data }) => {
 | `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). 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 +702,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 +780,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 +827,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 +877,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 +913,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,8 +922,15 @@ 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.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
 chart.setTimezone(tz: string): this                                // change display timezone at runtime
 chart.setVolume(show: boolean): this
@@ -722,6 +969,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 +978,33 @@ 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()`.
+
 ### Viewport
 
 ```ts
@@ -888,6 +1161,37 @@ 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`. With `bracketLabelMode: 'amount'`
+it reads `SL -$290.80` — the money the position gains or loses if that bracket
+is hit, currency symbol in front.
+
+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 +1224,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 +1304,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 +1328,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 +1353,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 +1365,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