@baron1996/klinecharts-adapter 0.9.4 → 0.9.7

package/dist/adapter.js

@@ -8,12 +8,15 @@ import { createSceneOverlays, fromEngineOverlay, normalizeSceneOverlayPrices, to
 import { normalizePriceValue } from './conversion/price.js';
 import { applyViewport } from './conversion/viewport.js';
 import { createStaticDataLoader } from './static-data-loader.js';
+import { assertGapAwareSceneSupported, engineDataForScene, GAP_AWARE_CANDLE_INDICATOR_ID, gapCount, installGapAwareMainSeries, isGapAwareScene, timelineItemOf, timelineSlotCount, } from './gap-aware-series.js';
 import { toOverlayStyles } from './conversion/overlays.js';
 import { drawingToSceneOverlay, sceneOverlayToDrawing, } from './drawing/overlay-conversion.js';
 import { MainSeriesPresentationError, presentationToSceneCandle, STANDARD_CLOSE_LINE_PRESENTATION, } from './main-series-presentation.js';
 import { createDragCandidate, } from './interaction/dragging.js';
-import { hitTestOverlayGeometries, } from './interaction/hit-testing.js';
+import { DEFAULT_OVERLAY_MOUSE_HIT_TOLERANCE, DEFAULT_OVERLAY_TOUCH_HIT_TOLERANCE, hitTestOverlayGeometries, } from './interaction/hit-testing.js';
+import { projectOverlayGeometry } from './interaction/overlay-geometry.js';
 import { shouldIgnoreStaleOverlayDeselection } from './interaction/selection-arbitration.js';
+import { isTouchPrecisionTap, resolveTouchPrecisionCursor, TouchPrecisionDrawingGuide, } from './interaction/touch-precision-drawing.js';
 function promoteSceneToM2(scene, scale) {
     const candidate = structuredClone(scene);
     candidate.runtime.runtimeVersion = '0.2.0';
@@ -41,12 +44,19 @@ export class KLineChartsSceneAdapter {
     #engine;
     /** 引擎点击仲裁显式复位；每次绘制开始前调用，保证新绘制首击独立成单击。 */
     #resetClickArbitration;
+    /** 向引擎派发鼠标移动语义，供触摸虚拟光标复用原生绘制预览。 */
+    #dispatchEngineMouseMove;
+    /** 向引擎派发鼠标单击语义，供触摸轻点复用原生绘制落点。 */
+    #dispatchEngineMouseClick;
     /** 引擎十字线动作监听器集合。 */
     #crosshairListeners = new Set();
     /** 引擎十字线动作退订函数。 */
     #unsubscribeCrosshair = null;
     /** 引擎十字线动作的绑定处理函数。 */
     #handleCrosshairChange = (payload) => {
+        if (this.#chartInteractionSnapshot !== undefined) {
+            return;
+        }
         const event = (typeof payload === 'object' && payload !== null
             ? payload
             : {});
@@ -74,14 +84,16 @@ export class KLineChartsSceneAdapter {
         }
         const match = barIndex === null ? undefined : data[barIndex];
         const timestamp = match?.timestamp ?? null;
-        const bar = match === undefined
+        const timelineItem = timelineItemOf(match);
+        const source = timelineItem?.kind === 'bar' ? timelineItem.bar : match;
+        const bar = source === undefined || timelineItem?.kind === 'gap'
             ? null
             : {
-                open: match.open,
-                high: match.high,
-                low: match.low,
-                close: match.close,
-                volume: match.volume ?? null,
+                open: source.open,
+                high: source.high,
+                low: source.low,
+                close: source.close,
+                volume: source.volume ?? null,
             };
         const snapshot = { timestamp, bar };
         for (const listener of this.#crosshairListeners) {
@@ -102,12 +114,26 @@ export class KLineChartsSceneAdapter {
     #listeners = new Set();
     /** 当前选择状态，null 表示明确未选择。 */
     #selectedOverlayId = null;
+    /** 独占选择前的图表交互状态，用于无损恢复宿主原配置。 */
+    #chartInteractionSnapshot;
+    /** 点击空白退出编辑时被完整消费的 Pointer ID。 */
+    #deselectingPointerId;
     /** 当前受控拖动事务；progress 永不写入 #scene。 */
     #pointerInteraction;
     /** 当前交互式量度的首锚点；只用于补偿引擎丢弃快速第二击，不进入 Scene。 */
     #interactivePriceMeasurement;
     /** 当前引擎进行中的绘制 Overlay ID；非 null 时 pointerdown 只路由给新绘制，不做命中测试。 */
     #drawingInProgressId = null;
+    /** 宿主显式开启的 Drawing 输入策略；未配置时保持引擎原生行为。 */
+    #drawingInteraction;
+    /** 触摸精确绘制的通用提示与虚拟光标层。 */
+    #touchPrecisionGuide;
+    /** 当前允许切换到触摸精确交互的线段绘制。 */
+    #touchPrecisionDrawing;
+    /** 当前单指定位手势；拖动只更新光标，轻点才确认。 */
+    #touchPrecisionPointer;
+    /** 阻断触摸结束后浏览器补发的兼容鼠标事件。 */
+    #suppressCompatibilityMouseUntil = 0;
     /** 确定性 opaque 交互 ID 序号。 */
     #interactionSequence = 0;
     /** 显式 Workspace 模式；Legacy 与 Workspace 状态严格隔离。 */
@@ -135,14 +161,19 @@ export class KLineChartsSceneAdapter {
         horizontal: false,
         vertical: false,
     };
-    constructor(container, scene, handle, idMap, originalBackground) {
+    constructor(container, scene, handle, idMap, originalBackground, drawingInteraction = {}) {
         this.#container = container;
         this.#scene = scene;
         this.#chart = handle.chart;
         this.#engine = handle.module;
         this.#resetClickArbitration = handle.resetClickArbitration;
+        this.#dispatchEngineMouseMove = handle.dispatchMouseMove;
+        this.#dispatchEngineMouseClick = handle.dispatchMouseClick;
         this.#idMap = idMap;
         this.#originalBackground = originalBackground;
+        this.#drawingInteraction = structuredClone(drawingInteraction);
+        this.#hitTolerance('mouse');
+        this.#hitTolerance('touch');
         this.#installInteractionListeners();
         this.#chart.subscribeAction('onCrosshairChange', this.#handleCrosshairChange);
         this.#unsubscribeCrosshair = () => {
@@ -156,6 +187,7 @@ export class KLineChartsSceneAdapter {
         let adapter;
         try {
             handle = await createEngine(container, scene);
+            installGapAwareMainSeries(scene, handle.chart, handle.module.registerIndicator);
             registerProjectOverlays(handle.module.registerOverlay);
             const idMap = createEngineIdMap(scene, handle.chart);
             applyPanes(scene, handle.chart, idMap);
@@ -193,10 +225,11 @@ export class KLineChartsSceneAdapter {
                     ? {}
                     : { displayTimezone: options.displayTimezone }),
             });
+            installGapAwareMainSeries(scene, handle.chart, handle.module.registerIndicator);
             registerProjectOverlays(handle.module.registerOverlay);
             const idMap = createEngineIdMap(scene, handle.chart);
             applyPanes(scene, handle.chart, idMap);
-            adapter = new KLineChartsSceneAdapter(container, scene, handle, idMap, originalBackground);
+            adapter = new KLineChartsSceneAdapter(container, scene, handle, idMap, originalBackground, options?.drawingInteraction);
             applyViewport(handle.chart, scene.viewport);
             container.style.backgroundColor = scene.chart.layout.backgroundColor;
             adapter.#workspaceMode = true;
@@ -279,7 +312,7 @@ export class KLineChartsSceneAdapter {
         }
     }
     #historicalDataLoader(scene) {
-        const snapshot = structuredClone(scene.data);
+        const snapshot = structuredClone(engineDataForScene(scene));
         return {
             getBars: ({ type, timestamp, callback }) => {
                 if (type === 'init') {
@@ -359,6 +392,12 @@ export class KLineChartsSceneAdapter {
         if (previousId === id) {
             return;
         }
+        if (previousId === null && id !== null) {
+            this.#enterExclusiveSelection();
+        }
+        else if (previousId !== null && id === null) {
+            this.#leaveExclusiveSelection();
+        }
         this.#selectedOverlayId = id;
         if (this.#workspaceMode) {
             this.#emitPort({
@@ -372,7 +411,63 @@ export class KLineChartsSceneAdapter {
             this.#emit({ type: 'overlay-selected', id });
         }
     }
+    #enterExclusiveSelection() {
+        if (this.#drawingInteraction.exclusiveSelection !== true ||
+            this.#chartInteractionSnapshot !== undefined) {
+            return;
+        }
+        this.#chartInteractionSnapshot = {
+            scrollEnabled: this.#chart.isScrollEnabled(),
+            zoomEnabled: this.#chart.isZoomEnabled(),
+            crosshairVisible: this.#chart.getStyles().crosshair.show,
+        };
+        this.#chart.setScrollEnabled(false);
+        this.#chart.setZoomEnabled(false);
+        this.#chart.setStyles({ crosshair: { show: false } });
+    }
+    #leaveExclusiveSelection() {
+        const snapshot = this.#chartInteractionSnapshot;
+        if (snapshot === undefined) {
+            return;
+        }
+        this.#chartInteractionSnapshot = undefined;
+        this.#chart.setScrollEnabled(snapshot.scrollEnabled);
+        this.#chart.setZoomEnabled(snapshot.zoomEnabled);
+        this.#chart.setStyles({ crosshair: { show: snapshot.crosshairVisible } });
+    }
+    #hitTolerance(pointerType) {
+        const touch = pointerType === 'touch';
+        const defaults = touch
+            ? DEFAULT_OVERLAY_TOUCH_HIT_TOLERANCE
+            : DEFAULT_OVERLAY_MOUSE_HIT_TOLERANCE;
+        const configured = touch
+            ? this.#drawingInteraction.hitTolerance?.touch
+            : this.#drawingInteraction.hitTolerance?.mouse;
+        const body = configured?.body ?? defaults.body;
+        const anchor = configured?.anchor ?? defaults.anchor;
+        if (!Number.isFinite(body) || body < 0 || !Number.isFinite(anchor) || anchor < 0) {
+            throw new SceneError('RUNTIME_INIT_FAILED', '/drawingInteraction/hitTolerance', 'Drawing hit tolerance must contain finite non-negative CSS pixel values.');
+        }
+        return { body, anchor };
+    }
     #dimensionsForHit(overlay, hit) {
+        const constrainedType = overlay.type === 'horizontalStraightLine'
+            || overlay.type === 'priceLine'
+            || overlay.type === 'simpleTag'
+            || overlay.type === 'horizontalRayLine'
+            || overlay.type === 'horizontalSegment'
+            ? 'vertical'
+            : overlay.type === 'verticalStraightLine'
+                || overlay.type === 'verticalRayLine'
+                || overlay.type === 'verticalSegment'
+                ? 'horizontal'
+                : null;
+        if (constrainedType === 'vertical') {
+            return { horizontal: false, vertical: true };
+        }
+        if (constrainedType === 'horizontal') {
+            return { horizontal: true, vertical: false };
+        }
         if (hit.target !== 'anchor') {
             return { horizontal: true, vertical: true };
         }
@@ -430,6 +525,7 @@ export class KLineChartsSceneAdapter {
                 preventDefault?.();
             },
             onDrawEnd: ({ overlay }) => {
+                this.#finishTouchPrecisionDrawing(overlay.id);
                 if (drawing &&
                     this.#interactivePriceMeasurement?.source.id === source.id) {
                     this.#interactivePriceMeasurement = undefined;
@@ -463,6 +559,7 @@ export class KLineChartsSceneAdapter {
                 }
             },
             onRemoved: ({ overlay }) => {
+                this.#finishTouchPrecisionDrawing(overlay.id);
                 if (this.#interactivePriceMeasurement?.source.id === overlay.id) {
                     this.#interactivePriceMeasurement = undefined;
                 }
@@ -496,32 +593,191 @@ export class KLineChartsSceneAdapter {
             throw error;
         }
     }
+    #prepareTouchPrecisionDrawing(id, paneId) {
+        if (this.#drawingInteraction.touch !== 'precision-cursor') {
+            return;
+        }
+        this.#finishTouchPrecisionDrawing();
+        this.#touchPrecisionDrawing = {
+            id,
+            paneId,
+            phase: 'move-start',
+        };
+        const view = this.#container.ownerDocument.defaultView;
+        if ((view?.navigator.maxTouchPoints ?? 0) > 0 ||
+            view?.matchMedia('(any-pointer: coarse)').matches === true) {
+            const guide = this.#ensureTouchPrecisionGuide();
+            guide.setPhase('move-start');
+            guide.show();
+        }
+    }
+    #ensureTouchPrecisionGuide() {
+        this.#touchPrecisionGuide ??= new TouchPrecisionDrawingGuide(this.#container, () => this.#cancelTouchPrecisionDrawing(true));
+        return this.#touchPrecisionGuide;
+    }
+    #finishTouchPrecisionDrawing(id) {
+        const drawing = this.#touchPrecisionDrawing;
+        if (drawing === undefined || (id !== undefined && drawing.id !== id)) {
+            return;
+        }
+        this.#stopTouchPrecisionPointerCapture();
+        this.#touchPrecisionPointer = undefined;
+        this.#touchPrecisionDrawing = undefined;
+        this.#touchPrecisionGuide?.hide();
+    }
+    #cancelTouchPrecisionDrawing(emitRemoval) {
+        const drawing = this.#touchPrecisionDrawing;
+        if (drawing === undefined) {
+            return;
+        }
+        const id = drawing.id;
+        this.#finishTouchPrecisionDrawing(id);
+        this.#suppressCompatibilityMouseUntil = performance.now() + 800;
+        this.#chart.removeOverlay({ id });
+        if (this.#drawingInProgressId === id) {
+            this.#drawingInProgressId = null;
+        }
+        if (this.#workspaceMode) {
+            const removed = this.#workspaceSources.delete(id);
+            if (emitRemoval && removed) {
+                this.#emitPort({ type: 'removed', id });
+            }
+        }
+    }
+    #stopTouchPrecisionPointerCapture() {
+        const pointer = this.#touchPrecisionPointer;
+        if (pointer === undefined) {
+            return;
+        }
+        try {
+            if (this.#container.hasPointerCapture(pointer.pointerId)) {
+                this.#container.releasePointerCapture(pointer.pointerId);
+            }
+        }
+        catch {
+            // Synthetic browser tests and interrupted system gestures may not own capture.
+        }
+    }
+    #touchPrecisionMainElement(paneId) {
+        const filter = this.#primaryAxisFilter(paneId);
+        const main = this.#chart.getDom(filter.paneId, 'main');
+        if (!(main instanceof HTMLElement)) {
+            throw new SceneError('INVALID_REFERENCE', '/drawings/target', 'Touch Drawing target Pane has no interactive main element.');
+        }
+        return main;
+    }
+    #touchPrecisionBounds(paneId) {
+        const containerRect = this.#container.getBoundingClientRect();
+        const mainRect = this.#touchPrecisionMainElement(paneId).getBoundingClientRect();
+        return {
+            left: Math.max(0, mainRect.left - containerRect.left),
+            top: Math.max(0, mainRect.top - containerRect.top),
+            right: Math.min(containerRect.width, mainRect.right - containerRect.left),
+            bottom: Math.min(containerRect.height, mainRect.bottom - containerRect.top),
+        };
+    }
+    #dispatchTouchPrecisionMouseMove(point) {
+        const rect = this.#container.getBoundingClientRect();
+        this.#dispatchEngineMouseMove({
+            x: point.x,
+            y: point.y,
+            pageX: rect.left + point.x + window.scrollX,
+            pageY: rect.top + point.y + window.scrollY,
+        });
+    }
+    #dispatchTouchPrecisionClick(point) {
+        const rect = this.#container.getBoundingClientRect();
+        this.#resetClickArbitration();
+        this.#dispatchEngineMouseClick({
+            x: point.x,
+            y: point.y,
+            pageX: rect.left + point.x + window.scrollX,
+            pageY: rect.top + point.y + window.scrollY,
+        });
+    }
+    #updateTouchPrecisionCursor(drawing, pointer) {
+        const cursor = resolveTouchPrecisionCursor(pointer, this.#touchPrecisionBounds(drawing.paneId));
+        this.#touchPrecisionGuide?.updateCursor(cursor);
+        this.#dispatchTouchPrecisionMouseMove(cursor);
+        return cursor;
+    }
+    #isTouchPrecisionCancelTarget(target) {
+        return this.#touchPrecisionGuide?.ownsCancelTarget(target) ?? false;
+    }
     #installInteractionListeners() {
         this.#container.addEventListener('mousedown', this.#handleRightMouseDown, true);
