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

package/src/rendering/render/createWebGPUSurfaceBackend.ts

@@ -0,0 +1,106 @@
+import type { CompositeOptions, SurfaceBackend, SurfaceRegion } from './SurfaceBackend'
+
+export type WebGPUSurfaceBackend = SurfaceBackend & {
+  readonly canvas: HTMLCanvasElement
+  readonly device: GPUDevice
+  readonly format: GPUTextureFormat
+  getBoundRegion(): SurfaceRegion | null
+  getCurrentTextureView(): GPUTextureView | null
+}
+
+export type WebGPUSurfaceBackendOptions = {
+  canvas: HTMLCanvasElement
+  device: GPUDevice
+  format: GPUTextureFormat
+}
+
+export function createWebGPUSurfaceBackend(
+  options: WebGPUSurfaceBackendOptions,
+): WebGPUSurfaceBackend {
+  const { canvas, device, format } = options
+  const context = canvas.getContext('webgpu')
+  if (!context) throw new Error('WebGPU canvas context unavailable')
+
+  const renderAttachmentUsage = globalThis.GPUTextureUsage?.RENDER_ATTACHMENT ?? 0x10
+  context.configure({
+    device,
+    format,
+    alphaMode: 'premultiplied',
+    usage: renderAttachmentUsage,
+  })
+
+  let disposed = false
+  let boundRegion: SurfaceRegion | null = null
+
+  return {
+    canvas,
+    device,
+    format,
+    isAvailable(): boolean {
+      return !disposed
+    },
+    resize(widthLogical: number, heightLogical: number, dpr: number): void {
+      if (disposed) return
+      const width = Math.max(1, Math.round(widthLogical * dpr))
+      const height = Math.max(1, Math.round(heightLogical * dpr))
+      if (canvas.width !== width) canvas.width = width
+      if (canvas.height !== height) canvas.height = height
+      // 可见 DOM 合成：CSS 尺寸跟逻辑 plot，buffer 跟物理像素
+      if (canvas.style) {
+        canvas.style.width = `${Math.max(0, widthLogical)}px`
+        canvas.style.height = `${Math.max(0, heightLogical)}px`
+      }
+    },
+    bindRegion(region: SurfaceRegion): boolean {
+      if (disposed || region.width <= 0 || region.height <= 0 || region.dpr <= 0) return false
+      boundRegion = { ...region }
+      return true
+    },
+    clearRegion(_region: SurfaceRegion): void {
+      if (disposed) return
+      // 空数据/清屏：提交透明 clear，避免 hybrid 可见 canvas 残留上一帧
+      try {
+        const view = context.getCurrentTexture().createView()
+        const encoder = device.createCommandEncoder()
+        const pass = encoder.beginRenderPass({
+          colorAttachments: [
+            {
+              view,
+              clearValue: { r: 0, g: 0, b: 0, a: 0 },
+              loadOp: 'clear',
+              storeOp: 'store',
+            },
+          ],
+        })
+        pass.end()
+        device.queue.submit([encoder.finish()])
+      } catch {
+        // device lost / texture unavailable：忽略，下帧 beginFrame 会重建
+      }
+    },
+    compositeTo(
+      _targetCtx: CanvasRenderingContext2D,
+      _region: SurfaceRegion,
+      _compositeOptions?: CompositeOptions,
+    ): void {
+      // M2：WebGPU 可见 canvas 直接参与 DOM 分层，禁止 GPU→2D drawImage
+    },
+    getBoundRegion(): SurfaceRegion | null {
+      return boundRegion ? { ...boundRegion } : null
+    },
+    getCurrentTextureView(): GPUTextureView | null {
+      if (disposed) return null
+      try {
+        return context.getCurrentTexture().createView()
+      } catch {
+        return null
+      }
+    },
+    dispose(): void {
+      if (disposed) return
+      disposed = true
+      boundRegion = null
+      context.unconfigure()
+    },
+  }
+}

package/src/rendering/render/frameMetrics.ts

