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

package/src/rendering/renderer-tier/selectBackend.ts

@@ -0,0 +1,193 @@
+/**
+ * Renderer backend selector — bridges the tier-detection layer
+ * ({@link detectRendererTier}) to the actual backend factory the
+ * `Renderer` interface will instantiate.
+ *
+ * Why this exists separately from {@link detectRendererTier}:
+ *
+ *   - Detection answers "what's *possible*?".
+ *   - Selection answers "what's *registered* and matches what's possible?".
+ *
+ * In practice the answers diverge. A consumer can:
+ *
+ *   (a) Choose to omit a backend they don't want to ship (e.g. drop the
+ *       WebGPU backend to save bundle size; the selector then falls
+ *       through to WebGL2 even when the host supports WebGPU).
+ *   (b) Override a backend for a specific tier (e.g. inject a Canvas2D
+ *       backend stub during tests, so the chart still renders headless).
+ *
+ * Both shapes need a *structural* fallback chain, not just "give me the
+ * factory for the detected tier". This module formalises that chain so
+ * the wiring is consistent across React, Vue, Angular, and any future
+ * adapter.
+ *
+ * Pure data: no DOM, no async, no side effects. The returned factory is
+ * just the function the caller registered.
+ */
+
+import { KLineChartError } from '../../errors'
+
+import { detectRendererTier, isTierAtLeast } from './detectRendererTier'
+import {
+  RENDERER_TIER_RANK,
+  type DetectRendererTierOptions,
+  type RendererTier,
+  type RendererTierResult,
+} from './types'
+
+// ---------------------------------------------------------------------------
+// Public shape
+// ---------------------------------------------------------------------------
+
+/**
+ * Opaque factory shape. We don't constrain the Renderer construction here —
+ * the consumer's backend implementation knows its own signature. The
+ * selector is purely about *which* factory to hand back.
+ */
+export type BackendFactory<T = unknown> = () => T
+
+/**
+ * Map of tier → registered factory. Tiers that are absent or `null` are
+ * treated as "not registered" and skipped during selection.
+ *
+ * `'none'` is intentionally absent from the type. A `'none'` tier is the
+ * absence of any rendering capability; there is nothing to register.
+ */
+export type BackendRegistry<T = unknown> = Partial<
+  Record<Exclude<RendererTier, 'none'>, BackendFactory<T> | null>
+>
+
+/**
+ * Selection result. `tier` is the effective tier the chosen factory
+ * targets — which is at most the detected tier. `fallbackChain`
+ * enumerates the tiers the selector traversed (high → low). When no
+ * backend is registered for any tier ≤ the detected tier, returns
+ * `tier: 'none'` and `factory: null`.
+ */
+export interface BackendSelection<T = unknown> {
+  readonly tier: RendererTier
+  readonly factory: BackendFactory<T> | null
+  readonly fallbackChain: ReadonlyArray<RendererTier>
+  readonly reason: string
+  /**
+   * The original tier-detection result. Useful for telemetry — when
+   * `tier < detection.tier` the consumer knows the host could have
+   * done better but the registry was the binding constraint.
+   */
+  readonly detection: RendererTierResult
+}
+
+export interface SelectBackendOptions<T = unknown> {
+  readonly registry: BackendRegistry<T>
+  /**
+   * Tier-detection probes pass-through for tests. Same shape as
+   * {@link DetectRendererTierOptions}.
+   */
+  readonly detect?: DetectRendererTierOptions
+  /**
+   * Optional pre-computed detection result. When provided, the selector
+   * skips `detectRendererTier()` and uses this directly. Useful when
+   * the caller cached the detection at app startup.
+   */
+  readonly detection?: RendererTierResult
+  /**
+   * Optional floor — refuse to select a backend below this tier even
+   * if a lower-tier factory is registered. Used by features that need
+   * GPU compute (`minimum: 'webgl2'`). When the floor can't be met,
+   * the result has `tier: 'none'` and `factory: null`.
+   */
+  readonly minimum?: RendererTier
+}
+
+// ---------------------------------------------------------------------------
+// Selection
+// ---------------------------------------------------------------------------
+
+const SEARCH_ORDER: ReadonlyArray<Exclude<RendererTier, 'none'>> = ['webgpu', 'webgl2', 'canvas2d']
+
+/**
+ * Pick the highest registered backend at or below the detected tier
+ * (and at or above the optional minimum). Pure-data.
+ *
+ *   const sel = selectBackend({
+ *     registry: { webgpu: makeGpu, webgl2: makeGl2, canvas2d: makeC2d },
+ *   })
+ *   if (sel.factory === null) throw new Error('no renderer')
+ *   const renderer = sel.factory()
+ *
+ * Telemetry pattern:
+ *
+ *   if (sel.tier !== sel.detection.tier) {
+ *     log('renderer downgrade', sel.detection.tier, '→', sel.tier, sel.reason)
+ *   }
+ */
+export function selectBackend<T = unknown>(opts: SelectBackendOptions<T>): BackendSelection<T> {
+  const detection = opts.detection ?? detectRendererTier(opts.detect)
+  const detectedTier = detection.tier
+  const minimum = opts.minimum ?? 'none'
+
+  // Validate the minimum is a known tier; reject 'none' as a minimum
+  // because a 'none' floor is meaningless — nothing can be below it.
+  if (!(minimum in RENDERER_TIER_RANK)) {
+    throw new KLineChartError(
+      'INVALID_PARAM',
+      `selectBackend: minimum must be a RendererTier, got ${JSON.stringify(minimum)}`,
+    )
+  }
+
+  const chain: RendererTier[] = []
+  // Search from the detected tier downwards through SEARCH_ORDER.
+  for (const candidate of SEARCH_ORDER) {
+    // Skip tiers above the detected ceiling.
+    if (RENDERER_TIER_RANK[candidate] > RENDERER_TIER_RANK[detectedTier]) {
+      continue
+    }
+    chain.push(candidate)
+    // Skip below the configured minimum.
+    if (!isTierAtLeast(candidate, minimum)) {
+      // No further candidate will satisfy the minimum.
+      break
+    }
+    const factory = opts.registry[candidate] ?? null
+    if (factory !== null) {
+      return {
+        tier: candidate,
+        factory,
+        fallbackChain: chain,
+        reason:
+          candidate === detectedTier
+            ? `direct match: detected ${candidate} and ${candidate} backend is registered`
+            : `downgrade: detected ${detectedTier}, but only ${candidate} backend is registered`,
+        detection,
+      }
+    }
+  }
+
+  return {
+    tier: 'none',
+    factory: null,
+    fallbackChain: chain,
+    reason:
+      detectedTier === 'none'
+        ? `host has no renderable tier`
+        : `no registered backend at or below detected ${detectedTier}` +
+          (opts.minimum !== undefined && opts.minimum !== 'none'
+            ? ` (minimum=${opts.minimum})`
+            : ''),
+    detection,
+  }
+}
+
+/**
+ * Strict variant: throws `KLineChartError('INVALID_STATE')` if no factory
+ * could be selected. Use when a renderable backend is mandatory.
+ */
+export function selectBackendOrThrow<T = unknown>(
+  opts: SelectBackendOptions<T>,
+): BackendSelection<T> & { factory: BackendFactory<T> } {
+  const sel = selectBackend(opts)
+  if (sel.factory === null) {
+    throw new KLineChartError('INVALID_STATE', `selectBackendOrThrow: ${sel.reason}`)
+  }
+  return sel as BackendSelection<T> & { factory: BackendFactory<T> }
+}

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

