react-native-livechart 4.19.0 → 4.21.0

package/src/hooks/useCandleGapPaths.ts

@@ -0,0 +1,88 @@
+import { useDerivedValue, type SharedValue } from "react-native-reanimated";
+import type { ResolvedCandleGapsConfig } from "../core/resolveConfig";
+import type { SingleEngineState } from "../core/useLiveChartEngine";
+import { buildCandleGapGeometry } from "../draw/candleGap";
+import type { ChartPadding } from "../draw/line";
+import type { CandleMetrics, CandlePoint } from "../types";
+import { usePathBuilder } from "./usePathBuilder";
+
+/** Batched neutral previous-close paths for each semantic candle-gap kind. */
+export function useCandleGapPaths(
+  engine: SingleEngineState,
+  padding: ChartPadding,
+  candles: SharedValue<CandlePoint[]>,
+  liveCandle: SharedValue<CandlePoint | null>,
+  displayCandleWidth: SharedValue<number>,
+  config: ResolvedCandleGapsConfig,
+  metrics: CandleMetrics,
+) {
+  const noTradesBuilder = usePathBuilder();
+  const unavailableBuilder = usePathBuilder();
+  const unknownBuilder = usePathBuilder();
+
+  /* istanbul ignore next -- worklet */
+  const geometry = useDerivedValue(() =>
+    buildCandleGapGeometry(
+      candles.get(),
+      liveCandle.get(),
+      config.gaps,
+      padding,
+      engine.canvasWidth.get(),
+      engine.canvasHeight.get(),
+      engine.timestamp.get() - engine.displayWindow.get(),
+      engine.displayWindow.get(),
+      engine.displayMin.get(),
+      engine.displayMax.get(),
+      displayCandleWidth.get(),
+      config.styles["no-trades"].bridge !== null,
+      config.styles.unavailable.bridge !== null,
+      config.styles.unknown.bridge !== null,
+      metrics,
+    ),
+  );
+
+  /* istanbul ignore next -- worklet */
+  const noTradesPath = useDerivedValue(() => {
+    const b = noTradesBuilder.get();
+    const marks = geometry.get().marks;
+    for (let i = 0; i < marks.length; i++) {
+      const mark = marks[i];
+      if (mark.kind !== "no-trades") continue;
+      b.moveTo(mark.x1, mark.y);
+      b.lineTo(mark.x2, mark.y);
+    }
+    return b.detach();
+  });
+
+  /* istanbul ignore next -- worklet */
+  const unavailablePath = useDerivedValue(() => {
+    const b = unavailableBuilder.get();
+    const marks = geometry.get().marks;
+    for (let i = 0; i < marks.length; i++) {
+      const mark = marks[i];
+      if (mark.kind !== "unavailable") continue;
+      b.moveTo(mark.x1, mark.y);
+      b.lineTo(mark.x2, mark.y);
+    }
+    return b.detach();
+  });
+
+  /* istanbul ignore next -- worklet */
+  const unknownPath = useDerivedValue(() => {
+    const b = unknownBuilder.get();
+    const marks = geometry.get().marks;
+    for (let i = 0; i < marks.length; i++) {
+      const mark = marks[i];
+      if (mark.kind !== "unknown") continue;
+      b.moveTo(mark.x1, mark.y);
+      b.lineTo(mark.x2, mark.y);
+    }
+    return b.detach();
+  });
+
+  return {
+    noTradesPath,
+    unavailablePath,
+    unknownPath,
+  } as const;
+}

package/src/hooks/useChartPaths.ts

@@ -7,6 +7,7 @@ import type {
   SingleEngineState,
 } from "../core/useLiveChartEngine";
 import { buildLinePoints, type ChartPadding } from "../draw/line";
