@363045841yyt/klinechart-core 0.8.11-alpha.0 → 0.8.12

package/src/scene/createScene.ts

@@ -0,0 +1,117 @@
+/**
+ * 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 '../reactivity/signal'
+import type { Layer, 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.slice() 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): void => {
+        if (disposed) return
+        // Filter then stable-sort. 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.
+        const candidates = layerList.filter(
+            (layer) => layer.paneRole === ctx.paneRole && layer.visible,
+        )
+        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,
+    }
+}

package/src/scene/index.ts

@@ -0,0 +1,29 @@
+/**
+ * Scene abstraction barrel.
+ *
+ * Exports the `Layer` / `Scene` types, the `createScene` factory, and the
+ * `LayerRegistry` mechanism + canonical built-in layer typeIds. This is the
+ * level above `render` and below `interaction` in the core dependency stack
+ * — see `docs/ROADMAP.md` §0.
+ */
+
+export type {
+    Layer,
+    LayerRole,
+    PaneRole,
+    PaintContext,
+    Scene,
+} from './types'
+
+export { createScene } from './createScene'
+
+export {
+    createLayerRegistry,
+    BUILTIN_LAYER_TYPES,
+} from './layerRegistry'
+
+export type {
+    LayerFactory,
+    LayerRegistry,
+    BuiltinLayerType,
+} from './layerRegistry'

package/src/scene/layerRegistry.ts

@@ -0,0 +1,117 @@
+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> =>
+        Array.from(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/scene/types.ts

@@ -0,0 +1,143 @@
+/**
+ * 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 { Renderer } from '../render/Renderer'
+import type { SurfaceRegion } from '../render/SurfaceBackend'
+import type { Signal } from '../reactivity/signal'
+
+/**
+ * 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'
+
+/**
+ * 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
+    /** 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 */
+    paintPane(ctx: PaintContext): void
+
+    dispose(): void
+}