0010 — Overlay geometry rendering via indicator draw callbacks
Status: Accepted Date: 2026-11-04
Context and Problem Statement
Section titled “Context and Problem Statement”ADR-0007 put
fills, hbars and divlines on the format=series wire. The web
frontend ignored them and logged a console.debug placeholder instead.
The result was that Bollinger/Keltner bands had no fill, Ichimoku had no
cloud, and volume-profile indicators were skipped completely, because they
emit no lines or histogram. Cipher B divergences were also missing. All
of these are part of the TradingView look the frontend aims for
(ADR-0006).
klinecharts 9 has no figure type for a band between two series, for bars anchored to the pane edge, or for a segment between two arbitrary bars. We had to choose where this geometry is drawn and how it stays in sync with pan, zoom and y-axis rescale.
Decision Drivers
Section titled “Decision Drivers”- Geometry must move with the chart: pan, zoom, pane resize and y-axis rescale, with no separate synchronization code.
- Keep ADR-0003’s rule that all indicator math stays on the server. The browser only maps payload values to pixels.
- The geometry maths (gaps, crossings, clipping, edge anchoring) must be testable without a browser.
Chart.tsxchanges stay small, because other work touches the same file.
Considered Options
Section titled “Considered Options”DOM / separate canvas overlay on top of the chart. Full control, but it has to subscribe to every klinecharts scroll, zoom and resize event and repeat the axis transforms. It also falls behind by a frame during interaction. Rejected.
klinecharts overlays (registerOverlay + createOverlay). Overlays
are meant for user drawings anchored to points. One overlay per
fill polygon, profile row or divergence segment would mean hundreds of
objects to create and remove on every payload. Overlays can also be
selected and dragged, which these shapes must not be. Rejected.
Custom figures (registerFigure) emitted per bar from calc.
Figures are drawn bar by bar, so a continuous polygon or a pane-anchored
bar does not fit that model. Rejected.
draw callback on the generic chartgen indicator template. The
template’s draw callback runs on every frame with the live xAxis,
yAxis, visibleRange and pane bounding, and reads the indicator’s
geometry from a store that Chart.tsx keeps. Chosen.
Decision Outcome
Section titled “Decision Outcome”Chosen option: indicator draw callbacks plus a pure geometry
module.
-
web/src/components/geometry.tshas no DOM or klinecharts dependency. It turns payload channels and a{ x(index), y(value) }mapper into pixel primitives:- fill polygons, split at
nullgaps and at crossings, with the crossing point interpolated. Each polygon is clipped to the visible range plus one bar. - hbar rects.
widthandoffsetare fractions of the pane width, measured from the edge thatleftselects. - divline segments, culled when they fall outside the visible range.
The visible range is klinecharts’ own
VisibleRange, which is already clamped to the data. Vitest covers the module (npm test). - fill polygons, split at
-
Data space.
seriesToKLinesdrops bars witht: null, so a payload index is not always a klinecharts data index.payloadToDataIndexbuilds the remap, andtoDataSpacecompacts the fill arrays and remaps divline endpoints once per payload. After that, everything is drawn in data indices. -
Geometry store, not
extendData. The data effect writes each indicator’s data-space geometry into a module-levelMap<regName, SeriesIndicator>beforeapplyNewData. The draw callback reads it from there.applyNewDataalready recalculates and repaints, so a new payload costs nothing extra. Passing the geometry throughoverrideIndicator({ extendData })would re-run calc and layout for every indicator on every payload, and live tail polling sends one every few seconds. -
Paint order and z-order.
ensureRegisteredattachesdraw: drawGeometry(name). The callback paints fills first, withdestination-over, so they land behind the candles already on the pane canvas, as TradingView bands do. The grid is painted afterwards, on top. Withdestination-overeach paint lands beneath the previous one, so fills are iterated in reverse to keep the server’s paint order. The callback then paints hbars and divlines and returnsfalse, so klinecharts still draws the line and bar figures.Dependency: this relies on nothing opaque being painted on the pane canvas before the indicator’s
draw. klinecharts 9 paints no canvas background, and the chart background comes from CSS. If a future change (a klinecharts upgrade or a background style) paints one, every fill would silently disappear beneath it.web/tests/e2e/overlay-geometry.spec.tsguards this. It loads Bollinger Bands and asserts that band-fill pixels are present on the canvas and differ from the page background. With an opaque layer injected, the test fails. -
Y-axis. klinecharts auto-scales over figure values only. Two typeless figures (
range_lo,range_hi) draw nothing, but carryvalueExtentsinto the scale: the min and max of every fill edge per bar, plus the payload’sy_rangefor oscillator panes. That keeps Kalman OB/OS zones and RSI 0–100 on-pane and gives geometry-only panes a real axis. Like klinecharts’minValue/maxValue,y_rangewidens the range and does not clamp it. We did not use those two fields: klinecharts ignores them when no figure has a value, and itsoverrideIndicatorpath writesmaxValuethroughsetMinValue. Overlays ignorey_range, so the price axis is never pinned. -
An indicator that emits only geometry (e.g.
volume_profile) is no longer skipped by the “no lines, no histogram” check. -
Colors. The wire drops server-side colors (ADR-0007), so the geometry module’s theme helpers mirror the Rust palettes per indicator. The Ichimoku cloud is green or red by the sign of Senkou A − Senkou B. Profile rows are tiered POC (widest row), value area (between the VAH and VAL hlines) and the rest. Divergences are classified bull or bear from their slope and pane: in an oscillator a bearish divergence joins lower highs, and in the price pane it joins higher highs. If the wire later carries colors, only these helpers change.
Consequences
Section titled “Consequences”Positive. Every indicator that emits fills, hbars or divlines now renders, and the geometry follows every chart interaction with no extra code. The edge cases (gaps, crossings, single points, clipping, scaling) are unit-tested.
Negative. Geometry is recomputed on every frame (O(visible bars)
per fill). This is negligible at chartgen’s bar counts, but it scales
with zoom-out. The client-side palette can drift from the Rust colors.
The VPVR split_up_down mode cannot be colored up/down, because an
up-only row and a down-only row look identical on the wire.
Neutral. The geometry store is module-level, like klinecharts’ own
indicator registry. That is fine while the app mounts a single Chart,
but a second chart instance would need the store keyed per chart.
More Information
Section titled “More Information”- ADR-0006 — TradingView visual parity
- ADR-0007 — Complete series serialization
- klinecharts 9
IndicatorTemplate.draw/IndicatorDrawParams(web/node_modules/klinecharts/dist/index.d.ts)