react-native-livechart 4.8.0 → 4.9.0

package/src/hooks/useThreshold.ts

@@ -1,13 +1,27 @@
-import { vec } from "@shopify/react-native-skia";
+import { vec, type Uniforms } from "@shopify/react-native-skia";
+import { useRef } from "react";
 import { useDerivedValue, type SharedValue } from "react-native-reanimated";
 
 import type { ChartEngineLayout } from "../core/useLiveChartEngine";
 import type { ChartPadding } from "../draw/line";
+import { interpolateAtTime } from "../math/interpolate";
 import {
+  sampleThresholdY,
+  sampleThresholdYAt,
+  THRESHOLD_SAMPLE_COUNT,
   thresholdLineY,
+  thresholdSampleSpanX,
+  thresholdSeriesVisible,
   thresholdSplitPositions,
   thresholdVisible,
 } from "../math/threshold";
+import type { LiveChartPoint } from "../types";
+
+/** A threshold value that is either a single live benchmark or a time-varying series. */
+export type ThresholdValue = SharedValue<number> | LiveChartPoint[];
+
+/** `clipRight` sentinel when the threshold extends to "now" (no forward cutoff). */
+export const THRESHOLD_NO_CLIP = 1e9;
 
 export interface ThresholdGeometry {
   /** Threshold pixel-Y within the canvas, or NaN before layout / degenerate range. */
@@ -21,26 +35,33 @@ export interface ThresholdGeometry {
 }
 
 /**
- * Per-frame screen geometry for the threshold split, shared by the stroke
- * gradient, the profit/loss fill band, and the dashed marker line. Reads the live
- * threshold value + engine Y-range on the UI thread; the math lives in
- * `math/threshold` so it stays unit-testable without Reanimated.
+ * Per-frame screen geometry for the **constant** threshold split (a single
+ * `SharedValue<number>` benchmark), shared by the stroke gradient, the
+ * profit/loss fill band, and the dashed marker line. Reads the live threshold
+ * value + engine Y-range on the UI thread; the math lives in `math/threshold` so
+ * it stays unit-testable without Reanimated.
+ *
+ * When the threshold is a time-varying series this geometry is unused — the
+ * worklets short-circuit to a NaN `lineY` (→ off-screen, solid-above fallback)
+ * and {@link useThresholdSeries} drives the render instead.
  */
 export function useThreshold(
   engine: ChartEngineLayout,
   padding: ChartPadding,
-  value: SharedValue<number>,
+  value: ThresholdValue,
 ): ThresholdGeometry {
-  const lineY = useDerivedValue(() =>
-    thresholdLineY(
+  const lineY = useDerivedValue(() => {
+    // Series thresholds are handled by `useThresholdSeries`; bail cheaply here.
+    if (Array.isArray(value)) return NaN;
+    return thresholdLineY(
       value.get(),
       engine.displayMin.get(),
       engine.displayMax.get(),
       engine.canvasHeight.get(),
       padding.top,
       padding.bottom,
-    ),
-  );
+    );
+  });
 
   const visible = useDerivedValue(() =>
     thresholdVisible(
@@ -61,3 +82,239 @@ export function useThreshold(
 
   return { lineY, visible, gradientEnd, splitPositions };
 }
+
+export interface ThresholdSeriesGeometry {
+  /** Marker-line polyline in screen space `[x, y, …]`, projected from `samples`
+   *  (so it aligns exactly with the band edge + stroke split) and pinned to the
+   *  plot's left edge and to `min(plot right, clipRightX)`. */
+  screenPts: SharedValue<number[]>;
+  /** `THRESHOLD_SAMPLE_COUNT` threshold pixel-Y values on the time-anchored
+   *  sample grid — the split shader's `samples[]`, and the bottom edge of the
+   *  profit/loss band. Their pixel-X span is `thresholdSampleSpanX(...)`, which
+   *  glides with the window (NOT the static plot edges). */
+  samples: SharedValue<number[]>;
+  /** Whether any of the polyline is on-screen (drives marker-line opacity). */
+  visible: SharedValue<boolean>;
+  /** Threshold value at `now` (flat-extended past the last point) — the badge label. */
+  currentValue: SharedValue<number>;
+  /** Pixel-Y of `currentValue` — anchors the badge. */
+  currentLineY: SharedValue<number>;
+  /** Whether the badge should show: `currentLineY` on-plot AND, with
+   *  `extendToNow` off, "now" not past the series' last point. (`visible` can be
+   *  true for the polyline while the value-at-now sits outside the plot; the
+   *  badge must not draw into the gutters then.) */
+  currentVisible: SharedValue<boolean>;
+  /** Pixel-X where the threshold ends: the last point's X with `extendToNow`
+   *  off, else {@link THRESHOLD_NO_CLIP}. The shader paints its plain
+   *  `restColor` right of it; the marker polyline stops there. */
+  clipRightX: SharedValue<number>;
+}
+
+/** Stable empties so the constant-mode short-circuit returns a churn-free reference. */
+const EMPTY_PTS: number[] = [];
+const EMPTY_SAMPLES: number[] = new Array(THRESHOLD_SAMPLE_COUNT).fill(0);
+
+/**
+ * Per-frame screen geometry for a **time-varying** threshold — a plain
+ * `LiveChartPoint[]` `value` or a live `SharedValue<LiveChartPoint[]>` `series`
+ * (which wins when both are given): the screen polyline (marker line +
+ * fill-band bottom), the shader's pixel-Y `samples[]`, the current value/anchor
+ * for the badge, and the `extendToNow` cutoff X. The array buffers ping-pong
+ * (Reanimated only re-notifies subscribers when the returned reference
+ * changes). When the threshold is a constant `SharedValue<number>` every
+ * worklet short-circuits cheaply and {@link useThreshold} drives the render
+ * instead.
+ */
+export function useThresholdSeries(
+  engine: ChartEngineLayout,
+  padding: ChartPadding,
+  value: ThresholdValue,
+  series: SharedValue<LiveChartPoint[]> | null = null,
+  extendToNow = true,
+): ThresholdSeriesGeometry {
+  const cacheRef = useRef<{
+    ptsA: number[];
+    ptsB: number[];
+    ptsTick: boolean;
+    sampA: number[];
+    sampB: number[];
+    sampTick: boolean;
+  } | null>(null);
+  if (cacheRef.current === null) {
+    cacheRef.current = {
+      ptsA: [],
+      ptsB: [],
+      ptsTick: false,
+      sampA: [],
+      sampB: [],
+      sampTick: false,
+    };
+  }
+
+  // Per-worklet inline: the live SharedValue form wins, then the plain-array
+  // form; null in constant / no-threshold mode. Inlined (not a shared helper)
+  // so `series` sits directly in each worklet's closure and Reanimated tracks
+  // it as a mapper input.
+  const samples = useDerivedValue(() => {
+    const pts = series ? series.get() : Array.isArray(value) ? value : null;
+    if (pts === null) return EMPTY_SAMPLES;
+    const cache = cacheRef.current!;
+    cache.sampTick = !cache.sampTick;
+    const buf = cache.sampTick ? cache.sampA : cache.sampB;
+    return sampleThresholdY(
+      pts,
+      engine.timestamp.get(),
+      engine.displayWindow.get(),
+      engine.displayMin.get(),
+      engine.displayMax.get(),
+      engine.canvasHeight.get(),
+      padding.top,
+      padding.bottom,
+      THRESHOLD_SAMPLE_COUNT,
+      buf,
+    );
+  });
+
+  const clipRightX = useDerivedValue(() => {
+    if (extendToNow) return THRESHOLD_NO_CLIP;
+    const pts = series ? series.get() : Array.isArray(value) ? value : null;
+    if (pts === null || pts.length === 0) return THRESHOLD_NO_CLIP;
+    const win = engine.displayWindow.get();
+    const plotLeft = padding.left;
+    const plotRight = engine.canvasWidth.get() - padding.right;
+    if (!(win > 0) || plotRight <= plotLeft) return THRESHOLD_NO_CLIP;
+    const winStart = engine.timestamp.get() - win;
+    const lastT = pts[pts.length - 1].time;
+    return plotLeft + ((lastT - winStart) / win) * (plotRight - plotLeft);
+  });
+
+  // Marker-line polyline projected from the SAME `samples` the band + shader read
+  // (the time-anchored, gliding grid). Tracing the exact threshold vertices
+  // instead would put the marker a fraction of a sample off the band/stroke
+  // split — the "gradient lagging the line" — so the marker, band edge and
+  // stroke colour all share one source of truth here. The grid overhangs the
+  // plot, so the ends are pinned to the exact plot edges via interpolation —
+  // which also keeps the dash pattern's anchor (the path start) fixed while the
+  // geometry glides. With `extendToNow` off the right end pins to the
+  // threshold's end X instead.
+  const screenPts = useDerivedValue(() => {
+    const pts = series ? series.get() : Array.isArray(value) ? value : null;
+    if (pts === null || pts.length === 0) return EMPTY_PTS;
+    const s = samples.get();
+    const n = s.length;
+    if (n < 2) return EMPTY_PTS;
+    const plotLeft = padding.left;
+    const plotRight = engine.canvasWidth.get() - padding.right;
+    const endX = Math.min(plotRight, clipRightX.get());
+    if (endX <= plotLeft) return EMPTY_PTS;
+    const cache = cacheRef.current!;
+    cache.ptsTick = !cache.ptsTick;
+    const buf = cache.ptsTick ? cache.ptsA : cache.ptsB;
+    buf.length = 0;
+    const [x0, x1] = thresholdSampleSpanX(
+      engine.timestamp.get(),
+      engine.displayWindow.get(),
+      plotLeft,
+      plotRight,
+      n,
+    );
+    buf.push(plotLeft, sampleThresholdYAt(s, x0, x1, plotLeft));
+    const step = (x1 - x0) / (n - 1);
+    for (let i = 0; i < n; i++) {
+      const sx = x0 + step * i;
+      if (sx > plotLeft && sx < endX) buf.push(sx, s[i]);
+    }
+    buf.push(endX, sampleThresholdYAt(s, x0, x1, endX));
+    return buf;
+  });
+
+  const visible = useDerivedValue(() => {
+    if (series === null && !Array.isArray(value)) return false;
+    return thresholdSeriesVisible(
+      screenPts.get(),
+      engine.canvasHeight.get(),
+      padding.top,
+      padding.bottom,
+    );
+  });
+
+  const currentValue = useDerivedValue(() => {
+    const pts = series ? series.get() : Array.isArray(value) ? value : null;
+    if (pts === null) return NaN;
+    return interpolateAtTime(pts, engine.timestamp.get()) ?? NaN;
+  });
+
+  const currentLineY = useDerivedValue(() =>
+    thresholdLineY(
+      currentValue.get(),
+      engine.displayMin.get(),
+      engine.displayMax.get(),
+      engine.canvasHeight.get(),
+      padding.top,
+      padding.bottom,
+    ),
+  );
+
+  const currentVisible = useDerivedValue(() => {
+    if (!extendToNow) {
+      // The threshold ends at its last point — no badge past it.
+      const pts = series ? series.get() : Array.isArray(value) ? value : null;
+      if (pts === null || pts.length === 0) return false;
+      if (pts[pts.length - 1].time < engine.timestamp.get()) return false;
+    }
+    return thresholdVisible(
+      currentLineY.get(),
+      engine.canvasHeight.get(),
+      padding.top,
+      padding.bottom,
+    );
+  });
+
+  return {
+    screenPts,
+    samples,
+    visible,
+    currentValue,
+    currentLineY,
+    currentVisible,
+    clipRightX,
+  };
+}
+
+/**
+ * Pack a series geometry + a color set into the {@link ThresholdSplitShader}'s
+ * uniforms (one `SharedValue` per paint — stroke vs. the alpha-reduced fill band).
+ * The object is rebuilt each frame so the shader re-paints as `samples` advance;
+ * `sampleLeft`/`sampleRight` are the gliding pixel-X span of the sample grid and
+ * `clipRight`/`restColor` implement the `extendToNow: false` cutoff (plain line
+ * color for the stroke, transparent for the band).
+ */
+export function useThresholdSplitUniforms(
+  samples: SharedValue<number[]>,
+  engine: ChartEngineLayout,
+  padding: ChartPadding,
+  aboveColor: number[],
+  belowColor: number[],
+  restColor: number[],
+  clipRightX: SharedValue<number>,
+): SharedValue<Uniforms> {
+  return useDerivedValue<Uniforms>(() => {
+    const s = samples.get();
+    const [x0, x1] = thresholdSampleSpanX(
+      engine.timestamp.get(),
+      engine.displayWindow.get(),
+      padding.left,
+      engine.canvasWidth.get() - padding.right,
+      s.length,
+    );
+    return {
+      sampleLeft: x0,
+      sampleRight: x1,
+      clipRight: clipRightX.get(),
+      aboveColor,
+      belowColor,
+      restColor,
+      samples: s,
+    };
+  });
+}

package/src/math/threshold.ts

@@ -4,6 +4,19 @@
  * wires the live SharedValues into them.
  */
 
+import { interpolateAtTime } from "./interpolate";
+import type { LiveChartPoint } from "../types";
+
+/**
+ * Sample resolution for the time-varying split shader: the threshold series is
+ * projected to this many evenly-spaced pixel-Y values across the plot, which the
+ * shader linearly interpolates between. ~one sample per 6px on a phone plot —
+ * fine enough that the line's crossing point is coloured accurately. The shader
+ * walks these in an unrolled loop (`THRESHOLD_SAMPLE_COUNT - 1` iterations), so
+ * keep it modest to stay within SkSL's unroll limits.
+ */
+export const THRESHOLD_SAMPLE_COUNT = 64;
+
 /**
  * Pixel Y of a threshold value within the plot. Mirrors the line path's value→Y
  * mapping in `buildLinePoints` (`top + (max - v) / range * chartH`). Returns NaN
@@ -57,3 +70,240 @@ export function thresholdSplitPositions(
   else if (t > 1) t = 1;
   return [0, t, t, 1];
 }
+
+/* ------------------------------------------------------------------------- *
+ * Time-varying threshold (a `LiveChartPoint[]` series, not a constant value)
+ * ------------------------------------------------------------------------- */
+
+/**
+ * Spacing of the threshold sample grid, in seconds. `count - 2` (not `count - 1`)
+ * so the `count` samples cover the window plus up to one spacing of overhang on
+ * each side — the grid is anchored to absolute time (see
+ * {@link thresholdSampleStart}) and must keep covering the plot as it glides.
+ */
+export function thresholdSampleStep(windowSecs: number, count: number): number {
+  "worklet";
+  return windowSecs / Math.max(count - 2, 1);
+}
+
+/**
+ * First sample time of the grid: the greatest multiple of the spacing at or
+ * before the window start. Anchoring sample TIMES to an absolute grid (instead
+ * of evenly across the current window) keeps each sample's *value* stable while
+ * the window scrolls — the grid's *pixel* positions glide left each frame, so a
+ * step riser translates fluidly instead of popping from one fixed sample bin to
+ * the next (~plotWidth/63 px at a time) while the data line glides beside it.
+ */
+export function thresholdSampleStart(
+  now: number,
+  windowSecs: number,
+  count: number,
+): number {
+  "worklet";
+  const dt = thresholdSampleStep(windowSecs, count);
+  return Math.floor((now - windowSecs) / dt) * dt;
+}
+
+/**
+ * Pixel-X endpoints `[x0, x1]` of the sample grid for the current frame — the
+ * span the shader / band / marker interpolate {@link sampleThresholdY}'s output
+ * across. Overhangs `[plotLeft, plotRight]` by up to one spacing per side and
+ * glides with the window. Falls back to the plot edges when the window or plot
+ * is degenerate (matching `sampleThresholdY`'s degenerate fill).
+ */
+export function thresholdSampleSpanX(
+  now: number,
+  windowSecs: number,
+  plotLeft: number,
+  plotRight: number,
+  count: number,
+): [number, number] {
+  "worklet";
+  const span = plotRight - plotLeft;
+  if (!(windowSecs > 0) || span <= 0 || count < 2) return [plotLeft, plotRight];
+  const dt = thresholdSampleStep(windowSecs, count);
+  const t0 = thresholdSampleStart(now, windowSecs, count);
+  const winStart = now - windowSecs;
+  const xScale = span / windowSecs;
+  const x0 = plotLeft + (t0 - winStart) * xScale;
+  return [x0, x0 + (count - 1) * dt * xScale];
+}
+
+/**
+ * Sample the threshold series to `count` pixel-Y values on the time-anchored
+ * grid ({@link thresholdSampleStart}/{@link thresholdSampleSpanX}), for the
+ * split shader's `samples[]` uniform (it linearly interpolates between them and
+ * compares each fragment's Y). Clamps to the series' first/last value outside
+ * its range (flat extension). When the canvas or range is degenerate — or a
+ * series value is NaN — it fills with a far-below Y, so the shader paints the
+ * above-color everywhere — matching the constant split's pre-layout fallback
+ * (`thresholdSplitPositions` → solid above).
+ */
+export function sampleThresholdY(
+  points: LiveChartPoint[],
+  now: number,
+  windowSecs: number,
+  displayMin: number,
+  displayMax: number,
+  canvasHeight: number,
+  paddingTop: number,
+  paddingBottom: number,
+  count: number,
+  out?: number[],
+): number[] {
+  "worklet";
+  const arr: number[] = out ?? [];
+  if (out) out.length = 0;
+  const chartH = canvasHeight - paddingTop - paddingBottom;
+  const valRange = displayMax - displayMin;
+  // A Y safely below every fragment → shader compares "above" everywhere.
+  // (canvasHeight * 2 stays below the canvas even when chartH is negative.)
+  const farBelow = canvasHeight > 0 ? canvasHeight * 2 : 1e6;
+  // !(valRange > 0) also catches a NaN display range.
+  if (points.length === 0 || !(valRange > 0) || chartH <= 0 || windowSecs <= 0) {
+    for (let i = 0; i < count; i++) arr.push(farBelow);
+    return arr;
+  }
+  const dt = thresholdSampleStep(windowSecs, count);
+  const t0 = thresholdSampleStart(now, windowSecs, count);
+  for (let i = 0; i < count; i++) {
+    const v = interpolateAtTime(points, t0 + i * dt)!;
+    const y = thresholdLineY(
+      v,
+      displayMin,
+      displayMax,
+      canvasHeight,
+      paddingTop,
+      paddingBottom,
+    );
+    // A NaN series value degrades per-sample to the solid-above fallback
+    // instead of leaking NaN into the shader uniform / band vertices.
+    arr.push(Number.isFinite(y) ? y : farBelow);
+  }
+  return arr;
+}
+
+/**
+ * Evaluate the threshold at pixel-x `x` from the evenly-spaced `samples[]` (the
+ * same array the split shader reads), linearly interpolated across the sample
+ * span `[spanLeft, spanRight]` (see {@link thresholdSampleSpanX}) and clamped
+ * outside it. The profit/loss band's bottom edge and the marker polyline's
+ * plot-edge pins are built from this so their geometry matches the shader
+ * **exactly** — a sharp step in the threshold becomes the same ~1-sample ramp in
+ * all of them, so no green/red sliver bleeds through at a step riser.
+ */
+export function sampleThresholdYAt(
+  samples: number[],
+  spanLeft: number,
+  spanRight: number,
+  x: number,
+): number {
+  "worklet";
+  const count = samples.length;
+  if (count === 0) return 0;
+  if (count === 1) return samples[0];
+  const span = spanRight - spanLeft;
+  if (span <= 0) return samples[0];
+  const u = ((x - spanLeft) / span) * (count - 1);
+  if (u <= 0) return samples[0];
+  if (u >= count - 1) return samples[count - 1];
+  const i = Math.floor(u);
+  return samples[i] + (samples[i + 1] - samples[i]) * (u - i);
+}
+
+/**
+ * Dash-phase (px) for the series marker line so its dash pattern travels WITH
+ * the scrolling threshold instead of staying screen-fixed. The marker path
+ * starts at the static plot edge, so without a moving phase the dashes sit
+ * still while the staircase glides left — reading as the dots "marching" right
+ * along the line. Advancing the phase at exactly the content scroll speed
+ * (`span/windowSecs` px per second, mod the dash cycle) pins the pattern to the
+ * geometry. Returns 0 for a degenerate window/plot/cycle (static dashes).
+ */
+export function thresholdDashPhase(
+  now: number,
+  windowSecs: number,
+  plotLeft: number,
+  plotRight: number,
+  dashCycle: number,
+): number {
+  "worklet";
+  const span = plotRight - plotLeft;
+  if (!(windowSecs > 0) || span <= 0 || !(dashCycle > 0)) return 0;
+  return ((now * span) / windowSecs) % dashCycle;
+}
+
+/**
+ * Min/max of a threshold series over the visible window `[now - windowSecs,
+ * now]` — the values folded into the engine's Y-range fit when
+ * `threshold.includeInRange` is set (like reference-line values). Uses the
+ * clamped window-edge values plus every interior point; with `extendToNow` off,
+ * the window end clamps to the series' last point (nothing projects forward).
+ * Writes `[min, max]` into `out` and returns it, or returns null when the
+ * series is empty / entirely outside the effective window / non-finite.
+ */
+export function thresholdRangeMinMax(
+  points: LiveChartPoint[],
+  now: number,
+  windowSecs: number,
+  extendToNow: boolean,
+  out: [number, number],
+): [number, number] | null {
+  "worklet";
+  if (points.length === 0 || !(windowSecs > 0)) return null;
+  const tStart = now - windowSecs;
+  let tEnd = now;
+  if (!extendToNow) {
+    const lastT = points[points.length - 1].time;
+    if (lastT < tStart) return null;
+    if (lastT < tEnd) tEnd = lastT;
+  }
+  let mn = interpolateAtTime(points, tStart)!;
+  let mx = mn;
+  const vEnd = interpolateAtTime(points, tEnd)!;
+  if (vEnd < mn) mn = vEnd;
+  else if (vEnd > mx) mx = vEnd;
+  for (let i = 0; i < points.length; i++) {
+    const t = points[i].time;
+    if (t <= tStart) continue;
+    if (t >= tEnd) break;
+    const v = points[i].value;
+    if (v < mn) mn = v;
+    else if (v > mx) mx = v;
+  }
+  if (!Number.isFinite(mn) || !Number.isFinite(mx)) return null;
+  out[0] = mn;
+  out[1] = mx;
+  return out;
+}
+
+/**
+ * True when any part of a threshold screen polyline crosses the plot: a vertex
+ * inside it, or a segment whose endpoints straddle it (a step riser can jump
+ * from below the bottom edge to above the top edge between two samples without
+ * landing a vertex inside).
+ */
+export function thresholdSeriesVisible(
+  screenPts: number[],
+  canvasHeight: number,
+  paddingTop: number,
+  paddingBottom: number,
+): boolean {
+  "worklet";
+  if (canvasHeight <= 0) return false;
+  let prev = NaN;
+  for (let i = 1; i < screenPts.length; i += 2) {
+    const y = screenPts[i];
+    if (!Number.isFinite(y)) {
+      prev = NaN;
+      continue;
+    }
+    if (thresholdVisible(y, canvasHeight, paddingTop, paddingBottom)) return true;
+    // Both endpoints are outside the plot band — on opposite sides means the
+    // segment crosses straight through it.
+    if (Number.isFinite(prev) && prev < paddingTop !== y < paddingTop)
+      return true;
+    prev = y;
+  }
+  return false;
+}

package/src/types.ts

@@ -431,32 +431,77 @@ export interface LineConfig {
 }
 
 /**
- * Color the line above vs. below a live threshold value — green above, red below
- * by default. The threshold is **always** a `SharedValue` so it can track a live
- * benchmark (break-even / average cost, VWAP, previous close, a peg) on the UI
- * thread without re-rendering. Drives a hard-split line stroke and, optionally, a
- * tinted profit/loss fill band and a dashed marker line at the threshold.
+ * Color the line above vs. below a threshold — green above, red below by
+ * default. The threshold is either a single **live benchmark** (a
+ * `SharedValue<number>` that tracks on the UI thread without re-rendering) or a
+ * **time-varying series** (a `LiveChartPoint[]` the split follows point-for-point
+ * — a stepped break-even, a historical VWAP). Drives a hard-split line stroke
+ * and, optionally, a tinted profit/loss fill band and a marker line at the
+ * threshold.
  *
  * The split stroke supersedes `LineConfig.color`/`colors` and segment recoloring
  * for the main line while a threshold is set.
  */
 export interface ThresholdConfig {
   /**
-   * The split value, in Y-axis (price) units. A `SharedValue` — update it with
-   * `.set()` and the split tracks live on the UI thread (break-even, VWAP, the
-   * previous close, a peg, …).
+   * The split value, in Y-axis (price) units. Two forms:
+   *
+   * - **`SharedValue<number>`** — a single live benchmark. Update it with
+   *   `.set()` and the horizontal split tracks on the UI thread without
+   *   re-rendering (break-even / average cost, VWAP, the previous close, a peg).
+   * - **`LiveChartPoint[]`** — a *time-varying* threshold (e.g. a historical
+   *   break-even that steps up as you average in). The stroke split, fill band
+   *   and marker line follow the series point-for-point. The series clamps to its
+   *   first/last value outside its own time range, so a threshold whose last
+   *   point sits behind the live edge extends as a flat line to "now" (see
+   *   {@link extendToNow}). Flows in on re-render — pass a stable (memoized)
+   *   array and reserve it for thresholds that change occasionally; for a
+   *   threshold series that updates live, use {@link series} instead.
+   *
+   * Provide `value` or {@link series} (not both) — `series` wins if both are set.
+   */
+  value?: SharedValue<number> | LiveChartPoint[];
+  /**
+   * A **live** time-varying threshold: like the `LiveChartPoint[]` form of
+   * {@link value}, but a `SharedValue` — update it with `.set()`/`.modify()` and
+   * the split tracks on the UI thread without re-rendering (a VWAP that updates
+   * every tick, mirroring how the chart's own `data` prop works). Points must be
+   * sorted by `time`, like `data`. Takes precedence over {@link value}.
+   */
+  series?: SharedValue<LiveChartPoint[]>;
+  /**
+   * Stroke color where the line is at/above `value`. Default: palette up-green
+   * (`candleUp`). With a series `value`, use hex (`#rgb`/`#rrggbb`), `rgb()` or
+   * `rgba()` — the split shader parses these; named CSS colors and 8-digit hex
+   * are only supported by the constant form.
    */
-  value: SharedValue<number>;
-  /** Stroke color where the line is at/above `value`. Default: palette up-green (`candleUp`). */
   aboveColor?: string;
-  /** Stroke color where the line is below `value`. Default: palette down-red (`candleDown`). */
+  /** Stroke color where the line is below `value`. Default: palette down-red
+   *  (`candleDown`). Same format support as `aboveColor`. */
   belowColor?: string;
   /**
-   * Tint the area between the line and `value` (the profit/loss band) toward the
-   * above/below colors. Independent of the baseline `gradient` fill — set
-   * `gradient={false}` for the threshold band alone. Default `false`.
+   * Tint the area between the line and the threshold (the profit/loss band)
+   * toward the above/below colors. Independent of the baseline `gradient` fill —
+   * set `gradient={false}` for the threshold band alone. `true` → default band
+   * opacity (`0.16`), or an object to tune it. Default `false`.
    */
-  fill?: boolean;
+  fill?: boolean | ThresholdFillConfig;
+  /**
+   * Fold the threshold into the Y-axis range fit — like reference lines — so a
+   * benchmark outside the data's own range stays on-plot instead of rendering
+   * invisibly (marker off-plot, whole line one color). For a series, the values
+   * visible in the current window count (respecting {@link extendToNow}).
+   * Default `false` (range fits the data only).
+   */
+  includeInRange?: boolean;
+  /**
+   * Series forms only: extend the threshold **flat past its last point to
+   * "now"**, carrying the last known benchmark forward. Set `false` for a
+   * benchmark that must not project into the future (a closed session's VWAP) —
+   * right of the last point the stroke keeps its plain line color and the band /
+   * marker / badge end. Default `true`.
+   */
+  extendToNow?: boolean;
   /**
    * Dashed marker line + optional gutter label at the threshold. `true` → a dashed
    * line in the palette reference color; object → styled; omit/`false` → none.
@@ -483,6 +528,16 @@ export interface ThresholdLineConfig {
   strokeWidth?: number;
   /** Append the formatted threshold value to the label. Default `false`. */
   showValue?: boolean;
+  /** Label text color. Defaults to {@link color}, then palette `refLabel` —
+   *  mirroring `ReferenceLine.labelColor`. */
+  labelColor?: string;
+}
+
+/** Object form of {@link ThresholdConfig.fill} — band tuning. */
+export interface ThresholdFillConfig {
+  /** Band fill opacity (0–1), applied to the above/below colors. Multiplies an
+   *  `rgba()` color's own alpha. Default `0.16` (matching reference-line bands). */
+  opacity?: number;
 }
 
 /** Area fill gradient beneath the chart line. */