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

package/src/rendering/render/Renderer.ts

@@ -1,60 +1,95 @@
 /**
- * High-level renderer interface — the drawing primitives the chart's
- * scene layers (candles, volume, indicators, drawings) call into.
+ * 渲染器接口 — Scene 各层（蜡烛、指标、drawing 等）通过它画图。
  *
- * WebGL (`createWebGLRenderer`) implements this contract today; P1 WebGPU
- * will implement the same surface. Call sites only use sceneRenderer
- * (fail-closed boolean → Canvas2D), never dual-path surfaces.
+ * WebGL 和 WebGPU 实现同一套接口。调用方只走 sceneRenderer（返回 false 时 fail-closed 降级 Canvas2D），不走双路径。
  *
- * Design notes:
- * - `drawInstances` is the workhorse: render N copies of a unit geometry
- *   parameterized by an instance buffer. K-lines, volume bars, footprint
- *   cells, heatmap tiles all reduce to instanced primitives — see
- *   `docs/ROADMAP.md` §2.3 for the K-line example.
- * - `drawLines` covers MA-style continuous polylines, drawings, axes.
- * - `dispatchCompute` exists only because WebGPU has compute shaders;
- *   the WebGL implementation throws on call so callers can feature-detect
- *   via `caps.compute`. Volume Profile binning, M4 downsampling, footprint
- *   aggregation will use it on the WebGPU path.
- * - `setUniforms` is intentionally schemaless on the interface — the
- *   uniform layout is owned by each shader/program. Callers pass a
- *   structured object that the backend translates into uniform writes.
+ * 设计说明：
+ * - drawInstances 是主力：一份 unit geometry 配 instance buffer 渲染 N 份。
+ *   蜡烛、成交量柱、footprint 格子、heatmap 磁贴都归约为 instanced 图元。
+ * - drawLines 画 MA-style 折线、drawing、坐标轴。
+ * - dispatchCompute 只有 WebGPU 有；WebGL 实现会抛异常，调用方先查 caps.compute。
+ * - uniform 布局由各 shader/pipeline 自行定义，接口不做 schema 约束。
  */
 
 import type { SurfaceBackend, SurfaceRegion } from './SurfaceBackend'
 
-/** Reported by the backend so feature-conditional code can branch. */
+/** 后端上报的能力位，调用方据此分支 */
 export type RendererCapabilities = {
-  /** WebGPU compute shaders available. WebGL backends report false. */
+  /** WebGPU compute shader 是否可用；WebGL 返回 false */
   compute: boolean
-  /** Storage buffers usable as ring buffers / scatter-add targets. */
+  /** storage buffer 是否可用 */
   storageBuffer: boolean
-  /** Maximum elements per drawInstances call (engine-imposed cap). */
+  /** 单次 drawInstances 上限（引擎强加） */
   maxInstances: number
-  /** Friendly name, e.g. "webgl2" or "webgpu". */
+  /** 名称，如 "webgl2" 或 "webgpu" */
   name: string
 }
 
