From 79a693ea67fc77c21403c737533c5a186d3cb1b2 Mon Sep 17 00:00:00 2001
From: Mark Silverwood <3482679+SlicedSilver@users.noreply.github.com>
Date: Mon, 29 Jul 2024 19:22:40 +0100
Subject: [PATCH 01/12] add pane primitives

---
 .../src/axis-pane-renderer.ts                 |   4 +-
 .../template-primitive/src/axis-pane-view.ts  |   8 +-
 .../template-primitive/src/pane-renderer.ts   |   4 +-
 .../template-primitive/src/pane-view.ts       |   4 +-
 .../plugins/anchored-text/anchored-text.ts    |   8 +-
 .../bands-indicator/bands-indicator.ts        |   8 +-
 .../delta-tooltip/crosshair-line-pane.ts      |  14 +-
 .../delta-tooltip/delta-tooltip-pane.ts       |  14 +-
 .../plugins/delta-tooltip/delta-tooltip.ts    |   4 +-
 .../expiring-price-alerts/primitive.ts        |  10 +-
 .../plugins/expiring-price-alerts/renderer.ts |   4 +-
 .../highlight-bar-crosshair.ts                |  14 +-
 .../image-watermark/image-watermark.ts        |  12 +-
 .../overlay-price-scale.ts                    |  10 +-
 .../partial-price-line/partial-price-line.ts  |  10 +-
 .../rectangle-drawing-tool.ts                 |  16 +-
 .../session-highlighting.ts                   |  12 +-
 .../src/plugins/tooltip/tooltip.ts            |  14 +-
 .../src/plugins/trend-line/trend-line.ts      |   8 +-
 .../plugins/user-price-alerts/pane-view.ts    |  12 +-
 .../user-price-alerts/renderer-base.ts        |   4 +-
 .../user-price-alerts/user-price-alerts.ts    |   6 +-
 .../user-price-lines/user-price-lines.ts      |  14 +-
 .../plugins/vertical-line/vertical-line.ts    |   8 +-
 .../plugins/volume-profile/volume-profile.ts  |   8 +-
 src/api/chart-api.ts                          |   2 +-
 src/api/ichart-api.ts                         |  15 +-
 src/api/ipane-api.ts                          |  16 ++
 src/api/ipane-primitive-api.ts                |  28 +++
 src/api/pane-api.ts                           |  25 ++-
 src/gui/draw-functions.ts                     |  25 ++-
 src/gui/iaxis-view-getters.ts                 |   6 +-
 src/gui/ipane-view-getter.ts                  |   4 +-
 src/gui/pane-hit-test.ts                      |  39 +++--
 src/gui/pane-widget.ts                        |  30 ++--
 src/gui/price-axis-widget.ts                  |  15 +-
 src/gui/time-axis-widget.ts                   |  10 +-
 src/model/chart-model.ts                      |  14 +-
 src/model/idata-source.ts                     |  16 +-
 src/model/ipane-primitive.ts                  | 143 +++++++++++++++
 src/model/iseries-primitive.ts                |  60 +------
 src/model/pane-primitive-wrapper.ts           | 110 ++++++++++++
 src/model/pane.ts                             |  29 +++-
 src/model/series-primitive-wrapper.ts         |  60 ++-----
 src/model/series.ts                           |  11 +-
 .../test-cases/plugins/pane-primitives.js     | 152 ++++++++++++++++
 .../plugins/pane-primitive-hit-test.js        | 163 ++++++++++++++++++
 website/docs/migrations/from-v4-to-v5.md      |  11 ++
 48 files changed, 925 insertions(+), 289 deletions(-)
 create mode 100644 src/api/ipane-primitive-api.ts
 create mode 100644 src/model/ipane-primitive.ts
 create mode 100644 src/model/pane-primitive-wrapper.ts
 create mode 100644 tests/e2e/graphics/test-cases/plugins/pane-primitives.js
 create mode 100644 tests/e2e/interactions/test-cases/plugins/pane-primitive-hit-test.js
 create mode 100644 website/docs/migrations/from-v4-to-v5.md

diff --git a/packages/create-lwc-plugin/template-primitive/src/axis-pane-renderer.ts b/packages/create-lwc-plugin/template-primitive/src/axis-pane-renderer.ts
index 2b984b708c..acbfbfd77b 100644
--- a/packages/create-lwc-plugin/template-primitive/src/axis-pane-renderer.ts
+++ b/packages/create-lwc-plugin/template-primitive/src/axis-pane-renderer.ts
@@ -1,8 +1,8 @@
 import { CanvasRenderingTarget2D } from 'fancy-canvas';
-import { ISeriesPrimitivePaneRenderer } from 'lightweight-charts';
+import { IPrimitivePaneRenderer } from 'lightweight-charts';
 import { positionsBox } from './helpers/dimensions/positions';
 
