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

package/src/rendering/scene/layerRegistry.ts

@@ -0,0 +1,115 @@
+import { KLineChartError } from '../../errors'
+/**
+ * Layer factory registry.
+ *
+ * The registry is a tiny lookup table from a stable string `typeId` to a
+ * factory function that builds a `Layer` instance. It exists so that:
+ *
+ * 1. Chart adapters can choose which built-in layer types to wire in,
+ *    rather than the core forcing all of them on every consumer.
+ * 2. Component layers built by sibling agents (Volume Profile, Order Book
+ *    Heatmap, Footprint) register their factories without touching the
+ *    scene code itself — the registry is the integration point.
+ * 3. The registry is decoupled from `Scene`: a factory produces a `Layer`;
+ *    the consumer is responsible for calling `scene.addLayer(layer)`. This
+ *    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.
+ */
+
+import type { Layer, LayerRole } from './types'
+
+/**
+ * A layer factory turns a typed config into a `Layer`.
+ *
+ * `TConfig` is parameterised so factories can declare their own config
+ * shape (e.g. the Volume Profile factory takes `{ store, bins, modes }`).
+ * The registry stores factories with `unknown` config — callers know which
+ * factory they're calling and cast on retrieval.
+ */
+export interface LayerFactory<TConfig = unknown> {
+  /** Stable id for this layer TYPE (not instance) — e.g. 'volume-profile'. */
+  typeId: string
+  role: LayerRole
+  /** Create a Layer instance; consumers pass any config + their store ref. */
+  create(config: TConfig): Layer
+}
+
+export interface LayerRegistry {
+  /**
+   * Register a factory. Returns nothing on success.
+   * Throws on duplicate `typeId` — duplicates are programmer errors
+   * (two systems trying to claim the same layer type id), not runtime
+   * conditions to be silently handled. The error message names the
+   * conflicting typeId so the caller can locate it.
+   */
+  register(factory: LayerFactory): void
+  /**
+   * Remove a factory by typeId. Returns true if a factory was removed,
+   * false if no such typeId was registered.
+   */
+  unregister(typeId: string): boolean
+  /** Look up a factory by typeId. Returns null when not registered. */
+  get(typeId: string): LayerFactory | null
+  /** Snapshot of all registered factories. Safe to iterate; do not mutate. */
+  list(): ReadonlyArray<LayerFactory>
+}
+
+export function createLayerRegistry(): LayerRegistry {
+  // Map preserves insertion order, which makes `list()` deterministic —
+  // useful for snapshot tests and for UI surfaces (e.g. an "available
+  // layers" picker) that render the list in registration order.
+  const factories = new Map<string, LayerFactory>()
+
+  const register = (factory: LayerFactory): void => {
+    if (factories.has(factory.typeId)) {
+      throw new KLineChartError(
+        'NOT_REGISTERED',
+        `LayerRegistry: typeId "${factory.typeId}" is already registered`,
+      )
+    }
+    factories.set(factory.typeId, factory)
+  }
+
+  const unregister = (typeId: string): boolean => factories.delete(typeId)
+
+  const get = (typeId: string): LayerFactory | null => factories.get(typeId) ?? null
+
+  const list = (): ReadonlyArray<LayerFactory> =>
+    [...factories.values()] as ReadonlyArray<LayerFactory>
+
+  return { register, unregister, get, list }
+}
+
+/**
+ * Canonical typeIds for the layer types this codebase intends to ship.
+ *
+ * Grouped into:
+ * - "builtin:" — layers backed by existing v0 WebGL renderers (will arrive
+ *   via adapter factories in a follow-up PR).
+ * - "component:" — the three P1 differentiating components from ROADMAP §3.
+ *
+ * These are string constants (not enums) so external code can pass through
+ * string literal types without an enum import — useful for config blobs.
+ */
+export const BUILTIN_LAYER_TYPES = {
+  // Existing in v0 (handled by legacy renderers)
+  CANDLE: 'builtin:candle',
+  VOLUME: 'builtin:volume',
+  INDICATOR_MA: 'builtin:indicator:ma',
+  INDICATOR_BOLL: 'builtin:indicator:boll',
+  DRAWING: 'builtin:drawing',
+  CROSSHAIR: 'builtin:crosshair',
+  GRID: 'builtin:grid',
+  // P1 component layers (controllers from sibling agents will provide factories)
+  VOLUME_PROFILE: 'component:volume-profile',
+  ORDER_BOOK_HEATMAP: 'component:order-book-heatmap',
+  FOOTPRINT: 'component:footprint',
+} as const
+
+export type BuiltinLayerType = (typeof BUILTIN_LAYER_TYPES)[keyof typeof BUILTIN_LAYER_TYPES]

