@baron1996/klinecharts-adapter 0.1.0 → 0.2.1

package/README.md

@@ -8,3 +8,9 @@ npm install @baron1996/klinecharts-adapter
 
 The adapter loads only scene-owned static data, maps supported panes, indicators and
 overlays, and owns chart lifecycle and touch gestures. KLineCharts is the only engine.
+
+At the engine-to-Scene boundary, every price-bearing Overlay coordinate is normalized
+to `scene.symbol.pricePrecision` (validated as `0..16`). Normalization uses the finite
+JavaScript Number's decimal representation, rounds to nearest with exact halfway values
+away from zero, rejects non-finite input/output, and canonicalizes negative zero to
+positive zero. Timestamp coordinates are never changed by this rule.

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;IAyH5B,SAAS,CAAC,QAAQ,EAAE,yBAAyB,GAAG,MAAM,IAAI;IAQ1D,WAAW,IAAI,UAAU;IAoBzB,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":"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"}

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,11 +101,22 @@ 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}`;
         const currentSource = existingIndex < 0 ? source : this.#scene.overlays[existingIndex];
-        const overlay = fromEngineOverlay(engineOverlay, currentSource, this.#idMap, path);
+        const overlay = fromEngineOverlay(engineOverlay, currentSource, this.#idMap, path, this.#scene.symbol.pricePrecision);
         const overlays = structuredClone(this.#scene.overlays);
         if (existingIndex < 0) {
             overlays.push(overlay);
@@ -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}`);
-        });
-        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();