@baron1996/klinecharts-adapter 0.1.1 → 0.2.2

package/dist/adapter.js

@@ -2,9 +2,29 @@ import { parseChartScene, SceneError, } from '@baron1996/kline-scene-schema';
 import { createEngine } from './engine.js';
 import { registerProjectOverlays } from './extensions/register.js';
 import { createEngineIdMap, } from './conversion/id-map.js';
-import { applyPanes } from './conversion/panes.js';
+import { applyPanes, overrideSceneYAxis } from './conversion/panes.js';
 import { createSceneOverlays, fromEngineOverlay, toEngineOverlay, toEngineOverlayDrawing, } from './conversion/overlays.js';
+import { normalizePriceValue } from './conversion/price.js';
 import { applyViewport } from './conversion/viewport.js';
+import { createDragCandidate, } from './interaction/dragging.js';
+import { hitTestOverlayGeometries, } from './interaction/hit-testing.js';
+import { shouldIgnoreStaleOverlayDeselection } from './interaction/selection-arbitration.js';
+function promoteSceneToM2(scene, scale) {
+    const candidate = structuredClone(scene);
+    candidate.runtime.runtimeVersion = '0.2.0';
+    for (const pane of candidate.panes) {
+        for (const axis of pane.yAxes) {
+            axis.scale =
+                pane.kind === 'candle' && axis.role === 'primary' && scale !== undefined
+                    ? scale
+                    : axis.scale ?? 'linear';
+        }
+    }
+    return candidate;
+}
+function isControlledInteractionOverlay(overlay) {
+    return overlay.type === 'horizontalStraightLine' || overlay.type === 'priceMeasurement';
+}
 /**
  * ChartScene 与 KLineCharts 之间的唯一边界。
  * 引擎对象和内部 ID 永不从该类的公共接口泄露。
@@ -16,7 +36,7 @@ export class KLineChartsSceneAdapter {
     #engine;
     /** 场景 ID 与引擎内部 ID 的双向映射。 */
     #idMap;
-    /** 当前可导出的规范化场景。 */
+    /** 当前最后一次成功提交、可导出的规范化场景。 */
     #scene;
     /** 当前引擎容器。 */
     #container;