@@ -0,0 +1,54 @@
+export type FrameMetricsSnapshot = {
+  bufferCreateCount: number
+  bufferUploadBytes: number
+  drawCallCount: number
+  queueSubmitCount: number
+  compositeCount: number
+}
+
+function empty(): FrameMetricsSnapshot {
+  return {
+    bufferCreateCount: 0,
+    bufferUploadBytes: 0,
+    drawCallCount: 0,
+    queueSubmitCount: 0,
+    compositeCount: 0,
+  }
+}
+
+let snapshot: FrameMetricsSnapshot = empty()
+
+export function resetFrameMetrics(): void {
+  snapshot = empty()
+}
+
+export function getFrameMetrics(): FrameMetricsSnapshot {
+  return { ...snapshot }
+}
+
+export function createFrameMetrics() {
+  let current = empty()
+  return {
+    beginFrame(): void {
+      current = empty()
+    },
+    recordBufferCreate(): void {
+      current.bufferCreateCount += 1
+    },
+    recordUpload(bytes: number): void {
+      current.bufferUploadBytes += bytes
+    },
+    recordDraw(): void {
+      current.drawCallCount += 1
+    },
+    recordSubmit(): void {
+      current.queueSubmitCount += 1
+    },
+    recordComposite(): void {
+      current.compositeCount += 1
+    },
+    endFrame(): void {
+      snapshot = { ...current }
+    },
+  }
+}

package/src/rendering/render/index.ts

@@ -9,6 +9,36 @@ export type { SurfaceBackend, SurfaceRegion, CompositeOptions } from './SurfaceB
 
 export { createWebGLSurfaceBackend } from './createWebGLSurfaceBackend'
 export { createWebGLRenderer } from './createWebGLRenderer'