-export class _CLASSNAME_AxisPaneRenderer implements ISeriesPrimitivePaneRenderer {
+export class _CLASSNAME_AxisPaneRenderer implements IPrimitivePaneRenderer {
 	_p1: number | null;
 	_p2: number | null;
 	_fillColor: string;
diff --git a/packages/create-lwc-plugin/template-primitive/src/axis-pane-view.ts b/packages/create-lwc-plugin/template-primitive/src/axis-pane-view.ts
index 0b2caac371..12ba3d7400 100644
--- a/packages/create-lwc-plugin/template-primitive/src/axis-pane-view.ts
+++ b/packages/create-lwc-plugin/template-primitive/src/axis-pane-view.ts
@@ -1,12 +1,12 @@
 import {
 	Coordinate,
-	ISeriesPrimitivePaneView,
-	SeriesPrimitivePaneViewZOrder,
+	IPrimitivePaneView,
+	PrimitivePaneViewZOrder,
 } from 'lightweight-charts';
 import { _CLASSNAME_AxisPaneRenderer } from './axis-pane-renderer';
 import { _CLASSNAME_DataSource } from './data-source';
 
-abstract class _CLASSNAME_AxisPaneView implements ISeriesPrimitivePaneView {
+abstract class _CLASSNAME_AxisPaneView implements IPrimitivePaneView {
 	_source: _CLASSNAME_DataSource;
 	_p1: number | null = null;
 	_p2: number | null = null;
@@ -31,7 +31,7 @@ abstract class _CLASSNAME_AxisPaneView implements ISeriesPrimitivePaneView {
 			this._vertical
 		);
 	}
-	zOrder(): SeriesPrimitivePaneViewZOrder {
+	zOrder(): PrimitivePaneViewZOrder {
 		return 'bottom';
 	}
 }
diff --git a/packages/create-lwc-plugin/template-primitive/src/pane-renderer.ts b/packages/create-lwc-plugin/template-primitive/src/pane-renderer.ts
index 663cda036c..f9abeb3c74 100644
--- a/packages/create-lwc-plugin/template-primitive/src/pane-renderer.ts
+++ b/packages/create-lwc-plugin/template-primitive/src/pane-renderer.ts
@@ -1,9 +1,9 @@
 import { CanvasRenderingTarget2D } from 'fancy-canvas';
-import { ISeriesPrimitivePaneRenderer } from 'lightweight-charts';
+import { IPrimitivePaneRenderer } from 'lightweight-charts';
 import { ViewPoint } from './pane-view';
 import { positionsBox } from './helpers/dimensions/positions';
 
-export class _CLASSNAME_PaneRenderer implements ISeriesPrimitivePaneRenderer {
+export class _CLASSNAME_PaneRenderer implements IPrimitivePaneRenderer {
 	_p1: ViewPoint;
 	_p2: ViewPoint;
 	_fillColor: string;
diff --git a/packages/create-lwc-plugin/template-primitive/src/pane-view.ts b/packages/create-lwc-plugin/template-primitive/src/pane-view.ts
index 0ddf569262..0fb6d4791b 100644
--- a/packages/create-lwc-plugin/template-primitive/src/pane-view.ts
+++ b/packages/create-lwc-plugin/template-primitive/src/pane-view.ts
@@ -1,4 +1,4 @@
-import { Coordinate, ISeriesPrimitivePaneView } from 'lightweight-charts';
+import { Coordinate, IPrimitivePaneView } from 'lightweight-charts';
 import { _CLASSNAME_PaneRenderer } from './pane-renderer';
 import { _CLASSNAME_DataSource } from './data-source';
 
@@ -7,7 +7,7 @@ export interface ViewPoint {
 	y: Coordinate | null;
 }
 
-export class _CLASSNAME_PaneView implements ISeriesPrimitivePaneView {
+export class _CLASSNAME_PaneView implements IPrimitivePaneView {
 	_source: _CLASSNAME_DataSource;
 	_p1: ViewPoint = { x: null, y: null };
 	_p2: ViewPoint = { x: null, y: null };
diff --git a/plugin-examples/src/plugins/anchored-text/anchored-text.ts b/plugin-examples/src/plugins/anchored-text/anchored-text.ts
index 55d17cdc00..bcab720953 100644
--- a/plugin-examples/src/plugins/anchored-text/anchored-text.ts
+++ b/plugin-examples/src/plugins/anchored-text/anchored-text.ts
@@ -1,8 +1,8 @@
 import { CanvasRenderingTarget2D } from 'fancy-canvas';
 import {
 	ISeriesPrimitive,
-	ISeriesPrimitivePaneRenderer,
-	ISeriesPrimitivePaneView,
+	IPrimitivePaneRenderer,
+	IPrimitivePaneView,
 	SeriesAttachedParameter,
 	Time,
 } from 'lightweight-charts';
@@ -16,7 +16,7 @@ interface AnchoredTextOptions {
 	color: string;
 }
 
-class AnchoredTextRenderer implements ISeriesPrimitivePaneRenderer {
+class AnchoredTextRenderer implements IPrimitivePaneRenderer {
 	_data: AnchoredTextOptions;
 
 	constructor(options: AnchoredTextOptions) {
@@ -61,7 +61,7 @@ class AnchoredTextRenderer implements ISeriesPrimitivePaneRenderer {
 	}
 }
 
-class AnchoredTextPaneView implements ISeriesPrimitivePaneView {
+class AnchoredTextPaneView implements IPrimitivePaneView {
 	private _source: AnchoredText;
 	constructor(source: AnchoredText) {
 		this._source = source;
diff --git a/plugin-examples/src/plugins/bands-indicator/bands-indicator.ts b/plugin-examples/src/plugins/bands-indicator/bands-indicator.ts
index 83bcc35874..e02808588b 100644
--- a/plugin-examples/src/plugins/bands-indicator/bands-indicator.ts
+++ b/plugin-examples/src/plugins/bands-indicator/bands-indicator.ts
@@ -5,8 +5,8 @@ import {
 	Coordinate,
 	DataChangedScope,
 	ISeriesPrimitive,
-	ISeriesPrimitivePaneRenderer,
-	ISeriesPrimitivePaneView,
+	IPrimitivePaneRenderer,
+	IPrimitivePaneView,
 	LineData,
 	Logical,
 	SeriesAttachedParameter,
@@ -25,7 +25,7 @@ interface BandRendererData {
 	lower: Coordinate | number;
 }
 
-class BandsIndicatorPaneRenderer implements ISeriesPrimitivePaneRenderer {
+class BandsIndicatorPaneRenderer implements IPrimitivePaneRenderer {
 	_viewData: BandViewData;
 	constructor(data: BandViewData) {
 		this._viewData = data;
@@ -69,7 +69,7 @@ interface BandViewData {
 	options: Required<BandsIndicatorOptions>;
 }
 
-class BandsIndicatorPaneView implements ISeriesPrimitivePaneView {
+class BandsIndicatorPaneView implements IPrimitivePaneView {
 	_source: BandsIndicator;
 	_data: BandViewData;
 
diff --git a/plugin-examples/src/plugins/delta-tooltip/crosshair-line-pane.ts b/plugin-examples/src/plugins/delta-tooltip/crosshair-line-pane.ts
index 991ad240f1..fda73cbbe9 100644
--- a/plugin-examples/src/plugins/delta-tooltip/crosshair-line-pane.ts
+++ b/plugin-examples/src/plugins/delta-tooltip/crosshair-line-pane.ts
@@ -1,12 +1,12 @@
 import { CanvasRenderingTarget2D } from 'fancy-canvas';
 import {
-	ISeriesPrimitivePaneRenderer,
-	ISeriesPrimitivePaneView,
-	SeriesPrimitivePaneViewZOrder,
+	IPrimitivePaneRenderer,
+	IPrimitivePaneView,
+	PrimitivePaneViewZOrder,
 } from 'lightweight-charts';
 import { positionsLine } from '../../helpers/dimensions/positions';
 
-class TooltipCrosshairLinePaneRenderer implements ISeriesPrimitivePaneRenderer {
+class TooltipCrosshairLinePaneRenderer implements IPrimitivePaneRenderer {
 	_data: TooltipCrosshairLineData[];
 
 	constructor(data: TooltipCrosshairLineData[]) {
@@ -61,7 +61,7 @@ class TooltipCrosshairLinePaneRenderer implements ISeriesPrimitivePaneRenderer {
 	}
 }
 
-export class MultiTouchCrosshairPaneView implements ISeriesPrimitivePaneView {
+export class MultiTouchCrosshairPaneView implements IPrimitivePaneView {
 	_data: TooltipCrosshairLineData[];
 	constructor(data: TooltipCrosshairLineData[]) {
 		this._data = data;
@@ -71,11 +71,11 @@ export class MultiTouchCrosshairPaneView implements ISeriesPrimitivePaneView {
 		this._data = data;
 	}
 
-	renderer(): ISeriesPrimitivePaneRenderer | null {
+	renderer(): IPrimitivePaneRenderer | null {
 		return new TooltipCrosshairLinePaneRenderer(this._data);
 	}
 
-	zOrder(): SeriesPrimitivePaneViewZOrder {
+	zOrder(): PrimitivePaneViewZOrder {
 		return 'top';
 	}
 }
diff --git a/plugin-examples/src/plugins/delta-tooltip/delta-tooltip-pane.ts b/plugin-examples/src/plugins/delta-tooltip/delta-tooltip-pane.ts
index 3c48997d31..ac0d349093 100644
--- a/plugin-examples/src/plugins/delta-tooltip/delta-tooltip-pane.ts
+++ b/plugin-examples/src/plugins/delta-tooltip/delta-tooltip-pane.ts
@@ -1,8 +1,8 @@
 import { CanvasRenderingTarget2D, Size } from 'fancy-canvas';
 import {
-	ISeriesPrimitivePaneRenderer,
-	ISeriesPrimitivePaneView,
-	SeriesPrimitivePaneViewZOrder,
+	IPrimitivePaneRenderer,
+	IPrimitivePaneView,
+	PrimitivePaneViewZOrder,
 } from 'lightweight-charts';
 
 const styles = {
@@ -233,7 +233,7 @@ function calculateDrawingPositions(
 	};
 }
 
-class DeltaTooltipPaneRenderer implements ISeriesPrimitivePaneRenderer {
+class DeltaTooltipPaneRenderer implements IPrimitivePaneRenderer {
 	_data: DeltaTooltipData;
 
 	constructor(data: DeltaTooltipData) {
@@ -347,7 +347,7 @@ class DeltaTooltipPaneRenderer implements ISeriesPrimitivePaneRenderer {
 	}
 }
 
-export class DeltaTooltipPaneView implements ISeriesPrimitivePaneView {
+export class DeltaTooltipPaneView implements IPrimitivePaneView {
 	_data: DeltaTooltipData;
 	constructor(data: Partial<DeltaTooltipData>) {
 		this._data = {
@@ -363,11 +363,11 @@ export class DeltaTooltipPaneView implements ISeriesPrimitivePaneView {
 		};
 	}
 
-	renderer(): ISeriesPrimitivePaneRenderer | null {
+	renderer(): IPrimitivePaneRenderer | null {
 		return new DeltaTooltipPaneRenderer(this._data);
 	}
 
-	zOrder(): SeriesPrimitivePaneViewZOrder {
+	zOrder(): PrimitivePaneViewZOrder {
 		return 'top';
 	}
 }
diff --git a/plugin-examples/src/plugins/delta-tooltip/delta-tooltip.ts b/plugin-examples/src/plugins/delta-tooltip/delta-tooltip.ts
index 677360b0d5..8f6064ebd8 100644
--- a/plugin-examples/src/plugins/delta-tooltip/delta-tooltip.ts
+++ b/plugin-examples/src/plugins/delta-tooltip/delta-tooltip.ts
@@ -8,7 +8,7 @@ import {
 	ColorType,
 	LineStyleOptions,
 	AreaStyleOptions,
-	ISeriesPrimitivePaneView,
+	IPrimitivePaneView,
 	Time,
 } from 'lightweight-charts';
 import { Delegate, ISubscription } from '../../helpers/delegate';
@@ -58,7 +58,7 @@ export class DeltaTooltipPrimitive implements ISeriesPrimitive<Time> {
 	private _options: TooltipPrimitiveOptions;
 	_crosshairPaneView: MultiTouchCrosshairPaneView;
 	_deltaTooltipPaneView: DeltaTooltipPaneView;
-	_paneViews: ISeriesPrimitivePaneView[];
+	_paneViews: IPrimitivePaneView[];
 	_crosshairData: TooltipCrosshairLineData[] = [];
 	_tooltipData: Partial<DeltaTooltipData>;
 	_attachedParams: SeriesAttachedParameter<Time> | undefined;
diff --git a/plugin-examples/src/plugins/expiring-price-alerts/primitive.ts b/plugin-examples/src/plugins/expiring-price-alerts/primitive.ts
index b677059edd..d0f1a70b1c 100644
--- a/plugin-examples/src/plugins/expiring-price-alerts/primitive.ts
+++ b/plugin-examples/src/plugins/expiring-price-alerts/primitive.ts
@@ -1,6 +1,6 @@
 import {
-	ISeriesPrimitivePaneView,
-	ISeriesPrimitivePaneRenderer,
+	IPrimitivePaneView,
+	IPrimitivePaneRenderer,
 	Time,
 	AutoscaleInfo,
 } from 'lightweight-charts';
@@ -9,7 +9,7 @@ import { ExpiringPriceAlerts } from './expiring-price-alerts';
 import { upArrowIcon, tickIcon, cancelIcon, downArrowIcon } from './icons';
 import { ExpiringPriceAlertsPaneRenderer, RendererDataItem } from './renderer';
 
-class ExpiringPriceAlertsPaneView implements ISeriesPrimitivePaneView {
+class ExpiringPriceAlertsPaneView implements IPrimitivePaneView {
 	_source: ExpiringPriceAlerts;
 	_renderer: ExpiringPriceAlertsPaneRenderer;
 
@@ -18,7 +18,7 @@ class ExpiringPriceAlertsPaneView implements ISeriesPrimitivePaneView {
 		this._renderer = new ExpiringPriceAlertsPaneRenderer();
 	}
 
-	renderer(): ISeriesPrimitivePaneRenderer {
+	renderer(): IPrimitivePaneRenderer {
 		return this._renderer;
 	}
 
@@ -96,7 +96,7 @@ export class ExpiringAlertPrimitive extends PluginBase {
 		this._views.forEach(view => view.update());
 	}
 
-	paneViews(): readonly ISeriesPrimitivePaneView[] {
+	paneViews(): readonly IPrimitivePaneView[] {
 		return this._views;
 	}
 
diff --git a/plugin-examples/src/plugins/expiring-price-alerts/renderer.ts b/plugin-examples/src/plugins/expiring-price-alerts/renderer.ts
index 038f0e6c36..f7f4306f8e 100644
--- a/plugin-examples/src/plugins/expiring-price-alerts/renderer.ts
+++ b/plugin-examples/src/plugins/expiring-price-alerts/renderer.ts
@@ -1,5 +1,5 @@
 import { CanvasRenderingTarget2D } from "fancy-canvas";
-import { ISeriesPrimitivePaneRenderer } from 'lightweight-charts';
+import { IPrimitivePaneRenderer } from 'lightweight-charts';
 import { iconDimensions } from "./icons";
 import { positionsLine } from "../../helpers/dimensions/positions";
 
@@ -13,7 +13,7 @@ export interface RendererDataItem {
 	fade: boolean;
 }
 
-export class ExpiringPriceAlertsPaneRenderer implements ISeriesPrimitivePaneRenderer {
+export class ExpiringPriceAlertsPaneRenderer implements IPrimitivePaneRenderer {
 	_data: RendererDataItem[] = [];
 
 	draw(target: CanvasRenderingTarget2D) {
diff --git a/plugin-examples/src/plugins/highlight-bar-crosshair/highlight-bar-crosshair.ts b/plugin-examples/src/plugins/highlight-bar-crosshair/highlight-bar-crosshair.ts
index f4d627f1a4..2a1f4bd51d 100644
--- a/plugin-examples/src/plugins/highlight-bar-crosshair/highlight-bar-crosshair.ts
+++ b/plugin-examples/src/plugins/highlight-bar-crosshair/highlight-bar-crosshair.ts
@@ -1,17 +1,17 @@
 import { CanvasRenderingTarget2D } from 'fancy-canvas';
 import {
 	CrosshairMode,
-	ISeriesPrimitivePaneRenderer,
-	ISeriesPrimitivePaneView,
+	IPrimitivePaneRenderer,
+	IPrimitivePaneView,
 	MouseEventParams,
-	SeriesPrimitivePaneViewZOrder,
+	PrimitivePaneViewZOrder,
 	ISeriesPrimitive,
 	SeriesAttachedParameter,
 	Time,
 } from 'lightweight-charts';
 import { positionsLine } from '../../helpers/dimensions/positions';
 
-class CrosshairHighlightPaneRenderer implements ISeriesPrimitivePaneRenderer {
+class CrosshairHighlightPaneRenderer implements IPrimitivePaneRenderer {
 	_data: CrosshairHighlightData;
 
 	constructor(data: CrosshairHighlightData) {
@@ -38,7 +38,7 @@ class CrosshairHighlightPaneRenderer implements ISeriesPrimitivePaneRenderer {
 	}
 }
 
-class CrosshairHighlightPaneView implements ISeriesPrimitivePaneView {
+class CrosshairHighlightPaneView implements IPrimitivePaneView {
 	_data: CrosshairHighlightData;
 	constructor(data: CrosshairHighlightData) {
 		this._data = data;
@@ -48,11 +48,11 @@ class CrosshairHighlightPaneView implements ISeriesPrimitivePaneView {
 		this._data = data;
 	}
 
-	renderer(): ISeriesPrimitivePaneRenderer | null {
+	renderer(): IPrimitivePaneRenderer | null {
 		return new CrosshairHighlightPaneRenderer(this._data);
 	}
 
-	zOrder(): SeriesPrimitivePaneViewZOrder {
+	zOrder(): PrimitivePaneViewZOrder {
 		return 'bottom';
 	}
 }
diff --git a/plugin-examples/src/plugins/image-watermark/image-watermark.ts b/plugin-examples/src/plugins/image-watermark/image-watermark.ts
index daf4d86c02..ebd6bb2074 100644
--- a/plugin-examples/src/plugins/image-watermark/image-watermark.ts
+++ b/plugin-examples/src/plugins/image-watermark/image-watermark.ts
@@ -2,10 +2,10 @@ import { CanvasRenderingTarget2D } from 'fancy-canvas';
 import {
 	IChartApi,
 	ISeriesPrimitive,
-	ISeriesPrimitivePaneRenderer,
-	ISeriesPrimitivePaneView,
+	IPrimitivePaneRenderer,
+	IPrimitivePaneView,
 	SeriesAttachedParameter,
-	SeriesPrimitivePaneViewZOrder,
+	PrimitivePaneViewZOrder,
 	Time,
 } from 'lightweight-charts';
 
@@ -16,7 +16,7 @@ export interface ImageWatermarkOptions {
 	alpha?: number;
 }
 
-class ImageWatermarkPaneRenderer implements ISeriesPrimitivePaneRenderer {
+class ImageWatermarkPaneRenderer implements IPrimitivePaneRenderer {
 	_source: ImageWatermark;
 	_view: ImageWatermarkPaneView;
 
@@ -50,7 +50,7 @@ interface Placement {
 	width: number;
 }
 
-class ImageWatermarkPaneView implements ISeriesPrimitivePaneView {
+class ImageWatermarkPaneView implements IPrimitivePaneView {
 	_source: ImageWatermark;
 	_placement: Placement | null = null;
 
@@ -58,7 +58,7 @@ class ImageWatermarkPaneView implements ISeriesPrimitivePaneView {
 		this._source = source;
 	}
 
-	zOrder(): SeriesPrimitivePaneViewZOrder {
+	zOrder(): PrimitivePaneViewZOrder {
 		return 'bottom';
 	}
 
diff --git a/plugin-examples/src/plugins/overlay-price-scale/overlay-price-scale.ts b/plugin-examples/src/plugins/overlay-price-scale/overlay-price-scale.ts
index 5ba9d4126f..8a802b2b74 100644
--- a/plugin-examples/src/plugins/overlay-price-scale/overlay-price-scale.ts
+++ b/plugin-examples/src/plugins/overlay-price-scale/overlay-price-scale.ts
@@ -6,8 +6,8 @@ import {
 	IPriceFormatter,
 	ISeriesApi,
 	ISeriesPrimitive,
-	ISeriesPrimitivePaneRenderer,
-	ISeriesPrimitivePaneView,
+	IPrimitivePaneRenderer,
+	IPrimitivePaneView,
 	SeriesAttachedParameter,
 	SeriesType,
 	Time,
@@ -39,7 +39,7 @@ const sideMargin = 10;
 const fontSize = 12;
 const radius = 4;
 
-class OverlayPriceScaleRenderer implements ISeriesPrimitivePaneRenderer {
+class OverlayPriceScaleRenderer implements IPrimitivePaneRenderer {
 	_data: RendererData | null = null;
 	update(data: RendererData) {
 		this._data = data;
@@ -109,13 +109,13 @@ class OverlayPriceScaleRenderer implements ISeriesPrimitivePaneRenderer {
 	}
 }
 
-class OverlayPriceScaleView implements ISeriesPrimitivePaneView {
+class OverlayPriceScaleView implements IPrimitivePaneView {
 	_renderer: OverlayPriceScaleRenderer;
 	constructor() {
 		this._renderer = new OverlayPriceScaleRenderer();
 	}
 
-	renderer(): ISeriesPrimitivePaneRenderer {
+	renderer(): IPrimitivePaneRenderer {
 		return this._renderer;
 	}
 
diff --git a/plugin-examples/src/plugins/partial-price-line/partial-price-line.ts b/plugin-examples/src/plugins/partial-price-line/partial-price-line.ts
index 5176e8be4f..5dc240d718 100644
--- a/plugin-examples/src/plugins/partial-price-line/partial-price-line.ts
+++ b/plugin-examples/src/plugins/partial-price-line/partial-price-line.ts
@@ -4,8 +4,8 @@ import {
 	IChartApi,
 	ISeriesApi,
 	ISeriesPrimitive,
-	ISeriesPrimitivePaneRenderer,
-	ISeriesPrimitivePaneView,
+	IPrimitivePaneRenderer,
+	IPrimitivePaneView,
 	LineData,
 	LineStyleOptions,
 	MismatchDirection,
@@ -16,7 +16,7 @@ import {
 } from 'lightweight-charts';
 import { positionsLine } from '../../helpers/dimensions/positions';
 
-class PartialPriceLineRenderer implements ISeriesPrimitivePaneRenderer {
+class PartialPriceLineRenderer implements IPrimitivePaneRenderer {
 	_price: number | null = null;
 	_x: number | null = null;
 	_color: string = '#000000';
@@ -47,13 +47,13 @@ class PartialPriceLineRenderer implements ISeriesPrimitivePaneRenderer {
 	}
 }
 
-class PartialPriceLineView implements ISeriesPrimitivePaneView {
+class PartialPriceLineView implements IPrimitivePaneView {
 	_renderer: PartialPriceLineRenderer;
 	constructor() {
 		this._renderer = new PartialPriceLineRenderer();
 	}
 
-	renderer(): ISeriesPrimitivePaneRenderer {
+	renderer(): IPrimitivePaneRenderer {
 		return this._renderer;
 	}
 
diff --git a/plugin-examples/src/plugins/rectangle-drawing-tool/rectangle-drawing-tool.ts b/plugin-examples/src/plugins/rectangle-drawing-tool/rectangle-drawing-tool.ts
index 6ac6a990c2..eda804abc0 100644
--- a/plugin-examples/src/plugins/rectangle-drawing-tool/rectangle-drawing-tool.ts
+++ b/plugin-examples/src/plugins/rectangle-drawing-tool/rectangle-drawing-tool.ts
@@ -5,10 +5,10 @@ import {
 	isBusinessDay,
 	ISeriesApi,
 	ISeriesPrimitiveAxisView,
-	ISeriesPrimitivePaneRenderer,
-	ISeriesPrimitivePaneView,
+	IPrimitivePaneRenderer,
+	IPrimitivePaneView,
 	MouseEventParams,
-	SeriesPrimitivePaneViewZOrder,
+	PrimitivePaneViewZOrder,
 	SeriesType,
 	Time,
 } from 'lightweight-charts';
@@ -16,7 +16,7 @@ import { ensureDefined } from '../../helpers/assertions';
 import { PluginBase } from '../plugin-base';
 import { positionsBox } from '../../helpers/dimensions/positions';
 
-class RectanglePaneRenderer implements ISeriesPrimitivePaneRenderer {
+class RectanglePaneRenderer implements IPrimitivePaneRenderer {
 	_p1: ViewPoint;
 	_p2: ViewPoint;
 	_fillColor: string;
@@ -63,7 +63,7 @@ interface ViewPoint {
 	y: Coordinate | null;
 }
 
-class RectanglePaneView implements ISeriesPrimitivePaneView {
+class RectanglePaneView implements IPrimitivePaneView {
 	_source: Rectangle;
 	_p1: ViewPoint = { x: null, y: null };
 	_p2: ViewPoint = { x: null, y: null };
@@ -92,7 +92,7 @@ class RectanglePaneView implements ISeriesPrimitivePaneView {
 	}
 }
 
-class RectangleAxisPaneRenderer implements ISeriesPrimitivePaneRenderer {
+class RectangleAxisPaneRenderer implements IPrimitivePaneRenderer {
 	_p1: number | null;
 	_p2: number | null;
 	_fillColor: string;
@@ -130,7 +130,7 @@ class RectangleAxisPaneRenderer implements ISeriesPrimitivePaneRenderer {
 	}
 }
 
-abstract class RectangleAxisPaneView implements ISeriesPrimitivePaneView {
+abstract class RectangleAxisPaneView implements IPrimitivePaneView {
 	_source: Rectangle;
 	_p1: number | null = null;
 	_p2: number | null = null;
@@ -155,7 +155,7 @@ abstract class RectangleAxisPaneView implements ISeriesPrimitivePaneView {
 			this._vertical
 		);
 	}
-	zOrder(): SeriesPrimitivePaneViewZOrder {
+	zOrder(): PrimitivePaneViewZOrder {
 		return 'bottom';
 	}
 }
diff --git a/plugin-examples/src/plugins/session-highlighting/session-highlighting.ts b/plugin-examples/src/plugins/session-highlighting/session-highlighting.ts
index 273f45a74e..ec96dbaf2b 100644
--- a/plugin-examples/src/plugins/session-highlighting/session-highlighting.ts
+++ b/plugin-examples/src/plugins/session-highlighting/session-highlighting.ts
@@ -3,11 +3,11 @@ import {
 	Coordinate,
 	DataChangedScope,
 	ISeriesPrimitive,
-	ISeriesPrimitivePaneRenderer,
-	ISeriesPrimitivePaneView,
+	IPrimitivePaneRenderer,
+	IPrimitivePaneView,
 	SeriesAttachedParameter,
 	SeriesDataItemTypeMap,
-	SeriesPrimitivePaneViewZOrder,
+	PrimitivePaneViewZOrder,
 	SeriesType,
 	Time,
 } from 'lightweight-charts';
@@ -18,7 +18,7 @@ interface SessionHighlightingRendererData {
 	color: string;
 }
 
-class SessionHighlightingPaneRenderer implements ISeriesPrimitivePaneRenderer {
+class SessionHighlightingPaneRenderer implements IPrimitivePaneRenderer {
 	_viewData: SessionHighlightingViewData;
 	constructor(data: SessionHighlightingViewData) {
 		this._viewData = data;
@@ -51,7 +51,7 @@ interface SessionHighlightingViewData {
 	barWidth: number;
 }
 
-class SessionHighlightingPaneView implements ISeriesPrimitivePaneView {
+class SessionHighlightingPaneView implements IPrimitivePaneView {
 	_source: SessionHighlighting;
 	_data: SessionHighlightingViewData;
 
@@ -83,7 +83,7 @@ class SessionHighlightingPaneView implements ISeriesPrimitivePaneView {
 		return new SessionHighlightingPaneRenderer(this._data);
 	}
 
-	zOrder(): SeriesPrimitivePaneViewZOrder {
+	zOrder(): PrimitivePaneViewZOrder {
 		return 'bottom';
 	}
 }
diff --git a/plugin-examples/src/plugins/tooltip/tooltip.ts b/plugin-examples/src/plugins/tooltip/tooltip.ts
index 04126d9983..14de4a01ce 100644
--- a/plugin-examples/src/plugins/tooltip/tooltip.ts
+++ b/plugin-examples/src/plugins/tooltip/tooltip.ts
@@ -1,10 +1,10 @@
 import { CanvasRenderingTarget2D } from 'fancy-canvas';
 import {
 	CrosshairMode,
-	ISeriesPrimitivePaneRenderer,
-	ISeriesPrimitivePaneView,
+	IPrimitivePaneRenderer,
+	IPrimitivePaneView,
 	MouseEventParams,
-	SeriesPrimitivePaneViewZOrder,
+	PrimitivePaneViewZOrder,
 	ISeriesPrimitive,
 	SeriesAttachedParameter,
 	LineData,
@@ -16,7 +16,7 @@ import { TooltipElement, TooltipOptions } from './tooltip-element';
 import { convertTime, formattedDateAndTime } from '../../helpers/time';
 import { positionsLine } from '../../helpers/dimensions/positions';
 
-class TooltipCrosshairLinePaneRenderer implements ISeriesPrimitivePaneRenderer {
+class TooltipCrosshairLinePaneRenderer implements IPrimitivePaneRenderer {
 	_data: TooltipCrosshairLineData;
 
 	constructor(data: TooltipCrosshairLineData) {
@@ -43,7 +43,7 @@ class TooltipCrosshairLinePaneRenderer implements ISeriesPrimitivePaneRenderer {
 	}
 }
 
-class MultiTouchCrosshairPaneView implements ISeriesPrimitivePaneView {
+class MultiTouchCrosshairPaneView implements IPrimitivePaneView {
 	_data: TooltipCrosshairLineData;
 	constructor(data: TooltipCrosshairLineData) {
 		this._data = data;
@@ -53,11 +53,11 @@ class MultiTouchCrosshairPaneView implements ISeriesPrimitivePaneView {
 		this._data = data;
 	}
 
-	renderer(): ISeriesPrimitivePaneRenderer | null {
+	renderer(): IPrimitivePaneRenderer | null {
 		return new TooltipCrosshairLinePaneRenderer(this._data);
 	}
 
-	zOrder(): SeriesPrimitivePaneViewZOrder {
+	zOrder(): PrimitivePaneViewZOrder {
 		return 'bottom';
 	}
 }
diff --git a/plugin-examples/src/plugins/trend-line/trend-line.ts b/plugin-examples/src/plugins/trend-line/trend-line.ts
index c408ad561b..57c0db4526 100644
--- a/plugin-examples/src/plugins/trend-line/trend-line.ts
+++ b/plugin-examples/src/plugins/trend-line/trend-line.ts
@@ -5,15 +5,15 @@ import {
 	IChartApi,
 	ISeriesApi,
 	ISeriesPrimitive,
-	ISeriesPrimitivePaneRenderer,
-	ISeriesPrimitivePaneView,
+	IPrimitivePaneRenderer,
+	IPrimitivePaneView,
 	Logical,
 	SeriesOptionsMap,
 	SeriesType,
 	Time,
 } from 'lightweight-charts';
 
-class TrendLinePaneRenderer implements ISeriesPrimitivePaneRenderer {
+class TrendLinePaneRenderer implements IPrimitivePaneRenderer {
 	_p1: ViewPoint;
 	_p2: ViewPoint;
 	_text1: string;
@@ -75,7 +75,7 @@ interface ViewPoint {
 	y: Coordinate | null;
 }
 
-class TrendLinePaneView implements ISeriesPrimitivePaneView {
+class TrendLinePaneView implements IPrimitivePaneView {
 	_source: TrendLine;
 	_p1: ViewPoint = { x: null, y: null };
 	_p2: ViewPoint = { x: null, y: null };
diff --git a/plugin-examples/src/plugins/user-price-alerts/pane-view.ts b/plugin-examples/src/plugins/user-price-alerts/pane-view.ts
index 7d3a2db716..1b1bc037f6 100644
--- a/plugin-examples/src/plugins/user-price-alerts/pane-view.ts
+++ b/plugin-examples/src/plugins/user-price-alerts/pane-view.ts
@@ -1,13 +1,13 @@
 import {
-	ISeriesPrimitivePaneRenderer,
-	ISeriesPrimitivePaneView,
-	SeriesPrimitivePaneViewZOrder,
+	IPrimitivePaneRenderer,
+	IPrimitivePaneView,
+	PrimitivePaneViewZOrder,
 } from 'lightweight-charts';
 import { IRendererData } from './irenderer-data';
 import { PaneRenderer } from './pane-renderer';
 import { PriceScalePaneRenderer } from './price-scale-pane-renderer';
 
-export class UserAlertPricePaneView implements ISeriesPrimitivePaneView {
+export class UserAlertPricePaneView implements IPrimitivePaneView {
 	_renderer: PaneRenderer | PriceScalePaneRenderer;
 	constructor(isPriceScale: boolean) {
 		this._renderer = isPriceScale
@@ -15,11 +15,11 @@ export class UserAlertPricePaneView implements ISeriesPrimitivePaneView {
 			: new PaneRenderer();
 	}
 
-	zOrder(): SeriesPrimitivePaneViewZOrder {
+	zOrder(): PrimitivePaneViewZOrder {
 		return 'top';
 	}
 
-	renderer(): ISeriesPrimitivePaneRenderer {
+	renderer(): IPrimitivePaneRenderer {
 		return this._renderer;
 	}
 
diff --git a/plugin-examples/src/plugins/user-price-alerts/renderer-base.ts b/plugin-examples/src/plugins/user-price-alerts/renderer-base.ts
index dbb712da07..2e03c277e4 100644
--- a/plugin-examples/src/plugins/user-price-alerts/renderer-base.ts
+++ b/plugin-examples/src/plugins/user-price-alerts/renderer-base.ts
@@ -1,8 +1,8 @@
 import { CanvasRenderingTarget2D } from 'fancy-canvas';
-import { ISeriesPrimitivePaneRenderer } from 'lightweight-charts';
+import { IPrimitivePaneRenderer } from 'lightweight-charts';
 import { IRendererData } from './irenderer-data';
 
-export abstract class PaneRendererBase implements ISeriesPrimitivePaneRenderer {
+export abstract class PaneRendererBase implements IPrimitivePaneRenderer {
 	_data: IRendererData | null = null;
 	abstract draw(target: CanvasRenderingTarget2D): void;
 	update(data: IRendererData | null) {
diff --git a/plugin-examples/src/plugins/user-price-alerts/user-price-alerts.ts b/plugin-examples/src/plugins/user-price-alerts/user-price-alerts.ts
index eb70a6e023..ab8b48dfd5 100644
--- a/plugin-examples/src/plugins/user-price-alerts/user-price-alerts.ts
+++ b/plugin-examples/src/plugins/user-price-alerts/user-price-alerts.ts
@@ -2,7 +2,7 @@ import {
 	IChartApi,
 	ISeriesApi,
 	ISeriesPrimitive,
-	ISeriesPrimitivePaneView,
+	IPrimitivePaneView,
 	PrimitiveHoveredItem,
 	SeriesAttachedParameter,
 	SeriesType,
@@ -78,11 +78,11 @@ export class UserPriceAlerts
 		this._series = undefined;
 	}
 
-	paneViews(): readonly ISeriesPrimitivePaneView[] {
+	paneViews(): readonly IPrimitivePaneView[] {
 		return this._paneViews;
 	}
 
-	priceAxisPaneViews(): readonly ISeriesPrimitivePaneView[] {
+	priceAxisPaneViews(): readonly IPrimitivePaneView[] {
 		return this._pricePaneViews;
 	}
 
diff --git a/plugin-examples/src/plugins/user-price-lines/user-price-lines.ts b/plugin-examples/src/plugins/user-price-lines/user-price-lines.ts
index 3173c1c214..d8d63ca2ea 100644
--- a/plugin-examples/src/plugins/user-price-lines/user-price-lines.ts
+++ b/plugin-examples/src/plugins/user-price-lines/user-price-lines.ts
@@ -3,11 +3,11 @@ import {
 	CrosshairMode,
 	IChartApi,
 	ISeriesApi,
-	ISeriesPrimitivePaneRenderer,
-	ISeriesPrimitivePaneView,
+	IPrimitivePaneRenderer,
+	IPrimitivePaneView,
 	MouseEventParams,
 	SeriesType,
-	SeriesPrimitivePaneViewZOrder,
+	PrimitivePaneViewZOrder,
 	LineStyle
 } from 'lightweight-charts';
 import { PluginBase } from '../plugin-base';
@@ -45,7 +45,7 @@ interface UserPriceLinesRendererData {
 	hovered: boolean;
 }
 
-class UserPriceLinesPaneRenderer implements ISeriesPrimitivePaneRenderer {
+class UserPriceLinesPaneRenderer implements IPrimitivePaneRenderer {
 	_data: UserPriceLinesRendererData;
 
 	constructor(data: UserPriceLinesRendererData) {
@@ -89,9 +89,9 @@ class UserPriceLinesPaneRenderer implements ISeriesPrimitivePaneRenderer {
 
 class UserPriceLinesPaneView
 	extends UserPriceLineDataBase
-	implements ISeriesPrimitivePaneView
+	implements IPrimitivePaneView
 {
-	renderer(): ISeriesPrimitivePaneRenderer | null {
+	renderer(): IPrimitivePaneRenderer | null {
 		const color = this._data.crosshairColor;
 		return new UserPriceLinesPaneRenderer({
 			visible: this._data.visible,
@@ -104,7 +104,7 @@ class UserPriceLinesPaneView
 		});
 	}
 
-    zOrder(): SeriesPrimitivePaneViewZOrder {
+    zOrder(): PrimitivePaneViewZOrder {
         return 'top';
     }
 }
diff --git a/plugin-examples/src/plugins/vertical-line/vertical-line.ts b/plugin-examples/src/plugins/vertical-line/vertical-line.ts
index be94e71dd8..96fd3e9a12 100644
--- a/plugin-examples/src/plugins/vertical-line/vertical-line.ts
+++ b/plugin-examples/src/plugins/vertical-line/vertical-line.ts
@@ -5,15 +5,15 @@ import {
 	ISeriesApi,
 	ISeriesPrimitive,
 	ISeriesPrimitiveAxisView,
-	ISeriesPrimitivePaneRenderer,
-	ISeriesPrimitivePaneView,
+	IPrimitivePaneRenderer,
+	IPrimitivePaneView,
 	SeriesOptionsMap,
 	SeriesType,
 	Time,
 } from 'lightweight-charts';
 import { positionsLine } from '../../helpers/dimensions/positions';
 
-class VertLinePaneRenderer implements ISeriesPrimitivePaneRenderer {
+class VertLinePaneRenderer implements IPrimitivePaneRenderer {
 	_x: Coordinate | null = null;
 	_options: VertLineOptions;
 	constructor(x: Coordinate | null, options: VertLineOptions) {
@@ -40,7 +40,7 @@ class VertLinePaneRenderer implements ISeriesPrimitivePaneRenderer {
 	}
 }
 
-class VertLinePaneView implements ISeriesPrimitivePaneView {
+class VertLinePaneView implements IPrimitivePaneView {
 	_source: VertLine;
 	_x: Coordinate | null = null;
 	_options: VertLineOptions;
diff --git a/plugin-examples/src/plugins/volume-profile/volume-profile.ts b/plugin-examples/src/plugins/volume-profile/volume-profile.ts
index 44a544f86b..d520d8c123 100644
--- a/plugin-examples/src/plugins/volume-profile/volume-profile.ts
+++ b/plugin-examples/src/plugins/volume-profile/volume-profile.ts
@@ -5,8 +5,8 @@ import {
 	IChartApi,
 	ISeriesApi,
 	ISeriesPrimitive,
-	ISeriesPrimitivePaneRenderer,
-	ISeriesPrimitivePaneView,
+	IPrimitivePaneRenderer,
+	IPrimitivePaneView,
 	Logical,
 	SeriesOptionsMap,
 	SeriesType,
@@ -38,7 +38,7 @@ export interface VolumeProfileData {
 	width: number;
 }
 
-class VolumeProfileRenderer implements ISeriesPrimitivePaneRenderer {
+class VolumeProfileRenderer implements IPrimitivePaneRenderer {
 	_data: VolumeProfileRendererData;
 	constructor(data: VolumeProfileRendererData) {
 		this._data = data;
@@ -91,7 +91,7 @@ class VolumeProfileRenderer implements ISeriesPrimitivePaneRenderer {
 	}
 }
 
-class VolumeProfilePaneView implements ISeriesPrimitivePaneView {
+class VolumeProfilePaneView implements IPrimitivePaneView {
 	_source: VolumeProfile;
 	_x: Coordinate | null = null;
 	_width: number = 6;
diff --git a/src/api/chart-api.ts b/src/api/chart-api.ts
index aaa060b372..276be96638 100644
--- a/src/api/chart-api.ts
+++ b/src/api/chart-api.ts
@@ -429,7 +429,7 @@ export class ChartApi<HorzScaleItem> implements IChartApiBase<HorzScaleItem>, Da
 	private _getPaneApi(pane: Pane): PaneApi<HorzScaleItem> {
 		let result = this._panes.get(pane);
 		if (!result) {
-			result = new PaneApi(this._chartWidget, (series: Series<SeriesType>) => this._mapSeriesToApi(series), pane);
+			result = new PaneApi(this._chartWidget, (series: Series<SeriesType>) => this._mapSeriesToApi(series), pane, this);
 			this._panes.set(pane, result);
 		}
 
diff --git a/src/api/ichart-api.ts b/src/api/ichart-api.ts
index 8b9822df1d..de108cc805 100644
--- a/src/api/ichart-api.ts
+++ b/src/api/ichart-api.ts
@@ -124,7 +124,8 @@ export interface IChartApiBase<HorzScaleItem = Time> {
 		TPartialOptions extends SeriesPartialOptions<TOptions> = SeriesPartialOptions<TOptions>
 	>(
 		customPaneView: ICustomSeriesPaneView<HorzScaleItem, TData, TOptions>,
-		customOptions?: SeriesPartialOptions<TOptions>
+		customOptions?: SeriesPartialOptions<TOptions>,
+		paneIndex?: number
 	): ISeriesApi<'Custom', HorzScaleItem, TData | WhitespaceData<HorzScaleItem>, TOptions, TPartialOptions>;
 
 	/**
@@ -137,7 +138,7 @@ export interface IChartApiBase<HorzScaleItem = Time> {
 	 * const series = chart.addAreaSeries();
 	 * ```
 	 */
-	addAreaSeries(areaOptions?: AreaSeriesPartialOptions): ISeriesApi<'Area', HorzScaleItem>;
+	addAreaSeries(areaOptions?: AreaSeriesPartialOptions, paneIndex?: number): ISeriesApi<'Area', HorzScaleItem>;
 
 	/**
 	 * Creates a baseline series with specified parameters.
@@ -149,7 +150,7 @@ export interface IChartApiBase<HorzScaleItem = Time> {
 	 * const series = chart.addBaselineSeries();
 	 * ```
 	 */
-	addBaselineSeries(baselineOptions?: BaselineSeriesPartialOptions): ISeriesApi<'Baseline', HorzScaleItem>;
+	addBaselineSeries(baselineOptions?: BaselineSeriesPartialOptions, paneIndex?: number): ISeriesApi<'Baseline', HorzScaleItem>;
 
 	/**
 	 * Creates a bar series with specified parameters.
@@ -161,7 +162,7 @@ export interface IChartApiBase<HorzScaleItem = Time> {
 	 * const series = chart.addBarSeries();
 	 * ```
 	 */
-	addBarSeries(barOptions?: BarSeriesPartialOptions): ISeriesApi<'Bar', HorzScaleItem>;
+	addBarSeries(barOptions?: BarSeriesPartialOptions, paneIndex?: number): ISeriesApi<'Bar', HorzScaleItem>;
 
 	/**
 	 * Creates a candlestick series with specified parameters.
@@ -173,7 +174,7 @@ export interface IChartApiBase<HorzScaleItem = Time> {
 	 * const series = chart.addCandlestickSeries();
 	 * ```
 	 */
-	addCandlestickSeries(candlestickOptions?: CandlestickSeriesPartialOptions): ISeriesApi<'Candlestick', HorzScaleItem>;
+	addCandlestickSeries(candlestickOptions?: CandlestickSeriesPartialOptions, paneIndex?: number): ISeriesApi<'Candlestick', HorzScaleItem>;
 
 	/**
 	 * Creates a histogram series with specified parameters.
@@ -185,7 +186,7 @@ export interface IChartApiBase<HorzScaleItem = Time> {
 	 * const series = chart.addHistogramSeries();
 	 * ```
 	 */
-	addHistogramSeries(histogramOptions?: HistogramSeriesPartialOptions): ISeriesApi<'Histogram', HorzScaleItem>;
+	addHistogramSeries(histogramOptions?: HistogramSeriesPartialOptions, paneIndex?: number): ISeriesApi<'Histogram', HorzScaleItem>;
 
 	/**
 	 * Creates a line series with specified parameters.
@@ -197,7 +198,7 @@ export interface IChartApiBase<HorzScaleItem = Time> {
 	 * const series = chart.addLineSeries();
 	 * ```
 	 */
-	addLineSeries(lineOptions?: LineSeriesPartialOptions): ISeriesApi<'Line', HorzScaleItem>;
+	addLineSeries(lineOptions?: LineSeriesPartialOptions, paneIndex?: number): ISeriesApi<'Line', HorzScaleItem>;
 
 	/**
 	 * Removes a series of any type. This is an irreversible operation, you cannot do anything with the series after removing it.
diff --git a/src/api/ipane-api.ts b/src/api/ipane-api.ts
index a0318ffce0..7f43c3d1ed 100644
--- a/src/api/ipane-api.ts
+++ b/src/api/ipane-api.ts
@@ -1,5 +1,6 @@
 import { SeriesType } from '../model/series-options';
 
+import { IPanePrimitive } from './ipane-primitive-api';
 import { ISeriesApi } from './iseries-api';
 
 /**
@@ -47,4 +48,19 @@ export interface IPaneApi<HorzScaleItem> {
 	 * @returns The HTML element of the pane.
 	 */
 	getHTMLElement(): HTMLElement;
+
+	/**
+	 * Attaches additional drawing primitive to the pane
+	 *
+	 * @param primitive - any implementation of IPanePrimitive interface
+	 */
+	attachPrimitive(primitive: IPanePrimitive<HorzScaleItem>): void;
+
+	/**
+	 * Detaches additional drawing primitive from the pane
+	 *
+	 * @param primitive - implementation of IPanePrimitive interface attached before
+	 * Does nothing if specified primitive was not attached
+	 */
+	detachPrimitive(primitive: IPanePrimitive<HorzScaleItem>): void;
 }
diff --git a/src/api/ipane-primitive-api.ts b/src/api/ipane-primitive-api.ts
new file mode 100644
index 0000000000..b0615d560d
--- /dev/null
+++ b/src/api/ipane-primitive-api.ts
@@ -0,0 +1,28 @@
+import { Time } from '../model/horz-scale-behavior-time/types';
+import { IPanePrimitiveBase } from '../model/ipane-primitive';
+
+import { IChartApiBase } from './ichart-api';
+
+/**
+ * Object containing references to the chart and series instances, and a requestUpdate method for triggering
+ * a refresh of the chart.
+ */
+export interface PaneAttachedParameter<
+	HorzScaleItem = Time
+> {
+	/**
+	 * Chart instance.
+	 */
+	chart: IChartApiBase<HorzScaleItem>;
+	/**
+	 * Request an update (redraw the chart)
+	 */
+	requestUpdate: () => void;
+}
+
+/**
+ * Interface for series primitives. It must be implemented to add some external graphics to series.
+ */
+export type IPanePrimitive<HorzScaleItem = Time> = IPanePrimitiveBase<
+    PaneAttachedParameter<HorzScaleItem>
+>;
diff --git a/src/api/pane-api.ts b/src/api/pane-api.ts
index 88ed59585c..cb5cb3d65d 100644
--- a/src/api/pane-api.ts
+++ b/src/api/pane-api.ts
@@ -2,14 +2,18 @@ import { IChartWidgetBase } from '../gui/chart-widget';
 
 import { assert } from '../helpers/assertions';
 
+import { IPanePrimitiveBase } from '../model/ipane-primitive';
 import { Pane } from '../model/pane';
 import { Series } from '../model/series';
 import { SeriesType } from '../model/series-options';
 
+import { IChartApiBase } from './ichart-api';
 import { IPaneApi } from './ipane-api';
+import { IPanePrimitive } from './ipane-primitive-api';
 import { ISeriesApi } from './iseries-api';
 
 export class PaneApi<HorzScaleItem> implements IPaneApi<HorzScaleItem> {
+	protected readonly _chartApi: IChartApiBase<HorzScaleItem>;
 	private _chartWidget: IChartWidgetBase;
 	private _pane: Pane;
 	private readonly _seriesApiGetter: (series: Series<SeriesType>) => ISeriesApi<SeriesType, HorzScaleItem>;
@@ -17,11 +21,13 @@ export class PaneApi<HorzScaleItem> implements IPaneApi<HorzScaleItem> {
 	public constructor(
 		chartWidget: IChartWidgetBase,
 		seriesApiGetter: (series: Series<SeriesType>) => ISeriesApi<SeriesType, HorzScaleItem>,
-		pane: Pane
+		pane: Pane,
+		chartApi: IChartApiBase<HorzScaleItem>
 	) {
 		this._chartWidget = chartWidget;
 		this._pane = pane;
 		this._seriesApiGetter = seriesApiGetter;
+		this._chartApi = chartApi;
 	}
 
 	public getHeight(): number {
@@ -57,4 +63,21 @@ export class PaneApi<HorzScaleItem> implements IPaneApi<HorzScaleItem> {
 	public getHTMLElement(): HTMLElement {
 		return this._chartWidget.paneWidgets()[this.paneIndex()].getElement();
 	}
+
+	public attachPrimitive(primitive: IPanePrimitive<HorzScaleItem>): void {
+		this._pane.attachPrimitive(primitive as IPanePrimitiveBase<unknown>);
+		if (primitive.attached) {
+			primitive.attached({
+				chart: this._chartApi,
+				requestUpdate: () => this._pane.model().fullUpdate(),
+			});
+		}
+	}
+
+	public detachPrimitive(primitive: IPanePrimitive<HorzScaleItem>): void {
+		this._pane.detachPrimitive(primitive as IPanePrimitiveBase<unknown>);
+		if (primitive.detached) {
+			primitive.detached();
+		}
+	}
 }
diff --git a/src/gui/draw-functions.ts b/src/gui/draw-functions.ts
index ae6245d5fd..3888effd57 100644
--- a/src/gui/draw-functions.ts
+++ b/src/gui/draw-functions.ts
@@ -1,9 +1,10 @@
 import { CanvasRenderingTarget2D } from 'fancy-canvas';
 
-import { IDataSource } from '../model/idata-source';
+import { IDataSource, IDataSourcePaneViews } from '../model/idata-source';
 import { Pane } from '../model/pane';
 import { IPaneRenderer } from '../renderers/ipane-renderer';
 
+import { IAxisViewsGetter } from './iaxis-view-getters';
 import { IPaneViewsGetter } from './ipane-view-getter';
 
 export type DrawFunction = (
@@ -35,16 +36,24 @@ export function drawForeground(
 
 type DrawRendererFn = (renderer: IPaneRenderer) => void;
 
-export function drawSourcePaneViews(
-	paneViewsGetter: IPaneViewsGetter,
+export type ViewsGetter<T> = T extends IDataSource
+	? IAxisViewsGetter
+	: IPaneViewsGetter;
+
+export function drawSourceViews<T extends IDataSource | IDataSourcePaneViews>(
+	paneViewsGetter: ViewsGetter<T>,
 	drawRendererFn: DrawRendererFn,
-	source: IDataSource,
+	source: T,
 	pane: Pane
 ): void {
-	const paneViews = paneViewsGetter(source, pane);
-
-	for (const paneView of paneViews) {
-		const renderer = paneView.renderer(pane);
+	const views = (
+		paneViewsGetter as unknown as (
+			source: T,
+			pane: Pane
+		) => ReturnType<ViewsGetter<T>>
+	)(source, pane);
+	for (const view of views) {
+		const renderer = view.renderer(pane);
 		if (renderer !== null) {
 			drawRendererFn(renderer);
 		}
diff --git a/src/gui/iaxis-view-getters.ts b/src/gui/iaxis-view-getters.ts
index 518cae44ce..b61991b190 100644
--- a/src/gui/iaxis-view-getters.ts
+++ b/src/gui/iaxis-view-getters.ts
@@ -1,8 +1,10 @@
 import { IDataSource } from '../model/idata-source';
+import { Pane } from '../model/pane';
 import { IAxisView } from '../views/pane/iaxis-view';
 
-type IAxisViewsGetter = (
-	source: IDataSource
+export type IAxisViewsGetter = (
+	source: IDataSource,
+	pane?: Pane,
 ) => readonly IAxisView[];
 
 export type IPriceAxisViewsGetter = IAxisViewsGetter;
diff --git a/src/gui/ipane-view-getter.ts b/src/gui/ipane-view-getter.ts
index 5c365c56c1..bd042c619d 100644
--- a/src/gui/ipane-view-getter.ts
+++ b/src/gui/ipane-view-getter.ts
@@ -1,10 +1,10 @@
 import {
-	IDataSource,
+	IDataSourcePaneViews,
 } from '../model/idata-source';
 import { Pane } from '../model/pane';
 import { IPaneView } from '../views/pane/ipane-view';
 
 export type IPaneViewsGetter = (
-	source: IDataSource,
+	source: IDataSourcePaneViews,
 	pane: Pane
 ) => readonly IPaneView[];
diff --git a/src/gui/pane-hit-test.ts b/src/gui/pane-hit-test.ts
index b9172e07e1..cbdec042c2 100644
--- a/src/gui/pane-hit-test.ts
+++ b/src/gui/pane-hit-test.ts
@@ -1,15 +1,15 @@
 import { HoveredObject } from '../model/chart-model';
 import { Coordinate } from '../model/coordinate';
-import { IPriceDataSource } from '../model/iprice-data-source';
+import { IDataSource, IPrimitiveHitTestSource } from '../model/idata-source';
+import { PrimitivePaneViewZOrder } from '../model/ipane-primitive';
 import {
 	PrimitiveHoveredItem,
-	SeriesPrimitivePaneViewZOrder,
 } from '../model/iseries-primitive';
 import { Pane } from '../model/pane';
 import { IPaneView } from '../views/pane/ipane-view';
 
 export interface HitTestResult {
-	source: IPriceDataSource;
+	source: IPrimitiveHitTestSource;
 	object?: HoveredObject;
 	view?: IPaneView;
 	cursorStyle?: string;
@@ -22,13 +22,13 @@ export interface HitTestPaneViewResult {
 
 interface BestPrimitiveHit {
 	hit: PrimitiveHoveredItem;
-	source: IPriceDataSource;
+	source: IPrimitiveHitTestSource;
 }
 
 // returns true if item is above reference
 function comparePrimitiveZOrder(
-	item: SeriesPrimitivePaneViewZOrder,
-	reference?: SeriesPrimitivePaneViewZOrder
+	item: PrimitivePaneViewZOrder,
+	reference?: PrimitivePaneViewZOrder
 ): boolean {
 	return (
 		!reference ||
@@ -38,12 +38,12 @@ function comparePrimitiveZOrder(
 }
 
 function findBestPrimitiveHitTest(
-	sources: readonly IPriceDataSource[],
+	sources: readonly IPrimitiveHitTestSource[],
 	x: Coordinate,
 	y: Coordinate
 ): BestPrimitiveHit | null {
 	let bestPrimitiveHit: PrimitiveHoveredItem | undefined;
-	let bestHitSource: IPriceDataSource | undefined;
+	let bestHitSource: IPrimitiveHitTestSource | undefined;
 	for (const source of sources) {
 		const primitiveHitResults = source.primitiveHitTest?.(x, y) ?? [];
 		for (const hitResult of primitiveHitResults) {
@@ -101,12 +101,17 @@ function hitTestPaneView(
 	return null;
 }
 
+function isDataSource(source: IPrimitiveHitTestSource): source is IDataSource {
+	return (source as IDataSource).paneViews !== undefined;
+}
+
+// eslint-disable-next-line complexity
 export function hitTestPane(
 	pane: Pane,
 	x: Coordinate,
 	y: Coordinate
 ): HitTestResult | null {
-	const sources = pane.orderedSources();
+	const sources: IPrimitiveHitTestSource[] = [pane, ...pane.orderedSources()];
 	const bestPrimitiveHit = findBestPrimitiveHitTest(sources, x, y);
 	if (bestPrimitiveHit?.hit.zOrder === 'top') {
         // a primitive hit on the 'top' layer will always beat the built-in hit tests
@@ -119,13 +124,15 @@ export function hitTestPane(
             // therefore it takes precedence here.
 			return convertPrimitiveHitResult(bestPrimitiveHit);
 		}
-		const sourceResult = hitTestPaneView(source.paneViews(pane), x, y, pane);
-		if (sourceResult !== null) {
-			return {
-				source: source,
-				view: sourceResult.view,
-				object: sourceResult.object,
-			};
+		if (isDataSource(source)) {
+			const sourceResult = hitTestPaneView(source.paneViews(pane), x, y, pane);
+			if (sourceResult !== null) {
+				return {
+					source: source,
+					view: sourceResult.view,
+					object: sourceResult.object,
+				};
+			}
 		}
 		if (bestPrimitiveHit && bestPrimitiveHit.source === source && bestPrimitiveHit.hit.zOrder !== 'bottom' && bestPrimitiveHit.hit.isBackground) {
 			return convertPrimitiveHitResult(bestPrimitiveHit);
diff --git a/src/gui/pane-widget.ts b/src/gui/pane-widget.ts
index 87c0493b31..4cb26ea632 100644
--- a/src/gui/pane-widget.ts
+++ b/src/gui/pane-widget.ts
@@ -16,7 +16,7 @@ import { ISubscription } from '../helpers/isubscription';
 
 import { IChartModelBase, TrackingModeExitMode } from '../model/chart-model';
 import { Coordinate } from '../model/coordinate';
-import { IDataSource } from '../model/idata-source';
+import { IDataSourcePaneViews } from '../model/idata-source';
 import { InvalidationLevel } from '../model/invalidate-mask';
 import { KineticAnimation } from '../model/kinetic-animation';
 import { Pane } from '../model/pane';
@@ -29,7 +29,8 @@ import { IPaneView } from '../views/pane/ipane-view';
 import { AttributionLogoWidget } from './attribution-logo-widget';
 import { createBoundCanvas, releaseCanvas } from './canvas-utils';
 import { IChartWidgetBase } from './chart-widget';
-import { drawBackground, drawForeground, DrawFunction, drawSourcePaneViews } from './draw-functions';
+import { drawBackground, drawForeground, DrawFunction, drawSourceViews } from './draw-functions';
+import { IAxisViewsGetter } from './iaxis-view-getters';
 import { IPaneViewsGetter } from './ipane-view-getter';
 import { MouseEventHandler, MouseEventHandlerEventBase, MouseEventHandlerMouseEvent, MouseEventHandlers, MouseEventHandlerTouchEvent, Position, TouchMouseEvent } from './mouse-event-handler';
 import { hitTestPane, HitTestResult } from './pane-hit-test';
@@ -42,16 +43,16 @@ const enum KineticScrollConstants {
 	ScrollMinMove = 15,
 }
 
-function sourceBottomPaneViews(source: IDataSource, pane: Pane): readonly IPaneView[] {
+function sourceBottomPaneViews(source: IDataSourcePaneViews, pane: Pane): readonly IPaneView[] {
 	return source.bottomPaneViews?.(pane) ?? [];
 }
-function sourcePaneViews(source: IDataSource, pane: Pane): readonly IPaneView[] {
+function sourcePaneViews(source: IDataSourcePaneViews, pane: Pane): readonly IPaneView[] {
 	return source.paneViews?.(pane) ?? [];
 }
-function sourceLabelPaneViews(source: IDataSource, pane: Pane): readonly IPaneView[] {
+function sourceLabelPaneViews(source: IDataSourcePaneViews, pane: Pane): readonly IPaneView[] {
 	return source.labelPaneViews?.(pane) ?? [];
 }
-function sourceTopPaneViews(source: IDataSource, pane: Pane): readonly IPaneView[] {
+function sourceTopPaneViews(source: IDataSourcePaneViews, pane: Pane): readonly IPaneView[] {
 	return source.topPaneViews?.(pane) ?? [];
 }
 
@@ -517,7 +518,7 @@ export class PaneWidget implements IDestroyable, MouseEventHandlers {
 		return this._rightPriceAxisWidget;
 	}
 
-	public drawAdditionalSources(target: CanvasRenderingTarget2D, paneViewsGetter: IPaneViewsGetter): void {
+	public drawAdditionalSources(target: CanvasRenderingTarget2D, paneViewsGetter: IPaneViewsGetter | IAxisViewsGetter): void {
 		this._drawSources(target, paneViewsGetter);
 	}
 
@@ -574,14 +575,21 @@ export class PaneWidget implements IDestroyable, MouseEventHandlers {
 		this._drawSourceImpl(target, sourcePaneViews, drawForeground, this._model().crosshairSource());
 	}
 
-	private _drawSources(target: CanvasRenderingTarget2D, paneViewsGetter: IPaneViewsGetter): void {
+	private _drawSources(target: CanvasRenderingTarget2D, paneViewsGetter: IPaneViewsGetter | IAxisViewsGetter): void {
 		const state = ensureNotNull(this._state);
 		const sources = state.orderedSources();
 
+		const panePrimitives = state.primitives();
+		for (const panePrimitive of panePrimitives) {
+			this._drawSourceImpl(target, paneViewsGetter, drawBackground, panePrimitive);
+		}
 		for (const source of sources) {
 			this._drawSourceImpl(target, paneViewsGetter, drawBackground, source);
 		}
 
+		for (const panePrimitive of panePrimitives) {
+			this._drawSourceImpl(target, paneViewsGetter, drawForeground, panePrimitive);
+		}
 		for (const source of sources) {
 			this._drawSourceImpl(target, paneViewsGetter, drawForeground, source);
 		}
@@ -589,9 +597,9 @@ export class PaneWidget implements IDestroyable, MouseEventHandlers {
 
 	private _drawSourceImpl(
 		target: CanvasRenderingTarget2D,
-		paneViewsGetter: IPaneViewsGetter,
+		paneViewsGetter: IPaneViewsGetter | IAxisViewsGetter,
 		drawFn: DrawFunction,
-		source: IDataSource
+		source: IDataSourcePaneViews
 	): void {
 		const state = ensureNotNull(this._state);
 		const hoveredSource = state.model().hoveredSource();
@@ -601,7 +609,7 @@ export class PaneWidget implements IDestroyable, MouseEventHandlers {
 			: undefined;
 
 		const drawRendererFn = (renderer: IPaneRenderer) => drawFn(renderer, target, isHovered, objecId);
-		drawSourcePaneViews(paneViewsGetter, drawRendererFn, source, state);
+		drawSourceViews(paneViewsGetter as IPaneViewsGetter, drawRendererFn, source, state);
 	}
 
 	private _recreatePriceAxisWidgets(): void {
diff --git a/src/gui/price-axis-widget.ts b/src/gui/price-axis-widget.ts
index c99c751f7b..a89c7a282c 100644
--- a/src/gui/price-axis-widget.ts
+++ b/src/gui/price-axis-widget.ts
@@ -16,10 +16,10 @@ import { makeFont } from '../helpers/make-font';
 
 import { ChartOptionsInternalBase } from '../model/chart-model';
 import { Coordinate } from '../model/coordinate';
-import { IDataSource } from '../model/idata-source';
+import { IDataSource, IDataSourcePaneViews } from '../model/idata-source';
 import { InvalidationLevel } from '../model/invalidate-mask';
+import { PrimitivePaneViewZOrder } from '../model/ipane-primitive';
 import { IPriceDataSource } from '../model/iprice-data-source';
-import { SeriesPrimitivePaneViewZOrder } from '../model/iseries-primitive';
 import { LayoutOptions } from '../model/layout-options';
 import { PriceScalePosition } from '../model/pane';
 import { PriceMark, PriceScale } from '../model/price-scale';
@@ -52,11 +52,18 @@ const enum Constants {
 	LabelOffset = 5,
 }
 
+function hasPriceScale(source: IDataSource | IDataSourcePaneViews): source is IDataSource {
+	return (source as IDataSource).priceScale !== undefined;
+}
+
 function buildPriceAxisViewsGetter(
-	zOrder: SeriesPrimitivePaneViewZOrder,
+	zOrder: PrimitivePaneViewZOrder,
 	priceScaleId: PriceAxisWidgetSide
 ): IPriceAxisViewsGetter {
-	return (source: IDataSource): readonly IAxisView[] => {
+	return (source: IDataSource | IDataSourcePaneViews): readonly IAxisView[] => {
+		if (!hasPriceScale(source)) {
+			return [];
+		}
 		const psId = source.priceScale()?.id() ?? '';
 		if (psId !== priceScaleId) {
 			// exclude if source is using a different price scale.
diff --git a/src/gui/time-axis-widget.ts b/src/gui/time-axis-widget.ts
index 9498dab9b4..e0a4494bc2 100644
--- a/src/gui/time-axis-widget.ts
+++ b/src/gui/time-axis-widget.ts
@@ -18,7 +18,7 @@ import { makeFont } from '../helpers/make-font';
 import { IDataSource } from '../model/idata-source';
 import { IHorzScaleBehavior } from '../model/ihorz-scale-behavior';
 import { InvalidationLevel } from '../model/invalidate-mask';
-import { SeriesPrimitivePaneViewZOrder } from '../model/iseries-primitive';
+import { PrimitivePaneViewZOrder } from '../model/ipane-primitive';
 import { LayoutOptions } from '../model/layout-options';
 import { Pane } from '../model/pane';
 import { TextWidthCache } from '../model/text-width-cache';
@@ -28,7 +28,7 @@ import { IAxisView } from '../views/pane/iaxis-view';
 
 import { createBoundCanvas, releaseCanvas } from './canvas-utils';
 import { ChartWidget } from './chart-widget';
-import { drawBackground, drawForeground, drawSourcePaneViews } from './draw-functions';
+import { drawBackground, drawForeground, drawSourceViews } from './draw-functions';
 import { ITimeAxisViewsGetter } from './iaxis-view-getters';
 import { MouseEventHandler, MouseEventHandlers, MouseEventHandlerTouchEvent, TouchMouseEvent } from './mouse-event-handler';
 import { PriceAxisStub, PriceAxisStubParams } from './price-axis-stub';
@@ -43,7 +43,7 @@ const enum CursorType {
 	EwResize,
 }
 
-function buildTimeAxisViewsGetter(zOrder: SeriesPrimitivePaneViewZOrder): ITimeAxisViewsGetter {
+function buildTimeAxisViewsGetter(zOrder: PrimitivePaneViewZOrder): ITimeAxisViewsGetter {
 	return (source: IDataSource): readonly IAxisView[] => source.timePaneViews?.(zOrder) ?? [];
 }
 const sourcePaneViews = buildTimeAxisViewsGetter('normal');
@@ -338,7 +338,7 @@ export class TimeAxisWidget<HorzScaleItem> implements MouseEventHandlers, IDestr
 		const sources = this._chart.model().serieses();
 
 		for (const source of sources) {
-			drawSourcePaneViews(
+			drawSourceViews(
 				axisViewsGetter,
 				(renderer: IPaneRenderer) => drawBackground(renderer, target, false, undefined),
 				source,
@@ -347,7 +347,7 @@ export class TimeAxisWidget<HorzScaleItem> implements MouseEventHandlers, IDestr
 		}
 
 		for (const source of sources) {
-			drawSourcePaneViews(
+			drawSourceViews(
 				axisViewsGetter,
 				(renderer: IPaneRenderer) => drawForeground(renderer, target, false, undefined),
 				source,
diff --git a/src/model/chart-model.ts b/src/model/chart-model.ts
index fb2d7d562d..a15e2fdaf4 100644
--- a/src/model/chart-model.ts
+++ b/src/model/chart-model.ts
@@ -15,6 +15,7 @@ import { Crosshair, CrosshairOptions } from './crosshair';
 import { DefaultPriceScaleId, isDefaultPriceScale } from './default-price-scale';
 import { GridOptions } from './grid';
 import { ICustomSeriesPaneView } from './icustom-series';
+import { IPrimitiveHitTestSource } from './idata-source';
 import { IHorzScaleBehavior, InternalHorzScaleItem } from './ihorz-scale-behavior';
 import { InvalidateMask, InvalidationLevel, ITimeScaleAnimation } from './invalidate-mask';
 import { IPriceDataSource } from './iprice-data-source';
@@ -170,7 +171,7 @@ export interface HoveredObject {
 }
 
 export interface HoveredSource {
-	source: IPriceDataSource;
+	source: IPriceDataSource | IPrimitiveHitTestSource;
 	object?: HoveredObject;
 }
 
@@ -502,7 +503,7 @@ export class ChartModel<HorzScaleItem> implements IDestroyable, IChartModelBase
 		this._invalidate(new InvalidateMask(InvalidationLevel.Cursor));
 	}
 
-	public updateSource(source: IPriceDataSource): void {
+	public updateSource(source: IPriceDataSource | IPrimitiveHitTestSource): void {
 		const inv = this._invalidationMaskForSource(source);
 		this._invalidate(inv);
 	}
@@ -873,8 +874,11 @@ export class ChartModel<HorzScaleItem> implements IDestroyable, IChartModelBase
 		}
 	}
 
-	public paneForSource(source: IPriceDataSource): Pane | null {
-		const pane = this._panes.find((p: Pane) => p.orderedSources().includes(source));
+	public paneForSource(source: IPriceDataSource | IPrimitiveHitTestSource): Pane | null {
+		if (source instanceof Pane) {
+			return source;
+		}
+		const pane = this._panes.find((p: Pane) => p.orderedSources().includes(source as IPriceDataSource));
 		return pane === undefined ? null : pane;
 	}
 
@@ -1089,7 +1093,7 @@ export class ChartModel<HorzScaleItem> implements IDestroyable, IChartModelBase
 		return inv;
 	}
 
-	private _invalidationMaskForSource(source: IPriceDataSource, invalidateType?: InvalidationLevel): InvalidateMask {
+	private _invalidationMaskForSource(source: IPriceDataSource | IPrimitiveHitTestSource, invalidateType?: InvalidationLevel): InvalidateMask {
 		if (invalidateType === undefined) {
 			invalidateType = InvalidationLevel.Light;
 		}
diff --git a/src/model/idata-source.ts b/src/model/idata-source.ts
index 8b34ea0765..ef83d9c24a 100644
--- a/src/model/idata-source.ts
+++ b/src/model/idata-source.ts
@@ -4,10 +4,15 @@ import { IPriceAxisView } from '../views/price-axis/iprice-axis-view';
 import { ITimeAxisView } from '../views/time-axis/itime-axis-view';
 
 import { Coordinate } from './coordinate';
-import { PrimitiveHoveredItem, SeriesPrimitivePaneViewZOrder } from './iseries-primitive';
+import { PrimitivePaneViewZOrder } from './ipane-primitive';
+import { PrimitiveHoveredItem } from './iseries-primitive';
 import { Pane } from './pane';
 import { PriceScale } from './price-scale';
 
+export interface IPrimitiveHitTestSource {
+	primitiveHitTest?(x: Coordinate, y: Coordinate): PrimitiveHoveredItem[];
+}
+
 export interface ZOrdered {
 	zorder(): number | null;
 }
@@ -16,14 +21,13 @@ export interface ZOrdered {
  * - bottom: Pane views that are painted at the bottom (above background color, below grid lines)
  * - top: Pane views that are painted on the most top layer and ABOVE the crosshair
  */
-interface IPluginPaneViews {
+interface IPluginPaneViews extends IPrimitiveHitTestSource {
 	bottomPaneViews?(pane: Pane): readonly IPaneView[];
-	pricePaneViews?(zOrder: SeriesPrimitivePaneViewZOrder): readonly IAxisView[];
-	timePaneViews?(zOrder: SeriesPrimitivePaneViewZOrder): readonly IAxisView[];
-	primitiveHitTest?(x: Coordinate, y: Coordinate): PrimitiveHoveredItem[];
+	pricePaneViews?(zOrder: PrimitivePaneViewZOrder): readonly IAxisView[];
+	timePaneViews?(zOrder: PrimitivePaneViewZOrder): readonly IAxisView[];
 }
 
-interface IDataSourcePaneViews extends IPluginPaneViews {
+export interface IDataSourcePaneViews extends IPluginPaneViews {
 	paneViews(pane: Pane): readonly IPaneView[];
 	labelPaneViews(pane?: Pane): readonly IPaneView[];
 
diff --git a/src/model/ipane-primitive.ts b/src/model/ipane-primitive.ts
new file mode 100644
index 0000000000..9330f9df47
--- /dev/null
+++ b/src/model/ipane-primitive.ts
@@ -0,0 +1,143 @@
+import { CanvasRenderingTarget2D } from 'fancy-canvas';
+
+/**
+ * This interface represents rendering some element on the canvas
+ */
+export interface IPrimitivePaneRenderer {
+	/**
+	 * Method to draw main content of the element
+	 *
+	 * @param target - canvas context to draw on, refer to FancyCanvas library for more details about this class
+	 *
+	 */
+	draw(target: CanvasRenderingTarget2D): void;
+
+	/**
+	 * Optional method to draw the background.
+	 * Some elements could implement this method to draw on the background of the chart.
+	 * Usually this is some kind of watermarks or time areas highlighting.
+	 *
+	 * @param target - canvas context to draw on, refer FancyCanvas library for more details about this class
+	 */
+	drawBackground?(target: CanvasRenderingTarget2D): void;
+}
+
+/**
+ * Defines where in the visual layer stack the renderer should be executed.
+ *
+ * - `bottom`: Draw below everything except the background.
+ * - `normal`: Draw at the same level as the series.
+ * - `top`: Draw above everything (including the crosshair).
+ */
+export type PrimitivePaneViewZOrder = 'bottom' | 'normal' | 'top';
+
+/**
+ * This interface represents the primitive for one of the pane of the chart (main chart area, time scale, price scale).
+ */
+export interface IPrimitivePaneView {
+	/**
+	 * Defines where in the visual layer stack the renderer should be executed. Default is `'normal'`.
+	 *
+	 * @returns the desired position in the visual layer stack. @see {@link SeriesPrimitivePaneViewZOrder}
+	 */
+	zOrder?(): PrimitivePaneViewZOrder;
+	/**
+	 * This method returns a renderer - special object to draw data
+	 *
+	 * @returns an renderer object to be used for drawing, or `null` if we have nothing to draw.
+	 */
+	renderer(): IPrimitivePaneRenderer | null;
+}
+
+/**
+ * This interface represents rendering some element on the canvas
+ */
+export interface IPanePrimitivePaneRenderer extends IPrimitivePaneRenderer {}
+
+/**
+ * This interface represents the primitive for one of the pane of the chart (main chart area, time scale, price scale).
+ */
+export interface IPanePrimitivePaneView {
+	/**
+	 * Defines where in the visual layer stack the renderer should be executed. Default is `'normal'`.
+	 *
+	 * @returns the desired position in the visual layer stack. @see {@link SeriesPrimitivePaneViewZOrder}
+	 */
+	zOrder?(): PrimitivePaneViewZOrder;
+	/**
+	 * This method returns a renderer - special object to draw data
+	 *
+	 * @returns an renderer object to be used for drawing, or `null` if we have nothing to draw.
+	 */
+	renderer(): IPrimitivePaneRenderer | null;
+}
+
+/**
+ * Data representing the currently hovered object from the Hit test.
+ */
+export interface PrimitiveHoveredItem {
+	/**
+	 * CSS cursor style as defined here: [MDN: CSS Cursor](https://developer.mozilla.org/en-US/docs/Web/CSS/cursor) or `undefined`
+	 * if you want the library to use the default cursor style instead.
+	 */
+	cursorStyle?: string;
+	/**
+	 * Hovered objects external ID. Can be used to identify the source item within a mouse subscriber event.
+	 */
+	externalId: string;
+	/**
+	 * The zOrder of the hovered item.
+	 */
+	zOrder: PrimitivePaneViewZOrder;
+	/**
+	 * Set to true if the object is rendered using `drawBackground` instead of `draw`.
+	 */
+	isBackground?: boolean;
+}
+
+/**
+ * Base interface for series primitives. It must be implemented to add some external graphics to series
+ */
+export interface IPanePrimitiveBase<TPaneAttachedParameters = unknown> {
+	/**
+	 * This method is called when viewport has been changed, so primitive have to recalculate / invalidate its data
+	 */
+	updateAllViews?(): void;
+
+	/**
+	 * Returns array of objects representing primitive in the main area of the chart
+	 *
+	 * @returns array of objects; each of then must implement ISeriesPrimitivePaneView interface
+	 *
+	 * For performance reasons, the lightweight library uses internal caches based on references to arrays
+	 * So, this method must return new array if set of views has changed and should try to return the same array if nothing changed
+	 */
+	paneViews?(): readonly IPanePrimitivePaneView[];
+
+	/**
+	 * Attached Lifecycle hook.
+	 *
+	 * @param param - An object containing useful references for the attached primitive to use.
+	 * @returns void
+	 */
+	attached?(param: TPaneAttachedParameters): void;
+	/**
+	 * Detached Lifecycle hook.
+	 *
+	 * @returns void
+	 */
+	detached?(): void;
+
+	/**
+	 * Hit test method which will be called by the library when the cursor is moved.
+	 * Use this to register object ids being hovered for use within the crosshairMoved
+	 * and click events emitted by the chart. Additionally, the hit test result can
+	 * specify a preferred cursor type to display for the main chart pane. This method
+	 * should return the top most hit for this primitive if more than one object is
+	 * being intersected.
+	 *
+	 * @param x - x Coordinate of mouse event
+	 * @param y - y Coordinate of mouse event
+	 */
+	hitTest?(x: number, y: number): PrimitiveHoveredItem | null;
+}
diff --git a/src/model/iseries-primitive.ts b/src/model/iseries-primitive.ts
index 4732e42ede..aa57cd3243 100644
--- a/src/model/iseries-primitive.ts
+++ b/src/model/iseries-primitive.ts
@@ -1,5 +1,4 @@
-import { CanvasRenderingTarget2D } from 'fancy-canvas';
-
+import { IPrimitivePaneView, PrimitivePaneViewZOrder } from './ipane-primitive';
 import { AutoscaleInfo } from './series-options';
 import { Logical } from './time-data';
 
@@ -51,55 +50,6 @@ export interface ISeriesPrimitiveAxisView {
 	tickVisible?(): boolean;
 }
 
-/**
- * This interface represents rendering some element on the canvas
- */
-export interface ISeriesPrimitivePaneRenderer {
-	/**
-	 * Method to draw main content of the element
-	 *
-	 * @param target - canvas context to draw on, refer to FancyCanvas library for more details about this class
-	 *
-	 */
-	draw(target: CanvasRenderingTarget2D): void;
-
-	/**
-	 * Optional method to draw the background.
-	 * Some elements could implement this method to draw on the background of the chart.
-	 * Usually this is some kind of watermarks or time areas highlighting.
-	 *
-	 * @param target - canvas context to draw on, refer FancyCanvas library for more details about this class
-	 */
-	drawBackground?(target: CanvasRenderingTarget2D): void;
-}
-
-/**
- * Defines where in the visual layer stack the renderer should be executed.
- *
- * - `bottom`: Draw below everything except the background.
- * - `normal`: Draw at the same level as the series.
- * - `top`: Draw above everything (including the crosshair).
- */
-export type SeriesPrimitivePaneViewZOrder = 'bottom' | 'normal' | 'top';
-
-/**
- * This interface represents the primitive for one of the pane of the chart (main chart area, time scale, price scale).
- */
-export interface ISeriesPrimitivePaneView {
-	/**
-	 * Defines where in the visual layer stack the renderer should be executed. Default is `'normal'`.
-	 *
-	 * @returns the desired position in the visual layer stack. @see {@link SeriesPrimitivePaneViewZOrder}
-	 */
-	zOrder?(): SeriesPrimitivePaneViewZOrder;
-	/**
-	 * This method returns a renderer - special object to draw data
-	 *
-	 * @returns an renderer object to be used for drawing, or `null` if we have nothing to draw.
-	 */
-	renderer(): ISeriesPrimitivePaneRenderer | null;
-}
-
 /**
  * Data representing the currently hovered object from the Hit test.
  */
@@ -116,7 +66,7 @@ export interface PrimitiveHoveredItem {
 	/**
 	 * The zOrder of the hovered item.
 	 */
-	zOrder: SeriesPrimitivePaneViewZOrder;
+	zOrder: PrimitivePaneViewZOrder;
 	/**
 	 * Set to true if the object is rendered using `drawBackground` instead of `draw`.
 	 */
@@ -160,7 +110,7 @@ export interface ISeriesPrimitiveBase<TSeriesAttachedParameters = unknown> {
 	 * For performance reasons, the lightweight library uses internal caches based on references to arrays
 	 * So, this method must return new array if set of views has changed and should try to return the same array if nothing changed
 	 */
-	paneViews?(): readonly ISeriesPrimitivePaneView[];
+	paneViews?(): readonly IPrimitivePaneView[];
 
 	/**
 	 * Returns array of objects representing primitive in the price axis area of the chart
@@ -170,7 +120,7 @@ export interface ISeriesPrimitiveBase<TSeriesAttachedParameters = unknown> {
 	 * For performance reasons, the lightweight library uses internal caches based on references to arrays
 	 * So, this method must return new array if set of views has changed and should try to return the same array if nothing changed
 	 */
-	priceAxisPaneViews?(): readonly ISeriesPrimitivePaneView[];
+	priceAxisPaneViews?(): readonly IPrimitivePaneView[];
 
 	/**
 	 * Returns array of objects representing primitive in the time axis area of the chart
@@ -180,7 +130,7 @@ export interface ISeriesPrimitiveBase<TSeriesAttachedParameters = unknown> {
 	 * For performance reasons, the lightweight library uses internal caches based on references to arrays
 	 * So, this method must return new array if set of views has changed and should try to return the same array if nothing changed
 	 */
-	timeAxisPaneViews?(): readonly ISeriesPrimitivePaneView[];
+	timeAxisPaneViews?(): readonly IPrimitivePaneView[];
 
 	/**
 	 * Return autoscaleInfo which will be merged with the series base autoscaleInfo. You can use this to expand the autoscale range
diff --git a/src/model/pane-primitive-wrapper.ts b/src/model/pane-primitive-wrapper.ts
new file mode 100644
index 0000000000..4c72310973
--- /dev/null
+++ b/src/model/pane-primitive-wrapper.ts
@@ -0,0 +1,110 @@
+import { CanvasRenderingTarget2D } from 'fancy-canvas';
+
+import { IPaneRenderer } from '../renderers/ipane-renderer';
+import { IPaneView } from '../views/pane/ipane-view';
+
+import { Coordinate } from './coordinate';
+import {
+    IPanePrimitiveBase,
+    IPrimitivePaneRenderer,
+    IPrimitivePaneView,
+    PrimitivePaneViewZOrder,
+} from './ipane-primitive';
+import {
+	ISeriesPrimitiveBase,
+	PrimitiveHoveredItem,
+} from './iseries-primitive';
+
+class PrimitiveRendererWrapper implements IPaneRenderer {
+	private readonly _baseRenderer: IPrimitivePaneRenderer;
+
+	public constructor(baseRenderer: IPrimitivePaneRenderer) {
+		this._baseRenderer = baseRenderer;
+	}
+
+	public draw(target: CanvasRenderingTarget2D, isHovered: boolean, hitTestData?: unknown): void {
+		this._baseRenderer.draw(target);
+	}
+
+	public drawBackground?(target: CanvasRenderingTarget2D, isHovered: boolean, hitTestData?: unknown): void {
+		this._baseRenderer.drawBackground?.(target);
+	}
+}
+
+interface RendererCache<Base, Wrapper> {
+	base: Base;
+	wrapper: Wrapper;
+}
+
+export interface ISeriesPrimitivePaneViewWrapper extends IPaneView {
+	zOrder(): PrimitivePaneViewZOrder;
+}
+
+class PrimitivePaneViewWrapper implements IPaneView {
+	private readonly _paneView: IPrimitivePaneView;
+	private _cache: RendererCache<IPrimitivePaneRenderer, PrimitiveRendererWrapper> | null = null;
+
+	public constructor(paneView: IPrimitivePaneView) {
+		this._paneView = paneView;
+	}
+
+	public renderer(): IPaneRenderer | null {
+		const baseRenderer = this._paneView.renderer();
+		if (baseRenderer === null) {
+			return null;
+		}
+		if (this._cache?.base === baseRenderer) {
+			return this._cache.wrapper;
+		}
+		const wrapper = new PrimitiveRendererWrapper(baseRenderer);
+		this._cache = {
+			base: baseRenderer,
+			wrapper,
+		};
+		return wrapper;
+	}
+
+	public zOrder(): PrimitivePaneViewZOrder {
+		return this._paneView.zOrder?.() ?? 'normal';
+	}
+}
+
+export abstract class PrimitiveWrapper<T extends ISeriesPrimitiveBase<TAttachedParameters> | IPanePrimitiveBase<TAttachedParameters>, TAttachedParameters = unknown> {
+	protected readonly _primitive: T;
+	private _paneViewsCache: RendererCache<readonly IPrimitivePaneView[], readonly PrimitivePaneViewWrapper[]> | null = null;
+
+	public constructor(primitive: T) {
+		this._primitive = primitive;
+	}
+
+	public primitive(): T {
+		return this._primitive;
+	}
+
+	public updateAllViews(): void {
+		this._primitive.updateAllViews?.();
+	}
+
+	public paneViews(): readonly ISeriesPrimitivePaneViewWrapper[] | readonly PrimitivePaneViewWrapper[] {
+		const base = this._primitive.paneViews?.() ?? [];
+		if (this._paneViewsCache?.base === base) {
+			return this._paneViewsCache.wrapper;
+		}
+		const wrapper = base.map((pw: IPrimitivePaneView) => new PrimitivePaneViewWrapper(pw));
+		this._paneViewsCache = {
+			base,
+			wrapper,
+		};
+		return wrapper;
+	}
+
+	public hitTest(x: Coordinate, y: Coordinate): PrimitiveHoveredItem | null {
+		return this._primitive.hitTest?.(x, y) ?? null;
+	}
+}
+
+export class PanePrimitiveWrapper extends PrimitiveWrapper<IPanePrimitiveBase<unknown>> {
+	public labelPaneViews(): readonly IPaneView[] {
+		return [];
+	}
+}
diff --git a/src/model/pane.ts b/src/model/pane.ts
index 28faab316f..e201c15967 100644
--- a/src/model/pane.ts
+++ b/src/model/pane.ts
@@ -5,9 +5,13 @@ import { ISubscription } from '../helpers/isubscription';
 import { clone, DeepPartial } from '../helpers/strict-type-checks';
 
 import { ChartOptionsBase, IChartModelBase, OverlayPriceScaleOptions, VisiblePriceScaleOptions } from './chart-model';
+import { Coordinate } from './coordinate';
 import { DefaultPriceScaleId, isDefaultPriceScale } from './default-price-scale';
 import { Grid } from './grid';
+import { IPrimitiveHitTestSource } from './idata-source';
+import { IPanePrimitiveBase, PrimitiveHoveredItem } from './ipane-primitive';
 import { IPriceDataSource } from './iprice-data-source';
+import { PanePrimitiveWrapper } from './pane-primitive-wrapper';
 import { PriceScale, PriceScaleOptions, PriceScaleState } from './price-scale';
 import { ISeries, Series } from './series';
 import { SeriesType } from './series-options';
@@ -28,7 +32,7 @@ interface MinMaxOrderInfo {
 	maxZOrder: number;
 }
 
-export class Pane implements IDestroyable {
+export class Pane implements IDestroyable, IPrimitiveHitTestSource {
 	private readonly _timeScale: ITimeScale;
 	private readonly _model: IChartModelBase;
 	private readonly _grid: Grid;
@@ -46,6 +50,8 @@ export class Pane implements IDestroyable {
 	private _leftPriceScale: PriceScale;
 	private _rightPriceScale: PriceScale;
 
+	private _primitives: PanePrimitiveWrapper[] = [];
+
 	public constructor(timeScale: ITimeScale, model: IChartModelBase) {
 		this._timeScale = timeScale;
 		this._model = model;
@@ -354,6 +360,27 @@ export class Pane implements IDestroyable {
 		return this._grid;
 	}
 
+	public attachPrimitive(primitive: IPanePrimitiveBase): void {
+		this._primitives.push(new PanePrimitiveWrapper(primitive));
+	}
+
+	public detachPrimitive(source: IPanePrimitiveBase): void {
+		this._primitives = this._primitives.filter((wrapper: PanePrimitiveWrapper) => wrapper.primitive() !== source);
+	}
+
+	public primitives(): PanePrimitiveWrapper[] {
+		return this._primitives;
+	}
+
+	public primitiveHitTest(x: Coordinate, y: Coordinate): PrimitiveHoveredItem[] {
+		return this._primitives
+			.map((primitive: PanePrimitiveWrapper) => primitive.hitTest(x, y))
+			.filter(
+				(result: PrimitiveHoveredItem | null): result is PrimitiveHoveredItem =>
+					result !== null
+			);
+	}
+
 	private _recalculatePriceScaleImpl(priceScale: PriceScale): void {
 		// TODO: can use this checks
 		const sourceForAutoScale = priceScale.sourcesForAutoScale();
diff --git a/src/model/series-primitive-wrapper.ts b/src/model/series-primitive-wrapper.ts
index d8ad2362d2..e224669224 100644
--- a/src/model/series-primitive-wrapper.ts
+++ b/src/model/series-primitive-wrapper.ts
@@ -8,15 +8,12 @@ import { IPriceAxisView } from '../views/price-axis/iprice-axis-view';
 import { PriceAxisView } from '../views/price-axis/price-axis-view';
 import { ITimeAxisView } from '../views/time-axis/itime-axis-view';
 
-import { Coordinate } from './coordinate';
+import { IPrimitivePaneRenderer, IPrimitivePaneView, PrimitivePaneViewZOrder } from './ipane-primitive';
 import {
 	ISeriesPrimitiveAxisView,
 	ISeriesPrimitiveBase,
-	ISeriesPrimitivePaneRenderer,
-	ISeriesPrimitivePaneView,
-	PrimitiveHoveredItem,
-	SeriesPrimitivePaneViewZOrder,
 } from './iseries-primitive';
+import { PrimitiveWrapper } from './pane-primitive-wrapper';
 import { PriceScale } from './price-scale';
 import { Series } from './series';
 import { AutoscaleInfo, SeriesType } from './series-options';
@@ -24,9 +21,9 @@ import { Logical, TimePointIndex } from './time-data';
 import { ITimeScale } from './time-scale';
 
 class SeriesPrimitiveRendererWrapper implements IPaneRenderer {
-	private readonly _baseRenderer: ISeriesPrimitivePaneRenderer;
+	private readonly _baseRenderer: IPrimitivePaneRenderer;
 
-	public constructor(baseRenderer: ISeriesPrimitivePaneRenderer) {
+	public constructor(baseRenderer: IPrimitivePaneRenderer) {
 		this._baseRenderer = baseRenderer;
 	}
 
@@ -45,14 +42,14 @@ interface RendererCache<Base, Wrapper> {
 }
 
 export interface ISeriesPrimitivePaneViewWrapper extends IPaneView {
-	zOrder(): SeriesPrimitivePaneViewZOrder;
+	zOrder(): PrimitivePaneViewZOrder;
 }
 
 class SeriesPrimitivePaneViewWrapper implements IPaneView {
-	private readonly _paneView: ISeriesPrimitivePaneView;
-	private _cache: RendererCache<ISeriesPrimitivePaneRenderer, SeriesPrimitiveRendererWrapper> | null = null;
+	private readonly _paneView: IPrimitivePaneView;
+	private _cache: RendererCache<IPrimitivePaneRenderer, SeriesPrimitiveRendererWrapper> | null = null;
 
-	public constructor(paneView: ISeriesPrimitivePaneView) {
+	public constructor(paneView: IPrimitivePaneView) {
 		this._paneView = paneView;
 	}
 
@@ -72,7 +69,7 @@ class SeriesPrimitivePaneViewWrapper implements IPaneView {
 		return wrapper;
 	}
 
-	public zOrder(): SeriesPrimitivePaneViewZOrder {
+	public zOrder(): PrimitivePaneViewZOrder {
 		return this._paneView.zOrder?.() ?? 'normal';
 	}
 }
@@ -150,41 +147,18 @@ class SeriesPrimitivePriceAxisViewWrapper extends PriceAxisView {
 	}
 }
 
-export class SeriesPrimitiveWrapper<TSeriesAttachedParameters = unknown> {
-	private readonly _primitive: ISeriesPrimitiveBase<TSeriesAttachedParameters>;
+export class SeriesPrimitiveWrapper<TSeriesAttachedParameters = unknown> extends PrimitiveWrapper<ISeriesPrimitiveBase<TSeriesAttachedParameters>> {
 	private readonly _series: Series<SeriesType>;
-	private _paneViewsCache: RendererCache<readonly ISeriesPrimitivePaneView[], readonly SeriesPrimitivePaneViewWrapper[]> | null = null;
 	private _timeAxisViewsCache: RendererCache<readonly ISeriesPrimitiveAxisView[], readonly SeriesPrimitiveTimeAxisViewWrapper[]> | null = null;
 	private _priceAxisViewsCache: RendererCache<readonly ISeriesPrimitiveAxisView[], readonly SeriesPrimitivePriceAxisViewWrapper[]> | null = null;
-	private _priceAxisPaneViewsCache: RendererCache<readonly ISeriesPrimitivePaneView[], readonly SeriesPrimitivePaneViewWrapper[]> | null = null;
-	private _timeAxisPaneViewsCache: RendererCache<readonly ISeriesPrimitivePaneView[], readonly SeriesPrimitivePaneViewWrapper[]> | null = null;
+	private _priceAxisPaneViewsCache: RendererCache<readonly IPrimitivePaneView[], readonly SeriesPrimitivePaneViewWrapper[]> | null = null;
+	private _timeAxisPaneViewsCache: RendererCache<readonly IPrimitivePaneView[], readonly SeriesPrimitivePaneViewWrapper[]> | null = null;
 
 	public constructor(primitive: ISeriesPrimitiveBase<TSeriesAttachedParameters>, series: Series<SeriesType>) {
-		this._primitive = primitive;
+		super(primitive);
 		this._series = series;
 	}
 
-	public primitive(): ISeriesPrimitiveBase<TSeriesAttachedParameters> {
-		return this._primitive;
-	}
-
-	public updateAllViews(): void {
-		this._primitive.updateAllViews?.();
-	}
-
-	public paneViews(): readonly ISeriesPrimitivePaneViewWrapper[] {
-		const base = this._primitive.paneViews?.() ?? [];
-		if (this._paneViewsCache?.base === base) {
-			return this._paneViewsCache.wrapper;
-		}
-		const wrapper = base.map((pw: ISeriesPrimitivePaneView) => new SeriesPrimitivePaneViewWrapper(pw));
-		this._paneViewsCache = {
-			base,
-			wrapper,
-		};
-		return wrapper;
-	}
-
 	public timeAxisViews(): readonly ITimeAxisView[] {
 		const base = this._primitive.timeAxisViews?.() ?? [];
 		if (this._timeAxisViewsCache?.base === base) {
@@ -218,7 +192,7 @@ export class SeriesPrimitiveWrapper<TSeriesAttachedParameters = unknown> {
 		if (this._priceAxisPaneViewsCache?.base === base) {
 			return this._priceAxisPaneViewsCache.wrapper;
 		}
-		const wrapper = base.map((pw: ISeriesPrimitivePaneView) => new SeriesPrimitivePaneViewWrapper(pw));
+		const wrapper = base.map((pw: IPrimitivePaneView) => new SeriesPrimitivePaneViewWrapper(pw));
 		this._priceAxisPaneViewsCache = {
 			base,
 			wrapper,
@@ -231,7 +205,7 @@ export class SeriesPrimitiveWrapper<TSeriesAttachedParameters = unknown> {
 		if (this._timeAxisPaneViewsCache?.base === base) {
 			return this._timeAxisPaneViewsCache.wrapper;
 		}
-		const wrapper = base.map((pw: ISeriesPrimitivePaneView) => new SeriesPrimitivePaneViewWrapper(pw));
+		const wrapper = base.map((pw: IPrimitivePaneView) => new SeriesPrimitivePaneViewWrapper(pw));
 		this._timeAxisPaneViewsCache = {
 			base,
 			wrapper,
@@ -250,8 +224,4 @@ export class SeriesPrimitiveWrapper<TSeriesAttachedParameters = unknown> {
 			) ?? null
 		);
 	}
-
-	public hitTest(x: Coordinate, y: Coordinate): PrimitiveHoveredItem | null {
-		return this._primitive.hitTest?.(x, y) ?? null;
-	}
 }
diff --git a/src/model/series.ts b/src/model/series.ts
index 51eca43058..af1aa1780e 100644
--- a/src/model/series.ts
+++ b/src/model/series.ts
@@ -33,8 +33,9 @@ import { CustomPriceLine } from './custom-price-line';
 import { isDefaultPriceScale } from './default-price-scale';
 import { CustomData, CustomSeriesWhitespaceData, ICustomSeriesPaneView, WhitespaceCheck } from './icustom-series';
 import { InternalHorzScaleItem } from './ihorz-scale-behavior';
+import { PrimitivePaneViewZOrder } from './ipane-primitive';
 import { FirstValue, IPriceDataSource } from './iprice-data-source';
-import { ISeriesPrimitiveBase, PrimitiveHoveredItem, SeriesPrimitivePaneViewZOrder } from './iseries-primitive';
+import { ISeriesPrimitiveBase, PrimitiveHoveredItem } from './iseries-primitive';
 import { Pane } from './pane';
 import { PlotRowValueIndex } from './plot-data';
 import { MismatchDirection } from './plot-list';
@@ -61,7 +62,7 @@ type PrimitivePaneViewExtractor = (wrapper: SeriesPrimitiveWrapper) => readonly
 function extractPrimitivePaneViews(
 	primitives: SeriesPrimitiveWrapper[],
 	extractor: PrimitivePaneViewExtractor,
-	zOrder: SeriesPrimitivePaneViewZOrder,
+	zOrder: PrimitivePaneViewZOrder,
 	destination: IPaneView[]
 ): void {
 	primitives.forEach((wrapper: SeriesPrimitiveWrapper) => {
@@ -440,11 +441,11 @@ export class Series<T extends SeriesType> extends PriceDataSource implements IDe
 		return this._extractPaneViews(primitivePaneViewsExtractor, 'bottom');
 	}
 
-	public pricePaneViews(zOrder: SeriesPrimitivePaneViewZOrder): readonly IPaneView[] {
+	public pricePaneViews(zOrder: PrimitivePaneViewZOrder): readonly IPaneView[] {
 		return this._extractPaneViews(primitivePricePaneViewsExtractor, zOrder);
 	}
 
-	public timePaneViews(zOrder: SeriesPrimitivePaneViewZOrder): readonly IPaneView[] {
+	public timePaneViews(zOrder: PrimitivePaneViewZOrder): readonly IPaneView[] {
 		return this._extractPaneViews(primitiveTimePaneViewsExtractor, zOrder);
 	}
 
@@ -783,7 +784,7 @@ export class Series<T extends SeriesType> extends PriceDataSource implements IDe
 		}
 	}
 
-	private _extractPaneViews(extractor: PrimitivePaneViewExtractor, zOrder: SeriesPrimitivePaneViewZOrder): readonly IPaneView[] {
+	private _extractPaneViews(extractor: PrimitivePaneViewExtractor, zOrder: PrimitivePaneViewZOrder): readonly IPaneView[] {
 		const res: IPaneView[] = [];
 		extractPrimitivePaneViews(this._primitives, extractor, zOrder, res);
 		return res;
diff --git a/tests/e2e/graphics/test-cases/plugins/pane-primitives.js b/tests/e2e/graphics/test-cases/plugins/pane-primitives.js
new file mode 100644
index 0000000000..044bbea3bf
--- /dev/null
+++ b/tests/e2e/graphics/test-cases/plugins/pane-primitives.js
@@ -0,0 +1,152 @@
+function generateData() {
+	const res = [];
+	const time = new Date(Date.UTC(2018, 0, 1, 0, 0, 0, 0));
+	for (let i = 0; i < 500; ++i) {
+		res.push({
+			time: time.getTime() / 1000,
+			value: i,
+		});
+
+		time.setUTCDate(time.getUTCDate() + 1);
+	}
+	return res;
+}
+
+class AnchoredTextRenderer {
+	constructor(options) {
+		this._data = options;
+	}
+
+	draw(target) {
+		target.useMediaCoordinateSpace(scope => {
+			const ctx = scope.context;
+			ctx.font = this._data.font;
+			const textWidth = ctx.measureText(this._data.text).width;
+			const horzMargin = 20;
+			let x = horzMargin;
+			const width = scope.mediaSize.width;
+			const height = scope.mediaSize.height;
+			switch (this._data.horzAlign) {
+				case 'right': {
+					x = width - horzMargin - textWidth;
+					break;
+				}
+				case 'middle': {
+					x = width / 2 - textWidth / 2;
+					break;
+				}
+			}
+			const vertMargin = 10;
+			const lineHeight = this._data.lineHeight;
+			let y = vertMargin + lineHeight;
+			switch (this._data.vertAlign) {
+				case 'middle': {
+					y = height / 2 + lineHeight / 2;
+					break;
+				}
+				case 'bottom': {
+					y = height - vertMargin;
+					break;
+				}
+			}
+			ctx.fillStyle = this._data.color;
+			ctx.fillText(this._data.text, x, y);
+		});
+	}
+}
+
+class AnchoredTextPaneView {
+	constructor(source) {
+		this._source = source;
+	}
+	update() {}
+	renderer() {
+		return new AnchoredTextRenderer(this._source._data);
+	}
+}
+
+class AnchoredText {
+	constructor(options) {
+		this._data = options;
+		this._paneViews = [new AnchoredTextPaneView(this)];
+	}
+
+	updateAllViews() {
+		this._paneViews.forEach(pw => pw.update());
+	}
+
+	paneViews() {
+		return this._paneViews;
+	}
+
+	requestUpdate() {}
+	attached({ requestUpdate }) {
+		this.requestUpdate = requestUpdate;
+	}
+
+	detached() {
+		this.requestUpdate = undefined;
+	}
+
+	applyOptions(options) {
+		this._data = { ...this._data, ...options };
+		if (this.requestUpdate) {
+			this.requestUpdate();
+		}
+	}
+}
+
+function runTestCase(container) {
+	const chart = (window.chart = LightweightCharts.createChart(container, {
+		layout: {
+			attributionLogo: true,
+			background: {
+				type: 'solid',
+				color: 'rgb(50,100,150)',
+			},
+			textColor: 'rgb(255,200,100)',
+		},
+	}));
+
+	const mainSeries = chart.addLineSeries(
+		{
+			priceFormat: {
+				minMove: 1,
+				precision: 0,
+			},
+		},
+		0
+	);
+	mainSeries.setData(generateData());
+
+	const secondSeries = chart.addLineSeries(
+		{
+			priceFormat: {
+				minMove: 1,
+				precision: 0,
+			},
+		},
+		1
+	);
+	secondSeries.setData(generateData());
+
+	const anchoredText = new AnchoredText({
+		vertAlign: 'middle',
+		horzAlign: 'middle',
+		text: 'Pane 1',
+		lineHeight: 54,
+		font: 'italic 54px Arial',
+		color: 'red',
+	});
+	chart.panes()[0].attachPrimitive(anchoredText);
+
+	const anchoredText2 = new AnchoredText({
+		vertAlign: 'middle',
+		horzAlign: 'middle',
+		text: 'Pane 2',
+		lineHeight: 26,
+		font: 'bold 26px Arial',
+		color: 'blue',
+	});
+	chart.panes()[1].attachPrimitive(anchoredText2);
+}
diff --git a/tests/e2e/interactions/test-cases/plugins/pane-primitive-hit-test.js b/tests/e2e/interactions/test-cases/plugins/pane-primitive-hit-test.js
new file mode 100644
index 0000000000..2accbd633e
--- /dev/null
+++ b/tests/e2e/interactions/test-cases/plugins/pane-primitive-hit-test.js
@@ -0,0 +1,163 @@
+function generateData() {
+	const res = [];
+	const time = new Date(Date.UTC(2018, 0, 1, 0, 0, 0, 0));
+	for (let i = 0; i < 500; ++i) {
+		res.push({
+			time: time.getTime() / 1000,
+			value: i,
+		});
+
+		time.setUTCDate(time.getUTCDate() + 1);
+	}
+	return res;
+}
+
+const testLayer = 'normal';
+const drawBackground = true; // whether the renderer is using drawBackground or draw
+
+class HitTestRenderer {
+	_draw(target) {
+		target.useMediaCoordinateSpace(scope => {
+			const ctx = scope.context;
+			ctx.save();
+			const width = scope.mediaSize.width;
+			const height = scope.mediaSize.height;
+			const boxWidth = Math.round(width / 2);
+			const boxHeight = Math.round(height / 2);
+			const x = Math.round((width - boxWidth) / 2);
+			const y = Math.round((height - boxHeight) / 2);
+
+			ctx.beginPath();
+			ctx.fillStyle = 'rgba(0,0,0,0.5)';
+			ctx.fillRect(x, y, boxWidth, boxHeight);
+			this._hitBox = {
+				x,
+				y,
+				height: boxHeight,
+				width: boxWidth,
+			};
+			ctx.restore();
+		});
+	}
+
+	draw(target) {
+		if (!drawBackground) {this._draw(target);}
+	}
+
+	drawBackground(target) {
+		if (drawBackground) {this._draw(target);}
+	}
+
+	hitTest(x, y) {
+		if (
+			!this._hitBox ||
+						x < this._hitBox.x ||
+						y < this._hitBox.y ||
+						x > this._hitBox.x + this._hitBox.width ||
+						y > this._hitBox.y + this._hitBox.height
+		) {return null;}
+		return {
+			cursorStyle: 'pointer',
+			externalId: 'PLUGIN',
+		};
+	}
+}
+
+class HitTestPaneView {
+	constructor() {
+		this._renderer = new HitTestRenderer();
+	}
+
+	update() {}
+
+	renderer() {
+		return this._renderer;
+	}
+
+	hitTest(x, y) {
+		const result = this._renderer.hitTest(x, y);
+		if (result) {
+			return {
+				...result,
+				zOrder: this.zOrder(),
+				isBackground: drawBackground,
+			};
+		}
+		return null;
+	}
+
+	zOrder() {
+		return testLayer;
+	}
+}
+
+class HitTest {
+	constructor() {
+		this._paneViews = [new HitTestPaneView()];
+	}
+
+	updateAllViews() {
+		this._paneViews.forEach(pw => pw.update());
+	}
+
+	paneViews() {
+		return this._paneViews;
+	}
+
+	hitTest(x, y) {
+		return this._paneViews[0].hitTest(x, y);
+	}
+}
+
+function initialInteractionsToPerform() {
+	return [{ action: 'click' }];
+}
+
+function finalInteractionsToPerform() {
+	return [{ action: 'click' }];
+}
+
+let chart;
+let pass = false;
+
+function beforeInteractions(container) {
+	chart = LightweightCharts.createChart(container);
+
+	const mainSeries = chart.addLineSeries();
+
+	mainSeries.setData(generateData());
+	const firstPane = chart.panes()[0];
+	firstPane.attachPrimitive(new HitTest());
+
+	chart.subscribeClick(mouseParams => {
+		if (!mouseParams) {
+			return;
+		}
+		if (mouseParams.hoveredObjectId === 'TEST') {
+			pass = true;
+			return;
+		}
+	});
+
+	return new Promise(resolve => {
+		requestAnimationFrame(() => {
+			resolve();
+		});
+	});
+}
+
+function afterInitialInteractions() {
+	return new Promise(resolve => {
+		requestAnimationFrame(() => {
+			setTimeout(resolve, 500); // large enough so the browser doesn't think it is a double click
+		});
+	});
+}
+
+function afterFinalInteractions() {
+	if (!pass) {
+		throw new Error("Expected hoveredObjectId to be equal to 'TEST'.");
+	}
+
+	return Promise.resolve();
+}
diff --git a/website/docs/migrations/from-v4-to-v5.md b/website/docs/migrations/from-v4-to-v5.md
new file mode 100644
index 0000000000..8b887a153b
--- /dev/null
+++ b/website/docs/migrations/from-v4-to-v5.md
@@ -0,0 +1,11 @@
+# From v4 to v5
+
+In this document you can find the migration guide from the previous version v4 to v5.
+
+## Plugin Typings
+
+Some of the plugin types and interfaces have been renamed due to the additional of Pane Primitives.
+
+- `ISeriesPrimitivePaneView` -> `IPrimitivePaneView`
+- `ISeriesPrimitivePaneRenderer` -> `IPrimitivePaneRenderer`
+- `SeriesPrimitivePaneViewZOrder` -> `PrimitivePaneViewZOrder`

From 5f53373420c1da891daa71d464cd4acbf5d75651 Mon Sep 17 00:00:00 2001
From: Mark Silverwood <3482679+SlicedSilver@users.noreply.github.com>
Date: Mon, 29 Jul 2024 21:39:56 +0100
Subject: [PATCH 02/12] improve e2e tests for pane primitives

---
 tests/e2e/graphics/test-cases/plugins/pane-primitives.js   | 7 +------
 .../test-cases/plugins/pane-primitive-hit-test.js          | 4 ++--
 2 files changed, 3 insertions(+), 8 deletions(-)

diff --git a/tests/e2e/graphics/test-cases/plugins/pane-primitives.js b/tests/e2e/graphics/test-cases/plugins/pane-primitives.js
index 044bbea3bf..2e30ad663c 100644
--- a/tests/e2e/graphics/test-cases/plugins/pane-primitives.js
+++ b/tests/e2e/graphics/test-cases/plugins/pane-primitives.js
@@ -99,12 +99,7 @@ class AnchoredText {
 function runTestCase(container) {
 	const chart = (window.chart = LightweightCharts.createChart(container, {
 		layout: {
-			attributionLogo: true,
-			background: {
-				type: 'solid',
-				color: 'rgb(50,100,150)',
-			},
-			textColor: 'rgb(255,200,100)',
+			attributionLogo: false,
 		},
 	}));
 
diff --git a/tests/e2e/interactions/test-cases/plugins/pane-primitive-hit-test.js b/tests/e2e/interactions/test-cases/plugins/pane-primitive-hit-test.js
index 2accbd633e..bc7baa3f45 100644
--- a/tests/e2e/interactions/test-cases/plugins/pane-primitive-hit-test.js
+++ b/tests/e2e/interactions/test-cases/plugins/pane-primitive-hit-test.js
@@ -133,7 +133,7 @@ function beforeInteractions(container) {
 		if (!mouseParams) {
 			return;
 		}
-		if (mouseParams.hoveredObjectId === 'TEST') {
+		if (mouseParams.hoveredObjectId === 'PLUGIN') {
 			pass = true;
 			return;
 		}
@@ -156,7 +156,7 @@ function afterInitialInteractions() {
 
 function afterFinalInteractions() {
 	if (!pass) {
-		throw new Error("Expected hoveredObjectId to be equal to 'TEST'.");
+		throw new Error("Expected hoveredObjectId to be equal to 'PLUGIN'.");
 	}
 
 	return Promise.resolve();

From ac045cce3f884362ef0d9ef13cde34bee82104ff Mon Sep 17 00:00:00 2001
From: Mark Silverwood <3482679+SlicedSilver@users.noreply.github.com>
Date: Mon, 29 Jul 2024 21:44:41 +0100
Subject: [PATCH 03/12] add coverage e2e test for pane primitives

---
 .../plugins/pane-primitive-with-hit-test.js   | 150 ++++++++++++++++++
 1 file changed, 150 insertions(+)
 create mode 100644 tests/e2e/coverage/test-cases/plugins/pane-primitive-with-hit-test.js

diff --git a/tests/e2e/coverage/test-cases/plugins/pane-primitive-with-hit-test.js b/tests/e2e/coverage/test-cases/plugins/pane-primitive-with-hit-test.js
new file mode 100644
index 0000000000..c5d82ef1b0
--- /dev/null
+++ b/tests/e2e/coverage/test-cases/plugins/pane-primitive-with-hit-test.js
@@ -0,0 +1,150 @@
+function generateData() {
+	const res = [];
+	const time = new Date(Date.UTC(2018, 0, 1, 0, 0, 0, 0));
+	for (let i = 0; i < 500; ++i) {
+		res.push({
+			time: time.getTime() / 1000,
+			value: i,
+		});
+
+		time.setUTCDate(time.getUTCDate() + 1);
+	}
+	return res;
+}
+
+const testLayer = 'normal';
+const drawBackground = true; // whether the renderer is using drawBackground or draw
+
+class HitTestRenderer {
+	_draw(target) {
+		target.useMediaCoordinateSpace(scope => {
+			const ctx = scope.context;
+			ctx.save();
+			const width = scope.mediaSize.width;
+			const height = scope.mediaSize.height;
+			const boxWidth = Math.round(width / 2);
+			const boxHeight = Math.round(height / 2);
+			const x = Math.round((width - boxWidth) / 2);
+			const y = Math.round((height - boxHeight) / 2);
+
+			ctx.beginPath();
+			ctx.fillStyle = 'rgba(0,0,0,0.5)';
+			ctx.fillRect(x, y, boxWidth, boxHeight);
+			this._hitBox = {
+				x,
+				y,
+				height: boxHeight,
+				width: boxWidth,
+			};
+			ctx.restore();
+		});
+	}
+
+	draw(target) {
+		if (!drawBackground) {this._draw(target);}
+	}
+
+	drawBackground(target) {
+		if (drawBackground) {this._draw(target);}
+	}
+
+	hitTest(x, y) {
+		if (
+			!this._hitBox ||
+						x < this._hitBox.x ||
+						y < this._hitBox.y ||
+						x > this._hitBox.x + this._hitBox.width ||
+						y > this._hitBox.y + this._hitBox.height
+		) {return null;}
+		return {
+			cursorStyle: 'pointer',
+			externalId: 'PLUGIN',
+		};
+	}
+}
+
+class HitTestPaneView {
+	constructor() {
+		this._renderer = new HitTestRenderer();
+	}
+
+	update() {}
+
+	renderer() {
+		return this._renderer;
+	}
+
+	hitTest(x, y) {
+		const result = this._renderer.hitTest(x, y);
+		if (result) {
+			return {
+				...result,
+				zOrder: this.zOrder(),
+				isBackground: drawBackground,
+			};
+		}
+		return null;
+	}
+
+	zOrder() {
+		return testLayer;
+	}
+}
+
+class HitTest {
+	constructor() {
+		this._paneViews = [new HitTestPaneView()];
+	}
+
+	updateAllViews() {
+		this._paneViews.forEach(pw => pw.update());
+	}
+
+	paneViews() {
+		return this._paneViews;
+	}
+
+	hitTest(x, y) {
+		return this._paneViews[0].hitTest(x, y);
+	}
+}
+
+function interactionsToPerform() {
+	return [{ action: 'click' }];
+}
+
+let chart;
+
+function beforeInteractions(container) {
+	chart = LightweightCharts.createChart(container);
+
+	const mainSeries = chart.addLineSeries();
+
+	mainSeries.setData(generateData());
+	const firstPane = chart.panes()[0];
+	firstPane.attachPrimitive(new HitTest());
+
+	chart.subscribeClick(mouseParams => {
+		if (!mouseParams) {
+			return;
+		}
+		if (mouseParams.hoveredObjectId === 'PLUGIN') {
+			return;
+		}
+	});
+
+	return new Promise(resolve => {
+		requestAnimationFrame(() => {
+			resolve();
+		});
+	});
+}
+
+function afterInteractions() {
+	return new Promise(resolve => {
+		requestAnimationFrame(() => {
+			setTimeout(resolve, 50);
+		});
+	});
+}
+

From cf0d662c25a24f1edf70a86eab721a79e86b4054 Mon Sep 17 00:00:00 2001
From: Mark Silverwood <3482679+SlicedSilver@users.noreply.github.com>
Date: Mon, 29 Jul 2024 22:51:14 +0100
Subject: [PATCH 04/12] improve internal typings for pane primitives

---
 src/api/ichart-api.ts          |  6 ++++++
 src/api/ipane-primitive-api.ts |  4 ++--
 src/gui/draw-functions.ts      |  7 +++----
 src/gui/pane-widget.ts         | 12 +++++-------
 src/gui/price-axis-widget.ts   | 10 +++++-----
 src/model/chart-model.ts       | 10 +++++++---
 src/model/ipane-primitive.ts   |  6 +++---
 7 files changed, 31 insertions(+), 24 deletions(-)

diff --git a/src/api/ichart-api.ts b/src/api/ichart-api.ts
index de108cc805..f28ddedc9b 100644
--- a/src/api/ichart-api.ts
+++ b/src/api/ichart-api.ts
@@ -132,6 +132,7 @@ export interface IChartApiBase<HorzScaleItem = Time> {
 	 * Creates an area series with specified parameters.
 	 *
 	 * @param areaOptions - Customization parameters of the series being created.
+	 * @param paneIndex - Index of the Pane to create the series on.
 	 * @returns An interface of the created series.
 	 * @example
 	 * ```js
@@ -144,6 +145,7 @@ export interface IChartApiBase<HorzScaleItem = Time> {
 	 * Creates a baseline series with specified parameters.
 	 *
 	 * @param baselineOptions - Customization parameters of the series being created.
+	 * @param paneIndex - Index of the Pane to create the series on.
 	 * @returns An interface of the created series.
 	 * @example
 	 * ```js
@@ -156,6 +158,7 @@ export interface IChartApiBase<HorzScaleItem = Time> {
 	 * Creates a bar series with specified parameters.
 	 *
 	 * @param barOptions - Customization parameters of the series being created.
+	 * @param paneIndex - Index of the Pane to create the series on.
 	 * @returns An interface of the created series.
 	 * @example
 	 * ```js
@@ -168,6 +171,7 @@ export interface IChartApiBase<HorzScaleItem = Time> {
 	 * Creates a candlestick series with specified parameters.
 	 *
 	 * @param candlestickOptions - Customization parameters of the series being created.
+	 * @param paneIndex - Index of the Pane to create the series on.
 	 * @returns An interface of the created series.
 	 * @example
 	 * ```js
@@ -180,6 +184,7 @@ export interface IChartApiBase<HorzScaleItem = Time> {
 	 * Creates a histogram series with specified parameters.
 	 *
 	 * @param histogramOptions - Customization parameters of the series being created.
+	 * @param paneIndex - Index of the Pane to create the series on.
 	 * @returns An interface of the created series.
 	 * @example
 	 * ```js
@@ -192,6 +197,7 @@ export interface IChartApiBase<HorzScaleItem = Time> {
 	 * Creates a line series with specified parameters.
 	 *
 	 * @param lineOptions - Customization parameters of the series being created.
+	 * @param paneIndex - Index of the Pane to create the series on.
 	 * @returns An interface of the created series.
 	 * @example
 	 * ```js
diff --git a/src/api/ipane-primitive-api.ts b/src/api/ipane-primitive-api.ts
index b0615d560d..4dee67b292 100644
--- a/src/api/ipane-primitive-api.ts
+++ b/src/api/ipane-primitive-api.ts
@@ -4,7 +4,7 @@ import { IPanePrimitiveBase } from '../model/ipane-primitive';
 import { IChartApiBase } from './ichart-api';
 
 /**
- * Object containing references to the chart and series instances, and a requestUpdate method for triggering
+ * Object containing references to the chart instance, and a requestUpdate method for triggering
  * a refresh of the chart.
  */
 export interface PaneAttachedParameter<
@@ -21,7 +21,7 @@ export interface PaneAttachedParameter<
 }
 
 /**
- * Interface for series primitives. It must be implemented to add some external graphics to series.
+ * Interface for pane primitives. It must be implemented to add some external graphics to a pane.
  */
 export type IPanePrimitive<HorzScaleItem = Time> = IPanePrimitiveBase<
     PaneAttachedParameter<HorzScaleItem>
diff --git a/src/gui/draw-functions.ts b/src/gui/draw-functions.ts
index 3888effd57..f7de7e3de7 100644
--- a/src/gui/draw-functions.ts
+++ b/src/gui/draw-functions.ts
@@ -3,6 +3,8 @@ import { CanvasRenderingTarget2D } from 'fancy-canvas';
 import { IDataSource, IDataSourcePaneViews } from '../model/idata-source';
 import { Pane } from '../model/pane';
 import { IPaneRenderer } from '../renderers/ipane-renderer';
+import { IAxisView } from '../views/pane/iaxis-view';
+import { IPaneView } from '../views/pane/ipane-view';
 
 import { IAxisViewsGetter } from './iaxis-view-getters';
 import { IPaneViewsGetter } from './ipane-view-getter';
@@ -47,10 +49,7 @@ export function drawSourceViews<T extends IDataSource | IDataSourcePaneViews>(
 	pane: Pane
 ): void {
 	const views = (
-		paneViewsGetter as unknown as (
-			source: T,
-			pane: Pane
-		) => ReturnType<ViewsGetter<T>>
+		paneViewsGetter as (s: T, p: Pane) => readonly (IAxisView | IPaneView)[]
 	)(source, pane);
 	for (const view of views) {
 		const renderer = view.renderer(pane);
diff --git a/src/gui/pane-widget.ts b/src/gui/pane-widget.ts
index 4cb26ea632..5eefde20f3 100644
--- a/src/gui/pane-widget.ts
+++ b/src/gui/pane-widget.ts
@@ -29,9 +29,7 @@ import { IPaneView } from '../views/pane/ipane-view';
 import { AttributionLogoWidget } from './attribution-logo-widget';
 import { createBoundCanvas, releaseCanvas } from './canvas-utils';
 import { IChartWidgetBase } from './chart-widget';
-import { drawBackground, drawForeground, DrawFunction, drawSourceViews } from './draw-functions';
-import { IAxisViewsGetter } from './iaxis-view-getters';
-import { IPaneViewsGetter } from './ipane-view-getter';
+import { drawBackground, drawForeground, DrawFunction, drawSourceViews, ViewsGetter } from './draw-functions';
 import { MouseEventHandler, MouseEventHandlerEventBase, MouseEventHandlerMouseEvent, MouseEventHandlers, MouseEventHandlerTouchEvent, Position, TouchMouseEvent } from './mouse-event-handler';
 import { hitTestPane, HitTestResult } from './pane-hit-test';
 import { PriceAxisWidget, PriceAxisWidgetSide } from './price-axis-widget';
@@ -518,7 +516,7 @@ export class PaneWidget implements IDestroyable, MouseEventHandlers {
 		return this._rightPriceAxisWidget;
 	}
 
-	public drawAdditionalSources(target: CanvasRenderingTarget2D, paneViewsGetter: IPaneViewsGetter | IAxisViewsGetter): void {
+	public drawAdditionalSources(target: CanvasRenderingTarget2D, paneViewsGetter: ViewsGetter<IDataSourcePaneViews>): void {
 		this._drawSources(target, paneViewsGetter);
 	}
 
@@ -575,7 +573,7 @@ export class PaneWidget implements IDestroyable, MouseEventHandlers {
 		this._drawSourceImpl(target, sourcePaneViews, drawForeground, this._model().crosshairSource());
 	}
 
-	private _drawSources(target: CanvasRenderingTarget2D, paneViewsGetter: IPaneViewsGetter | IAxisViewsGetter): void {
+	private _drawSources(target: CanvasRenderingTarget2D, paneViewsGetter: ViewsGetter<IDataSourcePaneViews>): void {
 		const state = ensureNotNull(this._state);
 		const sources = state.orderedSources();
 
@@ -597,7 +595,7 @@ export class PaneWidget implements IDestroyable, MouseEventHandlers {
 
 	private _drawSourceImpl(
 		target: CanvasRenderingTarget2D,
-		paneViewsGetter: IPaneViewsGetter | IAxisViewsGetter,
+		paneViewsGetter: ViewsGetter<IDataSourcePaneViews>,
 		drawFn: DrawFunction,
 		source: IDataSourcePaneViews
 	): void {
@@ -609,7 +607,7 @@ export class PaneWidget implements IDestroyable, MouseEventHandlers {
 			: undefined;
 
 		const drawRendererFn = (renderer: IPaneRenderer) => drawFn(renderer, target, isHovered, objecId);
-		drawSourceViews(paneViewsGetter as IPaneViewsGetter, drawRendererFn, source, state);
+		drawSourceViews(paneViewsGetter, drawRendererFn, source, state);
 	}
 
 	private _recreatePriceAxisWidgets(): void {
diff --git a/src/gui/price-axis-widget.ts b/src/gui/price-axis-widget.ts
index a89c7a282c..a1c613228d 100644
--- a/src/gui/price-axis-widget.ts
+++ b/src/gui/price-axis-widget.ts
@@ -30,7 +30,7 @@ import { IAxisView } from '../views/pane/iaxis-view';
 import { IPriceAxisView } from '../views/price-axis/iprice-axis-view';
 
 import { createBoundCanvas, releaseCanvas } from './canvas-utils';
-import { IPriceAxisViewsGetter } from './iaxis-view-getters';
+import { ViewsGetter } from './draw-functions';
 import { suggestPriceScaleWidth } from './internal-layout-sizes-hints';
 import { MouseEventHandler, MouseEventHandlers, TouchMouseEvent } from './mouse-event-handler';
 import { PaneWidget } from './pane-widget';
@@ -59,7 +59,7 @@ function hasPriceScale(source: IDataSource | IDataSourcePaneViews): source is ID
 function buildPriceAxisViewsGetter(
 	zOrder: PrimitivePaneViewZOrder,
 	priceScaleId: PriceAxisWidgetSide
-): IPriceAxisViewsGetter {
+): ViewsGetter<IDataSourcePaneViews> {
 	return (source: IDataSource | IDataSourcePaneViews): readonly IAxisView[] => {
 		if (!hasPriceScale(source)) {
 			return [];
@@ -143,9 +143,9 @@ export class PriceAxisWidget implements IDestroyable {
 	private _prevOptimalWidth: number = 0;
 	private _isSettingSize: boolean = false;
 
-	private _sourcePaneViews: IPriceAxisViewsGetter;
-	private _sourceTopPaneViews: IPriceAxisViewsGetter;
-	private _sourceBottomPaneViews: IPriceAxisViewsGetter;
+	private _sourcePaneViews: ViewsGetter<IDataSourcePaneViews>;
+	private _sourceTopPaneViews: ViewsGetter<IDataSourcePaneViews>;
+	private _sourceBottomPaneViews: ViewsGetter<IDataSourcePaneViews>;
 
 	public constructor(pane: PaneWidget, options: Readonly<ChartOptionsInternalBase>, rendererOptionsProvider: PriceAxisRendererOptionsProvider, side: PriceAxisWidgetSide) {
 		this._pane = pane;
diff --git a/src/model/chart-model.ts b/src/model/chart-model.ts
index a15e2fdaf4..7cd309df8a 100644
--- a/src/model/chart-model.ts
+++ b/src/model/chart-model.ts
@@ -447,6 +447,10 @@ export interface IChartModelBase {
 	changePanesHeight(paneIndex: number, height: number): void;
 }
 
+function isPanePrimitive(source: IPriceDataSource | IPrimitiveHitTestSource): source is IPrimitiveHitTestSource | Pane {
+	return source instanceof Pane;
+}
+
 export class ChartModel<HorzScaleItem> implements IDestroyable, IChartModelBase {
 	private readonly _options: ChartOptionsInternal<HorzScaleItem>;
 	private readonly _invalidateHandler: InvalidateHandler;
@@ -875,10 +879,10 @@ export class ChartModel<HorzScaleItem> implements IDestroyable, IChartModelBase
 	}
 
 	public paneForSource(source: IPriceDataSource | IPrimitiveHitTestSource): Pane | null {
-		if (source instanceof Pane) {
-			return source;
+		if (isPanePrimitive(source)) {
+			return source as Pane;
 		}
-		const pane = this._panes.find((p: Pane) => p.orderedSources().includes(source as IPriceDataSource));
+		const pane = this._panes.find((p: Pane) => p.orderedSources().includes(source));
 		return pane === undefined ? null : pane;
 	}
 
diff --git a/src/model/ipane-primitive.ts b/src/model/ipane-primitive.ts
index 9330f9df47..097d167034 100644
--- a/src/model/ipane-primitive.ts
+++ b/src/model/ipane-primitive.ts
@@ -38,7 +38,7 @@ export interface IPrimitivePaneView {
 	/**
 	 * Defines where in the visual layer stack the renderer should be executed. Default is `'normal'`.
 	 *
-	 * @returns the desired position in the visual layer stack. @see {@link SeriesPrimitivePaneViewZOrder}
+	 * @returns the desired position in the visual layer stack. @see {@link PrimitivePaneViewZOrder}
 	 */
 	zOrder?(): PrimitivePaneViewZOrder;
 	/**
@@ -61,7 +61,7 @@ export interface IPanePrimitivePaneView {
 	/**
 	 * Defines where in the visual layer stack the renderer should be executed. Default is `'normal'`.
 	 *
-	 * @returns the desired position in the visual layer stack. @see {@link SeriesPrimitivePaneViewZOrder}
+	 * @returns the desired position in the visual layer stack. @see {@link PrimitivePaneViewZOrder}
 	 */
 	zOrder?(): PrimitivePaneViewZOrder;
 	/**
@@ -107,7 +107,7 @@ export interface IPanePrimitiveBase<TPaneAttachedParameters = unknown> {
 	/**
 	 * Returns array of objects representing primitive in the main area of the chart
 	 *
-	 * @returns array of objects; each of then must implement ISeriesPrimitivePaneView interface
+	 * @returns array of objects; each of then must implement IPrimitivePaneView interface
 	 *
 	 * For performance reasons, the lightweight library uses internal caches based on references to arrays
 	 * So, this method must return new array if set of views has changed and should try to return the same array if nothing changed

From dc5abb69e577a84fbfca3334fe1c35b52bb14748 Mon Sep 17 00:00:00 2001
From: Mark Silverwood <3482679+SlicedSilver@users.noreply.github.com>
Date: Tue, 30 Jul 2024 10:57:14 +0100
Subject: [PATCH 05/12] update documentation for plugins

---
 .../docs/plugins/canvas-rendering-target.md   |  2 +-
 website/docs/plugins/custom_series.md         |  2 +-
 website/docs/plugins/intro.md                 | 37 +++++++------
 website/docs/plugins/pane-primitives.md       | 55 +++++++++++++++++++
 website/docs/plugins/series-primitives.mdx    | 16 +++---
 5 files changed, 85 insertions(+), 27 deletions(-)
 create mode 100644 website/docs/plugins/pane-primitives.md

diff --git a/website/docs/plugins/canvas-rendering-target.md b/website/docs/plugins/canvas-rendering-target.md
index e646a9bc1e..6b40dead39 100644
--- a/website/docs/plugins/canvas-rendering-target.md
+++ b/website/docs/plugins/canvas-rendering-target.md
@@ -1,6 +1,6 @@
 ---
 sidebar_label: Canvas Rendering Target
-sidebar_position: 3
+sidebar_position: 4
 ---
 
 # Canvas Rendering Target
diff --git a/website/docs/plugins/custom_series.md b/website/docs/plugins/custom_series.md
index 3fc84325c1..383e746fe4 100644
--- a/website/docs/plugins/custom_series.md
+++ b/website/docs/plugins/custom_series.md
@@ -1,6 +1,6 @@
 ---
 sidebar_label: Custom Series Types
-sidebar_position: 2
+sidebar_position: 3
 ---
 
 # Custom Series Types
diff --git a/website/docs/plugins/intro.md b/website/docs/plugins/intro.md
index 9644d7c737..9c36b4caab 100644
--- a/website/docs/plugins/intro.md
+++ b/website/docs/plugins/intro.md
@@ -8,11 +8,14 @@ sidebar_position: 0
 The library provides a rich set of charting capabilities out of the box, but
 developers can also extend its functionality by building custom plugins.
 
-Plugins in Lightweight Charts™️ come in two types:
-[custom series](#custom-series) and [drawing primitives](#drawing-primitives).
+Plugins in Lightweight Charts™️ come in three types:
+[custom series](#custom-series), [drawing primitives](#drawing-primitives),
+and [pane primitives](#pane-primitives).
 Custom series allow developers to define new types of series, while drawing
 primitives enable the creation of custom visualizations, drawing tools, and
 chart annotations (and more) which can be attached to an existing series.
+Pane primitives are similar to series primitives but are attached to the chart
+pane itself, allowing for chart-wide annotations or features like watermarks.
 
 :::tip Picking between the Custom Series and Drawing Primitives
 
@@ -115,31 +118,31 @@ const data = [
 lineSeries.attachPrimitive(myCustomPrimitive);
 ```
 
-### Adding a primitive to the chart instead of a series
+## Pane Primitives
 
-It is required that a drawing primitive is attached to series on the chart. In some cases, it might not make sense to attach a primitive to a specific series on the chart, for example if you are dynamically adding and removing series but would like a specific primitive to remain on the chart always. If this is the case then it is recommended to create an empty series (of any type) and attach the primitive to that instead.
+Pane Primitives are similar to Series Primitives but are attached to the chart pane itself rather than a specific series. They are ideal for creating chart-wide annotations or features that are not tied to any particular series data.
 
-:::caution
+### Adding a Pane Primitive to a chart
 
-This series wouldn't have data, and thus wouldn't have the concept of price values for the vertical positioning of items. In some cases, such as a watermark, this isn't an issue.
+A Pane Primitive can be added to a chart using the `attachPrimitive()` method on the `IPaneApi` interface. Here's an example:
 
-:::
+```javascript
+class MyCustomPanePrimitive {
+    /* Class implementing the IPanePrimitive interface */
+}
 
-**Example:**
-
-```js title='javascript'
-// ...
-// Create an instantiated series primitive.
-const myCustomPrimitive = new MyCustomPrimitive();
+// Create an instantiated pane primitive.
+const myCustomPanePrimitive = new MyCustomPanePrimitive();
 
 const chart = createChart(document.getElementById('container'));
+const mainPane = chart.panes()[0]; // Get the main pane
 
-// an empty series which won't ever have data
-const chartSeries = chart.addLineSeries();
-chartSeries.attachPrimitive(myCustomPrimitive);
-
+// Attach the primitive to the pane
+mainPane.attachPrimitive(myCustomPanePrimitive);
 ```
 
+Pane Primitives offer a powerful way to add chart-wide features or annotations without the need to associate them with a specific series.
+
 ## Examples
 
 We have a few example plugins within the `plugin-examples` folder of the Lightweight Charts™️ repo: [plugin-examples](https://github.com/tradingview/lightweight-charts/tree/master/plugin-examples).
diff --git a/website/docs/plugins/pane-primitives.md b/website/docs/plugins/pane-primitives.md
new file mode 100644
index 0000000000..074eea2737
--- /dev/null
+++ b/website/docs/plugins/pane-primitives.md
@@ -0,0 +1,55 @@
+---
+sidebar_label: Pane Primitives
+sidebar_position: 2
+---
+
+# Pane Primitives
+
+In addition to Series Primitives, the library now supports Pane Primitives. These are essentially the same as Series Primitives but are designed to draw on the pane of a chart rather than being associated with a specific series. Pane Primitives can be used for features like watermarks or other chart-wide annotations.
+
+## Key Differences from Series Primitives
+
+1. Pane Primitives are attached to the chart pane rather than a specific series.
+2. They cannot draw on the price and time scales.
+3. They are ideal for chart-wide features that are not tied to a particular series.
+
+## Adding a Pane Primitive
+
+Pane Primitives can be added to a chart using the `attachPrimitive` method on the [`IPaneApi`](../api/interfaces/IPaneApi.md) interface. Here's an example:
+
+```javascript
+const chart = createChart(document.getElementById('container'));
+const pane = chart.panes()[0]; // Get the first (main) pane
+
+const myPanePrimitive = new MyCustomPanePrimitive();
+pane.attachPrimitive(myPanePrimitive);
+```
+
+## Implementing a Pane Primitive
+
+To create a Pane Primitive, you should implement the [`IPanePrimitive`](../api/type-aliases/IPanePrimitive.md) interface. This interface is similar to [`ISeriesPrimitive`](../api/type-aliases/ISeriesPrimitive.md), but with some key differences:
+
+- It doesn't include methods for drawing on price and time scales.
+- The `paneViews` method is used to define what will be drawn on the chart pane.
+
+Here's a basic example of a Pane Primitive implementation:
+
+```javascript
+class MyCustomPanePrimitive {
+    paneViews() {
+        return [
+            {
+                renderer: {
+                    draw: target => {
+                        // Custom drawing logic here
+                    },
+                },
+            },
+        ];
+    }
+
+    // Other methods as needed...
+}
+```
+
+For more details on implementing Pane Primitives, refer to the [`IPanePrimitive`](../api/type-aliases/IPanePrimitive.md) interface documentation.
diff --git a/website/docs/plugins/series-primitives.mdx b/website/docs/plugins/series-primitives.mdx
index f6ece87d0d..1cfc0dd12b 100644
--- a/website/docs/plugins/series-primitives.mdx
+++ b/website/docs/plugins/series-primitives.mdx
@@ -23,7 +23,7 @@ panes.
 There are two types of views which are supported within `ISeriesPrimitive` which
 are:
 
-- [`ISeriesPrimitivePaneView`](../api/interfaces/ISeriesPrimitivePaneView.md)
+- [`IPrimitivePaneView`](../api/interfaces/IPrimitivePaneView.md)
 - [`ISeriesPrimitiveAxisView`](../api/interfaces/ISeriesPrimitiveAxisView.md)
 
 The library will evoke the following getter functions (if defined) to get
@@ -55,25 +55,25 @@ import sectionsExplainerCode from '!!raw-loader!./explainer-sections-demo.js';
 	{sectionsExplainerCode}
 </CodeBlock>
 
-### ISeriesPrimitivePaneView
+### IPrimitivePaneView
 
-The [`ISeriesPrimitivePaneView`](../api/interfaces/ISeriesPrimitivePaneView.md)
+The [`IPrimitivePaneView`](../api/interfaces/IPrimitivePaneView.md)
 interface can be used to define a view which provides a renderer (implementing
 the
-[`ISeriesPrimitivePaneRenderer`](../api/interfaces/ISeriesPrimitivePaneRenderer.md)
+[`IPrimitivePaneRenderer`](../api/interfaces/IPrimitivePaneRenderer.md)
 interface) for drawing on the corresponding area of the chart using the
 [CanvasRenderingContext2D](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D)
 API. The view can define a
-[`zOrder`](../api/interfaces/ISeriesPrimitivePaneView.md#zorder) to control where
+[`zOrder`](../api/interfaces/IPrimitivePaneView.md#zorder) to control where
 in the visual stack the drawing will occur (See
-[`SeriesPrimitivePaneViewZOrder`](../api/type-aliases/SeriesPrimitivePaneViewZOrder.md)
+[`PrimitivePaneViewZOrder`](../api/type-aliases/PrimitivePaneViewZOrder.md)
 for more information).
 
 Renderers should provide a
-[`draw`](../api/interfaces/ISeriesPrimitivePaneRenderer.md#draw) method which will
+[`draw`](../api/interfaces/IPrimitivePaneRenderer.md#draw) method which will
 be given a `CanvasRenderingTarget2D` target on which it can draw. Additionally,
 a renderer can optionally provide a
-[`drawBackground`](../api/interfaces/ISeriesPrimitivePaneRenderer.md#drawbackground)
+[`drawBackground`](../api/interfaces/IPrimitivePaneRenderer.md#drawbackground)
 method for drawing beneath other elements on the same zOrder.
 
 :::tip

From c6749ea5414b33721b4b7281b4785f84d64e4ac7 Mon Sep 17 00:00:00 2001
From: Mark Silverwood <3482679+SlicedSilver@users.noreply.github.com>
Date: Tue, 30 Jul 2024 11:37:12 +0100
Subject: [PATCH 06/12] remove duplicate type definition

and add a CI check
---
 package.json                            |  4 ++-
 scripts/check-typings-for-duplicates.js | 37 +++++++++++++++++++++++++
 src/gui/pane-hit-test.ts                |  5 +---
 src/model/idata-source.ts               |  3 +-
 src/model/iseries-primitive.ts          | 25 +----------------
 src/model/pane-primitive-wrapper.ts     |  2 +-
 src/model/series.ts                     |  4 +--
 7 files changed, 46 insertions(+), 34 deletions(-)
 create mode 100644 scripts/check-typings-for-duplicates.js

diff --git a/package.json b/package.json
index 18b184243f..e63f6da591 100644
--- a/package.json
+++ b/package.json
@@ -120,7 +120,9 @@
     "lint": "npm-run-all -p lint:**",
     "lint:eslint": "eslint --format=unix ./",
     "lint:md": "markdownlint -i \"**/node_modules/**\" -i \"**/website/docs/api/**\" -i \"**/website/versioned_docs/**/api/**\" -i \"**/*.mdx\" \"**/*.md\"",
-    "check-dts-docs": "eslint --format=unix ./dist/typings.d.ts --no-ignore",
+    "check-dts-docs": "npm-run-all -p check-dts-docs-duplicates check-dts-docs-eslint",
+    "check-dts-docs-duplicates": "node ./scripts/check-typings-for-duplicates.js ./dist/typings.d.ts",
+    "check-dts-docs-eslint": "eslint --format=unix ./dist/typings.d.ts --no-ignore",
     "check-markdown-links": "node scripts/check-markdown-links.js",
     "rollup": "rollup -c rollup.config.js",
     "rollup-watch": "npm run rollup -- --watch",
diff --git a/scripts/check-typings-for-duplicates.js b/scripts/check-typings-for-duplicates.js
new file mode 100644
index 0000000000..e48f1b0317
--- /dev/null
+++ b/scripts/check-typings-for-duplicates.js
@@ -0,0 +1,37 @@
+import fs from 'node:fs/promises';
+import process from 'node:process';
+
+/*
+    Quick test to check if there are any duplicates in the d.ts file
+    which dts-bundle-generator found. The simple quick test is to
+    look for the string '$1 '.
+*/
+
+async function checkDtsFile(filePath) {
+	try {
+		// Read the contents of the .d.ts file
+		const content = await fs.readFile(filePath, 'utf-8');
+
+		// Check if the content includes the string '$1 '
+		if (content.includes('$1 ')) {
+			console.error('Error: The string "$1 " was found in the .d.ts file. This typically means there is a duplicate type definition.');
+			process.exit(1); // Exit with an error code
+		} else {
+			process.exit(0); // Exit successfully
+		}
+	} catch (error) {
+		console.error('An error occurred:', error.message);
+		process.exit(1); // Exit with an error code
+	}
+}
+
+// Check if a file path is provided as a command-line argument
+if (process.argv.length < 3) {
+	console.error(
+		'Please provide the path to the .d.ts file as a command-line argument.'
+	);
+	process.exit(1);
+}
+
+const filePath = process.argv[2];
+checkDtsFile(filePath);
diff --git a/src/gui/pane-hit-test.ts b/src/gui/pane-hit-test.ts
index cbdec042c2..99969ae5df 100644
--- a/src/gui/pane-hit-test.ts
+++ b/src/gui/pane-hit-test.ts
@@ -1,10 +1,7 @@
 import { HoveredObject } from '../model/chart-model';
 import { Coordinate } from '../model/coordinate';
 import { IDataSource, IPrimitiveHitTestSource } from '../model/idata-source';
-import { PrimitivePaneViewZOrder } from '../model/ipane-primitive';
-import {
-	PrimitiveHoveredItem,
-} from '../model/iseries-primitive';
+import { PrimitiveHoveredItem, PrimitivePaneViewZOrder } from '../model/ipane-primitive';
 import { Pane } from '../model/pane';
 import { IPaneView } from '../views/pane/ipane-view';
 
diff --git a/src/model/idata-source.ts b/src/model/idata-source.ts
index ef83d9c24a..1b88087d97 100644
--- a/src/model/idata-source.ts
+++ b/src/model/idata-source.ts
@@ -4,8 +4,7 @@ import { IPriceAxisView } from '../views/price-axis/iprice-axis-view';
 import { ITimeAxisView } from '../views/time-axis/itime-axis-view';
 
 import { Coordinate } from './coordinate';
-import { PrimitivePaneViewZOrder } from './ipane-primitive';
-import { PrimitiveHoveredItem } from './iseries-primitive';
+import { PrimitiveHoveredItem, PrimitivePaneViewZOrder } from './ipane-primitive';
 import { Pane } from './pane';
 import { PriceScale } from './price-scale';
 
diff --git a/src/model/iseries-primitive.ts b/src/model/iseries-primitive.ts
index aa57cd3243..8e6914acd2 100644
--- a/src/model/iseries-primitive.ts
+++ b/src/model/iseries-primitive.ts
@@ -1,4 +1,4 @@
-import { IPrimitivePaneView, PrimitivePaneViewZOrder } from './ipane-primitive';
+import { IPrimitivePaneView, PrimitiveHoveredItem } from './ipane-primitive';
 import { AutoscaleInfo } from './series-options';
 import { Logical } from './time-data';
 
@@ -50,29 +50,6 @@ export interface ISeriesPrimitiveAxisView {
 	tickVisible?(): boolean;
 }
 
-/**
- * Data representing the currently hovered object from the Hit test.
- */
-export interface PrimitiveHoveredItem {
-	/**
-	 * CSS cursor style as defined here: [MDN: CSS Cursor](https://developer.mozilla.org/en-US/docs/Web/CSS/cursor) or `undefined`
-	 * if you want the library to use the default cursor style instead.
-	 */
-	cursorStyle?: string;
-	/**
-	 * Hovered objects external ID. Can be used to identify the source item within a mouse subscriber event.
-	 */
-	externalId: string;
-	/**
-	 * The zOrder of the hovered item.
-	 */
-	zOrder: PrimitivePaneViewZOrder;
-	/**
-	 * Set to true if the object is rendered using `drawBackground` instead of `draw`.
-	 */
-	isBackground?: boolean;
-}
-
 /**
  * Base interface for series primitives. It must be implemented to add some external graphics to series
  */
diff --git a/src/model/pane-primitive-wrapper.ts b/src/model/pane-primitive-wrapper.ts
index 4c72310973..79e869a253 100644
--- a/src/model/pane-primitive-wrapper.ts
+++ b/src/model/pane-primitive-wrapper.ts
@@ -8,11 +8,11 @@ import {
     IPanePrimitiveBase,
     IPrimitivePaneRenderer,
     IPrimitivePaneView,
+    PrimitiveHoveredItem,
     PrimitivePaneViewZOrder,
 } from './ipane-primitive';
 import {
 	ISeriesPrimitiveBase,
-	PrimitiveHoveredItem,
 } from './iseries-primitive';
 
 class PrimitiveRendererWrapper implements IPaneRenderer {
diff --git a/src/model/series.ts b/src/model/series.ts
index af1aa1780e..dcf1c1a9fd 100644
--- a/src/model/series.ts
+++ b/src/model/series.ts
@@ -33,9 +33,9 @@ import { CustomPriceLine } from './custom-price-line';
 import { isDefaultPriceScale } from './default-price-scale';
 import { CustomData, CustomSeriesWhitespaceData, ICustomSeriesPaneView, WhitespaceCheck } from './icustom-series';
 import { InternalHorzScaleItem } from './ihorz-scale-behavior';
-import { PrimitivePaneViewZOrder } from './ipane-primitive';
+import { PrimitiveHoveredItem, PrimitivePaneViewZOrder } from './ipane-primitive';
 import { FirstValue, IPriceDataSource } from './iprice-data-source';
-import { ISeriesPrimitiveBase, PrimitiveHoveredItem } from './iseries-primitive';
+import { ISeriesPrimitiveBase } from './iseries-primitive';
 import { Pane } from './pane';
 import { PlotRowValueIndex } from './plot-data';
 import { MismatchDirection } from './plot-list';

From c5a84095f838f697ed45c381b58821bf96d61304 Mon Sep 17 00:00:00 2001
From: Mark Silverwood <3482679+SlicedSilver@users.noreply.github.com>
Date: Tue, 30 Jul 2024 16:36:38 +0100
Subject: [PATCH 07/12] extract watermark into TextWatermark primitive plugin

---
 .size-limit.js                                |  10 +-
 src/api/options/chart-options-defaults.ts     |   2 -
 src/api/options/watermark-options-defaults.ts |  14 --
 src/gui/pane-widget.ts                        |   7 -
 src/index.ts                                  |   5 +
 src/model/chart-model.ts                      |  19 ---
 src/model/watermark.ts                        |  93 ------------
 src/plugins/text-watermark/options.ts         |  93 ++++++++++++
 src/plugins/text-watermark/pane-renderer.ts   | 118 ++++++++++++++++
 src/plugins/text-watermark/pane-view.ts       |  54 +++++++
 src/plugins/text-watermark/primitive.ts       |  98 +++++++++++++
 src/plugins/types.ts                          |   8 ++
 src/renderers/watermark-renderer.ts           | 133 ------------------
 src/tsconfig.composite.json                   |   1 +
 src/views/pane/watermark-pane-view.ts         |  62 --------
 .../coverage/test-cases/chart/watermark.js    |  53 -------
 .../test-cases/plugins/text-watermark.js      |  64 +++++++++
 .../graphics/test-cases/api/series-markers.js |  15 +-
 .../api/subscribe-crosshair-move.js           |  30 +++-
 .../test-cases/applying-options/watermark.js  |  44 ++++--
 .../test-cases/initial-options/watermark.js   |  21 ++-
 website/docs/migrations/from-v4-to-v5.md      |  72 +++++++++-
 website/tutorials/how_to/.eslintrc.js         |   1 +
 website/tutorials/how_to/watermark-simple.js  |  23 +--
 website/tutorials/how_to/watermark.mdx        |  35 +++--
 25 files changed, 637 insertions(+), 438 deletions(-)
 delete mode 100644 src/api/options/watermark-options-defaults.ts
 delete mode 100644 src/model/watermark.ts
 create mode 100644 src/plugins/text-watermark/options.ts
 create mode 100644 src/plugins/text-watermark/pane-renderer.ts
 create mode 100644 src/plugins/text-watermark/pane-view.ts
 create mode 100644 src/plugins/text-watermark/primitive.ts
 create mode 100644 src/plugins/types.ts
 delete mode 100644 src/renderers/watermark-renderer.ts
 delete mode 100644 src/views/pane/watermark-pane-view.ts
 delete mode 100644 tests/e2e/coverage/test-cases/chart/watermark.js
 create mode 100644 tests/e2e/coverage/test-cases/plugins/text-watermark.js

diff --git a/.size-limit.js b/.size-limit.js
index 7e4e3f3c4a..ac4b0e917e 100644
--- a/.size-limit.js
+++ b/.size-limit.js
@@ -30,7 +30,7 @@ export default [
 		brotli: true,
 	},
 	{
-		name: 'Standalone-ESM',
+		name: 'ESM Standalone',
 		path: 'dist/lightweight-charts.standalone.production.mjs',
 		limit: '50.00 KB',
 		import: '*',
@@ -42,4 +42,12 @@ export default [
 		limit: '50.00 KB',
 		brotli: true,
 	},
+	{
+		name: 'Plugin: Text Watermark',
+		path: 'dist/lightweight-charts.production.mjs',
+		import: '{ TextWatermark }',
+		ignore: ['fancy-canvas'],
+		limit: '2.00 KB',
+		brotli: true,
+	},
 ];
diff --git a/src/api/options/chart-options-defaults.ts b/src/api/options/chart-options-defaults.ts
index 10c003e58f..3ef44f5464 100644
--- a/src/api/options/chart-options-defaults.ts
+++ b/src/api/options/chart-options-defaults.ts
@@ -7,7 +7,6 @@ import { gridOptionsDefaults } from './grid-options-defaults';
 import { layoutOptionsDefaults } from './layout-options-defaults';
 import { priceScaleOptionsDefaults } from './price-scale-options-defaults';
 import { timeScaleOptionsDefaults } from './time-scale-options-defaults';
-import { watermarkOptionsDefaults } from './watermark-options-defaults';
 
 export function chartOptionsDefaults<HorzScaleItem>(): ChartOptionsInternal<HorzScaleItem> {
 	return {
@@ -29,7 +28,6 @@ export function chartOptionsDefaults<HorzScaleItem>(): ChartOptionsInternal<Horz
 			visible: true,
 		},
 		timeScale: timeScaleOptionsDefaults,
-		watermark: watermarkOptionsDefaults,
 		localization: {
 			locale: isRunningOnClientSide ? navigator.language : '',
 			dateFormat: 'dd MMM \'yy',
diff --git a/src/api/options/watermark-options-defaults.ts b/src/api/options/watermark-options-defaults.ts
deleted file mode 100644
index 3c12a616c2..0000000000
--- a/src/api/options/watermark-options-defaults.ts
+++ /dev/null
@@ -1,14 +0,0 @@
-import { defaultFontFamily } from '../../helpers/make-font';
-
-import { WatermarkOptions } from '../../model/watermark';
-
-export const watermarkOptionsDefaults: WatermarkOptions = {
-	color: 'rgba(0, 0, 0, 0)',
-	visible: false,
-	fontSize: 48,
-	fontFamily: defaultFontFamily,
-	fontStyle: '',
-	text: '',
-	horzAlign: 'center',
-	vertAlign: 'center',
-};
diff --git a/src/gui/pane-widget.ts b/src/gui/pane-widget.ts
index 5eefde20f3..f0e49730c8 100644
--- a/src/gui/pane-widget.ts
+++ b/src/gui/pane-widget.ts
@@ -490,7 +490,6 @@ export class PaneWidget implements IDestroyable, MouseEventHandlers {
 				if (this._state) {
 					this._drawSources(target, sourceBottomPaneViews);
 					this._drawGrid(target);
-					this._drawWatermark(target);
 					this._drawSources(target, sourcePaneViews);
 					this._drawSources(target, sourceLabelPaneViews);
 				}
@@ -563,12 +562,6 @@ export class PaneWidget implements IDestroyable, MouseEventHandlers {
 		}
 	}
 
-	private _drawWatermark(target: CanvasRenderingTarget2D): void {
-		const source = this._model().watermarkSource();
-		this._drawSourceImpl(target, sourcePaneViews, drawBackground, source);
-		this._drawSourceImpl(target, sourcePaneViews, drawForeground, source);
-	}
-
 	private _drawCrosshair(target: CanvasRenderingTarget2D): void {
 		this._drawSourceImpl(target, sourcePaneViews, drawForeground, this._model().crosshairSource());
 	}
diff --git a/src/index.ts b/src/index.ts
index a3442c68a1..ac52d08eb8 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -21,6 +21,11 @@ export const customSeriesDefaultOptions: CustomSeriesOptions = {
 
 export { createChart, createChartEx, defaultHorzScaleBehavior } from './api/create-chart';
 
+/*
+	Plugins
+*/
+export { TextWatermark } from './plugins/text-watermark/primitive';
+
 /**
  * Returns the current version as a string. For example `'3.3.0'`.
  */
diff --git a/src/model/chart-model.ts b/src/model/chart-model.ts
index 7cd309df8a..860bff5ba8 100644
--- a/src/model/chart-model.ts
+++ b/src/model/chart-model.ts
@@ -30,7 +30,6 @@ import { SeriesOptionsMap, SeriesType } from './series-options';
 import { LogicalRange, TimePointIndex, TimeScalePoint } from './time-data';
 import { HorzScaleOptions, ITimeScale, TimeScale } from './time-scale';
 import { TouchMouseEventData } from './touch-mouse-event-data';
-import { Watermark, WatermarkOptions } from './watermark';
 
 /**
  * Represents options for how the chart is scrolled by the mouse and touch gestures.
@@ -268,16 +267,6 @@ export interface ChartOptionsBase {
 	 */
 	autoSize: boolean;
 
-	/**
-	 * Watermark options.
-	 *
-	 * A watermark is a background label that includes a brief description of the drawn data. Any text can be added to it.
-	 *
-	 * Please make sure you enable it and set an appropriate font color and size to make your watermark visible in the background of the chart.
-	 * We recommend a semi-transparent color and a large font. Also note that watermark position can be aligned vertically and horizontally.
-	 */
-	watermark: WatermarkOptions;
-
 	/**
 	 * Layout options
 	 */
@@ -420,7 +409,6 @@ export interface IChartModelBase {
 	setHoveredSource(source: HoveredSource | null): void;
 
 	crosshairSource(): Crosshair;
-	watermarkSource(): Watermark;
 
 	startScrollPrice(pane: Pane, priceScale: PriceScale, x: number): void;
 	scrollPriceTo(pane: Pane, priceScale: PriceScale, x: number): void;
@@ -461,7 +449,6 @@ export class ChartModel<HorzScaleItem> implements IDestroyable, IChartModelBase
 	private readonly _panes: Pane[] = [];
 	private readonly _crosshair: Crosshair;
 	private readonly _magnet: Magnet;
-	private readonly _watermark: Watermark;
 
 	private _serieses: Series<SeriesType>[] = [];
 
@@ -486,7 +473,6 @@ export class ChartModel<HorzScaleItem> implements IDestroyable, IChartModelBase
 		this._timeScale = new TimeScale(this, options.timeScale, this._options.localization, horzScaleBehavior);
 		this._crosshair = new Crosshair(this, options.crosshair);
 		this._magnet = new Magnet(options.crosshair);
-		this._watermark = new Watermark(this, options.watermark);
 
 		this._getOrCreatePane(0);
 		this._panes[0].setStretchFactor(DEFAULT_STRETCH_FACTOR * 2);
@@ -604,10 +590,6 @@ export class ChartModel<HorzScaleItem> implements IDestroyable, IChartModelBase
 		return this._panes;
 	}
 
-	public watermarkSource(): Watermark {
-		return this._watermark;
-	}
-
 	public crosshairSource(): Crosshair {
 		return this._crosshair;
 	}
@@ -887,7 +869,6 @@ export class ChartModel<HorzScaleItem> implements IDestroyable, IChartModelBase
 	}
 
 	public recalculateAllPanes(): void {
-		this._watermark.updateAllViews();
 		this._panes.forEach((p: Pane) => p.recalculate());
 		this.updateCrosshair();
 	}
diff --git a/src/model/watermark.ts b/src/model/watermark.ts
deleted file mode 100644
index 0cb88ca98e..0000000000
--- a/src/model/watermark.ts
+++ /dev/null
@@ -1,93 +0,0 @@
-import { HorzAlign, VertAlign } from '../renderers/watermark-renderer';
-import { IPaneView } from '../views/pane/ipane-view';
-import { WatermarkPaneView } from '../views/pane/watermark-pane-view';
-import { IPriceAxisView } from '../views/price-axis/iprice-axis-view';
-
-import { IChartModelBase } from './chart-model';
-import { DataSource } from './data-source';
-
-/** Watermark options. */
-export interface WatermarkOptions {
-	/**
-	 * Watermark color.
-	 *
-	 * @defaultValue `'rgba(0, 0, 0, 0)'`
-	 */
-	color: string;
-
-	/**
-	 * Display the watermark.
-	 *
-	 * @defaultValue `false`
-	 */
-	visible: boolean;
-
-	/**
-	 * Text of the watermark. Word wrapping is not supported.
-	 *
-	 * @defaultValue `''`
-	 */
-	text: string;
-
-	/**
-	 * Font size in pixels.
-	 *
-	 * @defaultValue `48`
-	 */
-	fontSize: number;
-
-	/**
-	 * Font family.
-	 *
-	 * @defaultValue `-apple-system, BlinkMacSystemFont, 'Trebuchet MS', Roboto, Ubuntu, sans-serif`
-	 */
-	fontFamily: string;
-
-	/**
-	 * Font style.
-	 *
-	 * @defaultValue `''`
-	 */
-	fontStyle: string;
-
-	/**
-	 * Horizontal alignment inside the chart area.
-	 *
-	 * @defaultValue `'center'`
-	 */
-	horzAlign: HorzAlign;
-
-	/**
-	 * Vertical alignment inside the chart area.
-	 *
-	 * @defaultValue `'center'`
-	 */
-	vertAlign: VertAlign;
-}
-
-export class Watermark extends DataSource {
-	private readonly _paneView: WatermarkPaneView;
-	private readonly _options: WatermarkOptions;
-
-	public constructor(model: IChartModelBase, options: WatermarkOptions) {
-		super();
-		this._options = options;
-		this._paneView = new WatermarkPaneView(this);
-	}
-
-	public override priceAxisViews(): readonly IPriceAxisView[] {
-		return [];
-	}
-
-	public paneViews(): readonly IPaneView[] {
-		return [this._paneView];
-	}
-
-	public options(): Readonly<WatermarkOptions> {
-		return this._options;
-	}
-
-	public updateAllViews(): void {
-		this._paneView.update();
-	}
-}
diff --git a/src/plugins/text-watermark/options.ts b/src/plugins/text-watermark/options.ts
new file mode 100644
index 0000000000..d35cc26d63
--- /dev/null
+++ b/src/plugins/text-watermark/options.ts
@@ -0,0 +1,93 @@
+import { defaultFontFamily } from '../../helpers/make-font';
+
+import { HorzAlign, VertAlign } from '../types';
+
+export interface TextWatermarkOptions {
+	/**
+	 * Display the watermark.
+	 *
+	 * @defaultValue `true`
+	 */
+	visible: boolean;
+
+	/**
+	 * Horizontal alignment inside the chart area.
+	 *
+	 * @defaultValue `'center'`
+	 */
+	horzAlign: HorzAlign;
+
+	/**
+	 * Vertical alignment inside the chart area.
+	 *
+	 * @defaultValue `'center'`
+	 */
+	vertAlign: VertAlign;
+
+	/**
+	 * Text to be displayed within the watermark. Each item
+	 * in the array is treated as new line.
+	 *
+	 * @defaultValue `[]`
+	 */
+	lines: TextWatermarkLineOptions[];
+}
+
+export interface TextWatermarkLineOptions {
+	/**
+	 * Watermark color.
+	 *
+	 * @defaultValue `'rgba(0, 0, 0, 0.5)'`
+	 */
+
+	color: string;
+	/**
+	 * Text of the watermark. Word wrapping is not supported.
+	 *
+	 * @defaultValue `''`
+	 */
+	text: string;
+
+	/**
+	 * Font size in pixels.
+	 *
+	 * @defaultValue `48`
+	 */
+	fontSize: number;
+
+	/**
+	 * Line height in pixels.
+	 *
+	 * @defaultValue `1.2 * fontSize`
+	 */
+	lineHeight?: number;
+
+	/**
+	 * Font family.
+	 *
+	 * @defaultValue `-apple-system, BlinkMacSystemFont, 'Trebuchet MS', Roboto, Ubuntu, sans-serif`
+	 */
+	fontFamily: string;
+
+	/**
+	 * Font style.
+	 *
+	 * @defaultValue `''`
+	 */
+	fontStyle: string;
+}
+
+export const textWatermarkOptionsDefaults: TextWatermarkOptions = {
+	visible: true,
+	horzAlign: 'center',
+	vertAlign: 'center',
+	lines: [],
+};
+
+export const textWatermarkLineOptionsDefaults: TextWatermarkLineOptions = {
+	color: 'rgba(0, 0, 0, 0.5)',
+	fontSize: 48,
+	fontFamily: defaultFontFamily,
+	fontStyle: '',
+	text: '',
+};
diff --git a/src/plugins/text-watermark/pane-renderer.ts b/src/plugins/text-watermark/pane-renderer.ts
new file mode 100644
index 0000000000..186089f5a7
--- /dev/null
+++ b/src/plugins/text-watermark/pane-renderer.ts
@@ -0,0 +1,118 @@
+import {
+	CanvasRenderingTarget2D,
+	MediaCoordinatesRenderingScope,
+} from 'fancy-canvas';
+
+import { IPrimitivePaneRenderer } from '../../model/ipane-primitive';
+
+import { TextWatermarkLineOptions, TextWatermarkOptions } from './options';
+
+export interface TextWatermarkLineRendererOptions
+	extends TextWatermarkLineOptions {
+	zoom: number;
+	vertOffset: number;
+	font: string;
+	lineHeight: number;
+}
+
+export interface TextWatermarkRendererOptions extends TextWatermarkOptions {
+	lines: TextWatermarkLineRendererOptions[];
+}
+
+export class TextWatermarkRenderer implements IPrimitivePaneRenderer {
+	private _data: TextWatermarkRendererOptions;
+	private _metricsCache: Map<string, Map<string, number>> = new Map();
+
+	public constructor(options: TextWatermarkRendererOptions) {
+		this._data = options;
+	}
+
+	public draw(target: CanvasRenderingTarget2D): void {
+		target.useMediaCoordinateSpace((scope: MediaCoordinatesRenderingScope) => {
+			const { context: ctx, mediaSize } = scope;
+
+			let textHeight = 0;
+			for (const line of this._data.lines) {
+				if (line.text.length === 0) {
+					continue;
+				}
+
+				ctx.font = line.font;
+				const textWidth = this._metrics(ctx, line.text);
+				if (textWidth > mediaSize.width) {
+					line.zoom = mediaSize.width / textWidth;
+				} else {
+					line.zoom = 1;
+				}
+
+				textHeight += line.lineHeight * line.zoom;
+			}
+
+			let vertOffset = 0;
+			switch (this._data.vertAlign) {
+				case 'top':
+					vertOffset = 0;
+					break;
+
+				case 'center':
+					vertOffset = Math.max((mediaSize.height - textHeight) / 2, 0);
+					break;
+
+				case 'bottom':
+					vertOffset = Math.max(mediaSize.height - textHeight, 0);
+					break;
+			}
+
+			for (const line of this._data.lines) {
+				ctx.save();
+				ctx.fillStyle = line.color;
+				let horzOffset = 0;
+				switch (this._data.horzAlign) {
+					case 'left':
+						ctx.textAlign = 'left';
+						horzOffset = line.lineHeight / 2;
+						break;
+
+					case 'center':
+						ctx.textAlign = 'center';
+						horzOffset = mediaSize.width / 2;
+						break;
+
+					case 'right':
+						ctx.textAlign = 'right';
+						horzOffset = mediaSize.width - 1 - line.lineHeight / 2;
+						break;
+				}
+
+				ctx.translate(horzOffset, vertOffset);
+				ctx.textBaseline = 'top';
+				ctx.font = line.font;
+				ctx.scale(line.zoom, line.zoom);
+				ctx.fillText(line.text, 0, line.vertOffset);
+				ctx.restore();
+				vertOffset += line.lineHeight * line.zoom;
+			}
+		});
+	}
+
+	private _metrics(ctx: CanvasRenderingContext2D, text: string): number {
+		const fontCache = this._fontCache(ctx.font);
+		let result = fontCache.get(text);
+		if (result === undefined) {
+			result = ctx.measureText(text).width;
+			fontCache.set(text, result);
+		}
+
+		return result;
+	}
+
+	private _fontCache(font: string): Map<string, number> {
+		let fontCache = this._metricsCache.get(font);
+		if (fontCache === undefined) {
+			fontCache = new Map();
+			this._metricsCache.set(font, fontCache);
+		}
+
+		return fontCache;
+	}
+}
diff --git a/src/plugins/text-watermark/pane-view.ts b/src/plugins/text-watermark/pane-view.ts
new file mode 100644
index 0000000000..46ec02e96d
--- /dev/null
+++ b/src/plugins/text-watermark/pane-view.ts
@@ -0,0 +1,54 @@
+import { makeFont } from '../../helpers/make-font';
+
+import {
+	IPrimitivePaneRenderer,
+	IPrimitivePaneView,
+} from '../../model/ipane-primitive';
+
+import { TextWatermarkLineOptions, TextWatermarkOptions } from './options';
+import {
+	TextWatermarkLineRendererOptions,
+	TextWatermarkRenderer,
+	TextWatermarkRendererOptions,
+} from './pane-renderer';
+
+export class TextWatermarkPaneView implements IPrimitivePaneView {
+	private _options: TextWatermarkRendererOptions;
+
+	public constructor(options: TextWatermarkOptions) {
+		this._options = buildRendererOptions(options);
+	}
+
+	public update(options: TextWatermarkOptions): void {
+		this._options = buildRendererOptions(options);
+	}
+
+	public renderer(): IPrimitivePaneRenderer {
+		return new TextWatermarkRenderer(this._options);
+	}
+}
+
+function buildRendererLineOptions(
+	lineOption: TextWatermarkLineOptions
+): TextWatermarkLineRendererOptions {
+	return {
+		...lineOption,
+		font: makeFont(
+			lineOption.fontSize,
+			lineOption.fontFamily,
+			lineOption.fontStyle
+		),
+		lineHeight: lineOption.lineHeight || lineOption.fontSize * 1.2,
+		vertOffset: 0,
+		zoom: 0,
+	};
+}
+
+function buildRendererOptions(
+	options: TextWatermarkOptions
+): TextWatermarkRendererOptions {
+	return {
+		...options,
+		lines: options.lines.map(buildRendererLineOptions),
+	};
+}
diff --git a/src/plugins/text-watermark/primitive.ts b/src/plugins/text-watermark/primitive.ts
new file mode 100644
index 0000000000..6a8e0e17c6
--- /dev/null
+++ b/src/plugins/text-watermark/primitive.ts
@@ -0,0 +1,98 @@
+import {
+	IPanePrimitive,
+	PaneAttachedParameter,
+} from '../../api/ipane-primitive-api';
+
+import { DeepPartial } from '../../helpers/strict-type-checks';
+
+import { IPanePrimitivePaneView } from '../../model/ipane-primitive';
+
+import {
+	TextWatermarkLineOptions,
+	textWatermarkLineOptionsDefaults,
+	TextWatermarkOptions,
+	textWatermarkOptionsDefaults,
+} from './options';
+import { TextWatermarkPaneView } from './pane-view';
+
+function mergeLineOptionsWithDefaults(
+	options: Partial<TextWatermarkLineOptions>
+): TextWatermarkLineOptions {
+	return {
+		...textWatermarkLineOptionsDefaults,
+		...options,
+	};
+}
+
+function mergeOptionsWithDefaults(
+	options: DeepPartial<TextWatermarkOptions>
+): TextWatermarkOptions {
+	return {
+		...textWatermarkOptionsDefaults,
+		...options,
+		lines: options.lines?.map(mergeLineOptionsWithDefaults) ?? [],
+	};
+}
+
+/**
+ * A pane primitive for rendering a text watermark.
+ *
+ * @example
+ * ```js
+ *  const textWatermark = new TextWatermark({
+ * 	  horzAlign: 'center',
+ * 	  vertAlign: 'center',
+ * 	  lines: [
+ * 	    {
+ * 	      text: 'Hello',
+ * 	      color: 'rgba(255,0,0,0.5)',
+ * 	      fontSize: 100,
+ * 	      fontStyle: 'bold',
+ * 	    },
+ * 	    {
+ * 	      text: 'This is a text watermark',
+ * 	      color: 'rgba(0,0,255,0.5)',
+ * 	      fontSize: 50,
+ * 	      fontStyle: 'italic',
+ * 	      fontFamily: 'monospace',
+ * 	    },
+ * 	  ],
+ *  });
+ * chart.panes()[0].attachPrimitive(textWatermark);
+ * ```
+ */
+export class TextWatermark implements IPanePrimitive<unknown> {
+	public requestUpdate?: () => void;
+	private _paneViews: TextWatermarkPaneView[];
+	private _options: TextWatermarkOptions;
+
+	public constructor(options: DeepPartial<TextWatermarkOptions>) {
+		this._options = mergeOptionsWithDefaults(options);
+		this._paneViews = [new TextWatermarkPaneView(this._options)];
+	}
+
+	public updateAllViews(): void {
+		this._paneViews.forEach((pw: TextWatermarkPaneView) =>
+			pw.update(this._options)
+		);
+	}
+
+	public paneViews(): readonly IPanePrimitivePaneView[] {
+		return this._paneViews;
+	}
+
+	public attached({ requestUpdate }: PaneAttachedParameter<unknown>): void {
+		this.requestUpdate = requestUpdate;
+	}
+
+	public detached(): void {
+		this.requestUpdate = undefined;
+	}
+
+	public applyOptions(options: DeepPartial<TextWatermarkOptions>): void {
+		this._options = mergeOptionsWithDefaults({ ...this._options, ...options });
+		if (this.requestUpdate) {
+			this.requestUpdate();
+		}
+	}
+}
diff --git a/src/plugins/types.ts b/src/plugins/types.ts
new file mode 100644
index 0000000000..b6f88ff426
--- /dev/null
+++ b/src/plugins/types.ts
@@ -0,0 +1,8 @@
+/**
+ * Represents a horizontal alignment.
+ */
+export type HorzAlign = 'left' | 'center' | 'right';
+/**
+ * Represents a vertical alignment.
+ */
+export type VertAlign = 'top' | 'center' | 'bottom';
diff --git a/src/renderers/watermark-renderer.ts b/src/renderers/watermark-renderer.ts
deleted file mode 100644
index 3e43a35259..0000000000
--- a/src/renderers/watermark-renderer.ts
+++ /dev/null
@@ -1,133 +0,0 @@
-import { MediaCoordinatesRenderingScope } from 'fancy-canvas';
-
-import { MediaCoordinatesPaneRenderer } from './media-coordinates-pane-renderer';
-
-export interface WatermarkRendererLineData {
-	text: string;
-	font: string;
-	lineHeight: number;
-	vertOffset: number;
-	zoom: number;
-}
-
-/**
- * Represents a horizontal alignment.
- */
-export type HorzAlign = 'left' | 'center' | 'right';
-/**
- * Represents a vertical alignment.
- */
-export type VertAlign = 'top' | 'center' | 'bottom';
-
-export interface WatermarkRendererData {
-	lines: WatermarkRendererLineData[];
-	color: string;
-	visible: boolean;
-	horzAlign: HorzAlign;
-	vertAlign: VertAlign;
-}
-
-export class WatermarkRenderer extends MediaCoordinatesPaneRenderer {
-	private readonly _data: WatermarkRendererData;
-	private _metricsCache: Map<string, Map<string, number>> = new Map();
-
-	public constructor(data: WatermarkRendererData) {
-		super();
-		this._data = data;
-	}
-
-	protected _drawImpl(renderingScope: MediaCoordinatesRenderingScope): void {}
-
-	protected override _drawBackgroundImpl(renderingScope: MediaCoordinatesRenderingScope): void {
-		if (!this._data.visible) {
-			return;
-		}
-
-		const { context: ctx, mediaSize } = renderingScope;
-
-		let textHeight = 0;
-		for (const line of this._data.lines) {
-			if (line.text.length === 0) {
-				continue;
-			}
-
-			ctx.font = line.font;
-			const textWidth = this._metrics(ctx, line.text);
-			if (textWidth > mediaSize.width) {
-				line.zoom = mediaSize.width / textWidth;
-			} else {
-				line.zoom = 1;
-			}
-
-			textHeight += line.lineHeight * line.zoom;
-		}
-
-		let vertOffset = 0;
-		switch (this._data.vertAlign) {
-			case 'top':
-				vertOffset = 0;
-				break;
-
-			case 'center':
-				vertOffset = Math.max((mediaSize.height - textHeight) / 2, 0);
-				break;
-
-			case 'bottom':
-				vertOffset = Math.max((mediaSize.height - textHeight), 0);
-				break;
-		}
-
-		ctx.fillStyle = this._data.color;
-
-		for (const line of this._data.lines) {
-			ctx.save();
-
-			let horzOffset = 0;
-			switch (this._data.horzAlign) {
-				case 'left':
-					ctx.textAlign = 'left';
-					horzOffset = line.lineHeight / 2;
-					break;
-
-				case 'center':
-					ctx.textAlign = 'center';
-					horzOffset = mediaSize.width / 2;
-					break;
-
-				case 'right':
-					ctx.textAlign = 'right';
-					horzOffset = mediaSize.width - 1 - line.lineHeight / 2;
-					break;
-			}
-
-			ctx.translate(horzOffset, vertOffset);
-			ctx.textBaseline = 'top';
-			ctx.font = line.font;
-			ctx.scale(line.zoom, line.zoom);
-			ctx.fillText(line.text, 0, line.vertOffset);
-			ctx.restore();
-			vertOffset += line.lineHeight * line.zoom;
-		}
-	}
-
-	private _metrics(ctx: CanvasRenderingContext2D, text: string): number {
-		const fontCache = this._fontCache(ctx.font);
-		let result = fontCache.get(text);
-		if (result === undefined) {
-			result = ctx.measureText(text).width;
-			fontCache.set(text, result);
-		}
-
-		return result;
-	}
-
-	private _fontCache(font: string): Map<string, number> {
-		let fontCache = this._metricsCache.get(font);
-		if (fontCache === undefined) {
-			fontCache = new Map();
-			this._metricsCache.set(font, fontCache);
-		}
-
-		return fontCache;
-	}
-}
diff --git a/src/tsconfig.composite.json b/src/tsconfig.composite.json
index 8ca4c042d1..4906c1a091 100644
--- a/src/tsconfig.composite.json
+++ b/src/tsconfig.composite.json
@@ -8,6 +8,7 @@
 		{ "path": "./tsconfig.model.json" }
 	],
 	"include": [
+		"./plugins/**/*.ts",
 		"./index.ts",
 		"./standalone.ts"
 	]
diff --git a/src/views/pane/watermark-pane-view.ts b/src/views/pane/watermark-pane-view.ts
deleted file mode 100644
index d3d94d1ddd..0000000000
--- a/src/views/pane/watermark-pane-view.ts
+++ /dev/null
@@ -1,62 +0,0 @@
-import { makeFont } from '../../helpers/make-font';
-
-import { Watermark } from '../../model/watermark';
-import { IPaneRenderer } from '../../renderers/ipane-renderer';
-import { WatermarkRenderer, WatermarkRendererData } from '../../renderers/watermark-renderer';
-
-import { IUpdatablePaneView } from './iupdatable-pane-view';
-
-export class WatermarkPaneView implements IUpdatablePaneView {
-	private _source: Watermark;
-	private _invalidated: boolean = true;
-
-	private readonly _rendererData: WatermarkRendererData = {
-		visible: false,
-		color: '',
-		lines: [],
-		vertAlign: 'center',
-		horzAlign: 'center',
-	};
-	private readonly _renderer: WatermarkRenderer = new WatermarkRenderer(this._rendererData);
-
-	public constructor(source: Watermark) {
-		this._source = source;
-	}
-
-	public update(): void {
-		this._invalidated = true;
-	}
-
-	public renderer(): IPaneRenderer {
-		if (this._invalidated) {
-			this._updateImpl();
-			this._invalidated = false;
-		}
-
-		return this._renderer;
-	}
-
-	private _updateImpl(): void {
-		const options = this._source.options();
-		const data = this._rendererData;
-		data.visible = options.visible;
-
-		if (!data.visible) {
-			return;
-		}
-
-		data.color = options.color;
-		data.horzAlign = options.horzAlign;
-		data.vertAlign = options.vertAlign;
-
-		data.lines = [
-			{
-				text: options.text,
-				font: makeFont(options.fontSize, options.fontFamily, options.fontStyle),
-				lineHeight: options.fontSize * 1.2,
-				vertOffset: 0,
-				zoom: 0,
-			},
-		];
-	}
-}
diff --git a/tests/e2e/coverage/test-cases/chart/watermark.js b/tests/e2e/coverage/test-cases/chart/watermark.js
deleted file mode 100644
index 17f5285bf0..0000000000
--- a/tests/e2e/coverage/test-cases/chart/watermark.js
+++ /dev/null
@@ -1,53 +0,0 @@
-function simpleData() {
-	return [
-		{ time: 1663740000, value: 10 },
-		{ time: 1663750000, value: 20 },
-		{ time: 1663760000, value: 30 },
-	];
-}
-
-function interactionsToPerform() {
-	return [];
-}
-
-let chart;
-
-function beforeInteractions(container) {
-	chart = LightweightCharts.createChart(container, {
-		watermark: {
-			visible: true,
-			color: 'red',
-			text: 'Watermark',
-			fontSize: 24,
-			fontStyle: 'italic',
-		},
-	});
-
-	const mainSeries = chart.addLineSeries();
-
-	mainSeries.setData(simpleData());
-
-	return Promise.resolve();
-}
-
-function afterInteractions() {
-	chart.applyOptions({
-		watermark: {
-			fontFamily: 'Roboto',
-			horzAlign: 'left',
-			vertAlign: 'top',
-		},
-	});
-
-	return new Promise(resolve => {
-		requestAnimationFrame(() => {
-			chart.applyOptions({
-				watermark: {
-					horzAlign: 'right',
-					vertAlign: 'bottom',
-				},
-			});
-		});
-		requestAnimationFrame(resolve);
-	});
-}
diff --git a/tests/e2e/coverage/test-cases/plugins/text-watermark.js b/tests/e2e/coverage/test-cases/plugins/text-watermark.js
new file mode 100644
index 0000000000..4c16bb78d5
--- /dev/null
+++ b/tests/e2e/coverage/test-cases/plugins/text-watermark.js
@@ -0,0 +1,64 @@
+function simpleData() {
+	return [
+		{ time: 1663740000, value: 10 },
+		{ time: 1663750000, value: 20 },
+		{ time: 1663760000, value: 30 },
+	];
+}
+
+function interactionsToPerform() {
+	return [];
+}
+
+let chart;
+let textWatermark;
+
+function beforeInteractions(container) {
+	chart = LightweightCharts.createChart(container);
+
+	const mainSeries = chart.addLineSeries();
+
+	mainSeries.setData(simpleData());
+
+	textWatermark = new LightweightCharts.TextWatermark({
+		horzAlign: 'center',
+		vertAlign: 'center',
+		lines: [
+			{
+				text: 'Hello',
+				color: 'rgba(255,0,0,0.5)',
+				fontSize: 100,
+				fontStyle: 'bold',
+			},
+			{
+				text: 'This is a text watermark',
+				color: 'rgba(0,0,255,0.5)',
+				fontSize: 50,
+				fontStyle: 'italic',
+				fontFamily: 'monospace',
+			},
+		],
+	});
+
+	const pane = chart.panes()[0];
+	pane.attachPrimitive(textWatermark);
+
+	return Promise.resolve();
+}
+
+function afterInteractions() {
+	textWatermark.applyOptions({
+		horzAlign: 'left',
+		vertAlign: 'top',
+	});
+
+	return new Promise(resolve => {
+		requestAnimationFrame(() => {
+			textWatermark.applyOptions({
+				horzAlign: 'right',
+				vertAlign: 'bottom',
+			});
+		});
+		requestAnimationFrame(resolve);
+	});
+}
diff --git a/tests/e2e/graphics/test-cases/api/series-markers.js b/tests/e2e/graphics/test-cases/api/series-markers.js
index b06dfe62ab..6880723234 100644
--- a/tests/e2e/graphics/test-cases/api/series-markers.js
+++ b/tests/e2e/graphics/test-cases/api/series-markers.js
@@ -40,13 +40,16 @@ function runTestCase(container) {
 	series.setMarkers(markers);
 	const seriesApiMarkers = series.markers();
 
-	chart.applyOptions({
-		watermark: {
-			color: 'red',
-			visible: true,
-			text: JSON.stringify(seriesApiMarkers[0]),
-		},
+	const textWatermark = new LightweightCharts.TextWatermark({
+		lines: [
+			{
+				text: JSON.stringify(seriesApiMarkers[0]),
+				color: 'red',
+			},
+		],
 	});
+	const pane = chart.panes()[0];
+	pane.attachPrimitive(textWatermark);
 
 	console.assert(compare(markers, seriesApiMarkers), `series.markers() should return exactly the same that was provided to series.setMarkers()\n${JSON.stringify(seriesApiMarkers)}\n${JSON.stringify(markers)}`);
 }
diff --git a/tests/e2e/graphics/test-cases/api/subscribe-crosshair-move.js b/tests/e2e/graphics/test-cases/api/subscribe-crosshair-move.js
index 0592dd6e64..9e03dda8a5 100644
--- a/tests/e2e/graphics/test-cases/api/subscribe-crosshair-move.js
+++ b/tests/e2e/graphics/test-cases/api/subscribe-crosshair-move.js
@@ -1,5 +1,7 @@
 function runTestCase(container) {
-	const chart = window.chart = LightweightCharts.createChart(container, { layout: { attributionLogo: false } });
+	const chart = (window.chart = LightweightCharts.createChart(container, {
+		layout: { attributionLogo: false },
+	}));
 	const series = chart.addAreaSeries();
 	series.setData([
 		{ time: '1990-04-24', value: 0 },
@@ -12,15 +14,29 @@ function runTestCase(container) {
 
 	chart.timeScale().fitContent();
 
+	const textWatermark = new LightweightCharts.TextWatermark({
+		lines: [
+			{
+				text: '',
+				color: 'red',
+				fontSize: 12,
+			},
+		],
+	});
+	const pane = chart.panes()[0];
+	pane.attachPrimitive(textWatermark);
+
 	chart.subscribeCrosshairMove(param => {
 		if (param.time) {
 			const seriesData = param.seriesData.get(series) || {};
-			chart.applyOptions({
-				watermark: {
-					color: 'red',
-					visible: true,
-					text: `${param.time} - ${seriesData.time}`,
-				},
+			textWatermark.applyOptions({
+				lines: [
+					{
+						text: `${param.time} - ${seriesData.time}`,
+						color: 'red',
+						fontSize: 12,
+					},
+				],
 			});
 		}
 	});
diff --git a/tests/e2e/graphics/test-cases/applying-options/watermark.js b/tests/e2e/graphics/test-cases/applying-options/watermark.js
index 4f4dacb688..eddc3b25c5 100644
--- a/tests/e2e/graphics/test-cases/applying-options/watermark.js
+++ b/tests/e2e/graphics/test-cases/applying-options/watermark.js
@@ -22,26 +22,46 @@ function generateData() {
 	return res;
 }
 
+let textWatermark;
+
 function runTestCase(container) {
-	const chart = window.chart = LightweightCharts.createChart(container, { layout: { attributionLogo: false } });
+	const chart = (window.chart = LightweightCharts.createChart(container, {
+		layout: { attributionLogo: false },
+	}));
 
 	const mainSeries = chart.addCandlestickSeries();
 
 	mainSeries.setData(generateData());
 
+	textWatermark = new LightweightCharts.TextWatermark({
+		horzAlign: 'left',
+		vertAlign: 'bottom',
+		lines: [
+			{
+				text: 'Watermark Before',
+				color: 'rgba(0, 0, 0, 0.5)',
+				fontSize: 12,
+			},
+		],
+	});
+	const pane = chart.panes()[0];
+	pane.attachPrimitive(textWatermark);
+
 	return new Promise(resolve => {
 		setTimeout(() => {
-			chart.applyOptions({
-				watermark: {
-					visible: true,
-					fontSize: 24,
-					horzAlign: 'center',
-					vertAlign: 'center',
-					color: 'rgba(171, 71, 188, 0.5)',
-					text: 'Watermark',
-					fontFamily: 'Roboto',
-					fontStyle: 'bold',
-				},
+			textWatermark.applyOptions({
+				visible: true,
+				horzAlign: 'center',
+				vertAlign: 'center',
+				lines: [
+					{
+						text: 'Watermark',
+						color: 'rgba(171, 71, 188, 0.5)',
+						fontSize: 24,
+						fontFamily: 'Roboto',
+						fontStyle: 'bold',
+					},
+				],
 			});
 			resolve();
 		}, 300);
diff --git a/tests/e2e/graphics/test-cases/initial-options/watermark.js b/tests/e2e/graphics/test-cases/initial-options/watermark.js
index 19c135d485..2cbe45b2a6 100644
--- a/tests/e2e/graphics/test-cases/initial-options/watermark.js
+++ b/tests/e2e/graphics/test-cases/initial-options/watermark.js
@@ -13,7 +13,7 @@ function generateData() {
 }
 
 function runTestCase(container) {
-	const chart = window.chart = LightweightCharts.createChart(container, {
+	const chart = (window.chart = LightweightCharts.createChart(container, {
 		watermark: {
 			visible: true,
 			color: 'red',
@@ -23,9 +23,24 @@ function runTestCase(container) {
 			fontStyle: 'italic',
 		},
 		layout: { attributionLogo: false },
-	});
+	}));
 
 	const mainSeries = chart.addAreaSeries();
-
 	mainSeries.setData(generateData());
+
+	const textWatermark = new LightweightCharts.TextWatermark({
+		visible: true,
+		lines: [
+			{
+				color: 'red',
+				text: 'TradingView Watermark Example',
+				fontSize: 24,
+				fontFamily: 'Roboto',
+				fontStyle: 'italic',
+			},
+		],
+	});
+
+	const pane = chart.panes()[0];
+	pane.attachPrimitive(textWatermark);
 }
diff --git a/website/docs/migrations/from-v4-to-v5.md b/website/docs/migrations/from-v4-to-v5.md
index 8b887a153b..e2598a53f5 100644
--- a/website/docs/migrations/from-v4-to-v5.md
+++ b/website/docs/migrations/from-v4-to-v5.md
@@ -1,10 +1,78 @@
 # From v4 to v5
 
-In this document you can find the migration guide from the previous version v4 to v5.
+In this document you can find the migration guide from the previous version v4
+to v5.
+
+## Watermarks
+
+### Overview of Changes
+
+In the new version of Lightweight Charts, the watermark feature has undergone significant changes:
+
+1. **Extraction from Core**: The watermark functionality has been extracted from the core library.
+2. **Re-implementation**: It's now re-implemented as a Pane Primitive (plugin) included within the library.
+3. **Improved Tree-shaking**: This change makes the feature more tree-shakeable, potentially reducing bundle sizes for users who don't need watermarks.
+
+If you're currently using the watermark feature, you'll need to make a few adjustments to your code.
+
+### Accessing the New TextWatermark
+
+The TextWatermark primitive is now available as follows:
+
+- **ESM builds**: Import [`TextWatermark`](/api/classes/TextWatermark.md) directly.
+- **Standalone script build**: Access via `LightweightCharts.TextWatermark`.
+
+### Changes in Options
+
+The options structure for watermarks has been revised:
+
+1. **Multiple Lines**: The plugin now supports multiple lines of text.
+2. **Text Options**: Text-related options are now defined per line within the `lines` property of the options object.
+
+### Attaching the Watermark
+
+To use the Primitive, you need to attach it to a Pane:
+
+1. **Single Pane**: If you're using only one pane, you can easily fetch it using `chart.panes()[0]`.
+2. **Multiple Panes**: For charts with multiple panes, you'll need to specify which pane to attach the watermark to.
+
+### Example: Implementing a Text Watermark
+
+Here's a comprehensive example demonstrating how to implement a text watermark in the new version:
+
+```js
+const chart = createChart(container, options);
+const mainSeries = chart.addLineSeries();
+mainSeries.setData(generateData());
+
+const textWatermark = new TextWatermark({
+    horzAlign: 'center',
+    vertAlign: 'center',
+    lines: [
+        {
+            text: 'Hello',
+            color: 'rgba(255,0,0,0.5)',
+            fontSize: 100,
+            fontStyle: 'bold',
+        },
+        {
+            text: 'This is a text watermark',
+            color: 'rgba(0,0,255,0.5)',
+            fontSize: 50,
+            fontStyle: 'italic',
+            fontFamily: 'monospace',
+        },
+    ],
+});
+
+const firstPane = chart.panes()[0];
+firstPane.attachPrimitive(textWatermark);
+```
 
 ## Plugin Typings
 
-Some of the plugin types and interfaces have been renamed due to the additional of Pane Primitives.
+Some of the plugin types and interfaces have been renamed due to the additional
+of Pane Primitives.
 
 - `ISeriesPrimitivePaneView` -> `IPrimitivePaneView`
 - `ISeriesPrimitivePaneRenderer` -> `IPrimitivePaneRenderer`
diff --git a/website/tutorials/how_to/.eslintrc.js b/website/tutorials/how_to/.eslintrc.js
index e5bae9c40c..ab4f85f00a 100644
--- a/website/tutorials/how_to/.eslintrc.js
+++ b/website/tutorials/how_to/.eslintrc.js
@@ -3,5 +3,6 @@ module.exports = {
 		document: false,
 		createChart: false,
 		createChartEx: false,
+		TextWatermark: false,
 	},
 };
diff --git a/website/tutorials/how_to/watermark-simple.js b/website/tutorials/how_to/watermark-simple.js
index a8bbd80fe7..73e09bfded 100644
--- a/website/tutorials/how_to/watermark-simple.js
+++ b/website/tutorials/how_to/watermark-simple.js
@@ -13,17 +13,22 @@ const chartOptions = {
 /** @type {import('lightweight-charts').IChartApi} */
 const chart = createChart(document.getElementById('container'), chartOptions);
 
+// remove-line
+/** @type {import('lightweight-charts').TextWatermark} */
 // highlight-start
-chart.applyOptions({
-	watermark: {
-		visible: true,
-		fontSize: 24,
-		horzAlign: 'center',
-		vertAlign: 'center',
-		color: 'rgba(171, 71, 188, 0.5)',
-		text: 'Watermark Example',
-	},
+const textWatermark = new TextWatermark({
+	horzAlign: 'center',
+	vertAlign: 'center',
+	lines: [
+		{
+			text: 'Watermark Example',
+			color: 'rgba(171, 71, 188, 0.5)',
+			fontSize: 24,
+		},
+	],
 });
+const firstPane = chart.panes()[0];
+firstPane.attachPrimitive(textWatermark);
 // highlight-end
 
 const lineSeries = chart.addAreaSeries({
diff --git a/website/tutorials/how_to/watermark.mdx b/website/tutorials/how_to/watermark.mdx
index cda9d4f57d..a3a1fbb484 100644
--- a/website/tutorials/how_to/watermark.mdx
+++ b/website/tutorials/how_to/watermark.mdx
@@ -16,31 +16,36 @@ included below.
 
 ## Short answer
 
-A simple text watermark can be configured and added by specifying the [`watermark`](/docs/api/interfaces/ChartOptionsBase#watermark) property within
-the chart options as follows:
+A simple text watermark can be configured and added by using the [`TextWatermark`](/docs/next/api/classes/TextWatermark) pane primitive exported
+from the library as follows:
 
 ```js
-chart.applyOptions({
-    watermark: {
-        visible: true,
-        fontSize: 24,
-        horzAlign: 'center',
-        vertAlign: 'center',
-        color: 'rgba(171, 71, 188, 0.5)',
-        text: 'Watermark Example',
-    },
+import { TextWatermark } from 'lightweight-charts';
+
+const textWatermark = new TextWatermark({
+    horzAlign: 'center',
+    vertAlign: 'center',
+    lines: [
+        {
+            text: 'Watermark Example',
+            color: 'rgba(171, 71, 188, 0.5)',
+            fontSize: 24,
+        },
+    ],
 });
-```
 
-The options available for the watermark are: [Watermark Options](/docs/api/interfaces/WatermarkOptions).
+const firstPane = chart.panes()[0];
+firstPane.attachPrimitive(textWatermark);
+```
 
-To have the watermark appear, you need to set `visible` to `true` and ensure that the `text` property isn't empty.
+The options available for the watermark are: [TextWatermark Options](/docs/next/api/interfaces/TextWatermarkOptions).
 
 You can see full [working examples](#examples) below.
 
 ## Resources
 
-- [Watermark Options](/docs/api/interfaces/WatermarkOptions)
+- [`TextWatermark` pane primitive](/docs/next/api/classes/TextWatermark).
+- [TextWatermark Options](/docs/next/api/interfaces/TextWatermarkOptions)
 
 ## Examples
 

From a319a719939fbb547e6926d4bf5bcd1168ac8265 Mon Sep 17 00:00:00 2001
From: Mark Silverwood <3482679+SlicedSilver@users.noreply.github.com>
Date: Tue, 30 Jul 2024 18:08:47 +0100
Subject: [PATCH 08/12] add missing pane primitives updateAllViews call

---
 src/gui/pane-widget.ts | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/src/gui/pane-widget.ts b/src/gui/pane-widget.ts
index 5eefde20f3..b3a463378f 100644
--- a/src/gui/pane-widget.ts
+++ b/src/gui/pane-widget.ts
@@ -447,6 +447,9 @@ export class PaneWidget implements IDestroyable, MouseEventHandlers {
 				source.updateAllViews();
 			}
 		}
+		for (const primitive of pane.primitives()) {
+			primitive.updateAllViews();
+		}
 	}
 
 	public getBitmapSize(): Size {

From 4e421f35fb2b4cbbdf1a9f9f9f4175e6c32b86ef Mon Sep 17 00:00:00 2001
From: Mark Silverwood <3482679+SlicedSilver@users.noreply.github.com>
Date: Tue, 30 Jul 2024 19:08:22 +0100
Subject: [PATCH 09/12] add image watermark

---
 .size-limit.js                                |   8 ++
 src/index.ts                                  |   1 +
 src/plugins/image-watermark/options.ts        |  33 +++++
 src/plugins/image-watermark/pane-renderer.ts  |  43 ++++++
 src/plugins/image-watermark/pane-view.ts      | 133 ++++++++++++++++++
 src/plugins/image-watermark/primitive.ts      | 112 +++++++++++++++
 src/plugins/text-watermark/primitive.ts       |   5 +-
 .../test-cases/initial-options/watermark.js   |   8 --
 .../test-cases/plugins/image-watermark.js     |  81 +++++++++++
 .../non-time-based-custom-series.ts           |   7 +-
 tests/type-checks/watermarks.ts               |  28 ++++
 website/docs/migrations/from-v4-to-v5.md      |   2 +
 website/tutorials/how_to/.eslintrc.js         |   1 +
 .../tutorials/how_to/watermark-advanced.js    |  27 ++--
 website/tutorials/how_to/watermark.mdx        |  54 +++----
 15 files changed, 485 insertions(+), 58 deletions(-)
 create mode 100644 src/plugins/image-watermark/options.ts
 create mode 100644 src/plugins/image-watermark/pane-renderer.ts
 create mode 100644 src/plugins/image-watermark/pane-view.ts
 create mode 100644 src/plugins/image-watermark/primitive.ts
 create mode 100644 tests/e2e/graphics/test-cases/plugins/image-watermark.js
 create mode 100644 tests/type-checks/watermarks.ts

diff --git a/.size-limit.js b/.size-limit.js
index ac4b0e917e..328ae38200 100644
--- a/.size-limit.js
+++ b/.size-limit.js
@@ -50,4 +50,12 @@ export default [
 		limit: '2.00 KB',
 		brotli: true,
 	},
+	{
+		name: 'Plugin: Image Watermark',
+		path: 'dist/lightweight-charts.production.mjs',
+		import: '{ ImageWatermark }',
+		ignore: ['fancy-canvas'],
+		limit: '2.00 KB',
+		brotli: true,
+	},
 ];
diff --git a/src/index.ts b/src/index.ts
index ac52d08eb8..14c3675742 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -25,6 +25,7 @@ export { createChart, createChartEx, defaultHorzScaleBehavior } from './api/crea
 	Plugins
 */
 export { TextWatermark } from './plugins/text-watermark/primitive';
+export { ImageWatermark } from './plugins/image-watermark/primitive';
 
 /**
  * Returns the current version as a string. For example `'3.3.0'`.
diff --git a/src/plugins/image-watermark/options.ts b/src/plugins/image-watermark/options.ts
new file mode 100644
index 0000000000..a2417bf222
--- /dev/null
+++ b/src/plugins/image-watermark/options.ts
@@ -0,0 +1,33 @@
+export interface ImageWatermarkOptions {
+	/**
+	 * Maximum width for the image watermark.
+	 *
+	 * @defaultValue undefined
+	 */
+	maxWidth?: number;
+	/**
+	 * Maximum height for the image watermark.
+	 *
+	 * @defaultValue undefined
+	 */
+	maxHeight?: number;
+	/**
+	 * Padding to maintain around the image watermark relative
+	 * to the chart pane edges.
+	 *
+	 * @defaultValue 0
+	 */
+	padding: number;
+	/**
+	 * The alpha (opacity) for the image watermark. Where `1` is fully
+	 * opaque (visible) and `0` is fully transparent.
+	 *
+	 * @defaultValue 1
+	 */
+	alpha: number;
+}
+
+export const imageWatermarkOptionsDefaults: ImageWatermarkOptions = {
+	alpha: 1,
+	padding: 0,
+};
diff --git a/src/plugins/image-watermark/pane-renderer.ts b/src/plugins/image-watermark/pane-renderer.ts
new file mode 100644
index 0000000000..e676e4fe6b
--- /dev/null
+++ b/src/plugins/image-watermark/pane-renderer.ts
@@ -0,0 +1,43 @@
+import {
+	CanvasRenderingTarget2D,
+	MediaCoordinatesRenderingScope,
+} from 'fancy-canvas';
+
+import { IPrimitivePaneRenderer } from '../../model/ipane-primitive';
+
+import { ImageWatermarkOptions } from './options';
+
+export interface Placement {
+	x: number;
+	y: number;
+	height: number;
+	width: number;
+}
+
+export interface ImageWatermarkRendererOptions extends ImageWatermarkOptions {
+	placement: Placement | null;
+	imgElement: HTMLImageElement | null;
+}
+
+export class ImageWatermarkRenderer implements IPrimitivePaneRenderer {
+	private _data: ImageWatermarkRendererOptions;
+
+	public constructor(data: ImageWatermarkRendererOptions) {
+		this._data = data;
+	}
+
+	public draw(target: CanvasRenderingTarget2D): void {
+		target.useMediaCoordinateSpace((scope: MediaCoordinatesRenderingScope) => {
+			const ctx = scope.context;
+			const pos = this._data.placement;
+			if (!pos) {
+				return;
+			}
+			if (!this._data.imgElement) {
+				throw new Error(`Image element missing.`);
+			}
+			ctx.globalAlpha = this._data.alpha ?? 1;
+			ctx.drawImage(this._data.imgElement, pos.x, pos.y, pos.width, pos.height);
+		});
+	}
+}
diff --git a/src/plugins/image-watermark/pane-view.ts b/src/plugins/image-watermark/pane-view.ts
new file mode 100644
index 0000000000..2d31b7db4c
--- /dev/null
+++ b/src/plugins/image-watermark/pane-view.ts
@@ -0,0 +1,133 @@
+import { IChartApiBase } from '../../api/ichart-api';
+
+import {
+	IPrimitivePaneRenderer,
+	IPrimitivePaneView,
+	PrimitivePaneViewZOrder,
+} from '../../model/ipane-primitive';
+
+import { ImageWatermarkOptions } from './options';
+import {
+	ImageWatermarkRenderer,
+	ImageWatermarkRendererOptions,
+	Placement,
+} from './pane-renderer';
+
+interface ImageWatermarkPaneViewState<T> {
+	image: HTMLImageElement | null;
+	imageWidth: number;
+	imageHeight: number;
+	chart: IChartApiBase<T> | null;
+}
+
+export class ImageWatermarkPaneView<T> implements IPrimitivePaneView {
+	private _options: ImageWatermarkOptions;
+	private _rendererOptions: ImageWatermarkRendererOptions;
+	private _image: HTMLImageElement | null = null;
+	private _imageWidth: number = 0; // don't draw until loaded
+	private _imageHeight: number = 0;
+	private _chart: IChartApiBase<T> | null = null;
+	private _placement: Placement | null = null;
+
+	public constructor(options: ImageWatermarkOptions) {
+		this._options = options;
+		this._rendererOptions = buildRendererOptions(
+			this._options,
+			this._placement,
+			this._image
+		);
+	}
+
+	public stateUpdate(state: ImageWatermarkPaneViewState<T>): void {
+		if (state.chart !== undefined) {
+			this._chart = state.chart;
+		}
+		if (state.imageWidth !== undefined) {
+			this._imageWidth = state.imageWidth;
+		}
+		if (state.imageHeight !== undefined) {
+			this._imageHeight = state.imageHeight;
+		}
+		if (state.image !== undefined) {
+			this._image = state.image;
+		}
+		this.update();
+	}
+
+	public optionsUpdate(options: ImageWatermarkOptions): void {
+		this._options = options;
+		this.update();
+	}
+
+	public zOrder(): PrimitivePaneViewZOrder {
+		return 'bottom' satisfies PrimitivePaneViewZOrder;
+	}
+
+	public update(): void {
+		this._placement = this._determinePlacement();
+		this._rendererOptions = buildRendererOptions(
+			this._options,
+			this._placement,
+			this._image
+		);
+	}
+
+	public renderer(): IPrimitivePaneRenderer {
+		return new ImageWatermarkRenderer(this._rendererOptions);
+	}
+
+	private _determinePlacement(): Placement | null {
+		if (!this._chart || !this._imageWidth || !this._imageHeight) {
+			return null;
+		}
+		const leftPriceScaleWidth = this._chart.priceScale('left').width();
+		const plotAreaWidth = this._chart.timeScale().width();
+		const startX = leftPriceScaleWidth;
+		const plotAreaHeight =
+			this._chart.chartElement().clientHeight -
+			this._chart.timeScale().height();
+
+		const plotCentreX = Math.round(plotAreaWidth / 2) + startX;
+		const plotCentreY = Math.round(plotAreaHeight / 2) + 0;
+
+		const padding = this._options.padding ?? 0;
+		let availableWidth = plotAreaWidth - 2 * padding;
+		let availableHeight = plotAreaHeight - 2 * padding;
+
+		if (this._options.maxHeight) {
+			availableHeight = Math.min(availableHeight, this._options.maxHeight);
+		}
+		if (this._options.maxWidth) {
+			availableWidth = Math.min(availableWidth, this._options.maxWidth);
+		}
+
+		const scaleX = availableWidth / this._imageWidth;
+		const scaleY = availableHeight / this._imageHeight;
+		const scaleToUse = Math.min(scaleX, scaleY);
+
+		const drawWidth = this._imageWidth * scaleToUse;
+		const drawHeight = this._imageHeight * scaleToUse;
+
+		const x = plotCentreX - 0.5 * drawWidth;
+		const y = plotCentreY - 0.5 * drawHeight;
+
+		return {
+			x,
+			y,
+			height: drawHeight,
+			width: drawWidth,
+		};
+	}
+}
+
+function buildRendererOptions(
+	options: ImageWatermarkOptions,
+	placement: Placement | null,
+	imgElement: HTMLImageElement | null
+): ImageWatermarkRendererOptions {
+	return {
+		...options,
+		placement,
+		imgElement,
+	};
+}
diff --git a/src/plugins/image-watermark/primitive.ts b/src/plugins/image-watermark/primitive.ts
new file mode 100644
index 0000000000..5cbdcef134
--- /dev/null
+++ b/src/plugins/image-watermark/primitive.ts
@@ -0,0 +1,112 @@
+import {
+	IPanePrimitive,
+	PaneAttachedParameter,
+} from '../../api/ipane-primitive-api';
+
+import { DeepPartial } from '../../helpers/strict-type-checks';
+
+import { Time } from '../../model/horz-scale-behavior-time/types';
+import { IPanePrimitivePaneView } from '../../model/ipane-primitive';
+
+import {
+	ImageWatermarkOptions,
+	imageWatermarkOptionsDefaults,
+} from './options';
+import { ImageWatermarkPaneView } from './pane-view';
+
+function mergeOptionsWithDefaults(
+	options: DeepPartial<ImageWatermarkOptions>
+): ImageWatermarkOptions {
+	return {
+		...imageWatermarkOptionsDefaults,
+		...options,
+	};
+}
+
+/**
+ * A pane primitive for rendering a image watermark.
+ *
+ * @example
+ * ```js
+ * import { ImageWatermark } from 'lightweight-charts';
+ *
+ * const imageWatermark = new ImageWatermark('/images/my-image.png', {
+ *   alpha: 0.5,
+ *   padding: 20,
+ * });
+ *
+ * const firstPane = chart.panes()[0];
+ * firstPane.attachPrimitive(imageWatermark);
+ * ```
+ */
+export class ImageWatermark<T = Time> implements IPanePrimitive<T> {
+	private _requestUpdate?: () => void;
+	private _paneViews: ImageWatermarkPaneView<T>[];
+	private _options: ImageWatermarkOptions;
+	private _imgElement: HTMLImageElement | null = null;
+	private _imageUrl: string;
+
+	public constructor(
+		imageUrl: string,
+		options: DeepPartial<ImageWatermarkOptions>
+	) {
+		this._imageUrl = imageUrl;
+		this._options = mergeOptionsWithDefaults(options);
+		this._paneViews = [new ImageWatermarkPaneView(this._options)];
+	}
+
+	public updateAllViews(): void {
+		this._paneViews.forEach((pw: ImageWatermarkPaneView<T>) => pw.update());
+	}
+
+	public paneViews(): readonly IPanePrimitivePaneView[] {
+		return this._paneViews;
+	}
+
+	public attached(attachedParams: PaneAttachedParameter<T>): void {
+		const { requestUpdate, chart } = attachedParams;
+		this._requestUpdate = requestUpdate;
+		this._imgElement = new Image();
+		this._imgElement.onload = () => {
+			const imageHeight = this._imgElement?.naturalHeight ?? 1;
+			const imageWidth = this._imgElement?.naturalWidth ?? 1;
+			this._paneViews.forEach((pv: ImageWatermarkPaneView<T>) =>
+				pv.stateUpdate({
+					imageHeight,
+					imageWidth,
+					image: this._imgElement,
+					chart,
+				})
+			);
+			if (this._requestUpdate) {
+				this._requestUpdate();
+			}
+		};
+		this._imgElement.src = this._imageUrl;
+	}
+
+	public detached(): void {
+		this._requestUpdate = undefined;
+		this._imgElement = null;
+	}
+
+	public applyOptions(options: DeepPartial<ImageWatermarkOptions>): void {
+		this._options = mergeOptionsWithDefaults({ ...this._options, ...options });
+		this._updateOptions();
+		if (this.requestUpdate) {
+			this.requestUpdate();
+		}
+	}
+
+	public requestUpdate(): void {
+		if (this._requestUpdate) {
+			this._requestUpdate();
+		}
+	}
+
+	private _updateOptions(): void {
+		this._paneViews.forEach((pw: ImageWatermarkPaneView<T>) =>
+			pw.optionsUpdate(this._options)
+		);
+	}
+}
diff --git a/src/plugins/text-watermark/primitive.ts b/src/plugins/text-watermark/primitive.ts
index 6a8e0e17c6..3892b5107f 100644
--- a/src/plugins/text-watermark/primitive.ts
+++ b/src/plugins/text-watermark/primitive.ts
@@ -5,6 +5,7 @@ import {
 
 import { DeepPartial } from '../../helpers/strict-type-checks';
 
+import { Time } from '../../model/horz-scale-behavior-time/types';
 import { IPanePrimitivePaneView } from '../../model/ipane-primitive';
 
 import {
@@ -61,7 +62,7 @@ function mergeOptionsWithDefaults(
  * chart.panes()[0].attachPrimitive(textWatermark);
  * ```
  */
-export class TextWatermark implements IPanePrimitive<unknown> {
+export class TextWatermark<T = Time> implements IPanePrimitive<T> {
 	public requestUpdate?: () => void;
 	private _paneViews: TextWatermarkPaneView[];
 	private _options: TextWatermarkOptions;
@@ -81,7 +82,7 @@ export class TextWatermark implements IPanePrimitive<unknown> {
 		return this._paneViews;
 	}
 
-	public attached({ requestUpdate }: PaneAttachedParameter<unknown>): void {
+	public attached({ requestUpdate }: PaneAttachedParameter<T>): void {
 		this.requestUpdate = requestUpdate;
 	}
 
diff --git a/tests/e2e/graphics/test-cases/initial-options/watermark.js b/tests/e2e/graphics/test-cases/initial-options/watermark.js
index 2cbe45b2a6..e48f1f7b7d 100644
--- a/tests/e2e/graphics/test-cases/initial-options/watermark.js
+++ b/tests/e2e/graphics/test-cases/initial-options/watermark.js
@@ -14,14 +14,6 @@ function generateData() {
 
 function runTestCase(container) {
 	const chart = (window.chart = LightweightCharts.createChart(container, {
-		watermark: {
-			visible: true,
-			color: 'red',
-			text: 'TradingView Watermark Example',
-			fontSize: 24,
-			fontFamily: 'Roboto',
-			fontStyle: 'italic',
-		},
 		layout: { attributionLogo: false },
 	}));
 
diff --git a/tests/e2e/graphics/test-cases/plugins/image-watermark.js b/tests/e2e/graphics/test-cases/plugins/image-watermark.js
new file mode 100644
index 0000000000..0e2fd8a905
--- /dev/null
+++ b/tests/e2e/graphics/test-cases/plugins/image-watermark.js
@@ -0,0 +1,81 @@
+function generateData() {
+	const res = [];
+	const time = new Date(Date.UTC(2018, 0, 1, 0, 0, 0, 0));
+	for (let i = 0; i < 500; ++i) {
+		res.push({
+			time: time.getTime() / 1000,
+			value: i,
+		});
+
+		time.setUTCDate(time.getUTCDate() + 1);
+	}
+	return res;
+}
+
+function svgToDataUrl(svgString) {
+	// Encode the SVG string
+	const encodedSvg = encodeURIComponent(svgString);
+
+	// Create the data URL
+	const dataUrl = `data:image/svg+xml;charset=utf-8,${encodedSvg}`;
+
+	return dataUrl;
+}
+
+const svgString = `<svg width="445" height="370" viewBox="0 0 445 370" fill="none" xmlns="http://www.w3.org/2000/svg">
+<mask id="mask0_101_2" style="mask-type:alpha" maskUnits="userSpaceOnUse" x="75" y="15" width="300" height="300">
+<rect x="75" y="15" width="300" height="300" rx="30" fill="#D9D9D9"/>
+</mask>
+<g mask="url(#mask0_101_2)">
+<rect x="74" y="15" width="300" height="300" fill="url(#paint0_linear_101_2)"/>
+<g style="mix-blend-mode:luminosity">
+<path d="M374 15H74V315H374V15Z" fill="white"/>
+<g style="mix-blend-mode:luminosity" opacity="0.42" filter="url(#filter0_f_101_2)">
+<path d="M224.5 282C289.946 282 343 231.408 343 169C343 106.592 289.946 56 224.5 56C159.054 56 106 106.592 106 169C106 231.408 159.054 282 224.5 282Z" fill="#434651" fill-opacity="0.5"/>
+</g>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M78 47V284.5C78.8333 293.333 85.1 311.2 103.5 312C121.9 312.8 274.833 312.333 349 312C356.333 308.667 371 299.5 371 289.5V44.5C370.333 35.8333 365 18.4 349 18C333 17.6 176.667 17.8333 100.5 18C93 19.6667 78 27.8 78 47ZM220 284.5L100.5 248C86.9 241.6 94.8333 232.667 100.5 229L211.5 174.5C251.167 186.667 332.4 211.6 340 214C347.6 216.4 344.833 225 342.5 229C322.333 242.5 278.3 271.7 263.5 280.5C248.7 289.3 228.333 286.833 220 284.5Z" fill="white"/>
+<path d="M371 289.5C371 299.5 356.333 308.667 349 312C274.833 312.333 121.9 312.8 103.5 312C85.1 311.2 78.8333 293.333 78 284.5V47C78 27.8 93 19.6667 100.5 18C176.667 17.8333 333 17.6 349 18C365 18.4 370.333 35.8333 371 44.5M371 289.5C371 279.5 371 122 371 44.5M371 289.5V44.5M100.5 248L220 284.5C228.333 286.833 248.7 289.3 263.5 280.5C278.3 271.7 322.333 242.5 342.5 229C344.833 225 347.6 216.4 340 214C332.4 211.6 251.167 186.667 211.5 174.5L100.5 229C94.8333 232.667 86.9 241.6 100.5 248Z" stroke="black"/>
+<path d="M136.384 258.757L99.7262 247.673C91.5706 245.206 90.5712 233.98 98.161 230.092L186.39 184.889C198.507 178.681 212.509 177.324 225.579 181.091L337.928 213.47C345.768 215.729 347.265 226.265 340.37 230.65L323.896 241.127M136.384 258.757L104.678 279.13M136.384 258.757L180.091 271.756M180.091 271.756L216.512 282.713C236.049 288.591 257.175 285.321 274.059 273.806L291.067 262.207M180.091 271.756L148.424 292M291.067 262.207L329.188 273.794M291.067 262.207L323.896 241.127M323.896 241.127L362 252.62" stroke="#5D606B" stroke-width="10" stroke-linecap="round"/>
+<rect x="78" y="18" width="293" height="294" rx="27" stroke="#753636" stroke-width="6"/>
+</g>
+</g>
+<path d="M334.887 70.2296C313 128.139 279.557 154.294 254.462 162.621C253.895 166.583 251.927 170.214 248.913 172.857C245.899 175.501 242.037 176.984 238.024 177.039C235.797 177.002 233.599 176.528 231.555 175.644C229.512 174.76 227.663 173.483 226.115 171.887C224.567 170.29 223.349 168.405 222.531 166.339C221.713 164.273 221.312 162.066 221.349 159.845C221.349 157.14 221.939 154.576 223 152.318L199.156 127.621C196.218 129.847 192.607 131.007 188.919 130.909C185.231 130.811 181.687 129.46 178.873 127.08L119.297 172.946C131.278 188.611 146.632 201.477 163.684 209.357L164.274 209.639H165.028C165.328 209.634 165.626 209.619 165.925 209.592C166.538 209.569 167.387 209.475 168.495 209.357C171.579 208.923 174.623 208.246 177.599 207.334C185.747 204.817 193.462 201.074 200.476 196.232C197.736 204.567 192.388 211.805 185.217 216.884L192.057 218.295C221.844 224.458 256.844 215.026 283.943 192.469C309.085 171.535 327.292 141.169 328.401 99.678C336.986 84.5775 343.425 65.3372 346.491 56.1639L346.656 55.717L339.109 59.2452C337.807 62.9571 336.391 66.6281 334.863 70.2531L334.887 70.2296Z" fill="#4994EC"/>
+<path d="M115.476 167.725C108.171 157.222 102.449 145.707 98.4953 133.548L98 132.043L98.7075 130.679C126.231 79.3323 187.316 59.6451 234.557 77.5917L236.349 78.2973L236.608 80.3437C237.472 87.8787 240.01 95.1267 244.038 101.56C246.273 104.705 248.905 107.551 251.868 110.027C244.792 94.668 246.325 82.7193 246.325 82.7193L250.712 85.5418C270.453 97.3965 297.363 100.642 320.288 86.5768C300.17 128.444 274.132 148.555 254.203 155.799C253.394 152.104 251.354 148.792 248.416 146.4C245.479 144.008 241.816 142.679 238.024 142.628C233.887 142.63 229.907 144.202 226.892 147.026L203.448 122.799C205.102 120.058 205.975 116.919 205.972 113.72C206.012 111.499 205.614 109.292 204.799 107.225C203.984 105.157 202.769 103.27 201.223 101.671C199.676 100.073 197.829 98.7932 195.787 97.9063C193.745 97.0194 191.548 96.5425 189.321 96.5027C187.094 96.5425 184.896 97.0194 182.854 97.9063C180.812 98.7932 178.965 100.073 177.419 101.671C175.873 103.27 174.657 105.157 173.843 107.225C173.028 109.292 172.629 111.499 172.67 113.72C172.67 116.754 173.425 119.6 174.769 122.07L115.453 167.725H115.476Z" fill="#4994EC"/>
+<path d="M199.651 113.72C199.651 119.6 195.005 124.352 189.321 124.352C186.541 124.302 183.895 123.155 181.963 121.162C180.03 119.169 178.97 116.492 179.014 113.72C179.014 107.84 183.637 103.065 189.321 103.065C190.699 103.09 192.059 103.385 193.323 103.933C194.587 104.482 195.73 105.274 196.687 106.263C197.644 107.253 198.397 108.421 198.901 109.7C199.406 110.98 199.652 112.346 199.627 113.72H199.651ZM248 159.845C248.083 162.572 247.08 165.221 245.211 167.213C243.341 169.205 240.758 170.378 238.024 170.477C235.285 170.385 232.696 169.214 230.821 167.221C228.947 165.228 227.941 162.576 228.024 159.845C227.935 157.11 228.938 154.452 230.813 152.454C232.688 150.456 235.281 149.282 238.024 149.19C243.236 149.19 248.024 153.659 248.024 159.845H248Z" fill="#4994EC"/>
+<defs>
+<filter id="filter0_f_101_2" x="-14" y="-64" width="477" height="466" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
+<feFlood flood-opacity="0" result="BackgroundImageFix"/>
+<feBlend mode="normal" in="SourceGraphic" in2="BackgroundImageFix" result="shape"/>
+<feGaussianBlur stdDeviation="60" result="effect1_foregroundBlur_101_2"/>
+</filter>
+<linearGradient id="paint0_linear_101_2" x1="74" y1="15" x2="372.995" y2="315.998" gradientUnits="userSpaceOnUse">
+<stop stop-color="#88E3FF"/>
+<stop offset="0.19127" stop-color="#C1C9FF"/>
+<stop offset="0.338542" stop-color="#C495FF"/>
+<stop offset="0.510417" stop-color="#E785FF"/>
+<stop offset="0.677083" stop-color="#8B7EFF"/>
+<stop offset="0.833333" stop-color="#4474FF"/>
+<stop offset="0.9999" stop-color="#1251FF"/>
+<stop offset="1" stop-color="#2962FF"/>
+</linearGradient>
+</defs>
+</svg>`;
+
+const imageDataUrl = svgToDataUrl(svgString);
+
+function runTestCase(container) {
+	const chart = (window.chart = LightweightCharts.createChart(container, {
+		layout: { attributionLogo: false },
+	}));
+
+	const mainSeries = chart.addAreaSeries();
+	mainSeries.setData(generateData());
+
+	const imageWatermark = new LightweightCharts.ImageWatermark(imageDataUrl, {
+		alpha: 0.5,
+		padding: 20,
+	});
+
+	const pane = chart.panes()[0];
+	pane.attachPrimitive(imageWatermark);
+}
diff --git a/tests/type-checks/non-time-based-custom-series.ts b/tests/type-checks/non-time-based-custom-series.ts
index 0453b9d212..a30145a361 100644
--- a/tests/type-checks/non-time-based-custom-series.ts
+++ b/tests/type-checks/non-time-based-custom-series.ts
@@ -1,4 +1,4 @@
-import { createChartEx, customSeriesDefaultOptions } from '../../src';
+import { createChartEx, customSeriesDefaultOptions, TextWatermark } from '../../src';
 import { CandlestickData, WhitespaceData } from '../../src/model/data-consumer';
 import { Time } from '../../src/model/horz-scale-behavior-time/types';
 import { CustomData, CustomSeriesPricePlotValues, ICustomSeriesPaneRenderer, ICustomSeriesPaneView, PaneRendererCustomData } from '../../src/model/icustom-series';
@@ -106,3 +106,8 @@ if (dataSet) {
 // @ts-expect-error readonly array
 // eslint-disable-next-line @typescript-eslint/no-unsafe-call
 dataSet.push({ time: 12 });
+
+const textWatermark = new TextWatermark<HorizontalScaleType>({
+	lines: [],
+});
+chart.panes()[1].attachPrimitive(textWatermark);
diff --git a/tests/type-checks/watermarks.ts b/tests/type-checks/watermarks.ts
new file mode 100644
index 0000000000..2fe644860d
--- /dev/null
+++ b/tests/type-checks/watermarks.ts
@@ -0,0 +1,28 @@
+import { createChart, ImageWatermark, TextWatermark } from '../../src';
+
+const chart = createChart('anything');
+
+const mainSeries = chart.addLineSeries();
+mainSeries.setData([]);
+
+const imageWatermark = new ImageWatermark('/debug/image.svg', {
+	alpha: 0.5,
+	padding: 50,
+	maxHeight: 400,
+	maxWidth: 400,
+});
+chart.panes()[0].attachPrimitive(imageWatermark);
+
+const textWatermark = new TextWatermark({
+	horzAlign: 'center',
+	vertAlign: 'center',
+	lines: [
+		{
+			text: 'Hello',
+			color: 'rgba(255,0,0,0.5)',
+			fontSize: 100,
+			fontStyle: 'bold',
+		},
+	],
+});
+chart.panes()[1].attachPrimitive(textWatermark);
diff --git a/website/docs/migrations/from-v4-to-v5.md b/website/docs/migrations/from-v4-to-v5.md
index e2598a53f5..573603f254 100644
--- a/website/docs/migrations/from-v4-to-v5.md
+++ b/website/docs/migrations/from-v4-to-v5.md
@@ -12,6 +12,8 @@ In the new version of Lightweight Charts, the watermark feature has undergone si
 1. **Extraction from Core**: The watermark functionality has been extracted from the core library.
 2. **Re-implementation**: It's now re-implemented as a Pane Primitive (plugin) included within the library.
 3. **Improved Tree-shaking**: This change makes the feature more tree-shakeable, potentially reducing bundle sizes for users who don't need watermarks.
+4. **Added an Image Watermark Primitive**: In addition to the usual text based watermark, there is now
+an image watermark feature provided by the [`ImageWatermark`](/api/classes/ImageWatermark.md) primitive.
 
 If you're currently using the watermark feature, you'll need to make a few adjustments to your code.
 
diff --git a/website/tutorials/how_to/.eslintrc.js b/website/tutorials/how_to/.eslintrc.js
index ab4f85f00a..379db16386 100644
--- a/website/tutorials/how_to/.eslintrc.js
+++ b/website/tutorials/how_to/.eslintrc.js
@@ -4,5 +4,6 @@ module.exports = {
 		createChart: false,
 		createChartEx: false,
 		TextWatermark: false,
+		ImageWatermark: false,
 	},
 };
diff --git a/website/tutorials/how_to/watermark-advanced.js b/website/tutorials/how_to/watermark-advanced.js
index b709d35973..5ab395a50e 100644
--- a/website/tutorials/how_to/watermark-advanced.js
+++ b/website/tutorials/how_to/watermark-advanced.js
@@ -1,14 +1,12 @@
 // remove-start
-// Lightweight Charts™ Example: Watermark Advanced
+// Lightweight Charts™ Example: Image Watermark
 // https://tradingview.github.io/lightweight-charts/tutorials/how_to/watermark
 
 // remove-end
 const chartOptions = {
 	layout: {
 		textColor: CHART_TEXT_COLOR,
-		// set chart background color to transparent so we can see the elements below
-		// highlight-next-line
-		background: { type: 'solid', color: 'transparent' },
+		background: { type: 'solid', color: CHART_BACKGROUND_COLOR },
 	},
 };
 // remove-line
@@ -16,18 +14,15 @@ const chartOptions = {
 const chart = createChart(document.getElementById('container'), chartOptions);
 
 // highlight-start
-const container = document.getElementById('container');
-const background = document.createElement('div');
-// place below the chart
-background.style.zIndex = -1;
-background.style.position = 'absolute';
-// set size and position to match container
-background.style.inset = '0px';
-background.style.backgroundImage = `url("data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyOTIiIGhlaWdodD0iMTI4IiB2aWV3Qm94PSIwIDAgMjkyIDEyOCI+PHBhdGggZmlsbC1ydWxlPSJldmVub2RkIiBkPSJtMTgyLjkzIDcuNi42My0uMzdhNjQuMSA2NC4xIDAgMCAwIDIuNDMtNS4zMWw0Ljc3LTEuMzlhNjQuNjggNjQuNjggMCAwIDEtNC43MiAxMC41NGMuMzggMTAuNDUtMy45MyAyMS4xNS0xMS4xIDI5LjM3LTExLjY2IDEzLjQxLTI2Ljk4IDE1Ljk3LTQzLjU3IDEzLjc4bDEuMDctLjk4YTIxLjEgMjEuMSAwIDAgMCAzLjcyLTQuMDUgNDguMzcgNDguMzcgMCAwIDEtMTEuMDQgMi44NGMtMTAuNjUtNS41NC0yMS42NC0xNC45NC0yNC4yNy0yNy4yNyA5LjE5LTE3IDI4Ljk1LTI0LjAxIDQ3LjM5LTE5Ljk0YTIyLjU3IDIyLjU3IDAgMCAwIDUuODYgOS4wMmMtLjEyLTEuOTItLjEtMy44NC0uMS01Ljc2bC4wMS0xLjc4YzQuOCAyLjk2IDkuNjYgNS44NSAxNS41MiA1LjcgNC4wOC0uMSA4LjQtMS41MiAxMy40LTQuNFptLTIyLjU1IDIzLjI4YTguNDggOC40OCAwIDAgMC0xMi40NS0uMzNsLTcuOS03LjI2QTguNiA4LjYgMCAwIDAgMTMyIDEyYy02LjE0IDAtMTAuMjUgNi42My03LjcgMTIuMDlsLTEzLjAyIDEyLjE5Yy00LjEtNC45Ny01LjY4LTkuMy02LjE3LTEwLjk0IDguMzYtMTMuNzIgMjQuNDYtMjAuMTggNDAuMTUtMTcuMDcgMi45MyA2LjkgOC4zOCAxMC43MiAxNC43NyAxMy45NmwtLjMzLTEuMTRjLS43NC0yLjU2LTEuNDctNS4xLTEuNjItNy43OCA3LjA1IDMuNDUgMTQuNiAzLjM1IDIxLjc2LjMxLTQuNzYgNy4yNy0xMS4xMyAxNC4yMi0xOS40NiAxNy4yNlptLTIyLjU2LTQuMTkgOC4wMyA3LjM4QTguNiA4LjYgMCAwIDAgMTU0IDQ1YTguNiA4LjYgMCAwIDAgOC4yNS0xMC41NWM3Ljk5LTMuMDggMTQuMzctOS4zOCAxOS4yOC0xNi4yMy0zLjQ3IDE5LjQ3LTIxLjk2IDM0LjYxLTQxLjkgMzIuOTggMS43Ny0yLjg0IDIuNDktNi4wNiAzLjIxLTkuMjhsLjM1LTEuNTZjLTUuNDcgMy43Ny0xMC42NyA2LjM4LTE3LjM3IDcuNTJhNDkuOSA0OS45IDAgMCAxLTExLjg1LTguNjVsMTIuODMtMTJhOC41OCA4LjU4IDAgMCAwIDExLjAyLS41NFpNMTMyIDE2YTQuNSA0LjUgMCAxIDAgMCA5IDQuNSA0LjUgMCAwIDAgMC05Wm0xNy41IDIwLjVhNC41IDQuNSAwIDEgMSA5IDAgNC41IDQuNSAwIDAgMS05IDBaTTIxLjYzIDcxLjhhMi4zMyAyLjMzIDAgMCAxIDIuMzMgMi4zNCAyLjM0IDIuMzQgMCAwIDEtMi4zMyAyLjM3IDIuMzggMi4zOCAwIDAgMS0yLjM3LTIuMzcgMi4zOCAyLjM4IDAgMCAxIDIuMzctMi4zM1ptMS43NiA4LjJ2MTZoLTMuNTJWODBoMy41MlptLTYuNDYgMTZIMi43OFY3My4yOGgzLjc1djE5LjE0aDEwLjRWOTZabTI2LjM5LTEuMDlWODBIMzkuOHYyLjE0YTYuMjYgNi4yNiAwIDAgMC01LjEyLTIuNDZjLTQuMzIgMC03LjY4IDMuNTgtNy42OCA4LjEgMCA0LjU0IDMuMzYgOC4xMiA3LjY4IDguMTIgMi4yIDAgNC4xNi0xLjA4IDUuMTItMi41djEuNDhjMCAzLjIzLTIuMTggNS00LjgzIDVhNy4wMyA3LjAzIDAgMCAxLTUuMzItMi4zNGwtMi4xNCAyLjUyYzEuNTcgMS43NiA0LjM1IDIuOTUgNy40OSAyLjk1IDQuNzMgMCA4LjMyLTIuNTMgOC4zMi04LjFabS0xMi43Ny03LjEzYTQuNyA0LjcgMCAwIDEgNC43Ny00LjkgNC43IDQuNyAwIDAgMSA0Ljc3IDQuOSA0LjcgNC43IDAgMCAxLTQuNzcgNC45IDQuNyA0LjcgMCAwIDEtNC43Ny00LjlaTTUxLjU4IDk2aC0zLjUyVjcyaDMuNTJ2MTAuMThjLjk2LTEuNiAyLjc4LTIuNSA0Ljg2LTIuNSAzLjcxIDAgNi4xMSAyLjYyIDYuMTEgNi42OVY5NmgtMy41MnYtOS4wNmMwLTIuNTItMS4yOC00LjA2LTMuMzMtNC4wNi0yLjMzIDAtNC4xMiAxLjgyLTQuMTIgNS4yNVY5NlptMjQuODYtLjJ2LTMuMTNjLS41Mi4yLTEuMjIuMzItMS45LjMyLTEuODIgMC0yLjY4LS43My0yLjY4LTIuNzJ2LTcuMTNoNC41OFY4MGgtNC41OHYtNC40NWgtMy41MlY4MGgtMy4zM3YzLjE0aDMuMzN2Ny43YzAgMy42MiAyLjQgNS4zMiA1LjQ3IDUuMzIgMS4wOSAwIDEuOTItLjEzIDIuNjMtLjM1Wm0yMC4zLjJIOTMuNGwtMy41Mi0xMC4zN0w4Ni4zOSA5NmgtMy4zMmwtNS4zOC0xNmgzLjcybDMuNDUgMTEgMy42OC0xMWgyLjY5bDMuNjUgMTEgMy40OS0xMWgzLjc0bC01LjM4IDE2Wm02Ljc2LThjMCA0Ljg2IDMuNDkgOC4zMiA4LjM1IDguMzIgMy4zNiAwIDUuODYtMS40NCA3LjMtMy43MWwtMi43LTEuOTJhNS4wMyA1LjAzIDAgMCAxLTQuNTcgMi40M2MtMi42NSAwLTQuNzctMS43My00LjkzLTQuMzVoMTIuNThjLjAzLS41MS4wMy0uOC4wMy0xLjE1IDAtNS4xNi0zLjUyLTcuOTQtNy43MS03Ljk0QTguMTIgOC4xMiAwIDAgMCAxMDMuNSA4OFptOC4yMi01LjM0YzIuMDUgMCAzLjkgMS4yNCA0LjI5IDMuNTVoLTguOWMuNDgtMi4zNyAyLjU2LTMuNTUgNC42MS0zLjU1Wm0xMy4yMi0xMC44NWEyLjMzIDIuMzMgMCAwIDEgMi4zNCAyLjMzIDIuMzQgMi4zNCAwIDAgMS0yLjM0IDIuMzcgMi4zOCAyLjM4IDAgMCAxLTIuMzctMi4zNyAyLjM4IDIuMzggMCAwIDEgMi4zNy0yLjMzWm0yMS43IDIzLjFWODBoLTMuNTN2Mi4xNGE2LjI2IDYuMjYgMCAwIDAtNS4xMi0yLjQ2Yy00LjMyIDAtNy42OCAzLjU4LTcuNjggOC4xIDAgNC41NCAzLjM2IDguMTIgNy42OCA4LjEyIDIuMiAwIDQuMTYtMS4wOCA1LjEyLTIuNXYxLjQ4YzAgMy4yMy0yLjE4IDUtNC44MyA1YTcuMDMgNy4wMyAwIDAgMS01LjMxLTIuMzRsLTIuMTUgMi41MmMxLjU3IDEuNzYgNC4zNiAyLjk1IDcuNSAyLjk1IDQuNzMgMCA4LjMxLTIuNTMgOC4zMS04LjFaTTEyNi43IDk2aC0zLjUyVjgwaDMuNTJ2MTZabTcuMTYtOC4yMmE0LjcgNC43IDAgMCAxIDQuNzctNC45IDQuNyA0LjcgMCAwIDEgNC43NyA0LjkgNC43IDQuNyAwIDAgMS00Ljc3IDQuOSA0LjcgNC43IDAgMCAxLTQuNzctNC45Wk0xNTQuOSA5NmgtMy41MlY3MmgzLjUydjEwLjE4Yy45Ni0xLjYgMi43OC0yLjUgNC44Ni0yLjUgMy43MSAwIDYuMTEgMi42MiA2LjExIDYuNjlWOTZoLTMuNTJ2LTkuMDZjMC0yLjUyLTEuMjgtNC4wNi0zLjMyLTQuMDYtMi4zNCAwLTQuMTMgMS44Mi00LjEzIDUuMjVWOTZabTI0Ljg2LS4ydi0zLjEzYy0uNTEuMi0xLjIyLjMyLTEuODkuMzItMS44MiAwLTIuNjktLjczLTIuNjktMi43MnYtNy4xM2g0LjU4VjgwaC00LjU4di00LjQ1aC0zLjUyVjgwaC0zLjMzdjMuMTRoMy4zM3Y3LjdjMCAzLjYyIDIuNCA1LjMyIDUuNDcgNS4zMiAxLjEgMCAxLjkyLS4xMyAyLjYzLS4zNVptMjEuNTkuNThhMTEuNjcgMTEuNjcgMCAwIDEtMTEuNzUtMTEuNzRjMC02LjU2IDUuMjItMTEuNzQgMTEuNzUtMTEuNzQgNC40NSAwIDguMjIgMi4yNyAxMC4yNCA1Ljc2bC0zLjIzIDEuODVhNy45NCA3Ljk0IDAgMCAwLTcuMDEtNCA3Ljk2IDcuOTYgMCAwIDAtNy45NyA4LjEzIDcuOTYgNy45NiAwIDAgMCA3Ljk3IDguMTMgNy45NCA3Ljk0IDAgMCAwIDctNGwzLjI0IDEuODVhMTEuNjYgMTEuNjYgMCAwIDEtMTAuMjQgNS43NlptMTMuNC0uMzhoMy41MnYtNy44N2MwLTMuNDMgMS44LTUuMjUgNC4xMy01LjI1IDIuMDUgMCAzLjMzIDEuNTQgMy4zMyA0LjA2Vjk2aDMuNTJ2LTkuNjNjMC00LjA3LTIuNC02LjY5LTYuMTEtNi42OS0yLjA4IDAtMy45LjktNC44NyAyLjVWNzJoLTMuNTJ2MjRabTI1LjU2LjMyYy00LjM4IDAtNy43LTMuNzQtNy43LTguMzJzMy4zMi04LjMyIDcuNy04LjMyYzIuMyAwIDQuMjMgMS4xOCA1LjEyIDIuNDZWODBoMy41MnYxNmgtMy41MnYtMi4xNGE2LjM4IDYuMzggMCAwIDEtNS4xMiAyLjQ2Wm0uNjQtMy4yYzIuODUgMCA0Ljc3LTIuMjQgNC43Ny01LjEycy0xLjkyLTUuMTItNC43Ny01LjEyYy0yLjg0IDAtNC43NiAyLjI0LTQuNzYgNS4xMnMxLjkxIDUuMTIgNC43NiA1LjEyWk0yNTMuNzEgOTZoMy41MnYtNy44YzAtMy4yIDEuODMtNC45IDMuODQtNC45LjY0IDAgMS4xNS4xIDEuNzYuMjh2LTMuNjFjLS40OC0uMS0uOTMtLjEzLTEuMzctLjEzYTQuNSA0LjUgMCAwIDAtNC4yMyAzVjgwaC0zLjUydjE2Wm0yMS43My0zLjMzdjMuMTRjLS43LjIyLTEuNTQuMzUtMi42My4zNS0zLjA3IDAtNS40Ny0xLjctNS40Ny01LjMxdi03LjcxaC0zLjMzVjgwaDMuMzN2LTQuNDVoMy41MlY4MGg0LjU4djMuMTRoLTQuNTh2Ny4xM2MwIDEuOTkuODYgMi43MiAyLjY5IDIuNzIuNjcgMCAxLjM3LS4xMyAxLjg5LS4zMlptMTQuMjEtMS4zMWMwLTIuNjItMS42Ni00LjAzLTQuNDgtNC44NmwtMS42My0uNDhjLTEuNTctLjQ1LTEuOTItMS4xMi0xLjkyLTEuOSAwLS45NSAxLjA5LTEuNSAyLjE1LTEuNSAxLjMgMCAyLjMzLjY0IDMuMDQgMS42NGwyLjQzLTEuODZjLTEuMTItMS43Ni0zLjAxLTIuNzItNS40MS0yLjcyLTMuMiAwLTUuNyAxLjczLTUuNzMgNC41OC0uMDMgMi4zNiAxLjQxIDQuMTIgNC4yIDQuOWwxLjQuMzhjMS45Mi41NyAyLjQ3IDEuMTIgMi40NyAyLjA0IDAgMS4xMi0xLjA2IDEuNy0yLjMgMS43LTEuNjQgMC0zLjItLjgtMy44NS0yLjJsLTIuNTkgMS44NWMxLjE1IDIuMjcgMy41OCAzLjM5IDYuNDMgMy4zOSAzLjMgMCA1LjgtMS44OSA1LjgtNC45NlptLTE0My4zOCAyMS40YzAgLjQ2LS4zNy44NC0uODMuODRhLjg2Ljg2IDAgMCAxLS44Ny0uODVjMC0uNDYuMzktLjg1Ljg3LS44NS40NiAwIC44My4zOS44My44NVptLS4yOSAxMS4yNGgtMS4xMnYtOGgxLjEydjhabS01Mi4wMi4xNmE0LjA0IDQuMDQgMCAwIDAgMy45OC00LjE2IDQuMDQgNC4wNCAwIDAgMC0zLjk4LTQuMTZjLTEuMjQgMC0yLjM5LjY0LTIuOTYgMS41VjExMmgtMS4xMnYxMkg5MXYtMS4zNGMuNTcuODYgMS43MiAxLjUgMi45NiAxLjVabS0uMTItMS4wNGMtMS43NCAwLTIuOTQtMS40LTIuOTQtMy4xMiAwLTEuNzMgMS4yLTMuMTIgMi45NC0zLjEyIDEuNzUgMCAyLjk1IDEuNCAyLjk1IDMuMTIgMCAxLjczLTEuMiAzLjEyLTIuOTUgMy4xMlptNy45IDQuMjIgNS4zLTExLjM0aC0xLjI2bC0yLjkzIDYuMzUtMi45My02LjM1aC0xLjI0bDMuNTUgNy42LTEuNzYgMy43NGgxLjI2Wk0xMTUuMyAxMjRoLTEuMnYtMTAuMmgtMy42OHYtMS4xNmg4LjU2djEuMTVoLTMuNjhWMTI0Wm0zLjgyIDBoMS4xMnYtNC4wMmMwLTIuMDQgMS4yMy0yLjk0IDIuMjItMi45NC4yNCAwIC40NS4wMy42Ny4xMXYtMS4xN2EyLjQ0IDIuNDQgMCAwIDAtMi45IDEuNjZWMTE2aC0xLjExdjhabTExLjcyLTEuMzRhMy42NCAzLjY0IDAgMCAxLTIuOTYgMS41IDQuMDQgNC4wNCAwIDAgMS0zLjk4LTQuMTYgNC4wNCA0LjA0IDAgMCAxIDMuOTgtNC4xNmMxLjIzIDAgMi4zOS42NCAyLjk2IDEuNVYxMTZoMS4xMnY4aC0xLjEydi0xLjM0Wm0tNS44LTIuNjZjMCAxLjczIDEuMiAzLjEyIDIuOTUgMy4xMiAxLjc1IDAgMi45NS0xLjQgMi45NS0zLjEyIDAtMS43My0xLjItMy4xMi0yLjk1LTMuMTItMS43NCAwLTIuOTQgMS40LTIuOTQgMy4xMlptMTIuOTggNC4xNmMxLjIzIDAgMi4zOS0uNjQgMi45Ni0xLjVWMTI0aDEuMTJ2LTEySDE0MXY1LjM0YTMuNjQgMy42NCAwIDAgMC0yLjk2LTEuNSA0LjA0IDQuMDQgMCAwIDAtMy45OCA0LjE2IDQuMDQgNC4wNCAwIDAgMCAzLjk4IDQuMTZabS4xMS0xLjA0Yy0xLjc0IDAtMi45NC0xLjQtMi45NC0zLjEyIDAtMS43MyAxLjItMy4xMiAyLjk0LTMuMTIgMS43NSAwIDIuOTUgMS40IDIuOTUgMy4xMiAwIDEuNzMtMS4yIDMuMTItMi45NSAzLjEyWm0xMC42Ljg4aDEuMTF2LTMuOThjMC0xLjk5IDEuMS0zLjE0IDIuNS0zLjE0IDEuMTkgMCAyLjAyLjg2IDIuMDIgMi4yN1YxMjRoMS4xMnYtNWMwLTEuOTYtMS4yNy0zLjE2LTMuMDEtMy4xNi0xLjA0IDAtMi4wNS40NS0yLjYzIDEuNVYxMTZoLTEuMTF2OFptMTYuNzEtLjQyYzAgMi42MS0xLjcyIDMuOTItMy45NSAzLjkyLTEuODQgMC0zLjE3LS44My0zLjc3LTEuNzRsLjg4LS43NWEzLjQgMy40IDAgMCAwIDIuOSAxLjQ1YzEuMzcgMCAyLjgyLS44MyAyLjgyLTIuOTR2LTEuMDJjLS41Ny44Ni0xLjcgMS41LTIuOTIgMS41YTMuOTQgMy45NCAwIDAgMS0zLjk2LTQuMDggMy45NCAzLjk0IDAgMCAxIDMuOTYtNC4wOGMxLjIzIDAgMi4zNS42NCAyLjkyIDEuNVYxMTZoMS4xMnY3LjU4Wm0tNi44NC0zLjY2YzAgMS43MyAxLjE2IDMuMDQgMi45IDMuMDQgMS43NSAwIDIuOTItMS4zMSAyLjkyLTMuMDRzLTEuMTctMy4wNC0yLjkxLTMuMDRjLTEuNzUgMC0yLjkxIDEuMzEtMi45MSAzLjA0Wm0xMy41NSA0LjA4IDQuODgtMTEuMzZoLTEuMzVsLTQuMDMgOS4zOC00LjAzLTkuMzhoLTEuMzZsNC45IDExLjM2aC45OVptNy44NC0xMS4yNWMwIC40Ny0uMzcuODUtLjgzLjg1YS44Ni44NiAwIDAgMS0uODYtLjg1YzAtLjQ2LjM4LS44NS44Ni0uODUuNDcgMCAuODMuMzkuODMuODVabS0uMjggMTEuMjVoLTEuMTN2LThoMS4xM3Y4Wm02LjIuMTZhMy45IDMuOSAwIDAgMCAzLjU2LTEuOTVsLS45MS0uNmEyLjc4IDIuNzggMCAwIDEtMi42NCAxLjUxIDIuODcgMi44NyAwIDAgMS0yLjk2LTIuOTNoNi43NXYtLjNjLS4wMi0yLjU2LTEuNjgtNC4wNS0zLjc2LTQuMDVhNC4wNSA0LjA1IDAgMCAwLTQuMTUgNC4xNmMwIDIuMyAxLjYgNC4xNiA0LjEyIDQuMTZabS0uMDEtNy4yOGMxLjM0IDAgMi40NS44OCAyLjY0IDIuMzJoLTUuNDlhMi44NCAyLjg0IDAgMCAxIDIuODUtMi4zMlptMTMuNTUgNy4xMmgtLjkzbC0yLjEtNi4xLTIuMTQgNi4xaC0uOTJsLTIuNzQtOGgxLjE1bDIuMDggNi4wOCAyLjExLTYuMDhoLjg3bDIuMTEgNi4wOCAyLjA4LTYuMDhoMS4xN2wtMi43NCA4WiIgZmlsbD0iY3VycmVudENvbG9yIj48L3BhdGg+PC9zdmc+")`;
-background.style.backgroundRepeat = 'no-repeat';
-background.style.backgroundPosition = 'center';
-background.style.opacity = '0.5';
-container.appendChild(background);
+// imageDataUrl would usually be an url like '/images/my-image.png'
+const imageDataUrl = 'data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyOTIiIGhlaWdodD0iMTI4IiB2aWV3Qm94PSIwIDAgMjkyIDEyOCI+PHBhdGggZmlsbC1ydWxlPSJldmVub2RkIiBkPSJtMTgyLjkzIDcuNi42My0uMzdhNjQuMSA2NC4xIDAgMCAwIDIuNDMtNS4zMWw0Ljc3LTEuMzlhNjQuNjggNjQuNjggMCAwIDEtNC43MiAxMC41NGMuMzggMTAuNDUtMy45MyAyMS4xNS0xMS4xIDI5LjM3LTExLjY2IDEzLjQxLTI2Ljk4IDE1Ljk3LTQzLjU3IDEzLjc4bDEuMDctLjk4YTIxLjEgMjEuMSAwIDAgMCAzLjcyLTQuMDUgNDguMzcgNDguMzcgMCAwIDEtMTEuMDQgMi44NGMtMTAuNjUtNS41NC0yMS42NC0xNC45NC0yNC4yNy0yNy4yNyA5LjE5LTE3IDI4Ljk1LTI0LjAxIDQ3LjM5LTE5Ljk0YTIyLjU3IDIyLjU3IDAgMCAwIDUuODYgOS4wMmMtLjEyLTEuOTItLjEtMy44NC0uMS01Ljc2bC4wMS0xLjc4YzQuOCAyLjk2IDkuNjYgNS44NSAxNS41MiA1LjcgNC4wOC0uMSA4LjQtMS41MiAxMy40LTQuNFptLTIyLjU1IDIzLjI4YTguNDggOC40OCAwIDAgMC0xMi40NS0uMzNsLTcuOS03LjI2QTguNiA4LjYgMCAwIDAgMTMyIDEyYy02LjE0IDAtMTAuMjUgNi42My03LjcgMTIuMDlsLTEzLjAyIDEyLjE5Yy00LjEtNC45Ny01LjY4LTkuMy02LjE3LTEwLjk0IDguMzYtMTMuNzIgMjQuNDYtMjAuMTggNDAuMTUtMTcuMDcgMi45MyA2LjkgOC4zOCAxMC43MiAxNC43NyAxMy45NmwtLjMzLTEuMTRjLS43NC0yLjU2LTEuNDctNS4xLTEuNjItNy43OCA3LjA1IDMuNDUgMTQuNiAzLjM1IDIxLjc2LjMxLTQuNzYgNy4yNy0xMS4xMyAxNC4yMi0xOS40NiAxNy4yNlptLTIyLjU2LTQuMTkgOC4wMyA3LjM4QTguNiA4LjYgMCAwIDAgMTU0IDQ1YTguNiA4LjYgMCAwIDAgOC4yNS0xMC41NWM3Ljk5LTMuMDggMTQuMzctOS4zOCAxOS4yOC0xNi4yMy0zLjQ3IDE5LjQ3LTIxLjk2IDM0LjYxLTQxLjkgMzIuOTggMS43Ny0yLjg0IDIuNDktNi4wNiAzLjIxLTkuMjhsLjM1LTEuNTZjLTUuNDcgMy43Ny0xMC42NyA2LjM4LTE3LjM3IDcuNTJhNDkuOSA0OS45IDAgMCAxLTExLjg1LTguNjVsMTIuODMtMTJhOC41OCA4LjU4IDAgMCAwIDExLjAyLS41NFpNMTMyIDE2YTQuNSA0LjUgMCAxIDAgMCA5IDQuNSA0LjUgMCAwIDAgMC05Wm0xNy41IDIwLjVhNC41IDQuNSAwIDEgMSA5IDAgNC41IDQuNSAwIDAgMS05IDBaTTIxLjYzIDcxLjhhMi4zMyAyLjMzIDAgMCAxIDIuMzMgMi4zNCAyLjM0IDIuMzQgMCAwIDEtMi4zMyAyLjM3IDIuMzggMi4zOCAwIDAgMS0yLjM3LTIuMzcgMi4zOCAyLjM4IDAgMCAxIDIuMzctMi4zM1ptMS43NiA4LjJ2MTZoLTMuNTJWODBoMy41MlptLTYuNDYgMTZIMi43OFY3My4yOGgzLjc1djE5LjE0aDEwLjRWOTZabTI2LjM5LTEuMDlWODBIMzkuOHYyLjE0YTYuMjYgNi4yNiAwIDAgMC01LjEyLTIuNDZjLTQuMzIgMC03LjY4IDMuNTgtNy42OCA4LjEgMCA0LjU0IDMuMzYgOC4xMiA3LjY4IDguMTIgMi4yIDAgNC4xNi0xLjA4IDUuMTItMi41djEuNDhjMCAzLjIzLTIuMTggNS00LjgzIDVhNy4wMyA3LjAzIDAgMCAxLTUuMzItMi4zNGwtMi4xNCAyLjUyYzEuNTcgMS43NiA0LjM1IDIuOTUgNy40OSAyLjk1IDQuNzMgMCA4LjMyLTIuNTMgOC4zMi04LjFabS0xMi43Ny03LjEzYTQuNyA0LjcgMCAwIDEgNC43Ny00LjkgNC43IDQuNyAwIDAgMSA0Ljc3IDQuOSA0LjcgNC43IDAgMCAxLTQuNzcgNC45IDQuNyA0LjcgMCAwIDEtNC43Ny00LjlaTTUxLjU4IDk2aC0zLjUyVjcyaDMuNTJ2MTAuMThjLjk2LTEuNiAyLjc4LTIuNSA0Ljg2LTIuNSAzLjcxIDAgNi4xMSAyLjYyIDYuMTEgNi42OVY5NmgtMy41MnYtOS4wNmMwLTIuNTItMS4yOC00LjA2LTMuMzMtNC4wNi0yLjMzIDAtNC4xMiAxLjgyLTQuMTIgNS4yNVY5NlptMjQuODYtLjJ2LTMuMTNjLS41Mi4yLTEuMjIuMzItMS45LjMyLTEuODIgMC0yLjY4LS43My0yLjY4LTIuNzJ2LTcuMTNoNC41OFY4MGgtNC41OHYtNC40NWgtMy41MlY4MGgtMy4zM3YzLjE0aDMuMzN2Ny43YzAgMy42MiAyLjQgNS4zMiA1LjQ3IDUuMzIgMS4wOSAwIDEuOTItLjEzIDIuNjMtLjM1Wm0yMC4zLjJIOTMuNGwtMy41Mi0xMC4zN0w4Ni4zOSA5NmgtMy4zMmwtNS4zOC0xNmgzLjcybDMuNDUgMTEgMy42OC0xMWgyLjY5bDMuNjUgMTEgMy40OS0xMWgzLjc0bC01LjM4IDE2Wm02Ljc2LThjMCA0Ljg2IDMuNDkgOC4zMiA4LjM1IDguMzIgMy4zNiAwIDUuODYtMS40NCA3LjMtMy43MWwtMi43LTEuOTJhNS4wMyA1LjAzIDAgMCAxLTQuNTcgMi40M2MtMi42NSAwLTQuNzctMS43My00LjkzLTQuMzVoMTIuNThjLjAzLS41MS4wMy0uOC4wMy0xLjE1IDAtNS4xNi0zLjUyLTcuOTQtNy43MS03Ljk0QTguMTIgOC4xMiAwIDAgMCAxMDMuNSA4OFptOC4yMi01LjM0YzIuMDUgMCAzLjkgMS4yNCA0LjI5IDMuNTVoLTguOWMuNDgtMi4zNyAyLjU2LTMuNTUgNC42MS0zLjU1Wm0xMy4yMi0xMC44NWEyLjMzIDIuMzMgMCAwIDEgMi4zNCAyLjMzIDIuMzQgMi4zNCAwIDAgMS0yLjM0IDIuMzcgMi4zOCAyLjM4IDAgMCAxLTIuMzctMi4zNyAyLjM4IDIuMzggMCAwIDEgMi4zNy0yLjMzWm0yMS43IDIzLjFWODBoLTMuNTN2Mi4xNGE2LjI2IDYuMjYgMCAwIDAtNS4xMi0yLjQ2Yy00LjMyIDAtNy42OCAzLjU4LTcuNjggOC4xIDAgNC41NCAzLjM2IDguMTIgNy42OCA4LjEyIDIuMiAwIDQuMTYtMS4wOCA1LjEyLTIuNXYxLjQ4YzAgMy4yMy0yLjE4IDUtNC44MyA1YTcuMDMgNy4wMyAwIDAgMS01LjMxLTIuMzRsLTIuMTUgMi41MmMxLjU3IDEuNzYgNC4zNiAyLjk1IDcuNSAyLjk1IDQuNzMgMCA4LjMxLTIuNTMgOC4zMS04LjFaTTEyNi43IDk2aC0zLjUyVjgwaDMuNTJ2MTZabTcuMTYtOC4yMmE0LjcgNC43IDAgMCAxIDQuNzctNC45IDQuNyA0LjcgMCAwIDEgNC43NyA0LjkgNC43IDQuNyAwIDAgMS00Ljc3IDQuOSA0LjcgNC43IDAgMCAxLTQuNzctNC45Wk0xNTQuOSA5NmgtMy41MlY3MmgzLjUydjEwLjE4Yy45Ni0xLjYgMi43OC0yLjUgNC44Ni0yLjUgMy43MSAwIDYuMTEgMi42MiA2LjExIDYuNjlWOTZoLTMuNTJ2LTkuMDZjMC0yLjUyLTEuMjgtNC4wNi0zLjMyLTQuMDYtMi4zNCAwLTQuMTMgMS44Mi00LjEzIDUuMjVWOTZabTI0Ljg2LS4ydi0zLjEzYy0uNTEuMi0xLjIyLjMyLTEuODkuMzItMS44MiAwLTIuNjktLjczLTIuNjktMi43MnYtNy4xM2g0LjU4VjgwaC00LjU4di00LjQ1aC0zLjUyVjgwaC0zLjMzdjMuMTRoMy4zM3Y3LjdjMCAzLjYyIDIuNCA1LjMyIDUuNDcgNS4zMiAxLjEgMCAxLjkyLS4xMyAyLjYzLS4zNVptMjEuNTkuNThhMTEuNjcgMTEuNjcgMCAwIDEtMTEuNzUtMTEuNzRjMC02LjU2IDUuMjItMTEuNzQgMTEuNzUtMTEuNzQgNC40NSAwIDguMjIgMi4yNyAxMC4yNCA1Ljc2bC0zLjIzIDEuODVhNy45NCA3Ljk0IDAgMCAwLTcuMDEtNCA3Ljk2IDcuOTYgMCAwIDAtNy45NyA4LjEzIDcuOTYgNy45NiAwIDAgMCA3Ljk3IDguMTMgNy45NCA3Ljk0IDAgMCAwIDctNGwzLjI0IDEuODVhMTEuNjYgMTEuNjYgMCAwIDEtMTAuMjQgNS43NlptMTMuNC0uMzhoMy41MnYtNy44N2MwLTMuNDMgMS44LTUuMjUgNC4xMy01LjI1IDIuMDUgMCAzLjMzIDEuNTQgMy4zMyA0LjA2Vjk2aDMuNTJ2LTkuNjNjMC00LjA3LTIuNC02LjY5LTYuMTEtNi42OS0yLjA4IDAtMy45LjktNC44NyAyLjVWNzJoLTMuNTJ2MjRabTI1LjU2LjMyYy00LjM4IDAtNy43LTMuNzQtNy43LTguMzJzMy4zMi04LjMyIDcuNy04LjMyYzIuMyAwIDQuMjMgMS4xOCA1LjEyIDIuNDZWODBoMy41MnYxNmgtMy41MnYtMi4xNGE2LjM4IDYuMzggMCAwIDEtNS4xMiAyLjQ2Wm0uNjQtMy4yYzIuODUgMCA0Ljc3LTIuMjQgNC43Ny01LjEycy0xLjkyLTUuMTItNC43Ny01LjEyYy0yLjg0IDAtNC43NiAyLjI0LTQuNzYgNS4xMnMxLjkxIDUuMTIgNC43NiA1LjEyWk0yNTMuNzEgOTZoMy41MnYtNy44YzAtMy4yIDEuODMtNC45IDMuODQtNC45LjY0IDAgMS4xNS4xIDEuNzYuMjh2LTMuNjFjLS40OC0uMS0uOTMtLjEzLTEuMzctLjEzYTQuNSA0LjUgMCAwIDAtNC4yMyAzVjgwaC0zLjUydjE2Wm0yMS43My0zLjMzdjMuMTRjLS43LjIyLTEuNTQuMzUtMi42My4zNS0zLjA3IDAtNS40Ny0xLjctNS40Ny01LjMxdi03LjcxaC0zLjMzVjgwaDMuMzN2LTQuNDVoMy41MlY4MGg0LjU4djMuMTRoLTQuNTh2Ny4xM2MwIDEuOTkuODYgMi43MiAyLjY5IDIuNzIuNjcgMCAxLjM3LS4xMyAxLjg5LS4zMlptMTQuMjEtMS4zMWMwLTIuNjItMS42Ni00LjAzLTQuNDgtNC44NmwtMS42My0uNDhjLTEuNTctLjQ1LTEuOTItMS4xMi0xLjkyLTEuOSAwLS45NSAxLjA5LTEuNSAyLjE1LTEuNSAxLjMgMCAyLjMzLjY0IDMuMDQgMS42NGwyLjQzLTEuODZjLTEuMTItMS43Ni0zLjAxLTIuNzItNS40MS0yLjcyLTMuMiAwLTUuNyAxLjczLTUuNzMgNC41OC0uMDMgMi4zNiAxLjQxIDQuMTIgNC4yIDQuOWwxLjQuMzhjMS45Mi41NyAyLjQ3IDEuMTIgMi40NyAyLjA0IDAgMS4xMi0xLjA2IDEuNy0yLjMgMS43LTEuNjQgMC0zLjItLjgtMy44NS0yLjJsLTIuNTkgMS44NWMxLjE1IDIuMjcgMy41OCAzLjM5IDYuNDMgMy4zOSAzLjMgMCA1LjgtMS44OSA1LjgtNC45NlptLTE0My4zOCAyMS40YzAgLjQ2LS4zNy44NC0uODMuODRhLjg2Ljg2IDAgMCAxLS44Ny0uODVjMC0uNDYuMzktLjg1Ljg3LS44NS40NiAwIC44My4zOS44My44NVptLS4yOSAxMS4yNGgtMS4xMnYtOGgxLjEydjhabS01Mi4wMi4xNmE0LjA0IDQuMDQgMCAwIDAgMy45OC00LjE2IDQuMDQgNC4wNCAwIDAgMC0zLjk4LTQuMTZjLTEuMjQgMC0yLjM5LjY0LTIuOTYgMS41VjExMmgtMS4xMnYxMkg5MXYtMS4zNGMuNTcuODYgMS43MiAxLjUgMi45NiAxLjVabS0uMTItMS4wNGMtMS43NCAwLTIuOTQtMS40LTIuOTQtMy4xMiAwLTEuNzMgMS4yLTMuMTIgMi45NC0zLjEyIDEuNzUgMCAyLjk1IDEuNCAyLjk1IDMuMTIgMCAxLjczLTEuMiAzLjEyLTIuOTUgMy4xMlptNy45IDQuMjIgNS4zLTExLjM0aC0xLjI2bC0yLjkzIDYuMzUtMi45My02LjM1aC0xLjI0bDMuNTUgNy42LTEuNzYgMy43NGgxLjI2Wk0xMTUuMyAxMjRoLTEuMnYtMTAuMmgtMy42OHYtMS4xNmg4LjU2djEuMTVoLTMuNjhWMTI0Wm0zLjgyIDBoMS4xMnYtNC4wMmMwLTIuMDQgMS4yMy0yLjk0IDIuMjItMi45NC4yNCAwIC40NS4wMy42Ny4xMXYtMS4xN2EyLjQ0IDIuNDQgMCAwIDAtMi45IDEuNjZWMTE2aC0xLjExdjhabTExLjcyLTEuMzRhMy42NCAzLjY0IDAgMCAxLTIuOTYgMS41IDQuMDQgNC4wNCAwIDAgMS0zLjk4LTQuMTYgNC4wNCA0LjA0IDAgMCAxIDMuOTgtNC4xNmMxLjIzIDAgMi4zOS42NCAyLjk2IDEuNVYxMTZoMS4xMnY4aC0xLjEydi0xLjM0Wm0tNS44LTIuNjZjMCAxLjczIDEuMiAzLjEyIDIuOTUgMy4xMiAxLjc1IDAgMi45NS0xLjQgMi45NS0zLjEyIDAtMS43My0xLjItMy4xMi0yLjk1LTMuMTItMS43NCAwLTIuOTQgMS40LTIuOTQgMy4xMlptMTIuOTggNC4xNmMxLjIzIDAgMi4zOS0uNjQgMi45Ni0xLjVWMTI0aDEuMTJ2LTEySDE0MXY1LjM0YTMuNjQgMy42NCAwIDAgMC0yLjk2LTEuNSA0LjA0IDQuMDQgMCAwIDAtMy45OCA0LjE2IDQuMDQgNC4wNCAwIDAgMCAzLjk4IDQuMTZabS4xMS0xLjA0Yy0xLjc0IDAtMi45NC0xLjQtMi45NC0zLjEyIDAtMS43MyAxLjItMy4xMiAyLjk0LTMuMTIgMS43NSAwIDIuOTUgMS40IDIuOTUgMy4xMiAwIDEuNzMtMS4yIDMuMTItMi45NSAzLjEyWm0xMC42Ljg4aDEuMTF2LTMuOThjMC0xLjk5IDEuMS0zLjE0IDIuNS0zLjE0IDEuMTkgMCAyLjAyLjg2IDIuMDIgMi4yN1YxMjRoMS4xMnYtNWMwLTEuOTYtMS4yNy0zLjE2LTMuMDEtMy4xNi0xLjA0IDAtMi4wNS40NS0yLjYzIDEuNVYxMTZoLTEuMTF2OFptMTYuNzEtLjQyYzAgMi42MS0xLjcyIDMuOTItMy45NSAzLjkyLTEuODQgMC0zLjE3LS44My0zLjc3LTEuNzRsLjg4LS43NWEzLjQgMy40IDAgMCAwIDIuOSAxLjQ1YzEuMzcgMCAyLjgyLS44MyAyLjgyLTIuOTR2LTEuMDJjLS41Ny44Ni0xLjcgMS41LTIuOTIgMS41YTMuOTQgMy45NCAwIDAgMS0zLjk2LTQuMDggMy45NCAzLjk0IDAgMCAxIDMuOTYtNC4wOGMxLjIzIDAgMi4zNS42NCAyLjkyIDEuNVYxMTZoMS4xMnY3LjU4Wm0tNi44NC0zLjY2YzAgMS43MyAxLjE2IDMuMDQgMi45IDMuMDQgMS43NSAwIDIuOTItMS4zMSAyLjkyLTMuMDRzLTEuMTctMy4wNC0yLjkxLTMuMDRjLTEuNzUgMC0yLjkxIDEuMzEtMi45MSAzLjA0Wm0xMy41NSA0LjA4IDQuODgtMTEuMzZoLTEuMzVsLTQuMDMgOS4zOC00LjAzLTkuMzhoLTEuMzZsNC45IDExLjM2aC45OVptNy44NC0xMS4yNWMwIC40Ny0uMzcuODUtLjgzLjg1YS44Ni44NiAwIDAgMS0uODYtLjg1YzAtLjQ2LjM4LS44NS44Ni0uODUuNDcgMCAuODMuMzkuODMuODVabS0uMjggMTEuMjVoLTEuMTN2LThoMS4xM3Y4Wm02LjIuMTZhMy45IDMuOSAwIDAgMCAzLjU2LTEuOTVsLS45MS0uNmEyLjc4IDIuNzggMCAwIDEtMi42NCAxLjUxIDIuODcgMi44NyAwIDAgMS0yLjk2LTIuOTNoNi43NXYtLjNjLS4wMi0yLjU2LTEuNjgtNC4wNS0zLjc2LTQuMDVhNC4wNSA0LjA1IDAgMCAwLTQuMTUgNC4xNmMwIDIuMyAxLjYgNC4xNiA0LjEyIDQuMTZabS0uMDEtNy4yOGMxLjM0IDAgMi40NS44OCAyLjY0IDIuMzJoLTUuNDlhMi44NCAyLjg0IDAgMCAxIDIuODUtMi4zMlptMTMuNTUgNy4xMmgtLjkzbC0yLjEtNi4xLTIuMTQgNi4xaC0uOTJsLTIuNzQtOGgxLjE1bDIuMDggNi4wOCAyLjExLTYuMDhoLjg3bDIuMTEgNi4wOCAyLjA4LTYuMDhoMS4xN2wtMi43NCA4WiIgZmlsbD0iY3VycmVudENvbG9yIj48L3BhdGg+PC9zdmc+';
+const imageWatermark = new ImageWatermark(imageDataUrl, {
+	alpha: 0.5,
+	padding: 20,
+});
+
+const firstPane = chart.panes()[0];
+firstPane.attachPrimitive(imageWatermark);
 // highlight-end
 
 const lineSeries = chart.addAreaSeries({
diff --git a/website/tutorials/how_to/watermark.mdx b/website/tutorials/how_to/watermark.mdx
index a3a1fbb484..6fe89b2a79 100644
--- a/website/tutorials/how_to/watermark.mdx
+++ b/website/tutorials/how_to/watermark.mdx
@@ -11,7 +11,7 @@ keywords:
 
 Lightweight Charts™ has a built-in feature for displaying simple text watermarks on your chart.
 This example shows how to configure and add this simple text watermark to your chart.
-If you are looking to add a more complex watermark then have a look at the [advanced watermark example](#advanced-watermark-example)
+If you are looking to add a more complex watermark then have a look at the [image watermark example](#image-watermark-example)
 included below.
 
 ## Short answer
@@ -63,46 +63,38 @@ import codeSimple from "!!raw-loader!./watermark-simple.js";
 	{codeSimple}
 </CodeBlock>
 
-### Advanced Watermark Example
+### Image Watermark Example
 
-If a simple text watermark doesn't meet your requirements then you can use the following tips
-to rather create your own custom watermark using `html` and `css`.
-
-We will first set the `background` color of the chart to `transparent` so that we can
-place our custom watermark underneath the chart and still see it.
+If a simple text watermark doesn't meet your requirements then you can use the [`ImageWatermark`](/docs/next/api/classes/ImageWatermark) pane primitive exported
+from the library as follows:
 
 ```js
-chart.applyOptions({
-    layout: {
-        // set chart background color to transparent so we can see the elements below
-        // highlight-next-line
-        background: { type: 'solid', color: 'transparent' },
-    },
+import { ImageWatermark } from 'lightweight-charts';
+
+const imageWatermark = new ImageWatermark('/images/my-image.png', {
+    alpha: 0.5,
+    padding: 20,
 });
+
+const firstPane = chart.panes()[0];
+firstPane.attachPrimitive(imageWatermark);
 ```
 
-Next we will create a `div` element, and attach it as a child of the `container` element which is holding the chart.
+The options available for the watermark are: [ImageWatermark Options](/docs/next/api/interfaces/ImageWatermarkOptions).
 
-By setting the `zIndex` value for this div to be negative it will appear beneath the chart.
+You can see full [working examples](#examples) below.
 
-We will position the div using `display: absolute` and by setting `inset: 0px` the div will fill the container.
+## Resources
 
-You can then style the div to meet your specific needs.
+- [`ImageWatermark` pane primitive](/docs/next/api/classes/ImageWatermark).
+- [ImageWatermark Options](/docs/next/api/interfaces/ImageWatermarkOptions)
 
-```js
-const container = document.getElementById('container');
-const background = document.createElement('div');
-// place below the chart
-background.style.zIndex = -1;
-background.style.position = 'absolute';
-// set size and position to match container
-background.style.inset = '0px';
-background.style.backgroundImage = `url("data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyOTIiIGhlaWdodD0iMTI4IiB2aWV3Qm94PSIwIDAgMjkyIDEyOCI+PHBhdGggZmlsbC1ydWxlPSJldmVub2RkIiBkPSJtMTgyLjkzIDcuNi42My0uMzdhNjQuMSA2NC4xIDAgMCAwIDIuNDMtNS4zMWw0Ljc3LTEuMzlhNjQuNjggNjQuNjggMCAwIDEtNC43MiAxMC41NGMuMzggMTAuNDUtMy45MyAyMS4xNS0xMS4xIDI5LjM3LTExLjY2IDEzLjQxLTI2Ljk4IDE1Ljk3LTQzLjU3IDEzLjc4bDEuMDctLjk4YTIxLjEgMjEuMSAwIDAgMCAzLjcyLTQuMDUgNDguMzcgNDguMzcgMCAwIDEtMTEuMDQgMi44NGMtMTAuNjUtNS41NC0yMS42NC0xNC45NC0yNC4yNy0yNy4yNyA5LjE5LTE3IDI4Ljk1LTI0LjAxIDQ3LjM5LTE5Ljk0YTIyLjU3IDIyLjU3IDAgMCAwIDUuODYgOS4wMmMtLjEyLTEuOTItLjEtMy44NC0uMS01Ljc2bC4wMS0xLjc4YzQuOCAyLjk2IDkuNjYgNS44NSAxNS41MiA1LjcgNC4wOC0uMSA4LjQtMS41MiAxMy40LTQuNFptLTIyLjU1IDIzLjI4YTguNDggOC40OCAwIDAgMC0xMi40NS0uMzNsLTcuOS03LjI2QTguNiA4LjYgMCAwIDAgMTMyIDEyYy02LjE0IDAtMTAuMjUgNi42My03LjcgMTIuMDlsLTEzLjAyIDEyLjE5Yy00LjEtNC45Ny01LjY4LTkuMy02LjE3LTEwLjk0IDguMzYtMTMuNzIgMjQuNDYtMjAuMTggNDAuMTUtMTcuMDcgMi45MyA2LjkgOC4zOCAxMC43MiAxNC43NyAxMy45NmwtLjMzLTEuMTRjLS43NC0yLjU2LTEuNDctNS4xLTEuNjItNy43OCA3LjA1IDMuNDUgMTQuNiAzLjM1IDIxLjc2LjMxLTQuNzYgNy4yNy0xMS4xMyAxNC4yMi0xOS40NiAxNy4yNlptLTIyLjU2LTQuMTkgOC4wMyA3LjM4QTguNiA4LjYgMCAwIDAgMTU0IDQ1YTguNiA4LjYgMCAwIDAgOC4yNS0xMC41NWM3Ljk5LTMuMDggMTQuMzctOS4zOCAxOS4yOC0xNi4yMy0zLjQ3IDE5LjQ3LTIxLjk2IDM0LjYxLTQxLjkgMzIuOTggMS43Ny0yLjg0IDIuNDktNi4wNiAzLjIxLTkuMjhsLjM1LTEuNTZjLTUuNDcgMy43Ny0xMC42NyA2LjM4LTE3LjM3IDcuNTJhNDkuOSA0OS45IDAgMCAxLTExLjg1LTguNjVsMTIuODMtMTJhOC41OCA4LjU4IDAgMCAwIDExLjAyLS41NFpNMTMyIDE2YTQuNSA0LjUgMCAxIDAgMCA5IDQuNSA0LjUgMCAwIDAgMC05Wm0xNy41IDIwLjVhNC41IDQuNSAwIDEgMSA5IDAgNC41IDQuNSAwIDAgMS05IDBaTTIxLjYzIDcxLjhhMi4zMyAyLjMzIDAgMCAxIDIuMzMgMi4zNCAyLjM0IDIuMzQgMCAwIDEtMi4zMyAyLjM3IDIuMzggMi4zOCAwIDAgMS0yLjM3LTIuMzcgMi4zOCAyLjM4IDAgMCAxIDIuMzctMi4zM1ptMS43NiA4LjJ2MTZoLTMuNTJWODBoMy41MlptLTYuNDYgMTZIMi43OFY3My4yOGgzLjc1djE5LjE0aDEwLjRWOTZabTI2LjM5LTEuMDlWODBIMzkuOHYyLjE0YTYuMjYgNi4yNiAwIDAgMC01LjEyLTIuNDZjLTQuMzIgMC03LjY4IDMuNTgtNy42OCA4LjEgMCA0LjU0IDMuMzYgOC4xMiA3LjY4IDguMTIgMi4yIDAgNC4xNi0xLjA4IDUuMTItMi41djEuNDhjMCAzLjIzLTIuMTggNS00LjgzIDVhNy4wMyA3LjAzIDAgMCAxLTUuMzItMi4zNGwtMi4xNCAyLjUyYzEuNTcgMS43NiA0LjM1IDIuOTUgNy40OSAyLjk1IDQuNzMgMCA4LjMyLTIuNTMgOC4zMi04LjFabS0xMi43Ny03LjEzYTQuNyA0LjcgMCAwIDEgNC43Ny00LjkgNC43IDQuNyAwIDAgMSA0Ljc3IDQuOSA0LjcgNC43IDAgMCAxLTQuNzcgNC45IDQuNyA0LjcgMCAwIDEtNC43Ny00LjlaTTUxLjU4IDk2aC0zLjUyVjcyaDMuNTJ2MTAuMThjLjk2LTEuNiAyLjc4LTIuNSA0Ljg2LTIuNSAzLjcxIDAgNi4xMSAyLjYyIDYuMTEgNi42OVY5NmgtMy41MnYtOS4wNmMwLTIuNTItMS4yOC00LjA2LTMuMzMtNC4wNi0yLjMzIDAtNC4xMiAxLjgyLTQuMTIgNS4yNVY5NlptMjQuODYtLjJ2LTMuMTNjLS41Mi4yLTEuMjIuMzItMS45LjMyLTEuODIgMC0yLjY4LS43My0yLjY4LTIuNzJ2LTcuMTNoNC41OFY4MGgtNC41OHYtNC40NWgtMy41MlY4MGgtMy4zM3YzLjE0aDMuMzN2Ny43YzAgMy42MiAyLjQgNS4zMiA1LjQ3IDUuMzIgMS4wOSAwIDEuOTItLjEzIDIuNjMtLjM1Wm0yMC4zLjJIOTMuNGwtMy41Mi0xMC4zN0w4Ni4zOSA5NmgtMy4zMmwtNS4zOC0xNmgzLjcybDMuNDUgMTEgMy42OC0xMWgyLjY5bDMuNjUgMTEgMy40OS0xMWgzLjc0bC01LjM4IDE2Wm02Ljc2LThjMCA0Ljg2IDMuNDkgOC4zMiA4LjM1IDguMzIgMy4zNiAwIDUuODYtMS40NCA3LjMtMy43MWwtMi43LTEuOTJhNS4wMyA1LjAzIDAgMCAxLTQuNTcgMi40M2MtMi42NSAwLTQuNzctMS43My00LjkzLTQuMzVoMTIuNThjLjAzLS41MS4wMy0uOC4wMy0xLjE1IDAtNS4xNi0zLjUyLTcuOTQtNy43MS03Ljk0QTguMTIgOC4xMiAwIDAgMCAxMDMuNSA4OFptOC4yMi01LjM0YzIuMDUgMCAzLjkgMS4yNCA0LjI5IDMuNTVoLTguOWMuNDgtMi4zNyAyLjU2LTMuNTUgNC42MS0zLjU1Wm0xMy4yMi0xMC44NWEyLjMzIDIuMzMgMCAwIDEgMi4zNCAyLjMzIDIuMzQgMi4zNCAwIDAgMS0yLjM0IDIuMzcgMi4zOCAyLjM4IDAgMCAxLTIuMzctMi4zNyAyLjM4IDIuMzggMCAwIDEgMi4zNy0yLjMzWm0yMS43IDIzLjFWODBoLTMuNTN2Mi4xNGE2LjI2IDYuMjYgMCAwIDAtNS4xMi0yLjQ2Yy00LjMyIDAtNy42OCAzLjU4LTcuNjggOC4xIDAgNC41NCAzLjM2IDguMTIgNy42OCA4LjEyIDIuMiAwIDQuMTYtMS4wOCA1LjEyLTIuNXYxLjQ4YzAgMy4yMy0yLjE4IDUtNC44MyA1YTcuMDMgNy4wMyAwIDAgMS01LjMxLTIuMzRsLTIuMTUgMi41MmMxLjU3IDEuNzYgNC4zNiAyLjk1IDcuNSAyLjk1IDQuNzMgMCA4LjMxLTIuNTMgOC4zMS04LjFaTTEyNi43IDk2aC0zLjUyVjgwaDMuNTJ2MTZabTcuMTYtOC4yMmE0LjcgNC43IDAgMCAxIDQuNzctNC45IDQuNyA0LjcgMCAwIDEgNC43NyA0LjkgNC43IDQuNyAwIDAgMS00Ljc3IDQuOSA0LjcgNC43IDAgMCAxLTQuNzctNC45Wk0xNTQuOSA5NmgtMy41MlY3MmgzLjUydjEwLjE4Yy45Ni0xLjYgMi43OC0yLjUgNC44Ni0yLjUgMy43MSAwIDYuMTEgMi42MiA2LjExIDYuNjlWOTZoLTMuNTJ2LTkuMDZjMC0yLjUyLTEuMjgtNC4wNi0zLjMyLTQuMDYtMi4zNCAwLTQuMTMgMS44Mi00LjEzIDUuMjVWOTZabTI0Ljg2LS4ydi0zLjEzYy0uNTEuMi0xLjIyLjMyLTEuODkuMzItMS44MiAwLTIuNjktLjczLTIuNjktMi43MnYtNy4xM2g0LjU4VjgwaC00LjU4di00LjQ1aC0zLjUyVjgwaC0zLjMzdjMuMTRoMy4zM3Y3LjdjMCAzLjYyIDIuNCA1LjMyIDUuNDcgNS4zMiAxLjEgMCAxLjkyLS4xMyAyLjYzLS4zNVptMjEuNTkuNThhMTEuNjcgMTEuNjcgMCAwIDEtMTEuNzUtMTEuNzRjMC02LjU2IDUuMjItMTEuNzQgMTEuNzUtMTEuNzQgNC40NSAwIDguMjIgMi4yNyAxMC4yNCA1Ljc2bC0zLjIzIDEuODVhNy45NCA3Ljk0IDAgMCAwLTcuMDEtNCA3Ljk2IDcuOTYgMCAwIDAtNy45NyA4LjEzIDcuOTYgNy45NiAwIDAgMCA3Ljk3IDguMTMgNy45NCA3Ljk0IDAgMCAwIDctNGwzLjI0IDEuODVhMTEuNjYgMTEuNjYgMCAwIDEtMTAuMjQgNS43NlptMTMuNC0uMzhoMy41MnYtNy44N2MwLTMuNDMgMS44LTUuMjUgNC4xMy01LjI1IDIuMDUgMCAzLjMzIDEuNTQgMy4zMyA0LjA2Vjk2aDMuNTJ2LTkuNjNjMC00LjA3LTIuNC02LjY5LTYuMTEtNi42OS0yLjA4IDAtMy45LjktNC44NyAyLjVWNzJoLTMuNTJ2MjRabTI1LjU2LjMyYy00LjM4IDAtNy43LTMuNzQtNy43LTguMzJzMy4zMi04LjMyIDcuNy04LjMyYzIuMyAwIDQuMjMgMS4xOCA1LjEyIDIuNDZWODBoMy41MnYxNmgtMy41MnYtMi4xNGE2LjM4IDYuMzggMCAwIDEtNS4xMiAyLjQ2Wm0uNjQtMy4yYzIuODUgMCA0Ljc3LTIuMjQgNC43Ny01LjEycy0xLjkyLTUuMTItNC43Ny01LjEyYy0yLjg0IDAtNC43NiAyLjI0LTQuNzYgNS4xMnMxLjkxIDUuMTIgNC43NiA1LjEyWk0yNTMuNzEgOTZoMy41MnYtNy44YzAtMy4yIDEuODMtNC45IDMuODQtNC45LjY0IDAgMS4xNS4xIDEuNzYuMjh2LTMuNjFjLS40OC0uMS0uOTMtLjEzLTEuMzctLjEzYTQuNSA0LjUgMCAwIDAtNC4yMyAzVjgwaC0zLjUydjE2Wm0yMS43My0zLjMzdjMuMTRjLS43LjIyLTEuNTQuMzUtMi42My4zNS0zLjA3IDAtNS40Ny0xLjctNS40Ny01LjMxdi03LjcxaC0zLjMzVjgwaDMuMzN2LTQuNDVoMy41MlY4MGg0LjU4djMuMTRoLTQuNTh2Ny4xM2MwIDEuOTkuODYgMi43MiAyLjY5IDIuNzIuNjcgMCAxLjM3LS4xMyAxLjg5LS4zMlptMTQuMjEtMS4zMWMwLTIuNjItMS42Ni00LjAzLTQuNDgtNC44NmwtMS42My0uNDhjLTEuNTctLjQ1LTEuOTItMS4xMi0xLjkyLTEuOSAwLS45NSAxLjA5LTEuNSAyLjE1LTEuNSAxLjMgMCAyLjMzLjY0IDMuMDQgMS42NGwyLjQzLTEuODZjLTEuMTItMS43Ni0zLjAxLTIuNzItNS40MS0yLjcyLTMuMiAwLTUuNyAxLjczLTUuNzMgNC41OC0uMDMgMi4zNiAxLjQxIDQuMTIgNC4yIDQuOWwxLjQuMzhjMS45Mi41NyAyLjQ3IDEuMTIgMi40NyAyLjA0IDAgMS4xMi0xLjA2IDEuNy0yLjMgMS43LTEuNjQgMC0zLjItLjgtMy44NS0yLjJsLTIuNTkgMS44NWMxLjE1IDIuMjcgMy41OCAzLjM5IDYuNDMgMy4zOSAzLjMgMCA1LjgtMS44OSA1LjgtNC45NlptLTE0My4zOCAyMS40YzAgLjQ2LS4zNy44NC0uODMuODRhLjg2Ljg2IDAgMCAxLS44Ny0uODVjMC0uNDYuMzktLjg1Ljg3LS44NS40NiAwIC44My4zOS44My44NVptLS4yOSAxMS4yNGgtMS4xMnYtOGgxLjEydjhabS01Mi4wMi4xNmE0LjA0IDQuMDQgMCAwIDAgMy45OC00LjE2IDQuMDQgNC4wNCAwIDAgMC0zLjk4LTQuMTZjLTEuMjQgMC0yLjM5LjY0LTIuOTYgMS41VjExMmgtMS4xMnYxMkg5MXYtMS4zNGMuNTcuODYgMS43MiAxLjUgMi45NiAxLjVabS0uMTItMS4wNGMtMS43NCAwLTIuOTQtMS40LTIuOTQtMy4xMiAwLTEuNzMgMS4yLTMuMTIgMi45NC0zLjEyIDEuNzUgMCAyLjk1IDEuNCAyLjk1IDMuMTIgMCAxLjczLTEuMiAzLjEyLTIuOTUgMy4xMlptNy45IDQuMjIgNS4zLTExLjM0aC0xLjI2bC0yLjkzIDYuMzUtMi45My02LjM1aC0xLjI0bDMuNTUgNy42LTEuNzYgMy43NGgxLjI2Wk0xMTUuMyAxMjRoLTEuMnYtMTAuMmgtMy42OHYtMS4xNmg4LjU2djEuMTVoLTMuNjhWMTI0Wm0zLjgyIDBoMS4xMnYtNC4wMmMwLTIuMDQgMS4yMy0yLjk0IDIuMjItMi45NC4yNCAwIC40NS4wMy42Ny4xMXYtMS4xN2EyLjQ0IDIuNDQgMCAwIDAtMi45IDEuNjZWMTE2aC0xLjExdjhabTExLjcyLTEuMzRhMy42NCAzLjY0IDAgMCAxLTIuOTYgMS41IDQuMDQgNC4wNCAwIDAgMS0zLjk4LTQuMTYgNC4wNCA0LjA0IDAgMCAxIDMuOTgtNC4xNmMxLjIzIDAgMi4zOS42NCAyLjk2IDEuNVYxMTZoMS4xMnY4aC0xLjEydi0xLjM0Wm0tNS44LTIuNjZjMCAxLjczIDEuMiAzLjEyIDIuOTUgMy4xMiAxLjc1IDAgMi45NS0xLjQgMi45NS0zLjEyIDAtMS43My0xLjItMy4xMi0yLjk1LTMuMTItMS43NCAwLTIuOTQgMS40LTIuOTQgMy4xMlptMTIuOTggNC4xNmMxLjIzIDAgMi4zOS0uNjQgMi45Ni0xLjVWMTI0aDEuMTJ2LTEySDE0MXY1LjM0YTMuNjQgMy42NCAwIDAgMC0yLjk2LTEuNSA0LjA0IDQuMDQgMCAwIDAtMy45OCA0LjE2IDQuMDQgNC4wNCAwIDAgMCAzLjk4IDQuMTZabS4xMS0xLjA0Yy0xLjc0IDAtMi45NC0xLjQtMi45NC0zLjEyIDAtMS43MyAxLjItMy4xMiAyLjk0LTMuMTIgMS43NSAwIDIuOTUgMS40IDIuOTUgMy4xMiAwIDEuNzMtMS4yIDMuMTItMi45NSAzLjEyWm0xMC42Ljg4aDEuMTF2LTMuOThjMC0xLjk5IDEuMS0zLjE0IDIuNS0zLjE0IDEuMTkgMCAyLjAyLjg2IDIuMDIgMi4yN1YxMjRoMS4xMnYtNWMwLTEuOTYtMS4yNy0zLjE2LTMuMDEtMy4xNi0xLjA0IDAtMi4wNS40NS0yLjYzIDEuNVYxMTZoLTEuMTF2OFptMTYuNzEtLjQyYzAgMi42MS0xLjcyIDMuOTItMy45NSAzLjkyLTEuODQgMC0zLjE3LS44My0zLjc3LTEuNzRsLjg4LS43NWEzLjQgMy40IDAgMCAwIDIuOSAxLjQ1YzEuMzcgMCAyLjgyLS44MyAyLjgyLTIuOTR2LTEuMDJjLS41Ny44Ni0xLjcgMS41LTIuOTIgMS41YTMuOTQgMy45NCAwIDAgMS0zLjk2LTQuMDggMy45NCAzLjk0IDAgMCAxIDMuOTYtNC4wOGMxLjIzIDAgMi4zNS42NCAyLjkyIDEuNVYxMTZoMS4xMnY3LjU4Wm0tNi44NC0zLjY2YzAgMS43MyAxLjE2IDMuMDQgMi45IDMuMDQgMS43NSAwIDIuOTItMS4zMSAyLjkyLTMuMDRzLTEuMTctMy4wNC0yLjkxLTMuMDRjLTEuNzUgMC0yLjkxIDEuMzEtMi45MSAzLjA0Wm0xMy41NSA0LjA4IDQuODgtMTEuMzZoLTEuMzVsLTQuMDMgOS4zOC00LjAzLTkuMzhoLTEuMzZsNC45IDExLjM2aC45OVptNy44NC0xMS4yNWMwIC40Ny0uMzcuODUtLjgzLjg1YS44Ni44NiAwIDAgMS0uODYtLjg1YzAtLjQ2LjM4LS44NS44Ni0uODUuNDcgMCAuODMuMzkuODMuODVabS0uMjggMTEuMjVoLTEuMTN2LThoMS4xM3Y4Wm02LjIuMTZhMy45IDMuOSAwIDAgMCAzLjU2LTEuOTVsLS45MS0uNmEyLjc4IDIuNzggMCAwIDEtMi42NCAxLjUxIDIuODcgMi44NyAwIDAgMS0yLjk2LTIuOTNoNi43NXYtLjNjLS4wMi0yLjU2LTEuNjgtNC4wNS0zLjc2LTQuMDVhNC4wNSA0LjA1IDAgMCAwLTQuMTUgNC4xNmMwIDIuMyAxLjYgNC4xNiA0LjEyIDQuMTZabS0uMDEtNy4yOGMxLjM0IDAgMi40NS44OCAyLjY0IDIuMzJoLTUuNDlhMi44NCAyLjg0IDAgMCAxIDIuODUtMi4zMlptMTMuNTUgNy4xMmgtLjkzbC0yLjEtNi4xLTIuMTQgNi4xaC0uOTJsLTIuNzQtOGgxLjE1bDIuMDggNi4wOCAyLjExLTYuMDhoLjg3bDIuMTEgNi4wOCAyLjA4LTYuMDhoMS4xN2wtMi43NCA4WiIgZmlsbD0iY3VycmVudENvbG9yIj48L3BhdGg+PC9zdmc+")`;
-background.style.backgroundRepeat = 'no-repeat';
-background.style.backgroundPosition = 'center';
-background.style.opacity = '0.5';
-container.appendChild(background);
-```
+:::tip
+
+Since the watermark image is black content with a transparent background, it may not be visible when
+viewing the documentation site in dark mode.
+
+:::
 
 import codeAdvanced from "!!raw-loader!./watermark-advanced.js";
 

From 5340b1661fe890169c24770093f6f3a17d4ca2d5 Mon Sep 17 00:00:00 2001
From: Mark Silverwood <3482679+SlicedSilver@users.noreply.github.com>
Date: Thu, 8 Aug 2024 22:10:42 +0100
Subject: [PATCH 10/12] detach hook for pane primitives called for removePane

---
 src/api/pane-api.ts      |  3 ---
 src/model/chart-model.ts |  2 ++
 src/model/pane.ts        | 11 +++++++++++
 3 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/src/api/pane-api.ts b/src/api/pane-api.ts
index cb5cb3d65d..134f610d44 100644
--- a/src/api/pane-api.ts
+++ b/src/api/pane-api.ts
@@ -76,8 +76,5 @@ export class PaneApi<HorzScaleItem> implements IPaneApi<HorzScaleItem> {
 
 	public detachPrimitive(primitive: IPanePrimitive<HorzScaleItem>): void {
 		this._pane.detachPrimitive(primitive as IPanePrimitiveBase<unknown>);
-		if (primitive.detached) {
-			primitive.detached();
-		}
 	}
 }
diff --git a/src/model/chart-model.ts b/src/model/chart-model.ts
index 860bff5ba8..e0a2c5a254 100644
--- a/src/model/chart-model.ts
+++ b/src/model/chart-model.ts
@@ -617,7 +617,9 @@ export class ChartModel<HorzScaleItem> implements IDestroyable, IChartModelBase
 
 		assert(index >= 0 && index < this._panes.length, 'Invalid pane index');
 
+		const pane = this._panes[index];
 		this._panes.splice(index, 1);
+		pane.destroy();
 		this.fullUpdate();
 	}
 
diff --git a/src/model/pane.ts b/src/model/pane.ts
index e201c15967..1850fbae5c 100644
--- a/src/model/pane.ts
+++ b/src/model/pane.ts
@@ -121,6 +121,13 @@ export class Pane implements IDestroyable, IPrimitiveHitTestSource {
 				source.destroy();
 			}
 		});
+		this._primitives = this._primitives.filter((primitive: PanePrimitiveWrapper) => {
+			const p = primitive.primitive();
+			if (p.detached) {
+				p.detached();
+			}
+			return false;
+		});
 		this._destroyed.fire();
 	}
 
@@ -366,6 +373,10 @@ export class Pane implements IDestroyable, IPrimitiveHitTestSource {
 
 	public detachPrimitive(source: IPanePrimitiveBase): void {
 		this._primitives = this._primitives.filter((wrapper: PanePrimitiveWrapper) => wrapper.primitive() !== source);
+		if (source.detached) {
+			source.detached();
+		}
+		this._model.lightUpdate();
 	}
 
 	public primitives(): PanePrimitiveWrapper[] {

From 26636a2390ae6b1ac29bb9382ddbb676f372f065 Mon Sep 17 00:00:00 2001
From: Mark Silverwood <3482679+SlicedSilver@users.noreply.github.com>
Date: Thu, 8 Aug 2024 22:23:56 +0100
Subject: [PATCH 11/12] refactor image watermark to use mediaSize from pane

---
 src/plugins/image-watermark/pane-renderer.ts | 45 ++++++++++--
 src/plugins/image-watermark/pane-view.ts     | 75 ++++----------------
 src/plugins/image-watermark/primitive.ts     |  3 +-
 3 files changed, 53 insertions(+), 70 deletions(-)

diff --git a/src/plugins/image-watermark/pane-renderer.ts b/src/plugins/image-watermark/pane-renderer.ts
index e676e4fe6b..38194afc38 100644
--- a/src/plugins/image-watermark/pane-renderer.ts
+++ b/src/plugins/image-watermark/pane-renderer.ts
@@ -1,6 +1,7 @@
 import {
 	CanvasRenderingTarget2D,
 	MediaCoordinatesRenderingScope,
+	Size,
 } from 'fancy-canvas';
 
 import { IPrimitivePaneRenderer } from '../../model/ipane-primitive';
@@ -15,8 +16,9 @@ export interface Placement {
 }
 
 export interface ImageWatermarkRendererOptions extends ImageWatermarkOptions {
-	placement: Placement | null;
 	imgElement: HTMLImageElement | null;
+	imgWidth: number;
+	imgHeight: number;
 }
 
 export class ImageWatermarkRenderer implements IPrimitivePaneRenderer {
@@ -29,15 +31,46 @@ export class ImageWatermarkRenderer implements IPrimitivePaneRenderer {
 	public draw(target: CanvasRenderingTarget2D): void {
 		target.useMediaCoordinateSpace((scope: MediaCoordinatesRenderingScope) => {
 			const ctx = scope.context;
-			const pos = this._data.placement;
-			if (!pos) {
+			const pos = this._determinePlacement(this._data, scope.mediaSize);
+			if (!pos || !this._data.imgElement) {
 				return;
 			}
-			if (!this._data.imgElement) {
-				throw new Error(`Image element missing.`);
-			}
 			ctx.globalAlpha = this._data.alpha ?? 1;
 			ctx.drawImage(this._data.imgElement, pos.x, pos.y, pos.width, pos.height);
 		});
 	}
+
+	private _determinePlacement(data: ImageWatermarkRendererOptions, paneSize: Size): Placement | null {
+		const { maxHeight, maxWidth, imgHeight, imgWidth, padding } = data;
+		const plotCentreX = Math.round(paneSize.width / 2);
+		const plotCentreY = Math.round(paneSize.height / 2);
+
+		const paddingSize = padding ?? 0;
+		let availableWidth = paneSize.width - 2 * paddingSize;
+		let availableHeight = paneSize.height - 2 * paddingSize;
+
+		if (maxHeight) {
+			availableHeight = Math.min(availableHeight, maxHeight);
+		}
+		if (maxWidth) {
+			availableWidth = Math.min(availableWidth, maxWidth);
+		}
+
+		const scaleX = availableWidth / imgWidth;
+		const scaleY = availableHeight / imgHeight;
+		const scaleToUse = Math.min(scaleX, scaleY);
+
+		const drawWidth = imgWidth * scaleToUse;
+		const drawHeight = imgHeight * scaleToUse;
+
+		const x = plotCentreX - 0.5 * drawWidth;
+		const y = plotCentreY - 0.5 * drawHeight;
+
+		return {
+			x,
+			y,
+			height: drawHeight,
+			width: drawWidth,
+		};
+	}
 }
diff --git a/src/plugins/image-watermark/pane-view.ts b/src/plugins/image-watermark/pane-view.ts
index 2d31b7db4c..e235d2113a 100644
--- a/src/plugins/image-watermark/pane-view.ts
+++ b/src/plugins/image-watermark/pane-view.ts
@@ -1,5 +1,3 @@
-import { IChartApiBase } from '../../api/ichart-api';
-
 import {
 	IPrimitivePaneRenderer,
 	IPrimitivePaneView,
@@ -10,14 +8,12 @@ import { ImageWatermarkOptions } from './options';
 import {
 	ImageWatermarkRenderer,
 	ImageWatermarkRendererOptions,
-	Placement,
 } from './pane-renderer';
 
-interface ImageWatermarkPaneViewState<T> {
+interface ImageWatermarkPaneViewState {
 	image: HTMLImageElement | null;
 	imageWidth: number;
 	imageHeight: number;
-	chart: IChartApiBase<T> | null;
 }
 
 export class ImageWatermarkPaneView<T> implements IPrimitivePaneView {
@@ -26,22 +22,18 @@ export class ImageWatermarkPaneView<T> implements IPrimitivePaneView {
 	private _image: HTMLImageElement | null = null;
 	private _imageWidth: number = 0; // don't draw until loaded
 	private _imageHeight: number = 0;
-	private _chart: IChartApiBase<T> | null = null;
-	private _placement: Placement | null = null;
 
 	public constructor(options: ImageWatermarkOptions) {
 		this._options = options;
 		this._rendererOptions = buildRendererOptions(
 			this._options,
-			this._placement,
-			this._image
+			this._image,
+			this._imageWidth,
+			this._imageHeight
 		);
 	}
 
-	public stateUpdate(state: ImageWatermarkPaneViewState<T>): void {
-		if (state.chart !== undefined) {
-			this._chart = state.chart;
-		}
+	public stateUpdate(state: ImageWatermarkPaneViewState): void {
 		if (state.imageWidth !== undefined) {
 			this._imageWidth = state.imageWidth;
 		}
@@ -64,70 +56,29 @@ export class ImageWatermarkPaneView<T> implements IPrimitivePaneView {
 	}
 
 	public update(): void {
-		this._placement = this._determinePlacement();
 		this._rendererOptions = buildRendererOptions(
 			this._options,
-			this._placement,
-			this._image
+			this._image,
+			this._imageWidth,
+			this._imageHeight
 		);
 	}
 
 	public renderer(): IPrimitivePaneRenderer {
 		return new ImageWatermarkRenderer(this._rendererOptions);
 	}
-
-	private _determinePlacement(): Placement | null {
-		if (!this._chart || !this._imageWidth || !this._imageHeight) {
-			return null;
-		}
-		const leftPriceScaleWidth = this._chart.priceScale('left').width();
-		const plotAreaWidth = this._chart.timeScale().width();
-		const startX = leftPriceScaleWidth;
-		const plotAreaHeight =
-			this._chart.chartElement().clientHeight -
-			this._chart.timeScale().height();
-
-		const plotCentreX = Math.round(plotAreaWidth / 2) + startX;
-		const plotCentreY = Math.round(plotAreaHeight / 2) + 0;
-
-		const padding = this._options.padding ?? 0;
-		let availableWidth = plotAreaWidth - 2 * padding;
-		let availableHeight = plotAreaHeight - 2 * padding;
-
-		if (this._options.maxHeight) {
-			availableHeight = Math.min(availableHeight, this._options.maxHeight);
-		}
-		if (this._options.maxWidth) {
-			availableWidth = Math.min(availableWidth, this._options.maxWidth);
-		}
-
-		const scaleX = availableWidth / this._imageWidth;
-		const scaleY = availableHeight / this._imageHeight;
-		const scaleToUse = Math.min(scaleX, scaleY);
-
-		const drawWidth = this._imageWidth * scaleToUse;
-		const drawHeight = this._imageHeight * scaleToUse;
-
-		const x = plotCentreX - 0.5 * drawWidth;
-		const y = plotCentreY - 0.5 * drawHeight;
-
-		return {
-			x,
-			y,
-			height: drawHeight,
-			width: drawWidth,
-		};
-	}
 }
 
 function buildRendererOptions(
 	options: ImageWatermarkOptions,
-	placement: Placement | null,
-	imgElement: HTMLImageElement | null
+	imgElement: HTMLImageElement | null,
+	imgWidth: number,
+	imgHeight: number
 ): ImageWatermarkRendererOptions {
 	return {
 		...options,
-		placement,
 		imgElement,
+		imgWidth,
+		imgHeight,
 	};
 }
diff --git a/src/plugins/image-watermark/primitive.ts b/src/plugins/image-watermark/primitive.ts
index 5cbdcef134..ed84aacd9c 100644
--- a/src/plugins/image-watermark/primitive.ts
+++ b/src/plugins/image-watermark/primitive.ts
@@ -64,7 +64,7 @@ export class ImageWatermark<T = Time> implements IPanePrimitive<T> {
 	}
 
 	public attached(attachedParams: PaneAttachedParameter<T>): void {
-		const { requestUpdate, chart } = attachedParams;
+		const { requestUpdate } = attachedParams;
 		this._requestUpdate = requestUpdate;
 		this._imgElement = new Image();
 		this._imgElement.onload = () => {
@@ -75,7 +75,6 @@ export class ImageWatermark<T = Time> implements IPanePrimitive<T> {
 					imageHeight,
 					imageWidth,
 					image: this._imgElement,
-					chart,
 				})
 			);
 			if (this._requestUpdate) {

From 5b9a71e44dd3b3981d95bcd9a57ecc4afc7368e4 Mon Sep 17 00:00:00 2001
From: Mark Silverwood <3482679+SlicedSilver@users.noreply.github.com>
Date: Fri, 9 Aug 2024 12:36:08 +0100
Subject: [PATCH 12/12] fixed paneApi destroying for removePane action

---
 src/gui/pane-widget.ts   | 1 +
 src/model/chart-model.ts | 2 --
 2 files changed, 1 insertion(+), 2 deletions(-)

diff --git a/src/gui/pane-widget.ts b/src/gui/pane-widget.ts
index 5b6c38a7da..853f7cd622 100644
--- a/src/gui/pane-widget.ts
+++ b/src/gui/pane-widget.ts
@@ -163,6 +163,7 @@ export class PaneWidget implements IDestroyable, MouseEventHandlers {
 
 		if (this._state !== null) {
 			this._state.onDestroyed().unsubscribeAll(this);
+			this._state.destroy();
 		}
 
 		this._mouseEventHandler.destroy();
diff --git a/src/model/chart-model.ts b/src/model/chart-model.ts
index e0a2c5a254..860bff5ba8 100644
--- a/src/model/chart-model.ts
+++ b/src/model/chart-model.ts
@@ -617,9 +617,7 @@ export class ChartModel<HorzScaleItem> implements IDestroyable, IChartModelBase
 
 		assert(index >= 0 && index < this._panes.length, 'Invalid pane index');
 
-		const pane = this._panes[index];
 		this._panes.splice(index, 1);
-		pane.destroy();
 		this.fullUpdate();
 	}