Throw {@link ChartDisposedError} when `disposed` is true.
(disposed: boolean, label: string) => voidMerge consecutive triangle primitives that share color and z-index. Line strips are **not** merged: concatenating strips would invent a segment between series. Each line series is already one draw of N points. Rects stay separate because they expand to a strip at draw time.
(nodes: readonly PrimitiveNode[]) => PrimitiveNode[]An operation was attempted on a chart, engine, or renderer that has already been disposed.
class ChartDisposedErrorAccepted color inputs at public APIs. - {@link Rgba} object - `[r, g, b]` or `[r, g, b, a]` in 0–1 - CSS hex (`#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`) - `rgb()` / `rgba()` functions - a small set of named colors
type ColorInput = ColorInputCompile a scene snapshot into clear + primitive passes.
(background: Rgba, nodes: readonly SceneNode[]) => RenderGraphCreate an element. Uses `document` when present; otherwise a memory node so unit tests do not require jsdom.
(tag: string) => HTMLElementCreate an uninitialized engine. Call {@link Engine.initialize} before drawing.
(options: EngineOptions) => EngineCreate a mutable group node.
(options?: CreateGroupOptions) => GroupNodeOptions for {@link createGroup}.
interface CreateGroupOptions| id? | string | undefined |
| children? | readonly SceneNode[] | undefined |
| visible? | boolean | undefined |
| zIndex? | number | undefined |
Attach a canvas and overlay to a container. Works in a real DOM and in the Phase 1 memory-element test harness.
(options: { readonly container: HTMLElement | string; readonly canvas?: HTMLCanvasElement; readonly ariaLabel?: string; }) => HostSurfaceAllocate a unique scene-node id.
(prefix?: string) => stringCreate a primitive scene node in clip space.
(options: CreatePrimitiveOptions) => PrimitiveNodeOptions for {@link createPrimitive}.
interface CreatePrimitiveOptions| primitive | PrimitiveKind |
| vertices | ArrayLike<number> |
| color | ColorInput |
| id? | string | undefined |
| visible? | boolean | undefined |
| zIndex? | number | undefined |
| texture? | HeatmapTexture | undefined |
| mesh? | Mesh3DData | undefined |
Create and initialize a renderer for `canvas`. Core path is always WebGL2: hardware GPU when present, software WebGL2 when it is not. Canvas is opt-in (`force: "canvas"` or an explicit prefer list). WebGPU is skipped unless ready.
(canvas: RenderTarget, prefs?: RendererPrefs) => Promise<Renderer>Create an empty resource manager.
() => ResourceManagerCreate an empty scene with the default dark background.
() => SceneDefault dark-theme clear color (graphite).
RgbaDefault light-theme clear color.
RgbaDefault try order. WebGPU is omitted until the milestone is ready (see `@rekhly/renderer-webgpu`).
readonly RendererKind[]Owns the scene, renderer, frame loop, and resource lifetime. Frame-loop ownership lives here — not on individual charts. Charts request frames via {@link Engine.requestFrame}; they do not call `requestAnimationFrame` themselves.
interface Engine| scene | Scene |
| renderer | Renderer | undefined |
| resources | ResourceManager |
| disposed | boolean |
| initialized | boolean |
| viewport | ViewportSize |
| cssSize | ViewportSize |
| pixelRatio | number |
| initialize | () => Promise<void> |
| resize | (width: number, height: number) => void |
| requestFrame | () => void |
| renderNow | () => void |
| start | () => void |
| stop | () => void |
| dispose | () => void |
| on | <K extends keyof EngineEventMap>(event: K, handler: (payload: EngineEventMap[K]) => void) => () => void |
Events emitted by {@link Engine}.
interface EngineEventMap| resize | { readonly css: ViewportSize; readonly viewport: ViewportSize; } |
| dispose | undefined |
| frame | { readonly timestamp: number; } |
interface EngineOptions| canvas | RenderTarget |
| renderer? | RendererPrefs | undefined |
| autoResize? | boolean | undefined |
| pixelRatio? | number | undefined |
An export operation failed.
class ExportErrorNested scene group. Children are flattened when the render graph compiles.
interface GroupNode| kind | "group" |
| children | readonly SceneNode[] |
| id | string |
| visible | boolean |
| zIndex | number |
RGBA8 heatmap texture. Partial updates carry a dirty rectangle so the renderer can `texSubImage2D` instead of re-uploading the whole matrix.
interface HeatmapTexture| width | number |
| height | number |
| pixels | Uint8Array<ArrayBufferLike> |
| interpolation | "nearest" | "bilinear" |
| dirty? | { readonly x: number; readonly y: number; readonly width: number; readonly height: number; readonly pixels: Uint8Array; } | undefined |
Chart host: canvas plus a DOM overlay for labels, cursor, and tooltip.
interface HostSurface| container | HTMLElement |
| canvas | HTMLCanvasElement |
| overlay | HTMLElement |
| createdCanvas | boolean |
| dispose | () => void |
Input data failed validation (wrong arity, NaN, empty required buffer).
class InvalidDataErrorLicense validation failed. Secrets must never be hardcoded; see env `REKHLY_LICENSE`.
class LicenseErrorWorld-space mesh drawn with an MVP matrix. The renderer enables depth testing and optional Lambert lighting. Software backends project on CPU.
interface Mesh3DData| positions | Float32Array<ArrayBufferLike> |
| normals? | Float32Array<ArrayBufferLike> | undefined |
| colors? | Float32Array<ArrayBufferLike> | undefined |
| mvp | Float32Array<ArrayBufferLike> |
| mode | "triangles" | "lines" | "line-strip" | "points" |
| pointSize? | number | undefined |
| clipPlane? | readonly [number, number, number, number] | undefined |
| lit? | boolean | undefined |
Stable identifier for a scene node.
type NodeId = stringValidate and copy interleaved clip-space vertices.
(kind: PrimitiveKind, vertices: ArrayLike<number>) => Float32ArrayNormalize a public color input into clamped RGBA 0–1.
(input: ColorInput) => RgbaBuilt-in drawable kinds for Phase 1 smoke rendering. Chart series attach as additional node kinds in later phases; they still compile down to the same render-graph passes.
type PrimitiveKind = PrimitiveKindinterface PrimitiveNode| kind | "primitive" |
| primitive | PrimitiveKind |
| color | Rgba |
| vertices | Float32Array<ArrayBufferLike> |
| texture? | HeatmapTexture | undefined |
| mesh? | Mesh3DData | undefined |
| clipRect? | readonly [number, number, number, number] | undefined |
| id | string |
| visible | boolean |
| zIndex | number |
Default engine implementation. Owns the frame loop.
class RekhlyEngineBase typed error. All public Rekhly failures extend this class so callers can branch on {@link RekhlyError.code} without string-matching `name`.
class RekhlyErrorStable error codes for typed Rekhly failures (PRD §74).
type RekhlyErrorCode = RekhlyErrorCodeReference-free create/cache/dispose table. Dispose functions must be idempotent. `disposeAll` continues after individual failures and throws a single {@link ResourceError} if any disposer threw.
class RekhlyResourceManagerMutable scene graph with a cached render-graph snapshot.
class RekhlySceneBackend-agnostic renderer contract (PRD §3). Chart and series code must never call WebGL/WebGPU APIs directly. Custom drawing goes through scene primitives or a later plugin API.
interface Renderer| kind | RendererKind |
| device | RendererDevice |
| disposed | boolean |
| viewport | ViewportSize |
| lastFrameStats? | RendererFrameStats | undefined |
| initialize | () => Promise<void> |
| resize | (width: number, height: number) => void |
| render | (scene: Scene) => void |
| dispose | () => void |
Where the WebGL core actually executes. - `gpu` — hardware `webgl2` context - `software` — CPU WebGL2 implementation (no GPU / headless)
type RendererDevice = RendererDeviceMeasured per-frame renderer counters. Values are recorded, never invented.
interface RendererFrameStats| drawCalls | number |
| uploadBytes | number |
| bufferBytes | number |
| vertexCount | number |
Renderer construction or `initialize()` failed for a reason other than a specific backend being unavailable.
class RendererInitializationErrorSupported rendering backends (PRD §3). Preference order when a backend is ready: WebGPU → WebGL2 → Canvas. WebGPU is not production-ready in Phase 1 and is skipped unless forced.
type RendererKind = RendererKindRenderer selection preferences.
interface RendererPrefs| prefer? | readonly RendererKind[] | undefined |
| force? | RendererKind | undefined |
| strict? | boolean | undefined |
| powerPreference? | "default" | "high-performance" | "low-power" | undefined |
| failIfMajorPerformanceCaveat? | boolean | undefined |
| allowSoftware? | boolean | undefined |
Immutable snapshot of work for one frame.
interface RenderGraph| passes | readonly RenderPass[] |
| nodeCount | number |
| primitiveCount | number |
A compiled, backend-agnostic draw unit.
type RenderPass = RenderPassSurface the engine can draw into. OffscreenCanvas is accepted so a later worker/OffscreenCanvas path can reuse the same engine without an API break.
type RenderTarget = RenderTargetResolve a host element from an element or CSS selector.
(container: HTMLElement | string) => HTMLElementA GPU/CPU resource could not be created, compiled, or disposed cleanly.
class ResourceErrorHandle to a cached engine resource. `backendRef` is opaque and must not be used by chart-level code.
interface ResourceHandle| id | string |
| kind | ResourceKind |
| byteSize | number |
| backendRef | unknown |
Resource kinds tracked by the resource manager (PRD §58, §75).
type ResourceKind = ResourceKindCreate/cache/dispose manager for shaders, buffers, textures, and other long-lived objects. Callers must {@link ResourceManager.disposeAll} when the owning renderer or engine is disposed.
interface ResourceManager| register | (handle: ResourceHandle, disposeFn: () => void) => ResourceHandle |
| get | (id: string) => ResourceHandle | undefined |
| dispose | (id: string) => boolean |
| disposeAll | () => void |
| stats | () => ResourceStats |
Aggregate resource accounting. Values are measured, not estimated marketing figures.
interface ResourceStats| count | number |
| byteSize | number |
| byKind | Readonly<Record<ResourceKind, ResourceKindStats>> |
Normalized device-independent color in linear-ish 0–1 RGBA. Values are stored in the 0–1 range. Conversion from CSS hex/rgb happens at the public-API boundary so the render path never parses strings.
interface Rgba| r | number |
| g | number |
| b | number |
| a | number |
Convert RGBA 0–1 to a CSS `rgba()` string for the Canvas fallback.
(color: Rgba) => stringCPU-side scene. The public chart API mutates the scene; renderers only consume {@link Scene.compile}.
interface Scene| background | Rgba |
| nodes | readonly SceneNode[] |
| dirty | boolean |
| add | (node: SceneNode) => SceneNode |
| remove | (id: NodeId) => boolean |
| get | (id: NodeId) => SceneNode | undefined |
| clear | () => void |
| markDirty | () => void |
| compile | () => RenderGraph |
Discriminated scene node union. New chart node kinds are added here without changing the renderer contract.
type SceneNode = SceneNodeA streaming transport failed to connect or dropped unexpectedly.
class StreamConnectionErrorBacking-store size in physical pixels.
interface ViewportSize| width | number |
| height | number |
WebGL2 was requested (or required as fallback) but the environment could not produce a `webgl2` context.
class WebGLUnavailableErrorWebGPU was requested but is unavailable, or is not production-ready in this Rekhly release.
class WebGPUUnavailableErrorGot any questions? I'm happy to help with products, licensing, and examples.