@baron1996/klinecharts-adapter 0.1.1 → 0.2.1

package/dist/adapter.d.ts

@@ -1,6 +1,10 @@
 import type { ChartScene, SceneIndicator, SceneOverlay } from '@baron1996/kline-scene-schema';
 import { SceneError } from '@baron1996/kline-scene-schema';
 import { type OverlayDrawingSource } from './conversion/overlays.js';
+import { type OverlayHitResult, type PixelCoordinate } from './interaction/hit-testing.js';
+export type PriceScale = 'linear' | 'logarithmic';
+export type AdapterDragTarget = 'body' | 'anchor';
+export type AdapterDragCancelReason = 'escape' | 'pointer-cancel' | 'window-blur' | 'destroy' | 'validation-error';
 export interface AdapterIndicatorSnapshot {
     readonly id: string;
     readonly name: SceneIndicator['name'];
@@ -9,6 +13,7 @@ export interface AdapterIndicatorSnapshot {
 }
 export interface AdapterSnapshot {
     readonly engineVersion: string;
+    readonly runtimeVersion: ChartScene['runtime']['runtimeVersion'];
     readonly dataCount: number;
     readonly paneIds: readonly string[];
     readonly indicators: readonly AdapterIndicatorSnapshot[];
@@ -16,19 +21,45 @@ export interface AdapterSnapshot {
     readonly barSpace: number;
     readonly rightOffsetDistance: number;
 }
+interface AdapterDragEventIdentity {
+    readonly interactionId: string;
+    readonly overlayId: string;
+    readonly target: AdapterDragTarget;
+    readonly anchorIndex: number | null;
+    readonly before: SceneOverlay;
+}
 export type AdapterSceneEvent = {
     readonly type: 'overlay-created';
     readonly overlay: SceneOverlay;
 } | {
     readonly type: 'overlay-updated';
     readonly overlay: SceneOverlay;
+} | {
+    readonly type: 'overlay-style-changed';
+    readonly before: SceneOverlay;
+    readonly overlay: SceneOverlay;
 } | {
     readonly type: 'overlay-removed';
     readonly id: string;
+} | {
+    readonly type: 'overlay-selection-changed';
+    readonly previousId: string | null;
+    readonly id: string | null;
 } | {
     readonly type: 'overlay-selected';
     readonly id: string;
-} | {
+} | ({
+    readonly type: 'overlay-drag-started';
+} & AdapterDragEventIdentity) | ({
+    readonly type: 'overlay-dragging';
+    readonly candidate: SceneOverlay;
+} & AdapterDragEventIdentity) | ({
+    readonly type: 'overlay-drag-committed';
+    readonly overlay: SceneOverlay;
+} & AdapterDragEventIdentity) | ({
+    readonly type: 'overlay-drag-cancelled';
+    readonly reason: AdapterDragCancelReason;
+} & AdapterDragEventIdentity) | {
     readonly type: 'scene-error';
     readonly issues: readonly SceneError['issues'][number][];
 };
@@ -45,8 +76,15 @@ export declare class KLineChartsSceneAdapter {
     static create(container: HTMLElement, value: unknown): Promise<KLineChartsSceneAdapter>;
     subscribe(listener: AdapterSceneEventListener): () => void;
     exportScene(): ChartScene;
+    setPriceScale(scale: PriceScale): Promise<ChartScene>;
+    projectPoint(point: {
+        readonly timestamp: number;
+        readonly value: number;
+    }, paneId?: string): PixelCoordinate;
+    hitTestOverlay(point: PixelCoordinate): OverlayHitResult | null;
     addOverlay(value: SceneOverlay): SceneOverlay;
     updateOverlay(value: SceneOverlay): SceneOverlay;
+    updateOverlayStyles(id: string, styles: SceneOverlay['styles']): SceneOverlay;
     removeOverlay(id: string): boolean;
     startOverlayDrawing(request: OverlayDrawingRequest): string;
     getOverlay(id: string): SceneOverlay | undefined;
@@ -54,4 +92,5 @@ export declare class KLineChartsSceneAdapter {
     inspect(): AdapterSnapshot;
     dispose(): void;
 }
+export {};
 //# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,UAAU,EACV,cAAc,EACd,YAAY,EACZ,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAEN,UAAU,EACV,MAAM,+BAA+B,CAAC;AAUvC,OAAO,EAIN,KAAK,oBAAoB,EAGzB,MAAM,0BAA0B,CAAC;AAGlC,MAAM,WAAW,wBAAwB;IACxC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,SAAS,wBAAwB,EAAE,CAAC;IACzD,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;CACrC;AAED,MAAM,MAAM,iBAAiB,GAC1B;IAAE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;CAAE,GACpE;IAAE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;CAAE,GACpE;IAAE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC1D;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE,CAAA;CAAE,CAAC;AAE9F,MAAM,MAAM,yBAAyB,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;AAE3E,MAAM,WAAW,qBAAsB,SAAQ,oBAAoB;CAAG;AAEtE;;;GAGG;AACH,qBAAa,uBAAuB;;IAkBnC,OAAO;WAea,MAAM,CACzB,SAAS,EAAE,WAAW,EACtB,KAAK,EAAE,OAAO,GACZ,OAAO,CAAC,uBAAuB,CAAC;IA+H5B,SAAS,CAAC,QAAQ,EAAE,yBAAyB,GAAG,MAAM,IAAI;IAQ1D,WAAW,IAAI,UAAU;IA0BzB,UAAU,CAAC,KAAK,EAAE,YAAY,GAAG,YAAY;IA4B7C,aAAa,CAAC,KAAK,EAAE,YAAY,GAAG,YAAY;IA6BhD,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAuBlC,mBAAmB,CAAC,OAAO,EAAE,qBAAqB,GAAG,MAAM;IAyB3D,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAIhD,YAAY,IAAI,SAAS,YAAY,EAAE;IAIvC,OAAO,IAAI,eAAe;IA8B1B,OAAO,IAAI,IAAI;CAUtB"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,UAAU,EACV,cAAc,EACd,YAAY,EACZ,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAEN,UAAU,EACV,MAAM,+BAA+B,CAAC;AAUvC,OAAO,EAIN,KAAK,oBAAoB,EAGzB,MAAM,0BAA0B,CAAC;AAMlC,OAAO,EAEN,KAAK,gBAAgB,EAErB,KAAK,eAAe,EACpB,MAAM,8BAA8B,CAAC;AAGtC,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,aAAa,CAAC;AAClD,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,QAAQ,CAAC;AAClD,MAAM,MAAM,uBAAuB,GAChC,QAAQ,GACR,gBAAgB,GAChB,aAAa,GACb,SAAS,GACT,kBAAkB,CAAC;AAEtB,MAAM,WAAW,wBAAwB;IACxC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,cAAc,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC,gBAAgB,CAAC,CAAC;IACjE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,SAAS,wBAAwB,EAAE,CAAC;IACzD,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;CACrC;AAED,UAAU,wBAAwB;IACjC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;CAC9B;AAED,MAAM,MAAM,iBAAiB,GAC1B;IAAE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;CAAE,GACpE;IAAE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;CAAE,GACpE;IAAE,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;CAAE,GACzG;IAAE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,QAAQ,CAAC,IAAI,EAAE,2BAA2B,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAC9G;IAAE,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC1D,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAA;CAAE,GAAG,wBAAwB,CAAC,GACtE,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAA;CAAE,GAAG,wBAAwB,CAAC,GACpG,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;CAAE,GAAG,wBAAwB,CAAC,GACxG,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAA;CAAE,GAAG,wBAAwB,CAAC,GAClH;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE,CAAA;CAAE,CAAC;AAE9F,MAAM,MAAM,yBAAyB,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;AAE3E,MAAM,WAAW,qBAAsB,SAAQ,oBAAoB;CAAG;AAkCtE;;;GAGG;AACH,qBAAa,uBAAuB;;IAwBnC,OAAO;WAgBa,MAAM,CACzB,SAAS,EAAE,WAAW,EACtB,KAAK,EAAE,OAAO,GACZ,OAAO,CAAC,uBAAuB,CAAC;IA0e5B,SAAS,CAAC,QAAQ,EAAE,yBAAyB,GAAG,MAAM,IAAI;IAQ1D,WAAW,IAAI,UAAU;IAenB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IA0C3D,YAAY,CAClB,KAAK,EAAE;QAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAC7D,MAAM,CAAC,EAAE,MAAM,GACb,eAAe;IAMX,cAAc,CAAC,KAAK,EAAE,eAAe,GAAG,gBAAgB,GAAG,IAAI;IAK/D,UAAU,CAAC,KAAK,EAAE,YAAY,GAAG,YAAY;IAiE7C,aAAa,CAAC,KAAK,EAAE,YAAY,GAAG,YAAY;IAIhD,mBAAmB,CACzB,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,YAAY,CAAC,QAAQ,CAAC,GAC5B,YAAY;IAQR,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IA0BlC,mBAAmB,CAAC,OAAO,EAAE,qBAAqB,GAAG,MAAM;IA6B3D,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAMhD,YAAY,IAAI,SAAS,YAAY,EAAE;IAKvC,OAAO,IAAI,eAAe;IA+B1B,OAAO,IAAI,IAAI;CAYtB"}

package/dist/adapter.js

@@ -2,9 +2,28 @@ 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 { 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 +35,7 @@ export class KLineChartsSceneAdapter {
     #engine;
     /** 场景 ID 与引擎内部 ID 的双向映射。 */
     #idMap;
-    /** 当前可导出的规范化场景。 */
+    /** 当前最后一次成功提交、可导出的规范化场景。 */
     #scene;
     /** 当前引擎容器。 */
     #container;
@@ -26,6 +45,12 @@ export class KLineChartsSceneAdapter {
     #disposed = false;
     /** 仅传递纯场景数据的事件订阅者。 */
     #listeners = new Set();
+    /** 当前选择状态，null 表示明确未选择。 */
+    #selectedOverlayId = null;
+    /** 当前受控拖动事务；progress 永不写入 #scene。 */
+    #pointerInteraction;
+    /** 确定性 opaque 交互 ID 序号。 */
+    #interactionSequence = 0;
     constructor(container, scene, handle, idMap, originalBackground) {
         this.#container = container;
         this.#scene = scene;
@@ -33,6 +58,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 +101,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}`;
@@ -101,11 +138,28 @@ export class KLineChartsSceneAdapter {
             onDrawEnd: ({ overlay }) => {
                 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.#scene.overlays.some((candidate) => candidate.id === overlay.id)) {
@@ -113,6 +167,9 @@ export class KLineChartsSceneAdapter {
                         ...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 +187,272 @@ 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 };
+    }
+    #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 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 +462,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 +527,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 +541,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 +575,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 +588,24 @@ 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;
         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 +624,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 +637,9 @@ export class KLineChartsSceneAdapter {
         if (this.#disposed) {
             return;
         }
+        this.#cancelInteraction('destroy');
         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"}

package/dist/conversion/overlays.js

@@ -81,6 +81,7 @@ function toPoints(overlay) {
             return [structuredClone(overlay.point ?? {})];
         case 'rectangle':
         case 'arrow':
+        case 'priceMeasurement':
             return [structuredClone(overlay.start ?? {}), structuredClone(overlay.end ?? {})];
     }
 }
@@ -278,6 +279,7 @@ export function fromEngineOverlay(engine, source, idMap, path, pricePrecision) {
             };
         case 'rectangle':
         case 'arrow':
+        case 'priceMeasurement':
             return {
                 ...base,
                 start: readPoint(0, true, true, `${path}/start`),

package/dist/conversion/panes.d.ts

@@ -1,6 +1,8 @@
-import type { ChartScene } from '@baron1996/kline-scene-schema';
+import type { ChartScene, YAxis as SceneYAxis } from '@baron1996/kline-scene-schema';
 import type { Chart } from 'klinecharts';
 import type { EngineIdMap } from './id-map.js';
+/** 原子提交 Scene 前，将单条轴映射到引擎的正式 normal/logarithm 名称。 */
+export declare function overrideSceneYAxis(chart: Chart, idMap: EngineIdMap, axis: SceneYAxis, paneId: string, path: string): void;
 /** 按 Scene 顺序创建 Pane、Y 轴和指标，并核对每个映射。 */
 export declare function applyPanes(scene: ChartScene, chart: Chart, idMap: EngineIdMap): void;
 //# sourceMappingURL=panes.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"panes.d.ts","sourceRoot":"","sources":["../../src/conversion/panes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAuB,MAAM,+BAA+B,CAAC;AAErF,OAAO,KAAK,EAAE,KAAK,EAAS,MAAM,aAAa,CAAC;AAEhD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AA8B/C,wCAAwC;AACxC,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAuEpF"}
+{"version":3,"file":"panes.d.ts","sourceRoot":"","sources":["../../src/conversion/panes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,KAAK,IAAI,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAErF,OAAO,KAAK,EAAE,KAAK,EAAS,MAAM,aAAa,CAAC;AAEhD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AA8B/C,qDAAqD;AACrD,wBAAgB,kBAAkB,CACjC,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACV,IAAI,CAIN;AAED,wCAAwC;AACxC,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAuEpF"}

package/dist/conversion/panes.js

@@ -5,7 +5,7 @@ function axisOverride(axis, enginePaneId, engineAxisId) {
     return {
         id: engineAxisId,
         paneId: enginePaneId,
-        name: 'normal',
+        name: axis.scale === 'logarithmic' ? 'logarithm' : 'normal',
         reverse: axis.reverse,
         inside: axis.inside,
         position: axis.position,
@@ -17,6 +17,12 @@ function axisOverride(axis, enginePaneId, engineAxisId) {
         needWidget: true,
     };
 }
+/** 原子提交 Scene 前，将单条轴映射到引擎的正式 normal/logarithm 名称。 */
+export function overrideSceneYAxis(chart, idMap, axis, paneId, path) {
+    const enginePaneId = requireMappedId(idMap.paneToEngine, paneId, `${path}/paneId`, 'Pane');
+    const engineAxisId = requireMappedId(idMap.yAxisToEngine, axis.id, `${path}/id`, 'Y-axis');
+    chart.overrideYAxis(axisOverride(axis, enginePaneId, engineAxisId));
+}
 /** 按 Scene 顺序创建 Pane、Y 轴和指标，并核对每个映射。 */
 export function applyPanes(scene, chart, idMap) {
     for (let paneIndex = 0; paneIndex < scene.panes.length; paneIndex++) {

package/dist/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAEhE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AASzC,MAAM,MAAM,iBAAiB,GAAG,cAAc,aAAa,CAAC,CAAC;AAE7D,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;CACnC;AAiBD,qCAAqC;AACrC,wBAAsB,YAAY,CACjC,SAAS,EAAE,WAAW,EACtB,KAAK,EAAE,UAAU,GACf,OAAO,CAAC,YAAY,CAAC,CA+BvB"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAEhE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAUzC,MAAM,MAAM,iBAAiB,GAAG,cAAc,aAAa,CAAC,CAAC;AAE7D,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;CACnC;AAmBD,qCAAqC;AACrC,wBAAsB,YAAY,CACjC,SAAS,EAAE,WAAW,EACtB,KAAK,EAAE,UAAU,GACf,OAAO,CAAC,YAAY,CAAC,CA+BvB"}

package/dist/engine.js

@@ -1,13 +1,13 @@
 import { SceneError } from '@baron1996/kline-scene-schema';
 import { toKLineChartsOptions } from './conversion/chart-options.js';
 import { createStaticDataLoader } from './static-data-loader.js';
-import { KLINECHARTS_ENGINE_VERSION, KLINECHARTS_RUNTIME_VERSION, } from './version.js';
+import { KLINECHARTS_ENGINE_VERSION, KLINECHARTS_RUNTIME_VERSION, SUPPORTED_KLINECHARTS_RUNTIME_VERSIONS, } from './version.js';
 function assertRuntimeIdentity(scene, actualEngineVersion) {
     if (scene.runtime.engine !== 'klinecharts' ||
         scene.runtime.engineVersion !== KLINECHARTS_ENGINE_VERSION ||
         actualEngineVersion !== KLINECHARTS_ENGINE_VERSION ||
-        scene.runtime.runtimeVersion !== KLINECHARTS_RUNTIME_VERSION) {
-        throw new SceneError('ENGINE_VERSION_MISMATCH', '/runtime', `Expected klinecharts ${KLINECHARTS_ENGINE_VERSION} and Runtime ${KLINECHARTS_RUNTIME_VERSION}; received engine ${actualEngineVersion}.`);
+        !SUPPORTED_KLINECHARTS_RUNTIME_VERSIONS.includes(scene.runtime.runtimeVersion)) {
+        throw new SceneError('ENGINE_VERSION_MISMATCH', '/runtime', `Expected klinecharts ${KLINECHARTS_ENGINE_VERSION} and a supported Runtime through ${KLINECHARTS_RUNTIME_VERSION}; received engine ${actualEngineVersion}.`);
     }
 }
 /** 按固定顺序创建并初始化唯一的 KLineCharts 引擎。 */

package/dist/extensions/price-measurement.d.ts

@@ -0,0 +1,13 @@
+import type { registerOverlay } from 'klinecharts';
+type KLineOverlayTemplate = Parameters<typeof registerOverlay>[0];
+export interface PriceMeasurementDisplay {
+    readonly absoluteChange: number;
+    readonly percentageChange: number;
+    readonly label: string;
+}
+/** 仅派生显示值；绝对变化、百分比和 label 永不写入 Scene。 */
+export declare function derivePriceMeasurementDisplay(startValue: number, endValue: number, pricePrecision: number): PriceMeasurementDisplay;
+/** 量度工具只从两个引擎数据点派生显示文字，派生值不进入 Scene。 */
+export declare const priceMeasurementOverlay: KLineOverlayTemplate;
+export {};
+//# sourceMappingURL=price-measurement.d.ts.map

package/dist/extensions/price-measurement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"price-measurement.d.ts","sourceRoot":"","sources":["../../src/extensions/price-measurement.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGnD,KAAK,oBAAoB,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;AAOlE,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACvB;AAED,yCAAyC;AACzC,wBAAgB,6BAA6B,CAC5C,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,GACpB,uBAAuB,CAsBzB;AAED,wCAAwC;AACxC,eAAO,MAAM,uBAAuB,EAAE,oBA6CrC,CAAC"}

package/dist/extensions/price-measurement.js

@@ -0,0 +1,64 @@
+import { SceneError } from '@baron1996/kline-scene-schema';
+function signedFixed(value, precision) {
+    const prefix = value > 0 ? '+' : '';
+    return `${prefix}${value.toFixed(precision)}`;
+}
+/** 仅派生显示值；绝对变化、百分比和 label 永不写入 Scene。 */
+export function derivePriceMeasurementDisplay(startValue, endValue, pricePrecision) {
+    if (!Number.isFinite(startValue) ||
+        !Number.isFinite(endValue) ||
+        startValue <= 0 ||
+        !Number.isInteger(pricePrecision) ||
+        pricePrecision < 0 ||
+        pricePrecision > 16) {
+        throw new SceneError('SCENE_SCHEMA_INVALID', '/overlays/priceMeasurement', 'Price measurement display inputs must be positive finite prices and a 0..16 precision.');
+    }
+    const absoluteChange = endValue - startValue;
+    const percentageChange = absoluteChange / startValue * 100;
+    return {
+        absoluteChange,
+        percentageChange,
+        label: `${signedFixed(absoluteChange, pricePrecision)} (${signedFixed(percentageChange, 2)}%)`,
+    };
+}
+/** 量度工具只从两个引擎数据点派生显示文字，派生值不进入 Scene。 */
+export const priceMeasurementOverlay = {
+    name: 'priceMeasurement',
+    totalStep: 3,
+    needDefaultPointFigure: true,
+    needDefaultXAxisFigure: true,
+    needDefaultYAxisFigure: true,
+    createPointFigures: ({ chart, coordinates, overlay }) => {
+        const startCoordinate = coordinates[0];
+        const endCoordinate = coordinates[1];
+        const startPoint = overlay.points[0];
+        const endPoint = overlay.points[1];
+        if (startCoordinate === undefined ||
+            endCoordinate === undefined ||
+            startPoint?.value === undefined ||
+            endPoint?.value === undefined) {
+            return [];
+        }
+        const pricePrecision = chart.getSymbol()?.pricePrecision ?? 0;
+        const { label } = derivePriceMeasurementDisplay(startPoint.value, endPoint.value, pricePrecision);
+        return [
+            {
+                key: 'measurement-body',
+                type: 'line',
+                attrs: { coordinates: [startCoordinate, endCoordinate] },
+            },
+            {
+                key: 'measurement-label',
+                type: 'text',
+                attrs: {
+                    x: (startCoordinate.x + endCoordinate.x) / 2 + 8,
+                    y: (startCoordinate.y + endCoordinate.y) / 2 - 8,
+                    text: label,
+                    align: 'left',
+                    baseline: 'bottom',
+                },
+                ignoreEvent: true,
+            },
+        ];
+    },
+};

package/dist/extensions/register.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../src/extensions/register.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAQnD,KAAK,oBAAoB,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;AAClE,KAAK,eAAe,GAAG,CAAC,QAAQ,EAAE,oBAAoB,KAAK,IAAI,CAAC;AAYhE,kCAAkC;AAClC,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAQvE;AAED,wBAAgB,4BAA4B,IAAI,OAAO,CAEtD"}
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../src/extensions/register.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AASnD,KAAK,oBAAoB,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;AAClE,KAAK,eAAe,GAAG,CAAC,QAAQ,EAAE,oBAAoB,KAAK,IAAI,CAAC;AAahE,kCAAkC;AAClC,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAQvE;AAED,wBAAgB,4BAA4B,IAAI,OAAO,CAEtD"}

package/dist/extensions/register.js

@@ -2,8 +2,10 @@ import { arrowOverlay } from './arrow.js';
 import { calloutOverlay } from './callout.js';
 import { crossLineOverlay } from './cross-line.js';
 import { rectangleOverlay } from './rectangle.js';
+import { priceMeasurementOverlay } from './price-measurement.js';
 import { textOverlay } from './text.js';
 const projectExtensions = [
+    priceMeasurementOverlay,
     rectangleOverlay,
     arrowOverlay,
     crossLineOverlay,

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export * from './adapter.js';
 export * from './errors.js';
 export * from './extensions/register.js';
+export * from './interaction/dragging.js';
+export * from './interaction/hit-testing.js';
 export * from './registry/indicators.js';
 export * from './registry/overlays.js';
 export * from './static-data-loader.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,cAAc,CAAC"}

package/dist/index.js

@@ -1,6 +1,8 @@
 export * from './adapter.js';
 export * from './errors.js';
 export * from './extensions/register.js';
+export * from './interaction/dragging.js';
+export * from './interaction/hit-testing.js';
 export * from './registry/indicators.js';
 export * from './registry/overlays.js';
 export * from './static-data-loader.js';

package/dist/interaction/dragging.d.ts

@@ -0,0 +1,12 @@
+import type { SceneOverlay } from '@baron1996/kline-scene-schema';
+export interface DragDataPoint {
+    readonly dataIndex: number;
+    readonly value: number;
+}
+export interface DragTarget {
+    readonly target: 'anchor' | 'body';
+    readonly anchorIndex: number | null;
+}
+/** 根据冻结的绝对平移语义构造未提交候选，不修改输入 Overlay。 */
+export declare function createDragCandidate(before: SceneOverlay, dragTarget: DragTarget, origin: DragDataPoint, current: DragDataPoint, timestamps: readonly number[], pricePrecision: number): SceneOverlay;
+//# sourceMappingURL=dragging.d.ts.map

package/dist/interaction/dragging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dragging.d.ts","sourceRoot":"","sources":["../../src/interaction/dragging.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAKlE,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAyBD,wCAAwC;AACxC,wBAAgB,mBAAmB,CAClC,MAAM,EAAE,YAAY,EACpB,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,aAAa,EACtB,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,cAAc,EAAE,MAAM,GACpB,YAAY,CAgFd"}

package/dist/interaction/dragging.js

@@ -0,0 +1,71 @@
+import { SceneError } from '@baron1996/kline-scene-schema';
+import { normalizePriceValue } from '../conversion/price.js';
+function requireDataIndex(value, path) {
+    if (!Number.isFinite(value)) {
+        throw new SceneError('INVALID_REFERENCE', path, 'Drag data index must be finite.');
+    }
+    return Math.round(value);
+}
+function requireTimestamp(timestamps, index, path) {
+    const timestamp = timestamps[index];
+    if (timestamp === undefined) {
+        throw new SceneError('INVALID_REFERENCE', path, 'Drag candidate must remain on an embedded market-data bar.');
+    }
+    return timestamp;
+}
+/** 根据冻结的绝对平移语义构造未提交候选，不修改输入 Overlay。 */
+export function createDragCandidate(before, dragTarget, origin, current, timestamps, pricePrecision) {
+    const deltaValue = current.value - origin.value;
+    if (!Number.isFinite(deltaValue)) {
+        throw new SceneError('SCENE_SCHEMA_INVALID', '/overlays', 'Drag price delta must be finite.');
+    }
+    if (before.type === 'horizontalStraightLine') {
+        const anchor = before.anchor;
+        if (anchor === undefined || !('value' in anchor)) {
+            throw new SceneError('SCENE_SCHEMA_INVALID', '/overlays/anchor', 'Missing price anchor.');
+        }
+        return {
+            ...structuredClone(before),
+            anchor: {
+                value: normalizePriceValue(anchor.value + deltaValue, pricePrecision, '/overlays/anchor/value'),
+            },
+        };
+    }
+    if (before.type !== 'priceMeasurement' || before.start === undefined || before.end === undefined) {
+        throw new SceneError('SCENE_SCHEMA_INVALID', '/overlays/type', 'Controlled M2 dragging only supports horizontalStraightLine and priceMeasurement.');
+    }
+    const candidate = structuredClone(before);
+    if (dragTarget.target === 'anchor') {
+        if (dragTarget.anchorIndex !== 0 && dragTarget.anchorIndex !== 1) {
+            throw new SceneError('INVALID_REFERENCE', '/overlays/anchorIndex', 'Invalid anchor index.');
+        }
+        const index = requireDataIndex(current.dataIndex, '/overlays/anchor/dataIndex');
+        const point = {
+            timestamp: requireTimestamp(timestamps, index, '/overlays/anchor/timestamp'),
+            value: normalizePriceValue(current.value, pricePrecision, '/overlays/anchor/value'),
+        };
+        if (dragTarget.anchorIndex === 0) {
+            candidate.start = point;
+        }
+        else {
+            candidate.end = point;
+        }
+        return candidate;
+    }
+    const startIndex = timestamps.indexOf(before.start.timestamp);
+    const endIndex = timestamps.indexOf(before.end.timestamp);
+    if (startIndex < 0 || endIndex < 0) {
+        throw new SceneError('INVALID_REFERENCE', '/overlays', 'priceMeasurement endpoints must reference embedded bars before dragging.');
+    }
+    const deltaIndex = requireDataIndex(current.dataIndex, '/overlays/body/dataIndex') -
+        requireDataIndex(origin.dataIndex, '/overlays/body/originDataIndex');
+    candidate.start = {
+        timestamp: requireTimestamp(timestamps, startIndex + deltaIndex, '/overlays/start/timestamp'),
+        value: normalizePriceValue(before.start.value + deltaValue, pricePrecision, '/overlays/start/value'),
+    };
+    candidate.end = {
+        timestamp: requireTimestamp(timestamps, endIndex + deltaIndex, '/overlays/end/timestamp'),
+        value: normalizePriceValue(before.end.value + deltaValue, pricePrecision, '/overlays/end/value'),
+    };
+    return candidate;
+}

package/dist/interaction/hit-testing.d.ts

@@ -0,0 +1,26 @@
+export declare const OVERLAY_BODY_HIT_THRESHOLD_CSS_PX = 12;
+export declare const OVERLAY_ANCHOR_HIT_THRESHOLD_CSS_PX = 14;
+export interface PixelCoordinate {
+    readonly x: number;
+    readonly y: number;
+}
+export interface OverlayPixelGeometry {
+    readonly overlayId: string;
+    readonly sceneIndex: number;
+    readonly zLevel: number;
+    readonly locked: boolean;
+    readonly anchors: readonly PixelCoordinate[];
+    readonly bodySegments: readonly (readonly [PixelCoordinate, PixelCoordinate])[];
+}
+export interface OverlayHitResult {
+    readonly overlayId: string;
+    readonly target: 'anchor' | 'body';
+    readonly anchorIndex: number | null;
+    readonly locked: boolean;
+}
+/**
+ * 按冻结契约在 CSS 像素坐标中执行命中测试。
+ * 锚点全局优先于主体；同类再按 zLevel、Scene 后序和锚点低索引排序。
+ */
+export declare function hitTestOverlayGeometries(point: PixelCoordinate, geometries: readonly OverlayPixelGeometry[]): OverlayHitResult | null;
+//# sourceMappingURL=hit-testing.d.ts.map

package/dist/interaction/hit-testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hit-testing.d.ts","sourceRoot":"","sources":["../../src/interaction/hit-testing.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iCAAiC,KAAK,CAAC;AACpD,eAAO,MAAM,mCAAmC,KAAK,CAAC;AAEtD,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC,SAAS,CAAC,eAAe,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC;CAChF;AAED,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CACzB;AAmDD;;;GAGG;AACH,wBAAgB,wBAAwB,CACvC,KAAK,EAAE,eAAe,EACtB,UAAU,EAAE,SAAS,oBAAoB,EAAE,GACzC,gBAAgB,GAAG,IAAI,CAgDzB"}

package/dist/interaction/hit-testing.js

@@ -0,0 +1,86 @@
+export const OVERLAY_BODY_HIT_THRESHOLD_CSS_PX = 12;
+export const OVERLAY_ANCHOR_HIT_THRESHOLD_CSS_PX = 14;
+function coordinateDistance(left, right) {
+    return Math.hypot(left.x - right.x, left.y - right.y);
+}
+function segmentDistance(point, start, end) {
+    const dx = end.x - start.x;
+    const dy = end.y - start.y;
+    const lengthSquared = dx * dx + dy * dy;
+    if (lengthSquared === 0) {
+        return coordinateDistance(point, start);
+    }
+    const projection = Math.max(0, Math.min(1, ((point.x - start.x) * dx + (point.y - start.y) * dy) / lengthSquared));
+    return coordinateDistance(point, {
+        x: start.x + projection * dx,
+        y: start.y + projection * dy,
+    });
+}
+function compareHits(left, right) {
+    if (left.zLevel !== right.zLevel) {
+        return right.zLevel - left.zLevel;
+    }
+    if (left.sceneIndex !== right.sceneIndex) {
+        return right.sceneIndex - left.sceneIndex;
+    }
+    if (left.overlayId === right.overlayId &&
+        left.anchorIndex !== null &&
+        right.anchorIndex !== null &&
+        left.anchorIndex !== right.anchorIndex) {
+        return left.anchorIndex - right.anchorIndex;
+    }
+    return left.distance - right.distance;
+}
+/**
+ * 按冻结契约在 CSS 像素坐标中执行命中测试。
+ * 锚点全局优先于主体；同类再按 zLevel、Scene 后序和锚点低索引排序。
+ */
+export function hitTestOverlayGeometries(point, geometries) {
+    const anchorHits = [];
+    const bodyHits = [];
+    for (const geometry of geometries) {
+        for (let anchorIndex = 0; anchorIndex < geometry.anchors.length; anchorIndex++) {
+            const anchor = geometry.anchors[anchorIndex];
+            if (anchor === undefined) {
+                continue;
+            }
+            const distance = coordinateDistance(point, anchor);
+            if (distance <= OVERLAY_ANCHOR_HIT_THRESHOLD_CSS_PX) {
+                anchorHits.push({
+                    overlayId: geometry.overlayId,
+                    target: 'anchor',
+                    anchorIndex,
+                    locked: geometry.locked,
+                    distance,
+                    sceneIndex: geometry.sceneIndex,
+                    zLevel: geometry.zLevel,
+                });
+            }
+        }
+        let distance = Number.POSITIVE_INFINITY;
+        for (const [start, end] of geometry.bodySegments) {
+            distance = Math.min(distance, segmentDistance(point, start, end));
+        }
+        if (distance <= OVERLAY_BODY_HIT_THRESHOLD_CSS_PX) {
+            bodyHits.push({
+                overlayId: geometry.overlayId,
+                target: 'body',
+                anchorIndex: null,
+                locked: geometry.locked,
+                distance,
+                sceneIndex: geometry.sceneIndex,
+                zLevel: geometry.zLevel,
+            });
+        }
+    }
+    const winner = (anchorHits.length > 0 ? anchorHits : bodyHits).sort(compareHits)[0];
+    if (winner === undefined) {
+        return null;
+    }
+    return {
+        overlayId: winner.overlayId,
+        target: winner.target,
+        anchorIndex: winner.anchorIndex,
+        locked: winner.locked,
+    };
+}

package/dist/interaction/selection-arbitration.d.ts

@@ -0,0 +1,6 @@
+import { type OverlayPixelGeometry, type PixelCoordinate } from './hit-testing.js';
+/**
+ * 仅忽略引擎旧命中区域产生的取消选择：回调坐标必须仍命中当前选中 Overlay 的规范几何。
+ */
+export declare function shouldIgnoreStaleOverlayDeselection(selectedOverlayId: string | null, deselectedOverlayId: string, coordinate: PixelCoordinate | undefined, currentGeometries: readonly OverlayPixelGeometry[]): boolean;
+//# sourceMappingURL=selection-arbitration.d.ts.map

package/dist/interaction/selection-arbitration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selection-arbitration.d.ts","sourceRoot":"","sources":["../../src/interaction/selection-arbitration.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,MAAM,kBAAkB,CAAC;AAE1B;;GAEG;AACH,wBAAgB,mCAAmC,CAClD,iBAAiB,EAAE,MAAM,GAAG,IAAI,EAChC,mBAAmB,EAAE,MAAM,EAC3B,UAAU,EAAE,eAAe,GAAG,SAAS,EACvC,iBAAiB,EAAE,SAAS,oBAAoB,EAAE,GAChD,OAAO,CAKT"}

package/dist/interaction/selection-arbitration.js

@@ -0,0 +1,10 @@
+import { hitTestOverlayGeometries, } from './hit-testing.js';
+/**
+ * 仅忽略引擎旧命中区域产生的取消选择：回调坐标必须仍命中当前选中 Overlay 的规范几何。
+ */
+export function shouldIgnoreStaleOverlayDeselection(selectedOverlayId, deselectedOverlayId, coordinate, currentGeometries) {
+    if (selectedOverlayId !== deselectedOverlayId || coordinate === undefined) {
+        return false;
+    }
+    return hitTestOverlayGeometries(coordinate, currentGeometries)?.overlayId === deselectedOverlayId;
+}

package/dist/registry/overlays.d.ts

@@ -1,6 +1,6 @@
 import type { SceneOverlay } from '@baron1996/kline-scene-schema';
 export declare const BUILT_IN_OVERLAYS: readonly ["horizontalRayLine", "horizontalSegment", "horizontalStraightLine", "verticalRayLine", "verticalSegment", "verticalStraightLine", "rayLine", "segment", "straightLine", "priceLine", "priceChannelLine", "parallelStraightLine", "fibonacciLine", "brush", "simpleAnnotation", "simpleTag"];
-export declare const PROJECT_OVERLAYS: readonly ["rectangle", "arrow", "crossLine", "callout", "text"];
-export declare const SUPPORTED_OVERLAYS: readonly ["horizontalRayLine", "horizontalSegment", "horizontalStraightLine", "verticalRayLine", "verticalSegment", "verticalStraightLine", "rayLine", "segment", "straightLine", "priceLine", "priceChannelLine", "parallelStraightLine", "fibonacciLine", "brush", "simpleAnnotation", "simpleTag", "rectangle", "arrow", "crossLine", "callout", "text"];
+export declare const PROJECT_OVERLAYS: readonly ["priceMeasurement", "rectangle", "arrow", "crossLine", "callout", "text"];
+export declare const SUPPORTED_OVERLAYS: readonly ["horizontalRayLine", "horizontalSegment", "horizontalStraightLine", "verticalRayLine", "verticalSegment", "verticalStraightLine", "rayLine", "segment", "straightLine", "priceLine", "priceChannelLine", "parallelStraightLine", "fibonacciLine", "brush", "simpleAnnotation", "simpleTag", "priceMeasurement", "rectangle", "arrow", "crossLine", "callout", "text"];
 export declare function isSupportedOverlay(name: string): name is SceneOverlay['type'];
 //# sourceMappingURL=overlays.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"overlays.d.ts","sourceRoot":"","sources":["../../src/registry/overlays.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAElE,eAAO,MAAM,iBAAiB,uSAiBsB,CAAC;AAErD,eAAO,MAAM,gBAAgB,iEAMuB,CAAC;AAErD,eAAO,MAAM,kBAAkB,6VAGqB,CAAC;AAIrD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,YAAY,CAAC,MAAM,CAAC,CAE7E"}
+{"version":3,"file":"overlays.d.ts","sourceRoot":"","sources":["../../src/registry/overlays.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAElE,eAAO,MAAM,iBAAiB,uSAiBsB,CAAC;AAErD,eAAO,MAAM,gBAAgB,qFAOuB,CAAC;AAErD,eAAO,MAAM,kBAAkB,iXAGqB,CAAC;AAIrD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,YAAY,CAAC,MAAM,CAAC,CAE7E"}

package/dist/registry/overlays.js

@@ -17,6 +17,7 @@ export const BUILT_IN_OVERLAYS = [
     'simpleTag',
 ];
 export const PROJECT_OVERLAYS = [
+    'priceMeasurement',
     'rectangle',
     'arrow',
     'crossLine',

package/dist/version.d.ts

@@ -1,7 +1,8 @@
 /** Adapter 包版本。 */
-export declare const ADAPTER_PACKAGE_VERSION: "0.1.1";
+export declare const ADAPTER_PACKAGE_VERSION: "0.2.1";
 /** 唯一允许加载的 KLineCharts 引擎版本。 */
 export declare const KLINECHARTS_ENGINE_VERSION: "10.0.0";
 /** 与 ChartScene 绑定的 Runtime 协议版本。 */
-export declare const KLINECHARTS_RUNTIME_VERSION: "0.1.0";
+export declare const KLINECHARTS_RUNTIME_VERSION: "0.2.0";
+export declare const SUPPORTED_KLINECHARTS_RUNTIME_VERSIONS: readonly ["0.1.0", "0.2.0"];
 //# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,mBAAmB;AACnB,eAAO,MAAM,uBAAuB,EAAG,OAAgB,CAAC;AAExD,gCAAgC;AAChC,eAAO,MAAM,0BAA0B,EAAG,QAAiB,CAAC;AAE5D,qCAAqC;AACrC,eAAO,MAAM,2BAA2B,EAAG,OAAgB,CAAC"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,mBAAmB;AACnB,eAAO,MAAM,uBAAuB,EAAG,OAAgB,CAAC;AAExD,gCAAgC;AAChC,eAAO,MAAM,0BAA0B,EAAG,QAAiB,CAAC;AAE5D,qCAAqC;AACrC,eAAO,MAAM,2BAA2B,EAAG,OAAgB,CAAC;AAC5D,eAAO,MAAM,sCAAsC,6BAA8B,CAAC"}

package/dist/version.js

@@ -1,6 +1,7 @@
 /** Adapter 包版本。 */
-export const ADAPTER_PACKAGE_VERSION = '0.1.1';
+export const ADAPTER_PACKAGE_VERSION = '0.2.1';
 /** 唯一允许加载的 KLineCharts 引擎版本。 */
 export const KLINECHARTS_ENGINE_VERSION = '10.0.0';
 /** 与 ChartScene 绑定的 Runtime 协议版本。 */
-export const KLINECHARTS_RUNTIME_VERSION = '0.1.0';
+export const KLINECHARTS_RUNTIME_VERSION = '0.2.0';
+export const SUPPORTED_KLINECHARTS_RUNTIME_VERSIONS = ['0.1.0', '0.2.0'];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@baron1996/klinecharts-adapter",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Controlled ChartScene adapter for KLineCharts.",
   "type": "module",
   "license": "Apache-2.0",
@@ -38,7 +38,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@baron1996/kline-scene-schema": "0.1.0",
+    "@baron1996/kline-scene-schema": "0.2.1",
     "klinecharts": "10.0.0"
   }
 }