openalgo-charts 2.5.4 → 2.5.5

package/README.md

@@ -25,7 +25,7 @@ with no runtime dependencies.
 npm install openalgo-charts
 ```
 
-Current version: **2.5.4**. Go to any date, lay out a grid of charts, collapse panes, route study output and lock host drawings.
+Current version: **2.5.5**. Watchlists, news and account panels, a movable price pane, drawings pinned to the screen, price tick bands, and studies that recover after a missing bar.
 See the [changelog](./CHANGELOG.md) for release notes.
 
 ## Quick start
@@ -56,7 +56,7 @@ for live data, or [the widget example](#the-whole-terminal-in-one-call) for char
 
 ## Architecture
 
-<a href="docs/architecture-diagram.svg"><img src="docs/architecture-diagram.svg" alt="OpenAlgo Charts 2.5.4 architecture: host responsibilities, the base data-to-rendering pipeline with alerts and shared replay, and eight optional tiers including workspace storage, trading tools and the widget" width="920" /></a>
+<a href="docs/architecture-diagram.svg"><img src="docs/architecture-diagram.svg" alt="OpenAlgo Charts 2.5.5 architecture: host responsibilities, the base data-to-rendering pipeline with alerts and shared replay, and eight optional tiers including workspace storage, trading tools and the widget" width="920" /></a>
 
 How data reaches the chart, what your app owns, and which features you can import.
 [Open the full-size diagram](docs/architecture-diagram.svg).
@@ -107,7 +107,7 @@ You can also load the library from a CDN in a plain HTML page:
 ```html
 <div id="chart" style="width:100vw;height:100vh"></div>
 <script type="module">
-  import { createChart, generateBars } from 'https://unpkg.com/openalgo-charts@2.5.4/dist/openalgo-charts.mjs';
+  import { createChart, generateBars } from 'https://unpkg.com/openalgo-charts@2.5.5/dist/openalgo-charts.mjs';
   const chart = createChart(document.getElementById('chart'), { timezone: 'Asia/Kolkata' });
   chart.addSeries('candlestick').setData(generateBars(1700000000, 200, 3600));
   chart.fitContent();
@@ -145,7 +145,9 @@ toolbar, settings, indicators, a status line, mobile controls and layout persist
 Its dialogs use the chart's settings schemas and follow the active theme. **Go to**
 jumps to a date or a range, loading older history first (`widget.goTo`), and
 `createChartGrid` lays out one widget per cell, from `1x1` to `2x2`, with splitters,
-linked charts and portable workspace documents.
+linked charts and portable workspace documents. The panel dock also holds named
+**Watchlists** with live quote rows and a **News** reader when the host supplies a
+quote or news feed, and an account summary when its broker declares accounts.
 
 The widget uses the same public API as a custom interface. Your app supplies the
 data feed and handles order requests; the widget does not choose a broker or send
@@ -160,17 +162,17 @@ Unused optional tiers stay out of the base chart download.
 
 | Import | Contents | Brotli |
 |---|---|---|
-| `openalgo-charts` | Engine, 13 chart types, panes and scales, custom indicator registry, primitives, alerts, replay, comparisons, chart linking, state, feeds, bar cache, trading overlays, CSV and SVG export | 117.42 kB |
-| `openalgo-charts/indicators` | 105 built-in indicators, calculation helpers and helpers for studies that use external data | 36.27 kB |
-| `openalgo-charts/draw` | 87 drawing tools + a headless drawing controller, clipboard, settings schema, level palette, freehand geometry and SVG icons | 42.53 kB |
+| `openalgo-charts` | Engine, 13 chart types, panes and scales, custom indicator registry, primitives, alerts, replay, comparisons, chart linking, state, feeds, bar cache, trading overlays, CSV and SVG export | 119.15 kB |
+| `openalgo-charts/indicators` | 105 built-in indicators, calculation helpers and helpers for studies that use external data | 36.34 kB |
+| `openalgo-charts/draw` | 87 drawing tools + a headless drawing controller, clipboard, settings schema, level palette, freehand geometry and SVG icons | 44.87 kB |
 | `openalgo-charts/transform` | Heikin Ashi, Renko, Range bars, Line Break, Point &amp; Figure, Kagi, and symbol arithmetic (`AAPL/MSFT`) | 4.50 kB |
 | `openalgo-charts/profile` | Volume Profile, Market Profile (TPO) with compact pixel letters, Footprint, order flow | 14.96 kB |
-| `openalgo-charts/trade` | Order, position and bracket tools, plus a depth-of-market ladder | 8.01 kB |
+| `openalgo-charts/trade` | Order, position and bracket tools, account state, order preview and position commands, plus a depth-of-market ladder | 16.64 kB |
 | `openalgo-charts/webgl` | GPU drawing for supported series, with Canvas 2D fallback | 6.39 kB |
-| `openalgo-charts/widget` | `createWidget`: toolbar, Data and Objects dock, symbol search, dialogs, mobile controls, shortcuts and optional layout persistence | 71.33 kB |
-| `openalgo-charts/workspace` | Validated workspace and indicator-template documents, named catalogs with revision checks, asynchronous storage and an IndexedDB adapter; no DOM | 8.67 kB |
+| `openalgo-charts/widget` | `createWidget`: toolbar, Data, Objects, Watchlist and News dock, account summary, symbol search, dialogs, mobile controls, shortcuts and optional layout persistence | 82.30 kB |
+| `openalgo-charts/workspace` | Validated workspace and indicator-template documents, named watchlists, named catalogs with revision checks, asynchronous storage and an IndexedDB adapter; no DOM | 9.99 kB |
 
-Everything together is **310.09 kB Brotli**; a widget terminal with built-in indicators (base + draw + indicators + widget) is 267.55 kB. Figures are measured from the 2.5.4 release build. The trade tier is 8.01 kB on its own; base + trade costs 125.42 kB. Sizes use decimal kB.
+Everything together is **335.15 kB Brotli**; a widget terminal with built-in indicators (base + draw + indicators + widget) is 282.67 kB. Figures are measured from the 2.5.5 release build. The trade tier is 16.64 kB on its own; base + trade costs 135.79 kB. Sizes use decimal kB.
 
 ## What's built
 
