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

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/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 等动态内容） */

package/src/foundation/reactivity/frameTransaction.ts

@@ -10,6 +10,17 @@
  * 一帧固定走 capture → derive → seal → render → publish → complete。
  * render 或 publish 期间的 writeInput 一律进入下一代 pending。
  * 非 idle 时调用 flush 不会嵌套发布，仅保留 dirty 供外层完成后调度。
+ *
+ * @remarks 适用范围
+ * 这是一个半通用的 rAF 合帧器（semi-general frame coalescer），
+ * 专为 ChartRenderer 的绘制管线设计，并非全场景通用的高频处理方案。
+ *
+ * @Todo 如需在其他场景（WebSocket 消息合并、键盘事件批处理）复用，需补充：
+ * - 深层合并 / 自定义 merge 策略（目前 mergeInput 仅浅合并）
+ * - 快照深层不可变保证（目前 sealSnapshotRoot 只冻根对象）
+ * - 超时/失帧策略（目前纯乐观逐帧）
+ * - 背压与优先级集成（FrameBudget 在 scheduler 层但未在此集成）
+ * - 非 Record 输入类型支持（目前 TInput 约束为 Record）
  */
 
 import { createSignal, type ReadonlySignal } from './signal'
@@ -88,10 +99,9 @@ export interface FrameTransaction<TInput extends Record<string, unknown>, TSnaps
  * @typeParam TInput - 可合并的输入形状（浅层 Partial 合并）
  * @typeParam TSnapshot - derive 产出的不可变快照类型
  */
-export function createFrameTransaction<
-  TInput extends Record<string, unknown>,
-  TSnapshot,
->(options: FrameTransactionOptions<TInput, TSnapshot>): FrameTransaction<TInput, TSnapshot> {
+export function createFrameTransaction<TInput extends Record<string, unknown>, TSnapshot>(
+  options: FrameTransactionOptions<TInput, TSnapshot>,
+): FrameTransaction<TInput, TSnapshot> {
   const { derive, render } = options
   const schedule =
     options.schedule ??
@@ -145,24 +155,27 @@ export function createFrameTransaction<
     }
 
     let sealedInput: TInput | undefined
+    // 封存输入，后续写入只能进下一代
     phase = 'capturing'
     try {
       sealedInput = pending
       dirty = false
-      // 本帧 capture 之后的新写入进入 nextPending，不得污染 sealedInput
       pending = { ...sealedInput }
 
+      // 从封存输入纯推导不可变快照
       phase = 'deriving'
       const nextGeneration = generation + 1
       const snapshot = derive(sealedInput, nextGeneration)
 
+      // 冻结快照根对象
       phase = 'sealing'
       sealSnapshotRoot(snapshot)
 
+      // 用本帧快照绘制
       phase = 'rendering'
       render?.(snapshot)
 
-      // 先推进代际再发布，保证订阅者读 generation 与 snapshot.generation 一致
+      // 先推进代际再发布，保证订阅者读到一致代际
       phase = 'publishing'
       generation = nextGeneration
       published.set(snapshot)
@@ -191,6 +204,7 @@ export function createFrameTransaction<
   }
 
   function scheduleFlush(): void {
+    // 已有 raf 帧，
     if (scheduleQueued) return
     if (!dirty && nextPending === null) return
     scheduleQueued = true