@wick-charts/react 0.3.5 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wick-charts/react",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "description": "High-performance canvas timeseries charts for React — candlestick, line, bar, pie. Tree-shakeable, zero runtime deps.",
   "license": "MIT",
   "repository": {
@@ -8,7 +8,7 @@
     "url": "git+https://github.com/mo4islona/wick-charts.git",
     "directory": "packages/react"
   },
-  "homepage": "https://mo4islona.github.io/wick-charts/",
+  "homepage": "https://wick-charts.eeff.io/",
   "bugs": "https://github.com/mo4islona/wick-charts/issues",
   "keywords": [
     "charts",
@@ -49,7 +49,7 @@
     "react-dom": ">=18.0.0"
   },
   "devDependencies": {
-    "@wick-charts/core": "^0.3.5"
+    "@wick-charts/core": "^0.4.0"
   },
   "scripts": {
     "build": "vite build"

package/src/BarSeries.tsx

@@ -1,6 +1,12 @@
 import { useEffect, useLayoutEffect, useRef } from 'react';
 
-import { type BarSeriesOptions, type TimePoint, normalizeTime } from '@wick-charts/core';
+import {
+  type BarSeriesOptions,
+  EMPTY_SYNC_STATE,
+  type SeriesSyncState,
+  type TimePoint,
+  syncSeriesLayer,
+} from '@wick-charts/core';
 
 import { useChartInstance } from './context';
 
@@ -13,30 +19,19 @@ export interface BarSeriesProps {
   id?: string;
 }
 
-/** Only fall back to a full `setSeriesData` replace when more than this many new
- * points appear in a single tick — otherwise streamed updates would always look
- * like bulk loads and the renderer would clear its entrance-animation entries. */
-const BULK_THRESHOLD = 20;
-
 export function BarSeries({ data, options, id: idProp }: BarSeriesProps) {
   const chart = useChartInstance();
   const seriesRef = useRef<string | null>(null);
-  const prevLensRef = useRef<number[]>([]);
-  const prevFirstTimesRef = useRef<(number | null)[]>([]);
-  const prevLastTimesRef = useRef<(number | null)[]>([]);
+  const prevSyncRef = useRef<SeriesSyncState[]>([]);
 
   useLayoutEffect(() => {
-    const id = chart.addBarSeries({ ...options, layers: data.length, id: idProp });
+    const id = chart.addSeries('bar', { ...options, layers: data.length, id: idProp });
     seriesRef.current = id;
-    prevLensRef.current = new Array(data.length).fill(0);
-    prevFirstTimesRef.current = new Array(data.length).fill(null);
-    prevLastTimesRef.current = new Array(data.length).fill(null);
+    prevSyncRef.current = new Array(data.length).fill(EMPTY_SYNC_STATE);
     return () => {
       chart.removeSeries(id);
       seriesRef.current = null;
-      prevLensRef.current = [];
-      prevFirstTimesRef.current = [];
-      prevLastTimesRef.current = [];
+      prevSyncRef.current = [];
     };
   }, [chart, data.length, idProp]);
 
@@ -46,44 +41,13 @@ export function BarSeries({ data, options, id: idProp }: BarSeriesProps) {
 
     chart.batch(() => {
       for (let i = 0; i < data.length; i++) {
-        const layer = data[i];
-        const prevLen = prevLensRef.current[i] ?? 0;
-        const prevFirst = prevFirstTimesRef.current[i] ?? null;
-
-        if (layer.length === 0) {
-          chart.setSeriesData(id, [], i);
-          prevLensRef.current[i] = 0;
-          prevFirstTimesRef.current[i] = null;
-          prevLastTimesRef.current[i] = null;
-          continue;
-        }
-
-        const firstTime = normalizeTime(layer[0].time);
-        const lastTime = normalizeTime(layer[layer.length - 1].time);
-        const prevLast = prevLastTimesRef.current[i] ?? null;
-        const shifted = prevFirst !== null && prevFirst !== firstTime;
-        const added = layer.length - prevLen;
-        const hasNewLast = prevLast !== null && prevLast !== lastTime;
-
-        // Rolling-window slide (maxPoints cap): drop oldest, append newest,
-        // length unchanged. Sync prefix then appendData the new tail so the
-        // entrance animation fires instead of getting wiped by setSeriesData.
-        if (shifted && added === 0 && hasNewLast) {
-          chart.setSeriesData(id, layer.slice(0, -1), i);
-          chart.appendData(id, layer[layer.length - 1], i);
-        } else if (prevLen === 0 || layer.length < prevLen || added > BULK_THRESHOLD || shifted) {
-          chart.setSeriesData(id, layer, i);
-        } else if (layer.length === prevLen) {
-          chart.updateData(id, layer[layer.length - 1], i);
-        } else {
-          for (let j = prevLen; j < layer.length; j++) {
-            chart.appendData(id, layer[j], i);
-          }
-        }
-
-        prevLensRef.current[i] = layer.length;
-        prevFirstTimesRef.current[i] = firstTime;
-        prevLastTimesRef.current[i] = lastTime;
+        prevSyncRef.current[i] = syncSeriesLayer({
+          chart,
+          id,
+          data: data[i],
+          prev: prevSyncRef.current[i] ?? EMPTY_SYNC_STATE,
+          layerIndex: i,
+        });
       }
     });
   }, [chart, data]);
@@ -98,9 +62,7 @@ export function BarSeries({ data, options, id: idProp }: BarSeriesProps) {
     options?.barWidthRatio,
     options?.stacking,
     options?.entryAnimation,
-    options?.enterAnimation,
     options?.entryMs,
-    options?.enterMs,
     options?.smoothMs,
   ]);
 