+export { createWebGPUSurfaceBackend } from './createWebGPUSurfaceBackend'
+export { createWebGPURenderer } from './createWebGPURenderer'
+export { createCanvas2DRenderer } from './createCanvas2DRenderer'
+export { createRendererHost, createRendererHostFromRenderer } from './rendererHost'
+export {
+  createDefaultRendererHost,
+  createDefaultRendererHostSync,
+} from './createDefaultRendererHost'
+
+export type {
+  RendererBackend,
+  RendererBackendStatus,
+  RendererBackendRuntime,
+  RendererFactory,
+  RendererHostDependencies,
+  RendererHostListeners,
+  RendererHost,
+} from './rendererHost'
+
+export type {
+  WebGPUSurfaceBackend,
+  WebGPUSurfaceBackendOptions,
+} from './createWebGPUSurfaceBackend'
+export type { CreateWebGPURendererOptions } from './createWebGPURenderer'
+export {
+  createFrameMetrics,
+  getFrameMetrics,
+  resetFrameMetrics,
+} from './frameMetrics'
+export type { FrameMetricsSnapshot } from './frameMetrics'
 
 export type {
   Renderer,

package/src/rendering/render/rendererHost.ts

@@ -0,0 +1,210 @@
+import type { Renderer } from './Renderer'
+
+export type RendererBackend = 'webgpu' | 'webgl' | 'canvas'
+
+export type RendererBackendStatus = 'initializing' | 'ready' | 'switching' | 'degraded' | 'failed'
+
+export type RendererBackendRuntime = {
+  effective: RendererBackend
+  status: RendererBackendStatus
+  error: string | null
+}
+
+export type RendererFactory = () => Renderer | Promise<Renderer>
+
+export type RendererHostDependencies = {
+  createWebGPU: RendererFactory
+  createWebGL: RendererFactory
+  createCanvas: RendererFactory
+  onRuntimeChange?: (runtime: Readonly<RendererBackendRuntime>) => void
+  requestRedraw?: () => void
+}
+
+export type RendererHostListeners = Pick<
+  RendererHostDependencies,
+  'onRuntimeChange' | 'requestRedraw'
+>
+
+export interface RendererHost {
+  readonly renderer: Renderer
+  readonly runtime: Readonly<RendererBackendRuntime>
+  resize(widthLogical: number, heightLogical: number, dpr: number): void
+  switchTo(preference: RendererBackend): Promise<void>
+  handleDeviceLost(error: string): Promise<void>
+  setListeners(listeners: RendererHostListeners): void
+  dispose(): void
+}
+
+export type PreparedRenderer = {
+  renderer: Renderer
+  effective: RendererBackend
+  error: string | null
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+async function prepareRenderer(
+  preference: RendererBackend,
+  deps: RendererHostDependencies,
+): Promise<PreparedRenderer> {
+  const attempts: Array<[RendererBackend, RendererFactory]> =
+    preference === 'webgpu'
+      ? [
+          ['webgpu', deps.createWebGPU],
+          ['webgl', deps.createWebGL],
+          ['canvas', deps.createCanvas],
+        ]
+      : preference === 'webgl'
+        ? [
+            ['webgl', deps.createWebGL],
+            ['canvas', deps.createCanvas],
+          ]
+        : [['canvas', deps.createCanvas]]
+  let firstError: string | null = null
+
+  for (const [effective, factory] of attempts) {
+    try {
+      return {
+        renderer: await factory(),
+        effective,
+        error: firstError,
+      }
+    } catch (error) {
+      firstError ??= errorMessage(error)
+    }
+  }
+
+  throw new Error(firstError ?? `Unable to create ${preference} renderer`)
+}
+
+export async function createRendererHost(
+  preference: RendererBackend,
+  deps: RendererHostDependencies,
+): Promise<RendererHost> {
+  const initial = await prepareRenderer(preference, deps)
+  return createRendererHostFromRenderer(preference, initial, deps)
+}
+
+export function createRendererHostFromRenderer(
+  preference: RendererBackend,
+  initial: PreparedRenderer,
+  deps: RendererHostDependencies,
+): RendererHost {
+  let activeRenderer = initial.renderer
+  let runtime: RendererBackendRuntime = {
+    effective: initial.effective,
+    status: initial.effective === preference ? 'ready' : 'degraded',
+    error: initial.error,
+  }
+  let generation = 0
+  let disposed = false
+  let surfaceSize: { widthLogical: number; heightLogical: number; dpr: number } | null = null
+  let listeners: RendererHostListeners = {
+    onRuntimeChange: deps.onRuntimeChange,
+    requestRedraw: deps.requestRedraw,
+  }
+
+  function publish(next: RendererBackendRuntime): void {
+    runtime = next
+    listeners.onRuntimeChange?.(runtime)
+  }
+
+  const host: RendererHost = {
+    get renderer() {
+      return activeRenderer
+    },
+    get runtime() {
+      return runtime
+    },
+    resize(widthLogical, heightLogical, dpr): void {
+      if (disposed) return
+      surfaceSize = { widthLogical, heightLogical, dpr }
+      activeRenderer.surface.resize(widthLogical, heightLogical, dpr)
+    },
+    async switchTo(nextPreference): Promise<void> {
+      if (disposed) return
+      const requestGeneration = ++generation
+      publish({ ...runtime, status: 'switching', error: null })
+
+      let prepared: PreparedRenderer
+      try {
+        prepared = await prepareRenderer(nextPreference, deps)
+      } catch (error) {
+        if (disposed || requestGeneration !== generation) return
+        publish({ ...runtime, status: 'degraded', error: errorMessage(error) })
+        return
+      }
+
+      if (disposed || requestGeneration !== generation) {
+        prepared.renderer.dispose()
+        return
+      }
+
+      if (surfaceSize) {
+        prepared.renderer.surface.resize(
+          surfaceSize.widthLogical,
+          surfaceSize.heightLogical,
+          surfaceSize.dpr,
+        )
+      }
+
+      const previous = activeRenderer
+      activeRenderer = prepared.renderer
+      publish({
+        effective: prepared.effective,
+        status: prepared.effective === nextPreference ? 'ready' : 'degraded',
+        error: prepared.error,
+      })
+      listeners.requestRedraw?.()
+      if (previous !== activeRenderer) previous.dispose()
+    },
+    async handleDeviceLost(error): Promise<void> {
+      if (disposed || runtime.effective !== 'webgpu') return
+      const requestGeneration = ++generation
+      publish({ ...runtime, status: 'degraded', error })
+
+      let prepared: PreparedRenderer
+      try {
+        prepared = await prepareRenderer('webgl', deps)
+      } catch (fallbackError) {
+        if (disposed || requestGeneration !== generation) return
+        publish({ ...runtime, status: 'failed', error: errorMessage(fallbackError) })
+        return
+      }
+
+      if (disposed || requestGeneration !== generation) {
+        prepared.renderer.dispose()
+        return
+      }
+
+      if (surfaceSize) {
+        prepared.renderer.surface.resize(
+          surfaceSize.widthLogical,
+          surfaceSize.heightLogical,
+          surfaceSize.dpr,
+        )
+      }
+
+      const previous = activeRenderer
+      activeRenderer = prepared.renderer
+      publish({ effective: prepared.effective, status: 'degraded', error })
+      listeners.requestRedraw?.()
+      if (previous !== activeRenderer) previous.dispose()
+    },
+    setListeners(nextListeners): void {
+      listeners = { ...nextListeners }
+      listeners.onRuntimeChange?.(runtime)
+    },
+    dispose(): void {
+      if (disposed) return
+      disposed = true
+      generation += 1
+      activeRenderer.dispose()
+    },
+  }
+
+  listeners.onRuntimeChange?.(runtime)
+  return host
+}

package/src/rendering/render/webgpuResourceTable.ts

@@ -0,0 +1,87 @@
+import type { createFrameMetrics } from './frameMetrics'
+
+type Metrics = ReturnType<typeof createFrameMetrics>
+
+export type ResourceUsage = 'vertex' | 'instance' | 'uniform'
+
+export type EnsureUploadedParams = {
+  key: string
+  revision: number
+  data: Float32Array
+  usage: ResourceUsage
+}
+
+export type GpuResourceHandle = {
+  buffer: GPUBuffer
+  capacity: number
+  lastRevision: number
+}
+
+export type WebGPUResourceTable = {
+  ensureUploaded(params: EnsureUploadedParams): GpuResourceHandle
+  destroyKey(key: string): void
+  destroyAll(): void
+}
+
+const GPU_BUFFER_COPY_DST = globalThis.GPUBufferUsage?.COPY_DST ?? 0x0008
+const GPU_BUFFER_VERTEX = globalThis.GPUBufferUsage?.VERTEX ?? 0x0020
+const GPU_BUFFER_UNIFORM = globalThis.GPUBufferUsage?.UNIFORM ?? 0x0040
+
+function gpuUsage(usage: ResourceUsage): GPUBufferUsageFlags {
+  if (usage === 'uniform') return GPU_BUFFER_UNIFORM | GPU_BUFFER_COPY_DST
+  return GPU_BUFFER_VERTEX | GPU_BUFFER_COPY_DST
+}
+
+function growCapacity(needed: number, existing: number): number {
+  let capacity = Math.max(4, existing || 4)
+  while (capacity < needed) capacity = Math.ceil(capacity * 1.5)
+  return Math.ceil(capacity / 4) * 4
+}
+
+export function createWebGPUResourceTable(options: {
+  device: GPUDevice
+  metrics?: Metrics
+}): WebGPUResourceTable {
+  const { device, metrics } = options
+  const resources = new Map<string, GpuResourceHandle>()
+
+  return {
+    ensureUploaded({ key, revision, data, usage }): GpuResourceHandle {
+      const byteLength = data.byteLength
+      let resource = resources.get(key)
+      if (!resource || resource.capacity < byteLength) {
+        resource?.buffer.destroy()
+        const capacity = growCapacity(byteLength, resource?.capacity ?? 0)
+        const buffer = device.createBuffer({
+          size: capacity,
+          usage: gpuUsage(usage),
+        })
+        metrics?.recordBufferCreate()
+        resource = { buffer, capacity, lastRevision: -1 }
+        resources.set(key, resource)
+      }
+      if (resource.lastRevision !== revision) {
+        device.queue.writeBuffer(
+          resource.buffer,
+          0,
+          data.buffer as ArrayBuffer,
+          data.byteOffset,
+          data.byteLength,
+        )
+        metrics?.recordUpload(byteLength)
+        resource.lastRevision = revision
+      }
+      return resource
+    },
+    destroyKey(key): void {
+      const resource = resources.get(key)
+      if (!resource) return
+      resource.buffer.destroy()
+      resources.delete(key)
+    },
+    destroyAll(): void {
+      for (const resource of resources.values()) resource.buffer.destroy()
+      resources.clear()
+    },
+  }
+}

package/src/rendering/scene/__tests__/layerFromPlugin.test.ts

@@ -70,6 +70,33 @@ describe('createLayerFromPlugin', () => {
     expect(plugin.draw).toHaveBeenCalledWith(context)
   })
 
+  it('injects PaintContext.renderer as RenderContext.sceneRenderer before draw', () => {
+    const plugin = makeMockPlugin({
+      draw: vi.fn((c: RenderContext) => {
+        expect(c.sceneRenderer).toBe(stubPaintCtx.renderer)
+      }),
+    })
+    const context = makeMockContext()
+    const layer = createLayerFromPlugin(plugin, () => context, 'main')
+    layer.paint(stubPaintCtx)
+    expect(plugin.draw).toHaveBeenCalledOnce()
+  })
+
+  it('isolates plugin.draw errors so paint does not throw', () => {
+    const plugin = makeMockPlugin({
+      draw: vi.fn(() => {
+        throw new Error('draw boom')
+      }),
+    })
+    const context = makeMockContext()
+    const layer = createLayerFromPlugin(plugin, () => context, 'main')
+    const err = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+    expect(() => layer.paint(stubPaintCtx)).not.toThrow()
+    expect(plugin.draw).toHaveBeenCalledOnce()
+    err.mockRestore()
+  })
+
   it('skips plugin.draw when getContext returns null', () => {
     const plugin = makeMockPlugin()
     const getContext = vi.fn(() => null)
@@ -93,7 +120,7 @@ describe('createLayerFromPlugin', () => {
     expect(plugin.draw).not.toHaveBeenCalled()
   })
 
-  it('calls plugin.onUninstall on dispose', () => {
+  it('does not call plugin.onUninstall on dispose (owned by removeRenderer)', () => {
     const onUninstall = vi.fn()
     const plugin = makeMockPlugin({ onUninstall })
     const getContext = vi.fn(() => makeMockContext())
@@ -101,7 +128,7 @@ describe('createLayerFromPlugin', () => {
 
     layer.dispose()
 
-    expect(onUninstall).toHaveBeenCalledOnce()
+    expect(onUninstall).not.toHaveBeenCalled()
   })
 
   it('does not throw when dispose is called without onUninstall', () => {

package/src/rendering/scene/__tests__/retainedScene.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest'
+
+import { createRetainedScene } from '../retainedScene'
+
+describe('createRetainedScene', () => {
+  it('upserts by key and replaces geometry when revision changes', () => {
+    const scene = createRetainedScene()
+    scene.beginFrame(1)
+    scene.upsert({
+      kind: 'rects',
+      key: 'main/candle/upBody',
+      revision: 1,
+      instances: new Float32Array([0, 0, 1, 2]),
+      count: 1,
+      color: '#0f0',
+      scrollLeft: 0,
+      z: 10,
+      paneId: 'main',
+    })
+    scene.upsert({
+      kind: 'rects',
+      key: 'main/candle/upBody',
+      revision: 2,
+      instances: new Float32Array([1, 1, 1, 2]),
+      count: 1,
+      color: '#0f0',
+      scrollLeft: 5,
+      z: 10,
+      paneId: 'main',
+    })
+    const nodes = scene.collectVisible('main')
+    expect(nodes).toHaveLength(1)
+    expect(nodes[0]?.revision).toBe(2)
+    expect(nodes[0]?.scrollLeft).toBe(5)
+  })
+
+  it('prunes keys not touched for N frames', () => {
+    const scene = createRetainedScene({ staleFrames: 2 })
+    scene.beginFrame(1)
+    scene.upsert({
+      kind: 'rects',
+      key: 'a',
+      revision: 1,
+      instances: new Float32Array(4),
+      count: 1,
+      color: '#fff',
+      scrollLeft: 0,
+      z: 0,
+      paneId: 'main',
+    })
+    scene.endFrame()
+    scene.beginFrame(2)
+    scene.endFrame()
+    scene.beginFrame(3)
+    const removed = scene.prune()
+    expect(removed).toEqual(['a'])
+    expect(scene.collectVisible('main')).toEqual([])
+  })
+})

package/src/rendering/scene/createLayerFromPlugin.ts

@@ -29,10 +29,17 @@ export function createLayerFromPlugin(
       if (paneRole === 'sub' && ctx.paneId !== targetPaneId) return
       const context = getContext()
       if (!context) return
-      plugin.draw(context)
+      // 注入本帧 Scene Renderer，供已迁路径（candle 等）走统一画笔
+      context.sceneRenderer = ctx.renderer
+      try {
+        plugin.draw(context)
+      } catch (e) {
+        // 隔离单层异常，避免中断同 pane 后续 Layer（对齐旧 Manager.render）
+        console.error(`[RendererPlugin] ${plugin.name} draw error:`, e)
+      }
     },
     dispose() {
-      plugin.onUninstall?.()
+      // onUninstall 由 removeRenderer / Manager.unregister 单点负责，避免双调
     },
   }
 }

package/src/rendering/scene/layerRegistry.ts

@@ -15,11 +15,9 @@ import { KLineChartError } from '../../errors'
  *    avoids forcing every consumer through a single "register + auto-add"
  *    pipeline that would be hard to compose with config-driven scenes.
  *
- * This PR does NOT pre-register any factories — that's a follow-up PR
- * once the legacy WebGL renderers have adapters that satisfy the `Layer`
- * interface. This file ships the registry mechanism plus the canonical
- * `typeId` constants so the rest of the codebase can reference layer types
- * by symbol rather than magic string.
+ * Factories are registered by chart wiring / plugins; this file ships the
+ * registry mechanism plus the canonical `typeId` constants so the rest of
+ * the codebase can reference layer types by symbol rather than magic string.
  */
 
 import type { Layer, LayerRole } from './types'
@@ -98,7 +96,7 @@ export function createLayerRegistry(): LayerRegistry {
  * string literal types without an enum import — useful for config blobs.
  */
 export const BUILTIN_LAYER_TYPES = {
-  // Existing in v0 (handled by legacy renderers)
+  // Built-in chart layers
   CANDLE: 'builtin:candle',
   VOLUME: 'builtin:volume',
   INDICATOR_MA: 'builtin:indicator:ma',