openalgo-charts 2.5.2 → 2.5.4

package/README.md

@@ -12,7 +12,7 @@ with no runtime dependencies.
 [![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)
 [![npm downloads](https://img.shields.io/npm/dm/openalgo-charts.svg?color=0ea5e9&label=npm%20downloads)](https://www.npmjs.com/package/openalgo-charts)
-[![tests](https://img.shields.io/badge/engine%20tests-6023%20passing-brightgreen.svg)](#develop)
+[![tests](https://img.shields.io/badge/engine%20tests-6095%20passing-brightgreen.svg)](#develop)
 [![dependencies](https://img.shields.io/badge/runtime%20deps-0-brightgreen.svg)](#principles)
 
 [**Documentation**](https://marketcalls.github.io/openalgo-charts/)  ·  [**Live examples**](https://marketcalls.github.io/openalgo-charts/examples)  ·  [**Getting started**](./docs/getting-started.md)  ·  [**Migrating to 2.0**](./docs/migrating-to-2.md)  ·  [**Architecture**](./ARCHITECTURE.md)
@@ -25,7 +25,7 @@ with no runtime dependencies.
 npm install openalgo-charts
 ```
 
-Current version: **2.5.2**. Add anchored volume studies, share drawings and appearance, and open grouped timeline events.
+Current version: **2.5.4**. Go to any date, lay out a grid of charts, collapse panes, route study output and lock host drawings.
 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.2 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.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>
 
 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.2/dist/openalgo-charts.mjs';
+  import { createChart, generateBars } from 'https://unpkg.com/openalgo-charts@2.5.4/dist/openalgo-charts.mjs';
   const chart = createChart(document.getElementById('chart'), { timezone: 'Asia/Kolkata' });
   chart.addSeries('candlestick').setData(generateBars(1700000000, 200, 3600));
   chart.fitContent();
@@ -142,7 +142,10 @@ widget.draw;    // the DrawingController the rail drives
 
 The optional widget adds symbol search, interval and chart-type controls, a drawing
 toolbar, settings, indicators, a status line, mobile controls and layout persistence.
-Its dialogs use the chart's settings schemas and follow the active theme.
+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.
 
 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
@@ -157,17 +160,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 | 95.04 kB |
-| `openalgo-charts/indicators` | 105 built-in indicators, calculation helpers and helpers for studies that use external data | 29.84 kB |
-| `openalgo-charts/draw` | 87 drawing tools + a headless drawing controller, clipboard, settings schema, level palette, freehand geometry and SVG icons | 40.73 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 | 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/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/webgl` | GPU drawing for supported series, with Canvas 2D fallback | 6.39 kB |
-| `openalgo-charts/widget` | `createWidget`: toolbar, drawing controls, dialogs, mobile controls, status line, shortcuts and optional layout persistence | 51.06 kB |
-| `openalgo-charts/workspace` | Validated workspace and indicator-template documents, named catalogs with revision checks, asynchronous storage and an IndexedDB adapter; no DOM | 5.55 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 |
 
-Everything together is **256.08 kB Brotli**; a widget terminal with built-in indicators (base + draw + indicators + widget) is 216.67 kB. Figures are measured from the 2.5.2 release build. The trade tier is 8.01 kB on its own; base + trade costs 103.05 kB. Sizes use decimal 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.
 
 ## What's built
 
@@ -225,7 +228,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. 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'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.
 
@@ -252,7 +255,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 / 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 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.
 
@@ -322,6 +325,8 @@ Hover one chart and the same **instant** is marked on the others; pan or zoom on
 
 Nothing crosses a chart boundary as a logical index. The x axis is a gapless index over each chart's own bars, so index 300 is a different instant on every chart: every value is converted index to time on the sender and time back to index on the receiver, against that chart's own data. A daily chart and an hourly chart with different history depth therefore stay on the same instant, which the naive index copy gets right only when both charts hold the same bars. An instant outside a follower's first or last bar is an absence, not a gap, so it draws nothing; inside its range with no bar there it snaps to the nearest bar in time, or draws nothing under `whenMissing: 'hide'`. The linked crosshair is a vertical line only, at reduced opacity: a mirrored horizontal line would assert a price that belongs to another instrument.
 
+For a ready-made grid of widgets with these links, splitters and saved layouts, use `createChartGrid` from `openalgo-charts/widget`.
+
 Symbol sync remains a host partnership even when using optional instrument metadata: the host emits `'symbol'` on the chart's bus (or calls `group.setSymbol`) and supplies the per-member `onSymbol` that loads the bars. A member with no `onSymbol` broadcasts but never follows, which is how you pin one chart of a grid.
 
 ### Settings &amp; context menu
@@ -489,17 +494,17 @@ Enforced in CI by [`size-limit`](./.size-limit.json). Nothing is excluded, becau
 
 | Bundle | Limit | Actual |
 |---|---|---|
-| Base engine | 95.5 kB | 95.04 kB |
-| Base + trade | 103.5 kB | 103.05 kB |
-| Indicators tier | 30 kB | 29.84 kB |
-| Draw tier | 41 kB | 40.73 kB |
+| 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 |
 | Transform tier | 6 kB | 4.50 kB |
 | Profile tier | 15 kB | 14.96 kB |
 | WebGL2 tier | 7 kB | 6.39 kB |
-| Widget tier | 51.5 kB | 51.06 kB |
-| Widget terminal (base + draw + indicators + widget) | 217 kB | 216.67 kB |
-| Workspace tier | 6 kB | 5.55 kB |
-| **Everything** | 256.75 kB | 256.08 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 |
 
 ## Documentation
 
@@ -544,8 +549,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): 6023 across 256 files
-npm run test:demo  # reference-host tests: 415 across 32 files
+npm test           # engine unit tests (Vitest): 8228 across 359 files
+npm run test:demo  # reference-host tests: 542 across 50 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
@@ -563,7 +568,7 @@ npm run verify     # lint + types + unit + endurance harness + build + demo + dt
 
 ## Status &amp; limitations
 
-Version **2.5.2**. All engine build phases are implemented. Upgrading a 1.9.x host: [Migrating to 2.0](./docs/migrating-to-2.md).
+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).
 
 Known gaps, stated plainly:
 

package/dist/draw/index.d.ts

@@ -250,6 +250,41 @@ interface DrawingStyle {
     /** Brush: let pen pressure drive the stroke width. */
     pressure?: boolean;
 }
+/**
+ * What a host allows the user to do with one drawing. The flags are
+ * independent of one another and of `locked`, and each defaults to true, so a
+ * drawing without a policy behaves exactly as one did before policies
+ * existed. A copy (paste, duplicate) never inherits a policy: it is the
+ * user's own drawing.
+ *
+ * `selectable`, `persistent` and `listed` bind every caller. `editable`
+ * restricts the user: the controller cannot tell a click from a call, so its
+ * methods treat every call as the user's unless it passes `{ force: true }`
+ * (see `DrawingEditOptions`), which is how the host that placed the drawing
+ * moves or retires it. Stacking order (front, back, either side of the
+ * series) is outside the policy.
+ */
+interface DrawingPolicy {
+    /**
+     * `false`: never joins the selection, whoever asks. A click passes through
+     * to what lies under it, and nothing hovers, drags or selects it.
+     */
+    selectable?: boolean;
+    /**
+     * `false`: read-only to the user. It still selects, copies and duplicates,
+     * but nothing moves, reshapes, restyles, hides, locks, cuts, deletes or
+     * regroups it, and undo and redo never touch it or the group it is in.
+     */
+    editable?: boolean;
+    /**
+     * `false`: transient. Left out of `toJSON`, and so out of the chart state
+     * and every saved layout, while it renders and undoes as usual in the
+     * session. A restore replaces it with what was saved.
+     */
+    persistent?: boolean;
+    /** `false`: left out of the object inventory (`ChartObjects`) and every panel built on it. */
+    listed?: boolean;
+}
 interface Drawing {
     id: string;
     /** Registered tool id. */
@@ -265,8 +300,14 @@ interface Drawing {
      */
     props?: Record<string, unknown>;
     paneIndex: number;
-    /** Locked drawings render but cannot be selected or dragged. */
+    /**
+     * Locked drawings render but cannot be selected or dragged on the chart.
+     * The user toggles it; a host restriction the user cannot lift is a
+     * {@link DrawingPolicy}.
+     */
     locked?: boolean;
+    /** Host restrictions on this drawing. Absent means none. */
+    policy?: DrawingPolicy;
     /** Default true. */
     visible?: boolean;
     /**
@@ -288,17 +329,27 @@ type DrawingInput = Omit<Drawing, 'id' | 'zIndex' | 'createdAt'> & {
     zIndex?: number;
     createdAt?: number;
 };
-/** The fields `DrawingController.update` and `updateMany` can change. */
-type DrawingPatch = Partial<Pick<Drawing, 'points' | 'style' | 'text' | 'props' | 'locked' | 'visible' | 'zIndex'>>;
+/**
+ * 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'>>;
 /** The persisted shape's version; bumped when {@link Drawing} changes. */
 declare const DRAWING_STATE_VERSION = 2;
 /**
  * What `toJSON` returns and `ChartState.drawings` carries. Versioned so a 1.9.x
  * save (a bare `Drawing[]`) is recognisable and upgraded rather than misread.
  */
+/** A named set of drawing ids. A drawing belongs to at most one group. */
+interface DrawingGroup {
+    id: string;
+    name: string;
+    members: string[];
+}
 interface DrawingsDocument {
     version: 2;
     drawings: Drawing[];
+    groups?: DrawingGroup[];
 }
 /** A point mapped to the pane, in media px. */
 interface ScreenPoint {
@@ -678,10 +729,12 @@ interface DrawingChartHost {
     timeToCoordinate?(time: number): number;
     coordinateToTime?(x: number): number;
     /**
-     * Optional, and used only to keep 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 it names, so without this a drawing copied out of an indicator
-     * pane would conjure an empty pane in a single-pane chart.
+     * 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
+     * it names, so without this a drawing copied out of an indicator pane would
+     * conjure an empty pane in a single-pane chart. An entry with `priceToY` and
+     * `yToPrice`, as a chart pane has, also lets an alert read a drawing on a
+     * pane the chart maps no price for, one collapsed to its header strip.
      */
     panes?(): readonly unknown[];
 }
@@ -728,12 +781,40 @@ interface DrawingControllerOptions {
 }
 /** 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. */
+interface DrawingEditOptions {
+    /**
+     * Reach drawings whose policy sets `editable: false` as well, and the
+     * groups that hold them. Without it they are left exactly as they are,
+     * which is what keeps every control a host wires to the user off them. The
+     * host that placed such a drawing passes it to move, restyle, regroup or
+     * retire it. A forced call is the host's own act, not the user's, so it
+     * records no undo step, and every step already recorded takes it too: no
+     * later undo or redo reverses it, and a step it leaves with nothing to do
+     * is dropped.
+     *
+     * Cost: taking a call into the recorded steps is one pass over the undo
+     * and redo history, parsing and rewriting both snapshots of every step, so
+     * it grows with the number of recorded steps (see `historyLimit`) times
+     * the drawing count. A forced delete, a forced grouping call, a forced
+     * patch to a drawing the user may edit or one that carries `zIndex`, any
+     * patch that carries `policy` and a linked chart's change of policy make
+     * that pass. A forced patch to a read-only drawing that carries neither
+     * `policy` nor `zIndex` (a level the host trails on every tick) makes
+     * none: history cannot reach that drawing's content while it stays
+     * read-only, so the patch is held and goes in with the next pass, which a
+     * change of its policy always makes.
+     */
+    force?: boolean;
+}
 declare class DrawingController {
     private readonly _chart;
     private _opts;
     private readonly _clipboard;
     private readonly _layers;
     private _drawings;
+    private _groups;
+    private _nextGroup;
     private readonly _linkedPreviews;
     private _destroyed;
     private _tool;
@@ -758,6 +839,8 @@ declare class DrawingController {
     private _undo;
     private _redo;
     private _pendingHistory;
+    /** The host's patches the recorded steps have yet to take, merged per drawing. */
+    private readonly _hostPatches;
     /**
      * One gesture's starting state. `items` are ids rather than objects because
      * an undo mid-drag replaces every drawing object, and a stale reference
@@ -797,6 +880,31 @@ declare class DrawingController {
      * moves one; the list is the tie-break for equal `zIndex`, so it is also the
      * paint order within a band.
      */
+    /** Named drawing sets, returned as detached records. */
+    groups(): readonly DrawingGroup[];
+    /**
+     * Group live drawings, replacing any previous membership for those ids. A
+     * read-only drawing's group is the host's, so it is left where it is
+     * unless `options.force` is set.
+     */
+    createGroup(name: string, ids: readonly string[], options?: DrawingEditOptions): DrawingGroup | null;
+    /** Rename a group. One that holds a read-only drawing is the host's, and needs `options.force`. */
+    renameGroup(id: string, name: string, options?: DrawingEditOptions): boolean;
+    /**
+     * Remove a group, optionally deleting all its drawings as one edit. One
+     * that holds a read-only drawing is the host's, and needs `options.force`.
+     */
+    removeGroup(id: string, removeDrawings?: boolean, options?: DrawingEditOptions): boolean;
+    /**
+     * Make a grouping edit. The host's forced one is its own act, so every
+     * recorded step takes it as well, and no undo or redo reverses it.
+     */
+    private _regroup;
+    /** The live group `id`, unless it holds a read-only drawing and the call is not forced. */
+    private _group;
+    /** Move one step through the rendered stack, preserving the side of the series. */
+    reorder(id: string, direction: -1 | 1): boolean;
+    private _remapPanes;
     drawings(): readonly Drawing[];
     get(id: string): Drawing | undefined;
     get isDestroyed(): boolean;
@@ -810,7 +918,11 @@ declare class DrawingController {
     alertInfo(id: string): AlertDrawingInfo;
     /** Numeric drawing value using the actual pane projection and collapsed time axis. */
     valueAt(id: string, time: number, level?: string): AlertDrawingValue | undefined;
-    /** Add a fully-specified drawing (import, or a host-authored one). */
+    /**
+     * Add a fully-specified drawing (import, or a host-authored one). One that
+     * carries a restriction is the host's, and placing it is not a step the
+     * user can take back, so it is not recorded.
+     */
     add(drawing: DrawingInput): Drawing;
     /**
      * Append one drawing without touching history or the layers. Split out so a
@@ -818,32 +930,46 @@ declare class DrawingController {
      */
     private _insert;
     private _mintId;
-    update(id: string, patch: DrawingPatch): boolean;
+    /**
+     * 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.
+     */
+    update(id: string, patch: DrawingPatch, options?: DrawingEditOptions): boolean;
     /**
      * Patch several drawings as one undo entry: a colour change across a
      * multi-selection is one edit to the user, so it is one Ctrl+Z too. Ids that
-     * no longer exist are skipped; nothing is recorded when none exist.
+     * no longer exist are skipped, and so are read-only drawings unless
+     * `options.force` is set; nothing is recorded when nothing is left, or
+     * when every patch is the host's (forced, or carrying `policy`).
      */
     updateMany(patches: ReadonlyArray<{
         id: string;
         patch: DrawingPatch;
-    }>): void;
+    }>, options?: DrawingEditOptions): void;
     private _applyPatch;
-    remove(id: string): boolean;
-    /** Delete several drawings as one undo entry. Unknown ids are ignored. */
-    removeMany(ids: readonly string[]): void;
+    /** Delete one drawing. A read-only one goes only with `options.force`. */
+    remove(id: string, options?: DrawingEditOptions): boolean;
+    /**
+     * Delete several drawings as one undo entry. Unknown ids are ignored, and
+     * read-only drawings stay unless `options.force` is set.
+     */
+    removeMany(ids: readonly string[], options?: DrawingEditOptions): void;
     /**
      * The delete shared by `remove`, `removeMany`, `cut` and `clear`. Returns
      * what went, and records nothing when nothing did.
      */
     private _removeIds;
-    clear(): void;
+    /** Delete every drawing the user may, as one undo entry; `options.force` takes the read-only ones too. */
+    clear(options?: DrawingEditOptions): void;
     /**
      * Replace the selection, or with `additive` toggle each id into it (the
-     * shift-click gesture). Ids that name nothing are ignored, so the selection
-     * never refers to a drawing that is not there. Pass null to clear.
+     * shift-click gesture). Ids that name nothing, or a drawing whose policy
+     * says it cannot be selected, are ignored, so the selection only ever holds
+     * drawings that are there to act on. Pass null to clear.
      */
     select(id: string | readonly string[] | null, additive?: boolean): void;
+    private _selectable;
     /** The primary selection: the first id picked, or null. */
     selected(): string | null;
     /** Every selected id, in the order they were picked. */
@@ -865,13 +991,14 @@ declare class DrawingController {
     /**
      * Move drawings by a screen distance, `dx` right and `dy` down in media px,
      * as one undo entry. Pixels rather than data units so an arrow key moves a
-     * shape the same visible amount on every pane and scale. Locked drawings
-     * stay put.
+     * shape the same visible amount on every pane and scale. Locked and
+     * read-only drawings stay put.
      */
     nudge(ids: readonly string[], dxPx: number, dyPx: number): void;
     /**
      * Clone drawings, offset like a paste so the copies are visibly new, and
-     * select the clones. One undo entry. Ids that name nothing are ignored.
+     * select the clones. One undo entry. Ids that name nothing are ignored. A
+     * clone is the user's own drawing, so it carries no policy.
      */
     duplicate(ids: readonly string[]): Drawing[];
     /**
@@ -883,7 +1010,8 @@ declare class DrawingController {
     /**
      * Copy, then delete. The delete happens **only** after the clipboard write
      * resolves successfully, so a refused write leaves the model exactly as it
-     * was rather than destroying a drawing that went nowhere.
+     * was rather than destroying a drawing that went nowhere. A read-only
+     * drawing cannot be deleted, so it is not cut either: it stays, uncopied.
      */
     cut(target?: string | readonly string[] | null): Promise<boolean>;
     /**
@@ -915,13 +1043,25 @@ declare class DrawingController {
     private _offsetTime;
     undo(): boolean;
     redo(): boolean;
+    /**
+     * Move the model from one snapshot to the other; false when the policy left
+     * nothing to move. Without `kind` it only answers, and moves nothing.
+     */
     private _applyHistory;
-    /** Drop selected ids the model no longer holds, after a history jump. */
+    /** Drop selected ids the model no longer holds, or that can no longer be selected. */
     private _pruneSelection;
     canUndo(): boolean;
     canRedo(): boolean;
-    /** Serialisable document, the same shape `ChartState.drawings` carries. */
+    /**
+     * Serialisable document, the same shape `ChartState.drawings` carries.
+     * Transient drawings (`policy.persistent` false) are left out, and so is
+     * their group membership.
+     */
     toJSON(): DrawingsDocument;
+    /** `drawings` as a document, with the groups narrowed to them. */
+    private _document;
+    /** Every drawing, transient ones too: an undo in the session reaches them. */
+    private _historyText;
     /**
      * Replace every drawing. Accepts a {@link DrawingsDocument} or a 1.9.x bare
      * `Drawing[]`; both go through the migration, so an old save upgrades on
@@ -1080,6 +1220,24 @@ declare class DrawingController {
      */
     private _syncSnapRing;
     private _pushUndo;
+    /**
+     * Open an edit: recorded, or, for a change the history does not hold (a
+     * host placing or moving a read-only drawing), not recorded and leaving
+     * both branches alone. Either way a drag in progress ends first.
+     */
+    private _begin;
+    /**
+     * What the host does (a policy, a forced call) is its own act and never
+     * history's to reverse: `edit` makes the same change to every recorded
+     * snapshot, as if it had always been so, and a step left with nothing to do
+     * is dropped, so `canUndo` and `canRedo` match what a press would do. The
+     * step still being recorded stays whatever it holds so far. `edit` may
+     * share live objects, since each snapshot is serialised at once. The
+     * host's patches still held back go in first, being older. Both snapshots
+     * of every step are parsed and written, which is why a forced move of a
+     * read-only drawing is held back rather than paying for this.
+     */
+    private _rebase;
 }
 
 /** Both fields must be known. A host may use its feed namespace as the exchange. */
@@ -1959,4 +2117,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 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 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 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 };