@363045841yyt/klinechart-core 0.9.0-alpha.2 → 0.9.0-alpha.4

package/src/engine/chart.ts

@@ -1,3 +1,14 @@
+/**
+ * Chart — 图表顶层编排器。
+ *
+ * 职责范围：
+ * - 持有 StateKernel（所有配置与状态的唯一数据源）
+ * - 管理 Viewport / 布局 / 渲染器生命周期
+ * - 提供 scheduleDraw / draw 入口供外部（交互、数据、插件）触发重绘
+ * - 协调插件宿主、指标控制器、标注管理器等子系统的初始化与销毁
+ *
+ * 不是绘制管线的一部分。绘制由 ChartRenderer 完成，Chart 仅负责代理调用并维护 runtimeProjection（批量投影）屏障。
+ */
 import { createAlertController } from '../features/alerts/index'
 import {
   createVolumeLookbacks,
@@ -15,10 +26,13 @@ import {
 import { createLayerFromPlugin } from '../rendering/scene/createLayerFromPlugin'
 import {
   computed,
+  createSignal,
   type Computed,
   type ReadonlySignal,
   type Signal,
+  type WritableSignal,
 } from '../foundation/reactivity/signal'
+import type { LegendTemplateContext } from './renderers/Indicator/mainIndicatorLegendContext'
 
 import { InteractionController, type InteractionSnapshot } from './controller/interaction'
 
@@ -46,10 +60,9 @@ import { UpdateLevel, type VisibleRange } from './layout/pane'
 import { KLineMode } from './modes/kLineMode'
 import { TimeShareMode } from './modes/timeShareMode'
 import { PaneRenderer } from './paneRenderer'
-import { ChartRenderer } from './render/chartRenderer'
+import { ChartRenderer, mergeUpdateLevel } from './render/chartRenderer'
 import { ChartStateKernel } from './state/chartStateKernel'
 import { ChartViewportManager } from './viewport/chartViewportManager'
-import { getVisibleRange } from './viewport/viewport'
 import { ChartZoomController } from './utils/chartZoomController'
 import { getPhysicalKLineConfig } from './utils/klineConfig'
 import type {
@@ -117,8 +130,13 @@ export class Chart {
 
   /** 渲染器 */
   private renderer: ChartRenderer
+  /** runRuntimeProjection 嵌套深度，大于 0 时推迟 scheduleDraw */
   private runtimeProjectionDepth = 0
-  private runtimeProjectionDrawPending = false
+  /** 被推迟的绘制级别，退出嵌套后统一 flush */
+  private pendingProjectionLevel: UpdateLevel | null = null
+  /** 主图图例模板上下文（每帧由 mainIndicatorLegend 发布） */
+  private readonly _legendTemplateContext: WritableSignal<LegendTemplateContext | null> =
+    createSignal<LegendTemplateContext | null>(null)
 
   /** 绘图交互会话（锚点/预览/拖拽）；工具 id 在 kernel */
   private drawingSession: DrawingInteractionController | null = null
@@ -133,7 +151,13 @@ export class Chart {
     zoomLevel: number
     scaleTypes: Map<string, ScaleType>
     mainIndicators: Array<{ id: string; params: Record<string, number | boolean | string> }>
-    subPanes: Array<{ id: string; params: Record<string, unknown> }>
+    subPanes: Array<{
+      paneId: string
+      indicatorId: string
+      params: Record<string, unknown>
+    }>
+    paneRatios: Record<string, number>
+    candleEnabled: boolean
   } | null = null
 
   /** 上次预警评估的最新 K 线时间戳（用于去重） */
@@ -275,17 +299,13 @@ export class Chart {
           defaultPaneMinHeightPx: o.defaultPaneMinHeightPx,
         }
       },
-      getViewport: () => this.viewportManager.getViewport(),
+      viewport: this.kernel.viewport,
       setKnownPaneIds: (ids) => this.rendererPluginManager.setKnownPaneIds(ids),
       notifyPaneResize: (paneId, pane) =>
         this.rendererPluginManager.notifyResize(paneId, wrapPaneInfo(pane)),
       scheduleDraw: (level) => this.scheduleDraw(level),
-      getPaneRatios: () => this.kernel.pane.readonly.paneRatios.peek(),
-      getPaneScaleTypes: () => this.kernel.pane.readonly.paneScaleTypes.peek(),
-      commitLayout: (ratios, specs) => {
-        this.kernel.pane.actions.commitLayout(ratios, specs)
-        this.ensurePaneScaleTypesFromSettings()
-      },
+      pane: this.kernel.pane,
+      afterCommitLayout: () => this.ensurePaneScaleTypesFromSettings(),
     })
 
     this.alertController = createAlertController()
@@ -300,51 +320,25 @@ export class Chart {
             kGap: this.kernel.viewport.readonly.kGap(),
           }
         },