+import { buildLineGapSegmentRanges } from "../draw/lineGap";
 import {
   makeLineSimplifyScratch,
   simplifyLinePoints,
@@ -15,6 +16,7 @@ import { drawSpline, makeSplineScratch } from "../math/spline";
 import { sampleThresholdYAt, thresholdSampleSpanX } from "../math/threshold";
 import { blendPtsY, squigglifyPts } from "../math/squiggly";
 import { usePathBuilder } from "./usePathBuilder";
+import type { CandleGap } from "../types";
 
 /** Selects the synthetic right-edge line tip without coupling chart geometry
  * to badge or live-indicator presentation options. */
@@ -58,6 +60,8 @@ export function useChartPaths(
   thresholdSamples?: SharedValue<number[]>,
   /** Screen-space path simplification tolerance in pixels. `0` disables it. */
   simplifyTolerance = 0,
+  /** Explicit empty intervals that split line and fill geometry. */
+  lineGaps: CandleGap[] = [],
 ) {
   const lineBuilder = usePathBuilder();
   const fillBuilder = usePathBuilder();
@@ -68,6 +72,10 @@ export function useChartPaths(
     ptsA: number[];
     ptsB: number[];
     rawPts: number[];
+    rangesA: number[];
+    rangesB: number[];
+    gapXs: number[];
+    rangesTick: boolean;
     ptsTick: boolean;
     squigglePts: number[];
     morphA: number[];
@@ -82,6 +90,10 @@ export function useChartPaths(
       ptsA: [] as number[],
       ptsB: [] as number[],
       rawPts: [] as number[],
+      rangesA: [] as number[],
+      rangesB: [] as number[],
+      gapXs: [] as number[],
+      rangesTick: false,
       ptsTick: false,
       squigglePts: [] as number[],
       morphA: [] as number[],
@@ -169,14 +181,39 @@ export function useChartPaths(
     );
   });
 
+  const segmentRanges = useDerivedValue(() => {
+    const cache = cacheRef.current!;
+    cache.rangesTick = !cache.rangesTick;
+    const ranges = cache.rangesTick ? cache.rangesA : cache.rangesB;
+    const windowSecs = engine.displayWindow.get();
+    const canvasWidth = engine.canvasWidth.get();
+    return buildLineGapSegmentRanges(
+      flatPts.get(),
+      engine.data.get(),
+      lineGaps,
+      engine.timestamp.get() - windowSecs,
+      windowSecs,
+      padding.left,
+      canvasWidth - padding.left - padding.right,
+      ranges,
+      cache.gapXs,
+    );
+  });
+
   const linePath = useDerivedValue(() => {
     const cache = cacheRef.current!;
     const pts = flatPts.get();
     const n = pts.length >> 1;
     if (n < 2) return cache.emptyPath;
     const b = lineBuilder.value;
-    b.moveTo(pts[0], pts[1]);
-    drawSpline(b, pts, cache.scratch, linear);
+    const ranges = segmentRanges.get();
+    if (ranges.length === 0) return cache.emptyPath;
+    for (let i = 0; i < ranges.length; i += 2) {
+      const start = ranges[i];
+      const end = ranges[i + 1];
+      b.moveTo(pts[start * 2], pts[start * 2 + 1]);
+      drawSpline(b, pts, cache.scratch, linear, start, end);
+    }
     return b.detach();
   });
 
@@ -186,12 +223,20 @@ export function useChartPaths(
     const n = pts.length >> 1;
     if (n < 2) return cache.emptyPath;
     const b = fillBuilder.value;
-    b.moveTo(pts[0], pts[1]);
-    drawSpline(b, pts, cache.scratch, linear);
+    const ranges = segmentRanges.get();
+    if (ranges.length === 0) return cache.emptyPath;
     const bottom = engine.canvasHeight.get() - padding.bottom;
-    b.lineTo(pts[(n - 1) * 2], bottom);
-    b.lineTo(pts[0], bottom);
-    b.close();
+    for (let i = 0; i < ranges.length; i += 2) {
+      const start = ranges[i];
+      const end = ranges[i + 1];
+      const first = start * 2;
+      const last = (end - 1) * 2;
+      b.moveTo(pts[first], pts[first + 1]);
+      drawSpline(b, pts, cache.scratch, linear, start, end);
+      b.lineTo(pts[last], bottom);
+      b.lineTo(pts[first], bottom);
+      b.close();
+    }
     return b.detach();
   });
 
@@ -207,19 +252,17 @@ export function useChartPaths(
     const pts = flatPts.get();
     const n = pts.length >> 1;
     if (n < 2) return cache.emptyPath;
+    const ranges = segmentRanges.get();
+    if (ranges.length === 0) return cache.emptyPath;
 
     const tsamples = thresholdSamples?.get();
     if (tsamples && tsamples.length >= 2) {
       const b = thresholdFillBuilder.value;
-      b.moveTo(pts[0], pts[1]);
-      drawSpline(b, pts, cache.scratch, linear);
       // Band bottom = the SAMPLED threshold (identical to what the split shader
       // reads), pinned to the LINE's x-range. Because the geometry and the shader
       // use the same evenly-spaced, linearly-interpolated samples, a step riser
       // ramps the same way in both — no green/red sliver bleeds through — and the
       // x-range pin keeps the band closing with clean vertical sides (no wedge).
-      const leftX = pts[0];
-      const rightX = pts[(n - 1) * 2];
       const count = tsamples.length;
       // The samples live on the time-anchored, gliding grid — interpolate them
       // across that span (same as the shader), not the static plot edges.
@@ -231,13 +274,23 @@ export function useChartPaths(
         count,
       );
       const step = (x1 - x0) / (count - 1);
-      b.lineTo(rightX, sampleThresholdYAt(tsamples, x0, x1, rightX));
-      for (let i = count - 1; i >= 0; i--) {
-        const sx = x0 + step * i;
-        if (sx > leftX && sx < rightX) b.lineTo(sx, tsamples[i]);
+      for (let range = 0; range < ranges.length; range += 2) {
+        const start = ranges[range];
+        const end = ranges[range + 1];
+        const first = start * 2;
+        const last = (end - 1) * 2;
+        const leftX = pts[first];
+        const rightX = pts[last];
+        b.moveTo(leftX, pts[first + 1]);
+        drawSpline(b, pts, cache.scratch, linear, start, end);
+        b.lineTo(rightX, sampleThresholdYAt(tsamples, x0, x1, rightX));
+        for (let i = count - 1; i >= 0; i--) {
+          const sx = x0 + step * i;
+          if (sx > leftX && sx < rightX) b.lineTo(sx, tsamples[i]);
+        }
+        b.lineTo(leftX, sampleThresholdYAt(tsamples, x0, x1, leftX));
+        b.close();
       }
-      b.lineTo(leftX, sampleThresholdYAt(tsamples, x0, x1, leftX));
-      b.close();
       return b.detach();
     }
 
@@ -245,11 +298,17 @@ export function useChartPaths(
     const yT = thresholdY.get();
     if (!Number.isFinite(yT)) return cache.emptyPath;
     const b = thresholdFillBuilder.value;
-    b.moveTo(pts[0], pts[1]);
-    drawSpline(b, pts, cache.scratch, linear);
-    b.lineTo(pts[(n - 1) * 2], yT);
-    b.lineTo(pts[0], yT);
-    b.close();
+    for (let i = 0; i < ranges.length; i += 2) {
+      const start = ranges[i];
+      const end = ranges[i + 1];
+      const first = start * 2;
+      const last = (end - 1) * 2;
+      b.moveTo(pts[first], pts[first + 1]);
+      drawSpline(b, pts, cache.scratch, linear, start, end);
+      b.lineTo(pts[last], yT);
+      b.lineTo(pts[first], yT);
+      b.close();
+    }
     return b.detach();
   });
 

package/src/hooks/useCrosshair.ts

@@ -10,10 +10,16 @@ import { BADGE_METRICS_DEFAULTS, X_AXIS_LABEL_OFFSET_Y } from "../constants";
 import type { ResolvedScrubActionConfig } from "../core/resolveConfig";
 import type { SingleEngineState } from "../core/useLiveChartEngine";
 import { type ChartPadding } from "../draw/line";
+import { lineGapContainsData, previousLineValueAtTime } from "../draw/lineGap";
 import { interpolateAtTime } from "../math/interpolate";
+import {
+  pickCandleGapAtTime,
+  previousCandleCloseAtTime,
+} from "../math/candleGaps";
 import { pickCandleAtTime } from "../math/pickCandle";
 import type {
   BadgeMetrics,
+  CandleGap,
   CandlePoint,
   LiveChartPalette,
   ScrubActionPoint,
@@ -24,6 +30,7 @@ import {
   computeActionBadgeLayout,
   computeCandleTooltipLayout,
   computeCrosshairOpacity,
+  computeLineGapTooltipLayout,
   computeScrubDotY,
   computeScrubTime,
   computeTimeBadgeLayout,
@@ -84,22 +91,27 @@ function clampPlotY(
 export type { CrosshairState, TooltipLayout } from "./crosshairShared";
 export type { ScrubPoint };
 
-  export {
-    computeCandleTooltipLayout,
-    computeCrosshairOpacity,
-    computeScrubTime,
-    computeTooltipLayout,
-    computeTooltipLayoutMulti,
-    deriveCrosshairTooltipSingle,
-    deriveScrubValueSingle,
-    HIDDEN_TOOLTIP
-  } from "./crosshairShared";
+export {
+  computeCandleTooltipLayout,
+  computeCrosshairOpacity,
+  computeLineGapTooltipLayout,
+  computeScrubTime,
+  computeTooltipLayout,
+  computeTooltipLayoutMulti,
+  deriveCrosshairTooltipSingle,
+  deriveScrubValueSingle,
+  HIDDEN_TOOLTIP,
+} from "./crosshairShared";
 
-export interface CrosshairCandleOpts {
+export interface CrosshairChartOpts {
   mode: "line" | "candle";
   candles?: SharedValue<CandlePoint[]>;
   liveCandle?: SharedValue<CandlePoint | null>;
-  candleWidthSecs: number;
+  candleWidthSecs?: number;
+  gaps?: CandleGap[];
+  bridgeNoTrades?: boolean;
+  bridgeUnavailable?: boolean;
+  bridgeUnknown?: boolean;
 }
 
 /**
@@ -114,7 +126,7 @@ export function useCrosshair(
   font: SkFont,
   enabled: boolean,
   onScrub?: (point: ScrubPoint | null) => void,
-  candleOpts?: CrosshairCandleOpts,
+  chartOpts?: CrosshairChartOpts,
   /** Press-and-hold delay (ms) before scrubbing activates. 0 = immediate. */
   panGestureDelay = 0,
   onGestureStart?: () => void,
@@ -209,10 +221,14 @@ export function useCrosshair(
   const actionShowText = scrubAction?.text ?? true;
   const hasTimeBadge = scrubAction?.timeBadge ?? false;
 
-  const isCandleMode = candleOpts?.mode === "candle";
-  const candlesSV = candleOpts?.candles;
-  const liveCandleSV = candleOpts?.liveCandle;
-  const candleWidthSecs = candleOpts?.candleWidthSecs ?? 60;
+  const isCandleMode = chartOpts?.mode === "candle";
+  const candlesSV = chartOpts?.candles;
+  const liveCandleSV = chartOpts?.liveCandle;
+  const candleWidthSecs = chartOpts?.candleWidthSecs ?? 60;
+  const chartGaps = chartOpts?.gaps ?? [];
+  const bridgeNoTrades = chartOpts?.bridgeNoTrades ?? false;
+  const bridgeUnavailable = chartOpts?.bridgeUnavailable ?? false;
+  const bridgeUnknown = chartOpts?.bridgeUnknown ?? false;
 
   // Monospace advance width, measured once per render (not per scrub frame) so
   // the tooltip layout worklet can size text by character count instead of a
@@ -220,6 +236,7 @@ export function useCrosshair(
   const monoCharWidth = font.measureText("0").width;
   const scrubTime = useSharedValue(-1);
   const scrubCandle = useSharedValue<CandlePoint | null>(null);
+  const scrubGap = useSharedValue<CandleGap | null>(null);
   const scrubValue = useSharedValue<number | null>(null);
   const crosshairOpacity = useSharedValue(0);
   const scrubDotY = useSharedValue(-1);
@@ -252,12 +269,42 @@ export function useCrosshair(
               candleWidthSecs,
             )
           : null;
+      const lineData = engine.data.get();
+      const candidateGap =
+        active && time >= 0 && (!isCandleMode || !candle)
+          ? pickCandleGapAtTime(chartGaps, time)
+          : null;
+      const gap =
+        candidateGap &&
+        !isCandleMode &&
+        lineGapContainsData(lineData, candidateGap)
+          ? null
+          : candidateGap;
+      const gapBridged = gap
+        ? gap.kind === "no-trades"
+          ? bridgeNoTrades
+          : gap.kind === "unavailable"
+            ? bridgeUnavailable
+            : bridgeUnknown
+        : false;
+      const gapValue =
+        gap && gapBridged
+          ? isCandleMode && candlesSV
+            ? previousCandleCloseAtTime(
+                candlesSV.get(),
+                liveCandleSV?.get() ?? null,
+                time,
+              )
+            : previousLineValueAtTime(lineData, gap.from)
+          : null;
       const value =
         !active || time < 0
           ? null
           : isCandleMode
-            ? (candle?.close ?? null)
-            : interpolateAtTime(engine.data.get(), time);
+            ? (candle?.close ?? gapValue)
+            : gap
+              ? gapValue
+              : interpolateAtTime(lineData, time);
       const dotY = computeScrubDotY(
         value,
         engine.displayMin.get(),
@@ -278,28 +325,49 @@ export function useCrosshair(
             formatTime,
             font,
             monoCharWidth,
+            gap,
+            gapValue,
           )
-        : deriveCrosshairTooltipSingle(
-            active,
-            x,
-            time,
-            value,
-            padding,
-            canvasWidth,
-            formatValue,
-            formatTime,
-            font,
-            monoCharWidth,
-            tooltipPlacement,
-            tooltipShowValue,
-            tooltipShowTime,
-            canvasHeight,
-            tooltipMargin,
-            dotY,
-          );
+        : gap
+          ? computeLineGapTooltipLayout(
+              active,
+              x,
+              gap,
+              time,
+              padding,
+              canvasWidth,
+              formatTime,
+              font,
+              monoCharWidth,
+              tooltipPlacement,
+              tooltipShowValue,
+              tooltipShowTime,
+              canvasHeight,
+              tooltipMargin,
+              dotY,
+            )
+          : deriveCrosshairTooltipSingle(
+              active,
+              x,
+              time,
+              value,
+              padding,
+              canvasWidth,
+              formatValue,
+              formatTime,
+              font,
+              monoCharWidth,
+              tooltipPlacement,
+              tooltipShowValue,
+              tooltipShowTime,
+              canvasHeight,
+              tooltipMargin,
+              dotY,
+            );
       return {
         time,
         candle,
+        gap,
         value,
         opacity: computeCrosshairOpacity(active, x, canvasWidth, padding.right),
         dotY,
@@ -310,6 +378,7 @@ export function useCrosshair(
       "worklet";
       scrubTime.set(snapshot.time);
       scrubCandle.set(snapshot.candle);
+      scrubGap.set(snapshot.gap);
       scrubValue.set(snapshot.value);
       crosshairOpacity.set(snapshot.opacity);
       scrubDotY.set(snapshot.dotY);
@@ -440,11 +509,15 @@ export function useCrosshair(
     time: number,
     value: number,
     candleJson: string | null,
+    gapJson: string | null,
   ) {
     const candle: CandlePoint | undefined = candleJson
       ? (JSON.parse(candleJson) as CandlePoint)
       : undefined;
-    onScrub?.({ time, value, x, y, candle });
+    const gap: CandleGap | undefined = gapJson
+      ? (JSON.parse(gapJson) as CandleGap)
+      : undefined;
+    onScrub?.({ time, value, x, y, candle, gap });
   }
 
   /* istanbul ignore next */
@@ -490,7 +563,9 @@ export function useCrosshair(
         const c = scrubCandle.get();
         if (c) candleJson = JSON.stringify(c);
       }
-      return JSON.stringify([time, val, x, dotY, candleJson]);
+      const gap = scrubGap.get();
+      const gapJson = gap ? JSON.stringify(gap) : null;
+      return JSON.stringify([time, val, x, dotY, candleJson, gapJson]);
     },
     (curr, prev) => {
       "worklet";
@@ -509,8 +584,17 @@ export function useCrosshair(
         number,
         number,
         string | null,
+        string | null,
       ];
-      scheduleOnRN(handleScrub, row[2], row[3], row[0], row[1], row[4]);
+      scheduleOnRN(
+        handleScrub,
+        row[2],
+        row[3],
+        row[0],
+        row[1],
+        row[4],
+        row[5],
+      );
     },
   );
 
@@ -543,6 +627,7 @@ export function useCrosshair(
       engine.canvasWidth.get(),
       engine.timestamp.get(),
       engine.displayWindow.get(),
+      chartGaps,
     );
   };
 
@@ -824,6 +909,7 @@ export function useCrosshair(
     scrubTime,
     scrubValue,
     scrubCandle,
+    scrubGap,
     crosshairOpacity,
     tooltipLayout,
     scrubDotY,

package/src/hooks/useLineGapPaths.ts

@@ -0,0 +1,76 @@
+import { useDerivedValue } from "react-native-reanimated";
+import type { ResolvedCandleGapsConfig } from "../core/resolveConfig";
+import type { SingleEngineState } from "../core/useLiveChartEngine";
+import type { ChartPadding } from "../draw/line";
+import { buildLineGapGeometry } from "../draw/lineGap";
+import { usePathBuilder } from "./usePathBuilder";
+
+/** Batched flat previous-value bridge paths for each semantic line-gap kind. */
+export function useLineGapPaths(
+  engine: SingleEngineState,
+  padding: ChartPadding,
+  config: ResolvedCandleGapsConfig,
+) {
+  const noTradesBuilder = usePathBuilder();
+  const unavailableBuilder = usePathBuilder();
+  const unknownBuilder = usePathBuilder();
+
+  /* istanbul ignore next -- worklet */
+  const geometry = useDerivedValue(() =>
+    buildLineGapGeometry(
+      engine.data.get(),
+      config.gaps,
+      padding,
+      engine.canvasWidth.get(),
+      engine.canvasHeight.get(),
+      engine.timestamp.get() - engine.displayWindow.get(),
+      engine.displayWindow.get(),
+      engine.displayMin.get(),
+      engine.displayMax.get(),
+      config.styles["no-trades"].bridge !== null,
+      config.styles.unavailable.bridge !== null,
+      config.styles.unknown.bridge !== null,
+    ),
+  );
+
+  /* istanbul ignore next -- worklet */
+  const noTradesPath = useDerivedValue(() => {
+    const b = noTradesBuilder.get();
+    const bridges = geometry.get().bridges;
+    for (let i = 0; i < bridges.length; i++) {
+      const bridge = bridges[i];
+      if (bridge.kind !== "no-trades") continue;
+      b.moveTo(bridge.x1, bridge.y);
+      b.lineTo(bridge.x2, bridge.y);
+    }
+    return b.detach();
+  });
+
+  /* istanbul ignore next -- worklet */
+  const unavailablePath = useDerivedValue(() => {
+    const b = unavailableBuilder.get();
+    const bridges = geometry.get().bridges;
+    for (let i = 0; i < bridges.length; i++) {
+      const bridge = bridges[i];
+      if (bridge.kind !== "unavailable") continue;
+      b.moveTo(bridge.x1, bridge.y);
+      b.lineTo(bridge.x2, bridge.y);
+    }
+    return b.detach();
+  });
+
+  /* istanbul ignore next -- worklet */
+  const unknownPath = useDerivedValue(() => {
+    const b = unknownBuilder.get();
+    const bridges = geometry.get().bridges;
+    for (let i = 0; i < bridges.length; i++) {
+      const bridge = bridges[i];
+      if (bridge.kind !== "unknown") continue;
+      b.moveTo(bridge.x1, bridge.y);
+      b.lineTo(bridge.x2, bridge.y);
+    }
+    return b.detach();
+  });
+
+  return { noTradesPath, unavailablePath, unknownPath } as const;
+}

package/src/hooks/usePinchZoom.ts

@@ -26,6 +26,27 @@ export interface PinchZoomEngineRefs {
   canvasWidth: SharedValue<number>;
 }
 
+/** The pinch state cleared by the public chart handle's `resetZoom()` method. */
+export type PinchZoomResetRefs = Pick<
+  PinchZoomEngineRefs,
+  "viewWindow" | "viewEnd"
+>;
+
+/**
+ * Clear the focal-anchored pinch overrides so the engine follows its configured
+ * `timeWindow` and live edge again. Safe to call when the chart is already reset.
+ */
+export function resetPinchZoom({
+  viewWindow,
+  viewEnd,
+}: PinchZoomResetRefs): void {
+  "worklet";
+  cancelAnimation(viewWindow);
+  cancelAnimation(viewEnd);
+  viewWindow.set(null);
+  viewEnd.set(null);
+}
+
 export interface UsePinchZoomOptions {
   engine: PinchZoomEngineRefs;
   padding: ChartPadding;

package/src/hooks/useReferenceLine.ts

@@ -279,9 +279,10 @@ export function computeReferenceBadgeRect(
 
 /**
  * Derives screen-space layout for a single reference line or band. Supports all
- * three `ReferenceLine` forms (horizontal line, horizontal value band, vertical
- * time band) plus the pill badge for a Form-A value (in-range tag + off-screen
- * chevron pin).
+ * three scalar/band `ReferenceLine` forms (horizontal line, horizontal value
+ * band, vertical time band) plus the pill badge for a Form-A value (in-range tag
+ * + off-screen chevron pin). The series form is handled by
+ * `ReferenceLineSeriesOverlay`.
  */
 export function useReferenceLine(
   engine: ChartEngineLayout,
@@ -344,7 +345,7 @@ export function useReferenceLine(
     const fm = font.getMetrics();
     const baselineOffset = (fm.ascent + fm.descent) / 2;
 
-    // ── Form C — vertical time band (independent of the value range) ─────────
+    // ── Form D — vertical time band (independent of the value range) ─────────
     if (form === "time-band") {
       if (line.from === undefined || line.to === undefined) return INVISIBLE;
       const now = engine.timestamp.value;
@@ -392,7 +393,7 @@ export function useReferenceLine(
     if (valRange <= 0) return INVISIBLE;
     const toY = (v: number) => chartTop + ((dMax - v) / valRange) * chartH;
 
-    // ── Form B — horizontal value band ───────────────────────────────────────
+    // ── Form C — horizontal value band ───────────────────────────────────────
     if (form === "value-band") {
       if (line.valueFrom === undefined || line.valueTo === undefined) {
         return INVISIBLE;