package/src/rendering/scene/types.ts

@@ -0,0 +1,148 @@
+/**
+ * Scene + Layer type definitions.
+ *
+ * The scene is the level above `render` in core's dependency stack
+ * (see `docs/ROADMAP.md` §0):
+ *
+ *     interaction → store → scene → render
+ *
+ * A `Layer` is a self-contained drawing module — candles, volume bars,
+ * indicator plots, drawings, crosshair, and the P1 component layers
+ * (Volume Profile, Order Book Heatmap, Footprint) all conform to the same
+ * shape. The scene composes layers, owns ordering, and drives per-frame
+ * paint dispatch; it does NOT know which GPU backend is underneath
+ * because `paint()` only sees a `Renderer` reference via `PaintContext`.
+ *
+ * This file is **pure interface** — `createScene.ts` implements `Scene`,
+ * but the types here are zero-runtime so framework adapters and indicator
+ * controllers can compile against them without pulling in the implementation.
+ */
+
+import type { Signal } from '../../foundation/reactivity/signal'
+import type { Renderer } from '../render/Renderer'
+import type { SurfaceRegion } from '../render/SurfaceBackend'
+
+/**
+ * Roles let the scene group layers and let other systems target them
+ * (e.g. picking ignores `background`; drawings live above indicators).
+ *
+ * The ordering here is informational, not enforced — z-order is the
+ * authoritative paint order. Roles exist so a follow-up PR can build
+ * features like "hit-test only drawing + component layers" without
+ * peeking at layer ids.
+ */
+export type LayerRole =
+  | 'background' // grid, axes
+  | 'primary' // candles, volume bars
+  | 'indicator' // MA, BOLL, indicator-defined plots
+  | 'component' // Volume Profile, Heatmap, Footprint
+  | 'drawing' // user drawings
+  | 'overlay' // crosshair, hover, legends
+
+/**
+ * Which pane a layer belongs to. The chart has a main pane (candles +
+ * primary indicators) and zero-or-more sub panes (volume, RSI, MACD).
+ * Layers declare their pane statically; the scene's `paintPane` filters
+ * by this field so each pane's region only sees its own layers.
+ *
+ * NOTE for implementations: this PR uses a flat 'main' / 'sub' split.
+ * If a future iteration needs to address a specific sub-pane (e.g. the
+ * volume pane vs the RSI pane), extend this to a string id (e.g. 'sub:rsi')
+ * — the Layer / Scene contract here does not pre-commit a multi-sub-pane
+ * scheme on purpose.
+ */
+export type PaneRole = 'main' | 'sub' | 'global'
+
+/**
+ * Stateless paint context handed to each layer per frame.
+ *
+ * The layer reads what it needs from the store via subscriptions
+ * (the store reference is held by the layer itself, set up at construction
+ * time by its factory); this context is the per-frame state.
+ *
+ * Invariants:
+ * - `renderer` MUST already be inside a `beginFrame` / `endFrame` pair
+ *   when paint runs. The scene does not call beginFrame/endFrame itself —
+ *   that's the chart engine's responsibility (see `docs/ROADMAP.md` §0
+ *   for the layered call chain).
+ * - `region` is the surface region for the pane currently being painted.
+ *   Layers MUST treat all coordinates as logical pixels relative to this
+ *   region's origin (the renderer's surface handles DPR scaling).
+ * - `frameNumber` is monotonic across the chart's lifetime; layers can use
+ *   it to drive animations or detect skipped frames.
+ * - `deltaMs` is the wall-clock delta since the previous paint of any pane,
+ *   in milliseconds. May be `0` on the very first frame.
+ */
+export interface PaintContext {
+  renderer: Renderer
+  region: SurfaceRegion
+  paneRole: PaneRole
+  /** The pane id being painted (e.g. 'main', 'RSI_0') — used by sub-pane layers */
+  paneId: string
+  /** monotonically increasing frame counter for animation/timing */
+  frameNumber: number
+  /** time elapsed since last frame in ms (for animations) */
+  deltaMs: number
+}
+
+/**
+ * A Layer is a self-contained drawing module.
+ *
+ * The contract:
+ * - Pure function `paint()`: given context, produce GPU commands.
+ * - `paint()` MUST NOT mutate any shared state visible to other layers.
+ *   Layer-private state (cached buffers, last-seen frame number) is fine.
+ * - `paint()` runs in scene-defined order; order matters for visual stacking
+ *   (lower z paints first, so higher-z layers visually sit on top).
+ * - `dispose()` MUST release any renderer resources the layer allocated
+ *   (buffers, pipelines). After dispose, the layer is dead — the scene
+ *   removes it and will not call paint again.
+ * - `visible` is a runtime toggle. Invisible layers are skipped entirely
+ *   (no paint() call); the layer keeps its allocated resources so a flip
+ *   back to visible is cheap.
+ */
+export interface Layer {
+  readonly id: string
+  readonly role: LayerRole
+  /** which pane this layer belongs to */
+  readonly paneRole: PaneRole
+  /** lower z first; ties broken by registration order */
+  readonly z: number
+  /** quick toggle without removing the layer from the scene */
+  visible: boolean
+
+  paint(ctx: PaintContext): void
+  dispose(): void
+}
+
+/**
+ * The Scene composes layers and exposes them to subscribers via a Signal.
+ *
+ * Add/remove operations produce a NEW array on the `layers` signal — never
+ * mutate the previous value in place. This guarantees framework adapters
+ * (React, Vue, Angular) using `Object.is` equality detect changes correctly.
+ *
+ * `paintPane` is the only entry point that draws anything; it filters layers
+ * by `paneRole`, drops invisible layers, and dispatches in z order with ties
+ * broken by registration order (FIFO stable sort).
+ *
+ * `dispose` tears down every layer the scene currently owns and freezes the
+ * scene — subsequent add/remove/setLayerVisibility/paintPane calls are silent
+ * no-ops. This matches the renderer's "dispose freezes the object" semantics.
+ */
+export interface Scene {
+  readonly layers: Signal<ReadonlyArray<Layer>>
+
+  addLayer(layer: Layer): void
+  removeLayer(id: string): boolean
+  getLayer(id: string): Layer | null
+  setLayerVisibility(id: string, visible: boolean): boolean
+
+  /**
+   * paint layers for one pane in z-order, then by registration order
+   * @param roles - if provided, only paint layers whose role is in this list
+   */
+  paintPane(ctx: PaintContext, roles?: ReadonlyArray<LayerRole>): void
+
+  dispose(): void
+}

