KDE renders as a browser-side raster; static export support is deferred
KDE renders via a canvas-to-data-URL raster wrapped in an SVG `<image>`. Static export skips KDE entirely — it is not a member of the stable `ExportFrameSpec` union. Vector output is deferred until raster-vs-static parity rules are deliberately defined.
Context
KDE is a continuous density surface. Rendering options:
- Canvas raster — fast, visually smooth, trivially themed. Does not serialise into static SVG export cleanly (would embed a base64 image in the SVG, which no downstream tool expects).
- SVG contours — vector, exportable, but visually lossy and more expensive to compute.
- Tiled
<rect>grid — a lot of DOM nodes; slow at high resolution.
The static-export pipeline (PDF, server-rendered report) expects declarative SVG primitives. Shipping a KDE export path that embeds raster data would lock the export schema to a specific resolution and theme in ways that are hard to reverse.
Decision
KDE is browser-only in v0.3. It renders via densityToDataURL() inside a
<ChartDensitySurfaceImage> wrapper. The stable ExportFrameSpec union
does not include KDE. Documentation and the /kde demo page mark this
explicitly. Consumers integrating static export drop KDE from their
pipeline or substitute Heatmap where a binned surface suffices.
When this changes
A future export packet defines whether KDE exports as (a) vector contours, (b) embedded raster, or (c) adaptive between the two. Until that decision lands, KDE stays out of the export union. The deferral is intentional and documented.
Consequences
- Consumers building static report generators do not get KDE surfaces in their output; Heatmap is the available substitute.
- Theme-aware rendering of KDE is fast because the raster is regenerated on theme switch, not diffed.
- Raster resolution (default 100 cells per 100 Campos units) is an implementation detail, not a stable public prop — will harden once export rules are defined.