@@ -228,7 +230,7 @@ draw.setTool('trend-line');   // the next two clicks place it
 
 87 tools. Lines, channels and four pitchfork variants. Fibonacci levels, time projections, fans, circles, arcs, wedges and spirals. Gann fans, boxes and squares. Harmonic patterns, Elliott waves and Head and Shoulders. Geometric wavefronts and tessellation. Shapes, paths, forecasts, positions, measurements, text, tables and freehand brushes. Every tool appears in the [editable drawing gallery](https://marketcalls.github.io/openalgo-charts/demos/drawings/index.html), with simulated NIFTY prices near 23800 and desktop or touch controls.
 
-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. A drawing's `policy` makes it read-only, unselectable, transient or unlisted, for levels the host places and the user should not move. Anchors are `{ time, price }`, never pixels, so they survive zoom and resolve inside collapsed session gaps and past the last bar.
+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. A drawing can be pinned to the screen (`space: 'viewport'`), so pan and zoom leave it where it is. A drawing's `policy` makes it read-only, unselectable, transient or unlisted, for levels the host places and the user should not move. Anchors are `{ time, price }`, never pixels, so they survive zoom and resolve inside collapsed session gaps and past the last bar.
 
 `draw.copy()`, `draw.cut()` and `draw.paste()` move drawings through the OS clipboard, including between two charts on the page. The payload is JSON under one namespaced key, so foreign text pastes nothing instead of throwing at your Ctrl+V handler, and every field is validated before it reaches the model. A refused clipboard permission does not lose the copy: every write also lands in a shared in-memory clipboard, and a cut deletes only after the write succeeds. A paste is one undo step of fresh objects, nudged two bars and 16 px so it is visibly a second shape. The key bindings stay yours; the engine installs no listeners.
 
@@ -255,7 +257,7 @@ A drawing carries a paint order (`zIndex`: below zero paints under the series, a
 Under the hand: the drawing under the pointer shows its handles faintly before it is grabbed (`hovered()`, `drawing:hover`), at the cost of the overlay tier only; Shift locks a line to 45 degree steps while placing or dragging a handle; the magnet paints a ring on the bar centre where the next click will land, and `'weak'` pulls only when an O/H/L/C is within a few pixels; grab targets grow for a touch pointer; Escape, Enter and Backspace cancel, finish or pop an anchor while placing, through `keyToDrawingAction`, which also maps undo, redo, copy, cut, paste, duplicate, delete and arrow nudge as a pure function you wire yourself. Line tools take a `showStats` readout of change, percent, bars and angle. The brush and highlighter ink every coalesced pointer sample, thin on release and paint as a spline, with pen pressure driving the width when `style.pressure` is on. Every tool icon and a chrome set ship as path data with builders for an inline `<svg>`, a sprite with `<use>` and a CSS cursor (`iconSvg`, `iconSprite`, `iconUse`, `toolCursor`), so a rail, a flyout and the armed cursor derive from one registry.
 
 ### Panes, scales &amp; legends
-Draggable pane dividers, move / maximize / collapse to a strip / remove, and pane legends showing one reading per plot in that plot's own colour, with inline show-hide / settings / move / delete controls revealed on hover. The status line is switchable field by field (logo, title, market status, OHLC, bar change, volume, last day change, last value) over a host-supplied data source.
+Draggable pane dividers, move / maximize / collapse to a strip / remove (and, on a chart that opts in with `movablePrimaryPane`, move the price pane below its studies), and pane legends showing one reading per plot in that plot's own colour, with inline show-hide / settings / move / delete controls revealed on hover. The status line is switchable field by field (logo, title, market status, OHLC, bar change, volume, last day change, last value) over a host-supplied data source.
 
 Each pane carries a right, a left and a hidden overlay price scale, in four modes: linear, logarithmic, and the two rebasing modes **percentage** (`+3.42%`) and **indexed-to-100** (`103.42`), which quote every price against a baseline taken from the first visible bar, so panning re-bases the axis.
 
@@ -335,7 +337,7 @@ Symbol sync remains a host partnership even when using optional instrument metad
 `chart.on('contextmenu', ...)` reports the pane, price, time, logical index and what sits under the pointer: a drawing, an indicator instance, a legend, a primitive, a series, a price scale (with the side and the scale id it names), the time scale, or empty plot. For a menu raised on a price axis, `chart.priceAxisState(pane, scaleId)` reads back every item that menu draws (auto-fit, invert, scale mode, price-per-bar lock, whether the axis is movable) and `setPriceAxisOptions`, `setPriceAxisAutoFit`, `setPriceAxisLockRatio` and `movePriceAxis` act on it, so no row is ticked with nothing behind it.
 
 ### Trading
-Order, position, and bracket lines with live P&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).
+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). Instruments can carry a price-dependent tick schedule that validation, dragging and the ladder follow, and brokers that declare them get account state, order preview, durations and native close, reverse and bracket commands.
 
 ### Depth of market: simulated live example
 
@@ -494,17 +496,17 @@ Enforced in CI by [`size-limit`](./.size-limit.json). Nothing is excluded, becau
 
 | Bundle | Limit | Actual |
 |---|---|---|
-| Base engine | 117.42 kB | 117.42 kB |
-| Base + trade | 125.43 kB | 125.42 kB |
-| Indicators tier | 36.3 kB | 36.27 kB |
-| Draw tier | 42.53 kB | 42.53 kB |
+| Base engine | 119.15 kB | 119.15 kB |
+| Base + trade | 135.79 kB | 135.79 kB |
+| Indicators tier | 36.35 kB | 36.34 kB |
+| Draw tier | 44.87 kB | 44.87 kB |
 | Transform tier | 6 kB | 4.50 kB |
 | Profile tier | 15 kB | 14.96 kB |
 | WebGL2 tier | 7 kB | 6.39 kB |