+        this.#container.addEventListener('click', this.#handleCompatibilityClick, true);
         this.#container.addEventListener('contextmenu', this.#handleContextMenu, true);
         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);
+        this.#container.addEventListener('touchstart', this.#handleCompatibilityTouch, {
+            capture: true,
+            passive: false,
+        });
+        this.#container.addEventListener('touchmove', this.#handleCompatibilityTouch, {
+            capture: true,
+            passive: false,
+        });
+        this.#container.addEventListener('touchend', this.#handleCompatibilityTouch, {
+            capture: true,
+            passive: false,
+        });
+        this.#container.addEventListener('touchcancel', this.#handleCompatibilityTouch, {
+            capture: true,
+            passive: false,
+        });
         window.addEventListener('keydown', this.#handleKeyDown);
         window.addEventListener('blur', this.#handleWindowBlur);
     }
     #removeInteractionListeners() {
         this.#container.removeEventListener('mousedown', this.#handleRightMouseDown, true);
+        this.#container.removeEventListener('click', this.#handleCompatibilityClick, true);
         this.#container.removeEventListener('contextmenu', this.#handleContextMenu, true);
         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);
+        this.#container.removeEventListener('touchstart', this.#handleCompatibilityTouch, true);
+        this.#container.removeEventListener('touchmove', this.#handleCompatibilityTouch, true);
+        this.#container.removeEventListener('touchend', this.#handleCompatibilityTouch, true);
+        this.#container.removeEventListener('touchcancel', this.#handleCompatibilityTouch, true);
         window.removeEventListener('keydown', this.#handleKeyDown);
         window.removeEventListener('blur', this.#handleWindowBlur);
     }
     #handleRightMouseDown = (event) => {
+        if (event.button === 0 &&
+            event.isTrusted &&
+            performance.now() < this.#suppressCompatibilityMouseUntil &&
+            !this.#isTouchPrecisionCancelTarget(event.target)) {
+            event.preventDefault();
+            event.stopImmediatePropagation();
+            return;
+        }
         if (event.button === 2) {
             // 阻止事件到达 KLineCharts；不 preventDefault，保留浏览器原生右键菜单。
             event.stopPropagation();
         }
     };
