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

package/src/engine/__tests__/paneRenderer.resize.test.ts

@@ -4,56 +4,58 @@ import { describe, expect, it } from 'vitest'
 import { Pane } from '@/core/layout/pane'
 import { PaneRenderer } from '@/core/paneRenderer'
 
+function createDom() {
+  return {
+    mainCanvas: document.createElement('canvas'),
+    overlayCanvas: document.createElement('canvas'),
+    yAxisCanvas: document.createElement('canvas'),
+    yAxisOverlayCanvas: document.createElement('canvas'),
+  }
+}
+
 describe('PaneRenderer resize DPR mapping', () => {
   it('maps logical plot size to physical canvas size and keeps CSS size logical', () => {
-    const mainCanvas = document.createElement('canvas')
-    const overlayCanvas = document.createElement('canvas')
-    const yAxisCanvas = document.createElement('canvas')
+    const dom = createDom()
     const pane = new Pane('main')
-    const renderer = new PaneRenderer(
-      { mainCanvas, overlayCanvas, yAxisCanvas },
-      pane,
-      {
-        rightAxisWidth: 80,
-        leftAxisWidth: 60,
-        yPaddingPx: 0,
-        priceLabelWidth: 60,
-      },
-    )
+    const renderer = new PaneRenderer(dom, pane, {
+      rightAxisWidth: 80,
+      leftAxisWidth: 60,
+      yPaddingPx: 0,
+      priceLabelWidth: 60,
+    })
 
     renderer.resize(500, 240, 2)
 
-    expect(mainCanvas.width).toBe(Math.round(500 * 2))
-    expect(mainCanvas.height).toBe(Math.round(240 * 2))
-    expect(mainCanvas.style.width).toBe('500px')
-    expect(mainCanvas.style.height).toBe('240px')
+    expect(dom.mainCanvas.width).toBe(Math.round(500 * 2))
+    expect(dom.mainCanvas.height).toBe(Math.round(240 * 2))
+    expect(dom.mainCanvas.style.width).toBe('500px')
+    expect(dom.mainCanvas.style.height).toBe('240px')
     // overlayCanvas should match mainCanvas
-    expect(overlayCanvas.width).toBe(mainCanvas.width)
-    expect(overlayCanvas.height).toBe(mainCanvas.height)
+    expect(dom.overlayCanvas.width).toBe(dom.mainCanvas.width)
+    expect(dom.overlayCanvas.height).toBe(dom.mainCanvas.height)
+    // yAxis overlay matches yAxis base
+    expect(dom.yAxisOverlayCanvas.width).toBe(dom.yAxisCanvas.width)
+    expect(dom.yAxisOverlayCanvas.height).toBe(dom.yAxisCanvas.height)
   })
 
   it('uses (rightAxisWidth + priceLabelWidth) for yAxis physical width when no parent width is available', () => {
-    const mainCanvas = document.createElement('canvas')
-    const overlayCanvas = document.createElement('canvas')
-    const yAxisCanvas = document.createElement('canvas')
+    const dom = createDom()
     const pane = new Pane('main')
-    const renderer = new PaneRenderer(
-      { mainCanvas, overlayCanvas, yAxisCanvas },
-      pane,
-      {
-        rightAxisWidth: 100,
-        leftAxisWidth: 60,
-        yPaddingPx: 0,
-        priceLabelWidth: 70,
-      },
-    )
+    const renderer = new PaneRenderer(dom, pane, {
+      rightAxisWidth: 100,
+      leftAxisWidth: 60,
+      yPaddingPx: 0,
+      priceLabelWidth: 70,
+    })
 
     renderer.resize(500, 200, 1.5)
 
-    expect(yAxisCanvas.width).toBe(Math.round((100 + 70) * 1.5))
-    expect(yAxisCanvas.height).toBe(Math.round(200 * 1.5))
-    expect(yAxisCanvas.style.width).toBe('170px')
-    expect(yAxisCanvas.style.height).toBe('200px')
+    expect(dom.yAxisCanvas.width).toBe(Math.round((100 + 70) * 1.5))
+    expect(dom.yAxisCanvas.height).toBe(Math.round(200 * 1.5))
+    expect(dom.yAxisCanvas.style.width).toBe('170px')
+    expect(dom.yAxisCanvas.style.height).toBe('200px')
+    expect(dom.yAxisOverlayCanvas.width).toBe(dom.yAxisCanvas.width)
+    expect(dom.yAxisOverlayCanvas.height).toBe(dom.yAxisCanvas.height)
   })
 
   it('uses parent clientWidth for yAxis canvas width when available', () => {
@@ -63,28 +65,24 @@ describe('PaneRenderer resize DPR mapping', () => {
       configurable: true,
     })
 
-    const mainCanvas = document.createElement('canvas')
-    const overlayCanvas = document.createElement('canvas')
-    const yAxisCanvas = document.createElement('canvas')
-    host.appendChild(yAxisCanvas)
+    const dom = createDom()
+    host.appendChild(dom.yAxisCanvas)
+    host.appendChild(dom.yAxisOverlayCanvas)
 
     const pane = new Pane('main')
-    const renderer = new PaneRenderer(
-      { mainCanvas, overlayCanvas, yAxisCanvas },
-      pane,
-      {
-        rightAxisWidth: 100,
-        leftAxisWidth: 60,
-        yPaddingPx: 0,
-        priceLabelWidth: 70,
-      },
-    )
+    const renderer = new PaneRenderer(dom, pane, {
+      rightAxisWidth: 100,
+      leftAxisWidth: 60,
+      yPaddingPx: 0,
+      priceLabelWidth: 70,
+    })
 
     renderer.resize(500, 200, 1.5)
 
-    expect(yAxisCanvas.width).toBe(Math.round(168 * 1.5))
-    expect(yAxisCanvas.height).toBe(Math.round(200 * 1.5))
-    expect(yAxisCanvas.style.width).toBe('168px')
-    expect(yAxisCanvas.style.height).toBe('200px')
+    expect(dom.yAxisCanvas.width).toBe(Math.round(168 * 1.5))
+    expect(dom.yAxisCanvas.height).toBe(Math.round(200 * 1.5))
+    expect(dom.yAxisCanvas.style.width).toBe('168px')
+    expect(dom.yAxisCanvas.style.height).toBe('200px')
+    expect(dom.yAxisOverlayCanvas.width).toBe(dom.yAxisCanvas.width)
   })
 })

