feat: add reference line series

[brandtnewlabs]

Summary

• add ReferenceLine.series for historical, time-varying benchmark lines
• render the series over line and candle charts with the existing color, dash, width, label, and range-fitting options
• extend the final value to the live edge by default, with extendToNow: false as an opt-out
• document the API and add a realistic average-cost example to the candlestick demo

Why

Candle charts often need a benchmark that changes over time, such as average entry cost or VWAP. A single horizontal reference value cannot represent those historical changes, while the threshold-split API changes the chart's coloring and fill rather than drawing a neutral annotation.

Verification

• npm run verify — 106 suites passed, 1,600 tests passed, 5 skipped
• React Doctor — 96/100; the only warning is the example app's existing route metadata export
• iOS example app — verified the historical average-cost series renders over live candles, disappears when disabled, and restores when re-enabled

Closes #290

[brandtnewlabs]

• feat: add reference line series #295 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[brandtnewlabs]

Device proof

iOS candlestick example with the historical average-cost reference series enabled, disabled, and restored:

issue-290-reference-series-proof.mp4