-| Widget tier | 71.34 kB | 71.33 kB |
-| Widget terminal (base + draw + indicators + widget) | 267.56 kB | 267.55 kB |
-| Workspace tier | 8.75 kB | 8.67 kB |
-| **Everything** | 310.09 kB | 310.09 kB |
+| Widget tier | 82.31 kB | 82.30 kB |
+| Widget terminal (base + draw + indicators + widget) | 282.67 kB | 282.67 kB |
+| Workspace tier | 9.99 kB | 9.99 kB |
+| **Everything** | 335.15 kB | 335.15 kB |
 
 ## Documentation
 
@@ -549,8 +551,8 @@ See [Contributing](./CONTRIBUTING.md) for setup, targeted checks, documentation
 ```bash
 npm install        # install dev toolchain
 npm run typecheck  # strict TypeScript check
-npm test           # engine unit tests (Vitest): 8228 across 359 files
-npm run test:demo  # reference-host tests: 542 across 50 files
+npm test           # engine unit tests (Vitest): 8660 across 381 files
+npm run test:demo  # reference-host tests: 589 across 56 files
 npm run test:endurance # node endurance-harness tests: 7 cases
 npm run build      # Rollup -> dist/ (minified ESM per tier + types)
 npm run size       # size-limit (Brotli) against the budget
@@ -568,7 +570,7 @@ npm run verify     # lint + types + unit + endurance harness + build + demo + dt
 
 ## Status &amp; limitations
 
-Version **2.5.4**. All engine build phases are implemented. Upgrading a 1.9.x host: [Migrating to 2.0](./docs/migrating-to-2.md).
+Version **2.5.5**. All engine build phases are implemented. Upgrading a 1.9.x host: [Migrating to 2.0](./docs/migrating-to-2.md).
 
 Known gaps, stated plainly:
 

package/dist/draw/index.d.ts

@@ -3,7 +3,7 @@ import { AlertDrawingValue, AlertDrawingLevel, PrimitiveRenderContext, Bar, IPri
 /**
  * The per-tool settings schema: what a host may show in a drawing's settings
  * dialog, expressed as dot paths into the drawing (`style.color`,
- * `text.fontSize`, `props.foo`, `zIndex`) with a control kind and a label.
+ * `text.fontSize`, `props.foo`, `zIndex`, `space`) with a control kind and a label.
  *
  * The rule the whole module exists for: a tool declares only fields its `draw`
  * actually reads. A schema is not a wish list. A host renders exactly what is
@@ -20,8 +20,8 @@ type FieldGroup = 'line' | 'fill' | 'text' | 'levels' | 'behavior';
 interface SettingsField {
     /**
      * Dot path into the drawing. Two segments under `style`, `text` or `props`
-     * (`style.lineWidth`), or one of the top-level flags `locked`, `visible`,
-     * `zIndex`.
+     * (`style.lineWidth`), or one of the top-level fields `locked`, `visible`,
+     * `zIndex`, `space`.
      */
     path: string;
     label: string;
@@ -63,6 +63,11 @@ declare const TEXT_POSITION_OPTIONS: ReadonlyArray<{
     value: string;
     label: string;
 }>;
+/** The two coordinate spaces, as a host offers them: follow the bars, or stay on screen. */
+declare const SPACE_OPTIONS: ReadonlyArray<{
+    value: DrawingSpace;
+    label: string;
+}>;
 /**
  * Font stacks a host can offer. Values are real CSS stacks, so a drawing's
  * `text.fontFamily` needs no translation before it reaches `ctx.font`; a host
@@ -79,6 +84,13 @@ declare const LINE_STYLE_FIELD: SettingsField;
 declare const LINE_FIELDS: readonly SettingsField[];
 declare const FILL_FIELDS: readonly SettingsField[];
 declare const EXTEND_FIELDS: readonly SettingsField[];
+/**
+ * Where the drawing is anchored: to time and price, or to the screen. Declared
+ * only by tools that set `viewport`, since the controller converts nothing
+ * else. Writing it converts the anchors at the view on screen, so the drawing
+ * keeps its place and only stops (or starts) following the bars.
+ */
+declare const SPACE_FIELD: SettingsField;
 declare const SHOW_LABELS_FIELD: SettingsField;
 declare const LEVEL_FIELDS: readonly SettingsField[];
 /**
@@ -153,6 +165,13 @@ declare function applyDrawingSettings(d: Drawing, patch: Record<string, unknown>
  * {@link DrawingText}, made `levels` a list of {@link FibLevel} rather than bare
  * ratios, and gave every drawing a `zIndex`. A 1.9.x document is upgraded by
  * `migrateDrawings` on the way in; nothing downstream sees the old shape.
+ *
+ * The one exception to data space is a drawing whose `space` is `'viewport'`:
+ * a note or a box that belongs to the screen rather than to a bar. Its anchors
+ * are {@link ViewportPoint} fractions of its pane's plot, kept in a field of
+ * their own so a time or a price never has to mean a pixel. The field is
+ * optional and additive, which is why the document stays version 2: a save
+ * with no viewport drawing is byte for byte what it was.
  */
 
 /** One anchor, in data space. */
@@ -167,6 +186,30 @@ interface DrawingPoint {
      */
     pressure?: number;
 }
+/**
+ * Which coordinates a drawing's anchors are in. `'data'`, the default, is time
+ * and price: the drawing moves with the bars when the chart pans or zooms.
+ * `'viewport'` pins it to the screen: its anchors are fractions of its pane's
+ * plot, so pan and zoom leave it where it is and a resize keeps it in
+ * proportion.
+ */
+type DrawingSpace = 'data' | 'viewport';
+/**
+ * One anchor of a viewport drawing, as a fraction of the plot area of the pane
+ * that holds the drawing. Pane-relative, not whole-chart-relative: the pane's
+ * layer paints, clips and hit-tests the drawing, so these are the coordinates
+ * that follow the pane when it moves, resizes or folds.
+ *
+ * `x` is 0 at the plot's left edge and 1 at its right edge; the price axes are
+ * outside that span. `y` is 0 at the top of the pane and 1 at the bottom of its
+ * plot, which on the lowest pane is the top of the time axis. Sizes that a tool
+ * sets in pixels (a font size, a wrap width) stay in pixels: a resize moves a
+ * note in proportion without scaling its type.
+ */
+interface ViewportPoint {
+    x: number;
+    y: number;
+}
 /**
  * How new anchors snap to the bar under the cursor. `weak` snaps only when an
  * O/H/L/C sits within a few pixels of the pointer, so a click on empty space
@@ -289,7 +332,15 @@ interface Drawing {
     id: string;
     /** Registered tool id. */
     tool: string;
+    /** Anchors in time and price. Empty on a viewport drawing, whose anchors are `viewportPoints`. */
     points: DrawingPoint[];
+    /**
+     * Which coordinates the anchors are in. Absent means `'data'`. Only a tool
+     * that declares {@link DrawingTool.viewport} can be anchored to the viewport.
+     */
+    space?: DrawingSpace;
+    /** The anchors of a viewport drawing, one per handle. Present only when `space` is `'viewport'`. */
+    viewportPoints?: ViewportPoint[];
     style: DrawingStyle;
     /** The label (or, for the text tool, the whole content). */
     text?: DrawingText;
@@ -332,8 +383,16 @@ type DrawingInput = Omit<Drawing, 'id' | 'zIndex' | 'createdAt'> & {
 /**
  * The fields `DrawingController.update` and `updateMany` can change. `policy`
  * merges flag by flag, the way `style` does.
- */
-type DrawingPatch = Partial<Pick<Drawing, 'points' | 'style' | 'text' | 'props' | 'locked' | 'visible' | 'zIndex' | 'policy'>>;
+ *
+ * `space` on its own converts the anchors at the view on screen, so the
+ * drawing stays exactly where it is and only stops (or starts) following the
+ * bars. With the new space's anchors in the same patch (`viewportPoints` for
+ * the viewport, `points` for data) they are taken as given. A conversion the
+ * controller cannot make (a tool without viewport support, a pane with no
+ * place on screen) is left out of the patch and the rest of it applies, and
+ * `DrawingController.update` returns false.
+ */
+type DrawingPatch = Partial<Pick<Drawing, 'points' | 'style' | 'text' | 'props' | 'locked' | 'visible' | 'zIndex' | 'policy' | 'space' | 'viewportPoints'>>;
 /** The persisted shape's version; bumped when {@link Drawing} changes. */
 declare const DRAWING_STATE_VERSION = 2;
 /**
@@ -428,6 +487,33 @@ interface DrawingTool {
      * not what Shift means there.
      */
     angleLock?: boolean;
+    /**
+     * The tool can be anchored to the viewport (`Drawing.space`). Declare it
+     * only when `draw` and `distance` read the screen anchors (`pts`) and never
+     * `drawing.points`, which is empty in that space, and when nothing the tool
+     * prints is a price or a time: a label that reads the axis under a pinned
+     * shape would change every time the chart panned. `expand`, `constrain` and
+     * `alertValue` apply to data space only.
+     */
+    viewport?: boolean;
+    /**
+     * The box the drawing covers at `pts`, its anchors in media px (the space
+     * of {@link HitContext}). A drawing anchored to the viewport is always
+     * painted, hit-tested and moved with this box inside its pane's plot, so it
+     * can be seen and grabbed at every edge and after the chart resizes, and no
+     * drag, nudge or handle can take it out. Declare it on a `viewport` tool
+     * that paints beyond its anchors, as the text note and the table do from
+     * their one corner, and the rectangle and the ellipse do for a label above
+     * them or wider than they are; without it the box is the anchors' own
+     * bounds. A handle dragged toward an edge the box reaches first stops short
+     * of it, so the other anchors stay where they are.
+     */
+    bounds?(pts: readonly ScreenPoint[], drawing: Drawing): {
+        x0: number;
+        y0: number;
+        x1: number;
+        y1: number;
+    };
     /**
      * Turn the anchors actually clicked into the full anchor set. Lets a tool drop
      * a complete, immediately editable default from fewer clicks: the position
@@ -567,6 +653,13 @@ declare function fixedRangeVolumeProfileAnalysis(bars: readonly Bar[], fromTime:
  * The payload body is a drawings document (`DrawingsDocument`), so a copy made
  * by a 1.9.x build (a version 1 body carrying the old style-bag text fields)
  * is upgraded by the same migration a saved layout goes through.
+ *
+ * A `paneIndex` in the payload counts the price pane as 0 and the study panes
+ * after it in their order, whatever slot the price pane holds on the chart it
+ * came from: `DrawingController` converts on copy and on paste, so a drawing
+ * copied beside the candles pastes beside the candles on a chart that keeps
+ * its price pane below its studies. On a chart with the price pane on top,
+ * the default, that is the chart's own slot, as it always was.
  */
 
 /**
@@ -728,6 +821,28 @@ interface DrawingChartHost {
      */
     timeToCoordinate?(time: number): number;
     coordinateToTime?(x: number): number;
+    /**
+     * Optional, for drawings anchored to the viewport (`space: 'viewport'`):
+     * the time axis, whose `width` is the plot width a viewport `x` is a
+     * fraction of. A host without it still paints them, since the layer reads
+     * the plot size from its render context, but cannot place, move or convert
+     * them.
+     */
+    readonly timeScale?: {
+        readonly width: number;
+        indexToX(index: number): number;
+        xToIndex(x: number): number;
+    };
+    /**
+     * Optional: a pane's price columns in container px. On a chart with no bars
+     * to measure against, the innermost left column is where the plot, and so
+     * a viewport drawing's `x`, begins.
+     */
+    priceAxisLayout?(paneIndex?: number): readonly {
+        side: 'left' | 'right';
+        x: number;
+        width: number;
+    }[];
     /**
      * Optional. It keeps a paste from a chart with more panes than this one
      * landing on a pane the user cannot see: adding a primitive creates the pane
@@ -737,6 +852,12 @@ interface DrawingChartHost {
      * pane the chart maps no price for, one collapsed to its header strip.
      */
     panes?(): readonly unknown[];
+    /**
+     * Optional. Slot of the price pane, the one pane whose drawings the magnet
+     * snaps to candle prices and a drawing link shares. It moves when a host
+     * puts the price pane below its studies; without it the price pane is slot 0.
+     */
+    primaryPaneIndex?(): number;
 }
 interface DrawingControllerOptions {
     /**
@@ -779,6 +900,16 @@ interface DrawingControllerOptions {
     pasteOffsetBars?: number;
     pasteOffsetPixels?: number;
 }
+/** How `DrawingController.setTool` arms a tool. */
+interface DrawingPlacementOptions {
+    /**
+     * The space the placed drawing is anchored in. `'viewport'` pins it to the
+     * screen: the anchors are placed where they are clicked, as usual, and kept
+     * as fractions of the pane's plot from then on. Only a tool that declares
+     * `viewport` accepts it. Default `'data'`.
+     */
+    space?: DrawingSpace;
+}
 /** What `drawing:change` reports happened to the listed ids. */
 type DrawingChangeKind = 'add' | 'update' | 'remove' | 'reorder' | 'undo' | 'redo';
 /** Options for a call that changes, groups or deletes drawings. */
@@ -818,6 +949,8 @@ declare class DrawingController {
     private readonly _linkedPreviews;
     private _destroyed;
     private _tool;
+    /** The space the armed tool places in; data whenever no tool is armed. */
+    private _toolSpace;
     private _pending;
     private _pendingPane;
     /** Selected ids, in the order they were picked. The first is the primary. */
@@ -856,8 +989,16 @@ declare class DrawingController {
      */
     private _lastBar;
     constructor(chart: DrawingChartHost, options?: DrawingControllerOptions);
-    /** Arm a tool for placement, or pass null to return to the cursor. */
-    setTool(toolId: string | null): void;
+    /**
+     * Arm a tool for placement, or pass null to return to the cursor. With
+     * `options.space` set to `'viewport'` the drawing it places is pinned to the
+     * screen; a tool that cannot be (see `DrawingTool.viewport`) throws.
+     */
+    setTool(toolId: string | null, options?: DrawingPlacementOptions): void;
+    /** The space the armed tool places in: `'data'` unless it was armed for the viewport. */
+    activeToolSpace(): DrawingSpace;
+    /** `draw:tool`, carrying the space only when it is not the default, as the payload always has. */
+    private _emitTool;
     /**
      * Ask the chart to stop panning and report gestures as anchor placement.
      * Guarded so a base bundle predating `setPlacementMode` still loads the tier.
@@ -934,6 +1075,12 @@ declare class DrawingController {
      * Patch one drawing. False when there is no such drawing, or when it is
      * read-only to the user and `options.force` is not set. A patch that
      * carries `policy` is the host's, and like a forced one records no step.
+     *
+     * Also false when the patch asks for a `space` the drawing could not be
+     * moved to (a tool without viewport support, or a pane with no place on
+     * screen, folded or hidden behind a maximized pane): the rest of the patch
+     * still applies, and the false tells a host that the drawing is not in the
+     * space it asked for, which a control showing that space has to say.
      */
     update(id: string, patch: DrawingPatch, options?: DrawingEditOptions): boolean;
     /**
@@ -947,6 +1094,14 @@ declare class DrawingController {
         id: string;
         patch: DrawingPatch;
     }>, options?: DrawingEditOptions): void;
+    /**
+     * A patch as it applies to `d`. A change of space comes out complete, with
+     * the anchors of the new space (converted at the view on screen unless the
+     * patch gives them), or is left out when it cannot be made; anchors of the
+     * space the drawing will not be in are left out too, so one drawing never
+     * carries two positions.
+     */
+    private _spacePatch;
     private _applyPatch;
     /** Delete one drawing. A read-only one goes only with `options.force`. */
     remove(id: string, options?: DrawingEditOptions): boolean;
@@ -1029,8 +1184,30 @@ declare class DrawingController {
     paste(): Promise<Drawing[]>;
     /** Resolve an id list to live drawings; defaults to the selection. */
     private _targets;
-    /** Fold a pane index from another chart onto a pane this one actually has. */
+    /** The slot this chart keeps its price pane in, read at each use because a host can move it. */
+    private _pricePane;
+    /**
+     * Drawings as the clipboard carries them: panes counted price pane first,
+     * the study panes after it in their order, the way a portable template
+     * counts them. A price pane at the top, where every build before the move
+     * kept it, is written exactly as before, and a drawing copied beside the
+     * candles pastes beside the candles on any chart in any arrangement.
+     */
+    private _portable;
+    /**
+     * Fold a clipboard pane onto a pane this chart actually has: clamped to the
+     * pane count in clipboard order, so a study drawing from a taller stack
+     * lands on the last study pane rather than on the price pane, then put in
+     * this chart's own slots around its price pane.
+     */
     private _clampPane;
+    /**
+     * A copy's anchors, offset from the original's in its own space. A viewport
+     * copy moves the paste offset in pixels on both axes, as a fraction of the
+     * pane it lands on, so it reads the same on a chart of any size, and stays
+     * on that pane's plot when the original sits at its edge.
+     */
+    private _offsetAnchors;
     /** Nudge every anchor so a pasted copy is not hidden under its original. */
     private _offsetPoints;
     /**
@@ -1177,6 +1354,72 @@ declare class DrawingController {
     private _toPixel;
     /** The inverse of `_toPixel`. */
     private _fromPixel;
+    /**
+     * The drawing's anchors in container media px, the space `timeToCoordinate`
+     * and `priceToCoordinate` answer in, whichever space it is anchored in. What
+     * a host places an overlay by (an inline editor, a popover). Null for an
+     * unknown id, or when the drawing's pane has no place on screen (folded to
+     * a strip, or hidden behind a maximized pane).
+     */
+    screenPoints(id: string): ScreenPoint[] | null;
+    /** A pane's price projection, when the host exposes one. */
+    private _pane;
+    /**
+     * Where a pane's plot is and how big, or null when it has none on screen:
+     * a folded pane maps no price, and a pane hidden by a maximize has no
+     * height. A fraction of either would be a fraction of nothing.
+     */
+    private _plotFrame;
+    /**
+     * The plot's left edge in container px: the chart-wide left axis column.
+     * Any bar maps to both a container x and a plot x, and their gap is the
+     * column; a chart with no bars reads it off the left price columns.
+     */
+    private _plotLeft;
+    /**
+     * A gesture's position on its pane's plot, in media px. y reads the price
+     * back through the pane's readout scale, the exact inverse of how the chart
+     * read it; x is the pointer's container x less the left column, or, for a
+     * payload without one, the time through the time axis.
+     */
+    private _gesturePlot;
+    /**
+     * Where a drag was pressed, on its pane's plot. Read from the press's time
+     * and price when the chart reports them, so the first move is measured from
+     * the press and not from itself; a chart with fewer than two bars has no
+     * time axis to read a position back from, so it measures from the first move.
+     */
+    private _dragOrigin;
+    /**
+     * Data anchors as fractions of their pane's plot at the view on screen, or
+     * null when it has none. What is on screen stays where it is; a drawing part
+     * way or wholly off the plot comes onto it, since once pinned no pan could
+     * bring it back. One that fits moves in whole. One wider or taller than the
+     * plot is cut to it on that axis instead, so every handle of a pinned box
+     * is on screen to be grabbed.
+     */
+    private _toViewport;
+    /**
+     * The inverse of `_toViewport`: fractions back to time and price at the view
+     * on screen, from where the drawing is painted, so it does not move.
+     */
+    private _fromViewport;
+    /**
+     * Anchors in plot px as the fractions a pinned drawing stores, moved first
+     * so its box lies inside the plot. Every gesture ends here, so what is
+     * stored is what is painted, and no drag can leave the box where the
+     * pointer cannot reach it.
+     */
+    private _pinPlot;
+    /**
+     * Pinned anchors moved by a screen distance in media px, from where the
+     * drawing is painted rather than from what it stores: a note the layer
+     * holds in from a stored place off the plot (a host's value, a larger
+     * chart) moves at once, with no dead travel before it starts.
+     */
+    private _shiftPinned;
+    /** Put a drawing's anchors back as a gesture found them. */
+    private _restoreAnchors;
     /**
      * `free` projected onto the nearest 45 degree ray from `anchor`, all in
      * screen space: the angle the eye reads is the one on the canvas, and a log
@@ -1250,7 +1493,7 @@ type DrawingLinkContextSource = DrawingLinkContext | (() => DrawingLinkContext |
 interface DrawingLinkOptions {
     enabled?: boolean;
 }
-interface DrawingLinkChart extends Pick<DrawingChartHost, 'on'> {
+interface DrawingLinkChart extends Pick<DrawingChartHost, 'on' | 'primaryPaneIndex'> {
     readonly isDestroyed?: boolean;
     getDataContext?(): Readonly<DrawingLinkContext> | undefined;
 }
@@ -1258,6 +1501,14 @@ interface DrawingLinkChart extends Pick<DrawingChartHost, 'on'> {
  * Existing local drawings stay local until `share` is called. Persisted shared
  * lineage reconnects across restores. Only price-pane drawings participate; time anchors
  * cross the boundary unchanged so each interval uses its own coordinate map.
+ *
+ * The price pane is each chart's own, in whatever slot that chart keeps it: one
+ * chart can hold it at the top and another below its studies. A shared drawing
+ * is therefore kept on slot 0 and put on each member's price pane as it is
+ * applied there, never copied across by slot.
+ *
+ * A drawing pinned to the viewport never participates, and pinning a shared one
+ * takes it out of the link on that chart alone: the other charts keep their copy.
  */
 declare class DrawingLinkGroup {
     private readonly _members;
@@ -1276,10 +1527,32 @@ declare class DrawingLinkGroup {
     /** Committed drawings remain on peers; transient previews are discarded. */
     remove(chart: DrawingLinkChart): void;
     destroy(): void;
+    /** The slot this member keeps its price pane in, read at each use because it moves. */
+    private _pricePane;
+    /** A shared drawing as it lands on one member: on that member's own price pane. */
+    private _onPricePane;
     private _eligible;
     private _create;
     private _reconnect;
     private _change;
+    /**
+     * A shared drawing pinned to the screen leaves the link on this chart. Its
+     * lineage mark goes too, or a restore would find the peers' copy by it and
+     * pull the drawing back to where they keep it.
+     */
+    private _unlink;
+    /**
+     * An unbound drawing that carries this chart's lineage mark, while a peer
+     * still holds that lineage, is one that left the link by being pinned and
+     * came back by undo: the undo put the mark back but no binding. It joins
+     * again, as the newest edit, so its state goes to the peers the way any
+     * other undo on a linked drawing does. If the peers have since deleted
+     * their copies it stays on this chart alone and loses the mark, since an
+     * edit never brings back another chart's deletion, and a later restore
+     * must not apply that deletion here. A mark no peer holds is left for a
+     * peer that has yet to join, as after any restore.
+     */
+    private _rejoin;
     private _commit;
     private _preview;
     private _syncOrder;
@@ -1807,6 +2080,13 @@ declare function toolCursor(id: string, opts?: ToolCursorOptions): string;
  * Hit ids are `draw:<id>` for the body and `draw:<id>#<n>` for anchor `n`, so
  * the controller can tell "move the whole shape" from "move this handle".
  *