+    #handleCompatibilityClick = (event) => {
+        if (event.isTrusted &&
+            performance.now() < this.#suppressCompatibilityMouseUntil &&
+            !this.#isTouchPrecisionCancelTarget(event.target)) {
+            event.preventDefault();
+            event.stopImmediatePropagation();
+        }
+    };
+    #handleCompatibilityTouch = (event) => {
+        if ((this.#touchPrecisionDrawing !== undefined ||
+            performance.now() < this.#suppressCompatibilityMouseUntil) &&
+            !this.#isTouchPrecisionCancelTarget(event.target)) {
+            if (event.cancelable) {
+                event.preventDefault();
+            }
+            event.stopImmediatePropagation();
+        }
+    };
     #handleContextMenu = (event) => {
         // KLineCharts 会 preventDefault。捕获阶段截断传播，但 Baron 本身不拦截菜单。
         event.stopPropagation();
@@ -598,60 +854,40 @@ export class KLineChartsSceneAdapter {
     #overlayGeometries() {
         const geometries = [];
         const active = this.#activeOverlays();
+        const containerRect = this.#container.getBoundingClientRect();
+        const canvas = this.#container.ownerDocument.createElement('canvas');
+        const textContext = canvas.getContext('2d');
         for (let sceneIndex = 0; sceneIndex < active.length; sceneIndex++) {
             const overlay = active[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,
-                });
+            const paneFilter = this.#primaryAxisFilter(overlay.paneId);
+            const paneMain = this.#chart.getDom(paneFilter.paneId, 'main');
+            const mainRect = paneMain?.getBoundingClientRect() ?? containerRect;
+            const geometry = projectOverlayGeometry(overlay, sceneIndex, {
+                bounds: {
+                    left: mainRect.left - containerRect.left,
+                    top: mainRect.top - containerRect.top,
+                    right: mainRect.right - containerRect.left,
+                    bottom: mainRect.bottom - containerRect.top,
+                },
+                referenceTimestamp: this.#scene.data[0].timestamp,
+                referenceValue: this.#scene.data[0].close,
+                project: (point) => this.#toPixel(point, overlay.paneId),
+                measureText: (text, source) => {
+                    const textStyle = source.styles.text;
+                    if (textContext !== null) {
+                        textContext.font = `${textStyle.weight} ${textStyle.size}px ${textStyle.family}`;
+                    }
+                    return {
+                        width: Math.max(textStyle.size, textContext?.measureText(text).width ?? [...text].length * textStyle.size),
+                        height: textStyle.size * 1.4,
+                    };
+                },
+            });
+            if (geometry !== null) {
+                geometries.push(geometry);
             }
         }
         return geometries;