-/** Vertex/instance buffer wrapper. Backends own the GPU handle. */
+/**
+ * 各后端（WebGL/WebGPU/Canvas2D）都实现的绘制接口。
+ * 后端持有 GPU 资源，调用方通过不透明 handle 操作。
+ */
+export interface Renderer {
+  /** 底层 surface，用于 region 绑定和最终合成 */
+  readonly surface: SurfaceBackend
+
+  /** 能力位标志 */
+  readonly caps: RendererCapabilities
+
+  // --- 资源生命周期 ---
+
+  createBuffer(usage: BufferUsage, sizeBytes: number): BufferHandle
+  writeBuffer(handle: BufferHandle, data: ArrayBufferView, offsetBytes?: number): void
+  destroyBuffer(handle: BufferHandle): void
+
+  /** 编译 shader pipeline。descriptor 格式后端自定，适配层通常提供工厂函数（如 createCandlePipeline） */
+  createPipeline(descriptor: unknown): PipelineHandle
+  destroyPipeline(handle: PipelineHandle): void
+
+  /** WebGPU only — WebGL 会抛异常 */
+  createComputePipeline(descriptor: unknown): ComputePipelineHandle
+  destroyComputePipeline(handle: ComputePipelineHandle): void
+
+  // --- 帧 ---
+
+  beginFrame(region: SurfaceRegion): void
+  /**
+   * 返回 true 表示本批已成功提交 GPU（或 instanceCount<=0 无需绘制）。
+   * 返回 false 表示未画上（无 surface / pipeline 不匹配 / 资源缺失）——调用方应 fail-closed 走 2D。
+   */
+  drawInstances(params: DrawInstancesParams): boolean
+  /**
+   * 返回 true 表示本批折线/填充已成功提交 GPU。
+   * 返回 false 表示未画上——调用方应 fail-closed 走 2D。
+   */
+  drawLines(params: DrawLinesParams): boolean
+  /** WebGPU only — WebGL 会抛异常，调用方先查 caps */
+  dispatchCompute(params: DispatchComputeParams): void
+  endFrame(): void
+
+  dispose(): void
+}
+
+/** 不透明 buffer handle，后端持有 GPU 资源 */
 export type BufferHandle = { readonly __brand: 'BufferHandle' }
-/** Pipeline / shader program wrapper. */
+/** 不透明 pipeline handle */
 export type PipelineHandle = { readonly __brand: 'PipelineHandle' }
-/** Compute shader handle (WebGPU only). */
+/** WebGPU compute pipeline handle */
 export type ComputePipelineHandle = { readonly __brand: 'ComputePipelineHandle' }
 
 export type BufferUsage = 'vertex' | 'instance' | 'index' | 'uniform' | 'storage'
 
 export type DrawInstancesParams = {
   pipeline: PipelineHandle
-  /** Unit-geometry buffer (e.g. a single rectangle) shared across instances. */
+  /** 所有 instance 共享的 unit geometry（如一个矩形） */
   vertices: BufferHandle
-  /** Per-instance attribute buffer (e.g. one row per K-line). */
+  /** 每个 instance 的属性 buffer（如一行 K 线数据） */
   instances: BufferHandle
-  /** Number of instances to draw. */
+  /** 绘制多少个 instance */
   instanceCount: number
-  /** Vertices per instance (e.g. 4 for a quad, 6 if using triangles). */
+  /** 每个 instance 的顶点数（quad 用 4，triangle 用 6） */
   vertexCount: number
-  /** Uniform block — opaque object the backend reads. */
+  /** uniform 块，后端自行解译 */
   uniforms?: Record<string, unknown>
 }
 
