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

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

@@ -1,244 +0,0 @@
-import { describe, it, expect, vi } from 'vitest'
-
-import { RENDERER_PRIORITY } from '../../plugin'
-import type { RendererPlugin, RenderContext } from '../../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/scene/createLayerFromPlugin.ts

@@ -1,48 +0,0 @@
-import { RENDERER_PRIORITY } from '../plugin'
-import type { RendererPlugin, RenderContext } from '../plugin'
-
-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/scene/createScene.ts

@@ -1,121 +0,0 @@
-/**
- * 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, 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,
-  }
-}

package/src/scene/layerRegistry.ts

@@ -1,115 +0,0 @@
-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/scene/types.ts

@@ -1,148 +0,0 @@
-/**
- * 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 '../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
-}