@@ -695,13 +931,102 @@ export class KLineChartsSceneAdapter {
             this.#emit({ type: 'scene-error', issues: structuredClone(error.issues) });
         }
     }
+    #routeTouchPrecisionPointerDown(event) {
+        const drawing = this.#touchPrecisionDrawing;
+        if (drawing === undefined || this.#isTouchPrecisionCancelTarget(event.target)) {
+            return false;
+        }
+        if (event.pointerType !== 'touch') {
+            this.#finishTouchPrecisionDrawing(drawing.id);
+            return false;
+        }
+        event.preventDefault();
+        event.stopImmediatePropagation();
+        if (this.#touchPrecisionPointer !== undefined) {
+            return true;
+        }
+        const guide = this.#ensureTouchPrecisionGuide();
+        guide.setPhase(drawing.phase);
+        guide.show();
+        const point = this.#pointerCoordinate(event);
+        this.#touchPrecisionPointer = {
+            pointerId: event.pointerId,
+            origin: point,
+            current: point,
+        };
+        try {
+            this.#container.setPointerCapture(event.pointerId);
+        }
+        catch {
+            // Synthetic PointerEvents do not own browser pointer capture.
+        }
+        this.#suppressCompatibilityMouseUntil = performance.now() + 800;
+        this.#updateTouchPrecisionCursor(drawing, point);
+        return true;
+    }
+    #routeTouchPrecisionPointerMove(event) {
+        const drawing = this.#touchPrecisionDrawing;
+        const pointer = this.#touchPrecisionPointer;
+        if (drawing === undefined ||
+            pointer === undefined ||
+            pointer.pointerId !== event.pointerId) {
+            return false;
+        }
+        event.preventDefault();
+        event.stopImmediatePropagation();
+        const point = this.#pointerCoordinate(event);
+        pointer.current = point;
+        this.#suppressCompatibilityMouseUntil = performance.now() + 800;
+        this.#updateTouchPrecisionCursor(drawing, point);
+        return true;
+    }
+    #routeTouchPrecisionPointerUp(event) {
+        const drawing = this.#touchPrecisionDrawing;
+        const pointer = this.#touchPrecisionPointer;
+        if (drawing === undefined ||
+            pointer === undefined ||
+            pointer.pointerId !== event.pointerId) {
+            return false;
+        }
+        event.preventDefault();
+        event.stopImmediatePropagation();
+        const point = this.#pointerCoordinate(event);
+        pointer.current = point;
+        const cursor = this.#updateTouchPrecisionCursor(drawing, point);
+        const tap = isTouchPrecisionTap(pointer.origin, pointer.current);
+        this.#stopTouchPrecisionPointerCapture();
+        this.#touchPrecisionPointer = undefined;
+        this.#suppressCompatibilityMouseUntil = performance.now() + 800;
+        if (drawing.phase === 'move-start') {
+            drawing.phase = 'confirm-start';
+            this.#touchPrecisionGuide?.setPhase('confirm-start');
+            return true;
+        }
+        if (!tap) {
+            return true;
+        }
+        const phase = drawing.phase;
+        this.#dispatchTouchPrecisionClick(cursor);
+        const active = this.#touchPrecisionDrawing;
+        if (phase === 'confirm-start' &&
+            active !== undefined &&
+            active.id === drawing.id) {
+            active.phase = 'confirm-end';
+            this.#touchPrecisionGuide?.setPhase('confirm-end');
+        }
+        return true;
+    }
     #handlePointerDown = (event) => {
         if (this.#disposed ||
             event.button !== 0 ||
             this.#pointerInteraction !== undefined ||
+            this.#deselectingPointerId !== undefined ||
             !this.#mutationsEnabled) {
             return;
         }