package/src/engine/__tests__/subPaneManager.test.ts

@@ -41,9 +41,11 @@ function createMockContext(): SubPaneContext & {
     removeRenderer: vi.fn((name) => renderers.delete(name)),
     setRendererEnabled: vi.fn(),
     updateRendererConfig: vi.fn(),
-    getRightAxisWidth: () => 60,
-    getPriceLabelWidth: () => 60,
-    getYPaddingPx: () => 4,
+    getOption: () => ({
+      rightAxisWidth: 60,
+      priceLabelWidth: 60,
+      yPaddingPx: 4,
+    }),
     getCrosshairPos: () => null,
     getCrosshairPrice: () => null,
     getActivePaneId: () => null,

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
@@ -275,17 +293,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 +314,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 +340,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 +369,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 +388,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 +432,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 +444,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 +455,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()
   }
 
   /** 获取当前活跃的模式处理器 */
@@ -572,7 +552,7 @@ export class Chart {
   }
 
   getCurrentDpr(): number {
-    return this.viewportManager.getEffectiveDpr()
+    return this.kernel.viewport.readonly.dpr.peek()
   }
 
   /** 获取当前周期 */
@@ -580,25 +560,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 +1172,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 +1187,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 +1202,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 +1276,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 +1291,7 @@ export class Chart {
 
   /** 视口状态信号 */
   get viewport(): ReadonlySignal<ViewportState> {
-    return this.viewportManager.viewportSignal
+    return this.kernel.viewport.readonly.viewportState
   }
 
   /** 数据信号 */
@@ -1359,12 +1321,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 +1376,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', () => {