This document is the Phase 1 architecture source for the engine. Planning context lives in docs/ARCHITECTURE_OVERVIEW.md.
Chart (@rekhly/core)
↓
Scene (@rekhly/engine)
↓
Render Graph (@rekhly/engine)
↓
Renderer
├── WebGL2 (@rekhly/renderer-webgl) — **core** (GPU or software WebGL2)
├── WebGPU (@rekhly/renderer-webgpu) — stub; next milestone
└── Canvas (@rekhly/renderer-canvas) — opt-in reduced path only
The public chart API must not call WebGL or WebGPU. Custom drawing is added as scene primitives (and, later, plugins).
The engine owns the frame loop.
engine.requestFrame().requestFrame() coalesces to a single animation frame.renderNow() compiles the scene and calls renderer.render(scene).start() / stop() exist for later animation and streaming loops.requestAnimationFrame, the engine falls back to setTimeout.Charts do not register their own requestAnimationFrame callbacks.
interface Renderer {
initialize(): Promise<void>;
resize(width: number, height: number): void;
render(scene: Scene): void;
dispose(): void;
}
The core is WebGL2. It must run with and without a GPU:
getContext("webgl2") when a GPU/driver is present (device: "gpu").device: "software").Same renderer, shaders, buffers, and scene graph in both modes. Canvas 2D is opt-in (force: "canvas"), not the no-GPU path.
Default prefer is ["webgl2"]. Forcing "webgpu" throws WebGPUUnavailableError until that milestone is ready.
A canvas may only bind one drawing API. Hardware WebGL2 is never probed on a surface that will be used for Canvas 2D.
primitive, group).scene.compile() produces an immutable RenderGraph of passes: 1. clear 2. primitives (visible nodes, flattened groups, sorted by zIndex)
markDirty().[-1, 1] x,y pairs stored in Float32Array.Phase 2 series will attach as additional node kinds and still compile into the same pass model.
Phase 1 draws smoke primitives. The intended hot path (Phase 3) is:
TypedArray → DataBuffer → GPUBuffer → batched draw → shader → framebuffer
Never store millions of points as millions of JavaScript objects.
RekhlyResourceManager is the create/cache/dispose table for buffers, shaders, programs, textures, and VAOs.
dispose(id) and disposeAll() release backend objects.stats() reports measured counts and byte sizes.WebGL2 renderer deletes its program, buffer, and VAO on dispose(), and listens for webglcontextlost / webglcontextrestored.
dispose() on Renderer, Engine, and Chart is idempotent. A second call is a documented safe no-op. After dispose, any other method throws ChartDisposedError.
This is required for React Strict Mode (Phase 9) and defensive application teardown.
types
↑
renderer-webgl / renderer-canvas / renderer-webgpu
↑
engine
↑
core
↑
charts-* / react / nextjs / python (later phases)
Hard rules:
engine and renderers do not depend on React, Next.js, or Python.@rekhly/core does not import renderer packages or WebGL types.| Error | When |
|---|---|
RendererInitializationError |
Backend init failed for a non-availability reason |
WebGLUnavailableError |
No webgl2 context |
WebGPUUnavailableError |
WebGPU requested or used before the milestone is ready |
ChartDisposedError |
Use after dispose() |
ResourceError |
Shader/program/buffer failure |
InvalidDataError |
Bad vertices, colors, or container |
StreamConnectionError |
Reserved (Phase 5) |
LicenseError |
Reserved (env-only secrets) |
ExportError |
Reserved (Phase 13) |
rekhly.chartXY() lives in @rekhly/charts-2d and is re-exported from @rekhly/core.
rekhly.chartXY
→ Engine + HostSurface (canvas + overlay)
→ Linear X/Y axes + CoordinateSpace
→ Series compile to PrimitiveNodes (typed arrays → clip space)
→ Overlay: tick labels, cursor, tooltip
→ @rekhly/interaction: wheel zoom, drag pan, shift-drag rect zoom, double-click fit
Series storage is Float64Array internally (copied from Float32Array / Float64Array / XYPoint[]). Downsampling and GPU batching are Phase 3.
Python talks to the Rekhly runtime over the same versioned chart schema and (optionally) the local WebSocket API. The rekhly package is a native API; it does not wrap JS objects. Tests use an in-process mock. open(live=True) is an explicit lifecycle that must be paired with close().
Documented in packages/renderer-webgpu/README.md. Production WebGPU work is planned with GPU optimization and 3D (Phases 3 and 6).
Got any questions? I'm happy to help with products, licensing, and examples.