react-native-livechart 3.3.0 → 3.5.0

package/src/hooks/useReferenceLine.ts

@@ -7,6 +7,7 @@ import { measureFontTextWidth } from "../lib/measureFontTextWidth";
 import {
   classifyReferenceEdge,
   referenceLineForm,
+  resolveReferenceBadge,
 } from "../math/referenceLines";
 import type { ReferenceLine } from "../types";
 
@@ -21,14 +22,30 @@ export interface ReferenceLineLayout {
   x1: number;
   /** Right x extent. */
   x2: number;
-  /** Resolved label text (with appended value when `showValue`). */
+  /** Resolved label text (with appended value when `showValue`); "" when hidden. */
   label: string;
   labelX: number;
   labelY: number;
-  /** True when a Form-A line is off-screen and its off-axis badge is showing. */
+  /** True when a Form-A value is off-screen (badge pinned to the edge + chevron). */
   offAxis: boolean;
   /** Off-axis chevron points up (target above range) vs down (below). */
   chevronUp: boolean;
+  /** True when the value renders as a pill badge (icon / text / chevron tag). */
+  badge: boolean;
+  /** Badge pill rect left x. */
+  pillX: number;
+  /** Badge pill rect width. */
+  pillW: number;
+  /** Badge icon glyph x (-1 when no icon). */
+  iconX: number;
+  /** Badge icon glyph (""/none). */
+  icon: string;
+  /** Off-axis chevron center x (-1 when no chevron). */
+  chevronCx: number;
+  /** Connector dashed-line start x (-1 when no connector). */
+  connStart: number;
+  /** Connector dashed-line end x. */
+  connEnd: number;
 }
 
 const INVISIBLE: ReferenceLineLayout = {
@@ -42,15 +59,207 @@ const INVISIBLE: ReferenceLineLayout = {
   labelY: -1,
   offAxis: false,
   chevronUp: false,
+  badge: false,
+  pillX: 0,
+  pillW: 0,
+  iconX: -1,
+  icon: "",
+  chevronCx: -1,
+  connStart: -1,
+  connEnd: -1,
 };
 
 /** Off-axis indicator inset from the nearest plot edge, in px. */
 const OFF_AXIS_EDGE_INSET = 12;
 
+// Badge pill geometry (kept in sync with the overlay's pill height).
+const BADGE_PAD_X = 6;
+const BADGE_GAP = 4;
+const BADGE_CHEV_W = 8;
+/** Pill inset from the pinned plot edge, in px. */
+const BADGE_EDGE_INSET = 2;
+/** Vertical padding inside the pill (matches ReferenceLineOverlay's BADGE_PILL_PAD_Y). */
+const BADGE_PILL_PAD_Y = 3;
+
+interface BadgeGeometry {
+  pillX: number;
+  pillW: number;
+  iconX: number;
+  textX: number;
+  chevronCx: number;
+  connStart: number;
+  connEnd: number;
+}
+
+/**
+ * Lays out the badge pill at one plot edge: `[chevron?][icon?][text?]` left→right
+ * inside the pill, with a dashed connector running to the opposite edge.
+ */
+function badgeGeometry(
+  position: "left" | "right",
+  icon: string,
+  text: string,
+  hasChevron: boolean,
+  x1: number,
+  x2: number,
+  font: SkFont,
+): BadgeGeometry {
+  "worklet";
+  // Measure the icon's visual bounds (not just width): `SkiaText` draws from the
+  // pen origin, so the glyph's left side-bearing (`bounds.x`) must be subtracted
+  // to land the ink in its slot. Without this an asymmetric glyph (a ▼ triangle,
+  // a "+"/"−") sits off-center in an icon-only pill. Mirrors the action-badge
+  // price-pill centering in computeActionBadgeLayout.
+  const iconBounds = icon ? font.measureText(icon) : null;
+  const iconW = iconBounds ? iconBounds.width : 0;
+  const textW = text ? measureFontTextWidth(font, text) : 0;
+
+  let contentW = 0;
+  let count = 0;
+  if (hasChevron) {
+    contentW += BADGE_CHEV_W;
+    count++;
+  }
+  if (icon) {
+    contentW += iconW;
+    count++;
+  }
+  if (text) {
+    contentW += textW;
+    count++;
+  }
+  contentW += BADGE_GAP * Math.max(0, count - 1);
+
+  const pillW = contentW + BADGE_PAD_X * 2;
+  const pillX =
+    position === "right"
+      ? x2 - BADGE_EDGE_INSET - pillW
+      : x1 + BADGE_EDGE_INSET;
+
+  let cursor = pillX + BADGE_PAD_X;
+  let chevronCx = -1;
+  if (hasChevron) {
+    chevronCx = cursor + BADGE_CHEV_W / 2;
+    cursor += BADGE_CHEV_W + BADGE_GAP;
+  }
+  let iconX = -1;
+  if (icon) {
+    // Pen origin compensates the left side-bearing so the ink starts at `cursor`
+    // (and is centered in an icon-only pill, whose width is iconW + 2*padX).
+    iconX = cursor - (iconBounds ? iconBounds.x : 0);
+    cursor += iconW + BADGE_GAP;
+  }
+  const textX = text ? cursor : -1;
+
+  let connStart = -1;
+  let connEnd = -1;
+  if (position === "right") {
+    const end = pillX - 4;
+    if (end > x1) {
+      connStart = x1;
+      connEnd = end;
+    }
+  } else {
+    const start = pillX + pillW + 4;
+    if (start < x2) {
+      connStart = start;
+      connEnd = x2;
+    }
+  }
+
+  return { pillX, pillW, iconX, textX, chevronCx, connStart, connEnd };
+}
+
+/** Resolved badge text for a Form-A line (in-range tag or off-axis pin). */
+function referenceBadgeText(
+  line: ReferenceLine,
+  badge: ReturnType<typeof resolveReferenceBadge> & object,
+  v: number,
+  formatValue: (value: number) => string,
+  offAxis: boolean,
+): string {
+  "worklet";
+  if (!badge.showText) return "";
+  if (offAxis && badge.legacyText) {
+    const word = line.offAxisBadgeLabel ?? line.label;
+    return word ? `${word}: ${formatValue(v)}` : formatValue(v);
+  }
+  if (line.showValue && line.label) return `${line.label} ${formatValue(v)}`;
+  return line.label ?? formatValue(v);
+}
+
+/** Axis-aligned screen rect of a reference-line badge pill (the press hit-target). */
+export interface ReferenceBadgeRect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+/**
+ * Screen-space pill rect for a Form-A reference line's **badge**, or `null` when
+ * the line has no pressable badge (no `badge`/`offAxisBadge`, not a value line, a
+ * legacy off-axis badge while in range, or the canvas isn't laid out / range is
+ * degenerate). Shares `badgeGeometry` + the edge classification with
+ * {@link useReferenceLine}, so the hit-target tracks the rendered pill exactly.
+ * Pure worklet — used by {@link useReferenceLinePress} for tap hit-testing.
+ */
+export function computeReferenceBadgeRect(
+  line: ReferenceLine,
+  canvasWidth: number,
+  canvasHeight: number,
+  padding: ChartPadding,
+  dMin: number,
+  dMax: number,
+  font: SkFont,
+  formatValue: (value: number) => string,
+): ReferenceBadgeRect | null {
+  "worklet";
+  const badge = resolveReferenceBadge(line);
+  if (!badge) return null;
+  if (referenceLineForm(line) !== "line" || line.value === undefined) return null;
+  if (canvasWidth === 0 || canvasHeight === 0) return null;
+
+  const chartTop = padding.top;
+  const chartBottom = canvasHeight - padding.bottom;
+  const chartH = chartBottom - chartTop;
+  const valRange = dMax - dMin;
+  if (chartH <= 0 || valRange <= 0) return null;
+
+  const x1 = padding.left;
+  const x2 = canvasWidth - padding.right;
+  const v = line.value;
+  const edge = classifyReferenceEdge(v, dMin, dMax);
+
+  let y: number;
+  let hasChevron: boolean;
+  if (edge !== "in") {
+    // Off-screen: pinned to the nearest edge with a chevron.
+    hasChevron = true;
+    y =
+      edge === "above"
+        ? chartTop + OFF_AXIS_EDGE_INSET
+        : chartBottom - OFF_AXIS_EDGE_INSET;
+  } else {
+    // In range: a legacy off-axis-only badge shows no pill here → not pressable.
+    if (!badge.inRange) return null;
+    hasChevron = false;
+    y = chartTop + ((dMax - v) / valRange) * chartH;
+  }
+
+  const text = referenceBadgeText(line, badge, v, formatValue, edge !== "in");
+  const g = badgeGeometry(badge.position, badge.icon, text, hasChevron, x1, x2, font);
+  const fm = font.getMetrics();
+  const pillH = fm.descent - fm.ascent + BADGE_PILL_PAD_Y * 2;
+  // The pill is vertically centered on the line's y (see ReferenceLineOverlay).
+  return { x: g.pillX, y: y - pillH / 2, w: g.pillW, h: pillH };
+}
+
 /**
  * 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 off-axis badge for an off-screen Form-A value.
+ * time band) plus the pill badge for a Form-A value (in-range tag + off-screen
+ * chevron pin).
  */
 export function useReferenceLine(
   engine: ChartEngineLayout,
@@ -60,6 +269,8 @@ export function useReferenceLine(
   font: SkFont,
 ): SharedValue<ReferenceLineLayout> {
   const form = line ? referenceLineForm(line) : "none";
+  // Badge presentation depends only on the (stable) line props — resolve once.
+  const badge = line ? resolveReferenceBadge(line) : null;
 
   return useDerivedValue<ReferenceLineLayout>(() => {
     if (!line || form === "none") return INVISIBLE;
@@ -103,6 +314,7 @@ export function useReferenceLine(
           ? bx2 - 4 - measureFontTextWidth(font, label)
           : bx1 + 4;
       return {
+        ...INVISIBLE,
         visible: true,
         y: chartTop,
         yBottom: chartBottom,
@@ -111,8 +323,6 @@ export function useReferenceLine(
         label,
         labelX,
         labelY: chartTop - fm.ascent + 2,
-        offAxis: false,
-        chevronUp: false,
       };
     }
 
@@ -145,6 +355,7 @@ export function useReferenceLine(
           ? x2 - 4 - measureFontTextWidth(font, label)
           : x1 + 4;
       return {
+        ...INVISIBLE,
         visible: true,
         y: yTop,
         yBottom: yBot,
@@ -153,39 +364,74 @@ export function useReferenceLine(
         label,
         labelX,
         labelY: yTop - fm.ascent + 2,
-        offAxis: false,
-        chevronUp: false,
       };
     }
 
-    // ── Form A — horizontal line (with optional off-axis badge) ──────────────
+    // ── Form A — horizontal line (with optional pill badge) ──────────────────
     if (line.value === undefined) return INVISIBLE;
     const v = line.value;
     const edge = classifyReferenceEdge(v, dMin, dMax);
 
+    // Off-screen: pin the badge to the nearest edge with a chevron (when a badge
+    // is configured); otherwise cull the off-screen line (legacy behavior).
     if (edge !== "in") {
-      if (!line.offAxisBadge) return INVISIBLE; // legacy: cull off-screen line
+      if (!badge) return INVISIBLE;
       const above = edge === "above";
       const clampedY = above
         ? chartTop + OFF_AXIS_EDGE_INSET
         : chartBottom - OFF_AXIS_EDGE_INSET;
-      const word = line.offAxisBadgeLabel ?? line.label;
-      const text = word ? `${word}: ${formatValue(v)}` : formatValue(v);
+      const text = referenceBadgeText(line, badge, v, formatValue, true);
+      const g = badgeGeometry(badge.position, badge.icon, text, true, x1, x2, font);
       return {
+        ...INVISIBLE,
         visible: true,
         y: clampedY,
         yBottom: clampedY,
         x1,
         x2,
         label: text,
-        labelX: x1 + 16,
+        labelX: g.textX,
         labelY: clampedY - baselineOffset,
         offAxis: true,
         chevronUp: above,
+        badge: true,
+        pillX: g.pillX,
+        pillW: g.pillW,
+        iconX: g.iconX,
+        icon: badge.icon,
+        chevronCx: g.chevronCx,
+        connStart: g.connStart,
+        connEnd: g.connEnd,
       };
     }
 
     const y = toY(v);
+
+    // In-range pill badge (the `badge` config, not the legacy off-axis-only flag).
+    if (badge && badge.inRange) {
+      const text = referenceBadgeText(line, badge, v, formatValue, false);
+      const g = badgeGeometry(badge.position, badge.icon, text, false, x1, x2, font);
+      return {
+        ...INVISIBLE,
+        visible: true,
+        y,
+        yBottom: y,
+        x1,
+        x2,
+        label: text,
+        labelX: g.textX,
+        labelY: y - baselineOffset,
+        badge: true,
+        pillX: g.pillX,
+        pillW: g.pillW,
+        iconX: g.iconX,
+        icon: badge.icon,
+        connStart: g.connStart,
+        connEnd: g.connEnd,
+      };
+    }
+
+    // Plain gutter label (no badge, or a legacy off-axis badge that's in range).
     let label = line.label ?? formatValue(v);
     if (line.showValue && line.label) label = `${line.label} ${formatValue(v)}`;
 
@@ -197,6 +443,7 @@ export function useReferenceLine(
     else labelX = x2 + 4; // "right" — legacy gutter position
 
     return {
+      ...INVISIBLE,
       visible: true,
       y,
       yBottom: y,
@@ -205,8 +452,6 @@ export function useReferenceLine(
       label,
       labelX,
       labelY: y - baselineOffset,
-      offAxis: false,
-      chevronUp: false,
     };
   });
 }

package/src/hooks/useReferenceLinePress.ts

@@ -0,0 +1,92 @@
+import type { SkFont } from "@shopify/react-native-skia";
+import { Gesture } from "react-native-gesture-handler";
+import { useDerivedValue } from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+
+import type { ChartEngineLayout } from "../core/useLiveChartEngine";
+import type { ChartPadding } from "../draw/line";
+import type { ReferenceLine } from "../types";
+import { pointInRect } from "./crosshairShared";
+import {
+  computeReferenceBadgeRect,
+  type ReferenceBadgeRect,
+} from "./useReferenceLine";
+
+/**
+ * Builds a tap gesture that hit-tests a chart's reference-line **badges** (the
+ * pill tags for working orders / alerts / targets) and fires `onPress(line,
+ * index)` when one is tapped. Mirrors {@link useMarkers}: badge rects are
+ * projected to screen each frame on the UI thread (so they track the rescaling
+ * axis exactly like the rendered pills), and the gesture hit-tests against them.
+ *
+ * Also returns a `hitTest` worklet so a coexisting gesture (the scrub-action tap)
+ * can defer to a badge under the finger instead of acting on it. Only badge-tagged
+ * Form-A (value) lines are pressable; everything else projects to `null`.
+ */
+export function useReferenceLinePress(
+  engine: ChartEngineLayout,
+  padding: ChartPadding,
+  lines: ReferenceLine[],
+  font: SkFont,
+  formatValue: (v: number) => string,
+  active: boolean,
+  /** Touch-target inflation around each pill, in px. */
+  hitSlop: number,
+  onPress?: (line: ReferenceLine, index: number) => void,
+): {
+  tapGesture: ReturnType<typeof Gesture.Tap>;
+  hitTest: (x: number, y: number) => boolean;
+} {
+  // Per-frame badge hit-rects, index-aligned with `lines` (null = no pressable
+  // badge / off-screen / not laid out). Recomputed on the UI thread.
+  /* istanbul ignore next -- worklet runs on the UI thread, not in Jest */
+  const rects = useDerivedValue<(ReferenceBadgeRect | null)[]>(() => {
+    if (!active || lines.length === 0) return [];
+    const w = engine.canvasWidth.value;
+    const h = engine.canvasHeight.value;
+    const dMin = engine.displayMin.value;
+    const dMax = engine.displayMax.value;
+    const out: (ReferenceBadgeRect | null)[] = [];
+    for (let i = 0; i < lines.length; i++) {
+      out.push(
+        computeReferenceBadgeRect(lines[i], w, h, padding, dMin, dMax, font, formatValue),
+      );
+    }
+    return out;
+  });
+
+  // Topmost badge under (x, y), or -1. Last drawn = last in the array = topmost.
+  /* istanbul ignore next -- worklet, runs on the UI thread */
+  const indexAt = (x: number, y: number): number => {
+    "worklet";
+    const rs = rects.value;
+    for (let i = rs.length - 1; i >= 0; i--) {
+      const r = rs[i];
+      if (r && pointInRect(x, y, r, hitSlop)) return i;
+    }
+    return -1;
+  };
+
+  /* istanbul ignore next -- worklet, runs on the UI thread */
+  const hitTest = (x: number, y: number): boolean => {
+    "worklet";
+    return indexAt(x, y) >= 0;
+  };
+
+  /* istanbul ignore next -- runs only via scheduleOnRN from the UI-thread tap */
+  function emitPress(index: number) {
+    onPress?.(lines[index], index);
+  }
+
+  /* istanbul ignore next -- gesture worklet runs on the UI thread, not in Jest */
+  const tapGesture = Gesture.Tap()
+    .maxDuration(250)
+    .onEnd((e, success) => {
+      "worklet";
+      if (!active || !success) return;
+      const i = indexAt(e.x, e.y);
+      if (i >= 0) scheduleOnRN(emitPress, i);
+    });
+
+  return { tapGesture, hitTest };
+}

package/src/hooks/useThreshold.ts

@@ -0,0 +1,63 @@
+import { vec } from "@shopify/react-native-skia";
+import { useDerivedValue, type SharedValue } from "react-native-reanimated";
+
+import type { ChartEngineLayout } from "../core/useLiveChartEngine";
+import type { ChartPadding } from "../draw/line";
+import {
+  thresholdLineY,
+  thresholdSplitPositions,
+  thresholdVisible,
+} from "../math/threshold";
+
+export interface ThresholdGeometry {
+  /** Threshold pixel-Y within the canvas, or NaN before layout / degenerate range. */
+  lineY: SharedValue<number>;
+  /** Whether the threshold sits within the plot area (drives marker-line opacity). */
+  visible: SharedValue<boolean>;
+  /** Vertical gradient end vector, `vec(0, canvasHeight)` — shared by stroke + fill. */
+  gradientEnd: SharedValue<ReturnType<typeof vec>>;
+  /** `[0, t, t, 1]` stop positions for the hard-split gradient — shared by stroke + fill. */
+  splitPositions: SharedValue<number[]>;
+}
+
+/**
+ * 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.
+ */
+export function useThreshold(
+  engine: ChartEngineLayout,
+  padding: ChartPadding,
+  value: SharedValue<number>,
+): ThresholdGeometry {
+  const lineY = useDerivedValue(() =>
+    thresholdLineY(
+      value.get(),
+      engine.displayMin.get(),
+      engine.displayMax.get(),
+      engine.canvasHeight.get(),
+      padding.top,
+      padding.bottom,
+    ),
+  );
+
+  const visible = useDerivedValue(() =>
+    thresholdVisible(
+      lineY.get(),
+      engine.canvasHeight.get(),
+      padding.top,
+      padding.bottom,
+    ),
+  );
+
+  const splitPositions = useDerivedValue(() =>
+    thresholdSplitPositions(lineY.get(), engine.canvasHeight.get()),
+  );
+
+  const gradientEnd = useDerivedValue(() =>
+    vec(0, Math.max(1, engine.canvasHeight.get())),
+  );
+
+  return { lineY, visible, gradientEnd, splitPositions };
+}

package/src/index.ts

@@ -64,6 +64,9 @@ export type {
   MultiSeriesDotConfig,
   PulseConfig,
   ReferenceLine,
+  ReferenceLineBadgeConfig,
+  ScrubActionConfig,
+  ScrubActionPoint,
   ScrubConfig,
   ScrubPoint,
   ScrubPointCore,
@@ -74,6 +77,8 @@ export type {
   SelectionDotRingConfig,
   SeriesConfig,
   ThemeMode,
+  ThresholdConfig,
+  ThresholdLineConfig,
   TradeEvent,
   ValueLineConfig,
   XAxisConfig,

package/src/math/referenceLines.ts

@@ -40,6 +40,61 @@ export function collectReferenceValues(lines: ReferenceLine[]): number[] {
   return out;
 }
 
+/** Fully-resolved badge presentation for a Form-A reference line. */
+export interface ResolvedReferenceBadge {
+  position: "left" | "right";
+  /** Leading glyph, or "" for none. */
+  icon: string;
+  /** Whether the text label is shown. */
+  showText: boolean;
+  /** undefined → theme tooltipBg at render time. */
+  background: string | undefined;
+  /** undefined → the line color at render time. */
+  borderColor: string | undefined;
+  radius: number;
+  /** Show the pill at the value when in range (`badge`) vs only off-screen (legacy `offAxisBadge`). */
+  inRange: boolean;
+  /** Legacy `"word: value"` text format (off-axis badge) vs the `label`/value format. */
+  legacyText: boolean;
+}
+
+/**
+ * Resolves a Form-A reference line's badge presentation from the new `badge`
+ * config or the legacy `offAxisBadge` flag (the `badge` config wins). Returns
+ * null when neither is set. Pure — driven only by the line props.
+ */
+export function resolveReferenceBadge(
+  rl: ReferenceLine,
+): ResolvedReferenceBadge | null {
+  "worklet";
+  if (rl.badge) {
+    const cfg = rl.badge === true ? undefined : rl.badge;
+    return {
+      position: cfg?.position ?? "left",
+      icon: cfg?.icon ?? "",
+      showText: cfg?.text ?? true,
+      background: cfg?.background ?? rl.badgeBackground,
+      borderColor: cfg?.borderColor ?? rl.badgeBorderColor,
+      radius: cfg?.radius ?? rl.badgeRadius ?? 5,
+      inRange: true,
+      legacyText: false,
+    };
+  }
+  if (rl.offAxisBadge) {
+    return {
+      position: "left",
+      icon: "",
+      showText: true,
+      background: rl.badgeBackground,
+      borderColor: rl.badgeBorderColor,
+      radius: rl.badgeRadius ?? 5,
+      inRange: false,
+      legacyText: true,
+    };
+  }
+  return null;
+}
+
 /**
  * Where a Y value sits relative to the visible plot range:
  * `"in"` (within [min, max]), `"above"` (greater than max), or `"below"`.

package/src/math/threshold.ts

@@ -0,0 +1,59 @@
+/**
+ * Pure, worklet-safe geometry for the threshold split ({@link ThresholdConfig}).
+ * No SharedValues and no hooks — these are unit-tested directly; `useThreshold`
+ * wires the live SharedValues into them.
+ */
+
+/**
+ * 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
+ * when the canvas hasn't laid out yet or the value range is degenerate, so the
+ * line/fill/marker callers can cull instead of drawing at a bogus position.
+ */
+export function thresholdLineY(
+  value: number,
+  displayMin: number,
+  displayMax: number,
+  canvasHeight: number,
+  paddingTop: number,
+  paddingBottom: number,
+): number {
+  "worklet";
+  const range = displayMax - displayMin;
+  const chartH = canvasHeight - paddingTop - paddingBottom;
+  if (canvasHeight <= 0 || range <= 0 || chartH <= 0) return NaN;
+  return paddingTop + ((displayMax - value) / range) * chartH;
+}
+
+/** True when the threshold's Y sits within the plot area (i.e. on-screen). */
+export function thresholdVisible(
+  lineY: number,
+  canvasHeight: number,
+  paddingTop: number,
+  paddingBottom: number,
+): boolean {
+  "worklet";
+  if (!Number.isFinite(lineY) || canvasHeight <= 0) return false;
+  return lineY >= paddingTop && lineY <= canvasHeight - paddingBottom;
+}
+
+/**
+ * Stop positions for the vertical hard-split gradient, paired with the 4-stop
+ * color array `[above, above, below, below]`: `[0, t, t, 1]`, where `t` is the
+ * threshold's fraction down the full canvas (the gradient vector spans
+ * `0 → canvasHeight`), clamped to `[0, 1]`.
+ *
+ * - `t ≤ 0` (threshold above everything) → `[0, 0, 0, 1]` → solid below-color.
+ * - `t ≥ 1` (threshold below everything) → `[0, 1, 1, 1]` → solid above-color.
+ */
+export function thresholdSplitPositions(
+  lineY: number,
+  canvasHeight: number,
+): number[] {
+  "worklet";
+  if (canvasHeight <= 0 || !Number.isFinite(lineY)) return [0, 1, 1, 1];
+  let t = lineY / canvasHeight;
+  if (t < 0) t = 0;
+  else if (t > 1) t = 1;
+  return [0, t, t, 1];
+}