@363045841yyt/klinechart-core 0.8.14 → 0.9.0-alpha.0

package/src/engine/layout/chartPaneLayout.ts

@@ -1,9 +1,11 @@
-import type { PaneRole } from '../../plugin'
+import type { PaneRole } from '../../foundation/plugin/index'
 import type { ChartDom, PaneSpec, Viewport } from '../chartTypes'
 import { PaneRenderer } from '../paneRenderer'
 import type { SharedWebGLSurface } from '../renderers/webgl/sharedWebGLSurface'
+import type { ScaleType } from '../utils/tickPosition'
 
 import { Pane, UpdateLevel } from './pane'
+import { normalizeVisiblePaneRatios as pureNormalizeVisiblePaneRatios } from './paneRatioMath'
 
 export interface PaneLayoutDependencies {
   getDom: () => ChartDom
@@ -20,9 +22,22 @@ export interface PaneLayoutDependencies {
   setKnownPaneIds: (ids: string[]) => void
   notifyPaneResize: (paneId: string, pane: Pane) => void
   scheduleDraw: (level?: UpdateLevel) => void
-  onLayoutChange: (ratios: Record<string, number>, specs: PaneSpec[]) => void
+  getPaneRatios: () => Record<string, number>
+  /** kernel.paneScaleTypes 投影源；initPanes 优先于此 */
+  getPaneScaleTypes: () => ReadonlyMap<string, ScaleType>
+  commitLayout: (ratios: Record<string, number>, specs: PaneSpec[]) => void
 }
 
+/**
+ * Pane DOM / PaneRenderer 投影器 + 布局算法。
+ *
+ * SSOT: kernel.pane（paneRatios / paneSpecs）。
+ * 本地 _internalPaneRatios / _paneSpecs 仅是算法工作副本：
+ * - 入站: projectState(kernel snapshot) 或 applyPaneLayoutSpecs
+ * - 出站: 每次突变结束必须 commitLayout() → kernel
+ * projectState 必须 layoutPanes({ commit: false })，禁止回写抖动。
+ * 禁止在未 commit 的中间态对外暴露为业务真相。
+ */
 export class ChartPaneLayout {
   private deps: PaneLayoutDependencies
   private paneRenderers: PaneRenderer[] = []
@@ -32,7 +47,13 @@ export class ChartPaneLayout {
   constructor(initialPaneSpecs: PaneSpec[], deps: PaneLayoutDependencies) {
     this.deps = deps
     this._paneSpecs = initialPaneSpecs.map((s) => ({ ...s }))
-    this.syncPaneRatiosFromSpecs(this._paneSpecs)
+    this.syncRatiosFromKernel()
+    for (const spec of this._paneSpecs) {
+      if (!this._internalPaneRatios.has(spec.id)) {
+        this._internalPaneRatios.set(spec.id, spec.ratio ?? 1)
+      }
+    }
+    this.normalizeVisiblePaneRatios(this._paneSpecs)
     this.initPanes()
   }
 
@@ -40,20 +61,40 @@ export class ChartPaneLayout {
     return this.paneRenderers
   }
 
+  /**
+   * 公共读：specs 结构来自工作副本定义，ratio 字段取自 kernel（不写工作副本）。
+   */
   getPaneSpecs(): PaneSpec[] {
-    return this._paneSpecs
+    const kernelRatios = this.deps.getPaneRatios()
+    return this._paneSpecs.map((spec) => ({
+      ...spec,
+      ratio: kernelRatios[spec.id] ?? spec.ratio,
+      ...(spec.capabilities ? { capabilities: { ...spec.capabilities } } : {}),
+    }))
   }
 
+  /**
+   * 公共读：直接返回 kernel paneRatios 副本，不触碰算法工作副本。
+   */
   getInternalPaneRatios(): Map<string, number> {
-    return this._internalPaneRatios
+    return new Map(Object.entries(this.deps.getPaneRatios()))
+  }
+
+  private syncRatiosFromKernel(): void {
+    const kernelRatios = this.deps.getPaneRatios()
+    this._internalPaneRatios = new Map(Object.entries(kernelRatios))
   }
 
   setInternalPaneRatio(paneId: string, ratio: number): void {
+    this.syncRatiosFromKernel()
     this._internalPaneRatios.set(paneId, ratio)
+    this.commitLayout()
   }
 
   deleteInternalPaneRatio(paneId: string): void {
+    this.syncRatiosFromKernel()
     this._internalPaneRatios.delete(paneId)
+    this.commitLayout()
   }
 
   private resolvePaneRole(spec: PaneSpec, index: number): PaneRole {
@@ -71,7 +112,8 @@ export class ChartPaneLayout {
   }
 
   private initPanes() {
-    const prevScaleTypes = new Map<string, 'linear' | 'log' | 'percent'>()
+    const kernelScaleTypes = this.deps.getPaneScaleTypes()
+    const prevScaleTypes = new Map<string, ScaleType>()
     for (const r of this.paneRenderers) {
       prevScaleTypes.set(r.getPane().id, r.getPane().yAxis.getScaleType())
     }
@@ -82,8 +124,10 @@ export class ChartPaneLayout {
         capabilities: spec.capabilities,
       })
 
-      const prev = prevScaleTypes.get(spec.id)
-      if (prev) pane.yAxis.setScaleType(prev)
+      // 优先 kernel SSOT，其次重建前 runtime，最后 linear
+      const scaleType =
+        kernelScaleTypes.get(spec.id) ?? prevScaleTypes.get(spec.id) ?? 'linear'
+      pane.yAxis.setScaleType(scaleType)
 
       const mainCanvas = document.createElement('canvas')
       const overlayCanvas = document.createElement('canvas')
@@ -188,29 +232,12 @@ export class ChartPaneLayout {
   }
 
   private normalizeVisiblePaneRatios(specs: PaneSpec[]): void {
-    const visible = specs.filter((p) => p.visible !== false)
-    if (visible.length === 0) return
-
-    let sum = 0
-    for (const spec of visible) {
-      const raw = this._internalPaneRatios.get(spec.id) ?? spec.ratio ?? 0
-      const safe = Number.isFinite(raw) && raw > 0 ? raw : 0
-      this._internalPaneRatios.set(spec.id, safe)
-      sum += safe
-    }
-
-    if (sum <= 0) {
-      const equal = 1 / visible.length
-      for (const spec of visible) {
-        this._internalPaneRatios.set(spec.id, equal)
-      }
-      return
-    }
-
-    for (const spec of visible) {
-      const v = this._internalPaneRatios.get(spec.id) ?? 0
-      this._internalPaneRatios.set(spec.id, v / sum)
-    }
+    const asRecord: Record<string, number> = {}
+    this._internalPaneRatios.forEach((ratio, id) => {
+      asRecord[id] = ratio
+    })
+    const normalized = pureNormalizeVisiblePaneRatios(specs, asRecord)
+    this._internalPaneRatios = new Map(Object.entries(normalized))
   }
 
   private getPaneMinHeight(spec: PaneSpec, plotHeight: number): number {
@@ -270,7 +297,9 @@ export class ChartPaneLayout {
     return heights
   }
 
-  layoutPanes() {
+  layoutPanes(options?: { commit?: boolean }) {
+    this.syncRatiosFromKernel()
+
     const vp = this.deps.getViewport()
     if (!vp) return
 
@@ -331,18 +360,57 @@ export class ChartPaneLayout {
     }
     this.normalizeVisiblePaneRatios(visibleSpecs)
     this.syncPaneRatiosToSpecs()
-    this.emitLayoutChange()
+    if (options?.commit !== false) this.commitLayout()
+  }
+
+  /** 将 kernel pane snapshot 单向投影到 DOM/renderer，不反向写 state。 */
+  projectState(panes: ReadonlyArray<PaneSpec>, ratios: Readonly<Record<string, number>>): void {
+    const definitionsChanged =
+      panes.length !== this._paneSpecs.length ||
+      panes.some((pane, index) => {
+        const current = this._paneSpecs[index]
+        return (
+          !current ||
+          pane.id !== current.id ||
+          pane.visible !== current.visible ||
+          pane.role !== current.role ||
+          pane.minHeightPx !== current.minHeightPx ||
+          JSON.stringify(pane.capabilities ?? null) !== JSON.stringify(current.capabilities ?? null)
+        )
+      })
+
+    this._paneSpecs = panes.map((pane) => ({
+      ...pane,
+      ...(pane.capabilities ? { capabilities: { ...pane.capabilities } } : {}),
+    }))
+    this._internalPaneRatios = new Map(Object.entries(ratios))
+    if (definitionsChanged) this.initPanes()
+    this.layoutPanes({ commit: false })
   }
 
+  /**
+   * 公共读：用 kernel ratios + 本地 specs 定义组装快照，不写工作副本。
+   * commitLayout 走 buildLayoutSpecsFromWorkingCopy，避免公共读污染算法中间态。
+   */
   getPaneLayoutSpecs(): PaneSpec[] {
+    return this.buildLayoutSpecs(this.deps.getPaneRatios())
+  }
+
+  /** 仅算法/commit 使用：读当前工作副本 ratios，不读 kernel */
+  private buildLayoutSpecsFromWorkingCopy(): PaneSpec[] {
+    const ratios: Record<string, number> = {}
+    this._internalPaneRatios.forEach((ratio, id) => {
+      ratios[id] = ratio
+    })
+    return this.buildLayoutSpecs(ratios)
+  }
+
+  private buildLayoutSpecs(ratios: Readonly<Record<string, number>>): PaneSpec[] {
     const visible = this._paneSpecs.filter((p) => p.visible !== false)
-    const sum = visible.reduce(
-      (s, p) => s + (this._internalPaneRatios.get(p.id) ?? p.ratio ?? 0),
-      0,
-    )
+    const sum = visible.reduce((s, p) => s + (ratios[p.id] ?? p.ratio ?? 0), 0)
     const safeSum = sum > 0 ? sum : 1
     return this._paneSpecs.map((spec) => {
-      const base = this._internalPaneRatios.get(spec.id) ?? spec.ratio ?? 0
+      const base = ratios[spec.id] ?? spec.ratio ?? 0
       const ratio = spec.visible === false ? base : base / safeSum
       const pane = this.paneRenderers.find((r) => r.getPane().id === spec.id)?.getPane()
       return {
@@ -354,32 +422,41 @@ export class ChartPaneLayout {
     })
   }
 
-  private emitLayoutChange(): void {
+  private commitLayout(): void {
     const ratios: Record<string, number> = {}
     this._internalPaneRatios.forEach((ratio, id) => {
       ratios[id] = ratio
     })
-    this.deps.onLayoutChange(ratios, this.getPaneLayoutSpecs())
+    this.deps.commitLayout(ratios, this.buildLayoutSpecsFromWorkingCopy())
   }
 
-  applyPaneLayoutSpecs(panes: PaneSpec[]): void {
+  applyPaneLayoutSpecs(panes: PaneSpec[], options?: { preferIncomingRatios?: boolean }): void {
+    if (options?.preferIncomingRatios) {
+      // 显式替换布局：忽略 kernel 中旧 ratio，完全采用入参
+      this._internalPaneRatios = new Map()
+    } else {
+      this.syncRatiosFromKernel()
+    }
     this._paneSpecs = panes.map((spec) => ({ ...spec }))
     this.syncPaneRatiosFromSpecs(this._paneSpecs)
+    // 先提交到 kernel，避免 layoutPanes 开头 sync 读到旧 ratio
+    this.commitLayout()
     this.initPanes()
     this.layoutPanes()
     this.deps.scheduleDraw()
   }
 
   updatePaneLayout(panes: PaneSpec[]): void {
-    this._internalPaneRatios.clear()
-    this.applyPaneLayoutSpecs(panes)
+    this.applyPaneLayoutSpecs(panes, { preferIncomingRatios: true })
   }
 
   setPaneDefinitions(defs: PaneSpec[]): void {
+    this.syncRatiosFromKernel()
     this.applyPaneLayoutSpecs(defs)
   }
 
   upsertPane(def: PaneSpec): void {
+    this.syncRatiosFromKernel()
     const idx = this._paneSpecs.findIndex((pane) => pane.id === def.id)
     if (idx === -1) {
       this.applyPaneLayoutSpecs([...this._paneSpecs, { ...def }])
@@ -393,11 +470,13 @@ export class ChartPaneLayout {
 
   removePaneDefinition(paneId: string): void {
     if (!this._paneSpecs.some((pane) => pane.id === paneId)) return
+    this.syncRatiosFromKernel()
     this._internalPaneRatios.delete(paneId)
     this.applyPaneLayoutSpecs(this._paneSpecs.filter((pane) => pane.id !== paneId))
   }
 
   addPane(paneId: string): void {
+    this.syncRatiosFromKernel()
     if (this._paneSpecs.some((spec) => spec.id === paneId)) {
       console.warn(`Pane "${paneId}" already exists`)
       return
@@ -412,6 +491,7 @@ export class ChartPaneLayout {
 
   removePane(paneId: string): void {
     if (!this._paneSpecs.some((spec) => spec.id === paneId)) return
+    this.syncRatiosFromKernel()
 
     const next = this._paneSpecs.filter((spec) => spec.id !== paneId)
     this._internalPaneRatios.delete(paneId)
@@ -427,6 +507,8 @@ export class ChartPaneLayout {
     const vp = this.deps.getViewport()
     if (!vp) return false
 
+    this.syncRatiosFromKernel()
+
     const visibleSpecs = this._paneSpecs.filter((p) => p.visible !== false)
     const boundaryIndex = visibleSpecs.findIndex((p) => p.id === upperPaneId)
     if (boundaryIndex < 0 || boundaryIndex >= visibleSpecs.length - 1) return false
@@ -487,8 +569,7 @@ export class ChartPaneLayout {
       this._internalPaneRatios.set(spec.id, h / availableH)
     }
 
-    this.normalizeVisiblePaneRatios(visibleSpecs)
-    this.syncPaneRatiosToSpecs()
+    this.commitLayout()
 
     this.layoutPanes()
     this.deps.scheduleDraw()

package/src/engine/layout/pane.ts

@@ -1,5 +1,5 @@
-import type { PaneCapabilities, PaneRole } from '../../plugin'
-import type { KLineData } from '../../types/price'
+import type { PaneCapabilities, PaneRole } from '../../foundation/plugin/index'
+import type { KLineData } from '../../foundation/types/price'
 import type { MarkerManager } from '../marker/registry'
 import type { PriceRange } from '../scale/price'
 import { PriceScale } from '../scale/priceScale'

package/src/engine/layout/paneRatioMath.ts

@@ -0,0 +1,39 @@
+export type PaneRatioSpec = {
+  id: string
+  visible?: boolean
+  ratio?: number
+}
+
+/**
+ * 将可见 pane 的 ratio 归一化为和为 1；隐藏 pane 保留原始 ratio 不参与归一化。
+ */
+export function normalizeVisiblePaneRatios(
+  specs: ReadonlyArray<PaneRatioSpec>,
+  ratios: Readonly<Record<string, number>>,
+): Record<string, number> {
+  const next: Record<string, number> = { ...ratios }
+  const visible = specs.filter((p) => p.visible !== false)
+  if (visible.length === 0) return next
+
+  let sum = 0
+  for (const spec of visible) {
+    const raw = next[spec.id] ?? spec.ratio ?? 0
+    const safe = Number.isFinite(raw) && raw > 0 ? raw : 0
+    next[spec.id] = safe
+    sum += safe
+  }
+
+  if (sum <= 0) {
+    const equal = 1 / visible.length
+    for (const spec of visible) {
+      next[spec.id] = equal
+    }
+    return next
+  }
+
+  for (const spec of visible) {
+    const v = next[spec.id] ?? 0
+    next[spec.id] = v / sum
+  }
+  return next
+}

package/src/engine/marker/__tests__/markerManager.customMarkers.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest'
+
+import type { CustomMarkerEntity } from '../registry'
+import { MarkerManager } from '../registry'
+import { createMarkerState } from '../../state/markerState'
+
+function mk(id: string): CustomMarkerEntity {
+  return {
+    id,
+    date: '2025-01-15',
+    timestamp: 1,
+    shape: 'circle',
+  }
+}
+
+describe('MarkerManager customMarkers projection', () => {
+  it('reads custom markers from injected signal, not local map', () => {
+    const state = createMarkerState()
+    state.actions.setCustomMarkers([mk('a')])
+    const manager = new MarkerManager({ customMarkers$: state.readonly.customMarkers })
+
+    expect(manager.getCustomMarkers().map((m) => m.id)).toEqual(['a'])
+
+    state.actions.setCustomMarkers([mk('b')])
+    expect(manager.getCustomMarkers().map((m) => m.id)).toEqual(['b'])
+  })
+
+  it('still caches positions for hitTest independently of business state', () => {
+    const state = createMarkerState()
+    state.actions.setCustomMarkers([mk('a')])
+    const manager = new MarkerManager({ customMarkers$: state.readonly.customMarkers })
+    manager.setCustomMarkerPosition('a', 10, 20, 12, 'circle')
+    expect(manager.hitTestCustomMarker(10, 20)?.id).toBe('a')
+  })
+
+  it('clearPositionCache drops hit targets after business markers change', () => {
+    const state = createMarkerState()
+    state.actions.setCustomMarkers([mk('a')])
+    const manager = new MarkerManager({ customMarkers$: state.readonly.customMarkers })
+    manager.setCustomMarkerPosition('a', 10, 20, 12, 'circle')
+    expect(manager.hitTestCustomMarker(10, 20)?.id).toBe('a')
+
+    state.actions.clearCustomMarkers()
+    // 业务态已空，但未清 position 时 hitTest 仍可能因循环无数据而不命中；
+    // 清缓存后必须保证无残留 position。
+    manager.clearPositionCache()
+    expect(manager.hitTestCustomMarker(10, 20)).toBeNull()
+
+    state.actions.setCustomMarkers([mk('a')])
+    // 未重新 set position 时不可命中
+    expect(manager.hitTestCustomMarker(10, 20)).toBeNull()
+  })
+
+  it('stale positions without clear would still require business id match', () => {
+    const state = createMarkerState()
+    state.actions.setCustomMarkers([mk('a')])
+    const manager = new MarkerManager({ customMarkers$: state.readonly.customMarkers })
+    manager.setCustomMarkerPosition('a', 10, 20, 12, 'circle')
+
+    state.actions.setCustomMarkers([mk('b')])
+    // id a 的 position 残留，但业务列表已是 b → 不可命中 a
+    expect(manager.hitTestCustomMarker(10, 20)).toBeNull()
+  })
+})

package/src/engine/marker/registry.ts

@@ -1,4 +1,5 @@
-import { hitTestShape } from '../../semantic/drawShape'
+import type { ReadonlySignal } from '../../foundation/reactivity/signal'
+import { hitTestShape } from '../../features/semantic/drawShape'
 
 /**
  * 标记类型
@@ -100,10 +101,16 @@ export interface CustomMarkerEntity {
   metadata?: Record<string, unknown>
 }
 
+export interface MarkerManagerDeps {
+  customMarkers$: ReadonlySignal<ReadonlyMap<string, CustomMarkerEntity>>
+}
+
 /**
  * 标记 Manager
+ * 自定义标记业务态由 kernel markerState 持有；此类只投影读取 + 帧级 runtime。
  */
 export class MarkerManager {
+  private readonly deps: MarkerManagerDeps
   /** 当前帧可见的标记集合（key: marker.id） */
   private markers: Map<string, MarkerEntity> = new Map()
   /** 当前 hover 的标记 ID（跨帧持久） */
@@ -111,15 +118,16 @@ export class MarkerManager {
   /** 上一帧 hover 的标记 ID（用于触发 enter/leave 事件） */
   private lastHoveredId: string | null = null
 
-  // ============ 自定义标记状态管理 ============
-  /** 自定义标记集合 */
-  private customMarkers: Map<string, CustomMarkerEntity> = new Map()
   /** 自定义标记位置缓存（用于 hitTest） */
   private customMarkerPositions: Map<
     string,
     { x: number; y: number; size: number; shape: CustomMarkerShape }
   > = new Map()
 
+  constructor(deps: MarkerManagerDeps) {
+    this.deps = deps
+  }
+
   /**
    * 清空标记集合
    * 注意：不清除 hoveredMarkerId，保持 hover 状态跨帧持久
@@ -216,38 +224,20 @@ export class MarkerManager {
     return [...this.markers.values()]
   }
 
-  // ============ 自定义标记管理方法 ============
-
-  /**
-   * 注册自定义标记
-   */
-  registerCustomMarker(marker: CustomMarkerEntity): void {
-    this.customMarkers.set(marker.id, marker)
-  }
-
-  /**
-   * 批量设置自定义标记
-   */
-  setCustomMarkers(markers: CustomMarkerEntity[]): void {
-    this.clearCustomMarkers()
-    for (const marker of markers) {
-      this.customMarkers.set(marker.id, marker)
-    }
-  }
+  // ============ 自定义标记投影（业务态在 kernel） ============
 
   /**
-   * 清空自定义标记（含位置缓存）
+   * 清空自定义标记位置缓存（业务态清除后调用）
    */
-  clearCustomMarkers(): void {
-    this.customMarkers.clear()
+  clearPositionCache(): void {
     this.customMarkerPositions.clear()
   }
 
   /**
-   * 获取所有自定义标记
+   * 获取所有自定义标记（读 kernel signal）
    */
   getCustomMarkers(): CustomMarkerEntity[] {
-    return [...this.customMarkers.values()]
+    return [...this.deps.customMarkers$.peek().values()]
   }
 
   /**
@@ -270,7 +260,7 @@ export class MarkerManager {
    * @returns 命中的自定义标记，未命中返回 null
    */
   hitTestCustomMarker(x: number, y: number): CustomMarkerEntity | null {
-    for (const marker of this.customMarkers.values()) {
+    for (const marker of this.deps.customMarkers$.peek().values()) {
       const pos = this.customMarkerPositions.get(marker.id)
       if (pos) {
         // 使用实际渲染的大小进行命中测试

package/src/engine/modes/timeShareMode.ts

@@ -53,7 +53,7 @@ export class TimeShareMode implements ChartModeHandler {
     const baseline = tsData[0]?.price ?? 0
     if (baseline === 0) return
 
-    pane.yAxis.setScaleType('percent')
+    // scaleType 由 kernel.paneScaleTypes 投影（进入 timeshare 时写 percent）；此处只设会话 basePrice
     pane.yAxis.setBasePrice(baseline)
 
     let maxAbsPct = 0