@@ -72,7 +107,7 @@ export type DrawLinesParams = {
    */
   vertices?: BufferHandle
   vertexCount?: number
-  /** Line strip vs disconnected segments. */
+  /** strip 连续折线 / list 独立线段 */
   topology?: 'strip' | 'list'
   /** 多色折线批量（推荐 MA 等多周期） */
   strips?: ReadonlyArray<DrawLineStrip>
@@ -81,60 +116,9 @@ export type DrawLinesParams = {
 
 export type DispatchComputeParams = {
   pipeline: ComputePipelineHandle
-  /** Workgroup counts per axis. */
+  /** 各轴 workgroup 数 */
   workgroups: [number, number?, number?]
-  /** Input/output buffer bindings, keyed by binding index. */
+  /** 输入/输出 buffer 绑定，key 为 binding index */
   bindings: Record<number, BufferHandle>
   uniforms?: Record<string, unknown>
 }
-
-/**
- * The drawing-primitives interface every backend implements.
- *
- * Backends own the GPU resources; callers receive opaque handles
- * (`BufferHandle`, `PipelineHandle`) and pass them back for draws.
- */
-export interface Renderer {
-  /** Underlying surface (for region binding and final composite). */
-  readonly surface: SurfaceBackend
-
-  /** Reported feature flags — caller branches on `caps.compute` etc. */
-  readonly caps: RendererCapabilities
-
-  // --- resource lifecycle ---
-
-  createBuffer(usage: BufferUsage, sizeBytes: number): BufferHandle
-  writeBuffer(handle: BufferHandle, data: ArrayBufferView, offsetBytes?: number): void
-  destroyBuffer(handle: BufferHandle): void
-
-  /**
-   * Compile a shader pipeline. The exact pipeline descriptor is backend-specific;
-   * adapters typically expose factory helpers (e.g. `createCandlePipeline`) that
-   * internally call this with the right vertex/fragment sources.
-   */
-  createPipeline(descriptor: unknown): PipelineHandle
-  destroyPipeline(handle: PipelineHandle): void
-
-  /** WebGPU only — WebGL implementations MUST throw with a clear message. */
-  createComputePipeline(descriptor: unknown): ComputePipelineHandle
-  destroyComputePipeline(handle: ComputePipelineHandle): void
-
-  // --- frame ---
-
-  beginFrame(region: SurfaceRegion): void
-  /**
-   * 返回 true 表示本批已成功提交 GPU（或 instanceCount<=0 无需绘制）。
-   * 返回 false 表示未画上（无 surface / pipeline 不匹配 / 资源缺失）——调用方应 fail-closed 走 2D。
-   */
-  drawInstances(params: DrawInstancesParams): boolean
-  /**
-   * 返回 true 表示本批折线/填充已成功提交 GPU。
-   * 返回 false 表示未画上——调用方应 fail-closed 走 2D。
-   */
-  drawLines(params: DrawLinesParams): boolean
-  /** WebGPU only — WebGL implementations MUST throw. Caller checks caps first. */
-  dispatchCompute(params: DispatchComputeParams): void
-  endFrame(): void
-
-  dispose(): void
-}

package/src/rendering/render/__tests__/physicalLine.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest'
+
+import { prepareLineStripForPhysicalPixels } from '../physicalLine'
+
+describe('prepareLineStripForPhysicalPixels', () => {
+  it('snaps a horizontal one-pixel line to the physical pixel center', () => {
+    const strip = prepareLineStripForPhysicalPixels(
+      {
+        points: [
+          { x: 0.2, y: 5.1 },
+          { x: 10.7, y: 5.1 },
+        ],
+        color: '#f00',
+        width: 1,
+      },
+      1.25,
+    )
+
+    expect(strip).toEqual({
+      points: [
+        { x: 0, y: 5.2 },
+        { x: 10.4, y: 5.2 },
+      ],
+      color: '#f00',
+      width: 0.8,
+    })
+  })
+
+  it('preserves diagonal vertices while quantizing the physical line width', () => {
+    const strip = prepareLineStripForPhysicalPixels(
+      {
+        points: [
+          { x: 0.2, y: 5.1 },
+          { x: 10.7, y: 8.4 },
+        ],
+        color: '#0f0',
+        width: 1,
+      },
+      1.25,
+    )
+
+    expect(strip).toEqual({
+      points: [
+        { x: 0.2, y: 5.1 },
+        { x: 10.7, y: 8.4 },
+      ],
+      color: '#0f0',
+      width: 0.8,
+    })
+  })
+})

package/src/rendering/render/__tests__/physicalRegion.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest'
+
+import { toPhysicalRegion } from '../physicalRegion'
+
+describe('toPhysicalRegion', () => {
+  it('keeps adjacent fractional-DPR regions contiguous', () => {
+    const upper = toPhysicalRegion({ x: 0, y: 0, width: 320, height: 101.2, dpr: 1.25 })
+    const lower = toPhysicalRegion({ x: 0, y: 101.2, width: 320, height: 98.8, dpr: 1.25 })
+
+    expect(upper).toEqual({ x: 0, y: 0, width: 400, height: 127 })
+    expect(lower).toEqual({ x: 0, y: 127, width: 400, height: 123 })
+    expect(upper.y + upper.height).toBe(lower.y)
+  })
+
+  it('clips a physical region to the backing canvas', () => {
+    expect(
+      toPhysicalRegion(
+        { x: -0.4, y: 10, width: 100.8, height: 20, dpr: 1.25 },
+        { width: 125, height: 100 },
+      ),
+    ).toEqual({ x: 0, y: 13, width: 125, height: 25 })
+  })
+})

package/src/rendering/render/__tests__/webgpuRenderer.test.ts

@@ -159,6 +159,15 @@ describe('createWebGPURenderer', () => {
     expect(fake.passes[0]?.setScissorRect).toHaveBeenCalledWith(20, 10, 160, 80)
     expect(fake.passes[0]?.draw).toHaveBeenCalledWith(6, 3)
     expect(fake.queue.submit).toHaveBeenCalledOnce()
+
+    const uniformWrite = fake.queue.writeBuffer.mock.calls.find((call) => call[4] === 32)
+    expect(uniformWrite).toBeDefined()
+    expect(
+      Array.from(new Float32Array(uniformWrite![2] as ArrayBuffer, uniformWrite![3], 8)),
+    ).toEqual([160, 80, 2, 4, 1, 0, 0, 1])
+    expect(
+      (fake.pipelineDescriptors[0]?.vertex.module as { code: string }).code,
+    ).toContain('round((rect.x - uniforms.scrollLeft) * uniforms.dpr)')
   })
 
   it('records multiple draws and submits once on endFrame', async () => {
@@ -189,6 +198,27 @@ describe('createWebGPURenderer', () => {
     expect(fake.queue.submit).toHaveBeenCalledTimes(1)
   })
 
+  it('expands a logical one-pixel line to its physical DPR width', async () => {
+    const fake = makeWebGPU()
+    const renderer = await createWebGPURenderer({
+      gpu: fake.gpu as unknown as GPU,
+      canvas: fake.canvas,
+    })
+    renderer.surface.resize(100, 100, 2)
+    renderer.beginFrame({ x: 0, y: 0, width: 100, height: 100, dpr: 2 })
+    const pipeline = renderer.createPipeline({ type: 'line' })
+
+    expect(
+      renderer.drawLines({
+        pipeline,
+        strips: [{ points: [{ x: 0, y: 10 }, { x: 100, y: 10 }], color: '#f00', width: 1 }],
+      }),
+    ).toBe(true)
+    renderer.endFrame()
+
+    expect(fake.pipelineDescriptors[0]?.primitive?.topology).toBe('triangle-list')
+  })
+
   it('preserves earlier rectangle batches within the same frame', async () => {
     const fake = makeWebGPU()
     const renderer = await createWebGPURenderer({
@@ -262,7 +292,7 @@ describe('createWebGPURenderer', () => {
     const uniformWrites = fake.queue.writeBuffer.mock.calls.filter((call) => call[4] === 32)
     expect(uniformWrites).toHaveLength(2)
     for (const call of uniformWrites) {
-      expect(new Float32Array(call[2] as ArrayBuffer)[2]).toBe(12)
+      expect(new Float32Array(call[2] as ArrayBuffer)[3]).toBe(12)
     }
     expect(fake.queue.submit).toHaveBeenCalledOnce()
   })

package/src/rendering/render/__tests__/webgpuSurfaceBackend.test.ts

@@ -51,6 +51,17 @@ describe('createWebGPUSurfaceBackend', () => {
     expect(canvas.style.height).toBe('180px')
   })
 
+  it('derives CSS size from the rounded backing buffer', () => {
+    const { canvas, surface } = makeSurface()
+
+    surface.resize(101.2, 80.4, 1.25)
+
+    expect(canvas.width).toBe(127)
+    expect(canvas.height).toBe(101)
+    expect(canvas.style.width).toBe('101.6px')
+    expect(canvas.style.height).toBe('80.8px')
+  })
+
   it('compositeTo is a no-op under hybrid DOM (M2)', () => {
     const { surface } = makeSurface()
     const target = {

package/src/rendering/render/createWebGPURenderer.ts

@@ -11,6 +11,8 @@ import type {
 } from './Renderer'
 import { createWebGPUSurfaceBackend, type WebGPUSurfaceBackend } from './createWebGPUSurfaceBackend'
 import { createFrameMetrics } from './frameMetrics'
+import { prepareLineStripForPhysicalPixels } from './physicalLine'
+import { toPhysicalRegion } from './physicalRegion'
 import { createWebGPUResourceTable } from './webgpuResourceTable'
 
 type PipelineType = 'candle' | 'line' | 'fill'
@@ -42,8 +44,8 @@ const GPU_TEXTURE_RENDER_ATTACHMENT = globalThis.GPUTextureUsage?.RENDER_ATTACHM
 const RECT_SHADER = `
 struct Uniforms {
   resolution: vec2f,
+  dpr: f32,
   scrollLeft: f32,
-  padding: f32,
   color: vec4f,
 }
 
@@ -56,7 +58,14 @@ fn vertexMain(@builtin(vertex_index) vertexIndex: u32, @location(0) rect: vec4f)
     vec2f(0.0, 1.0), vec2f(1.0, 0.0), vec2f(1.0, 1.0)
   );
   let unit = corners[vertexIndex];
-  let position = vec2f(rect.x - uniforms.scrollLeft + unit.x * rect.z, rect.y + unit.y * rect.w);
+  let left = round((rect.x - uniforms.scrollLeft) * uniforms.dpr);
+  let top = round(rect.y * uniforms.dpr);
+  let right = round((rect.x + rect.z - uniforms.scrollLeft) * uniforms.dpr);
+  let bottom = round((rect.y + rect.w) * uniforms.dpr);
+  let position = vec2f(
+    left + unit.x * max(1.0, right - left),
+    top + unit.y * max(1.0, bottom - top),
+  );
   let clip = vec2f(position.x / uniforms.resolution.x * 2.0 - 1.0, 1.0 - position.y / uniforms.resolution.y * 2.0);
   return vec4f(clip, 0.0, 1.0);
 }
@@ -70,8 +79,8 @@ fn fragmentMain() -> @location(0) vec4f {
 const LINE_SHADER = `
 struct Uniforms {
   resolution: vec2f,
+  dpr: f32,
   scrollLeft: f32,
-  padding: f32,
   color: vec4f,
 }
 
@@ -79,7 +88,10 @@ struct Uniforms {
 
 @vertex
 fn vertexMain(@location(0) point: vec2f) -> @builtin(position) vec4f {
-  let position = vec2f(point.x - uniforms.scrollLeft, point.y);
+  let position = vec2f(
+    (point.x - uniforms.scrollLeft) * uniforms.dpr,
+    point.y * uniforms.dpr,
+  );
   let clip = vec2f(position.x / uniforms.resolution.x * 2.0 - 1.0, 1.0 - position.y / uniforms.resolution.y * 2.0);
   return vec4f(clip, 0.0, 1.0);
 }
@@ -368,10 +380,10 @@ export async function createWebGPURenderer(
     const color = parseColor(colorValue ?? '#000000')
     if (!color) return null
     const values = new Float32Array([
-      region.width,
-      region.height,
+      Math.round(region.width * region.dpr),
+      Math.round(region.height * region.dpr),
+      region.dpr,
       scrollLeft,
-      0,
       color[0],
       color[1],
       color[2],
@@ -406,10 +418,10 @@ export async function createWebGPURenderer(
         },
       ],
     })
-    const x = Math.max(0, Math.round(region.x * region.dpr))
-    const y = Math.max(0, Math.round(region.y * region.dpr))
-    const width = Math.min(canvas.width - x, Math.round(region.width * region.dpr))
-    const height = Math.min(canvas.height - y, Math.round(region.height * region.dpr))
+    const { x, y, width, height } = toPhysicalRegion(region, {
+      width: canvas.width,
+      height: canvas.height,
+    })
     if (width <= 0 || height <= 0) {
       pass.end()
       return null
@@ -456,10 +468,10 @@ export async function createWebGPURenderer(
           const region = draws[0]!.region
           rawSurface.bindRegion(region)
 
-          const x = Math.max(0, Math.round(region.x * region.dpr))
-          const y = Math.max(0, Math.round(region.y * region.dpr))
-          const width = Math.min(canvas.width - x, Math.round(region.width * region.dpr))
-          const height = Math.min(canvas.height - y, Math.round(region.height * region.dpr))
+          const { x, y, width, height } = toPhysicalRegion(region, {
+            width: canvas.width,
+            height: canvas.height,
+          })
           if (width > 0 && height > 0) {
             pass.setViewport(x, y, width, height, 0, 1)
             pass.setScissorRect(x, y, width, height)
@@ -608,8 +620,9 @@ export async function createWebGPURenderer(
           const scrollLeft = (params.uniforms?.scrollLeft as number) ?? 0
           for (const strip of params.strips) {
             if (strip.points.length < 2) return false
-            const wide = (strip.width ?? 1) > 1
-            const values = wide ? buildWideLine(strip) : linePoints(strip)
+            const physicalStrip = prepareLineStripForPhysicalPixels(strip, currentRegion.dpr)
+            const wide = Math.round((physicalStrip.width ?? 1) * currentRegion.dpr) > 1
+            const values = wide ? buildWideLine(physicalStrip) : linePoints(physicalStrip)
             if (!values) return false
             // 帧内序号作 key：同顺序跨帧复用；revision 未变则不 upload
             const key = `strip/${stripSeq++}`

package/src/rendering/render/createWebGPUSurfaceBackend.ts

@@ -45,10 +45,10 @@ export function createWebGPUSurfaceBackend(
       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 跟物理像素
+      // CSS 尺寸由物理 buffer 反算，避免浏览器二次缩放。
       if (canvas.style) {
-        canvas.style.width = `${Math.max(0, widthLogical)}px`
-        canvas.style.height = `${Math.max(0, heightLogical)}px`
+        canvas.style.width = `${width / dpr}px`
+        canvas.style.height = `${height / dpr}px`
       }
     },
     bindRegion(region: SurfaceRegion): boolean {

package/src/rendering/render/physicalLine.ts

@@ -0,0 +1,45 @@
+import type { DrawLineStrip } from './Renderer'
+
+function physicalLineWidth(width: number, dpr: number): number {
+  return Math.max(1, Math.round(width * dpr))
+}
+
+function alignedCenter(value: number, widthPx: number, dpr: number): number {
+  const base = Math.floor(value * dpr)
+  return (base + (widthPx % 2 === 0 ? 0 : 0.5)) / dpr
+}
+
+function alignedEdge(value: number, dpr: number): number {
+  return Math.round(value * dpr) / dpr
+}
+
+/** 仅对轴向线吸附物理像素；斜线保持原始顶点供 MSAA 平滑。 */
+export function prepareLineStripForPhysicalPixels(
+  strip: DrawLineStrip,
+  dpr: number,
+): DrawLineStrip {
+  const widthPx = physicalLineWidth(strip.width ?? 1, dpr)
+  const width = widthPx / dpr
+  const first = strip.points[0]
+  if (!first) return { ...strip, width }
+
+  const horizontal = strip.points.every((point) => point.y === first.y)
+  const vertical = strip.points.every((point) => point.x === first.x)
+  if (!horizontal && !vertical) return { ...strip, width }
+
+  if (horizontal) {
+    const y = alignedCenter(first.y, widthPx, dpr)
+    return {
+      ...strip,
+      width,
+      points: strip.points.map((point) => ({ x: alignedEdge(point.x, dpr), y })),
+    }
+  }
+
+  const x = alignedCenter(first.x, widthPx, dpr)
+  return {
+    ...strip,
+    width,
+    points: strip.points.map((point) => ({ x, y: alignedEdge(point.y, dpr) })),
+  }
+}

package/src/rendering/render/physicalRegion.ts

@@ -0,0 +1,32 @@
+import type { SurfaceRegion } from './SurfaceBackend'
+
+export type PhysicalRegion = {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+export type PhysicalBounds = {
+  width: number
+  height: number
+}
+
+/** 将逻辑 region 的两端分别对齐到物理像素，避免相邻 pane 出现缝隙。 */
+export function toPhysicalRegion(
+  region: SurfaceRegion,
+  bounds?: PhysicalBounds,
+): PhysicalRegion {
+  const left = Math.round(region.x * region.dpr)
+  const top = Math.round(region.y * region.dpr)
+  const right = Math.round((region.x + region.width) * region.dpr)
+  const bottom = Math.round((region.y + region.height) * region.dpr)
+  const maxWidth = bounds ? Math.max(0, bounds.width) : Infinity
+  const maxHeight = bounds ? Math.max(0, bounds.height) : Infinity
+  const x = Math.max(0, Math.min(left, maxWidth))
+  const y = Math.max(0, Math.min(top, maxHeight))
+  const clippedRight = Math.max(x, Math.min(right, maxWidth))
+  const clippedBottom = Math.max(y, Math.min(bottom, maxHeight))
+
+  return { x, y, width: clippedRight - x, height: clippedBottom - y }
+}

package/src/rendering/scene/createLayerFromPlugin.ts

@@ -23,18 +23,23 @@ export function createLayerFromPlugin(
     set visible(v: boolean) {
       visible = v
     },
+    /**
+     * @Todo 兼容层：把旧 RendererPlugin.draw 包装成 Layer.paint。
+     */
     paint(ctx: PaintContext) {
       if (!visible) return
-      // For sub-pane layers, skip if we're painting a different sub-pane
+      // 子图 layer 只画自己的 pane
       if (paneRole === 'sub' && ctx.paneId !== targetPaneId) return
+      // 获取业务层 RenderContext（含数据、几何、2D ctx）
       const context = getContext()
       if (!context) return
-      // 注入本帧 Scene Renderer，供已迁路径（candle 等）走统一画笔
+      // 注入本帧 sceneRenderer，已迁路径走统一 GPU 画笔，未迁路径仍用 context.ctx
       context.sceneRenderer = ctx.renderer
       try {
+        // 调用各个渲染器的绘制能力
         plugin.draw(context)
       } catch (e) {
-        // 隔离单层异常，避免中断同 pane 后续 Layer（对齐旧 Manager.render）
+        // 异常隔离，不中断同 pane 后续 layer
         console.error(`[RendererPlugin] ${plugin.name} draw error:`, e)
       }
     },

package/src/rendering/scene/createScene.ts

@@ -73,17 +73,18 @@ export function createScene(): Scene {
     return true
   }
 
+  /** 按 role 和可见性过滤 layer，z 排序后逐层 paint */
   const paintPane = (ctx: PaintContext, roles?: ReadonlyArray<LayerRole>): void => {
     if (disposed) return
+    // 选出属于当前 pane 或全局、且可见的 layer
     let candidates = layerList.filter(
       (layer) => (layer.paneRole === ctx.paneRole || layer.paneRole === 'global') && layer.visible,
     )
+    // 若传了 roles 参数，进一步按角色过滤（如只画 overlay）
     if (roles) {
       candidates = candidates.filter((layer) => roles.includes(layer.role))
     }
-    // Stable-sort by z. Native Array.prototype.sort is required
-    // by ECMAScript 2019+ to be stable, so equal z values preserve the
-    // surviving registration order from the filter pass.
+    // 按 z 升序稳定排序，相同时保留注册顺序（ECMAScript 2019+ 保证 sort 稳定）
     candidates.sort((a, b) => a.z - b.z)
     for (const layer of candidates) {
       layer.paint(ctx)

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.9.0-alpha.2'
+export const VERSION = '0.9.0-alpha.3'