openalgo-charts 1.0.8 → 1.0.10

package/README.md

@@ -4,11 +4,11 @@
 
 **A from-scratch, dependency-free HTML5-canvas charting engine for OpenAlgo.**
 
-Professional interactive financial charts, on-chart trading, and live data - in under 40 KB Brotli, with zero runtime dependencies.
+Professional interactive charts, indicators, drawing tools, order flow, and on-chart trading — six lazy-loaded tiers, zero runtime dependencies, ~33 KB Brotli for the base engine.
 
 [![npm version](https://img.shields.io/npm/v/openalgo-charts.svg?color=cb3837&label=npm)](https://www.npmjs.com/package/openalgo-charts)
 [![license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
-[![bundle](https://img.shields.io/badge/brotli-~33%20KB%20base%20%C2%B7%20~58%20KB%20full-brightgreen.svg)](./ARCHITECTURE.md)
+[![bundle](https://img.shields.io/badge/brotli-33%20KB%20base%20%C2%B7%2058%20KB%20all%20tiers-brightgreen.svg)](#size-budget)
 [![tests](https://img.shields.io/badge/tests-468%20passing-brightgreen.svg)](#develop)
 [![dependencies](https://img.shields.io/badge/runtime%20deps-0-brightgreen.svg)](#principles)
 
@@ -30,7 +30,7 @@ Right-click the chart to place market / limit / stop orders, drag the order and
 
 ## Examples gallery
 
-Every chart in the [live gallery](https://marketcalls.github.io/openalgo-charts/examples) is the real library running in your browser - switch tabs, hover the crosshair, drag the order lines. What you see is the code that ran.
+Every chart in the [live gallery](https://marketcalls.github.io/openalgo-charts/examples) is the real library running in your browser - switch tabs, hover the crosshair, drag the order lines, place a drawing. What you see is the code that ran.
 
 <p align="center">
   <img src="docs/demo1.png" alt="Chart-type switcher, custom themes, data tooltips, and event markers" width="49%" />
@@ -54,27 +54,81 @@ const chart = createChart(document.getElementById('chart'));
 chart.addSeries('candlestick').setData(generateBars(1700000000, 200, 3600));
 ```
 
-Loadable tiers - lazy-load only what you use:
+## Tiers
 
-| Import | Contents |
-|---|---|
-| `openalgo-charts` | Base engine + all standard chart types, indicators, primitives, trading overlay |
-| `openalgo-charts/trade` | On-chart order/position/bracket tools + DOM ladder |
-| `openalgo-charts/transform` | Renko, Range bars, Point &amp; Figure, Kagi, Line Break, Heikin Ashi |
-| `openalgo-charts/profile` | Volume Profile, Market Profile (TPO), Footprint, Order flow |
-| `openalgo-charts/indicators` | 18 built-in indicators + the Tier-2 (external-data) contract |
-| `openalgo-charts/draw` | 18 drawing tools + a headless drawing controller |
+Import only what you use. Each tier is a separate bundle that registers into the base engine's registries, so the cost of a feature you don't load is zero.
+
+| Import | Contents | Brotli |
+|---|---|---|
+| `openalgo-charts` | Engine, 13 chart types, panes &amp; scales, primitives, registries, chart state, trading overlay, OpenAlgo feeds | 32.7 KB |
+| `openalgo-charts/indicators` | 18 built-in indicators + the Tier-2 (external-data) contract | 4.5 KB |
+| `openalgo-charts/draw` | 18 drawing tools + a headless drawing controller | 6.3 KB |
+| `openalgo-charts/transform` | Heikin Ashi, Renko, Range bars, Line Break, Point &amp; Figure, Kagi | 2.7 KB |
+| `openalgo-charts/profile` | Volume Profile, Market Profile (TPO), Footprint, order flow | 5.5 KB |
+| `openalgo-charts/trade` | Order / position / bracket tools + DOM ladder | 6.6 KB |
+
+Everything together is **58 KB Brotli**.
 
 ## What's built
 
-- **Chart types:** candles, hollow/volume candles, bars, high-low, line, line+markers, step, area, HLC-area, baseline, columns, histogram.
-- **Transforms:** Heikin Ashi, Renko, Range bars, Line Break, Point &amp; Figure, Kagi.
-- **Profiles &amp; order flow:** Volume Profile, Market Profile (TPO), Footprint, cumulative delta.
-- **Indicators:** 18 built-ins via `chart.addIndicator(...)` - SMA, EMA, WMA, VWAP, Bollinger, Supertrend, Parabolic SAR, Ichimoku, RSI, MACD, Stochastic, ADX/DMI, CCI, MFI, ATR, Volume, OBV, A/D - plus a registry for your own, and a Tier-2 contract for indicators with external data (open interest, CVD).
-- **Trading:** order/position/bracket lines, live P&amp;L, one-click + drag-to-modify, OCO, validation, analyzer mode, and a depth-of-market ladder (5 to 200 levels).
-- **Drawing tools:** 18 tools (trend/ray/fib/channel/position/measure/text/...) with a headless controller - placement, selection, per-anchor drag, magnet snap, undo/redo, and persistence through the chart state.
-- **Panes:** draggable dividers, move/maximize/remove, and TradingView-style pane legends with inline show-hide / settings / delete controls.
-- **Live + historical** OpenAlgo data (REST history + WebSocket ticks with auto-reconnect), a unified `chart.on(...)` event bus, markers/signals, earnings/dividend/expiry event markers, and custom price/time formatters.
+### Chart types &amp; transforms
+Candles, hollow and volume candles, OHLC bars, high-low, line, line+markers, step, area, HLC-area, baseline, columns, histogram — plus Heikin Ashi, Renko, Range bars, Line Break, **Point &amp; Figure** (fixed / percent / ATR box sizing, high-low or close construction), and Kagi.
+
+### Indicators
+
+```ts
+import 'openalgo-charts/indicators';
+
+chart.addIndicator('bollinger');                      // overlays the price pane
+const macd = chart.addIndicator('macd', { fastPeriod: 8 });   // gets its own pane
+macd.setSettings({ 'macd:width': 2, 'macd:lineStyle': 'dashed' });
+```
+
+18 built-ins: SMA, EMA, WMA, VWAP, Bollinger Bands, Supertrend, Parabolic SAR, Ichimoku Cloud, RSI, MACD, Stochastic, ADX/DMI, CCI, MFI, ATR, Volume, OBV, A/D.
+
+The chart owns the whole lifecycle — series, pane placement, reference levels, fixed ranges (RSI 0..100), recompute on data change, teardown. Every plot gets colour, opacity, thickness, and line style for free, generated from the descriptor. Write your own with `registerIndicator`, or use the **Tier-2 contract** for indicators whose data isn't derived from OHLCV (open interest, CVD, any external feed).
+
+### Drawing tools
+
+```ts
+import { DrawingController } from 'openalgo-charts/draw';
+
+const draw = new DrawingController(chart, { magnet: true });
+draw.setTool('trend-line');   // the next two clicks place it
+```
+
+18 tools: trend line, ray, extended line, arrow, horizontal line/ray, vertical line, cross line, rectangle, ellipse, parallel channel, fib retracement/extension, long/short position (with R:R and risk-based sizing), measure, text, path.
+
+Headless by design — no toolbar, no dialogs. Placement with live preview, selection, whole-shape and per-anchor dragging, magnet snap to O/H/L/C, undo/redo (a drag is one step), and persistence. Anchors are `{ time, price }`, never pixels, so they survive zoom and resolve inside collapsed session gaps and past the last bar.
+
+### Panes &amp; legends
+Draggable pane dividers, move / maximize / remove, and TradingView-style pane legends showing one reading per plot in that plot's own colour, with inline show-hide / settings / move / delete controls revealed on hover.
+
+### Trading
+Order, position, and bracket lines with live P&amp;L, one-click and drag-to-modify, OCO, validation, an order state machine, analyzer (sandbox) mode, and a depth-of-market ladder (5 to 200 levels).
+
+### Profiles &amp; order flow
+Volume Profile, Market Profile (TPO), Footprint, and cumulative delta.
+
+### State
+`chart.getState()` / `chart.restoreState()` capture the viewport, grid, panes, price scales, indicator instances, and drawings as one JSON payload — saved layouts and templates with no extra storage plumbing.
+
+### Data
+OpenAlgo REST history + WebSocket ticks with auto-reconnect and resubscribe, live candle aggregation, tick/volume bars, a unified `chart.on(...)` event bus, markers and signals, earnings/dividend/expiry event markers, and custom price/time formatters.
+
+## Size budget
+
+Enforced in CI by [`size-limit`](./.size-limit.json) — nothing is excluded, because there are no runtime dependencies to exclude.
+
+| Bundle | Limit | Actual |
+|---|---|---|
+| Base engine | 34 KB | 32.72 KB |
+| Base + trade | 40.5 KB | 39.31 KB |
+| Indicators tier | 9 KB | 4.47 KB |
+| Draw tier | 14 KB | 6.25 KB |
+| Transform tier | 5 KB | 2.66 KB |
+| Profile tier | 8 KB | 5.53 KB |
+| **Everything** | **72 KB** | **58.22 KB** |
 
 ## Documentation
 
@@ -89,6 +143,16 @@ npm run build                               # build the library (dist/) the live
 cd website && npm install && npm run dev    # http://localhost:3000/openalgo-charts
 ```
 
+## Examples
+
+Runnable demos in [`examples/`](./examples), including a full **yfinance terminal** ([`examples/yfinance`](./examples/yfinance)) with a TradingView-style shell: symbol search, interval pills, chart-type picker, indicator menu, a vertical drawing rail, a floating properties bar, generated indicator settings, and layout persistence.
+
+```bash
+npm run build
+cd examples/yfinance && pip install -r requirements.txt && python server.py
+# → http://127.0.0.1:8000/examples/yfinance/index.html
+```
+
 ## Develop
 
 ```bash
@@ -103,14 +167,25 @@ npm run verify     # typecheck + test + build + size
 
 ## Principles
 
-- **Single canvas pipeline** (no SVG, no DOM-per-bar) - small and fast.
-- **Gapless time axis by default** - weekends, holidays, and session breaks collapse.
-- **Zero runtime dependencies** - nothing is excluded from the size budget.
+- **Single canvas pipeline** (no SVG, no DOM-per-bar) — small and fast.
+- **Gapless time axis by default** — weekends, holidays, and session breaks collapse.
+- **Registries, not switches** — chart types, indicators, and drawing tools are all descriptors. Adding one is a registration, never a core change.
+- **Zero runtime dependencies** — nothing is excluded from the size budget.
 - **Apache-2.0**, original code.
 
 ## Status &amp; limitations
 
-Version **1.0.8 (published)** - all engine build phases are implemented with 468 unit tests, base engine ~33 KB Brotli, full package ~58 KB Brotli (all six tiers). The OpenAlgo WS/trade adapters ship and auto-reconnect, but their exact message/endpoint schemas should be verified against your running OpenAlgo build. An optional DOM chrome package (toolbar, dialogs, command palette, objects panel) is the next planned piece; the Footprint/order-flow renderer still needs its visual pass, and overlay and `indexed-to-100` price scales are unimplemented - see [`ARCHITECTURE.md`](./ARCHITECTURE.md) for the honest deferred list.
+Version **1.0.8 (published)**. All engine build phases are implemented with 468 unit tests across 47 files.
+
+Known gaps, stated plainly:
+
+- The **Footprint / order-flow renderer** works but has not had its visual pass — hardcoded colours (not theme-aware), a single display mode, no `setOptions`, and `stackedImbalances` is computed but not drawn.
+- **Footprint and order flow need trade-by-trade data classified bid/ask.** OpenAlgo does not store this by default, so it is live-session-only unless you add a tick recorder. See [`ARCHITECTURE.md`](./ARCHITECTURE.md) §6A.
+- The OpenAlgo **WS/trade adapter wire schemas** ship with injectable transports and offline tests, but the exact field names should be verified against your running OpenAlgo build.
+- Price-scale **`percentage`** and **`indexed-to-100`** modes, and overlay scales on a shared axis, are not implemented.
+- An optional **DOM chrome package** (toolbar, dialogs, command palette, objects panel) is the next planned piece; today that UI lives in the examples.
+
+See [`ARCHITECTURE.md`](./ARCHITECTURE.md) §13a for the full deferred list.
 
 ## License
 

package/dist/draw/index.d.ts

@@ -403,6 +403,19 @@ interface DrawingStyle {
     wrapWidth?: number;
     /** Horizontal alignment within the box. Defaults to 'left'. */
     textAlign?: 'left' | 'center' | 'right';
+    /** Vertical placement within the box. Defaults to 'top'. */
+    textVAlign?: 'top' | 'middle' | 'bottom';
+    /**
+     * Where a shape's label sits relative to the shape: `inside` the outline, or
+     * `outside` just above it. Shapes only — the text tool *is* its own box.
+     */
+    textPosition?: 'inside' | 'outside';
+    /**
+     * Label colour. Shapes need this separate from `color`, which is the outline —
+     * a purple rectangle with white text is one shape with two colours.
+     * Falls back to `color`.
+     */
+    fontColor?: string;
     /** Position tools: capital base and risk per trade, for the size readout. */
     accountSize?: number;
     risk?: number;
@@ -815,6 +828,8 @@ declare class Pane {
     /** Remove a series record if present; returns true if it was found. */
     removeSeries(record: SeriesRecord): boolean;
     series(): readonly SeriesRecord[];
+    /** Primitives attached to this pane, in draw order. */
+    primitives(): readonly IPrimitive[];
     addPrimitive(primitive: IPrimitive, host: PrimitiveHost): void;
     /** Remove a primitive if present; returns true if it was found. */
     removePrimitive(primitive: IPrimitive): boolean;
@@ -1395,6 +1410,53 @@ declare class EventMarkers implements IPrimitive {
     hitTest(x: number, y: number): PrimitiveHit | null;
 }
 
+/**
+ * Time navigator (ARCHITECTURE.md §8) — the hover-revealed zoom / step controls
+ * that sit just above the time axis: `−` `+` to zoom, `‹` `›` to step one bar.
+ *
+ * Invisible until the pointer nears the bottom of the chart, so a clean chart
+ * stays clean. It fades in and out rather than snapping, which is what keeps it
+ * from reading as a glitch when the cursor crosses the reveal band.
+ *
+ * Reveal is driven by an explicit `setPointer` from the chart, **not** by
+ * `rc.hoverId`. Hover ids come from `bestHit`, which picks the nearest primitive
+ * — so a drawing or an order line near the bottom of the chart would win the
+ * hit and silently hide the controls. Pointer position is the honest input here;
+ * hit-testing still owns the buttons themselves.
+ */
+
+/** Command each button runs. These are `Chart` shortcut command ids. */
+type TimeNavigatorAction = 'zoomOut' | 'zoomIn' | 'panLeftBar' | 'panRightBar';
+interface TimeNavigatorOptions {
+    /** Prefix for hit ids. Lets a host run more than one. */
+    id: string;
+    /** Buttons, left to right. A `null` inserts a gap between groups. */
+    buttons: readonly (TimeNavigatorAction | null)[];
+    /** Button box size in media px. */
+    size: number;
+    /** Gap between buttons, and the wider gap a `null` produces. */
+    gap: number;
+    groupGap: number;
+    /** Distance from the bottom of the plot to the bottom of the buttons. */
+    bottomMargin: number;
+    /**
+     * Height of the reveal band above the plot bottom. The pointer anywhere in
+     * this band brings the controls in.
+     */
+    revealHeight: number;
+    /** Seconds the fade takes. 0 disables the animation. */
+    fadeSeconds: number;
+    /** Tooltip label per action. */
+    labels: Record<TimeNavigatorAction, string>;
+    /** Optional keyboard hint shown next to the label, e.g. `"Ctrl + −"`. */
+    hints: Partial<Record<TimeNavigatorAction, string>>;
+    /** Show the tooltip above the hovered button. */
+    showTooltip: boolean;
+    font: number;
+    radius: number;
+    zOrder: ZOrder;
+}
+
 /**
  * Top-level chart orchestrator (ARCHITECTURE.md §3.3). Owns the shared
  * DataLayer + time scale, the panes, the invalidate mask, and the render loop.
@@ -1455,6 +1517,12 @@ interface ChartOptions {
      * `(s) => new Date(s * 1000).toISOString().slice(11, 16)`.
      */
     timeFormatter?: (utcSeconds: number, tickMark?: TickMarkType) => string;
+    /**
+     * Hover-revealed zoom / step controls above the time axis (TradingView-style).
+     * `true` by default — they stay invisible until the pointer nears the bottom
+     * of the chart. Pass `false` to drop them, or an options object to restyle.
+     */
+    timeNavigator?: boolean | Partial<TimeNavigatorOptions>;
 }
 interface AddSeriesOptions {
     /** Target pane index (0 = price). Higher panes are created on demand. */
@@ -1565,6 +1633,8 @@ declare class Chart {
     private _clickCb;
     private _crosshairCb;
     private _pointerMoved;
+    /** While true, pointer gestures place anchors instead of panning. */
+    private _placementMode;
     private _downPane;
     private _downX;
     private _downLocalY;
@@ -1588,6 +1658,9 @@ declare class Chart {
     private _priceScaleOptions;
     private _timeFormatter;
     private _leftAxisWidth;
+    private _timeNav;
+    /** Pane the navigator is currently attached to, so it can follow the bottom. */
+    private _timeNavPane;
     constructor(container: HTMLElement, options?: ChartOptions);
     /** Register a callback fired when the user pans near the left (oldest) edge. */
     setHistoryLoader(loader: () => void): void;
@@ -1755,6 +1828,14 @@ declare class Chart {
      * at runtime. Pass undefined to restore the IST default.
      */
     setTimeFormatter(fn: ((utcSeconds: number, tickMark?: TickMarkType) => string) | undefined): void;
+    /**
+     * Turn pointer gestures into anchor placement instead of panning. A host arms
+     * this while a drawing tool is active: a press no longer scrolls the chart, and
+     * a press-drag-release is reported as two `click` events (press point, then
+     * release point, the latter tagged `viaDrag`) so a two-point shape can be drawn
+     * in one gesture. `DrawingController` drives this for you.
+     */
+    setPlacementMode(active: boolean): void;
     /** Swap the palette at runtime (dark/light toggle) without recreating the chart. */
     setTheme(theme: ChartTheme): void;
     /**
@@ -1852,6 +1933,22 @@ declare class Chart {
     private _handleLegendAction;
     /** Cumulative top + height of each pane, by weight (the source of truth for hit-testing). */
     private _paneLayout;
+    /**
+     * Keyboard hints for the navigator tooltips, read from the live keymap so a
+     * rebind shows up in the tooltip instead of a stale hardcoded string. The
+     * one-bar step buttons have no default binding, so they get no hint.
+     */
+    private _navHints;
+    /**
+     * Keep the navigator on the bottom pane — it belongs just above the time
+     * axis, and adding or removing a pane moves which one that is.
+     */
+    private _syncTimeNavPane;
+    /**
+     * Push the pointer to the navigator and keep painting while it fades, so the
+     * animation runs even when nothing else on the chart is changing.
+     */
+    private _feedTimeNav;
     private _renderContext;
     private _observeSize;
     private _onFrame;
@@ -1971,6 +2068,11 @@ declare class DrawingController {
     constructor(chart: Chart, options?: DrawingControllerOptions);
     /** Arm a tool for placement, or pass null to return to the cursor. */
     setTool(toolId: string | null): void;
+    /**
+     * Ask the chart to stop panning and report gestures as anchor placement.
+     * Guarded so a base bundle predating `setPlacementMode` still loads the tier.
+     */
+    private _setPlacementMode;
     activeTool(): string | null;
     setOptions(patch: DrawingControllerOptions): void;
     /** Every drawing, in creation order. */

package/dist/index.d.ts

@@ -707,6 +707,8 @@ declare class Pane {
     /** Remove a series record if present; returns true if it was found. */
     removeSeries(record: SeriesRecord): boolean;
     series(): readonly SeriesRecord[];
+    /** Primitives attached to this pane, in draw order. */
+    primitives(): readonly IPrimitive[];
     addPrimitive(primitive: IPrimitive, host: PrimitiveHost): void;
     /** Remove a primitive if present; returns true if it was found. */
     removePrimitive(primitive: IPrimitive): boolean;
@@ -1532,6 +1534,98 @@ declare class EventMarkers implements IPrimitive {
     hitTest(x: number, y: number): PrimitiveHit | null;
 }
 
+/**
+ * Time navigator (ARCHITECTURE.md §8) — the hover-revealed zoom / step controls
+ * that sit just above the time axis: `−` `+` to zoom, `‹` `›` to step one bar.
+ *
+ * Invisible until the pointer nears the bottom of the chart, so a clean chart
+ * stays clean. It fades in and out rather than snapping, which is what keeps it
+ * from reading as a glitch when the cursor crosses the reveal band.
+ *
+ * Reveal is driven by an explicit `setPointer` from the chart, **not** by
+ * `rc.hoverId`. Hover ids come from `bestHit`, which picks the nearest primitive
+ * — so a drawing or an order line near the bottom of the chart would win the
+ * hit and silently hide the controls. Pointer position is the honest input here;
+ * hit-testing still owns the buttons themselves.
+ */
+
+/** Command each button runs. These are `Chart` shortcut command ids. */
+type TimeNavigatorAction = 'zoomOut' | 'zoomIn' | 'panLeftBar' | 'panRightBar';
+interface TimeNavigatorOptions {
+    /** Prefix for hit ids. Lets a host run more than one. */
+    id: string;
+    /** Buttons, left to right. A `null` inserts a gap between groups. */
+    buttons: readonly (TimeNavigatorAction | null)[];
+    /** Button box size in media px. */
+    size: number;
+    /** Gap between buttons, and the wider gap a `null` produces. */
+    gap: number;
+    groupGap: number;
+    /** Distance from the bottom of the plot to the bottom of the buttons. */
+    bottomMargin: number;
+    /**
+     * Height of the reveal band above the plot bottom. The pointer anywhere in
+     * this band brings the controls in.
+     */
+    revealHeight: number;
+    /** Seconds the fade takes. 0 disables the animation. */
+    fadeSeconds: number;
+    /** Tooltip label per action. */
+    labels: Record<TimeNavigatorAction, string>;
+    /** Optional keyboard hint shown next to the label, e.g. `"Ctrl + −"`. */
+    hints: Partial<Record<TimeNavigatorAction, string>>;
+    /** Show the tooltip above the hovered button. */
+    showTooltip: boolean;
+    font: number;
+    radius: number;
+    zOrder: ZOrder;
+}
+declare const DEFAULT_TIME_NAVIGATOR_OPTIONS: TimeNavigatorOptions;
+declare class TimeNavigator implements IPrimitive {
+    private _opts;
+    private _host;
+    /** Button geometry from the last paint, in media px relative to the plot. */
+    private _boxes;
+    /** Pointer in plot-local media px, or null when it left the pane. */
+    private _pointer;
+    /** 0 hidden, 1 fully shown. Eased toward the target each frame. */
+    private _opacity;
+    private _lastFrameMs;
+    private _now;
+    constructor(opts?: Partial<TimeNavigatorOptions>, now?: () => number);
+    attached(host: PrimitiveHost): void;
+    detached(): void;
+    zOrder(): ZOrder;
+    options(): TimeNavigatorOptions;
+    setOptions(patch: Partial<TimeNavigatorOptions>): void;
+    /**
+     * Tell the navigator where the pointer is, in plot-local media px. `null`
+     * when it leaves. The chart calls this; hosts driving their own navigator
+     * should too.
+     */
+    setPointer(p: {
+        x: number;
+        y: number;
+    } | null): void;
+    /** True when the pointer is inside the reveal band. */
+    private _revealed;
+    private _targetOpacity;
+    /** Top of the reveal band, recomputed each paint from the plot height. */
+    private _revealTop;
+    /** Whether the fade is still running — the chart keeps painting while true. */
+    animating(): boolean;
+    draw(ctx: CanvasRenderingContext2D, rc: PrimitiveRenderContext): void;
+    /** Which button the pointer is over, or null. */
+    private _hoveredAction;
+    private _button;
+    private _tooltip;
+    /**
+     * Buttons hit-test only while visible, so a hidden navigator never steals a
+     * click from the chart body underneath it.
+     */
+    hitTest(x: number, y: number): PrimitiveHit | null;
+}
+
 /**
  * Top-level chart orchestrator (ARCHITECTURE.md §3.3). Owns the shared
  * DataLayer + time scale, the panes, the invalidate mask, and the render loop.
@@ -1592,6 +1686,12 @@ interface ChartOptions {
      * `(s) => new Date(s * 1000).toISOString().slice(11, 16)`.
      */
     timeFormatter?: (utcSeconds: number, tickMark?: TickMarkType) => string;
+    /**
+     * Hover-revealed zoom / step controls above the time axis (TradingView-style).
+     * `true` by default — they stay invisible until the pointer nears the bottom
+     * of the chart. Pass `false` to drop them, or an options object to restyle.
+     */
+    timeNavigator?: boolean | Partial<TimeNavigatorOptions>;
 }
 interface AddSeriesOptions {
     /** Target pane index (0 = price). Higher panes are created on demand. */
@@ -1704,6 +1804,8 @@ declare class Chart {
     private _clickCb;
     private _crosshairCb;
     private _pointerMoved;
+    /** While true, pointer gestures place anchors instead of panning. */
+    private _placementMode;
     private _downPane;
     private _downX;
     private _downLocalY;
@@ -1727,6 +1829,9 @@ declare class Chart {
     private _priceScaleOptions;
     private _timeFormatter;
     private _leftAxisWidth;
+    private _timeNav;
+    /** Pane the navigator is currently attached to, so it can follow the bottom. */
+    private _timeNavPane;
     constructor(container: HTMLElement, options?: ChartOptions);
     /** Register a callback fired when the user pans near the left (oldest) edge. */
     setHistoryLoader(loader: () => void): void;
@@ -1894,6 +1999,14 @@ declare class Chart {
      * at runtime. Pass undefined to restore the IST default.
      */
     setTimeFormatter(fn: ((utcSeconds: number, tickMark?: TickMarkType) => string) | undefined): void;
+    /**
+     * Turn pointer gestures into anchor placement instead of panning. A host arms
+     * this while a drawing tool is active: a press no longer scrolls the chart, and
+     * a press-drag-release is reported as two `click` events (press point, then
+     * release point, the latter tagged `viaDrag`) so a two-point shape can be drawn
+     * in one gesture. `DrawingController` drives this for you.
+     */
+    setPlacementMode(active: boolean): void;
     /** Swap the palette at runtime (dark/light toggle) without recreating the chart. */
     setTheme(theme: ChartTheme): void;
     /**
@@ -1991,6 +2104,22 @@ declare class Chart {
     private _handleLegendAction;
     /** Cumulative top + height of each pane, by weight (the source of truth for hit-testing). */
     private _paneLayout;
+    /**
+     * Keyboard hints for the navigator tooltips, read from the live keymap so a
+     * rebind shows up in the tooltip instead of a stale hardcoded string. The
+     * one-bar step buttons have no default binding, so they get no hint.
+     */
+    private _navHints;
+    /**
+     * Keep the navigator on the bottom pane — it belongs just above the time
+     * axis, and adding or removing a pane moves which one that is.
+     */
+    private _syncTimeNavPane;
+    /**
+     * Push the pointer to the navigator and keep painting while it fades, so the
+     * animation runs even when nothing else on the chart is changing.
+     */
+    private _feedTimeNav;
     private _renderContext;
     private _observeSize;
     private _onFrame;
@@ -2954,4 +3083,4 @@ declare function lerp(a: number, b: number, t: number): number;
  */
 declare function roundToTick(value: number, step: number): number;
 
-export { ALT_PRESET, type AddSeriesOptions, type AggTick, BUILTIN_COMMANDS, type Bar, type BarUpdate, type BarsRequest, BuySellButtons, type BuySellButtonsOptions, CHART_STATE_VERSION, CandleBuilder, type CandleBuilderOptions, type CandleStyle, type CandleUpdate, Chart, type ChartEvent, type ChartOptions, type ChartState, type ChartTheme, type CrosshairMoveEvent, type CustomShortcut, DEFAULT_CANDLE_BUILDER_OPTIONS, DEFAULT_CANDLE_STYLE, DEFAULT_HISTOGRAM_STYLE, DEFAULT_KEYMAP, DEFAULT_PRICE_SCALE_OPTIONS, DEFAULT_THEME, DEFAULT_TIME_SCALE_OPTIONS, DEFAULT_TRADING_COLORS, type DataFeed, type DepthLevel, type DrawItem, EventMarkers, FakeDataFeed, type FeedScheduler, type HistogramStyle, INDICATOR_LINE_STYLES, INDICATOR_SOURCES, type IPrimitive, IST_OFFSET_SECONDS, type IndicatorApi, type IndicatorAttachContext, type IndicatorDescriptor, type IndicatorHost, type IndicatorInput, type IndicatorLevel, type IndicatorPlot, type IndicatorSettings, type IndicatorSource, type IndicatorState, type IndicatorStore, type IndicatorValues, InvalidationLevel, type KeymapEntry, type LateTickPolicy, type LegendValue, type LinePoint, type LogicalRange, LogoWatermark, type LogoWatermarkOptions, type LtpEvent, type MarkerPosition, type MarkerShape, type MarkerSize, type MarketDepth, type OpenAlgoConfig, OpenAlgoDataFeed, type OpenAlgoLiveConfig, OpenAlgoLiveDataFeed, type OpenAlgoTradeConfig, OpenAlgoTradeFeed, type OpenAlgoWsConfig, OpenAlgoWsFeed, type OrderSide$1 as OrderSide, type OrderType$1 as OrderType, type OriginalTime, Pane, type PaneInvalidation, PaneLegend, type PaneLegendAction, type PaneLegendOptions, type PaneState, type PlaceOrder, type PositionSide, PriceLine, type PriceLineOptions, type PriceRange, PriceScale, type PriceScaleId, type PriceScaleMode, type PriceScaleOptions, type PriceScaleState, type PrimitiveHit, type PrimitiveHost, type PrimitiveRenderContext, type RendererEntry, type RestoreReport, type SeriesApi, type SeriesDataItem, type SeriesMarker, SeriesMarkers, type SeriesRenderContext, type SeriesState, type SeriesStyle, type SeriesType, type ShortcutListItem, ShortcutManager, type ShortcutManagerOptions, type ShortcutPreset, type ShortcutScope, type ShortcutTriggerEvent, type Size, type SocketFactory, type SocketLike, type SupertrendPoint, type Tick, TickBarAggregator, type TickMarkType, type TickTimeframe, TimeScale, type TimeScaleOp, type TimeScaleOptions, type TradeFeed, type TradeMarkerVariant, TradeMarkersPrimitive, type TradingColors, TradingController, type TradingHost, type TradingLineStyle, type TradingLineVariant, type TradingOrder, type TradingOrderSide, type TradingOrderType, type TradingPosition, type TradingSettings, type TradingSyncPayload, type TradingTrade, type UTCSeconds, type UnsubscribeFn, VERSION, type VolumeMode, type WatermarkPosition, type Whitespace, type WsControlMessage, type WsMode, type WsState, type ZOrder, atr, autoscaleRange, bestHit, bitmapSize, clamp, compactVolume, conflateBars, conflateItems, conflationGroupSize, createChart, darkTheme, drawShape, effectiveMarkerPx, ema, emaSeries, epochMsToUtcSeconds, eventToCombo, formatCombo, formatIstDate, formatIstTime, formatIstTimeSeconds, formatSubscribe, formatUnsubscribe, generateBars, getChartType, getIndicator, hasIndicator, indicatorDefaults, indicatorStyleInputs, intervalToSeconds, isNewIstDay, isReservedCombo, isValidCombo, isWhitespace, istStringToUtcSeconds, lerp, lightTheme, mapHistoryResponse, mapOrder, mapPosition, markerSizePx, mergeBars, niceTicks, normalizeCombo, optimalBarWidth, parseCombo, parseMessage, plotStyleKeys, precisionForStep, registerChartType, registerIndicator, registeredChartTypes, registeredIndicators, roundToTick, rowTimeToUtcSeconds, rsi, rsiSeries, snapToDevicePixel, sourceValue, sourceValues, supertrend, supertrendSeries, toBar, trueRange, utcSecondsToIstDateString, utcSecondsToIstParts, version, verticalGradient, watermarkRect };
+export { ALT_PRESET, type AddSeriesOptions, type AggTick, BUILTIN_COMMANDS, type Bar, type BarUpdate, type BarsRequest, BuySellButtons, type BuySellButtonsOptions, CHART_STATE_VERSION, CandleBuilder, type CandleBuilderOptions, type CandleStyle, type CandleUpdate, Chart, type ChartEvent, type ChartOptions, type ChartState, type ChartTheme, type CrosshairMoveEvent, type CustomShortcut, DEFAULT_CANDLE_BUILDER_OPTIONS, DEFAULT_CANDLE_STYLE, DEFAULT_HISTOGRAM_STYLE, DEFAULT_KEYMAP, DEFAULT_PRICE_SCALE_OPTIONS, DEFAULT_THEME, DEFAULT_TIME_NAVIGATOR_OPTIONS, DEFAULT_TIME_SCALE_OPTIONS, DEFAULT_TRADING_COLORS, type DataFeed, type DepthLevel, type DrawItem, EventMarkers, FakeDataFeed, type FeedScheduler, type HistogramStyle, INDICATOR_LINE_STYLES, INDICATOR_SOURCES, type IPrimitive, IST_OFFSET_SECONDS, type IndicatorApi, type IndicatorAttachContext, type IndicatorDescriptor, type IndicatorHost, type IndicatorInput, type IndicatorLevel, type IndicatorPlot, type IndicatorSettings, type IndicatorSource, type IndicatorState, type IndicatorStore, type IndicatorValues, InvalidationLevel, type KeymapEntry, type LateTickPolicy, type LegendValue, type LinePoint, type LogicalRange, LogoWatermark, type LogoWatermarkOptions, type LtpEvent, type MarkerPosition, type MarkerShape, type MarkerSize, type MarketDepth, type OpenAlgoConfig, OpenAlgoDataFeed, type OpenAlgoLiveConfig, OpenAlgoLiveDataFeed, type OpenAlgoTradeConfig, OpenAlgoTradeFeed, type OpenAlgoWsConfig, OpenAlgoWsFeed, type OrderSide$1 as OrderSide, type OrderType$1 as OrderType, type OriginalTime, Pane, type PaneInvalidation, PaneLegend, type PaneLegendAction, type PaneLegendOptions, type PaneState, type PlaceOrder, type PositionSide, PriceLine, type PriceLineOptions, type PriceRange, PriceScale, type PriceScaleId, type PriceScaleMode, type PriceScaleOptions, type PriceScaleState, type PrimitiveHit, type PrimitiveHost, type PrimitiveRenderContext, type RendererEntry, type RestoreReport, type SeriesApi, type SeriesDataItem, type SeriesMarker, SeriesMarkers, type SeriesRenderContext, type SeriesState, type SeriesStyle, type SeriesType, type ShortcutListItem, ShortcutManager, type ShortcutManagerOptions, type ShortcutPreset, type ShortcutScope, type ShortcutTriggerEvent, type Size, type SocketFactory, type SocketLike, type SupertrendPoint, type Tick, TickBarAggregator, type TickMarkType, type TickTimeframe, TimeNavigator, type TimeNavigatorAction, type TimeNavigatorOptions, TimeScale, type TimeScaleOp, type TimeScaleOptions, type TradeFeed, type TradeMarkerVariant, TradeMarkersPrimitive, type TradingColors, TradingController, type TradingHost, type TradingLineStyle, type TradingLineVariant, type TradingOrder, type TradingOrderSide, type TradingOrderType, type TradingPosition, type TradingSettings, type TradingSyncPayload, type TradingTrade, type UTCSeconds, type UnsubscribeFn, VERSION, type VolumeMode, type WatermarkPosition, type Whitespace, type WsControlMessage, type WsMode, type WsState, type ZOrder, atr, autoscaleRange, bestHit, bitmapSize, clamp, compactVolume, conflateBars, conflateItems, conflationGroupSize, createChart, darkTheme, drawShape, effectiveMarkerPx, ema, emaSeries, epochMsToUtcSeconds, eventToCombo, formatCombo, formatIstDate, formatIstTime, formatIstTimeSeconds, formatSubscribe, formatUnsubscribe, generateBars, getChartType, getIndicator, hasIndicator, indicatorDefaults, indicatorStyleInputs, intervalToSeconds, isNewIstDay, isReservedCombo, isValidCombo, isWhitespace, istStringToUtcSeconds, lerp, lightTheme, mapHistoryResponse, mapOrder, mapPosition, markerSizePx, mergeBars, niceTicks, normalizeCombo, optimalBarWidth, parseCombo, parseMessage, plotStyleKeys, precisionForStep, registerChartType, registerIndicator, registeredChartTypes, registeredIndicators, roundToTick, rowTimeToUtcSeconds, rsi, rsiSeries, snapToDevicePixel, sourceValue, sourceValues, supertrend, supertrendSeries, toBar, trueRange, utcSecondsToIstDateString, utcSecondsToIstParts, version, verticalGradient, watermarkRect };