package/src/CandlestickSeries.tsx

@@ -1,16 +1,15 @@
 import { useEffect, useLayoutEffect, useRef } from 'react';
 
-import type { CandlestickSeriesOptions, OHLCInput } from '@wick-charts/core';
-import { normalizeTime } from '@wick-charts/core';
+import {
+  type CandlestickSeriesOptions,
+  EMPTY_SYNC_STATE,
+  type OHLCInput,
+  type SeriesSyncState,
+  syncSeriesLayer,
+} from '@wick-charts/core';
 
 import { useChartInstance } from './context';
 
-/** Only fall back to a full `setSeriesData` replace when more than this many new
- * candles appear in a single tick. Streamed bursts (OHLCStream emits up to ~8
- * per 500ms) must stay under this so their appendData path still fires entrance
- * animations; history loads (50/batch) deliberately exceed it. */
-const BULK_THRESHOLD = 20;
-
 export interface CandlestickSeriesProps {
   /** OHLC candles to render. Each element carries `time/open/high/low/close` and an optional `volume`. */
   data: OHLCInput[];
@@ -23,19 +22,15 @@ export interface CandlestickSeriesProps {
 export function CandlestickSeries({ data, options, id: idProp }: CandlestickSeriesProps) {
   const chart = useChartInstance();
   const seriesRef = useRef<string | null>(null);
-  const prevLenRef = useRef(0);
-  const prevFirstTimeRef = useRef<number | null>(null);
-  const prevLastTimeRef = useRef<number | null>(null);
+  const prevSyncRef = useRef<SeriesSyncState>(EMPTY_SYNC_STATE);
 
   useLayoutEffect(() => {
-    const id = chart.addCandlestickSeries({ ...options, id: idProp });
+    const id = chart.addSeries('candlestick', { ...options, id: idProp });
     seriesRef.current = id;
     return () => {
       chart.removeSeries(id);
       seriesRef.current = null;
-      prevLenRef.current = 0;
-      prevFirstTimeRef.current = null;
-      prevLastTimeRef.current = null;
+      prevSyncRef.current = EMPTY_SYNC_STATE;
     };
   }, [chart, idProp]);
 
@@ -43,46 +38,7 @@ export function CandlestickSeries({ data, options, id: idProp }: CandlestickSeri
     const id = seriesRef.current;
     if (!id) return;
 
-    if (data.length === 0) {
-      // Explicit clear
-      chart.setSeriesData(id, []);
-      prevLenRef.current = 0;
-      prevFirstTimeRef.current = null;
-      prevLastTimeRef.current = null;
-      return;
-    }
-
-    const prevLen = prevLenRef.current;
-    const prevFirst = prevFirstTimeRef.current;
-    const prevLast = prevLastTimeRef.current;
-    const firstTime = normalizeTime(data[0].time);
-    const lastTime = normalizeTime(data[data.length - 1].time);
-    const shifted = prevFirst !== null && prevFirst !== firstTime;
-    const added = data.length - prevLen;
-    const hasNewLast = prevLast !== null && prevLast !== lastTime;
-
-    // Rolling-window slide: same array length but first AND last timestamps
-    // advanced (old point dropped, new point appended). Must NOT fall through
-    // to a full `setSeriesData` — that would wipe the entrance-animation
-    // entries. Sync the stable prefix, then appendData the fresh tail so the
-    // renderer registers an entry for just the new point.
-    if (shifted && added === 0 && hasNewLast) {
-      chart.setSeriesData(id, data.slice(0, -1));
-      chart.appendData(id, data[data.length - 1]);
-    } else if (prevLen === 0 || data.length < prevLen || added > BULK_THRESHOLD || shifted) {
-      chart.setSeriesData(id, data);
-    } else if (data.length === prevLen) {
-      // Same length, same timestamps — last candle updated in place.
-      chart.updateData(id, data[data.length - 1]);
-    } else {
-      for (let i = prevLen; i < data.length; i++) {
-        chart.appendData(id, data[i]);
-      }
-    }
-
-    prevLenRef.current = data.length;
-    prevFirstTimeRef.current = firstTime;
-    prevLastTimeRef.current = lastTime;
+    prevSyncRef.current = syncSeriesLayer({ chart, id, data, prev: prevSyncRef.current });
   }, [chart, data]);
 
   useEffect(() => {
@@ -100,9 +56,7 @@ export function CandlestickSeries({ data, options, id: idProp }: CandlestickSeri
     options?.down?.wick,
     options?.bodyWidthRatio,
     options?.entryAnimation,
-    options?.enterAnimation,
     options?.entryMs,
-    options?.enterMs,
     options?.smoothMs,
   ]);
 

package/src/ChartContainer.tsx

@@ -17,6 +17,8 @@ import {
   ChartInstance,
   type ChartOptions,
   type ChartTheme,
+  type EdgeReachedInfo,
+  type VisibleRangeSpec,
 } from '@wick-charts/core';
 
 type PerfOption = NonNullable<ChartOptions['perf']>;
@@ -62,6 +64,30 @@ export interface ChartContainerProps {
      */
     left?: number | { intervals: number };
   };
+  /**
+   * Viewport-level streaming behavior. Captured at mount only — changing this
+   * prop after the chart is created is ignored.
+   */
+  viewport?: {
+    /**
+     * Width of the visible window in data bars, set on the first data load
+     * to `maxVisibleBars * dataInterval`. While the dataset is smaller than
+     * this width, streaming ticks render into the empty right-side gap and
+     * the viewport stays put; once the data reaches the right edge, the
+     * viewport pans forward to keep the latest bar pinned (tail-scroll).
+     * Default: 200.
+     */
+    maxVisibleBars?: number;
+    /**
+     * Initial visible range applied before the first paint with data. Same
+     * shape as the imperative `chart.setVisibleRange` — pass a bar count
+     * (e.g. `35`), an explicit `{from, to}` window, or `{from, bars}` for
+     * a warm-up pair. The standard alternative is calling
+     * `setVisibleRange` from a `useEffect`, but that runs post-paint and
+     * makes the chart visibly re-zoom on the next RAF. Captured at mount.
+     */
+    initialRange?: VisibleRangeSpec;
+  };
   /** Show the chart background gradient. Defaults to true. */
   gradient?: boolean;
   /** Enable zoom, pan, and crosshair interactions. Defaults to true. */
@@ -81,33 +107,16 @@ export interface ChartContainerProps {
    */
   headerLayout?: 'overlay' | 'inline';
   /**
-   * Chart-level animation configuration. See {@link AnimationsConfig} for the
-   * full shape.
-   *
-   * Two layers — remember which is which:
-   *
-   * - **Chart-level (this prop)** — `animations.points.{enterMs, smoothMs,
-   *   pulseMs}` and `animations.viewport.{reboundMs, yAxisMs,
-   *   inputResponseMs}`. Acts as the default for every series.
-   * - **Per-series** — `<LineSeries options={{ entryMs, smoothMs, pulseMs }}>`
-   *   (and the analogous CandlestickSeries / BarSeries options). Overrides
-   *   the chart-level default for that one series. Note the spelling:
-   *   `entryMs` per-series, `enterMs` chart-level — historical artefact,
-   *   both refer to the same animation.
+   * Animation control. `true` / omitted uses built-in defaults; `false`
+   * disables every category. Per-series options on `<LineSeries>` /
+   * `<CandlestickSeries>` / `<BarSeries>` override these chart-level
+   * defaults unless the category here is explicitly `false`.
    *
-   * Resolution: per-series option wins over chart-level numeric value.
-   * Chart-level wins only when its category is explicitly `false` — that's
-   * a hard disable that overrides per-series too.
-   *
-   * Shorthands:
-   * - `true` / omitted — built-in defaults (every settling animation 250 ms,
-   *   pulse cycle 600 ms, input ease 0 / off).
-   * - `false` — disables every animation category.
-   * - `{ points: false }` / `{ viewport: false }` — disables a category.
-   *
-   * Runtime updates: changing this prop after mount calls
-   * `chart.setAnimations(...)` so the new durations take effect on the next
-   * animation / render.
+   * **Init-only by reference identity.** A new `animations` object
+   * recreates the underlying `ChartInstance` (and its canvas). Wrap the
+   * value in `useMemo(() => ({...}), [deps])` so an unstable parent
+   * render doesn't tear down the chart every commit. In dev mode the
+   * container emits a console warning when it detects >3 recreates / s.
    */
   animations?: boolean | AnimationsConfig;
   /**
@@ -120,6 +129,18 @@ export interface ChartContainerProps {
    * Only read at mount; changing this prop after the chart is created is ignored.
    */
   perf?: PerfOption;
+  /**
+   * Fired after the user releases a pan/zoom gesture that pulled the viewport
+   * past a data edge by more than ~10% of the visible range. Hosts typically
+   * respond by prefetching more history.
+   *
+   * For threshold-based prefetch (load *before* the user fully overshoots),
+   * use `<EdgeLoader>` instead — that component subscribes to `viewportChange`
+   * and arms when the visible range nears the data edge.
+   *
+   * Captured at mount only; changing the prop identity later is ignored.
+   */
+  onEdgeReached?: (info: EdgeReachedInfo) => void;
   /** Inline style for the chart's outer wrapper element. */
   style?: CSSProperties;
   /** Extra class for the chart's outer wrapper element. */
@@ -214,18 +235,22 @@ export function ChartContainer({
   theme,
   axis,
   padding,
+  viewport,
   gradient = true,
   interactive,
   grid,
   headerLayout = 'overlay',
   perf,
   animations,
+  onEdgeReached,
   style,
   className,
 }: ChartContainerProps) {
   // Mount-only: capture the initial perf option in a ref so later renders with
   // a new object identity don't recreate the chart or remount the HUD.
   const perfRef = useRef(perf);
+  // Same mount-only capture for the edge callback — the chart binds it once.
+  const onEdgeReachedRef = useRef(onEdgeReached);
   const contextTheme = useThemeOptional();
   const resolvedTheme = theme ?? contextTheme ?? undefined;
 
@@ -233,39 +258,65 @@ export function ChartContainer({
   const chartRef = useRef<ChartInstance | null>(null);
   const [_, setRevision] = useState(0);
 
-  // useLayoutEffect — synchronous, runs before paint.
+  // Dev-only: warn when `animations` reference identity changes more than
+  // three times per second. The most common cause is a parent re-rendering
+  // with a fresh inline object; ChartInstance is no longer reconfigurable
+  // post-construction, so each new reference is a full canvas teardown.
+  const recreateStampsRef = useRef<number[]>([]);
+
+  // useLayoutEffect — synchronous, runs before paint. Re-runs when
+  // `animations` changes by reference: chart-level animation timings, the
+  // Y transition factory and per-series timings are init-only contracts
+  // in Phase 2, so a new `animations` object is a full rebuild.
+  //
+  // TODO(api): this identity-based init-only contract is fragile — any
+  // streaming caller that forgets to wrap `animations` in useMemo gets
+  // a destroy+recreate on every tick (see docs/pages/stress/streaming.tsx
+  // for the worked example: ~30 rebuilds/sec at 32ms intervals). Either
+  // diff structurally here, or split the init-only sub-fields (the Y
+  // transition factory and per-series timings) into a separate prop with
+  // a name that signals "stable identity required", so the common
+  // chart-level timings can stay live-updatable.
   useLayoutEffect(() => {
     if (!containerRef.current) return;
-    if (chartRef.current) return;
 
     const options: ChartOptions = {};
     if (axis) options.axis = axis;
     if (resolvedTheme) options.theme = resolvedTheme;
     if (padding) options.padding = padding;
+    if (viewport) options.viewport = viewport;
     if (interactive !== undefined) options.interactive = interactive;
     if (grid !== undefined) options.grid = grid;
     if (perfRef.current !== undefined) options.perf = perfRef.current;
     if (animations !== undefined) options.animations = animations;
+    if (onEdgeReachedRef.current) options.onEdgeReached = onEdgeReachedRef.current;
     chartRef.current = new ChartInstance(containerRef.current, options);
 
-    // Note: the init path above already propagated `grid` into the chart. The
-    // effect below handles live updates, but also needs to run on the same
-    // commit so an initial `grid={{visible:false}}` isn't silently reset.
+    if (process.env.NODE_ENV !== 'production') {
+      const now = performance.now();
+      const stamps = recreateStampsRef.current;
+      stamps.push(now);
+      while (stamps.length > 0 && now - stamps[0] > 1000) stamps.shift();
+      if (stamps.length > 3) {
+        console.warn(
+          '[wick-charts] <ChartContainer> recreated the chart >3 times in the last second. ' +
+            'The `animations` prop is init-only — wrap it in useMemo(() => ({...}), [deps]) ' +
+            'so a stable reference identity prevents tear-down on every render.',
+        );
+      }
+    }
+
+    // The init path above already propagated `grid` into the chart. The
+    // effect below also writes it for live updates, but it needs to fire
+    // on the same commit so an initial `grid={{visible:false}}` isn't
+    // silently reset.
     setRevision((r) => r + 1);
 
     return () => {
-      // Destroy synchronously. A previous revision deferred this through
-      // `setTimeout(..., 0)` to "tolerate StrictMode" but the guard was
-      // broken: in the StrictMode remount sequence (cleanup → second mount →
-      // timeout), the check `if (!chartRef.current) instance.destroy()`
-      // always saw the second instance and skipped the destroy — leaking
-      // the first ChartInstance's canvases (hence 4 canvases per chart in
-      // dev). StrictMode exists precisely to exercise cleanup; a correct
-      // `destroy` is cheap enough to run on every cycle.
       chartRef.current?.destroy();
       chartRef.current = null;
     };
-  }, []);
+  }, [animations]);
 
   useEffect(() => {
     if (chartRef.current && resolvedTheme) {
@@ -279,16 +330,6 @@ export function ChartContainer({
     }
   }, [axis?.y?.width, axis?.y?.min, axis?.y?.max, axis?.y?.visible, axis?.x?.height, axis?.x?.visible]);
 
-  useEffect(() => {
-    if (chartRef.current && animations !== undefined) {
-      chartRef.current.setAnimations(animations);
-    }
-    // Dep array is the JSON shape of the config — covers both the boolean
-    // shorthand and the full object. Cheap to stringify (the object is tiny)
-    // and lets callers pass a fresh reference each render without thrashing
-    // animator state when nothing has actually changed.
-  }, [JSON.stringify(animations)]);
-
   // Top-overlay height (title + info bar) — measured below. Declared here so
   // the padding effect can fold it into `padding.top`.
   const topOverlayRef = useRef<HTMLDivElement>(null);
@@ -301,7 +342,12 @@ export function ChartContainer({
   // fire redundant `chart.setPadding(...)` calls (headerExtra stays 0).
   const headerExtra = headerLayout === 'overlay' ? topOverlayHeight : 0;
 
-  useEffect(() => {
+  // useLayoutEffect (not useEffect) so the header-height fold-in lands
+  // before the browser paints the chart for the first time. With
+  // `useEffect` the padding update would fire AFTER paint, causing a
+  // visible "chart drawn, then everything shifts down by the header
+  // height on the next frame" jump on initial mount.
+  useLayoutEffect(() => {
     const current = chartRef.current;
     if (!current) return;
     const userTop = padding?.top ?? 20;

package/src/EdgeLoader.tsx

@@ -0,0 +1,187 @@
+import { type ReactNode, useEffect, useRef, useState } from 'react';
+
+import type { EdgeSide } from '@wick-charts/core';
+
+import { useChartInstance } from './context';
+
+/** Argument shape passed to the {@link EdgeLoader} render-prop. */
+export interface EdgeLoaderRenderArgs {
+  /**
+   * CSS pixels in the chart's overlay coordinate space, anchored at the data
+   * edge (`data.from` for `side='left'`, `data.to` for `side='right'`).
+   * The overlay div is positioned with `inset: 0`, so this value can be used
+   * directly as `style={{ left: x }}` or `transform: translateX(...)`.
+   */
+  x: number;
+  side: EdgeSide;
+  /** True between {@link EdgeLoaderProps.onTrigger} firing and its Promise resolving. */
+  isLoading: boolean;
+  /** Time coordinate (ms) of the data edge — convenient for "fetch history before T" requests. */
+  boundaryTime: number;
+  /** Becomes `false` after `onTrigger` resolves with the literal value `false`. */
+  hasMore: boolean;
+}
+
+export interface EdgeLoaderProps {
+  /** Which edge to watch. */
+  side: EdgeSide;
+  /**
+   * Bars from the edge that arms the trigger. Multiplied by the chart's data
+   * interval. Default `5`.
+   */
+  threshold?: number;
+  /**
+   * Called when the visible range moves within {@link EdgeLoaderProps.threshold}
+   * bars of the data edge. Returning a Promise toggles `isLoading` for its
+   * lifetime. **Resolve with `false`** to signal "no more data" — the loader
+   * stops watching and switches the optional canvas indicator to its
+   * `'no-data'` state. Any other resolve value (including `undefined`) means
+   * "keep watching for the next near-edge event".
+   */
+  // biome-ignore lint/suspicious/noConfusingVoidType: void allows callers to write `() => fetch()` without an explicit return
+  onTrigger: () => void | Promise<unknown>;
+  /**
+   * - `'canvas'` (default): drive the chart's built-in canvas spinner via
+   *   {@link ChartInstance.setEdgeState}. Renders inside the chart area at
+   *   the data boundary.
+   * - `'custom'`: skip the canvas indicator. Use the render-prop `children`
+   *   to draw your own DOM/SVG loader.
+   */
+  indicator?: 'canvas' | 'custom';
+  /**
+   * Optional render-prop. Receives the live edge state — render whatever
+   * positioned overlay you want, or return `null`.
+   */
+  children?: (args: EdgeLoaderRenderArgs) => ReactNode;
+}
+
+/**
+ * Subscribes to the chart's viewport and triggers a fetch when the visible
+ * range nears the chosen data edge. Handles the boilerplate every load-on-scroll
+ * site otherwise has to re-implement: arming after first user pan, deduping
+ * via Promise tracking, and exposing the boundary's pixel coordinate so a
+ * loader can be anchored to "the wall of available history".
+ *
+ * Place as a child of `<ChartContainer>`.
+ */
+export function EdgeLoader({ side, threshold = 5, onTrigger, indicator = 'canvas', children }: EdgeLoaderProps) {
+  const chart = useChartInstance();
+  const [isLoading, setIsLoading] = useState(false);
+  const [hasMore, setHasMore] = useState(true);
+  // Bump on viewportChange / overlayChange so the render-prop re-runs with
+  // the latest pixel x. State, not ref, because we want the re-render.
+  const [, setTick] = useState(0);
+
+  const triggerRef = useRef(onTrigger);
+  triggerRef.current = onTrigger;
+  // Stash `children` in a ref so the effect doesn't have to rebind listeners
+  // on every render-prop identity change, and so the bump-on-change gate can
+  // read the latest value without putting `children` in deps.
+  const hasChildrenRef = useRef(children !== undefined);
+  hasChildrenRef.current = children !== undefined;
+  const inflight = useRef(false);
+  // Largest "distance from edge" (in time units) seen so far — gate the
+  // trigger on it crossing the threshold once, so the initial fit-to-data
+  // (where visible === data) doesn't fire the loader on mount.
+  const armed = useRef(false);
+
+  useEffect(() => {
+    if (!hasMore) return;
+
+    const distanceFromEdge = (): number | null => {
+      const visible = chart.getVisibleRange();
+      const data = chart.getDataRange();
+      if (!data) return null;
+
+      return side === 'left' ? visible.from - data.from : data.to - visible.to;
+    };
+
+    const fire = () => {
+      if (inflight.current || !hasMore) return;
+
+      inflight.current = true;
+      setIsLoading(true);
+      if (indicator === 'canvas') chart.setEdgeState(side, 'loading');
+
+      // biome-ignore lint/suspicious/noConfusingVoidType: matches onTrigger's return type exactly
+      let result: void | Promise<unknown>;
+      try {
+        result = triggerRef.current();
+      } catch (err) {
+        inflight.current = false;
+        setIsLoading(false);
+        if (indicator === 'canvas') chart.setEdgeState(side, 'idle');
+        throw err;
+      }
+
+      const finish = (value: unknown) => {
+        inflight.current = false;
+        setIsLoading(false);
+        if (value === false) {
+          setHasMore(false);
+          if (indicator === 'canvas') chart.setEdgeState(side, 'no-data');
+        } else if (indicator === 'canvas') {
+          chart.setEdgeState(side, 'idle');
+        }
+      };
+
+      if (result && typeof (result as Promise<unknown>).then === 'function') {
+        (result as Promise<unknown>).then(finish, () => finish(undefined));
+      } else {
+        finish(undefined);
+      }
+    };
+
+    const onChange = () => {
+      const interval = chart.getDataInterval();
+      const distance = distanceFromEdge();
+      if (distance === null) return;
+
+      if (!armed.current) {
+        // Wait until the visible range has moved away from the edge once —
+        // then we know the chart isn't in its mount-time fit-to-data state.
+        if (distance > threshold * interval) {
+          armed.current = true;
+        }
+
+        return;
+      }
+
+      if (distance <= threshold * interval) {
+        fire();
+      }
+
+      // Bump only when a render-prop is consuming the live pixel-x — the
+      // canvas-indicator path is driven entirely by chart.setEdgeState and
+      // doesn't need a React re-render on every pan/zoom frame.
+      if (hasChildrenRef.current) setTick((n) => n + 1);
+    };
+
+    chart.on('viewportChange', onChange);
+    chart.on('overlayChange', onChange);
+    onChange();
+
+    return () => {
+      chart.off('viewportChange', onChange);
+      chart.off('overlayChange', onChange);
+    };
+  }, [chart, side, threshold, indicator, hasMore]);
+
+  // Reset the canvas indicator when this loader unmounts so a remount with a
+  // fresh side / threshold doesn't inherit stale state.
+  useEffect(() => {
+    return () => {
+      if (indicator === 'canvas') chart.setEdgeState(side, 'idle');
+    };
+  }, [chart, side, indicator]);
+
+  if (!children) return null;
+
+  const data = chart.getDataRange();
+  if (!data) return null;
+
+  const boundaryTime = side === 'left' ? data.from : data.to;
+  const x = chart.timeScale.timeToX(boundaryTime);
+
+  return <>{children({ x, side, isLoading, boundaryTime, hasMore })}</>;
+}