+        if (this.#routeTouchPrecisionPointerDown(event)) {
+            return;
+        }
         const coordinate = this.#pointerCoordinate(event);
         const measurement = this.#interactivePriceMeasurement;
         if (measurement !== undefined) {
@@ -732,9 +1057,22 @@ export class KLineChartsSceneAdapter {
         if (this.#drawingInProgressId !== null) {
             return;
         }
-        const hit = hitTestOverlayGeometries(coordinate, this.#overlayGeometries());
+        const hit = hitTestOverlayGeometries(coordinate, this.#overlayGeometries(), this.#hitTolerance(event.pointerType));
         if (hit === null) {
             const selected = this.#activeOverlays().find((overlay) => overlay.id === this.#selectedOverlayId);
+            if (selected !== undefined &&
+                this.#drawingInteraction.exclusiveSelection === true) {
+                event.preventDefault();
+                event.stopImmediatePropagation();
+                this.#deselectingPointerId = event.pointerId;
+                try {
+                    this.#container.setPointerCapture(event.pointerId);
+                }
+                catch {
+                    // Synthetic PointerEvents do not own browser pointer capture.
+                }
+                return;
+            }
             if (selected !== undefined && isControlledInteractionOverlay(selected)) {
                 this.#selectOverlay(null);
             }
@@ -745,7 +1083,8 @@ export class KLineChartsSceneAdapter {
             return;
         }
         this.#selectOverlay(before.id);
-        if (!isControlledInteractionOverlay(before)) {
+        if (!isControlledInteractionOverlay(before) &&
+            this.#drawingInteraction.exclusiveSelection !== true) {
             return;
         }
         event.preventDefault();
@@ -753,7 +1092,12 @@ export class KLineChartsSceneAdapter {
         if (hit.locked) {
             return;
         }
-        this.#container.setPointerCapture(event.pointerId);
+        try {
+            this.#container.setPointerCapture(event.pointerId);
+        }
+        catch {
+            // Synthetic PointerEvents do not own browser pointer capture.
+        }
         this.#interactionDimensions = this.#dimensionsForHit(before, hit);
         this.#pointerInteraction = {
             pointerId: event.pointerId,
@@ -766,6 +1110,14 @@ export class KLineChartsSceneAdapter {
         };
     };
     #handlePointerMove = (event) => {
+        if (this.#routeTouchPrecisionPointerMove(event)) {
+            return;
+        }
+        if (this.#deselectingPointerId === event.pointerId) {
+            event.preventDefault();
+            event.stopImmediatePropagation();
+            return;
+        }
         const interaction = this.#pointerInteraction;
         if (interaction === undefined || interaction.pointerId !== event.pointerId) {
             return;
@@ -797,6 +1149,7 @@ export class KLineChartsSceneAdapter {
                 throw new SceneError('RUNTIME_INIT_FAILED', `/overlays/${index}`, `KLineCharts failed to preview Overlay ${normalized.id}.`);
             }
             if (this.#workspaceMode) {
+                interaction.candidate = candidate;
                 this.#setActiveOverlays(overlays);
                 return;
             }
@@ -816,6 +1169,19 @@ export class KLineChartsSceneAdapter {
         }
     };
     #handlePointerUp = (event) => {
+        if (this.#routeTouchPrecisionPointerUp(event)) {
+            return;
+        }
+        if (this.#deselectingPointerId === event.pointerId) {
+            event.preventDefault();
+            event.stopImmediatePropagation();
+            if (this.#container.hasPointerCapture(event.pointerId)) {
+                this.#container.releasePointerCapture(event.pointerId);
+            }
+            this.#deselectingPointerId = undefined;
+            this.#selectOverlay(null);
+            return;
+        }
         const interaction = this.#pointerInteraction;
         if (interaction === undefined || interaction.pointerId !== event.pointerId) {
             return;
@@ -823,6 +1189,7 @@ export class KLineChartsSceneAdapter {
         event.preventDefault();
         event.stopImmediatePropagation();
         this.#pointerInteraction = undefined;
+        const interactionDimensions = this.#interactionDimensions;
         this.#interactionDimensions = { horizontal: false, vertical: false };
         this.#stopPointerCapture(interaction);
         if (!interaction.started) {
@@ -841,7 +1208,7 @@ export class KLineChartsSceneAdapter {
                     type: 'updated',
                     id: overlay.id,
                     drawing: snapshotOfDrawing(sceneOverlayToDrawing(overlay, drawing)),
-                    editDimensions: structuredClone(this.#interactionDimensions),
+                    editDimensions: structuredClone(interactionDimensions),
                 });
             }
             return;
@@ -856,21 +1223,56 @@ export class KLineChartsSceneAdapter {
         this.#emit({ type: 'overlay-updated', overlay: committed });
     };
     #handlePointerCancel = (event) => {
+        if (this.#touchPrecisionPointer?.pointerId === event.pointerId) {
+            event.preventDefault();
+            event.stopImmediatePropagation();
+            this.#cancelTouchPrecisionDrawing(true);
+            return;
+        }
         if (this.#pointerInteraction?.pointerId === event.pointerId) {
             event.preventDefault();
             event.stopImmediatePropagation();
             this.#cancelInteraction('pointer-cancel');
+            return;
+        }
+        if (this.#deselectingPointerId === event.pointerId) {
+            event.preventDefault();
+            event.stopImmediatePropagation();
+            if (this.#container.hasPointerCapture(event.pointerId)) {
+                this.#container.releasePointerCapture(event.pointerId);
+            }
+            this.#deselectingPointerId = undefined;
+            this.#selectOverlay(null);
         }
     };
     #handleKeyDown = (event) => {
+        if (event.key === 'Escape' && this.#touchPrecisionDrawing !== undefined) {
+            this.#cancelTouchPrecisionDrawing(true);
+            return;
+        }
         if (event.key === 'Escape' && this.#pointerInteraction !== undefined) {
             this.#cancelInteraction('escape');
         }
+        if (event.key === 'Escape' &&
+            this.#drawingInteraction.exclusiveSelection === true &&
+            this.#selectedOverlayId !== null) {
+            this.#selectOverlay(null);
+        }
     };
     #handleWindowBlur = () => {
+        if (this.#touchPrecisionDrawing !== undefined) {
+            this.#cancelTouchPrecisionDrawing(true);
+        }
         if (this.#pointerInteraction !== undefined) {
             this.#cancelInteraction('window-blur');
         }
+        if (this.#deselectingPointerId !== undefined) {
+            if (this.#container.hasPointerCapture(this.#deselectingPointerId)) {
+                this.#container.releasePointerCapture(this.#deselectingPointerId);
+            }
+            this.#deselectingPointerId = undefined;
+            this.#selectOverlay(null);
+        }
     };
     subscribe(listener) {
         this.#assertActive();
@@ -922,6 +1324,10 @@ export class KLineChartsSceneAdapter {
     replaceScene(value) {
         this.#assertActive();
         const candidate = parseChartScene(value);
+        if (candidate.version !== this.#scene.version) {
+            throw new SceneError('INVALID_REFERENCE', '/version', 'Scene replacement requires the same ChartScene contract version.');
+        }
+        assertGapAwareSceneSupported(candidate);
         const paneShape = (scene) => JSON.stringify(scene.panes.map((pane) => ({
             id: pane.id,
             kind: pane.kind,
@@ -946,7 +1352,7 @@ export class KLineChartsSceneAdapter {
                 this.#historicalDataLoading = { hasMore: true };
             }
             this.#chart.setDataLoader(this.#historicalDataLoading === undefined
-                ? createStaticDataLoader(candidate.data)
+                ? createStaticDataLoader(engineDataForScene(candidate))
                 : this.#historicalDataLoader(candidate));
             this.#chart.resetData();
             applyViewport(this.#chart, candidate.viewport);
@@ -969,7 +1375,7 @@ export class KLineChartsSceneAdapter {
                     this.#historicalDataLoading = { hasMore: previousHistoricalHasMore };
                 }
                 this.#chart.setDataLoader(this.#historicalDataLoading === undefined
-                    ? createStaticDataLoader(previous.data)
+                    ? createStaticDataLoader(engineDataForScene(previous))
                     : this.#historicalDataLoader(previous));
                 this.#chart.resetData();
                 applyViewport(this.#chart, previous.viewport);
@@ -1080,6 +1486,9 @@ export class KLineChartsSceneAdapter {
             throw new SceneError('RUNTIME_INIT_FAILED', '/drawings', `KLineCharts failed to start Drawing ${request.id}.`);
         }
         this.#drawingInProgressId = request.id;
+        if (request.type === 'segment') {
+            this.#prepareTouchPrecisionDrawing(request.id, overlay.paneId);
+        }
         return request.id;
     }
     listDrawings() {
@@ -1224,6 +1633,9 @@ export class KLineChartsSceneAdapter {
     applyMainSeriesPresentation(presentation) {
         this.#assertActive();
         this.#assertNotTerminated();
+        if (isGapAwareScene(this.#scene)) {
+            throw new MainSeriesPresentationError('MAIN_SERIES_PRESENTATION_UNSUPPORTED', '/chart/candle/type', 'ChartScene v2 main-series switching is disabled until every presentation is Gap-aware.');
+        }
         if (presentation.type === 'area') {
             const expected = STANDARD_CLOSE_LINE_PRESENTATION;
             if (presentation.value !== expected.value ||
@@ -1513,7 +1925,9 @@ export class KLineChartsSceneAdapter {
     }
     inspect() {
         this.#assertActive();
-        const indicators = this.#chart.getIndicators().map((indicator) => {
+        const indicators = this.#chart.getIndicators()
+            .filter((indicator) => indicator.id !== GAP_AWARE_CANDLE_INDICATOR_ID)
+            .map((indicator) => {
             const paneId = this.#idMap.paneFromEngine.get(indicator.paneId);
             const yAxisId = this.#idMap.yAxisFromEngine.get(indicator.yAxisId);
             if (paneId === undefined || yAxisId === undefined) {
@@ -1529,7 +1943,9 @@ export class KLineChartsSceneAdapter {
         return {
             engineVersion: this.#engine.version(),
             runtimeVersion: this.#scene.runtime.runtimeVersion,
-            dataCount: this.#chart.getDataList().length,
+            dataCount: this.#scene.data.length,
+            timelineSlotCount: timelineSlotCount(this.#scene),
+            gapCount: gapCount(this.#scene),
             paneIds: this.#scene.panes.map((pane) => pane.id),
             indicators,
             overlays: this.exportScene().overlays,
@@ -1542,6 +1958,11 @@ export class KLineChartsSceneAdapter {
             return;
         }
         this.#cancelInteraction('destroy');
+        this.#deselectingPointerId = undefined;
+        this.#leaveExclusiveSelection();
+        this.#cancelTouchPrecisionDrawing(false);
+        this.#touchPrecisionGuide?.destroy();
+        this.#touchPrecisionGuide = undefined;
         this.#interactivePriceMeasurement = undefined;
         this.#drawingInProgressId = null;
         this.#disposed = true;