+ * A viewport drawing (`space: 'viewport'`) skips the time and price mapping:
+ * its anchors are fractions of this pane's plot and scale by the plot size in
+ * the render context, which is all that pan and zoom never touch. The one step
+ * added is keeping its box inside the plot. Everything after the projection
+ * (paint, handles, hit-testing) is shared, so the two spaces cannot drift
+ * apart in how they are grabbed.
+ *
  * The hover ring, the magnet ring and the hover handles are all overlay
  * state: they change on every pointer move, so they must only ever cost the
  * top canvas. The layer that paints them is the one whose `requestUpdate`
@@ -2008,6 +2288,11 @@ declare function keyToDrawingAction(e: DrawingKeyEvent, ctx: DrawingKeyContext):
  * - An unregistered tool is not a reason to drop anything: a plugin tool may
  *   register after the layout is restored. This module never consults the
  *   registry, which also keeps it pure.
+ * - A viewport drawing keeps its `viewportPoints` and carries no data
+ *   anchors; one without usable viewport anchors is dropped, since falling
+ *   back to its data anchors would put it somewhere it never was. Data is the
+ *   default space and is never written out, so a document with no viewport
+ *   drawing comes back exactly as it went in.
  * - Garbage yields an empty document. This runs on the load path, where an
  *   exception would take the whole chart down with it.
  *
