openalgo-charts 1.2.0 → 1.4.0

package/README.md

@@ -4,12 +4,12 @@
 
 **A from-scratch, dependency-free HTML5-canvas charting engine for OpenAlgo.**
 
-Professional interactive charts, indicators, drawing tools, order flow, and on-chart trading — six lazy-loaded tiers, zero runtime dependencies, ~37 KB Brotli for the base engine.
+Professional interactive charts, indicators, drawing tools, order flow, market replay, linked chart grids, and on-chart trading. Six lazy-loaded tiers, zero runtime dependencies, ~53 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-37%20KB%20base%20%C2%B7%2088%20KB%20all%20tiers-brightgreen.svg)](#size-budget)
-[![tests](https://img.shields.io/badge/tests-1001%20passing-brightgreen.svg)](#develop)
+[![bundle](https://img.shields.io/badge/brotli-53%20KB%20base%20%C2%B7%20111%20KB%20all%20tiers-brightgreen.svg)](#size-budget)
+[![tests](https://img.shields.io/badge/tests-1719%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)  ·  [**Architecture**](./ARCHITECTURE.md)
@@ -60,19 +60,19 @@ Import only what you use. Each tier is a separate bundle that registers into the
 
 | Import | Contents | Brotli |
 |---|---|---|
-| `openalgo-charts` | Engine, 13 chart types, panes & scales, primitives, registries, chart state, trading overlay, OpenAlgo feeds | 37.0 KB |
-| `openalgo-charts/indicators` | 91 built-in indicators + the Tier-2 (external-data) contract | 24.7 KB |
-| `openalgo-charts/draw` | 43 drawing tools + a headless drawing controller | 11.7 KB |
+| `openalgo-charts` | Engine, 13 chart types, panes & scales, primitives, registries, chart state, chart linking, bar cache, interval registry, trading overlay, OpenAlgo feeds | 52.9 KB |
+| `openalgo-charts/indicators` | 91 built-in indicators + the Tier-2 (external-data) contract | 24.9 KB |
+| `openalgo-charts/draw` | 43 drawing tools + a headless drawing controller and clipboard | 13.1 KB |
 | `openalgo-charts/transform` | Heikin Ashi, Renko, Range bars, Line Break, Point & Figure, Kagi | 2.7 KB |
-| `openalgo-charts/profile` | Volume Profile, Market Profile (TPO), Footprint, order flow | 10.1 KB |
+| `openalgo-charts/profile` | Volume Profile, Market Profile (TPO), Footprint, order flow | 10.7 KB |
 | `openalgo-charts/trade` | Order / position / bracket tools + DOM ladder | 6.6 KB |
 
-Everything together is **88.2 KB Brotli**. Figures are the measured `size-limit` output; the trade tier is a delta over the base, which is why base + trade (43.6 KB) is less than their listed sum.
+Everything together is **110.8 KB Brotli**. Figures are the measured `size-limit` output; the trade tier is a delta over the base, which is why base + trade (59.5 KB) is less than their listed sum.
 
 ## What's built
 
 ### Chart types & 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 & Figure** (fixed / percent / ATR box sizing, high-low or close construction), and Kagi.
+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 & Figure** (fixed / percent / ATR box sizing, high-low or close construction), and Kagi.
 
 ### Indicators
 
@@ -86,7 +86,7 @@ macd.setSettings({ 'macd:width': 2, 'macd:lineStyle': 'dashed' });
 
 91 built-ins across Trend, Momentum, Volatility and Volume, from the everyday (SMA, EMA, WMA, VWAP, Bollinger Bands, RSI, MACD, Stochastic, ADX/DMI, ATR) through Supertrend, HalfTrend, Ichimoku, Keltner, Donchian, Chandelier Exit and CPR with floor pivots to Connors RSI, Fisher Transform, Woodies CCI, Klinger, Vortex, WaveTrend Pro, Chop Zone and Williams Fractals. Twenty-five of them draw shaded bands, five emit named buy/sell markers, and Seasonality draws a monthly return heatmap as a table over the chart. The full catalogue with ids and defaults is in the docs.
 
-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).
+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
 
@@ -99,10 +99,81 @@ draw.setTool('trend-line');   // the next two clicks place it
 
 43 tools. Lines: trend line, ray, extended line, arrow, horizontal line/ray, vertical line, cross line. Shapes: rectangle, rotated rectangle, ellipse, circle, triangle. Paths: path, polyline, arc, curve, double curve. Channels: parallel channel, fib channel. Fibonacci: retracement, extension, time zone, speed fan. Gann: fan, box. Cycles: cyclic lines, time cycles, sine line. Forecasting: long/short position (1:1 from one click, with risk/reward and risk-based sizing), forecast. Measurers: price range, date range, measure. Arrows: mark up, mark down. Text and notes: text, price label, callout, flag mark. Brushes: brush, highlighter (freehand).
 
-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. Anchors are `{ time, price }`, never pixels, so they survive zoom and resolve inside collapsed session gaps and past the last bar.
 
-### Panes & 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.
+`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.
+
+### Panes, scales & 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.
+
+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.
+
+### Reference levels and axis chrome
+
+```ts
+import { PriceLevels } from 'openalgo-charts';
+
+const levels = new PriceLevels({
+  levels: { previousClose: { line: true, label: true }, sessionHigh: { line: true, label: false } },
+});
+chart.addPrimitive(levels, 0);
+levels.available('bid');   // false until a quote is fed: render that control disabled, not hidden
+```
+
+One primitive over ten levels: previous close, session high and low, last price, the four extended-hours opens and closes, and bid and ask. Each level's line across the plot and its tag on the price axis are two flags in the same options group, so they cannot drift apart. The session comes from the gaps in the bars rather than from a calendar midnight, and the session in view follows the viewport's right edge, so scrolling back through history moves the previous close back with it. A level with no data is `null`, never `0`: nothing draws at zero, and `available(kind)` is the signal to render that control disabled with its state visible instead of hiding it.
+
+Axis chrome is off until a chart asks for it. `createChart(el, { axisChrome: { sessionClock: true, barCountdown: true } })` puts a live clock in the corner where the two axis strips meet, in the chart's own timezone with the zone's UTC offset under it, and a countdown to the current bar's close as a second row inside the last-price tag, with the interval read back off the bars so a timeframe switch is followed. Tick labels that the last-price tag would cover are dropped rather than drawn through it, on a priority order that puts the crosshair above the last price, above a price line, above a session level.
+
+### Timezones
+
+```ts
+const chart = createChart(el, { timezone: 'America/New_York' });
+chart.setTimezone('Europe/London');    // relabels and recomputes on the next frame
+```
+
+An IANA name, never a fixed offset, so daylight saving is followed rather than approximated. The zone drives the time axis (including which ticks escalate to a day, month or year label), the crosshair time tag, and every calendar-anchored study (VWAP and TWAP anchors, CPR's weekly and monthly frames, the month a Seasonality bar counts in), and it rides along in `getState()`. Profile session windows carry their own zone, so `TRADING_HOURS['us-regular']` reads as 09:30-16:00 `America/New_York` whatever the chart is displayed in. The default is `Asia/Kolkata` on the same fixed-offset arithmetic it always used, so a chart that names no zone labels and computes exactly as before.
+
+### Market replay
+
+```ts
+import { ReplayController } from 'openalgo-charts';
+
+const replay = new ReplayController(chart, { bars, startIndex: 200, barMs: 500 });
+replay.play({ speed: 2 });          // emits replay:frame per bar
+```
+
+Headless: the controller owns the playhead and ships no DOM, so the transport bar is yours to draw from `state()` and the `replay:*` events. Each step hands the series a prefix of the session through the ordinary `setData` path, which is what makes every indicator, level, fill, marker and legend row reconstruct itself as it stood at that bar. `stop()` puts the full history and the exact viewport back.
+
+### Symbol comparison
+
+```ts
+import { addComparison } from 'openalgo-charts';
+
+const bn = addComparison(chart, { symbol: 'BANKNIFTY', bars });
+```
+
+The comparison rides the pane's hidden overlay scale in its own real prices, the pane rebases to percentage (or indexed-to-100), and the overlay's range is mirrored from the primary's, so equal percentage moves land on equal pixels instead of each line filling the pane. Alignment is by timestamp: a comparison print with no primary bar is dropped, a primary bar with no print becomes a gap.
+
+### Linked chart grids
+
+```ts
+import { createLinkGroup } from 'openalgo-charts';
+
+const group = createLinkGroup({ crosshair: true, viewport: true, symbol: false });
+group.add(daily);
+group.add(hourly, { symbol: 'RELIANCE', onSymbol: (s, c) => loadBars(s, c) });
+```
+
+Hover one chart and the same **instant** is marked on the others; pan or zoom one and the others move to the same wall-clock window. Each channel switches on its own, because mirroring the cursor across four timeframes while keeping each zoom is a different thing from slaving every chart's instrument.
+
+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.
+
+Headless like the rest, and the engine has no instrument concept, so symbol sync is a partnership: 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 & context menu
+`chartSettingsSchema(chart)` describes a full settings dialog as tabs of controls, in the same descriptor vocabulary the indicator settings form already uses; `readChartSettings` and `applyChartSettings` are its round trip over flat, JSON-safe keys. Five tabs (Price, Readout, Axes, Appearance, Trading), and a bullish/bearish pair is **one** `colorPair` row carrying its switch and both swatches instead of two stacked rows. Grid, crosshair, scale text, plot margins, status-line fields, the chart timezone, trading colours and the primary series' own style are all real options behind it, so no control in the schema is inert.
+
+`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&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).
@@ -110,25 +181,38 @@ Order, position, and bracket lines with live P&L, one-click and drag-to-modi
 ### Profiles & order flow
 Volume Profile, Market Profile (TPO), Footprint, and cumulative delta.
 
+### Warm-load cache & interval registry
+
+```ts
+import { withBarCache, registerInterval } from 'openalgo-charts';
+
+const feed = withBarCache(new OpenAlgoDataFeed(cfg), { ttlMs: 60_000 });
+registerInterval({ code: '1MO', bucketing: { mode: 'calendar', unit: 'month' } });
+```
+
+`withBarCache` wraps **any** `DataFeed`, so a custom feed warms up too. One entry per `symbol|exchange|interval` holds the widest range fetched so far and a narrower request is sliced out of it, because keying on the range would miss on every pan. **The forming bar is never stored**: a frozen snapshot of a live candle reaching the last-price line, the header LTP and every indicator computed off that close is worse than no cache at all, so coverage ends at the last closed bar and a hit is short by the one bar a live subscription re-supplies. Freshness is two gates, a TTL and "nothing new can have closed", the second measured on the feed's own bar grid rather than UTC midnight. Bounded LRU on entries and on total bars, in-memory by default with an injectable store if you want localStorage or IndexedDB, and `noCache`, `invalidate()`, `clear()` and `stats()` for the rest.
+
+An interval code resolves through a registry whose entry is a **bucketing rule, not a duration**: fixed seconds, a calendar month/quarter/year that opens at local midnight in a named zone, N ticks, or N traded quantity. That is the vocabulary the tick aggregator already used, widened by one case. An unrecognised code now throws `UnknownIntervalError` instead of quietly meaning 60 seconds, so a subscription fails at subscribe time rather than drawing minute bars under someone else's label; `tryResolveInterval` and `isKnownInterval` are the non-throwing probes for validating a picker.
+
 ### 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.
+`chart.getState()` / `chart.restoreState()` capture the viewport, grid, panes, price scales, indicator instances, drawings, and the whole settings block (canvas, status line, trading colours, event filters) 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.
+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, an IANA chart timezone, 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.
+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 | 40 KB | 37.04 KB |
-| Base + trade | 47 KB | 43.62 KB |
-| Indicators tier | 21 KB | 20.09 KB |
-| Draw tier | 14 KB | 11.73 KB |
+| Base engine | 55 KB | 52.88 KB |
+| Base + trade | 62 KB | 59.46 KB |
+| Indicators tier | 27 KB | 24.88 KB |
+| Draw tier | 14 KB | 13.11 KB |
 | Transform tier | 5 KB | 2.66 KB |
-| Profile tier | 11 KB | 10.12 KB |
-| **Everything** | **90 KB** | **88.21 KB** |
+| Profile tier | 11 KB | 10.66 KB |
+| **Everything** | **120 KB** | **110.76 KB** |
 
 ## Documentation
 
@@ -151,7 +235,7 @@ Teach your AI coding assistant this library:
 npx skills add https://github.com/marketcalls/openalgo-charts
 ```
 
-Installs six skills from [`.github/skills/`](./.github/skills) - a reference hub with 18 deep-dive files covering the whole API surface and its foot-guns, plus task skills for scaffolding a chart, adding indicators, building a terminal, writing a plugin, and debugging. Works with Claude Code, Cursor, Codex, Copilot, Gemini CLI and the rest of the `skills` CLI's supported agents.
+Installs six skills from [`.github/skills/`](./.github/skills) - a reference hub with 21 deep-dive files covering the whole API surface and its foot-guns, plus task skills for scaffolding a chart, adding indicators, building a terminal, writing a plugin, and debugging. Works with Claude Code, Cursor, Codex, Copilot, Gemini CLI and the rest of the `skills` CLI's supported agents.
 
 ## Examples
 
@@ -168,7 +252,7 @@ cd examples/yfinance && pip install -r requirements.txt && python server.py
 ```bash
 npm install        # install dev toolchain
 npm run typecheck  # strict TypeScript check
-npm test           # unit tests (vitest) - 1001 across 61 files
+npm test           # unit tests (vitest) - 1719 across 91 files
 npm run build      # Rollup -> dist/ (minified ESM per tier + types)
 npm run size       # size-limit (Brotli) against the budget
 npm run e2e        # Playwright Chromium smoke tests
@@ -177,22 +261,22 @@ 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.
-- **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.
+- **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 & limitations
 
-Version **1.1.0**. All engine build phases are implemented with 1001 unit tests across 61 files.
+Version **1.4.0**. All engine build phases are implemented with 1727 unit tests across 91 files.
 
 Known gaps, stated plainly:
 
-- **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 — `FootprintAggregator` is the live path. See [`ARCHITECTURE.md`](./ARCHITECTURE.md) §6A.
+- **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: `FootprintAggregator` is the live path. See [`ARCHITECTURE.md`](./ARCHITECTURE.md) §6A.
 - **Only `Footprint` is theme-aware among the profile primitives.** `VolumeProfile`, `MarketProfile` and `HorizontalProfile` never read `rc.theme`; their defaults are dark-tuned, so a light theme needs explicit colours. `HorizontalProfile` also hardcodes its POC / value-area line colours and has no `setOptions`.
 - 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 are not implemented. (Hidden overlay scales *are* — add a series with `priceScaleId: ''`.)
+- **A pane has exactly one hidden overlay scale**, so every symbol comparison on a pane shares one baseline. That is right for a single comparison, the common case, but a second one on the same pane is quoted against the first instrument's price; put further instruments on their own pane with `paneIndex` until the overlay scales are keyed.
 - 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.

package/dist/draw/index.d.ts

@@ -254,6 +254,115 @@ declare class DrawingLayer implements IPrimitive {
     hitTest(x: number, y: number, rc: PrimitiveRenderContext): PrimitiveHit | null;
 }
 
+/**
+ * Clipboard transfer for drawings: the layer between the drawing model and the
+ * OS clipboard.
+ *
+ * Two things make this more than `JSON.stringify`:
+ *
+ * 1. **The OS clipboard is shared with everything else on the machine.** A
+ *    paste can arrive from a spreadsheet, another charting product, or a
+ *    hand-edited copy of our own payload. So the payload is written under a
+ *    namespaced key and everything read back is validated field by field before
+ *    it can reach the model. Foreign text is *not ours* and is ignored, never an
+ *    exception the host has to catch on every Ctrl+V.
+ * 2. **Clipboard access is async and permission-gated.** `navigator.clipboard`
+ *    rejects when the document is not focused, the page is not secure, or the
+ *    user denied the permission. Copy must still work inside the tab, so every
+ *    write also lands in a module-level in-memory clipboard which is shared by
+ *    every controller in the page. That is what makes chart-to-chart paste work
+ *    with the permission denied, and it is why the memory store is a singleton
+ *    rather than per-controller state.
+ */
+
+/**
+ * Top-level key of the JSON payload. Namespaced so a paste of arbitrary text,
+ * or of JSON belonging to some other application, is recognisable as not ours
+ * by looking at one property.
+ */
+declare const DRAWING_CLIPBOARD_KEY = "openalgo-charts/drawings";
+/** Payload format version. Bumped only when the on-clipboard shape changes. */
+declare const DRAWING_CLIPBOARD_VERSION = 1;
+/** The async slice of `navigator.clipboard` this module uses. */
+interface ClipboardPort {
+    writeText(text: string): Promise<void>;
+    readText(): Promise<string>;
+}
+/** Test seam: drop whatever the in-memory clipboard is holding. */
+declare function clearMemoryClipboard(): void;
+/** `navigator.clipboard` when the browser exposes it, else null. */
+declare function systemClipboard(): ClipboardPort | null;
+/** Serialise drawings into the namespaced payload written to the clipboard. */
+declare function encodeClipboardPayload(drawings: readonly Drawing[]): string;
+/**
+ * Validate one entry into a drawing with no id. Returns null for anything that
+ * cannot be rendered: an unknown tool would throw inside the controller, and a
+ * NaN anchor produces a drawing that can never be drawn or hit-tested again.
+ */
+declare function sanitizeDrawing(value: unknown): Omit<Drawing, 'id'> | null;
+/**
+ * Parse clipboard text into drawings, or null when the text is not ours or is
+ * not usable. All-or-nothing on purpose: a payload with one corrupt entry is a
+ * corrupt payload, and pasting the other nine silently would be worse than
+ * pasting none.
+ */
+declare function decodeClipboardPayload(text: unknown): Omit<Drawing, 'id'>[] | null;
+interface DrawingClipboardOptions {
+    /** Where to read and write. Defaults to `navigator.clipboard` when present. */
+    port?: ClipboardPort | null;
+    /**
+     * Keep a copy in the shared in-memory clipboard so copy and paste keep
+     * working when the OS clipboard is unavailable or the permission is refused.
+     * Default true. Set false to make a failed system write a failed copy, which
+     * a host that must not silently lose cross-tab transfer may prefer.
+     */
+    fallbackToMemory?: boolean;
+}
+/**
+ * The clipboard as the controller sees it: drawings in, drawings out, no
+ * exceptions escaping. Every failure mode (no clipboard API, refused
+ * permission, foreign text, corrupt payload) reduces to `false` or `null`.
+ */
+declare class DrawingClipboard {
+    private _port;
+    private _fallback;
+    /** Why the last operation did not reach the OS clipboard, if it did not. */
+    private _lastError;
+    constructor(options?: DrawingClipboardOptions);
+    /** Swap the port at runtime (a host granting permission later, or a test). */
+    setPort(port: ClipboardPort | null): void;
+    /**
+     * Turn the in-memory backstop off or on. With it off, a refused system write
+     * is a failed copy, which is what a host wants when a cut that cannot reach
+     * the OS clipboard must not delete the drawing.
+     */
+    setFallbackToMemory(enabled: boolean): void;
+    /**
+     * Why the OS clipboard was not used by the last call, or null when it was.
+     * Set on a successful copy too, when the payload reached memory but not the
+     * system clipboard: that copy works in this tab and will not appear in
+     * another, which is exactly what a host wants to be able to tell the user.
+     */
+    lastError(): string | null;
+    /**
+     * Write drawings out. Resolves true when the payload is retrievable by a
+     * later `read()` (through the system clipboard, or through memory when the
+     * fallback is on), false when it is not, so a caller doing a cut knows
+     * whether it is safe to delete the original.
+     */
+    write(drawings: readonly Drawing[]): Promise<boolean>;
+    /**
+     * Read drawings back, or null when there is nothing of ours to paste. The
+     * system clipboard wins when it holds our payload, so a copy made in another
+     * tab beats a stale in-tab one; memory is consulted when the read fails or
+     * returns something that is not ours. That last case can paste an older copy
+     * after the user has copied unrelated text elsewhere, which is the deliberate
+     * trade: losing the copy whenever a browser refuses the read half of the
+     * permission would be the worse surprise.
+     */
+    read(): Promise<Omit<Drawing, 'id'>[] | null>;
+}
+
 /**
  * Drawing controller — the interaction and persistence layer over
  * `DrawingLayer`. It is **headless**: no DOM, no toolbar. A host sets the
@@ -289,6 +398,21 @@ interface DrawingChartHost {
     drawingState(): unknown;
     setDrawingState(state: unknown): void;
     setPlacementMode?(active: boolean): void;
+    /**
+     * Optional, and used only to offset a paste by a fixed screen distance. Going
+     * through pixels rather than adding a price delta keeps the offset the same
+     * visible nudge on a log scale as on a linear one. A host without them still
+     * gets the time half of the offset.
+     */
+    priceToCoordinate?(price: number, paneIndex?: number): number | null;
+    coordinateToPrice?(y: number, paneIndex?: number): number | null;
+    /**
+     * 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.
+     */
+    panes?(): readonly unknown[];
 }
 interface DrawingControllerOptions {
     /**
@@ -302,10 +426,34 @@ interface DrawingControllerOptions {
     stayInDrawingMode?: boolean;
     /** Undo depth. Default 50. */
     historyLimit?: number;
+    /**
+     * Where copy and paste move text. Defaults to `navigator.clipboard`; pass a
+     * port to route through a host's own transfer, or `null` to stay in the
+     * process-local clipboard entirely.
+     */
+    clipboard?: ClipboardPort | null;
+    /**
+     * Whether a refused or failing clipboard write still lands in the in-process
+     * clipboard. Defaults to true, which is what makes copy and paste work between
+     * two charts on a page where the browser has denied clipboard permission.
+     *
+     * Pass false for a host that would rather a failed copy be a failed copy: with
+     * it off, `cut` leaves the drawing alone when the write does not land, so a
+     * shape is never destroyed for a transfer that did not happen.
+     */
+    clipboardFallbackToMemory?: boolean;
+    /**
+     * How far a pasted copy lands from its original, in bars along time and in
+     * screen pixels down the price axis. A paste that lands exactly on top of the
+     * original reads as nothing having happened. Defaults: 2 bars, 16 px.
+     */
+    pasteOffsetBars?: number;
+    pasteOffsetPixels?: number;
 }
 declare class DrawingController {
     private readonly _chart;
     private _opts;
+    private readonly _clipboard;
     private readonly _layers;
     private _drawings;
     private _tool;
@@ -330,6 +478,8 @@ declare class DrawingController {
     private _setPlacementMode;
     activeTool(): string | null;
     setOptions(patch: DrawingControllerOptions): void;
+    /** The clipboard behind copy / cut / paste, for a host reporting failures. */
+    clipboard(): DrawingClipboard;
     /** Every drawing, in creation order. */
     drawings(): readonly Drawing[];
     get(id: string): Drawing | undefined;
@@ -337,11 +487,52 @@ declare class DrawingController {
     add(drawing: Omit<Drawing, 'id'> & {
         id?: string;
     }): Drawing;
+    /**
+     * Append one drawing without touching history or the layers. Split out so a
+     * paste of several drawings is a single undo step rather than one per shape.
+     */
+    private _insert;
     update(id: string, patch: Partial<Pick<Drawing, 'points' | 'style' | 'locked' | 'visible'>>): boolean;
     remove(id: string): boolean;
     clear(): void;
     select(id: string | null): void;
     selected(): string | null;
+    /**
+     * Put drawings on the clipboard. Defaults to the selection; pass an id or a
+     * list of ids to copy something else. Resolves false when there was nothing
+     * to copy, or when the payload could not be stored anywhere.
+     */
+    copy(target?: string | string[] | null): Promise<boolean>;
+    /**
+     * 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.
+     */
+    cut(target?: string | string[] | null): Promise<boolean>;
+    /**
+     * Paste whatever is on the clipboard into this chart, offset from the
+     * original so the copy is visibly a second object. Each pasted drawing is a
+     * fresh object with a fresh id, never a second reference to the one copied,
+     * so editing the paste cannot alter its source (or the clipboard).
+     *
+     * Anything that is not our payload (foreign text, a truncated or hand-edited
+     * copy, a newer format) pastes nothing and resolves to an empty array: a
+     * paste shortcut must not throw at the host because the user last copied a
+     * spreadsheet cell.
+     */
+    paste(): Promise<Drawing[]>;
+    /** Resolve a copy/cut target to live drawings; defaults to the selection. */
+    private _targets;
+    /** Fold a pane index from another chart onto a pane this one actually has. */
+    private _clampPane;
+    /** Nudge every anchor so a pasted copy is not hidden under its original. */
+    private _offsetPoints;
+    /**
+     * Move a price down the screen by `px`. Done per anchor rather than as one
+     * price delta so the paste is a rigid *screen* translation, which is what the
+     * eye expects and what keeps a shape's proportions on a log scale.
+     */
+    private _offsetPrice;
     undo(): boolean;
     redo(): boolean;
     canUndo(): boolean;
@@ -356,6 +547,12 @@ declare class DrawingController {
      * build a 1:1 box off one click). Identity for tools without the hook.
      */
     private _expand;
+    /**
+     * Bar spacing in seconds, read from the last gap in the data. A one-bar chart
+     * has no gap to read, so fall back to a minute rather than answering zero and
+     * producing zero-width defaults and invisible paste offsets.
+     */
+    private _barSeconds;
     private _isFreehand;
     /**
      * Append one sample to the stroke in progress. Points arriving closer than a
@@ -426,4 +623,4 @@ declare function extendSegment(a: ScreenPoint, b: ScreenPoint, width: number, le
 
 declare const DRAW_TIER: "draw";
 
-export { ARROW, BUILTIN_DRAWING_TOOLS, CROSS_LINE, DRAW_TIER, type DrawContext, type Drawing, DrawingController, type DrawingControllerOptions, DrawingLayer, type DrawingPoint, type DrawingStyle, type DrawingTool, ELLIPSE, EXTENDED_LINE, FIB_EXTENSION, FIB_RETRACEMENT, HORIZONTAL_LINE, HORIZONTAL_RAY, type HitContext, LONG_POSITION, MEASURE, PARALLEL_CHANNEL, PATH, RAY, RECTANGLE, SHORT_POSITION, type ScreenPoint, type ShortcutEvent, TEXT, TREND_LINE, VERTICAL_LINE, distToEllipse, distToLine, distToPolyline, distToRect, distToSegment, drawingShortcuts, extendSegment, getDrawingTool, hasDrawingTool, matchDrawingShortcut, rectOf, registerBuiltinDrawingTools, registerDrawingTool, registeredDrawingTools };
+export { ARROW, BUILTIN_DRAWING_TOOLS, CROSS_LINE, type ClipboardPort, DRAWING_CLIPBOARD_KEY, DRAWING_CLIPBOARD_VERSION, DRAW_TIER, type DrawContext, type Drawing, DrawingClipboard, type DrawingClipboardOptions, DrawingController, type DrawingControllerOptions, DrawingLayer, type DrawingPoint, type DrawingStyle, type DrawingTool, ELLIPSE, EXTENDED_LINE, FIB_EXTENSION, FIB_RETRACEMENT, HORIZONTAL_LINE, HORIZONTAL_RAY, type HitContext, LONG_POSITION, MEASURE, PARALLEL_CHANNEL, PATH, RAY, RECTANGLE, SHORT_POSITION, type ScreenPoint, type ShortcutEvent, TEXT, TREND_LINE, VERTICAL_LINE, clearMemoryClipboard, decodeClipboardPayload, distToEllipse, distToLine, distToPolyline, distToRect, distToSegment, drawingShortcuts, encodeClipboardPayload, extendSegment, getDrawingTool, hasDrawingTool, matchDrawingShortcut, rectOf, registerBuiltinDrawingTools, registerDrawingTool, registeredDrawingTools, sanitizeDrawing, systemClipboard };