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

package/src/engine/renderers/yAxis.ts

@@ -1,37 +1,37 @@
 import type { RendererPlugin, RenderContext } from '../../foundation/plugin/index'
 import { RENDERER_PRIORITY, GLOBAL_PANE_ID } from '../../foundation/plugin/index'
 import { resolveThemeColors } from '../../foundation/tokens/index'
-import type { KLineData } from '../../foundation/types/price'
 import { drawCrosshairPriceLabel, drawAxisPriceLabel } from '../../foundation/utils/kLineDraw/axis'
 import { roundToPhysicalPixel } from '../../foundation/utils/pixelAlign'
 import { getFont, setCanvasFont } from '../../foundation/tokens/fonts'
 
-/**
- * 创建 Y 轴渲染器插件
- * 按 pane capability 决定是否绘制刻度与价格标签
- */
-export function createYAxisRendererPlugin(options: {
+type YAxisOptions = {
   axisWidth: number
   yPaddingPx: number
   getCrosshair?: () => { y: number; price: number; activePaneId: string | null } | null
-}): RendererPlugin {
+}
+
+function shouldShowRightAxis(period: string, settings: RenderContext['settings']): boolean {
+  if (period === 'timeshare') return true
+  const rightType = settings?.rightAxisType as string | undefined
+  return rightType !== 'none'
+}
+
+/**
+ * Y 轴静态层：刻度 + 价格范围带，画到 yAxisCtx（main 级刷新）
+ */
+export function createYAxisStaticRendererPlugin(options: YAxisOptions): RendererPlugin {
   return {
     name: 'yAxis',
-    version: '1.0.0',
-    description: 'Y轴价格刻度渲染器',
-    debugName: 'Y轴',
+    version: '2.0.0',
+    description: 'Y轴价格刻度渲染器（静态）',
+    debugName: 'Y轴刻度',
     paneId: GLOBAL_PANE_ID,
     priority: RENDERER_PRIORITY.SYSTEM_YAXIS,
-    layer: 'overlay',
 
     draw(context: RenderContext) {
-      const { ctx, pane, dpr, yAxisCtx, data, period } = context
-
-      // 分时模式始终显示右轴，不受设置约束
-      if (period !== 'timeshare') {
-        const rightType = context.settings?.rightAxisType as string | undefined
-        if (rightType === 'none') return
-      }
+      const { ctx, pane, dpr, yAxisCtx, period } = context
+      if (!shouldShowRightAxis(period, context.settings)) return
 
       const tokenColors = resolveThemeColors(
         context.theme,
@@ -39,11 +39,8 @@ export function createYAxisRendererPlugin(options: {
         context.colorPresetSettings,
       )
       const scaleType = pane.yAxis.getScaleType()
-
       const targetCtx = yAxisCtx || ctx
       const axisWidth = yAxisCtx?.canvas ? yAxisCtx.canvas.width / dpr : options.axisWidth
-      const displayRange = pane.yAxis.getDisplayRange(pane.priceRange)
-
       const isPercent = scaleType === 'percent' && pane.role === 'price'
 
       if (pane.capabilities.showPriceAxisTicks && context.yAxisTicks) {
@@ -70,7 +67,7 @@ export function createYAxisRendererPlugin(options: {
         }
       }
 
-      // 绘制价格范围带（先于标签，使标签覆盖在范围带之上）
+      // 价格范围带（先于标签，使标签覆盖在范围带之上）
       if (context.yAxisRanges && pane.role === 'price') {
         for (const range of context.yAxisRanges) {
           const topY = range.topY + pane.top
@@ -83,6 +80,36 @@ export function createYAxisRendererPlugin(options: {
           targetCtx.restore()
         }
       }
+    },
+  }
+}
+
+/**
+ * Y 轴动态层：yAxisLabels + 十字线价签，画到 yAxisOverlayCtx（overlay 级刷新）
+ */
+export function createYAxisOverlayRendererPlugin(options: YAxisOptions): RendererPlugin {
+  return {
+    name: 'yAxisOverlay',
+    version: '2.0.0',
+    description: 'Y轴动态标签渲染器',
+    debugName: 'Y轴标签',
+    paneId: GLOBAL_PANE_ID,
+    priority: RENDERER_PRIORITY.SYSTEM_YAXIS + 1,
+    layer: 'overlay',
+
+    draw(context: RenderContext) {
+      const { pane, dpr, yAxisOverlayCtx, yAxisCtx, period } = context
+      if (!shouldShowRightAxis(period, context.settings)) return
+
+      const targetCtx = yAxisOverlayCtx ?? yAxisCtx
+      if (!targetCtx) return
+
+      const axisWidth = targetCtx.canvas ? targetCtx.canvas.width / dpr : options.axisWidth
+      targetCtx.clearRect(0, 0, axisWidth, pane.height)
+
+      const scaleType = pane.yAxis.getScaleType()
+      const displayRange = pane.yAxis.getDisplayRange(pane.priceRange)
+      const isPercent = scaleType === 'percent' && pane.role === 'price'
 
       // 绘制来自 yAxisLabels 的标签（最新价格、极值点、绘图锚点等）
       if (context.yAxisLabels && pane.role === 'price') {
@@ -151,3 +178,11 @@ export function createYAxisRendererPlugin(options: {
     },
   }
 }
+
+/**
+ * @deprecated 使用 createYAxisStaticRendererPlugin + createYAxisOverlayRendererPlugin
+ * 保留兼容：静态+动态合画到 yAxisCtx
+ */
+export function createYAxisRendererPlugin(options: YAxisOptions): RendererPlugin {
+  return createYAxisStaticRendererPlugin(options)
+}

package/src/engine/state/__tests__/settingsState.test.ts

@@ -43,4 +43,13 @@ describe('settingsState', () => {
       ;(snap as { showGridLines?: boolean }).showGridLines = false
     }).toThrow()
   })
+
+  it('preserves extension keys like preClose through resolve/patch', () => {
+    expect(resolveSettings({ preClose: 12.34 }).preClose).toBe(12.34)
+    const s = createSettingsState({ preClose: 12.34 })
+    expect(s.readonly.settings.peek().preClose).toBe(12.34)
+    s.actions.patch({ showGridLines: false })
+    expect(s.readonly.settings.peek().preClose).toBe(12.34)
+    expect(s.readonly.settings.peek().showGridLines).toBe(false)
+  })
 })

package/src/engine/state/viewportState.ts

@@ -7,7 +7,7 @@ import {
 } from '../../foundation/reactivity/signal'
 import type { Viewport, ViewportState } from '../chartTypes'
 import type { VisibleRange } from '../layout/pane'
-import { getVisibleRange } from '../viewport/viewport'
+import { clampVisibleRange, getVisibleRange } from '../viewport/viewport'
 import {
   computeLeftLoadBufferWidth as pureLeftBuffer,
   computeContentWidth as pureContentWidth,
@@ -197,8 +197,8 @@ export function createViewportState(signalDeps: ViewportSignalDeps) {
     return vp
   })
 
-  let _cachedVisibleRange: VisibleRange | null = null
-  const cachedVisibleRange = computed<VisibleRange>(() => {
+  let _cachedRawVisibleRange: VisibleRange | null = null
+  const cachedRawVisibleRange = computed<VisibleRange>(() => {
     const vp = cachedViewport()
     const opts = signalDeps.options$()
     const vr = getVisibleRange(
@@ -209,13 +209,32 @@ export function createViewportState(signalDeps: ViewportSignalDeps) {
       signalDeps.dataLength$(),
       vp.dpr,
     )
-    if (_cachedVisibleRange && _cachedVisibleRange.start === vr.start && _cachedVisibleRange.end === vr.end) {
-      return _cachedVisibleRange
+    if (
+      _cachedRawVisibleRange &&
+      _cachedRawVisibleRange.start === vr.start &&
+      _cachedRawVisibleRange.end === vr.end
+    ) {
+      return _cachedRawVisibleRange
     }
-    _cachedVisibleRange = vr
+    _cachedRawVisibleRange = vr
     return vr
   })
 
+  // 可索引可见区间（start>=0）— 绘制 / hit-test / 指标 / ViewportState 的 SSOT
+  let _cachedVisibleRange: VisibleRange | null = null
+  const cachedVisibleRange = computed<VisibleRange>(() => {
+    const clamped = clampVisibleRange(cachedRawVisibleRange())
+    if (
+      _cachedVisibleRange &&
+      _cachedVisibleRange.start === clamped.start &&
+      _cachedVisibleRange.end === clamped.end
+    ) {
+      return _cachedVisibleRange
+    }
+    _cachedVisibleRange = clamped
+    return clamped
+  })
+
   let _cachedViewportState: ViewportState | null = null
   const cachedViewportState = computed<ViewportState>(() => {
     const vp = cachedViewport()
@@ -355,6 +374,9 @@ export function createViewportState(signalDeps: ViewportSignalDeps) {
     scrollLeftLogical,
     kGap,
     viewport: cachedViewport,
+    /** raw：含左右扩窗，start 可能为 -1（增量加载左缘检测） */
+    rawVisibleRange: cachedRawVisibleRange,
+    /** clamped：start>=0，绘制 / hit-test / 指标 / ViewportState 的 SSOT */
     visibleRange: cachedVisibleRange,
     viewportState: cachedViewportState,
   }
@@ -414,7 +436,7 @@ export function createViewportState(signalDeps: ViewportSignalDeps) {
       /**
        * 初始化视口状态。
        *
-       * @remarks 从 DOM 容器读取当前 scrollLeft，并挂载 canvas 尺寸同步 effect。
+       * @remarks 从 DOM 容器读取首帧尺寸与 scrollLeft，并挂载 canvas 尺寸同步 effect。
        * 重复调用安全（仅首次生效）。
        */
       init() {
@@ -423,7 +445,21 @@ export function createViewportState(signalDeps: ViewportSignalDeps) {
         const container = _getDom().container
         if (!container) return
         signals.initialized.set(true)
-        setRequestedScrollLeft(container.scrollLeft)
+        // 首帧尺寸写入 kernel，避免 paint 路径读 DOM fallback
+        const w = Math.max(0, Math.round(container.clientWidth))
+        const h = Math.max(0, Math.round(container.clientHeight))
+        batch(() => {
+          if (w > 0 && h > 0) {
+            signals.viewWidth.set(w)
+            signals.viewHeight.set(h)
+          }
+          // 与 resize 一致：首帧 scrollLeft 为 0 时落到 viewWidth
+          if (container.scrollLeft === 0 && w > 0) {
+            signals.requestedScrollLeft.set(w)
+          } else {
+            setRequestedScrollLeft(container.scrollLeft)
+          }
+        })
         setupCanvasSync()
       },
     },

package/src/engine/subPaneManager.ts

@@ -44,9 +44,11 @@ export interface SubPaneContext {
   removeRenderer: (name: string) => void
   setRendererEnabled: (name: string, enabled: boolean) => void
   updateRendererConfig: (name: string, config: Record<string, unknown>) => void
-  getRightAxisWidth: () => number
-  getPriceLabelWidth: () => number
-  getYPaddingPx: () => number
+  getOption: () => {
+    rightAxisWidth: number
+    priceLabelWidth?: number
+    yPaddingPx: number
+  }
   getCrosshairPos: () => { x: number; y: number } | null
   getCrosshairPrice: () => number | null
   getActivePaneId: () => string | null
@@ -203,7 +205,8 @@ export class SubPaneManager {
       return
     }
     const definition = ctx.getIndicatorScheduler().getIndicatorMetadata(entry.indicatorId)
-    const axisWidth = ctx.getRightAxisWidth() + ctx.getPriceLabelWidth()
+    const opt = ctx.getOption()
+    const axisWidth = opt.rightAxisWidth + (opt.priceLabelWidth ?? 60)
     const getCrosshair = () => {
       const pos = ctx.getCrosshairPos()
       const price = ctx.getCrosshairPrice()
@@ -213,7 +216,7 @@ export class SubPaneManager {
     const options = {
       axisWidth,
       paneId: entry.paneId,
-      yPaddingPx: ctx.getYPaddingPx(),
+      yPaddingPx: opt.yPaddingPx,
       getCrosshair,
     }
     const plugin = definition?.scaleRendererFactory

package/src/engine/utils/chartZoomController.ts

@@ -1,18 +1,20 @@
 import { computeZoom, deriveKGap } from './zoom'
+import type { ReadonlySignal } from '../../foundation/reactivity/signal'
+import type { OptionsStateModule } from '../state/optionsState'
 import type { ZoomStateModule } from '../state/zoomState'
+import type { ViewportStateModule } from '../state/viewportState'
 
 export interface ZoomDependencies {
-  getLogicalScrollLeft: () => number
-  getCurrentDpr: () => number
+  /** scroll / dpr 几何，读写走 kernel.viewport */
+  viewport: ViewportStateModule
+  /** min/max kWidth / zoomLevelCount SSOT */
+  options: OptionsStateModule
+  /** 当前周期（kGap 推导） */
+  period$: ReadonlySignal<string>
   getClientWidth: () => number
   getDataLength: () => number
   getPlotWidth: () => number
-  setScrollLeft: (v: number) => void
   onChange?: () => void
-  getMinKWidth: () => number
-  getMaxKWidth: () => number
-  getPeriod: () => string
-  zoomLevelCount: number
 }
 
 /**
@@ -39,17 +41,17 @@ export class ChartZoomController {
   get currentKGap(): number {
     return deriveKGap({
       kWidth: this.currentKWidth,
-      dpr: this.deps.getCurrentDpr(),
-      period: this.deps.getPeriod(),
+      dpr: this.deps.viewport.readonly.dpr.peek(),
+      period: this.deps.period$.peek(),
     })
   }
 
   get zoomLevelCount(): number {
-    return this.deps.zoomLevelCount
+    return this.deps.options.readonly.options.peek().zoomLevelCount
   }
 
   zoomToLevel(level: number, anchorX?: number): void {
-    const clamped = Math.max(1, Math.min(this.deps.zoomLevelCount, Math.round(level)))
+    const clamped = Math.max(1, Math.min(this.zoomLevelCount, Math.round(level)))
     this.applyZoom(clamped, anchorX)
   }
 
@@ -65,7 +67,7 @@ export class ChartZoomController {
     const delta = deltaY > 0 ? -1 : 1
     const targetLevel = Math.max(
       1,
-      Math.min(this.deps.zoomLevelCount, this.currentZoomLevel + delta),
+      Math.min(this.zoomLevelCount, this.currentZoomLevel + delta),
     )
     if (targetLevel === this.currentZoomLevel) return
     this.applyZoom(targetLevel, viewportX)
@@ -74,7 +76,7 @@ export class ChartZoomController {
   handlePinch(delta: number, centerClientX: number): void {
     const targetLevel = Math.max(
       1,
-      Math.min(this.deps.zoomLevelCount, this.currentZoomLevel + delta),
+      Math.min(this.zoomLevelCount, this.currentZoomLevel + delta),
     )
     if (targetLevel === this.currentZoomLevel) return
     this.applyZoom(targetLevel, centerClientX)
@@ -84,8 +86,9 @@ export class ChartZoomController {
     if (targetLevel === this.currentZoomLevel) return
 
     const delta = targetLevel - this.currentZoomLevel
-    const logicalScrollLeft = this.deps.getLogicalScrollLeft()
-    const dpr = this.deps.getCurrentDpr()
+    const logicalScrollLeft = this.deps.viewport.readonly.scrollLeftLogical.peek()
+    const dpr = this.deps.viewport.readonly.dpr.peek()
+    const opt = this.deps.options.readonly.options.peek()
 
     const result = computeZoom(
       delta,
@@ -95,9 +98,9 @@ export class ChartZoomController {
       this.currentKWidth,
       this.currentKGap,
       {
-        minKWidth: this.deps.getMinKWidth(),
-        maxKWidth: this.deps.getMaxKWidth(),
-        zoomLevelCount: this.deps.zoomLevelCount,
+        minKWidth: opt.minKWidth,
+        maxKWidth: opt.maxKWidth,
+        zoomLevelCount: opt.zoomLevelCount,
         dpr,
         dataLength: this.deps.getDataLength(),
         plotWidth: this.deps.getPlotWidth(),
@@ -108,7 +111,7 @@ export class ChartZoomController {
     if (!result) return
 
     this.zoomState.actions.setZoomLevel(result.targetLevel)
-    this.deps.setScrollLeft(result.newDomScrollLeft)
+    this.deps.viewport.actions.scrollTo(result.newDomScrollLeft)
     this.deps.onChange?.()
   }
 }

package/src/engine/viewport/__tests__/visibleRange.clamp.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest'
+
+import { createSignal } from '../../../foundation/reactivity/signal'
+import { createViewportState } from '../../state/viewportState'
+import { clampVisibleRange, getVisibleRange } from '../viewport'
+
+describe('clampVisibleRange', () => {
+  it('clamps negative start to 0 and preserves end', () => {
+    expect(clampVisibleRange({ start: -1, end: 40 })).toEqual({ start: 0, end: 40 })
+  })
+
+  it('leaves non-negative start unchanged', () => {
+    expect(clampVisibleRange({ start: 12, end: 50 })).toEqual({ start: 12, end: 50 })
+  })
+})
+
+describe('getVisibleRange raw expansion', () => {
+  it('may return start < 0 when scroll is near the left edge (expansion pad)', () => {
+    // scrollLeft=0, first bars sit near plot origin → start-1 扩窗
+    const raw = getVisibleRange(0, 800, 8, 2, 100, 1)
+    expect(raw.start).toBeLessThan(0)
+    expect(raw.end).toBeGreaterThan(0)
+  })
+})
+
+describe('viewportState visibleRange SSOT', () => {
+  it('exposes clamped visibleRange/visibleFrom while keeping rawVisibleRange for load triggers', async () => {
+    const dataLength$ = createSignal(20)
+    const module = createViewportState({
+      options$: (() => ({ bottomAxisHeight: 30, kWidth: 8, kGap: 2 })) as any,
+      dataLength$,
+      period$: (() => 'daily') as any,
+      zoomLevel$: (() => 3) as any,
+    })
+
+    // resize 后 scrollLeftLogical≈0（右对齐短序列或左缘），raw start 常为 -1
+    module.actions.resize(800, 400, 1)
+    module.actions.scrollTo(module.readonly.leftLoadBufferWidth.peek())
+
+    const raw = module.readonly.rawVisibleRange()
+    const clamped = module.readonly.visibleRange()
+    const vs = module.readonly.viewportState()
+
+    expect(raw.start).toBeLessThan(0)
+    expect(clamped.start).toBe(0)
+    expect(clamped.end).toBe(raw.end)
+    expect(vs.visibleFrom).toBe(0)
+    expect(vs.visibleTo).toBe(clamped.end)
+  })
+})

package/src/engine/viewport/chartViewportManager.ts

@@ -1,69 +1,40 @@
-import { type ReadonlySignal } from '../../foundation/reactivity/signal'
-import type { ChartDom, Viewport, ViewportState } from '../chartTypes'
+import type { ChartDom } from '../chartTypes'
 import type { ChartStateKernel } from '../state/chartStateKernel'
 
-/** Minimal manager-level deps (DOM + lifecycle callbacks). */
+/** DOM 生命周期依赖：ResizeObserver / scroll 监听 */
 export interface ViewportDependencies {
   getDom: () => ChartDom
   onResizeCompleted: () => void
 }
 
+/**
+ * Viewport DOM 适配层：只挂 ResizeObserver 与 scroll，读写一律走 kernel。
+ */
 export class ChartViewportManager {
   private deps: ViewportDependencies
   private kernel: ChartStateKernel
   private resizeObserver?: ResizeObserver
   private onScroll?: (e: Event) => void
 
-  get viewportSignal(): ReadonlySignal<ViewportState> {
-    return this.kernel.viewport.readonly.viewportState
-  }
-
   constructor(deps: ViewportDependencies, kernel: ChartStateKernel) {
     this.deps = deps
     this.kernel = kernel
   }
 
-  getCachedScrollLeft(): number {
-    return this.kernel.viewport.readonly.scrollLeft.peek()
-  }
-
-  getLogicalScrollLeft(): number {
-    return this.kernel.viewport.readonly.scrollLeftLogical.peek()
-  }
-
-  getViewport(): Viewport | null {
-    if (this.kernel.viewport.readonly.viewWidth.peek() === 0) return null
-    return this.kernel.viewport.readonly.viewport.peek()
-  }
-
-  getEffectiveDpr(): number {
-    return this.kernel.viewport.readonly.dpr.peek()
-  }
-
-  getObservedSize(): { width: number; height: number } {
-    return {
-      width: this.kernel.viewport.readonly.viewWidth.peek(),
-      height: this.kernel.viewport.readonly.viewHeight.peek(),
-    }
-  }
-
-  setScrollLeft(v: number): void {
-    this.kernel.viewport.actions.scrollTo(v)
-  }
-
   init(): void {
-    if (typeof ResizeObserver === 'undefined') return
-
     const target = this.deps.getDom().container
     if (!target) return
 
+    // 首帧尺寸写入 kernel，不依赖 ResizeObserver 是否可用
     this.kernel.initViewport()
 
-    this.onScroll = (e: Event) => {
+    this.onScroll = () => {
       this.kernel.viewport.actions.syncFromDomScroll()
     }
     target.addEventListener('scroll', this.onScroll, { passive: true })
 
+    if (typeof ResizeObserver === 'undefined') return
+
     this.resizeObserver = new ResizeObserver((entries) => {
       const entry = entries[0]
       if (!entry) return
@@ -119,26 +90,4 @@ export class ChartViewportManager {
       this.onScroll = undefined
     }
   }
-
-  computeViewport(): Viewport | null {
-    const container = this.deps.getDom().container
-    if (!container) return null
-
-    const viewWidth = this.kernel.viewport.readonly.viewWidth.peek()
-    const viewHeight = this.kernel.viewport.readonly.viewHeight.peek()
-    if (viewWidth === 0 || viewHeight === 0) {
-      const fallbackW = Math.max(1, Math.round(container.clientWidth))
-      const fallbackH = Math.max(1, Math.round(container.clientHeight))
-      if (fallbackW > 0 && fallbackH > 0) {
-        this.kernel.viewport.actions.resize(fallbackW, fallbackH, this.kernel.viewport.readonly.preciseDpr.peek())
-      }
-    }
-
-    return this.kernel.viewport.readonly.viewport.peek()
-  }
-
-  /** @deprecated No-op — viewportState is now computed(). */
-  updateViewportSignal(): void {
-    // no-op
-  }
 }

package/src/engine/viewport/viewport.ts

@@ -40,6 +40,20 @@ export function getVisibleRange(
   return { start, end }
 }
 
+/**
+ * 将 raw visible range 钳制为可索引区间。
+ *
+ * @remarks getVisibleRange 左右各扩 1 根时 start 可能为 -1；
+ * 绘制 / hit-test / 数据下标必须用 clamp 后的 start>=0。
+ * 增量加载检测仍读 raw（start 小于 0 表示已滚到左缘扩窗）。
+ */
+export function clampVisibleRange(range: {
+  start: number
+  end: number
+}): { start: number; end: number } {
+  return { start: Math.max(0, range.start), end: range.end }
+}
+
 /**
  * 计算指定索引区间内的价格范围（max/min）。
  *

package/src/foundation/config/chartSettings.ts

@@ -158,6 +158,11 @@ export type ChartSettings = {
  * @param partial - 偏好的部分设置（通常是组件 prop 传入）
  * @returns 合并后的 ChartSettings 对象
  */
+const KNOWN_SETTING_KEYS = new Set<string>([
+  ...DEFAULT_SETTINGS.map((item) => item.key),
+  'colorPresetSettings',
+])
+
 export function resolveSettings(partial?: Partial<ChartSettings>): ChartSettings {
   // 用 Partial<_SettingByKey> 而非 ChartSettings 避免交叉类型索引赋值报错
   const result: Partial<_SettingByKey> = {}
@@ -170,6 +175,14 @@ export function resolveSettings(partial?: Partial<ChartSettings>): ChartSettings
   ;(result as ChartSettings).colorPresetSettings = normalizeColorPresetSettings(
     partial?.colorPresetSettings,
   )
+  // 保留扩展字段（如 preClose），避免业务元数据被 resolve 清掉
+  if (partial) {
+    for (const [key, value] of Object.entries(partial)) {
+      if (KNOWN_SETTING_KEYS.has(key)) continue
+      if (value === undefined) continue
+      ;(result as Record<string, unknown>)[key] = value
+    }
+  }
   return result as ChartSettings
 }
 

package/src/foundation/plugin/rendererPluginManager.test.ts

@@ -2,6 +2,24 @@ import { describe, expect, it, vi } from 'vitest'
 
 import { RendererPluginManager } from './rendererPluginManager'
 
+describe('RendererPluginManager lifecycle', () => {
+  it('installs a renderer plugin exactly once', () => {
+    const manager = new RendererPluginManager()
+    const onInstall = vi.fn()
+    manager.setPluginHost({} as never)
+
+    manager.register({
+      name: 'test',
+      paneId: 'main',
+      priority: 0,
+      draw: vi.fn(),
+      onInstall,
+    })
+
+    expect(onInstall).toHaveBeenCalledTimes(1)
+  })
+})
+
 describe('RendererPluginManager transaction', () => {
   it('coalesces renderer invalidations into one callback', () => {
     const manager = new RendererPluginManager()

package/src/foundation/plugin/types.ts

@@ -304,7 +304,10 @@ export interface RenderContext {
   crosshairIndex?: number | null
   // 可选的其他 Canvas 上下文
   yAxisCtx?: CanvasRenderingContext2D
+  /** 轴区动态层（最新价标签、十字线价签） */
+  yAxisOverlayCtx?: CanvasRenderingContext2D
   leftAxisCtx?: CanvasRenderingContext2D
+  leftAxisOverlayCtx?: CanvasRenderingContext2D
   xAxisCtx?: CanvasRenderingContext2D
   borderCtx?: CanvasRenderingContext2D
   /** 覆盖层 Canvas 上下文（用于十字线、Tooltip 等动态内容） */