acttrader-charts 1.3.0-beta.26 → 1.3.0-beta.27

package/README.md

@@ -1523,6 +1523,1398 @@ The composite excludes trade levels (positions, SL/TP) — same rule as `chart.t
 
 ---
 
+## Icons & Drawing Toolbar Options
+
+### 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
+const chart = new ChartEngine({
+    container,
+    features: { enableIconTools: true },
+});
+chart.setDrawingTool('icon');   // uses the last glyph picked
+```
+
+#### The picker
+
+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.
+
+```
+┌────────────────────────────────┐
+│ 😊 🐻 🍔 🏀 🚀 💡 ❤️ 🏳️        │  category tabs
+├────────────────────────────────┤
+│ 😀 😃 😄 😁 😆 😅 🤣 😂         │
+│ 🙂 🙃 😉 😊 😇 🥰 😍 🤩         │  scrolling grid
+├────────────────────────────────┤
+│   Emojis   Stickers   Icons    │  kind tabs
+└────────────────────────────────┘
+```
+
+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).
+
+---
+
+## Notes & Text
+
+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.
+
+---
+
+## Indicator Library
+
+**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()`: