react-native-livechart 4.10.0 → 4.12.0

package/src/components/LiveChartSeries.tsx

@@ -4,7 +4,7 @@
  *
  * @see https://github.com/benjitaylor/liveline
  */
-import { Canvas, Group } from "@shopify/react-native-skia";
+import { Canvas, Group, Rect } from "@shopify/react-native-skia";
 import { useLayoutEffect, useState } from "react";
 import { StyleSheet, View } from "react-native";
 import { Gesture, GestureDetector } from "react-native-gesture-handler";
@@ -28,7 +28,6 @@ import {
   lineStyleSignatureFromArray,
   resolveMultiSeriesLineColorsSnapshot,
   resolveMultiSeriesLineStylesSnapshot,
-  type SeriesLineStyle,
 } from "../core/multiSeriesLayout";
 import {
   resolveAxisLabel,
@@ -53,6 +52,7 @@ import { pulseRadialOutset } from "../draw/line";
 import { resolveChartLayout } from "../hooks/resolveChartLayout";
 import { useCanvasLayout } from "../hooks/useCanvasLayout";
 import { useChartReveal } from "../hooks/useChartReveal";
+import { useChartOverlayContext } from "../hooks/useChartOverlayContext";
 import { useChartSkiaFont } from "../hooks/useChartSkiaFont";
 import { useCrosshairSeries } from "../hooks/useCrosshairSeries";
 import { useMarkers } from "../hooks/useMarkers";
@@ -70,7 +70,10 @@ import {
 } from "../lib/format";
 import { measureFontTextWidth } from "../lib/measureFontTextWidth";
 import { MONO_FONT_FAMILY } from "../lib/monoFontFamily";
-import { collectReferenceValues } from "../math/referenceLines";
+import {
+  collectReferenceValues,
+  referenceLineReactKeys,
+} from "../math/referenceLines";
 import {
   applyPaletteOverride,
   leftEdgeFadeColorsFromBgRgb,
@@ -78,11 +81,16 @@ import {
 } from "../theme";
 import type { LiveChartSeriesProps, Marker, SeriesConfig } from "../types";
 import { AxisLabelOverlay } from "./AxisLabelOverlay";
+import { ChartOverlayLayer } from "./ChartOverlayLayer";
 import {
   ExtremaConnectorOverlay,
   labelConnector,
 } from "./ExtremaConnectorOverlay";
 import { CustomMarkerOverlay } from "./CustomMarkerOverlay";
+import {
+  CustomReferenceLineOverlay,
+  customReferenceLineFlags,
+} from "./CustomReferenceLineOverlay";
 import { CrosshairLine } from "./CrosshairLine";
 import { DegenParticlesOverlay } from "./DegenParticlesOverlay";
 import { LeftEdgeFade } from "./LeftEdgeFade";
@@ -92,6 +100,7 @@ import { MultiSeriesDots } from "./MultiSeriesDots";
 import { MultiSeriesStroke } from "./MultiSeriesStroke";
 import { MultiSeriesValueLabels } from "./MultiSeriesValueLabels";
 import { MultiSeriesValueLines } from "./MultiSeriesValueLines";
+import { PerSeriesTooltipOverlay } from "./PerSeriesTooltipOverlay";
 import { ReferenceLineOverlay } from "./ReferenceLineOverlay";
 import { SeriesToggleChips } from "./SeriesToggleChips";
 import { XAxisOverlay } from "./XAxisOverlay";
@@ -128,6 +137,7 @@ function useLiveChartSeriesController({
   font: fontProp,
   insets,
   style,
+  canvasMode = "transparent",
   timeWindow = 30,
   paused = false,
   loading = false,
@@ -172,6 +182,9 @@ function useLiveChartSeriesController({
   markerHitRadius = 16,
   markerCluster,
   renderMarker,
+  renderOverlay,
+  renderReferenceLine,
+  renderOffAxisReferenceLine,
   leftEdgeFade = true,
 }: LiveChartSeriesProps) {
   const emptyMarkers = useSharedValue<Marker[]>([]);
@@ -184,6 +197,10 @@ function useLiveChartSeriesController({
   const bottomLabelCfg = resolveAxisLabel(bottomLabel);
   const scrubCfg = resolveScrub(scrub);
   const scrubEnabled = scrubCfg !== null;
+  // Opt-in and subordinate to the existing master `tooltip` switch. Keeping
+  // this null by default preserves LiveChartSeries' historical guide-only scrub.
+  const seriesTooltipCfg =
+    scrubCfg?.tooltip === true ? scrubCfg.seriesTooltip : null;
 
   // Time-scroll + pinch-zoom (mirrors LiveChart). LiveChartSeries has no static
   // mode, so these gate on the props alone. `holdToScrub` requires the scrub
@@ -210,8 +227,8 @@ function useLiveChartSeriesController({
 
   // Multi-series defaults the scrub selection dot OFF: it can only track one
   // line (the leading series), which reads as a bug next to the other series.
-  // The crosshair line + per-series tooltip stack already mark the scrub point.
-  // Passing `selectionDot` explicitly (true / config) still opts it in.
+  // The crosshair line (and the opt-in tooltip's per-series intersection dots)
+  // mark the scrub point. Passing `selectionDot` explicitly still opts it in.
   const selectionDotCfg = resolveSelectionDot(selectionDot ?? false);
   const gridStyleCfg = resolveGridStyle(gridStyle);
   const dotCfg = resolveMultiSeriesDot(dotProp);
@@ -224,6 +241,24 @@ function useLiveChartSeriesController({
 
   const allRefLines = referenceLines ?? [];
   const refValues = collectReferenceValues(allRefLines);
+  // Form-A lines a custom renderer owns keep their line stroke but suppress the
+  // built-in Skia tag. The callback is probed per line on the JS thread, matching
+  // LiveChart and CustomMarkerOverlay's per-item fallback model.
+  const refLineCustom = customReferenceLineFlags(
+    allRefLines,
+    renderReferenceLine,
+  );
+  // A full custom tag owns both states, so it takes precedence over an
+  // off-axis-only renderer for the same line.
+  const refLineOffAxisCustom = customReferenceLineFlags(
+    allRefLines,
+    renderOffAxisReferenceLine,
+    "off-axis",
+  ).map((custom, index) => custom && !refLineCustom[index]);
+  const refLineKeys = referenceLineReactKeys(allRefLines);
+  // RN custom tags report their measured widths here so the Skia connector can
+  // start after the native badge instead of the hidden built-in pill.
+  const refLineCustomTagWidths = useSharedValue<number[]>([]);
 
   const palette = applyPaletteOverride(
     resolveTheme(accentColor, theme),
@@ -253,9 +288,15 @@ function useLiveChartSeriesController({
     // render scope for memoization, which trips Reanimated's strict-mode warning;
     // it leaves the `.get()` method call inside the effect.
     // react-doctor-disable-next-line react-hooks-js/set-state-in-effect -- Reanimated: seeding from a SharedValue off render is the warning-free path
+    // eslint-disable-next-line react-hooks/set-state-in-effect -- Reanimated: seed from the SharedValue outside render to avoid strict-mode access warnings
     setSeriesSnapshot(series.get().slice());
   }, [series]);
 
+  // Mount per-series drawing worklets only for real series. The previous fixed
+  // 12-slot render kept 144 derived-value mappers alive for the default stroke,
+  // dot, and value-label layers even when a chart contained only one line.
+  const activeSeriesCount = Math.min(seriesSnapshot.length, MAX_MULTI_SERIES);
+
   const maxSeriesLabelWidth = dotCfg.valueLabel
     ? Math.max(
         0,
@@ -336,7 +377,11 @@ function useLiveChartSeriesController({
     nowOverride,
   });
   const { layoutHeight, onLayout } = useCanvasLayout(engine);
-  const linePaths = useMultiSeriesLinePaths(engine, effectivePadding);
+  const linePaths = useMultiSeriesLinePaths(
+    engine,
+    effectivePadding,
+    activeSeriesCount,
+  );
 
   // Per-series colors and stroke styles, derived from the off-render snapshot
   // (React state — so no Reanimated read-during-render). The reaction below
@@ -385,6 +430,20 @@ function useLiveChartSeriesController({
     skiaFont,
   );
 
+  // Cross-gesture arbitration for the one-finger touch. `Gesture.Race` below is
+  // NOT arbitration — RNGH's Race adds no relation between its children, so both
+  // pans recognize independently and each can activate while the other already
+  // owns the touch. This latch (written by the scroll pan, read by the scrub's
+  // long-press guard) makes "the scroll already won" a hard fact; `scrubActive`
+  // (written by the crosshair, read by the scroll pan) is the mirror image.
+  const scrollActive = useSharedValue(false);
+  // `liveEdge` includes the optional right breathing-room buffer. The time pill
+  // must clamp against the real "now" anchor so its live bucket never ends in
+  // that future buffer.
+  const tooltipMaxTime = useDerivedValue(
+    () => engine.liveEdge.get() - windowBuffer * timeWindow,
+  );
+
   const crosshair = useCrosshairSeries(
     engine,
     effectivePadding,
@@ -393,6 +452,17 @@ function useLiveChartSeriesController({
     scrubHoldMs,
     onGestureStart,
     onGestureEnd,
+    scrollActive,
+    seriesTooltipCfg
+      ? {
+          config: seriesTooltipCfg,
+          formatValue,
+          formatTime,
+          font: skiaFont,
+          colors: lineColors,
+          maxTime: tooltipMaxTime,
+        }
+      : undefined,
   );
 
   // Capture only the shared value in the worklets below. Referencing
@@ -436,6 +506,10 @@ function useLiveChartSeriesController({
     minTime: scrollMinTime,
     enabled: timeScrollEnabled,
     mode: scrollGestureMode,
+    scrollActive,
+    // Once a scrub is engaged the chart is locked: scrolling goes inert so the
+    // finger only moves the price indicator across a fixed window.
+    scrubActive: crosshairScrubActive,
     onScrollStart: () => {
       "worklet";
       crosshairScrubActive.set(false);
@@ -503,6 +577,7 @@ function useLiveChartSeriesController({
     // passthrough props the render needs
     series,
     style,
+    canvasMode,
     accessibilityLabel,
     accessibilityRole,
     emptyText,
@@ -512,6 +587,7 @@ function useLiveChartSeriesController({
     yAxisCfg,
     xAxisCfg,
     scrubCfg,
+    seriesTooltipCfg,
     gridStyleCfg,
     dotCfg,
     dotOuterRadius,
@@ -519,6 +595,10 @@ function useLiveChartSeriesController({
     degenCfg,
     metricsCfg,
     allRefLines,
+    refLineKeys,
+    refLineCustom,
+    refLineOffAxisCustom,
+    refLineCustomTagWidths,
     leftEdgeFadeCfg,
     // theme / layout / fonts
     palette,
@@ -540,6 +620,7 @@ function useLiveChartSeriesController({
     layoutHeight,
     onLayout,
     linePaths,
+    activeSeriesCount,
     lineColors,
     lineStyles,
     degenPack,
@@ -555,6 +636,9 @@ function useLiveChartSeriesController({
     markerGroupOpacity,
     overlayScrubFade,
     renderMarker,
+    renderOverlay,
+    renderReferenceLine,
+    renderOffAxisReferenceLine,
     // selection dot: resolved config + fallback color (the leading series' color)
     selectionDot: selectionDotCfg,
     selectionColor: lineColors[0],
@@ -610,6 +694,9 @@ function SeriesChartStack({ model }: { model: LiveChartSeriesModel }) {
     loadingStrokeWidth,
     loadingAmplitude,
     loadingSpeed,
+    canvasMode,
+    activeSeriesCount,
+    refLineKeys,
   } = model;
 
   return (
@@ -629,14 +716,12 @@ function SeriesChartStack({ model }: { model: LiveChartSeriesModel }) {
         </Group>
       )}
 
-      {/* Index keys: reference lines are a positional array and two may share
-          value + label (e.g. duplicate working orders at the same price), which a
-          content-derived key would collapse to one. Fade group lets
-          `scrub.hideOverlaysOnScrub` ease the lines out while scrubbing. */}
+      {/* Fade group lets `scrub.hideOverlaysOnScrub` ease the lines out. Explicit
+          ids keep each reference line mounted when the caller reorders it. */}
       <Group opacity={overlayScrubFade}>
         {allRefLines.map((rl, i) => (
           <ReferenceLineOverlay
-            key={i}
+            key={refLineKeys[i]}
             engine={engine}
             padding={effectivePadding}
             line={rl}
@@ -654,12 +739,13 @@ function SeriesChartStack({ model }: { model: LiveChartSeriesModel }) {
             padding={effectivePadding}
             colors={lineColors}
             config={dotCfg.valueLine}
+            seriesCount={activeSeriesCount}
           />
         </Group>
       )}
 
       <Group opacity={reveal.lineOpacity}>
-        {Array.from({ length: MAX_MULTI_SERIES }, (_, i) => (
+        {Array.from({ length: activeSeriesCount }, (_, i) => (
           <MultiSeriesStroke
             key={i}
             index={i}
@@ -694,6 +780,7 @@ function SeriesChartStack({ model }: { model: LiveChartSeriesModel }) {
             color={dotCfg.color}
             pulse={dotCfg.pulse}
             viewEnd={engine.viewEnd}
+            seriesCount={activeSeriesCount}
           />
         </Group>
       )}
@@ -749,6 +836,7 @@ function SeriesChartStack({ model }: { model: LiveChartSeriesModel }) {
         lineStrokeWidth={loadingStrokeWidth}
         waveAmplitude={loadingAmplitude}
         waveSpeed={loadingSpeed}
+        opaqueCanvas={canvasMode === "opaque"}
       />
     </Group>
   );
@@ -767,6 +855,7 @@ function SeriesValueLabelLayer({ model }: { model: LiveChartSeriesModel }) {
     skiaFont,
     reveal,
     degenShakeTransform,
+    activeSeriesCount,
   } = model;
   if (!dotCfg.valueLabel) return null;
   return (
@@ -778,6 +867,7 @@ function SeriesValueLabelLayer({ model }: { model: LiveChartSeriesModel }) {
           colors={lineColors}
           font={skiaFont}
           dotRadius={dotOuterRadius}
+          seriesCount={activeSeriesCount}
         />
       </Group>
     </Group>
@@ -789,6 +879,10 @@ function SeriesValueLabelLayer({ model }: { model: LiveChartSeriesModel }) {
 function SeriesRefBadgeLayer({ model }: { model: LiveChartSeriesModel }) {
   const {
     allRefLines,
+    refLineKeys,
+    refLineCustom,
+    refLineOffAxisCustom,
+    refLineCustomTagWidths,
     engine,
     effectivePadding,
     palette,
@@ -802,7 +896,7 @@ function SeriesRefBadgeLayer({ model }: { model: LiveChartSeriesModel }) {
     <Group transform={degenShakeTransform} opacity={overlayScrubFade}>
       {allRefLines.map((rl, i) => (
         <ReferenceLineOverlay
-          key={i}
+          key={refLineKeys[i]}
           engine={engine}
           padding={effectivePadding}
           line={rl}
@@ -810,12 +904,22 @@ function SeriesRefBadgeLayer({ model }: { model: LiveChartSeriesModel }) {
           formatValue={formatValue}
           font={skiaFont}
           badgeLayer
+          suppressTag={refLineCustom[i]}
+          suppressTagWhenOffAxis={refLineOffAxisCustom[i]}
+          customTagWidths={refLineCustomTagWidths}
         />
       ))}
     </Group>
   );
 }
 
+/** Owns the price/time projection worklets for the multi-series custom overlay. */
+function SeriesCustomConsumerOverlay({ model }: { model: LiveChartSeriesModel }) {
+  const { engine, effectivePadding, renderOverlay } = model;
+  const overlayContext = useChartOverlayContext(engine, effectivePadding);
+  return <ChartOverlayLayer render={renderOverlay!} context={overlayContext} />;
+}
+
 export function LiveChartSeries(props: LiveChartSeriesProps) {
   const model = useLiveChartSeriesController(props);
   const {
@@ -833,6 +937,7 @@ export function LiveChartSeries(props: LiveChartSeriesProps) {
     effectivePadding,
     engine,
     scrubCfg,
+    seriesTooltipCfg,
     crosshair,
     palette,
     dotCfg,
@@ -848,7 +953,17 @@ export function LiveChartSeries(props: LiveChartSeriesProps) {
     markersSV,
     markerClusterCfg,
     renderMarker,
+    renderOverlay,
+    renderReferenceLine,
+    renderOffAxisReferenceLine,
+    allRefLines,
+    refLineCustom,
+    refLineOffAxisCustom,
+    refLineCustomTagWidths,
     overlayScrubFade,
+    canvasMode,
+    activeSeriesCount,
+    skiaFont,
   } = model;
 
   // Mirror the Skia overlay fade onto the RN custom-marker sibling so
@@ -891,7 +1006,21 @@ export function LiveChartSeries(props: LiveChartSeriesProps) {
           else points map into a taller area and the x-axis draws past the edge. */}
       <GestureDetector gesture={rootGesture}>
         <View style={{ flex: 1 }} onLayout={onLayout}>
-          <Canvas style={{ flex: 1, minHeight: layoutHeight || 1 }}>
+          {/* Skia chooses TextureView vs SurfaceView when the native Canvas mounts. */}
+          <Canvas
+            key={canvasMode}
+            style={{ flex: 1, minHeight: layoutHeight || 1 }}
+            opaque={canvasMode === "opaque"}
+          >
+            {canvasMode === "opaque" && (
+              <Rect
+                x={0}
+                y={0}
+                width={engine.canvasWidth}
+                height={engine.canvasHeight}
+                color={backgroundColor}
+              />
+            )}
             <SeriesChartStack model={model} />
 
             {/* "extrema-edge" connector lines (dot → edge readout). Outside the
@@ -910,6 +1039,9 @@ export function LiveChartSeries(props: LiveChartSeriesProps) {
                 startColor={leftEdgeFadeCfg.startColor}
                 endColor={leftEdgeFadeCfg.endColor}
                 engine={engine}
+                opaqueBackgroundRgb={
+                  canvasMode === "opaque" ? palette.bgRgb : undefined
+                }
               />
             )}
 
@@ -929,15 +1061,37 @@ export function LiveChartSeries(props: LiveChartSeriesProps) {
                 selectionColor={selectionColor}
                 dimOpacity={scrubCfg.dimOpacity}
                 liveDotExtent={liveDotExtent}
-                crosshairLineColor={scrubCfg.crosshairLineColor}
-                crosshairDash={scrubCfg.crosshairDash}
+                crosshairLineColor={
+                  seriesTooltipCfg?.guideColor ??
+                  scrubCfg.crosshairLineColor
+                }
+                crosshairLineWidth={seriesTooltipCfg?.guideWidth}
+                crosshairDash={
+                  seriesTooltipCfg
+                    ? seriesTooltipCfg.guideDashPattern
+                    : scrubCfg.crosshairDash
+                }
                 crosshairDimColor={scrubCfg.crosshairDimColor}
+                opaqueCanvas={canvasMode === "opaque"}
               />
             )}
 
             {/* Per-series value labels on top of the scrub dim so the dim never
                 clips them (they track each series' live value, not the scrub). */}
             <SeriesValueLabelLayer model={model} />
+
+            {seriesTooltipCfg && (
+              <PerSeriesTooltipOverlay
+                layout={crosshair.tooltipLayout}
+                font={skiaFont}
+                palette={palette}
+                config={seriesTooltipCfg}
+                seriesCount={activeSeriesCount}
+                tooltipBackground={scrubCfg?.tooltipBackground}
+                tooltipColor={scrubCfg?.tooltipColor}
+                tooltipBorderColor={scrubCfg?.tooltipBorderColor}
+              />
+            )}
           </Canvas>
 
           {/* RN labels floated over the canvas (sibling of <Canvas>, an RN
@@ -952,25 +1106,56 @@ export function LiveChartSeries(props: LiveChartSeriesProps) {
             padding={effectivePadding}
           />
 
-          {/* Custom-rendered markers — RN views floated over the canvas
-              (non-Skia), pinned to each marker's live position. Box-none fade
-              wrapper so `scrub.hideOverlaysOnScrub` hides them with the Skia
-              markers (full-bleed; children keep their own absolute positions). */}
-          {markersActive && renderMarker && (
+          {/* Custom annotations — RN views floated over the canvas (non-Skia),
+              pinned to their live positions. As a post-Canvas sibling they render
+              above the left-edge fade and scrub overlay. The box-none fade wrapper
+              keeps `scrub.hideOverlaysOnScrub` behavior aligned with Skia. */}
+          {((markersActive && renderMarker) ||
+            ((renderReferenceLine || renderOffAxisReferenceLine) &&
+              allRefLines.length > 0)) && (
             <Animated.View
               pointerEvents="box-none"
               style={[StyleSheet.absoluteFill, overlayFadeStyle]}
             >
-              <CustomMarkerOverlay
-                markers={markersSV}
-                renderMarker={renderMarker}
-                engine={engine}
-                padding={effectivePadding}
-                series={series}
-                cluster={markerClusterCfg}
-              />
+              {markersActive && renderMarker && (
+                <CustomMarkerOverlay
+                  markers={markersSV}
+                  renderMarker={renderMarker}
+                  engine={engine}
+                  padding={effectivePadding}
+                  series={series}
+                  cluster={markerClusterCfg}
+                />
+              )}
+              {renderReferenceLine && allRefLines.length > 0 && (
+                <CustomReferenceLineOverlay
+                  lines={allRefLines}
+                  renderReferenceLine={renderReferenceLine}
+                  custom={refLineCustom}
+                  engine={engine}
+                  padding={effectivePadding}
+                  formatValue={formatValue}
+                  tagWidths={refLineCustomTagWidths}
+                />
+              )}
+              {renderOffAxisReferenceLine && allRefLines.length > 0 && (
+                <CustomReferenceLineOverlay
+                  lines={allRefLines}
+                  renderReferenceLine={renderOffAxisReferenceLine}
+                  custom={refLineOffAxisCustom}
+                  engine={engine}
+                  padding={effectivePadding}
+                  formatValue={formatValue}
+                  tagWidths={refLineCustomTagWidths}
+                  offAxisOnly
+                />
+              )}
             </Animated.View>
           )}
+
+          {/* Custom consumer overlay — topmost RN sibling with the live plot
+              rect, including this multi-series chart's resolved axis inset. */}
+          {renderOverlay && <SeriesCustomConsumerOverlay model={model} />}
         </View>
       </GestureDetector>
       {legendCfg.position === "bottom" ? legend : null}

package/src/components/LoadingOverlay.tsx

@@ -8,6 +8,7 @@ import {
   vec,
   type SkFont,
 } from "@shopify/react-native-skia";
+import { useRef } from "react";
 import { useDerivedValue, type SharedValue } from "react-native-reanimated";
 import {
   BADGE_METRICS_DEFAULTS,
@@ -67,6 +68,7 @@ export function LoadingOverlay({
   lineStrokeWidth,
   waveAmplitude = 14,
   waveSpeed = 1,
+  opaqueCanvas = false,
 }: {
   engine: ChartEngineLayout;
   padding: ChartPadding;
@@ -86,6 +88,8 @@ export function LoadingOverlay({
   waveAmplitude?: number;
   /** Breathing-wave speed multiplier. */
   waveSpeed?: number;
+  /** Paint the owned background instead of erasing destination alpha. */
+  opaqueCanvas?: boolean;
   /** Mirror the badge prop so labels align with GridOverlay's label positions. */
   badge?: boolean;
   /** Whether the badge tail spike is shown; affects the left inset used for skeleton alignment. */
@@ -99,15 +103,26 @@ export function LoadingOverlay({
 }) {
   // Same left-inset formula as GridOverlay (only used when badge=true)
   const leftInset =
-    badgeMetrics.dotGap + badgeTailAndCap(font.getSize(), badgeTail, badgeMetrics);
+    badgeMetrics.dotGap +
+    badgeTailAndCap(font.getSize(), badgeTail, badgeMetrics);
 
   // Loading-shell color (squiggle + skeleton placeholders) and squiggle stroke,
   // both overridable via `loading={{ color, strokeWidth }}`.
   const loadingColor = lineColor ?? palette.gridLine;
   const loadingStroke = lineStrokeWidth ?? strokeWidth;
+  const [bgR, bgG, bgB] = palette.bgRgb;
+  const gapMaskColors = opaqueCanvas
+    ? [
+        `rgba(${bgR},${bgG},${bgB},0)`,
+        `rgb(${bgR},${bgG},${bgB})`,
+        `rgb(${bgR},${bgG},${bgB})`,
+        `rgba(${bgR},${bgG},${bgB},0)`,
+      ]
+    : ["rgba(0,0,0,0)", "rgba(0,0,0,1)", "rgba(0,0,0,1)", "rgba(0,0,0,0)"];
 
   // Squiggly path — built into a reused PathBuilder and detach()-ed each frame.
   const squigglyBuilder = usePathBuilder();
+  const squigglyPtsRef = useRef<number[]>([]);
 
   // Squiggly path — animated each frame via timestamp
   const squigglyPath = useDerivedValue(() => {
@@ -122,6 +137,7 @@ export function LoadingOverlay({
       engine.timestamp.get(),
       waveAmplitude,
       waveSpeed,
+      squigglyPtsRef.current,
     );
     return buildSplineDetached(b, pts);
   });
@@ -254,17 +270,15 @@ export function LoadingOverlay({
       />
 
       {/* Erase a soft horizontal band through the squiggle for the label (dstOut) */}
-      <Group opacity={showGapGroup} blendMode="dstOut">
+      <Group
+        opacity={showGapGroup}
+        blendMode={opaqueCanvas ? undefined : "dstOut"}
+      >
         <Rect x={gapLeft} y={gapTop} width={gapWidth} height={gapHeight}>
           <LinearGradient
             start={vec(0, 0)}
             end={gapGradEnd}
-            colors={[
-              "rgba(0,0,0,0)",
-              "rgba(0,0,0,1)",
-              "rgba(0,0,0,1)",
-              "rgba(0,0,0,0)",
-            ]}
+            colors={gapMaskColors}
             positions={gapGradientPositions}
           />
         </Rect>
@@ -279,7 +293,7 @@ export function LoadingOverlay({
             width={RECT_W}
             height={RECT_H}
             r={RECT_R}
-        color={loadingColor}
+            color={loadingColor}
           />
           <RoundedRect
             x={lx}
@@ -287,7 +301,7 @@ export function LoadingOverlay({
             width={RECT_W}
             height={RECT_H}
             r={RECT_R}
-        color={loadingColor}
+            color={loadingColor}
           />
           <RoundedRect
             x={lx}
@@ -295,7 +309,7 @@ export function LoadingOverlay({
             width={RECT_W}
             height={RECT_H}
             r={RECT_R}
-        color={loadingColor}
+            color={loadingColor}
           />
           <RoundedRect
             x={lx}
@@ -303,7 +317,7 @@ export function LoadingOverlay({
             width={RECT_W}
             height={RECT_H}
             r={RECT_R}
-        color={loadingColor}
+            color={loadingColor}
           />
         </>
       ) : null}

package/src/components/MarkerOverlay.tsx

@@ -351,6 +351,18 @@ export function MarkerOverlay({
   if (projRef.current === null) {
     projRef.current = { a: [], b: [], tick: false };
   }
+  const atlasFrameRef = useRef<{
+    a: { transforms: SkRSXform[]; sprites: SkRect[] };
+    b: { transforms: SkRSXform[]; sprites: SkRect[] };
+    tick: boolean;
+  } | null>(null);
+  if (atlasFrameRef.current === null) {
+    atlasFrameRef.current = {
+      a: { transforms: [], sprites: [] },
+      b: { transforms: [], sprites: [] },
+      tick: false,
+    };
+  }
 
   // Single per-frame worklet: project all markers, then emit a transform +
   // source rect for each visible atlas marker. Three mappers total regardless
@@ -377,8 +389,13 @@ export function MarkerOverlay({
         lineLinear,
       });
       clusterMarkers(ms, buf, { config: cluster });
-      const transforms: SkRSXform[] = [];
-      const sprites: SkRect[] = [];
+      const atlasFrames = atlasFrameRef.current!;
+      atlasFrames.tick = !atlasFrames.tick;
+      const frame = atlasFrames.tick ? atlasFrames.a : atlasFrames.b;
+      const transforms = frame.transforms;
+      const sprites = frame.sprites;
+      transforms.length = 0;
+      sprites.length = 0;
       for (let i = 0; i < ms.length; i++) {
         const pt = buf[i];
         // Collapsed-cluster members fold into their representative's badge.
@@ -455,7 +472,7 @@ export function MarkerOverlay({
         );
         sprites.push(cell.rect);
       }
-      return { transforms, sprites };
+      return frame;
     },
     [
       cells,