@@ -26,6 +46,14 @@ export class KLineChartsSceneAdapter {
     #disposed = false;
     /** 仅传递纯场景数据的事件订阅者。 */
     #listeners = new Set();
+    /** 当前选择状态，null 表示明确未选择。 */
+    #selectedOverlayId = null;
+    /** 当前受控拖动事务；progress 永不写入 #scene。 */
+    #pointerInteraction;
+    /** 当前交互式量度的首锚点；只用于补偿引擎丢弃快速第二击，不进入 Scene。 */
+    #interactivePriceMeasurement;
+    /** 确定性 opaque 交互 ID 序号。 */
+    #interactionSequence = 0;
     constructor(container, scene, handle, idMap, originalBackground) {
         this.#container = container;
         this.#scene = scene;
@@ -33,6 +61,7 @@ export class KLineChartsSceneAdapter {
         this.#engine = handle.module;
         this.#idMap = idMap;
         this.#originalBackground = originalBackground;
+        this.#installInteractionListeners();
     }
     static async create(container, value) {
         const scene = parseChartScene(value);
@@ -75,6 +104,17 @@ export class KLineChartsSceneAdapter {
             listener(structuredClone(event));
         }
     }
+    #selectOverlay(id) {
+        const previousId = this.#selectedOverlayId;
+        if (previousId === id) {
+            return;
+        }
+        this.#selectedOverlayId = id;
+        this.#emit({ type: 'overlay-selection-changed', previousId, id });
+        if (id !== null) {
+            this.#emit({ type: 'overlay-selected', id });
+        }
+    }
     #commitEngineOverlay(engineOverlay, source, kind) {
         const existingIndex = this.#scene.overlays.findIndex((overlay) => overlay.id === source.id);
         const path = existingIndex < 0 ? `/overlays/${this.#scene.overlays.length}` : `/overlays/${existingIndex}`;
@@ -99,20 +139,47 @@ export class KLineChartsSceneAdapter {
     #overlayCallbacks(source, drawing = false) {
         return {
             onDrawEnd: ({ overlay }) => {
+                if (drawing &&
+                    this.#interactivePriceMeasurement?.source.id === source.id) {
+                    this.#interactivePriceMeasurement = undefined;
+                }
                 this.#safelyCommitEngineOverlay(overlay, source, drawing ? 'created' : 'updated');
             },
+            onPressedMoveStart: ({ overlay }) => {
+                this.#selectOverlay(overlay.id);
+            },
             onPressedMoveEnd: ({ overlay }) => {
-                this.#safelyCommitEngineOverlay(overlay, source, 'updated');
+                if (!isControlledInteractionOverlay(source)) {
+                    this.#safelyCommitEngineOverlay(overlay, source, 'updated');
+                }
             },
             onSelected: ({ overlay }) => {
-                this.#emit({ type: 'overlay-selected', id: overlay.id });
+                this.#selectOverlay(overlay.id);
+            },
+            onDeselected: (event) => {
+                const eventX = event.x;
+                const eventY = event.y;
+                const coordinate = typeof eventX === 'number' && Number.isFinite(eventX) &&
+                    typeof eventY === 'number' && Number.isFinite(eventY)
+                    ? { x: eventX, y: eventY }
+                    : undefined;
+                if (this.#selectedOverlayId === event.overlay.id &&
+                    !shouldIgnoreStaleOverlayDeselection(this.#selectedOverlayId, event.overlay.id, coordinate, this.#overlayGeometries())) {
+                    this.#selectOverlay(null);
+                }
             },
             onRemoved: ({ overlay }) => {
+                if (this.#interactivePriceMeasurement?.source.id === overlay.id) {
+                    this.#interactivePriceMeasurement = undefined;
+                }
                 if (this.#scene.overlays.some((candidate) => candidate.id === overlay.id)) {
                     this.#scene = parseChartScene({
                         ...structuredClone(this.#scene),
                         overlays: this.#scene.overlays.filter((candidate) => candidate.id !== overlay.id),
                     });
+                    if (this.#selectedOverlayId === overlay.id) {
+                        this.#selectOverlay(null);
+                    }
                     this.#emit({ type: 'overlay-removed', id: overlay.id });
                 }
             },
@@ -130,6 +197,334 @@ export class KLineChartsSceneAdapter {
             throw error;
         }
     }
+    #installInteractionListeners() {
+        this.#container.addEventListener('pointerdown', this.#handlePointerDown, true);
+        this.#container.addEventListener('pointermove', this.#handlePointerMove, true);
+        this.#container.addEventListener('pointerup', this.#handlePointerUp, true);
+        this.#container.addEventListener('pointercancel', this.#handlePointerCancel, true);
+        window.addEventListener('keydown', this.#handleKeyDown);
+        window.addEventListener('blur', this.#handleWindowBlur);
+    }
+    #removeInteractionListeners() {
+        this.#container.removeEventListener('pointerdown', this.#handlePointerDown, true);
+        this.#container.removeEventListener('pointermove', this.#handlePointerMove, true);
+        this.#container.removeEventListener('pointerup', this.#handlePointerUp, true);
+        this.#container.removeEventListener('pointercancel', this.#handlePointerCancel, true);
+        window.removeEventListener('keydown', this.#handleKeyDown);
+        window.removeEventListener('blur', this.#handleWindowBlur);
+    }
+    #pointerCoordinate(event) {
+        const rect = this.#container.getBoundingClientRect();
+        return { x: event.clientX - rect.left, y: event.clientY - rect.top };
+    }
+    #primaryAxisFilter(paneId) {
+        const pane = this.#scene.panes.find((candidate) => candidate.id === paneId);
+        const axis = pane?.yAxes.find((candidate) => candidate.role === 'primary');
+        const enginePaneId = this.#idMap.paneToEngine.get(paneId);
+        const engineAxisId = axis === undefined ? undefined : this.#idMap.yAxisToEngine.get(axis.id);
+        if (enginePaneId === undefined || engineAxisId === undefined) {
+            throw new SceneError('INVALID_REFERENCE', '/panes', 'Overlay Pane or primary Y-axis is unmapped.');
+        }
+        return { paneId: enginePaneId, yAxisId: engineAxisId, absolute: true };
+    }
+    #toPixel(point, paneId) {
+        const converted = this.#chart.convertToPixel(point, this.#primaryAxisFilter(paneId));
+        if (!Number.isFinite(converted.x) || !Number.isFinite(converted.y)) {
+            throw new SceneError('EXPORT_INVALID', '/overlays', 'KLineCharts returned a non-finite pixel coordinate.');
+        }
+        return { x: converted.x, y: converted.y };
+    }
+    #fromPixel(point, paneId) {
+        const converted = this.#chart.convertFromPixel([point], this.#primaryAxisFilter(paneId));
+        const value = converted[0];
+        if (!Number.isFinite(value?.dataIndex) || !Number.isFinite(value?.value)) {
+            throw new SceneError('INVALID_REFERENCE', '/overlays', 'Pointer does not map to finite chart data.');
+        }
+        return { dataIndex: value.dataIndex, value: value.value };
+    }
+    #measurementAnchor(point, paneId, path) {
+        const converted = this.#chart.convertFromPixel([point], this.#primaryAxisFilter(paneId));
+        const value = converted[0];
+        if (!Number.isSafeInteger(value?.timestamp) ||
+            !Number.isFinite(value?.value) ||
+            !this.#scene.data.some((bar) => bar.timestamp === value?.timestamp)) {
+            throw new SceneError('INVALID_REFERENCE', path, 'Pointer does not map to a finite price and an embedded market-data timestamp.');
+        }
+        return {
+            timestamp: value.timestamp,
+            value: normalizePriceValue(value.value, this.#scene.symbol.pricePrecision, `${path}/value`),
+        };
+    }
+    #completeInteractivePriceMeasurement(drawing, end) {
+        const { text: _text, ...source } = drawing.source;
+        const candidate = parseChartScene({
+            ...structuredClone(this.#scene),
+            overlays: [
+                ...structuredClone(this.#scene.overlays),
+                {
+                    ...structuredClone(source),
+                    start: structuredClone(drawing.start),
+                    end: structuredClone(end),
+                },
+            ],
+        });
+        const index = candidate.overlays.length - 1;
+        const overlay = candidate.overlays[index];
+        this.#interactivePriceMeasurement = undefined;
+        if (!this.#chart.removeOverlay({ id: overlay.id })) {
+            throw new SceneError('RUNTIME_INIT_FAILED', `/overlays/${index}`, `KLineCharts failed to replace in-progress Overlay ${overlay.id}.`);
+        }
+        const result = this.#chart.createOverlay(toEngineOverlay(overlay, this.#idMap, `/overlays/${index}`, this.#overlayCallbacks(overlay)));
+        if (result !== overlay.id) {
+            throw new SceneError('RUNTIME_INIT_FAILED', `/overlays/${index}`, `KLineCharts failed to commit interactive Overlay ${overlay.id}.`);
+        }
+        this.#scene = candidate;
+        this.#emit({ type: 'overlay-created', overlay });
+    }
+    #overlayGeometries() {
+        const geometries = [];
+        for (let sceneIndex = 0; sceneIndex < this.#scene.overlays.length; sceneIndex++) {
+            const overlay = this.#scene.overlays[sceneIndex];
+            if (overlay === undefined || !overlay.visible) {
+                continue;
+            }
+            if (overlay.type === 'horizontalStraightLine') {
+                const anchor = overlay.anchor;
+                if (anchor === undefined || !('value' in anchor)) {
+                    continue;
+                }
+                const paneFilter = this.#primaryAxisFilter(overlay.paneId);
+                const paneMain = this.#chart.getDom(paneFilter.paneId, 'main');
+                const containerRect = this.#container.getBoundingClientRect();
+                const mainRect = paneMain?.getBoundingClientRect() ?? containerRect;
+                const projected = this.#toPixel({ timestamp: this.#scene.data[0].timestamp, value: anchor.value }, overlay.paneId);
+                const start = { x: mainRect.left - containerRect.left, y: projected.y };
+                const end = { x: mainRect.right - containerRect.left, y: projected.y };
+                geometries.push({
+                    overlayId: overlay.id,
+                    sceneIndex,
+                    zLevel: overlay.zLevel,
+                    locked: overlay.locked,
+                    anchors: [{ x: (start.x + end.x) / 2, y: projected.y }],
+                    bodySegments: [[start, end]],
+                });
+                continue;
+            }
+            if (overlay.type === 'priceMeasurement' && overlay.start !== undefined && overlay.end !== undefined) {
+                const start = this.#toPixel(overlay.start, overlay.paneId);
+                const end = this.#toPixel(overlay.end, overlay.paneId);
+                geometries.push({
+                    overlayId: overlay.id,
+                    sceneIndex,
+                    zLevel: overlay.zLevel,
+                    locked: overlay.locked,
+                    anchors: [start, end],
+                    bodySegments: [[start, end]],
+                });
+                continue;
+            }
+            if (overlay.points !== undefined && overlay.points.length >= 2) {
+                const anchors = overlay.points.map((point) => this.#toPixel(point, overlay.paneId));
+                const bodySegments = [];
+                for (let pointIndex = 1; pointIndex < anchors.length; pointIndex++) {
+                    bodySegments.push([anchors[pointIndex - 1], anchors[pointIndex]]);
+                }
+                geometries.push({
+                    overlayId: overlay.id,
+                    sceneIndex,
+                    zLevel: overlay.zLevel,
+                    locked: overlay.locked,
+                    anchors,
+                    bodySegments,
+                });
+            }
+        }
+        return geometries;
+    }
+    #interactionIdentity(interaction) {
+        return {
+            interactionId: interaction.interactionId,
+            overlayId: interaction.hit.overlayId,
+            target: interaction.hit.target,
+            anchorIndex: interaction.hit.anchorIndex,
+            before: structuredClone(interaction.before),
+        };
+    }
+    #stopPointerCapture(interaction) {
+        if (this.#container.hasPointerCapture(interaction.pointerId)) {
+            this.#container.releasePointerCapture(interaction.pointerId);
+        }
+    }
+    #cancelInteraction(reason, error) {
+        const interaction = this.#pointerInteraction;
+        if (interaction === undefined) {
+            return;
+        }
+        this.#pointerInteraction = undefined;
+        this.#stopPointerCapture(interaction);
+        if (!interaction.started) {
+            return;
+        }
+        const index = this.#scene.overlays.findIndex((overlay) => overlay.id === interaction.before.id);
+        if (index < 0 ||
+            !this.#chart.overrideOverlay(toEngineOverlay(interaction.before, this.#idMap, `/overlays/${index}`, this.#overlayCallbacks(interaction.before)))) {
+            throw new SceneError('RUNTIME_INIT_FAILED', '/overlays', `KLineCharts failed to restore Overlay ${interaction.before.id}.`);
+        }
+        this.#emit({
+            type: 'overlay-drag-cancelled',
+            ...this.#interactionIdentity(interaction),
+            reason,
+        });
+        if (reason === 'validation-error' && error !== undefined) {
+            this.#emit({ type: 'scene-error', issues: structuredClone(error.issues) });
+        }
+    }
+    #handlePointerDown = (event) => {
+        if (this.#disposed || event.button !== 0 || this.#pointerInteraction !== undefined) {
+            return;
+        }
+        const coordinate = this.#pointerCoordinate(event);
+        const measurement = this.#interactivePriceMeasurement;
+        if (measurement !== undefined) {
+            try {
+                const point = this.#measurementAnchor(coordinate, measurement.source.paneId, measurement.start === undefined ? '/overlays/start' : '/overlays/end');
+                if (measurement.start === undefined) {
+                    measurement.start = point;
+                    return;
+                }
+                event.preventDefault();
+                event.stopImmediatePropagation();
+                this.#completeInteractivePriceMeasurement(measurement, point);
+                return;
+            }
+            catch (error) {
+                if (error instanceof SceneError) {
+                    event.preventDefault();
+                    event.stopImmediatePropagation();
+                    this.#emit({ type: 'scene-error', issues: structuredClone(error.issues) });
+                    return;
+                }
+                throw error;
+            }
+        }
+        const hit = hitTestOverlayGeometries(coordinate, this.#overlayGeometries());
+        if (hit === null) {
+            const selected = this.#scene.overlays.find((overlay) => overlay.id === this.#selectedOverlayId);
+            if (selected !== undefined && isControlledInteractionOverlay(selected)) {
+                this.#selectOverlay(null);
+            }
+            return;
+        }
+        const before = this.#scene.overlays.find((overlay) => overlay.id === hit.overlayId);
+        if (before === undefined) {
+            return;
+        }
+        this.#selectOverlay(before.id);
+        if (!isControlledInteractionOverlay(before)) {
+            return;
+        }
+        event.preventDefault();
+        event.stopImmediatePropagation();
+        if (hit.locked) {
+            return;
+        }
+        this.#container.setPointerCapture(event.pointerId);
+        this.#pointerInteraction = {
+            pointerId: event.pointerId,
+            originClient: coordinate,
+            originData: this.#fromPixel(coordinate, before.paneId),
+            hit,
+            before: structuredClone(before),
+            interactionId: `interaction-${this.#interactionSequence++}`,
+            started: false,
+        };
+    };
+    #handlePointerMove = (event) => {
+        const interaction = this.#pointerInteraction;
+        if (interaction === undefined || interaction.pointerId !== event.pointerId) {
+            return;
+        }
+        event.preventDefault();
+        event.stopImmediatePropagation();
+        const coordinate = this.#pointerCoordinate(event);
+        if (!interaction.started &&
+            Math.hypot(coordinate.x - interaction.originClient.x, coordinate.y - interaction.originClient.y) < 0.5) {
+            return;
+        }
+        if (!interaction.started) {
+            interaction.started = true;
+            this.#emit({
+                type: 'overlay-drag-started',
+                ...this.#interactionIdentity(interaction),
+            });
+        }
+        try {
+            const candidate = createDragCandidate(interaction.before, interaction.hit, interaction.originData, this.#fromPixel(coordinate, interaction.before.paneId), this.#scene.data.map((bar) => bar.timestamp), this.#scene.symbol.pricePrecision);
+            const index = this.#scene.overlays.findIndex((overlay) => overlay.id === candidate.id);
+            const overlays = structuredClone(this.#scene.overlays);
+            overlays[index] = candidate;
+            const parsed = parseChartScene({ ...structuredClone(this.#scene), overlays });
+            const normalized = parsed.overlays[index];
+            if (!this.#chart.overrideOverlay(toEngineOverlay(normalized, this.#idMap, `/overlays/${index}`, this.#overlayCallbacks(normalized)))) {
+                throw new SceneError('RUNTIME_INIT_FAILED', `/overlays/${index}`, `KLineCharts failed to preview Overlay ${normalized.id}.`);
+            }
+            interaction.candidate = normalized;
+            this.#emit({
+                type: 'overlay-dragging',
+                ...this.#interactionIdentity(interaction),
+                candidate: normalized,
+            });
+        }
+        catch (error) {
+            if (error instanceof SceneError) {
+                this.#cancelInteraction('validation-error', error);
+                return;
+            }
+            throw error;
+        }
+    };
+    #handlePointerUp = (event) => {
+        const interaction = this.#pointerInteraction;
+        if (interaction === undefined || interaction.pointerId !== event.pointerId) {
+            return;
+        }
+        event.preventDefault();
+        event.stopImmediatePropagation();
+        this.#pointerInteraction = undefined;
+        this.#stopPointerCapture(interaction);
+        if (!interaction.started) {
+            return;
+        }
+        const overlay = interaction.candidate ?? interaction.before;
+        const index = this.#scene.overlays.findIndex((candidate) => candidate.id === overlay.id);
+        const overlays = structuredClone(this.#scene.overlays);
+        overlays[index] = overlay;
+        this.#scene = parseChartScene({ ...structuredClone(this.#scene), overlays });
+        const committed = this.#scene.overlays[index];
+        this.#emit({
+            type: 'overlay-drag-committed',
+            ...this.#interactionIdentity(interaction),
+            overlay: committed,
+        });
+        this.#emit({ type: 'overlay-updated', overlay: committed });
+    };
+    #handlePointerCancel = (event) => {
+        if (this.#pointerInteraction?.pointerId === event.pointerId) {
+            event.preventDefault();
+            event.stopImmediatePropagation();
+            this.#cancelInteraction('pointer-cancel');
+        }
+    };
+    #handleKeyDown = (event) => {
+        if (event.key === 'Escape' && this.#pointerInteraction !== undefined) {
+            this.#cancelInteraction('escape');
+        }
+    };
+    #handleWindowBlur = () => {
+        if (this.#pointerInteraction !== undefined) {
+            this.#cancelInteraction('window-blur');
+        }
+    };
     subscribe(listener) {
         this.#assertActive();
         this.#listeners.add(listener);
@@ -139,24 +534,60 @@ export class KLineChartsSceneAdapter {
     }
     exportScene() {
         this.#assertActive();
-        const engines = new Map(this.#engineOverlays().map((overlay) => [overlay.id, overlay]));
-        const overlays = this.#scene.overlays.map((source, index) => {
-            const engine = engines.get(source.id);
-            if (engine === undefined) {
-                throw new SceneError('EXPORT_INVALID', `/overlays/${index}`, `KLineCharts lost Overlay ${source.id}.`);
+        for (let index = 0; index < this.#scene.overlays.length; index++) {
+            const overlay = this.#scene.overlays[index];
+            if (!this.#engineOverlays().some((engine) => engine.id === overlay.id)) {
+                throw new SceneError('EXPORT_INVALID', `/overlays/${index}`, `KLineCharts lost Overlay ${overlay.id}.`);
             }
-            return fromEngineOverlay(engine, source, this.#idMap, `/overlays/${index}`, this.#scene.symbol.pricePrecision);
-        });
-        return parseChartScene({
-            ...structuredClone(this.#scene),
-            overlays,
-        });
+        }
+        return parseChartScene(structuredClone(this.#scene));
+    }
+    async setPriceScale(scale) {
+        this.#assertActive();
+        const candidate = parseChartScene(promoteSceneToM2(this.#scene, scale));
+        const paneIndex = candidate.panes.findIndex((pane) => pane.kind === 'candle');
+        const pane = candidate.panes[paneIndex];
+        const axisIndex = pane.yAxes.findIndex((axis) => axis.role === 'primary');
+        const axis = pane.yAxes[axisIndex];
+        const previousPane = this.#scene.panes[paneIndex];
+        const previousAxis = previousPane.yAxes[axisIndex];
+        const path = `/panes/${paneIndex}/yAxes/${axisIndex}`;
+        try {
+            overrideSceneYAxis(this.#chart, this.#idMap, axis, pane.id, path);
+            // KLineCharts batches Y-axis recreation in a microtask; await that formal
+            // layout boundary before making the upgraded Scene externally visible.
+            await Promise.resolve();
+            const reference = candidate.data[0];
+            this.#toPixel({ timestamp: reference.timestamp, value: reference.close }, pane.id);
+        }
+        catch (error) {
+            overrideSceneYAxis(this.#chart, this.#idMap, previousAxis, previousPane.id, path);
+            await Promise.resolve();
+            if (error instanceof SceneError) {
+                throw error;
+            }
+            throw new SceneError('RUNTIME_INIT_FAILED', `${path}/scale`, 'KLineCharts failed to apply the requested price scale atomically.');
+        }
+        this.#scene = candidate;
+        return structuredClone(candidate);
+    }
+    projectPoint(point, paneId) {
+        this.#assertActive();
+        const targetPane = paneId ?? this.#scene.panes.find((pane) => pane.kind === 'candle').id;
+        return this.#toPixel(point, targetPane);
+    }
+    hitTestOverlay(point) {
+        this.#assertActive();
+        return hitTestOverlayGeometries(point, this.#overlayGeometries());
     }
     addOverlay(value) {
         this.#assertActive();
+        const baseScene = value.type === 'priceMeasurement'
+            ? promoteSceneToM2(this.#scene)
+            : structuredClone(this.#scene);
         const candidate = parseChartScene({
-            ...structuredClone(this.#scene),
-            overlays: [...this.#scene.overlays, structuredClone(value)],
+            ...baseScene,
+            overlays: [...baseScene.overlays, structuredClone(value)],
         });
         const index = candidate.overlays.length - 1;
         const overlay = candidate.overlays[index];
@@ -168,12 +599,13 @@ export class KLineChartsSceneAdapter {
         this.#emit({ type: 'overlay-created', overlay });
         return structuredClone(overlay);
     }
-    updateOverlay(value) {
+    #updateOverlay(value, styleChange) {
         this.#assertActive();
         const index = this.#scene.overlays.findIndex((overlay) => overlay.id === value.id);
         if (index < 0) {
             throw new SceneError('INVALID_REFERENCE', '/overlays', `Overlay ${value.id} does not exist.`);
         }
+        const before = structuredClone(this.#scene.overlays[index]);
         const overlays = structuredClone(this.#scene.overlays);
         overlays[index] = structuredClone(value);
         const candidate = parseChartScene({
@@ -181,13 +613,26 @@ export class KLineChartsSceneAdapter {
             overlays,
         });
         const overlay = candidate.overlays[index];
-        if (!this.#chart.overrideOverlay(toEngineOverlay(overlay, this.#idMap, `/overlays/${index}`))) {
+        if (!this.#chart.overrideOverlay(toEngineOverlay(overlay, this.#idMap, `/overlays/${index}`, this.#overlayCallbacks(overlay)))) {
             throw new SceneError('RUNTIME_INIT_FAILED', `/overlays/${index}`, `KLineCharts failed to update Overlay ${overlay.id}.`);
         }
         this.#scene = candidate;
+        if (styleChange) {
+            this.#emit({ type: 'overlay-style-changed', before, overlay });
+        }
         this.#emit({ type: 'overlay-updated', overlay });
         return structuredClone(overlay);
     }
+    updateOverlay(value) {
+        return this.#updateOverlay(value, false);
+    }
+    updateOverlayStyles(id, styles) {
+        const overlay = this.getOverlay(id);
+        if (overlay === undefined) {
+            throw new SceneError('INVALID_REFERENCE', '/overlays', `Overlay ${id} does not exist.`);
+        }
+        return this.#updateOverlay({ ...overlay, styles: structuredClone(styles) }, true);
+    }
     removeOverlay(id) {
         this.#assertActive();
         const index = this.#scene.overlays.findIndex((overlay) => overlay.id === id);
@@ -202,6 +647,9 @@ export class KLineChartsSceneAdapter {
                 ...structuredClone(this.#scene),
                 overlays: this.#scene.overlays.filter((overlay) => overlay.id !== id),
             });
+            if (this.#selectedOverlayId === id) {
+                this.#selectOverlay(null);
+            }
             this.#emit({ type: 'overlay-removed', id });
         }
         return true;
@@ -212,17 +660,32 @@ export class KLineChartsSceneAdapter {
             this.#engineOverlays().some((overlay) => overlay.id === request.id)) {
             throw new SceneError('DUPLICATE_ID', '/overlays/id', `Overlay ${request.id} already exists.`);
         }
+        const candidate = request.type === 'priceMeasurement'
+            ? parseChartScene(promoteSceneToM2(this.#scene))
+            : this.#scene;
         const result = this.#chart.createOverlay(toEngineOverlayDrawing(structuredClone(request), this.#idMap, this.#overlayCallbacks(structuredClone(request), true)));
         if (result !== request.id) {
             throw new SceneError('RUNTIME_INIT_FAILED', '/overlays', `KLineCharts failed to start drawing Overlay ${request.id}.`);
         }
+        this.#scene = candidate;
+        if (request.type === 'priceMeasurement') {
+            this.#interactivePriceMeasurement = {
+                source: {
+                    ...structuredClone(request),
+                    type: 'priceMeasurement',
+                },
+            };
+        }
         return request.id;
     }
     getOverlay(id) {
-        return this.exportScene().overlays.find((overlay) => overlay.id === id);
+        this.#assertActive();
+        const overlay = this.#scene.overlays.find((candidate) => candidate.id === id);
+        return overlay === undefined ? undefined : structuredClone(overlay);
     }
     listOverlays() {
-        return this.exportScene().overlays;
+        this.#assertActive();
+        return structuredClone(this.#scene.overlays);
     }
     inspect() {
         this.#assertActive();
@@ -241,6 +704,7 @@ export class KLineChartsSceneAdapter {
         });
         return {
             engineVersion: this.#engine.version(),
+            runtimeVersion: this.#scene.runtime.runtimeVersion,
             dataCount: this.#chart.getDataList().length,
             paneIds: this.#scene.panes.map((pane) => pane.id),
             indicators,
@@ -253,7 +717,10 @@ export class KLineChartsSceneAdapter {
         if (this.#disposed) {
             return;
         }
+        this.#cancelInteraction('destroy');
+        this.#interactivePriceMeasurement = undefined;
         this.#disposed = true;
+        this.#removeInteractionListeners();
         this.#listeners.clear();
         this.#engine.dispose(this.#container);
         this.#container.replaceChildren();

package/dist/conversion/overlays.d.ts

@@ -18,9 +18,12 @@ export interface OverlayDrawingSource extends OverlaySourceSnapshot {
 }
 export interface EngineOverlayCallbacks {
     readonly onDrawEnd?: NonNullable<OverlayCreate['onDrawEnd']>;
+    readonly onPressedMoveStart?: NonNullable<OverlayCreate['onPressedMoveStart']>;
+    readonly onPressedMoving?: NonNullable<OverlayCreate['onPressedMoving']>;
     readonly onPressedMoveEnd?: NonNullable<OverlayCreate['onPressedMoveEnd']>;
     readonly onRemoved?: NonNullable<OverlayCreate['onRemoved']>;
     readonly onSelected?: NonNullable<OverlayCreate['onSelected']>;
+    readonly onDeselected?: NonNullable<OverlayCreate['onDeselected']>;
 }
 export declare function toEngineOverlay(overlay: SceneOverlay, idMap: EngineIdMap, path: string, callbacks?: EngineOverlayCallbacks): OverlayCreate;
 /** 创建尚无几何点的交互式 Overlay，不把临时状态写入 Scene。 */

package/dist/conversion/overlays.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"overlays.d.ts","sourceRoot":"","sources":["../../src/conversion/overlays.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,UAAU,EACV,YAAY,EACZ,MAAM,+BAA+B,CAAC;AAEvC,OAAO,KAAK,EAEX,OAAO,EACP,aAAa,EAGb,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAO/C,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;IACxC,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC,UAAU,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,oBAAqB,SAAQ,qBAAqB;IAClE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,SAAS,CAAC,EAAE,WAAW,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,CAAC;IAC7D,QAAQ,CAAC,gBAAgB,CAAC,EAAE,WAAW,CAAC,aAAa,CAAC,kBAAkB,CAAC,CAAC,CAAC;IAC3E,QAAQ,CAAC,SAAS,CAAC,EAAE,WAAW,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,CAAC;IAC7D,QAAQ,CAAC,UAAU,CAAC,EAAE,WAAW,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC;CAC/D;AAmGD,wBAAgB,eAAe,CAC9B,OAAO,EAAE,YAAY,EACrB,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,MAAM,EACZ,SAAS,GAAE,sBAA2B,GACpC,aAAa,CAwBf;AAED,0CAA0C;AAC1C,wBAAgB,sBAAsB,CACrC,MAAM,EAAE,oBAAoB,EAC5B,KAAK,EAAE,WAAW,EAClB,SAAS,EAAE,sBAAsB,GAC/B,aAAa,CAsBf;AAiED,wBAAgB,iBAAiB,CAChC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,qBAAqB,EAC7B,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,MAAM,GACpB,YAAY,CAiHd;AAED,qBAAqB;AACrB,wBAAgB,mBAAmB,CAClC,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE;IAAE,aAAa,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,GAAG,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;CAAE,EACpF,KAAK,EAAE,WAAW,EAClB,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,sBAAsB,GAC3D,IAAI,CAiBN"}
+{"version":3,"file":"overlays.d.ts","sourceRoot":"","sources":["../../src/conversion/overlays.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,UAAU,EACV,YAAY,EACZ,MAAM,+BAA+B,CAAC;AAEvC,OAAO,KAAK,EAEX,OAAO,EACP,aAAa,EAGb,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAO/C,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;IACxC,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC,UAAU,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,oBAAqB,SAAQ,qBAAqB;IAClE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,SAAS,CAAC,EAAE,WAAW,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,CAAC;IAC7D,QAAQ,CAAC,kBAAkB,CAAC,EAAE,WAAW,CAAC,aAAa,CAAC,oBAAoB,CAAC,CAAC,CAAC;IAC/E,QAAQ,CAAC,eAAe,CAAC,EAAE,WAAW,CAAC,aAAa,CAAC,iBAAiB,CAAC,CAAC,CAAC;IACzE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,WAAW,CAAC,aAAa,CAAC,kBAAkB,CAAC,CAAC,CAAC;IAC3E,QAAQ,CAAC,SAAS,CAAC,EAAE,WAAW,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,CAAC;IAC7D,QAAQ,CAAC,UAAU,CAAC,EAAE,WAAW,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC;IAC/D,QAAQ,CAAC,YAAY,CAAC,EAAE,WAAW,CAAC,aAAa,CAAC,cAAc,CAAC,CAAC,CAAC;CACnE;AAoGD,wBAAgB,eAAe,CAC9B,OAAO,EAAE,YAAY,EACrB,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,MAAM,EACZ,SAAS,GAAE,sBAA2B,GACpC,aAAa,CAwBf;AAED,0CAA0C;AAC1C,wBAAgB,sBAAsB,CACrC,MAAM,EAAE,oBAAoB,EAC5B,KAAK,EAAE,WAAW,EAClB,SAAS,EAAE,sBAAsB,GAC/B,aAAa,CAsBf;AAiED,wBAAgB,iBAAiB,CAChC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,qBAAqB,EAC7B,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,MAAM,GACpB,YAAY,CAkHd;AAED,qBAAqB;AACrB,wBAAgB,mBAAmB,CAClC,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE;IAAE,aAAa,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,GAAG,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;CAAE,EACpF,KAAK,EAAE,WAAW,EAClB,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,sBAAsB,GAC3D,IAAI,CAiBN"}