@@ -2117,4 +2402,4 @@ declare const PATTERN_DRAWING_TOOLS: readonly DrawingTool[];
 
 declare const DRAW_TIER: "draw";
 
-export { ADVANCED_GEOMETRY_TOOLS, ADVANCED_LINE_TOOLS, ALIGN_OPTIONS, ANCHORED_VWAP, ARC, ARROW, ARROW_DOWN, ARROW_LEFT, ARROW_RIGHT, ARROW_UP, type AnalysisProfileRow, type AnalysisStatus, type AnchoredVwapOptions, type AnchoredVwapPoint, type AnchoredVwapResult, type AnchoredVwapSource, BALLOON, BRUSH, BUILTIN_DRAWING_TOOLS, CALLOUT, CHROME_ICONS, CHROME_ICON_ATTRS, CHROME_ICON_FILLED, CHROME_ICON_STROKE, CHROME_ICON_VIEWBOX, CIRCLE, COLOR_FIELD, COMMENT, CROSS_LINE, CURVE, CYCLE_PALETTE, CYCLIC_LINES, type ClipboardPort, DATE_RANGE, DEFAULT_FIB, DEFAULT_FIB_FAN, DEFAULT_FIB_TIME_ZONE, DEFAULT_GANN_BOX, DEFAULT_GANN_FAN, DOUBLE_CURVE, DRAWING_CLIPBOARD_KEY, DRAWING_CLIPBOARD_VERSION, DRAWING_STATE_VERSION, DRAWING_TOOL_ICONS, DRAW_TIER, type DrawContext, type Drawing, type DrawingChangeKind, type DrawingChartHost, DrawingClipboard, type DrawingClipboardOptions, DrawingController, type DrawingControllerOptions, type DrawingEditOptions, type DrawingGroup, type DrawingInput, type DrawingKeyAction, type DrawingKeyContext, type DrawingKeyEvent, DrawingLayer, type DrawingLayerOrder, type DrawingLinkChart, type DrawingLinkContext, type DrawingLinkContextSource, DrawingLinkGroup, type DrawingLinkOptions, type DrawingPatch, type DrawingPoint, type DrawingPointerKind, type DrawingPolicy, type DrawingStyle, type DrawingText, type DrawingTool, type DrawingValueContext, type DrawingsDocument, ELLIPSE, EXTENDED_LINE, EXTEND_FIELDS, type ExpandContext, FIB_CHANNEL, FIB_EXTENSION, FIB_FAN, FIB_RETRACEMENT, FIB_TIME_ZONE, FILL_FIELDS, FIXED_RANGE_VOLUME_PROFILE, FLAG_MARK, FONT_FIELDS, FONT_OPTIONS, FORECAST, type FibLevel, type FieldGroup, type FieldKind, type FixedRangeVolumeProfileOptions, type FixedRangeVolumeProfileResult, GANN_BOX, GANN_FAN, HIGHLIGHTER, HORIZONTAL_LINE, HORIZONTAL_RAY, type HitContext, ICON_ATTRS, ICON_STROKE, ICON_SYMBOL_PREFIX, ICON_VIEWBOX, type IconAttrs, type IconSvgOptions, LEVEL_FIELDS, LEVEL_NEUTRAL, LINE_FIELDS, LINE_STYLE_FIELD, LINE_STYLE_OPTIONS, LINE_WIDTH_FIELD, LONG_POSITION, MEASURE, type MagnetMode, NOTE, NUDGE_STEP_PX, NUDGE_STEP_SHIFT_PX, PARALLEL_CHANNEL, PATH, PATTERN_DRAWING_TOOLS, PLATE_TEXT_FIELDS, POLYLINE, PRICE_LABEL, PRICE_NOTE, PRICE_RANGE, RAY, RECTANGLE, ROTATED_RECTANGLE, SHAPE_TEXT_FIELDS, SHORT_POSITION, SHOW_LABELS_FIELD, SIGNPOST, SINE_LINE, type ScreenPoint, type SettingsField, type SettingsSchema, type ShortcutEvent, TABLE, TEXT, TEXT_FIELDS, TEXT_POSITION_OPTIONS, TEXT_VALUE_FIELD, TIME_CYCLES, TREND_LINE, TRIANGLE, type ToolCursorOptions, VALIGN_OPTIONS, VERTICAL_LINE, anchoredVwapAnalysis, applyDrawingSettings, boundsOf, catmullRom, chromeIcon, chromeIconIds, chromeIconSvg, clearMemoryClipboard, cloneDrawing, cloneLevels, coerceSettingValue, composeSettings, createDrawingLinkGroup, cycleColor, decodeClipboardPayload, distToEllipse, distToLine, distToPolyline, distToRect, distToSegment, drawingSettingsSchema, drawingShortcuts, drawingToolIcon, drawingToolIconIds, encodeClipboardPayload, extendSegment, fixedRangeVolumeProfileAnalysis, formatRatio, gannLabel, getDrawingTool, hasDrawingTool, iconSprite, iconSvg, iconUse, keyToDrawingAction, levelColor, matchDrawingShortcut, migrateDrawings, pressureWidth, rdpSimplify, readDrawingSetting, readDrawingSettings, rectOf, registerBuiltinDrawingTools, registerDrawingTool, registeredDrawingTools, sanitizeDrawing, sortByZIndex, systemClipboard, toolCursor };
+export { ADVANCED_GEOMETRY_TOOLS, ADVANCED_LINE_TOOLS, ALIGN_OPTIONS, ANCHORED_VWAP, ARC, ARROW, ARROW_DOWN, ARROW_LEFT, ARROW_RIGHT, ARROW_UP, type AnalysisProfileRow, type AnalysisStatus, type AnchoredVwapOptions, type AnchoredVwapPoint, type AnchoredVwapResult, type AnchoredVwapSource, BALLOON, BRUSH, BUILTIN_DRAWING_TOOLS, CALLOUT, CHROME_ICONS, CHROME_ICON_ATTRS, CHROME_ICON_FILLED, CHROME_ICON_STROKE, CHROME_ICON_VIEWBOX, CIRCLE, COLOR_FIELD, COMMENT, CROSS_LINE, CURVE, CYCLE_PALETTE, CYCLIC_LINES, type ClipboardPort, DATE_RANGE, DEFAULT_FIB, DEFAULT_FIB_FAN, DEFAULT_FIB_TIME_ZONE, DEFAULT_GANN_BOX, DEFAULT_GANN_FAN, DOUBLE_CURVE, DRAWING_CLIPBOARD_KEY, DRAWING_CLIPBOARD_VERSION, DRAWING_STATE_VERSION, DRAWING_TOOL_ICONS, DRAW_TIER, type DrawContext, type Drawing, type DrawingChangeKind, type DrawingChartHost, DrawingClipboard, type DrawingClipboardOptions, DrawingController, type DrawingControllerOptions, type DrawingEditOptions, type DrawingGroup, type DrawingInput, type DrawingKeyAction, type DrawingKeyContext, type DrawingKeyEvent, DrawingLayer, type DrawingLayerOrder, type DrawingLinkChart, type DrawingLinkContext, type DrawingLinkContextSource, DrawingLinkGroup, type DrawingLinkOptions, type DrawingPatch, type DrawingPlacementOptions, type DrawingPoint, type DrawingPointerKind, type DrawingPolicy, type DrawingSpace, type DrawingStyle, type DrawingText, type DrawingTool, type DrawingValueContext, type DrawingsDocument, ELLIPSE, EXTENDED_LINE, EXTEND_FIELDS, type ExpandContext, FIB_CHANNEL, FIB_EXTENSION, FIB_FAN, FIB_RETRACEMENT, FIB_TIME_ZONE, FILL_FIELDS, FIXED_RANGE_VOLUME_PROFILE, FLAG_MARK, FONT_FIELDS, FONT_OPTIONS, FORECAST, type FibLevel, type FieldGroup, type FieldKind, type FixedRangeVolumeProfileOptions, type FixedRangeVolumeProfileResult, GANN_BOX, GANN_FAN, HIGHLIGHTER, HORIZONTAL_LINE, HORIZONTAL_RAY, type HitContext, ICON_ATTRS, ICON_STROKE, ICON_SYMBOL_PREFIX, ICON_VIEWBOX, type IconAttrs, type IconSvgOptions, LEVEL_FIELDS, LEVEL_NEUTRAL, LINE_FIELDS, LINE_STYLE_FIELD, LINE_STYLE_OPTIONS, LINE_WIDTH_FIELD, LONG_POSITION, MEASURE, type MagnetMode, NOTE, NUDGE_STEP_PX, NUDGE_STEP_SHIFT_PX, PARALLEL_CHANNEL, PATH, PATTERN_DRAWING_TOOLS, PLATE_TEXT_FIELDS, POLYLINE, PRICE_LABEL, PRICE_NOTE, PRICE_RANGE, RAY, RECTANGLE, ROTATED_RECTANGLE, SHAPE_TEXT_FIELDS, SHORT_POSITION, SHOW_LABELS_FIELD, SIGNPOST, SINE_LINE, SPACE_FIELD, SPACE_OPTIONS, type ScreenPoint, type SettingsField, type SettingsSchema, type ShortcutEvent, TABLE, TEXT, TEXT_FIELDS, TEXT_POSITION_OPTIONS, TEXT_VALUE_FIELD, TIME_CYCLES, TREND_LINE, TRIANGLE, type ToolCursorOptions, VALIGN_OPTIONS, VERTICAL_LINE, type ViewportPoint, anchoredVwapAnalysis, applyDrawingSettings, boundsOf, catmullRom, chromeIcon, chromeIconIds, chromeIconSvg, clearMemoryClipboard, cloneDrawing, cloneLevels, coerceSettingValue, composeSettings, createDrawingLinkGroup, cycleColor, decodeClipboardPayload, distToEllipse, distToLine, distToPolyline, distToRect, distToSegment, drawingSettingsSchema, drawingShortcuts, drawingToolIcon, drawingToolIconIds, encodeClipboardPayload, extendSegment, fixedRangeVolumeProfileAnalysis, formatRatio, gannLabel, getDrawingTool, hasDrawingTool, iconSprite, iconSvg, iconUse, keyToDrawingAction, levelColor, matchDrawingShortcut, migrateDrawings, pressureWidth, rdpSimplify, readDrawingSetting, readDrawingSettings, rectOf, registerBuiltinDrawingTools, registerDrawingTool, registeredDrawingTools, sanitizeDrawing, sortByZIndex, systemClipboard, toolCursor };