-        getEffectiveDpr: () => this.viewportManager.getEffectiveDpr(),
-        getLogicalScrollLeft: () => this.viewportManager.getLogicalScrollLeft(),
-        getCachedScrollLeft: () => this.viewportManager.getCachedScrollLeft(),
-        setScrollLeft: (v) => {
-          this.viewportManager.setScrollLeft(v)
-        },
         getDom: () => this.dom,
-        getObservedSize: () => this.viewportManager.getObservedSize(),
-        getViewport: () => this.viewportManager.getViewport(),
-        getVisibleRange: () => {
-          const vp = this.viewportManager.computeViewport()
-          if (!vp) return null
-          const dataLen = this.dataManager?.getData().length ?? 0
-          if (dataLen === 0) return null
-          return getVisibleRange(
-            vp.scrollLeft,
-            vp.plotWidth,
-            this.kernel.zoom.readonly.kWidth(),
-            this.kernel.viewport.readonly.kGap(),
-            dataLen,
-            vp.dpr,
-          )
-        },
-        getLeftLoadBufferWidth: () => this.kernel.viewport.readonly.leftLoadBufferWidth.peek(),
-        getContentWidth: () => this.kernel.viewport.readonly.contentWidth.peek(),
+        viewport: this.kernel.viewport,
+        comparison: this.kernel.comparison,
         scheduleDraw: (level) => this.scheduleDraw(level),
         resetInteraction: () => this.interaction.reset(),
         getIndicatorScheduler: () => this.indicatorManager.indicatorSchedulerAccessor,
         isPointerDown: () => this.interaction.isPointerDown(),
         onTimeShareDataReady: (dataLength) => {
-          const vp = this.viewportManager.computeViewport()
+          const vp = this.getViewport()
           if (!vp || vp.plotWidth <= 0) return
           const result = this._activeMode.computeKWidth(dataLength, vp.plotWidth, vp.dpr)
           if (result) {
             this.applyRenderState(result.kWidth, result.kGap)
             const leftBuffer = this.getLeftLoadBufferWidth()
-            this.viewportManager.setScrollLeft(leftBuffer)
+            this.kernel.viewport.actions.scrollTo(leftBuffer)
           }
         },
         onDataProcessed: (data, range) => this.evaluateAlerts(data, range),
         setSymbols: (symbols) => this.kernel.actions.setSymbols(symbols),
-        setComparisonLoading: (loading) => this.kernel.comparison.actions.setLoading(loading),
-        comparisonSpecs$: this.kernel.comparison.readonly.specs,
-        comparisonColors$: this.kernel.comparison.readonly.colors,
-        comparisonLoading$: this.kernel.comparison.readonly.loading,
       },
       this.kernel.data,
       this.kernel.dataManager,