@@ -0,0 +1,244 @@
+import { describe, it, expect, vi } from 'vitest'
+
+import { RENDERER_PRIORITY } from '../../../foundation/plugin'
+import type { RendererPlugin, RenderContext } from '../../../foundation/plugin'
+import { createLayerFromPlugin } from '../createLayerFromPlugin'
+import type { PaintContext } from '../types'
+
+// ---------------------------------------------------------------------------
+// Test helpers
+// ---------------------------------------------------------------------------
+
+function makeMockPlugin(overrides: Partial<RendererPlugin> = {}): RendererPlugin {
+  return {
+    name: 'test-plugin',
+    paneId: 'main',
+    priority: RENDERER_PRIORITY.MAIN,
+    enabled: true,
+    draw: vi.fn(),
+    ...overrides,
+  }
+}
+
+function makeMockContext(): RenderContext {
+  return {
+    ctx: {} as unknown as CanvasRenderingContext2D,
+    pane: {} as unknown as RenderContext['pane'],
+    data: [],
+    period: 'daily',
+    range: { start: 0, end: 10 },
+    scrollLeft: 0,
+    kWidth: 8,
+    kGap: 2,
+    dpr: 2,
+    paneWidth: 800,
+    kLinePositions: [0, 10, 20],
+    kLineCenters: [5, 15, 25],
+    kBarRects: [
+      { x: 0, width: 8 },
+      { x: 10, width: 8 },
+      { x: 20, width: 8 },
+    ],
+    theme: 'dark',
+  } as unknown as RenderContext
+}
+
+const stubPaintCtx = {
+  renderer: {} as unknown as PaintContext['renderer'],
+  region: { x: 0, y: 0, width: 800, height: 600, dpr: 2 },
+  paneRole: 'main' as const,
+  paneId: 'main',
+  frameNumber: 0,
+  deltaMs: 16,
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('createLayerFromPlugin', () => {
+  it('delegates paint to plugin.draw with context from getContext', () => {
+    const plugin = makeMockPlugin()
+    const context = makeMockContext()
+    const getContext = vi.fn(() => context)
+    const layer = createLayerFromPlugin(plugin, getContext, 'main')
+
+    layer.paint(stubPaintCtx)
+
+    expect(getContext).toHaveBeenCalledOnce()
+    expect(plugin.draw).toHaveBeenCalledOnce()
+    expect(plugin.draw).toHaveBeenCalledWith(context)
+  })
+
+  it('skips plugin.draw when getContext returns null', () => {
+    const plugin = makeMockPlugin()
+    const getContext = vi.fn(() => null)
+    const layer = createLayerFromPlugin(plugin, getContext, 'main')
+
+    layer.paint(stubPaintCtx)
+
+    expect(getContext).toHaveBeenCalledOnce()
+    expect(plugin.draw).not.toHaveBeenCalled()
+  })
+
+  it('skips plugin.draw when visible is false', () => {
+    const plugin = makeMockPlugin()
+    const context = makeMockContext()
+    const getContext = vi.fn(() => context)
+    const layer = createLayerFromPlugin(plugin, getContext, 'main')
+
+    layer.visible = false
+    layer.paint(stubPaintCtx)
+
+    expect(plugin.draw).not.toHaveBeenCalled()
+  })
+
+  it('calls plugin.onUninstall on dispose', () => {
+    const onUninstall = vi.fn()
+    const plugin = makeMockPlugin({ onUninstall })
+    const getContext = vi.fn(() => makeMockContext())
+    const layer = createLayerFromPlugin(plugin, getContext, 'main')
+
+    layer.dispose()
+
+    expect(onUninstall).toHaveBeenCalledOnce()
+  })
+
+  it('does not throw when dispose is called without onUninstall', () => {
+    const plugin = makeMockPlugin({ onUninstall: undefined })
+    const getContext = vi.fn(() => makeMockContext())
+    const layer = createLayerFromPlugin(plugin, getContext, 'main')
+
+    expect(() => layer.dispose()).not.toThrow()
+  })
+
+  it('maps enabled=false to visible=false, enabled=true to visible=true', () => {
+    const pluginDisabled = makeMockPlugin({ enabled: false })
+    const getContext = vi.fn(() => makeMockContext())
+    const layerDisabled = createLayerFromPlugin(pluginDisabled, getContext, 'main')
+    expect(layerDisabled.visible).toBe(false)
+
+    const pluginEnabled = makeMockPlugin({ enabled: true })
+    const layerEnabled = createLayerFromPlugin(pluginEnabled, getContext, 'main')
+    expect(layerEnabled.visible).toBe(true)
+  })
+
+  it('defaults visible to true when enabled is undefined', () => {
+    const plugin = makeMockPlugin({ enabled: undefined })
+    const getContext = vi.fn(() => makeMockContext())
+    const layer = createLayerFromPlugin(plugin, getContext, 'main')
+    expect(layer.visible).toBe(true)
+  })
+
+  it('visible setter updates the field', () => {
+    const plugin = makeMockPlugin()
+    const getContext = vi.fn(() => makeMockContext())
+    const layer = createLayerFromPlugin(plugin, getContext, 'main')
+
+    expect(layer.visible).toBe(true)
+    layer.visible = false
+    expect(layer.visible).toBe(false)
+    layer.visible = true
+    expect(layer.visible).toBe(true)
+  })
+
+  describe('layer identity fields', () => {
+    it('id is plugin: + plugin.name', () => {
+      const plugin = makeMockPlugin({ name: 'candle' })
+      const layer = createLayerFromPlugin(plugin, () => null, 'main')
+      expect(layer.id).toBe('plugin:candle')
+    })
+
+    it('z equals plugin.priority', () => {
+      const plugin = makeMockPlugin({ priority: 42 })
+      const layer = createLayerFromPlugin(plugin, () => null, 'main')
+      expect(layer.z).toBe(42)
+    })
+
+    it('paneRole is main when targetPaneId is main', () => {
+      const layer = createLayerFromPlugin(makeMockPlugin(), () => null, 'main')
+      expect(layer.paneRole).toBe('main')
+    })
+
+    it('paneRole is sub when targetPaneId is not main', () => {
+      const layer = createLayerFromPlugin(makeMockPlugin(), () => null, 'sub')
+      expect(layer.paneRole).toBe('sub')
+    })
+
+    it('skips paint when paneRole is sub and ctx.paneId does not match targetPaneId', () => {
+      const plugin = makeMockPlugin()
+      const context = makeMockContext()
+      const getContext = vi.fn(() => context)
+      const layer = createLayerFromPlugin(plugin, getContext, 'RSI_0')
+
+      // Paint with matching paneId → draws
+      layer.paint({ ...stubPaintCtx, paneRole: 'sub', paneId: 'RSI_0' })
+      expect(plugin.draw).toHaveBeenCalledTimes(1)
+
+      // Paint with non-matching paneId → skips
+      layer.paint({ ...stubPaintCtx, paneRole: 'sub', paneId: 'MACD_0' })
+      expect(plugin.draw).toHaveBeenCalledTimes(1)
+    })
+
+    it('main pane layers always paint regardless of paneId', () => {
+      const plugin = makeMockPlugin()
+      const context = makeMockContext()
+      const getContext = vi.fn(() => context)
+      const layer = createLayerFromPlugin(plugin, getContext, 'main')
+
+      layer.paint({ ...stubPaintCtx, paneRole: 'main', paneId: 'main' })
+      expect(plugin.draw).toHaveBeenCalledTimes(1)
+
+      // Main layer paints even with non-matching paneId (it has paneRole 'main')
+      layer.paint({ ...stubPaintCtx, paneRole: 'main', paneId: 'other' })
+      expect(plugin.draw).toHaveBeenCalledTimes(2)
+    })
+  })
+
+  describe('role mapping from priority and name', () => {
+    it('plugin.layer=overlay maps to role overlay', () => {
+      const plugin = makeMockPlugin({
+        priority: RENDERER_PRIORITY.MAIN,
+        layer: 'overlay',
+      })
+      const layer = createLayerFromPlugin(plugin, () => null, 'main')
+      expect(layer.role).toBe('overlay')
+    })
+
+    it('GRID priority maps to background', () => {
+      const plugin = makeMockPlugin({
+        name: 'gridLines',
+        priority: RENDERER_PRIORITY.GRID,
+      })
+      const layer = createLayerFromPlugin(plugin, () => null, 'main')
+      expect(layer.role).toBe('background')
+    })
+
+    it('INDICATOR priority maps to indicator', () => {
+      const plugin = makeMockPlugin({
+        name: 'ma',
+        priority: RENDERER_PRIORITY.INDICATOR,
+      })
+      const layer = createLayerFromPlugin(plugin, () => null, 'main')
+      expect(layer.role).toBe('indicator')
+    })
+
+    it('candle name with MAIN priority maps to primary', () => {
+      const plugin = makeMockPlugin({
+        name: 'candle',
+        priority: RENDERER_PRIORITY.MAIN,
+      })
+      const layer = createLayerFromPlugin(plugin, () => null, 'main')
+      expect(layer.role).toBe('primary')
+    })
+
+    it('drawing name maps to drawing role', () => {
+      const plugin = makeMockPlugin({
+        name: 'drawing-label-overlay',
+        priority: RENDERER_PRIORITY.OVERLAY,
+      })
+      const layer = createLayerFromPlugin(plugin, () => null, 'main')
+      expect(layer.role).toBe('drawing')
+    })
+  })
+})

package/src/rendering/scene/createLayerFromPlugin.ts

@@ -0,0 +1,48 @@
+import { RENDERER_PRIORITY } from '../../foundation/plugin/index'
+import type { RendererPlugin, RenderContext } from '../../foundation/plugin/index'
+
+import type { Layer, LayerRole, PaintContext, PaneRole } from './types'
+
+export function createLayerFromPlugin(
+  plugin: RendererPlugin,
+  getContext: () => RenderContext | null,
+  targetPaneId: string,
+): Layer {
+  const paneRole: PaneRole =
+    targetPaneId === 'main' ? 'main' : targetPaneId === 'global' ? 'global' : 'sub'
+  let visible = plugin.enabled !== false
+
+  return {
+    id: `plugin:${plugin.name}`,
+    role: pluginPriorityToRole(plugin.priority, plugin),
+    paneRole,
+    z: plugin.priority,
+    get visible() {
+      return visible
+    },
+    set visible(v: boolean) {
+      visible = v
+    },
+    paint(ctx: PaintContext) {
+      if (!visible) return
+      // For sub-pane layers, skip if we're painting a different sub-pane
+      if (paneRole === 'sub' && ctx.paneId !== targetPaneId) return
+      const context = getContext()
+      if (!context) return
+      plugin.draw(context)
+    },
+    dispose() {
+      plugin.onUninstall?.()
+    },
+  }
+}
+
+function pluginPriorityToRole(priority: number, plugin: RendererPlugin): LayerRole {
+  if (plugin.layer === 'overlay') return 'overlay'
+  if (priority <= RENDERER_PRIORITY.GRID || plugin.name === 'gridLines' || plugin.name === 'grid')
+    return 'background'
+  if (priority <= RENDERER_PRIORITY.INDICATOR && plugin.name !== 'candle') return 'indicator'
+  if (plugin.name === 'candle' || plugin.name === 'comparisonLine') return 'primary'
+  if (plugin.name.startsWith('drawing')) return 'drawing'
+  return 'indicator'
+}

package/src/rendering/scene/createScene.ts

@@ -0,0 +1,121 @@
+/**
+ * Scene factory — composition, ordered iteration, lifecycle.
+ *
+ * Design notes:
+ * - The layer list is stored in **registration order** in a private array.
+ *   `paintPane` performs a stable sort by `z` at paint time. We do not
+ *   maintain a sorted invariant on the array itself because:
+ *     1. Add/remove must remain O(n), and z is a number, so a sorted
+ *        insert is O(n) anyway.
+ *     2. Stable sort by z gives the documented tie-breaker (registration
+ *        order) "for free" without parallel arrays or registration counters.
+ * - The `layers` signal exposes a snapshot. Every mutation produces a NEW
+ *   array via spread or filter — never mutate the previous value. This is
+ *   the immutability contract framework adapters rely on.
+ * - After `dispose`, every public method becomes a no-op. The `disposed`
+ *   flag is checked at the top of each method; this matches the renderer's
+ *   "dispose freezes" semantic and prevents callers from leaking listeners
+ *   into a torn-down scene.
+ */
+
+import { createSignal, type Signal } from '../../foundation/reactivity/signal'
+
+import type { Layer, LayerRole, PaintContext, Scene } from './types'
+
+export function createScene(): Scene {
+  // ---- internal state ----------------------------------------------------
+  // Mutable list held outside the signal so that signal.set always receives
+  // a fresh frozen-shape snapshot. We never expose this array directly.
+  let layerList: Layer[] = []
+  let disposed = false
+  const layersSignal: Signal<ReadonlyArray<Layer>> = createSignal<ReadonlyArray<Layer>>([])
+
+  const publish = (): void => {
+    layersSignal.set([...layerList] as ReadonlyArray<Layer>)
+  }
+
+  // ---- public API --------------------------------------------------------
+
+  const addLayer = (layer: Layer): void => {
+    if (disposed) return
+    // Reject duplicate ids silently — protects against double-registration
+    // races where two systems (e.g. an indicator controller + a config
+    // restore) both attempt to add the same layer. The first wins.
+    if (layerList.some((existing) => existing.id === layer.id)) return
+    layerList = [...layerList, layer]
+    publish()
+  }
+
+  const removeLayer = (id: string): boolean => {
+    if (disposed) return false
+    const next = layerList.filter((layer) => layer.id !== id)
+    if (next.length === layerList.length) return false
+    layerList = next
+    publish()
+    return true
+  }
+
+  const getLayer = (id: string): Layer | null => {
+    if (disposed) return null
+    const hit = layerList.find((layer) => layer.id === id)
+    return hit ?? null
+  }
+
+  const setLayerVisibility = (id: string, visible: boolean): boolean => {
+    if (disposed) return false
+    const layer = layerList.find((l) => l.id === id)
+    if (!layer) return false
+    // `visible` is a mutable field on the layer (per the interface);
+    // mutating it does not affect the `layers` signal's identity because
+    // subscribers care about membership, not field state. This matches
+    // how chart adapters batch visibility toggles (no re-render storm).
+    layer.visible = visible
+    return true
+  }
+
+  const paintPane = (ctx: PaintContext, roles?: ReadonlyArray<LayerRole>): void => {
+    if (disposed) return
+    let candidates = layerList.filter(
+      (layer) => (layer.paneRole === ctx.paneRole || layer.paneRole === 'global') && layer.visible,
+    )
+    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.
+    candidates.sort((a, b) => a.z - b.z)
+    for (const layer of candidates) {
+      layer.paint(ctx)
+    }
+  }
+
+  const dispose = (): void => {
+    if (disposed) return
+    disposed = true
+    // Snapshot first because layer.dispose may attempt further mutations
+    // through a stale reference — we want predictable iteration here.
+    const snapshot = layerList
+    layerList = []
+    for (const layer of snapshot) {
+      try {
+        layer.dispose()
+      } catch {
+        // Swallow per-layer dispose errors so one broken layer can't
+        // strand the rest. A logger would go here in production; the
+        // headless core does not own a logger contract yet.
+      }
+    }
+    layersSignal.set([] as ReadonlyArray<Layer>)
+  }
+
+  return {
+    layers: layersSignal,
+    addLayer,
+    removeLayer,
+    getLayer,
+    setLayerVisibility,
+    paintPane,
+    dispose,
+  }
+}