package/src/rendering/scheduler/__tests__/createFrameBudget.test.ts

@@ -0,0 +1,319 @@
+/**
+ * Tests for `createFrameBudget`.
+ *
+ * The clock is injected via `opts.now`, so timing assertions are exact:
+ * we advance a counter manually and the scheduler reads from it.
+ *
+ * Coverage:
+ *   1. Construction validates targetMs / historySize / maxQueueSize.
+ *   2. submit:
+ *      - rejects empty id with KLineChartError(INVALID_PARAM)
+ *      - queues into correct priority tier (queueDepth updates)
+ *      - coalesces same-id submission (the later wins)
+ *      - re-buckets when coalesce changes priority
+ *      - drops oldest low/medium under maxQueueSize pressure
+ *      - never drops high under pressure
+ *   3. flush:
+ *      - runs all queued tasks if deadline is generous
+ *      - stops at deadline (remaining stay queued)
+ *      - runs high before medium before low (priority ordering)
+ *      - within a tier, FIFO
+ *      - returns the number of tasks run
+ *      - throw in task is caught + dropped, others continue
+ *   4. beginFrame / endFrame:
+ *      - validate finite timestamps
+ *      - recentFrameMs is the rolling average over historySize frames
+ *      - overruns increments only when dur > targetMs
+ *   5. clear / dispose.
+ */
+
+import { describe, it, expect } from 'vitest'
+
+import { createFrameBudget, type FrameTask } from '..'
+import { isKLineChartError } from '../../../errors'
+
+function fakeClock(): {
+  now: () => number
+  advance: (ms: number) => void
+  set: (t: number) => void
+} {
+  let t = 0
+  return {
+    now: () => t,
+    advance: (ms: number) => {
+      t += ms
+    },
+    set: (next: number) => {
+      t = next
+    },
+  }
+}
+
+function record(
+  id: string,
+  store: string[],
+  priority: FrameTask['priority'] = 'medium',
+): FrameTask {
+  return { id, priority, work: () => store.push(id) }
+}
+
+// ---------------------------------------------------------------------------
+// Construction
+// ---------------------------------------------------------------------------
+
+describe('createFrameBudget — validation', () => {
+  it('rejects non-positive targetMs', () => {
+    for (const v of [0, -1, Number.NaN]) {
+      try {
+        createFrameBudget({ targetMs: v })
+        expect.fail(`expected throw for ${v}`)
+      } catch (e) {
+        expect(isKLineChartError(e, 'INVALID_PARAM')).toBe(true)
+      }
+    }
+  })
+
+  it('rejects non-positive-integer historySize', () => {
+    for (const v of [0, -1, 1.5]) {
+      try {
+        createFrameBudget({ historySize: v })
+        expect.fail(`expected throw for ${v}`)
+      } catch (e) {
+        expect(isKLineChartError(e, 'INVALID_PARAM')).toBe(true)
+      }
+    }
+  })
+
+  it('rejects non-positive-integer maxQueueSize', () => {
+    try {
+      createFrameBudget({ maxQueueSize: 0 })
+      expect.fail('expected throw')
+    } catch (e) {
+      expect(isKLineChartError(e, 'INVALID_PARAM')).toBe(true)
+    }
+  })
+
+  it('exposes targetMs verbatim', () => {
+    expect(createFrameBudget({ targetMs: 8 }).targetMs).toBe(8)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// submit
+// ---------------------------------------------------------------------------
+
+describe('submit', () => {
+  it('rejects empty id', () => {
+    const fb = createFrameBudget()
+    try {
+      fb.submit({ id: '', priority: 'low', work: () => {} })
+      expect.fail('expected throw')
+    } catch (e) {
+      expect(isKLineChartError(e, 'INVALID_PARAM')).toBe(true)
+    }
+  })
+
+  it('queueDepth tracks submissions across tiers', () => {
+    const fb = createFrameBudget()
+    const seen: string[] = []
+    fb.submit(record('a', seen, 'high'))
+    fb.submit(record('b', seen, 'medium'))
+    fb.submit(record('c', seen, 'low'))
+    expect(fb.queueDepth.peek()).toBe(3)
+  })
+
+  it('coalesces same-id submission (later wins)', () => {
+    const fb = createFrameBudget()
+    const seen: string[] = []
+    fb.submit({ id: 'x', priority: 'low', work: () => seen.push('first') })
+    fb.submit({ id: 'x', priority: 'low', work: () => seen.push('second') })
+    const clk = fakeClock()
+    // Cheap test: a fresh budget with default now — flush with a far deadline.
+    fb.flush(Number.POSITIVE_INFINITY)
+    expect(seen).toEqual(['second'])
+  })
+
+  it('re-buckets when coalesce changes priority', () => {
+    const seen: string[] = []
+    const fb = createFrameBudget({ now: fakeClock().now })
+    fb.submit({ id: 'x', priority: 'low', work: () => seen.push('low') })
+    fb.submit({ id: 'x', priority: 'high', work: () => seen.push('high') })
+    fb.submit(record('y', seen, 'medium'))
+    fb.flush(Number.POSITIVE_INFINITY)
+    // x runs first (it's now high), then y.
+    expect(seen).toEqual(['high', 'y'])
+  })
+
+  it('drops oldest low under maxQueueSize pressure', () => {
+    const seen: string[] = []
+    const fb = createFrameBudget({ maxQueueSize: 2 })
+    fb.submit(record('a', seen, 'low'))
+    fb.submit(record('b', seen, 'low'))
+    fb.submit(record('c', seen, 'high'))
+    fb.flush(Number.POSITIVE_INFINITY)
+    // 'a' was the oldest low; it got dropped to make room for 'c'.
+    expect(seen).toEqual(['c', 'b'])
+  })
+
+  it('never drops high under pressure', () => {
+    const seen: string[] = []
+    const fb = createFrameBudget({ maxQueueSize: 2 })
+    fb.submit(record('a', seen, 'high'))
+    fb.submit(record('b', seen, 'high'))
+    fb.submit(record('c', seen, 'high'))
+    fb.flush(Number.POSITIVE_INFINITY)
+    // All 3 high tasks present; the cap was exceeded but high
+    // is never dropped (producer-is-misbehaving signal).
+    expect(seen).toEqual(['a', 'b', 'c'])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// flush
+// ---------------------------------------------------------------------------
+
+describe('flush', () => {
+  it('runs high before medium before low (priority)', () => {
+    const seen: string[] = []
+    const fb = createFrameBudget()
+    fb.submit(record('low1', seen, 'low'))
+    fb.submit(record('med1', seen, 'medium'))
+    fb.submit(record('hi1', seen, 'high'))
+    fb.submit(record('hi2', seen, 'high'))
+    fb.submit(record('med2', seen, 'medium'))
+    fb.flush(Number.POSITIVE_INFINITY)
+    expect(seen).toEqual(['hi1', 'hi2', 'med1', 'med2', 'low1'])
+  })
+
+  it('within a tier, runs FIFO', () => {
+    const seen: string[] = []
+    const fb = createFrameBudget()
+    for (const id of ['a', 'b', 'c', 'd']) {
+      fb.submit(record(id, seen, 'medium'))
+    }
+    fb.flush(Number.POSITIVE_INFINITY)
+    expect(seen).toEqual(['a', 'b', 'c', 'd'])
+  })
+
+  it('stops at deadline; remaining tasks stay queued', () => {
+    const seen: string[] = []
+    const clk = fakeClock()
+    const fb = createFrameBudget({ now: clk.now })
+    for (let i = 0; i < 5; i++) {
+      fb.submit({
+        id: `t${i}`,
+        priority: 'medium',
+        work: () => {
+          seen.push(`t${i}`)
+          clk.advance(2) // each task costs 2ms
+        },
+      })
+    }
+    // Deadline at 5ms — 2 tasks complete (4ms), the 3rd would push us
+    // to 6ms but clock check happens BEFORE running each task. After
+    // 2 tasks, the next iteration sees now() = 4 < 5 — runs the 3rd
+    // (push to 6). After that, now() = 6 >= 5 — stop.
+    const done = fb.flush(5)
+    expect(done).toBe(3)
+    expect(seen).toEqual(['t0', 't1', 't2'])
+    expect(fb.queueDepth.peek()).toBe(2)
+  })
+
+  it('returns 0 if deadline already passed', () => {
+    const clk = fakeClock()
+    clk.set(100)
+    const fb = createFrameBudget({ now: clk.now })
+    fb.submit(record('a', [], 'high'))
+    expect(fb.flush(50)).toBe(0)
+  })
+
+  it('a throwing task is dropped; others continue', () => {
+    const seen: string[] = []
+    const fb = createFrameBudget()
+    fb.submit({ id: 'a', priority: 'high', work: () => seen.push('a') })
+    fb.submit({
+      id: 'bad',
+      priority: 'high',
+      work: () => {
+        throw new Error('boom')
+      },
+    })
+    fb.submit({ id: 'c', priority: 'high', work: () => seen.push('c') })
+    const done = fb.flush(Number.POSITIVE_INFINITY)
+    expect(done).toBe(2) // a + c, not bad
+    expect(seen).toEqual(['a', 'c'])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// beginFrame / endFrame
+// ---------------------------------------------------------------------------
+
+describe('beginFrame / endFrame', () => {
+  it('validates finite timestamps', () => {
+    const fb = createFrameBudget()
+    for (const m of ['beginFrame', 'endFrame'] as const) {
+      try {
+        fb[m](Number.NaN)
+        expect.fail('expected throw')
+      } catch (e) {
+        expect(isKLineChartError(e, 'INVALID_PARAM')).toBe(true)
+      }
+    }
+  })
+
+  it('recentFrameMs is the rolling average over historySize frames', () => {
+    const fb = createFrameBudget({ historySize: 3 })
+    // 3 frames at 10ms each → avg 10
+    for (let i = 0; i < 3; i++) {
+      fb.beginFrame(i * 16)
+      fb.endFrame(i * 16 + 10)
+    }
+    expect(fb.recentFrameMs.peek()).toBe(10)
+    // Push one 20ms frame; rolling window drops the oldest.
+    fb.beginFrame(48)
+    fb.endFrame(68)
+    // window: [10, 10, 20] → avg ≈ 13.33
+    expect(fb.recentFrameMs.peek()).toBeCloseTo((10 + 10 + 20) / 3, 5)
+  })
+
+  it('overruns increments only when frame > targetMs', () => {
+    const fb = createFrameBudget({ targetMs: 16 })
+    // 10ms frame — not an overrun
+    fb.beginFrame(0)
+    fb.endFrame(10)
+    expect(fb.overruns.peek()).toBe(0)
+    // 18ms frame — overrun
+    fb.beginFrame(16)
+    fb.endFrame(34)
+    expect(fb.overruns.peek()).toBe(1)
+    // Exactly at targetMs — not an overrun (> strict)
+    fb.beginFrame(32)
+    fb.endFrame(48)
+    expect(fb.overruns.peek()).toBe(1)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// clear / dispose
+// ---------------------------------------------------------------------------
+
+describe('clear', () => {
+  it('drops all queued tasks', () => {
+    const fb = createFrameBudget()
+    fb.submit(record('a', [], 'high'))
+    fb.submit(record('b', [], 'low'))
+    fb.clear()
+    expect(fb.queueDepth.peek()).toBe(0)
+  })
+})
+
+describe('dispose', () => {
+  it('makes submit / flush / frame markers no-ops', () => {
+    const fb = createFrameBudget()
+    fb.dispose()
+    expect(() => fb.submit(record('a', [], 'high'))).not.toThrow()
+    expect(fb.queueDepth.peek()).toBe(0)
+    expect(fb.flush(Number.POSITIVE_INFINITY)).toBe(0)
+  })
+})