@@ -352,22 +346,16 @@ export class Chart {
 
     this.zoomController = new ChartZoomController(
       {
-        getLogicalScrollLeft: () => this.viewportManager.getLogicalScrollLeft(),
-        getCurrentDpr: () => this.viewportManager.getEffectiveDpr(),
+        viewport: this.kernel.viewport,
+        options: this.kernel.options,
+        period$: this.kernel.dataManager.readonly.currentPeriod,
         getClientWidth: () =>
-          this.viewportManager.getViewport()?.viewWidth ?? this.dom.container?.clientWidth ?? 0,
+          this.getViewport()?.viewWidth ?? this.dom.container?.clientWidth ?? 0,
         getDataLength: () => this.dataManager.getData().length,
         getPlotWidth: () => this.getLeftLoadBufferWidth(),
-        setScrollLeft: (v) => {
-          this.viewportManager.setScrollLeft(v)
-        },
         onChange: () => {
           this.scheduleDraw()
         },
-        getMinKWidth: () => this.kernel.options.readonly.options.peek().minKWidth,
-        getMaxKWidth: () => this.kernel.options.readonly.options.peek().maxKWidth,
-        getPeriod: () => this.kernel.dataManager.readonly.currentPeriod.peek(),
-        zoomLevelCount,
       },
       this.kernel.zoom,
     )
@@ -387,8 +375,9 @@ export class Chart {
       removeRenderer: (name) => this.removeRenderer(name),
       updateRendererConfig: (name, config) => this.updateRendererConfig(name, config),
       setRendererEnabled: (name, enabled) => this.setRendererEnabled(name, enabled),
-      getPaneRatiosSignal: () =>
-        this.kernel.pane.readonly.paneRatios as ReadonlySignal<Readonly<Record<string, number>>>,
+      paneRatios$: this.kernel.pane.readonly.paneRatios as ReadonlySignal<
+        Readonly<Record<string, number>>
+      >,
       paneSpecs$: this.kernel.pane.readonly.paneSpecs,
       projectPaneLayout: (specs, ratios) => {
         this.layoutManager.projectState(specs, ratios)
@@ -405,24 +394,17 @@ export class Chart {
       getLayer: (id) => this.renderer?.getScene()?.getLayer(id) ?? null,
       setLayerVisibility: (id, visible) =>
         this.renderer?.getScene()?.setLayerVisibility(id, visible),
-      getRightAxisWidth: () => this.kernel.options.readonly.options.peek().rightAxisWidth,
-      getPriceLabelWidth: () => this.kernel.options.readonly.options.peek().priceLabelWidth ?? 60,
-      getYPaddingPx: () => this.kernel.options.readonly.options.peek().yPaddingPx,
-      mainIndicators$: this.kernel.indicator.readonly.mainIndicators,
-      upsertMainIndicator: (id, params) => this.kernel.indicator.actions.upsert(id, params),
-      removeMainIndicator: (id) => this.kernel.indicator.actions.remove(id),
-      setMainIndicatorParams: (id, params) => this.kernel.indicator.actions.setParams(id, params),
-      replaceMainIndicators: (entries) => this.kernel.indicator.actions.replaceAll(entries),
-      clearMainIndicators: () => this.kernel.indicator.actions.clear(),
-      subPanes$: this.kernel.subPane.readonly.entries,
-      createSubPaneState: (paneId, indicatorId, params) =>
-        this.kernel.actions.createSubPane(paneId, indicatorId, params),
-      removeSubPaneState: (paneId) => this.kernel.actions.removeSubPane(paneId),
-      replaceSubPaneState: (paneId, indicatorId, params) =>
-        this.kernel.actions.replaceSubPane(paneId, indicatorId, params),
-      updateSubPaneStateParams: (paneId, params) =>
-        this.kernel.actions.updateSubPaneParams(paneId, params),
-      clearSubPaneState: () => this.kernel.actions.clearSubPanes(),
+      indicator: this.kernel.indicator,
+      subPaneOps: {
+        entries: this.kernel.subPane.readonly.entries,
+        create: (paneId, indicatorId, params) =>
+          this.kernel.actions.createSubPane(paneId, indicatorId, params),
+        remove: (paneId) => this.kernel.actions.removeSubPane(paneId),
+        replace: (paneId, indicatorId, params) =>
+          this.kernel.actions.replaceSubPane(paneId, indicatorId, params),
+        setParams: (paneId, params) => this.kernel.actions.updateSubPaneParams(paneId, params),
+        clear: () => this.kernel.actions.clearSubPanes(),
+      },
       runRendererTransaction: (run) => this.runRuntimeProjection(run),
     })
 
@@ -456,10 +438,10 @@ export class Chart {
       getSceneRenderer: () => this.rendererHost.renderer,
       getPluginHost: () => this.pluginHost,
       getRendererPluginManager: () => this.rendererPluginManager,
-      getTheme: () => this.kernel.effectiveTheme$.peek(),
-      getCurrentZoomLevel: () => this.kernel.zoom.readonly.zoomLevel.peek(),
-      getZoomLevelCount: () => this.kernel.options.readonly.options.peek().zoomLevelCount,
-      getViewportManager: () => this.viewportManager,
+      theme$: this.kernel.effectiveTheme$,
+      zoom: this.kernel.zoom,
+      options: this.kernel.options,
+      viewport: this.kernel.viewport,
       getDataManager: () => this.dataManager,
       getIndicatorManager: () => this.indicatorManager,
       getActiveMode: () => this._activeMode,
@@ -468,6 +450,9 @@ export class Chart {
       drawings$: this.kernel.drawing.readonly.drawings,
       selectedDrawingId$: this.kernel.drawing.readonly.selectedDrawingId,
       getOverlay: () => this.drawingSession?.getPaintOverlay() ?? [],
+      onLegendContext: (ctx) => {
+        this._legendTemplateContext.set(ctx)
+      },
     })
     this.renderer.registerDrawingPlugins()
     this.renderer.initCoreRenderers()
@@ -476,7 +461,8 @@ export class Chart {
   }
 
   getViewport(): Viewport | null {
-    return this.viewportManager.getViewport()
+    if (this.kernel.viewport.readonly.viewWidth.peek() === 0) return null
+    return this.kernel.viewport.readonly.viewport.peek()
   }
 
   /** 获取当前活跃的模式处理器 */
@@ -490,17 +476,21 @@ export class Chart {
     const prev = this._activeMode
 
     if (mode === this._timeShareMode) {
+      const candlePlugin = this.rendererPluginManager.getPlugin('candle')
       this._savedTimeShareState = {
         zoomLevel: this.kernel.zoom.readonly.zoomLevel.peek(),
         scaleTypes: new Map(this.kernel.pane.readonly.paneScaleTypes.peek()),
         mainIndicators: [],
         subPanes: [],
+        paneRatios: { ...this.kernel.pane.readonly.paneRatios.peek() },
+        candleEnabled: candlePlugin?.enabled !== false,
       }
       for (const [id, entry] of this.kernel.indicator.readonly.mainIndicators.peek()) {
         this._savedTimeShareState.mainIndicators.push({ id, params: { ...entry.params } })
       }
       this._savedTimeShareState.subPanes = this.indicatorManager.getSubPaneEntries().map((e) => ({
-        id: e.indicatorId,
+        paneId: e.paneId,
+        indicatorId: e.indicatorId,
         params: { ...e.params },
       }))
       // 分时强制 percent 进 kernel，再投影（不再由 updatePaneRange 每帧旁路写）
@@ -546,7 +536,7 @@ export class Chart {
 
     if (mode === this._timeShareMode) {
       for (const { id } of this._savedTimeShareState!.mainIndicators) {
-        if (id !== 'TIMESHARE') {
+        if (id !== 'TIMESHARE' && id !== 'timeShare') {
           this.indicatorManager.disableMainIndicator(id)
         }
       }
@@ -555,13 +545,26 @@ export class Chart {
       const saved = this._savedTimeShareState
       if (saved) {
         for (const { id, params } of saved.mainIndicators) {
-          if (id !== 'TIMESHARE') {
+          if (id !== 'TIMESHARE' && id !== 'timeShare') {
             this.indicatorManager.enableMainIndicator(id, params)
           }
         }
-        for (const { id, params } of saved.subPanes) {
-          this.indicatorManager.addIndicator(id, 'sub', params)
+        for (const { paneId, indicatorId, params } of saved.subPanes) {
+          this.indicatorManager.createSubPane(
+            paneId,
+            indicatorId as SubIndicatorType,
+            params as Record<string, number | boolean | string>,
+          )
+        }
+        // 恢复进入分时前的 pane 比例（createSubPane 会重算 3:1 分配）
+        if (Object.keys(saved.paneRatios).length > 0) {
+          const specs = this.kernel.pane.readonly.paneSpecs.peek().map((pane) => ({
+            ...pane,
+            ratio: saved.paneRatios[pane.id] ?? pane.ratio,
+          }))
+          this.kernel.pane.actions.commitLayout(saved.paneRatios, specs)
         }
+        this.setRendererEnabled('candle', saved.candleEnabled)
       }
       this._savedTimeShareState = null
     }
@@ -572,7 +575,7 @@ export class Chart {
   }
 
   getCurrentDpr(): number {
-    return this.viewportManager.getEffectiveDpr()
+    return this.kernel.viewport.readonly.dpr.peek()
   }
 
   /** 获取当前周期 */
@@ -580,25 +583,6 @@ export class Chart {
     return this.dataManager.currentPeriod
   }
 
-  /** 获取缓存的 scrollLeft（避免读取 DOM 触发强制回流） */
-  getCachedScrollLeft(): number {
-    return this.viewportManager.getCachedScrollLeft()
-  }
-
-  /** 同步程序性 scrollLeft 写入后的缓存，避免等待异步 scroll 事件 */
-  syncScrollLeft(scrollLeft: number): void {
-    this.viewportManager.setScrollLeft(scrollLeft)
-  }
-
-  setScrollLeft(v: number): void {
-    this.viewportManager.setScrollLeft(v)
-  }
-
-  /** 获取逻辑 scrollLeft（减去左侧加载缓冲宽度，可为负值） */
-  getLogicalScrollLeft(): number {
-    return this.viewportManager.getLogicalScrollLeft()
-  }
-
   /** 获取插件宿主 */
   get plugin(): PluginHostImpl {
     return this.pluginHost
@@ -1211,14 +1195,14 @@ export class Chart {
   resize() {
     if (this._activeMode === this._timeShareMode) {
       const tsData = this.dataManager.getTimeShareData()
-      const vp = this.viewportManager.computeViewport()
+      const vp = this.getViewport()
       if (!vp || vp.plotWidth <= 0) return
       if (tsData.length > 0) {
         const result = this._activeMode.computeKWidth(tsData.length, vp.plotWidth, vp.dpr)
         if (result) {
           this.applyRenderState(result.kWidth, result.kGap)
           const leftBuffer = this.getLeftLoadBufferWidth()
-          this.viewportManager.setScrollLeft(leftBuffer)
+          this.kernel.viewport.actions.scrollTo(leftBuffer)
         }
       }
       this.renderer.clearCachedFrame()
@@ -1226,7 +1210,7 @@ export class Chart {
       this.scheduleDraw()
       return
     }
-    const vp = this.viewportManager.computeViewport()
+    const vp = this.getViewport()
     // 防御性检查：容器尺寸无效时跳过布局
     if (!vp || vp.viewWidth < 10 || vp.viewHeight < 10) {
       return
@@ -1241,22 +1225,27 @@ export class Chart {
    * @param level 更新级别，默认为 All
    */
   scheduleDraw(level: UpdateLevel = UpdateLevel.All): void {
+    // 正在批量安装/卸载 renderer（pane 重排、指标切换、子图增删），等全部完成再 flush
     if (this.runtimeProjectionDepth > 0) {
-      this.runtimeProjectionDrawPending = true
+      this.pendingProjectionLevel = this.pendingProjectionLevel
+        ? mergeUpdateLevel(this.pendingProjectionLevel, level)
+        : level
       return
     }
     this.renderer.scheduleDraw(level)
   }
 
+  /** 在 RendererPluginManager 事务内执行 run，推迟期间的所有 scheduleDraw 到最外层统一 flush */
   private runRuntimeProjection(run: () => void): void {
     this.runtimeProjectionDepth++
     try {
       this.rendererPluginManager.transaction(run)
     } finally {
       this.runtimeProjectionDepth--
-      if (this.runtimeProjectionDepth === 0 && this.runtimeProjectionDrawPending) {
-        this.runtimeProjectionDrawPending = false
-        this.renderer?.scheduleDraw(UpdateLevel.All)
+      if (this.runtimeProjectionDepth === 0 && this.pendingProjectionLevel !== null) {
+        const level = this.pendingProjectionLevel
+        this.pendingProjectionLevel = null
+        this.renderer?.scheduleDraw(level)
       }
     }
   }
@@ -1310,10 +1299,6 @@ export class Chart {
     await this.pluginHost.destroy()
   }
 
-  private computeViewport(): Viewport | null {
-    return this.viewportManager.computeViewport()
-  }
-
   // ==================== Facade API (High-level interface for adapters) ====================
 
   /** interactionSnapshot lazy computed for the createChartController facade */
@@ -1329,7 +1314,7 @@ export class Chart {
 
   /** 视口状态信号 */
   get viewport(): ReadonlySignal<ViewportState> {
-    return this.viewportManager.viewportSignal
+    return this.kernel.viewport.readonly.viewportState
   }
 
   /** 数据信号 */
@@ -1359,12 +1344,12 @@ export class Chart {
 
   /** 比较商品颜色信号 */
   get comparisonColors(): ReadonlySignal<ReadonlyMap<string, string>> {
-    return this.dataManager.comparisonColors
+    return this.kernel.comparison.readonly.colors
   }
 
   /** 比较商品加载信号 */
   get comparisonLoading(): ReadonlySignal<boolean> {
-    return this.dataManager.comparisonLoading
+    return this.kernel.comparison.readonly.loading
   }
 
   /** 生效主题信号（settings.theme + systemTheme 推导） */
@@ -1414,6 +1399,11 @@ export class Chart {
     return this._interactionSnapshot
   }
 
+  /** 主图左上角图例模板上下文（null 表示无数据） */
+  get legendTemplateContext(): ReadonlySignal<LegendTemplateContext | null> {
+    return this._legendTemplateContext
+  }
+
   // ---------- Data ----------
 
   setData(data: KLineData[]): void {

package/src/engine/chartTypes.ts

@@ -22,7 +22,10 @@ export type PaneRendererDom = {
   mainCanvas: HTMLCanvasElement
   overlayCanvas: HTMLCanvasElement
   yAxisCanvas: HTMLCanvasElement
+  /** 轴区动态层（最新价标签、十字线价签），叠在 yAxisCanvas 上 */
+  yAxisOverlayCanvas: HTMLCanvasElement
   leftYAxisCanvas?: HTMLCanvasElement
+  leftYAxisOverlayCanvas?: HTMLCanvasElement
 }
 
 export type ChartOptions = {
@@ -58,7 +61,9 @@ export type ViewportState = {
   plotWidth: number
   plotHeight: number
   dpr: number
+  /** 可索引可见起点（已 clamp start>=0） */
   visibleFrom: number
+  /** 可索引可见终点（开区间） */
   visibleTo: number
   kWidth: number
   kGap: number

package/src/engine/controller/__tests__/interaction.dpr.test.ts

@@ -223,8 +223,22 @@ function createChartStub(args: {
       dpr: args.dpr,
     }),
     getCurrentDpr: () => args.dpr,
-    getCachedScrollLeft: () => 0,
-    getLogicalScrollLeft: () => 0,
+    kernel: {
+      viewport: {
+        readonly: {
+          scrollLeft: { peek: () => 0 },
+          scrollLeftLogical: { peek: () => 0 },
+        },
+        actions: {
+          scrollTo: () => undefined,
+        },
+      },
+      settings: {
+        readonly: {
+          settings: { peek: () => ({}) },
+        },
+      },
+    },
     getMarkerManager: () => markerManager,
     getPaneRenderers: () => paneRenderers,
     getData: () => data,
@@ -302,6 +316,29 @@ describe('InteractionController DPR consumption', () => {
     expect(interaction.crosshairPos).toBeNull()
     expect(interaction.crosshairIndex).toBeNull()
   })
+
+  it('indexes bars from sealed frameVisibleRange, not stale viewport.visibleFrom', () => {
+    // hit-test 与 positions 必须同帧同源；即使 viewport 快照与 seal range 不一致，也以 seal 为准
+    const chart = createChartStub({ dpr: 1, plotWidth: 300, plotHeight: 160 })
+    chart.viewport.peek = () => ({
+      zoomLevel: 1,
+      plotWidth: 300,
+      plotHeight: 160,
+      dpr: 1,
+      visibleFrom: 99,
+      visibleTo: 101,
+      kWidth: 6,
+      kGap: 2,
+    })
+    const interaction = new InteractionController(chart as never, createMockInteractionState())
+    interaction.setKLinePositions([0, 10], { start: 0, end: 2 }, 10)
+
+    interaction.onPointerMove({ clientX: 5, clientY: 40, isPrimary: true } as PointerEvent)
+    interaction.flushPendingHover()
+
+    expect(interaction.crosshairIndex).toBe(0)
+    expect(interaction.crosshairPos).not.toBeNull()
+  })
 })
 
 describe('InteractionController pane capability gating', () => {

package/src/engine/controller/interaction.ts

@@ -89,6 +89,8 @@ export class InteractionController {
   private framePositions: number[] | null = null
   private frameCenters: number[] | null = null
   private frameKWidthPx: number | null = null
+  /** 与 framePositions 同代的可见区间（已 clamp start>=0，与 calcKLinePositions 一致） */
+  private frameVisibleRange: { start: number; end: number } | null = null
   private markerState = new MarkerInteractionState()
   private lastHoverRenderKey = ''
   private useTooltipAnchorPositioning = false
@@ -211,7 +213,7 @@ export class InteractionController {
     if (!location) return
 
     const { mouseX, mouseY } = location
-    const scrollLeft = this.chart.getLogicalScrollLeft()
+    const scrollLeft = this.chart.kernel.viewport.readonly.scrollLeftLogical.peek()
 
     const markerManager = this.chart.getMarkerManager()
     const worldX = scrollLeft + mouseX
@@ -248,7 +250,7 @@ export class InteractionController {
     // 触屏始终以 pan 模式开始，长按后才切换为 explore
     this.dragStartX = e.clientX
     this.dragStartY = e.clientY
-    this.scrollStartX = this.chart.getCachedScrollLeft()
+    this.scrollStartX = this.chart.kernel.viewport.readonly.scrollLeft.peek()
     this._cachedMaxScrollLeft = -1
     const captureContainer = this.chart.getDom().container
     captureContainer?.setPointerCapture(e.pointerId)
@@ -348,6 +350,7 @@ export class InteractionController {
     this.framePositions = null
     this.frameCenters = null
     this.frameKWidthPx = null
+    this.frameVisibleRange = null
     this.hoverFlushPending = false
     this.clearHover()
     if (options.scheduleDraw !== false) {
@@ -419,7 +422,7 @@ export class InteractionController {
         }
         const clamped = Math.min(Math.max(0, this.scrollStartX + deltaX), this._cachedMaxScrollLeft)
         const dpr = this.chart.getCurrentDpr()
-        this.chart.syncScrollLeft(Math.round(clamped * dpr) / dpr)
+        this.chart.kernel.viewport.actions.scrollTo(Math.round(clamped * dpr) / dpr)
 
         const deltaY = e.clientY - this.dragStartY
         this.dragStartY = e.clientY
@@ -467,26 +470,30 @@ export class InteractionController {
    * ChartRenderer 在 paint 前调用；引用未变则跳过 hover 重算。
    *
    * @param positions K 线起始 x 坐标数组
-   * @param visibleRange 保留兼容签名（hover 用 viewport）
+   * @param visibleRange 与 positions 同代的可见区间（start 已 clamp 到 >=0）
    * @param kWidthPx K 线宽度（物理像素）
    * @param centers K 线中心 x 坐标数组
    */
   setKLinePositions(
     positions: number[] | null,
-    _visibleRange: { start: number; end: number } | null,
+    visibleRange: { start: number; end: number } | null,
     kWidthPx?: number,
     centers?: number[] | null,
   ) {
     const nextWidth = kWidthPx ?? null
     const nextCenters = centers ?? null
+    const nextRange = visibleRange
     const unchanged =
       this.framePositions === positions &&
       this.frameCenters === nextCenters &&
-      this.frameKWidthPx === nextWidth
+      this.frameKWidthPx === nextWidth &&
+      this.frameVisibleRange?.start === nextRange?.start &&
+      this.frameVisibleRange?.end === nextRange?.end
 
     this.framePositions = positions
     this.frameCenters = nextCenters
     this.frameKWidthPx = nextWidth
+    this.frameVisibleRange = nextRange
 
     // 几何变化时标记 hover 待刷新；由 flushPendingHover 与 paint 同帧完成
     if (!unchanged && this.lastClientPos && !this._state.readonly.isDragging.peek()) {
@@ -726,7 +733,7 @@ if (this.tooltipPositionMode === 'adaptive') {
       return null
     }
 
-    const scrollLeft = this.chart.getLogicalScrollLeft()
+    const scrollLeft = this.chart.kernel.viewport.readonly.scrollLeftLogical.peek()
     const dpr = this.chart.getCurrentDpr()
 
     return {
@@ -785,11 +792,11 @@ if (this.tooltipPositionMode === 'adaptive') {
   private findNearestBar(ctx: HoverContext): NearestBar | null {
     const kLinePositions = this.framePositions
     const kWidthPx = this.frameKWidthPx
-    const vp = this.chart.viewport.peek()
-    const visibleRange = vp ? { start: vp.visibleFrom, end: vp.visibleTo } : null
+    // 与 framePositions 同代的 seal range（viewport 已 clamp，此处仍用 seal 保证同帧一致）
+    const visibleRange = this.frameVisibleRange
     if (!kLinePositions || !visibleRange || !kWidthPx) return null
 
-    const { worldX, mouseY, dpr, scrollLeft, plotWidth } = ctx
+    const { worldX, dpr, scrollLeft, plotWidth } = ctx
     const kWidthLogical = kWidthPx / dpr
     const positions = kLinePositions
 
@@ -993,6 +1000,7 @@ if (this.tooltipPositionMode === 'adaptive') {
     this.framePositions = null
     this.frameCenters = null
     this.frameKWidthPx = null
+    this.frameVisibleRange = null
     this.lastHoverRenderKey = ''
   }