stream-charts 1.2.0 → 2.0.0

package/dist/app/charts/plots/PoincarePlot.js

@@ -1,40 +1,54 @@
-import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
-import { useCallback, useEffect, useMemo, useRef } from 'react';
+import { useCallback, useEffect, useEffectEvent, useMemo, useRef } from 'react';
+import { useCanvasZoomPan } from "./useCanvasZoomPan";
 import { useChart } from "../hooks/useChart";
 import * as d3 from "d3";
-import { setClipPathG } from "./plot";
-import { axesZoomHandler, defaultLineStyle, panHandler2D } from "../axes/axes";
-import { formatTime, noop, textDimensions } from "../utils";
-import { subscriptionIteratesFor } from "../subscriptions/subscriptions";
-import { useDataObservable } from "../hooks/useDataObservable";
+import { clipToArea } from "./plot";
+import { axesZoomHandler, AxisType, checkAxisType, defaultLineStyle, panHandler2D } from "../axes/axes";
+import { canvasLocalPoint, seriesAt } from "./hitTesting";
+import { fontStringFor, formatTime, noop, textDimensions } from "../utils";
+import { iteratesViewDriverFor } from "../subscriptions/viewDrivers";
+import { useDataSource, useDataSourceRunning, useInitialData, useStreamingSettings } from "../hooks/useDataSource";
 import { usePlotDimensions } from "../hooks/usePlotDimensions";
-import { useInitialData } from "../hooks/useInitialData";
 import { useTooltip } from "../hooks/useTooltip";
 import { ContinuousAxisRange } from "../axes/ContinuousAxisRange";
+import { AxisInterval } from "../axes/AxisInterval";
+import { warnAboutIgnoredAutoScale } from "../axes/autoScale";
+import { FastShiftArray } from "fast-shift-array";
+import { DEFAULT_LINE_COLOR_STEPS, DEFAULT_LINE_END_COLOR, DEFAULT_LINE_START_COLOR, pointColorScale, strokeColorizedLine } from "./colorizedLine";
+/**
+ * Creates an axis range (with its original range the same as its current range) from each axis'
+ * current domain
+ * @param axes The axes (continuous numeric ones), by their IDs
+ * @return The axes' ranges, by their IDs
+ */
 function generateAxisRangeMap(axes) {
     return new Map(Array.from(axes.entries()).map(([id, axis]) => {
         const [start, end] = axis.scale.domain();
         return [id, ContinuousAxisRange.from(start, end)];
     }));
 }
-// A sentinel that represents that no curve factory is to be used, which means
-// that no line will be drawn between the iterates (kinda gross)
-export const NoCurveFactory = undefined;
 /**
- * Renders a streaming Poincare (iterates) plot for the series in the initial data and those sourced by the
- * observable specified as a property in the {@link Chart}. This component uses the {@link useChart}
+ * Renders a streaming Poincare (iterates) plot for the series held by the {@link StreamingDataSource}
+ * handed to the {@link Chart} (its `dataSource` prop). This component uses the {@link useChart}
  * hook, and therefore must be a child of the {@link Chart} in order to be plugged in to the
  * chart ecosystem (axes, tracker, tooltip).
  *
- * @param props The properties associated with the scatter plot
+ * Internally, this no longer creates/updates SVG `<path>`/`<circle>`/`<text>` elements. Instead, it
+ * registers a single draw function with the chart's {@link CanvasContext} that redraws every
+ * series' line and points from scratch each time the canvas repaints. The old version's
+ * hover-a-point-and-annotate-its-neighbors behavior used direct `d3.select('#specific-id')` lookups
+ * into already-rendered SVG elements from a separate pass after the main render; since canvas has
+ * no persistent elements to reach back into, this is restructured so the single draw pass checks
+ * "is this point hovered, or a neighbor of the hovered point" and renders the highlight/label
+ * inline, driven by a `hoveredPointRef` updated on `mousemove`.
+ *
+ * @param props The properties associated with the Poincaré plot
+ * @return `null` (the plot draws onto the chart's canvas)
  * @example
  * ```typescript
- *  <ScatterPlot
+ *  <PoincarePlot
  *      interpolation={interpolation}
- *      axisAssignments={new Map([
- *          ['test2', assignAxes("x-axis-2", "y-axis-2")],
- *      ])}
- *      dropDataAfter={10000}
+ *      showPoints={true}
  *      panEnabled={true}
  *      zoomEnabled={true}
  *      zoomKeyModifiersRequired={true}
@@ -42,46 +56,315 @@ export const NoCurveFactory = undefined;
  * ```
  */
 export function PoincarePlot(props) {
-    const { chartId, container, mainG, axes, backgroundColor, seriesStyles, seriesFilter, mouse } = useChart();
+    var _a;
+    const { chartId, canvasContext, axes, backgroundColor, seriesStyles, seriesFilter, mouse } = useChart();
     const { xAxesState, yAxesState, setAxisIntervalFor, updateAxisRanges = noop, axisRangeFor, addAxesRangesUpdateHandler, removeAxesRangesUpdateHandler, } = axes;
+    // this plot doesn't auto-scale its y-axes, so warn about any that ask to be (see
+    // `ContinuousAxis`'s `autoScale` prop)
+    useEffect(() => warnAboutIgnoredAutoScale("PoincarePlot", yAxesState.axes), [yAxesState]);
     const { mouseOverHandlerFor, mouseLeaveHandlerFor } = mouse;
     const { plotDimensions, margin, } = usePlotDimensions();
-    const { seriesObservable, windowingTime = 100, shouldSubscribe, onSubscribe = noop, onUpdateData, onUpdateChartTime = noop, } = useDataObservable();
+    const { windowingTime = 100, onUpdateChartTime = noop, } = useStreamingSettings();
+    // the application-owned source of the data, and whether it's running (streaming)
+    const dataSource = useDataSource();
+    const running = useDataSourceRunning(dataSource);
     const { initialData } = useInitialData();
     const { visibilityState: tooltipVisible } = useTooltip();
-    const { interpolation, showPoints = true, dropDataAfter = 1000, panEnabled = false, zoomEnabled = false, zoomKeyModifiersRequired = true, zoomMinScaleFactor = 0, zoomMaxScaleFactor = 1, } = props;
+    const { interpolation, showPoints = true, panEnabled = false, zoomEnabled = false, zoomKeyModifiersRequired = true, zoomMinScaleFactor = 0, zoomMaxScaleFactor = 1, highlightAxesOnMouseOver = false, colorizeLines = false, lineStartColor = DEFAULT_LINE_START_COLOR, lineEndColor = DEFAULT_LINE_END_COLOR, lineColorSteps = DEFAULT_LINE_COLOR_STEPS, zoomState = undefined, onZoomStateChange = noop, onZoomReset = noop, } = props;
     // why do "dataRef" and "seriesRef" both hold on to the same underlying data? for performance.
     //
     // the "dataRef" and "seriesRef" both point to the same underlying data, a collection
-    // of series. The series in "dataRef" are bound to the DOM elements through d3. The "seriesRef" series
-    // are the ones that are updated as new data is streamed in.
+    // of series (held, and updated as new data is streamed in, by the data source). The series in
+    // "dataRef" are read by the canvas draw function, and the "seriesRef" map is for looking a
+    // series up by its name.
     //
     // the "dataRef" object holds on to a copy of the initial data (which is an array of
-    // time-series, e.i. an array of BaseSeries<OrdinalDatum> objects). The slice just creates a copy of
+    // iterate series, e.i. an array of BaseSeries<IterateDatum> objects). The slice just creates a copy of
     // the array, but the references to the BaseSeries objects are the same and still point to the same
     // data as the "initialData" array.
     //
-    // the "seriesRef" object is a reference to a map (series_name -> BaseSeries<OrdinalDatum>) which is
-    // used to update the data in the series. When new data enters, it is appended to one or more series.
+    // the "seriesRef" object is a reference to a map (series_name -> BaseSeries<IterateDatum>), used
+    // to find the series under the mouse (for the tooltip).
     //
-    // the series in the "dataRef" object are the ones bound to the DOM elements in d3, and so as these
-    // are updated, d3 will update the DOM elements (the elements in this plot).
+    // the series in the "dataRef" object are the ones read by the next redraw, so as these are
+    // updated, the next canvas repaint picks up the new data.
     const dataRef = useRef(initialData.slice());
     const seriesRef = useRef(new Map(initialData.map(series => [series.name, series])));
     // map(axis_id -> current_time) -- maps the axis ID to the current time for that axis
     const currentTimeRef = useRef(0);
     const xAxisRangesRef = useRef(new Map());
     const yAxisRangesRef = useRef(new Map());
-    const subscriptionRef = useRef(undefined);
-    const isSubscriptionClosed = () => subscriptionRef.current === undefined || subscriptionRef.current.closed;
-    const allowTooltip = useRef(isSubscriptionClosed());
-    // so that we can reset the zoom when the axes-bounds change, we hold on to the zoom-behaviour
-    // and the zoom-selection so that we can reset the transform to the identity
-    const zoomRef = useRef(undefined);
-    const zoomSelectionRef = useRef(undefined);
-    // calculates the distinct axis IDs that cover all the series in the plot
-    const xAxesForSeries = useMemo(() => xAxesState.axisIds(), [xAxesState]);
-    const yAxesForSeries = useMemo(() => yAxesState.axisIds(), [yAxesState]);
+    // tooltips are only shown while the data source is paused (and not while panning)
+    const allowTooltip = useRef(!((_a = dataSource === null || dataSource === void 0 ? void 0 : dataSource.running) !== null && _a !== void 0 ? _a : false));
+    // the last-drawn geometry for each series' points, in canvas coordinates, used for
+    // hit-testing mouse hover on `mousemove` (see the effect below that wires up the listener).
+    // Also keeps the corresponding `IteratePointSeries` so the hovered/neighbor points' data can
+    // be looked up by index.
+    const geometryRef = useRef(new Map());
+    const plotDataRef = useRef(new Map());
+    // which point (series + index) is currently hovered, so the draw pass can highlight it and
+    // its neighbors, and so we know when to fire a "leave"
+    const hoveredPointRef = useRef(undefined);
+    const updatePlot = useCallback(
+    /**
+     * (Re-)registers this plot's draw function with the canvas context and requests a redraw.
+     *
+     * Pan/zoom behavior setup lives in a separate effect (see below), not here -- this
+     * function runs on every data tick, and recreating/reattaching a `d3.drag()`/`d3.zoom()`
+     * behavior that often is pure overhead unrelated to drawing the new data.
+     * @param cc The canvas context to register the draw function with
+     */
+    (cc) => {
+        onUpdateChartTime(currentTimeRef.current);
+        // the colorized lines' color at a point, by the point's overall sequence number in its
+        // series (see `colorizeLines`)
+        const lineColorOf = pointColorScale(lineStartColor, lineEndColor, lineColorSteps);
+        const draw = (context) => {
+            const { context2D } = context;
+            // create a map associating series-names to their time-series.
+            const boundedSeries = new Map(dataRef.current.map(series => {
+                return [
+                    series.name,
+                    series.data
+                        .filter(datum => !isNaN(datum.iterateN))
+                        .map((datum, index) => ({
+                        n: datum.iterateN,
+                        n_1: datum.iterateN_1,
+                        time: datum.time,
+                        index: index
+                    }))
+                ];
+            }));
+            context2D.save();
+            clipToArea(context, plotDimensions, { x: margin.left, y: margin.top });
+            context2D.translate(margin.left, margin.top);
+            // ---
+            // todo only want to do this once, on the first plot, and then leave it,
+            //     unless the axes are updated, also needs to be removed/added when the
+            //     plot size changes
+            // (the same, checked axes as the series' below: the default x- and y-axes)
+            const [xAxis, yAxis] = axesFor(axisId => xAxesState.axisFor(axisId).getOrUndefined(), axisId => yAxesState.axisFor(axisId).getOrUndefined());
+            if (xAxis === undefined || yAxis === undefined)
+                throw new Error('No default axis found');
+            // ---
+            const [xStart, xEnd] = xAxesState.axisDefaultId()
+                .map(id => { var _a; return ((_a = xAxisRangesRef.current.get(id)) === null || _a === void 0 ? void 0 : _a.original.asTuple()) || [0, 0]; })
+                .getOrElse([0, 0]);
+            const [yStart, yEnd] = yAxesState.axisDefaultId()
+                .map(id => { var _a; return ((_a = yAxisRangesRef.current.get(id)) === null || _a === void 0 ? void 0 : _a.original.asTuple()) || [0, 0]; })
+                .getOrElse([0, 0]);
+            // the fn = fn+1 diagonal reference line (no hover behavior, matching the old
+            // version's explicitly no-op mouseenter/mouseleave handlers)
+            context2D.strokeStyle = "grey";
+            context2D.lineWidth = 1;
+            context2D.beginPath();
+            context2D.moveTo(xAxis.scale(xStart), yAxis.scale(yStart));
+            context2D.lineTo(xAxis.scale(xEnd), yAxis.scale(yEnd));
+            context2D.stroke();
+            const newGeometry = new Map();
+            const newPlotDataBySeries = new Map();
+            const hovered = hoveredPointRef.current;
+            boundedSeries.forEach((data, name) => {
+                var _a;
+                // grab the x and y axes assigned to the series, and if either or both
+                // axes aren't found, then give up and return
+                const [xAxisLinear, yAxisLinear] = axesFor(axisId => xAxesState.axisFor(axisId).getOrUndefined(), axisId => yAxesState.axisFor(axisId).getOrUndefined());
+                if (xAxisLinear === undefined || yAxisLinear === undefined)
+                    return;
+                // grab the style for the series
+                const seriesLineStyle = seriesStyles.get(name) || {
+                    ...defaultLineStyle(),
+                    highlightColor: defaultLineStyle().color
+                };
+                // only show the data for which the filter matches
+                const plotData = (name.match(seriesFilter)) ? data : FastShiftArray.empty();
+                newPlotDataBySeries.set(name, plotData);
+                // create the time-series path (when no interpolation is given, don't draw a
+                // connecting line at all -- matches the old version's `mainGElem.selectAll(...).remove()`)
+                // when colorizing the lines, a point's overall sequence number in its series is
+                // the number of points dropped from the series so far (when the data source
+                // counts them) plus its index -- the line leaving a point, and the point itself,
+                // are colored by it
+                const dropped = colorizeLines ? droppedCountFor(dataSource, name) : 0;
+                if (interpolation !== undefined) {
+                    const pathGenerator = d3.line()
+                        .x(d => xAxis.scale(d.n || 0))
+                        .y(d => yAxis.scale(d.n_1 || 0))
+                        .curve(interpolation);
+                    context2D.lineWidth = seriesLineStyle.lineWidth;
+                    if (colorizeLines) {
+                        // the line's color changes along it, one step per point
+                        const linePoints = Array.from(plotData);
+                        strokeColorizedLine(context2D, linePoints, d => xAxis.scale(d.n || 0), d => yAxis.scale(d.n_1 || 0), interpolation, index => lineColorOf(dropped + linePoints[index].index));
+                    }
+                    else {
+                        context2D.strokeStyle = seriesLineStyle.color;
+                        context2D.stroke(new Path2D((_a = pathGenerator(Array.from(plotData))) !== null && _a !== void 0 ? _a : ""));
+                    }
+                }
+                // when specified, show a circle for the actual data point
+                const points = [];
+                if (showPoints) {
+                    const isThisSeriesHovered = (hovered === null || hovered === void 0 ? void 0 : hovered.seriesName) === name;
+                    plotData.forEach((d) => {
+                        const x = xAxisLinear.scale(d.n) || 0;
+                        const y = yAxisLinear.scale(d.n_1) || 0;
+                        points.push([x + margin.left, y + margin.top]);
+                        const isHoveredPoint = isThisSeriesHovered && hovered.index === d.index;
+                        const isNeighborOfHovered = isThisSeriesHovered &&
+                            (hovered.index === d.index - 1 || hovered.index === d.index + 1);
+                        if (isHoveredPoint) {
+                            // the hovered point itself: enlarged, highlight-colored, no label
+                            // (matches the old version, which only labeled the *neighbors*)
+                            context2D.fillStyle = seriesLineStyle.highlightColor;
+                            context2D.beginPath();
+                            context2D.arc(x, y, 5, 0, 2 * Math.PI);
+                            context2D.fill();
+                        }
+                        else if (isNeighborOfHovered) {
+                            // a neighbor of the hovered point: enlarged, brighter fill, stroked,
+                            // with a floating "n = i; t = X ms" label above it
+                            context2D.fillStyle = d3.rgb(seriesLineStyle.highlightColor).brighter(0.7).toString();
+                            context2D.strokeStyle = seriesLineStyle.color;
+                            context2D.lineWidth = seriesLineStyle.lineWidth;
+                            context2D.beginPath();
+                            context2D.arc(x, y, 5, 0, 2 * Math.PI);
+                            context2D.fill();
+                            context2D.stroke();
+                            const label = `n = ${d.index}; t = ${formatTime(d.time)} ms`;
+                            context2D.font = fontStringFor(11, 'sans-serif', 700);
+                            const { width, height } = textDimensions(context2D, label);
+                            const padding = 4;
+                            const circleRadius = 5;
+                            const circleStroke = seriesLineStyle.lineWidth;
+                            context2D.fillStyle = backgroundColor;
+                            context2D.fillRect(x - padding / 2 - 8, y - padding / 2 - circleRadius - circleStroke - height, width + padding, height + padding / 2);
+                            context2D.fillStyle = seriesLineStyle.highlightColor;
+                            context2D.textAlign = 'left';
+                            context2D.textBaseline = 'alphabetic';
+                            context2D.fillText(label, x - 8, y - circleRadius - circleStroke - padding);
+                        }
+                        else {
+                            // normal, unhovered point (in the color of the line leaving it, when
+                            // the lines are colorized)
+                            context2D.fillStyle = colorizeLines ?
+                                lineColorOf(dropped + d.index) :
+                                seriesLineStyle.color;
+                            context2D.beginPath();
+                            context2D.arc(x, y, 2, 0, 2 * Math.PI);
+                            context2D.fill();
+                        }
+                    });
+                }
+                newGeometry.set(`${name}::points`, { points, hitRadius: 6 });
+            });
+            geometryRef.current = newGeometry;
+            plotDataRef.current = newPlotDataBySeries;
+            context2D.restore();
+        };
+        cc.register(`poincare-plot-${chartId}`, draw, 10);
+        cc.requestRedraw();
+    }, [
+        chartId, onUpdateChartTime, plotDimensions, xAxesState, yAxesState, seriesStyles, seriesFilter,
+        showPoints, interpolation, backgroundColor, colorizeLines, lineStartColor, lineEndColor,
+        lineColorSteps, dataSource, margin.left, margin.top
+    ]);
+    // need to keep the function references for use by the subscription, which forms a closure
+    // on them. without the references, the closures become stale, and resizing during streaming
+    // doesn't work properly
+    const updatePlotRef = useRef(updatePlot);
+    useEffect(() => {
+        updatePlotRef.current = updatePlot;
+    }, [updatePlot]);
+    // hands the current zoom/pan state (d3-zoom's cumulative `k`, and every axis' current domain) to
+    // the `onZoomStateChange` callback
+    const onZoomStateChangeRef = useRef(onZoomStateChange);
+    useEffect(() => {
+        onZoomStateChangeRef.current = onZoomStateChange;
+    }, [onZoomStateChange]);
+    const reportZoomState = useCallback(() => {
+        const ranges = {};
+        xAxisRangesRef.current.forEach((range, axisId) => ranges[axisId] = range.current.asTuple());
+        yAxisRangesRef.current.forEach((range, axisId) => ranges[axisId] = range.current.asTuple());
+        const k = canvasContext !== null ? d3.zoomTransform(canvasContext.canvas).k : 1;
+        onZoomStateChangeRef.current({ k, ranges });
+    }, [canvasContext]);
+    // panning (dragging) and zooming (the mouse wheel) -- see `useCanvasZoomPan`. Fully zooming out
+    // (back to a scale of 1) snaps the axes back to their original ranges.
+    const { resetZoomTransform, setZoomScale } = useCanvasZoomPan(canvasContext, {
+        panEnabled,
+        zoomEnabled,
+        keyModifiersRequired: zoomKeyModifiersRequired,
+        scaleExtent: [zoomMinScaleFactor, zoomMaxScaleFactor],
+        translateExtent: [[margin.left, margin.top], [plotDimensions.width, plotDimensions.height]],
+        // (tooltips are suppressed while panning and zooming, so that one isn't left behind)
+        onPanStart: () => {
+            allowTooltip.current = false;
+        },
+        onPan: (dx, dy) => {
+            if (canvasContext === null)
+                return;
+            onPan(dx, dy, plotDimensions, dataRef.current.map(series => series.name), xAxisRangesRef.current, yAxisRangesRef.current);
+            updatePlotRef.current(canvasContext);
+        },
+        onPanEnd: () => {
+            var _a;
+            allowTooltip.current = !((_a = dataSource === null || dataSource === void 0 ? void 0 : dataSource.running) !== null && _a !== void 0 ? _a : false);
+            reportZoomState();
+        },
+        onZoom: ({ factor, k, x, y }) => {
+            if (canvasContext === null)
+                return;
+            allowTooltip.current = false;
+            if (k === 1) {
+                snapToOriginalRanges();
+            }
+            else {
+                onZoom(factor, x - margin.left, y - margin.top, plotDimensions, xAxisRangesRef.current, yAxisRangesRef.current);
+            }
+            updatePlotRef.current(canvasContext);
+            reportZoomState();
+            allowTooltip.current = true;
+        },
+        onZoomReset,
+        resetView: () => {
+            snapToOriginalRanges();
+            if (canvasContext !== null)
+                updatePlotRef.current(canvasContext);
+            reportZoomState();
+        },
+    });
+    // the zoom state to restore, captured once at mount (see the `zoomState` prop); cleared once
+    // it has been applied (see `restoreZoomState` below), so it's only ever applied once
+    const pendingZoomStateRef = useRef(zoomState);
+    // applies the pending zoom state (if any) to the axes' ranges and to d3-zoom's transform on the
+    // canvas (a remounted plot has a brand-new canvas, whose transform starts at identity). Each
+    // range keeps its `.original` -- the axis' real, un-zoomed domain -- since the zoom handler's
+    // constraint is measured against it. Waits until the axes' ranges and the canvas exist.
+    const restoreZoomState = useEffectEvent(() => {
+        const pending = pendingZoomStateRef.current;
+        if (pending === undefined || canvasContext === null)
+            return;
+        if (xAxisRangesRef.current.size === 0 || yAxisRangesRef.current.size === 0)
+            return;
+        Object.entries(pending.ranges).forEach(([axisId, [start, end]]) => {
+            var _a;
+            const interval = AxisInterval.from(start, end);
+            const ranges = xAxisRangesRef.current.has(axisId) ? xAxisRangesRef.current : yAxisRangesRef.current;
+            const range = ranges.get(axisId);
+            const axis = (_a = xAxesState.axisFor(axisId).getOrUndefined()) !== null && _a !== void 0 ? _a : yAxesState.axisFor(axisId).getOrUndefined();
+            if (range === undefined || axis === undefined)
+                return;
+            ranges.set(axisId, range.update(start, end));
+            setAxisIntervalFor(axisId, interval);
+            axis.update(interval, plotDimensions, margin);
+        });
+        // `__zoom` is where d3-zoom keeps an element's transform; setting it directly (rather than
+        // through `zoom.transform`) avoids dispatching a synthetic "zoom" event
+        setZoomScale(pending.k);
+        pendingZoomStateRef.current = undefined;
+        updatePlotRef.current(canvasContext);
+    });
     // when the axes are available, then set the reference, but only once
     useEffect(() => {
         if (xAxesState.axes.size > 0 && xAxisRangesRef.current.size === 0) {
@@ -90,16 +373,22 @@ export function PoincarePlot(props) {
         if (yAxesState.axes.size > 0 && yAxisRangesRef.current.size === 0) {
             yAxisRangesRef.current = generateAxisRangeMap(yAxesState.axes);
         }
-    }, [xAxesState, yAxesState]);
+        // restore a zoom state handed in from a previous instance (only does anything the first
+        // time the axes and canvas are all available -- see `restoreZoomState`)
+        restoreZoomState();
+    }, [xAxesState, yAxesState, canvasContext]);
+    // calculates the distinct axis IDs that cover all the series in the plot
+    const xAxesForSeries = useMemo(() => xAxesState.axisIds(), [xAxesState]);
+    const yAxesForSeries = useMemo(() => yAxesState.axisIds(), [yAxesState]);
     // update the plot with the new axes bounds
     const updateRangesAndPlot = useCallback(() => {
-        if (mainG !== null) {
-            updatePlotRef.current(mainG);
+        if (canvasContext !== null) {
+            updatePlotRef.current(canvasContext);
         }
-    }, [mainG]);
+    }, [canvasContext]);
     // todo find better way
     // when the initial data changes, then reset the plot. note that the initial data doesn't change
-    // during the normal course of updates from the observable, only when the plot is restarted.
+    // during the normal course of updates from the data source, only when the data source is replaced.
     useEffect(() => {
         dataRef.current = initialData.slice();
         seriesRef.current = new Map(initialData.map(series => [series.name, series]));
@@ -107,23 +396,33 @@ export function PoincarePlot(props) {
         updateRangesAndPlot();
     }, [initialData, updateRangesAndPlot]);
     /**
-     * When the axes bounds have changed, we need to reset the range references so that
-     * the new axis ranges are used
+     * When the axes bounds have changed (from outside, e.g. a different iterate function), resets
+     * the range references so that the new axis ranges are used -- as the axes' new original
+     * (un-zoomed) domains -- resets the zoom, and reports the (reset) zoom state
      * @param updates The updates to the axes
      */
     const updatedBoundsHandler = useCallback((updates) => {
+        // the new bounds become the axes' new un-zoomed (original) domains -- the zoom is reset
+        // to identity below, so they're the baseline the zoom constraint and the fully-zoomed-out
+        // snap (see `snapToOriginalRanges`) must measure against. The update itself can't be
+        // used as-is: `ContinuousAxis` carries the *previous* `.original` forward on a domain
+        // change, which would leave the zoom clamped to (and snapping back to) the old domain,
+        // e.g. [0, 1] after switching to an iterate function whose range is [-1, 1].
         updates.forEach((update, axisId) => {
+            const [start, end] = update.current.asTuple();
             if (xAxisRangesRef.current.has(axisId)) {
-                xAxisRangesRef.current.set(axisId, update);
+                xAxisRangesRef.current.set(axisId, ContinuousAxisRange.from(start, end));
             }
             if (yAxisRangesRef.current.has(axisId)) {
-                yAxisRangesRef.current.set(axisId, update);
+                yAxisRangesRef.current.set(axisId, ContinuousAxisRange.from(start, end));
             }
         });
-        if (zoomEnabled && zoomSelectionRef.current !== undefined && zoomRef.current !== undefined) {
-            zoomSelectionRef.current.call(zoomRef.current.transform, d3.zoomIdentity);
-        }
-    }, [zoomEnabled]);
+        if (zoomEnabled)
+            resetZoomTransform();
+        // the axes' bounds were changed from outside (e.g. a different iterate function), which
+        // resets the zoom, so a previously reported zoom state no longer applies
+        reportZoomState();
+    }, [zoomEnabled, resetZoomTransform, reportZoomState]);
     // strange construct so that we only add the update handler when the chart ID
     // changes, and not when the addAxesBoundsUpdateHandler or removeAxesBoundsUpdateHandler
     // which they do, and that breaks the updates...someone, please teach me react
@@ -142,360 +441,220 @@ export function PoincarePlot(props) {
         };
     }, [chartId, updatedBoundsHandler]);
     /**
-     * Adjusts the time-range and updates the plot when the plot is dragged to the left or right
-     * @param x The amount that the plot is dragged
+     * Adjusts the x- and y-axes' ranges when the plot is dragged (the caller redraws the plot)
+     * @param x The amount that the plot is dragged in x
+     * @param y The amount that the plot is dragged in y
      * @param plotDimensions The dimensions of the plot
      * @param series An array of series names
-     * @param ranges A map holding the axis ID and its associated time range
+     * @param xRanges A map holding the x-axis ID and its associated range
+     * @param yRanges A map holding the y-axis ID and its associated range
      */
     const onPan = useCallback((x, y, plotDimensions, series, xRanges, yRanges) => panHandler2D(xAxesForSeries, yAxesForSeries, margin, setAxisIntervalFor, xAxesState, yAxesState)(x, y, plotDimensions, series, xRanges, yRanges), [xAxesForSeries, yAxesForSeries, margin, setAxisIntervalFor, xAxesState, yAxesState]);
+    /**
+     * Restores every axis to its original (un-zoomed) domain. Used when d3-zoom's cumulative `k`
+     * returns to exactly 1 (fully zoomed out): composing pivot-preserving zooms at *different*
+     * pivots isn't position-preserving (zooming in at one spot and back out at another nets a
+     * translation, as in any pinch-zoom UI), and the zoom constraint clamps that translated window
+     * to the original bounds -- so without this, zooming in at one spot and out at another stops
+     * short of the full view on both axes, with `k` already at its maximum. d3-zoom's `scaleExtent`
+     * clamps `k` to *exactly* 1 at that limit, so the equality check reliably detects it. (This is
+     * the continuous-axis counterpart of `OrdinalAxisRange.scaledCumulative`'s `factor === 1` case.)
+     */
+    const snapToOriginalRanges = useCallback(() => {
+        const snap = (ranges, axesState) => ranges.forEach((range, axisId) => {
+            ranges.set(axisId, range.update(range.original.start, range.original.end));
+            setAxisIntervalFor(axisId, range.original);
+            axesState.axisFor(axisId).ifPresent(axis => axis.update(range.original, plotDimensions, margin));
+        });
+        snap(xAxisRangesRef.current, xAxesState);
+        snap(yAxisRangesRef.current, yAxesState);
+    }, [setAxisIntervalFor, xAxesState, yAxesState, plotDimensions, margin]);
     /**
      * Called when the user uses the scroll wheel (or scroll gesture) to zoom in or out. Zooms in/out
      * at the location of the mouse when the scroll wheel or gesture was applied. Unlike time-series
      * plots, the iterates plot zooms the x- and y-axis at the same rate.
-     * @param transform The d3 zoom transformation information
+     * @param zoomFactor The *incremental* zoom scale factor for this event -- see
+     * `useCanvasZoomPan` for how d3-zoom's own cumulative `k` is converted to this incremental
+     * form before this is called.
      * @param x The x-position of the mouse when the scroll wheel or gesture is used
      * @param y The y-position of the mouse when the scroll wheel or gesture is used
      * @param plotDimensions The dimensions of the plot
-     * @param series An array of series names
-     * @param ranges A map holding the axis ID and its associated time-range
-     */
-    const onZoom = useCallback((transform, x, y, plotDimensions, xRanges, yRanges) => axesZoomHandler(xAxesForSeries, yAxesForSeries, margin, setAxisIntervalFor, xAxesState, yAxesState, [zoomMinScaleFactor, zoomMaxScaleFactor])(transform, [x, y], plotDimensions, xRanges, yRanges), [xAxesForSeries, yAxesForSeries, margin, setAxisIntervalFor, xAxesState, yAxesState, zoomMinScaleFactor, zoomMaxScaleFactor]);
-    const updatePlot = useCallback(
-    /**
-     * Updates the plot data for the specified time-range, which may have changed due to zoom or pan
-     * @param mainGElem The main <g> element selection for that holds the plot
+     * @param xRanges A map holding the x-axis ID and its associated range
+     * @param yRanges A map holding the y-axis ID and its associated range
      */
-    (mainGElem) => {
-        if (container) {
-            onUpdateChartTime(currentTimeRef.current);
-            // select the svg element bind the data to them
-            const svg = d3.select(container);
-            // create a map associating series-names to their time-series.
-            //
-            // performance-related confusion: wondering where the dataRef is updated? well it isn't
-            // directly. The dataRef holds on to an array of references to the Series. And so does the
-            // seriesRef, though it uses a map(series_name -> series). The seriesRef is used to append
-            // data to the underlying Series, and the dataRef is used so that we can just use
-            // dataRef.current and don't have to do Array.from(seriesRef.current.values()) which
-            // creates a temporary array
-            // const offset = 1
-            const boundedSeries = new Map(dataRef.current.map(series => {
-                return [
-                    series.name,
-                    series.data
-                        .filter(datum => !isNaN(datum.iterateN))
-                        .map((datum, index) => ({
-                        n: datum.iterateN,
-                        n_1: datum.iterateN_1,
-                        time: datum.time,
-                        index: index
-                    }))
-                ];
-            }));
-            // set up panning
-            if (panEnabled) {
-                const drag = d3.drag()
-                    .on("start", () => {
-                    d3.select(container).style("cursor", "move");
-                    // during panning, we need to disable viewing the tooltip to prevent
-                    // tooltips from rendering but not getting removed
-                    allowTooltip.current = false;
-                })
-                    .on("drag", event => {
-                    onPan(event.dx, event.dy, plotDimensions, Array.from(boundedSeries.keys()), xAxisRangesRef.current, yAxisRangesRef.current);
-                    updatePlotRef.current(mainGElem);
-                })
-                    .on("end", () => {
-                    d3.select(container).style("cursor", "auto");
-                    // during panning, we disabled viewing the tooltip to prevent
-                    // tooltips from rendering but not getting removed, now that panning
-                    // is over, allow tooltips to render again
-                    allowTooltip.current = isSubscriptionClosed();
-                });
-                svg.call(drag);
-            }
-            // set up for zooming
-            if (zoomEnabled) {
-                zoomRef.current = d3.zoom()
-                    .filter(event => !zoomKeyModifiersRequired || event.shiftKey || event.ctrlKey)
-                    .scaleExtent([zoomMinScaleFactor, zoomMaxScaleFactor])
-                    .translateExtent([[margin.left, margin.top], [plotDimensions.width, plotDimensions.height]])
-                    .on("zoom", event => {
-                    allowTooltip.current = false;
-                    if (event.sourceEvent !== null) {
-                        onZoom(event.transform, event.sourceEvent.offsetX - margin.left, event.sourceEvent.offsetY - margin.top, plotDimensions, xAxisRangesRef.current, yAxisRangesRef.current);
-                        updatePlotRef.current(mainGElem);
-                    }
-                    allowTooltip.current = true;
-                });
-                zoomSelectionRef.current = svg.call(zoomRef.current);
-            }
-            // define the clip-path so that the series lines don't go beyond the plot area
-            const clipPathId = setClipPathG(chartId, mainGElem, plotDimensions);
-            // ---
-            // todo only want to do this once, on the first plot, and then leave it,
-            //     unless the axes are updated, also needs to be removed/added when the
-            //     plot size changes
-            const xAxis = xAxesState.defaultAxis().getOrThrow(() => new Error('No default axis found'));
-            const yAxis = yAxesState.defaultAxis().getOrThrow(() => new Error('No default axis found'));
-            const lineGenerator = d3.line()
-                .x(d => xAxis.scale(d[0] || 0))
-                .y(d => yAxis.scale(d[1] || 0));
-            // ---
-            const [xStart, xEnd] = xAxesState.axisDefaultId()
-                .map(id => { var _a; return ((_a = xAxisRangesRef.current.get(id)) === null || _a === void 0 ? void 0 : _a.original.asTuple()) || [0, 0]; })
-                .getOrElse([0, 0]);
-            const [yStart, yEnd] = yAxesState.axisDefaultId()
-                .map(id => { var _a; return ((_a = yAxisRangesRef.current.get(id)) === null || _a === void 0 ? void 0 : _a.original.asTuple()) || [0, 0]; })
-                .getOrElse([0, 0]);
-            // const [xStart, xEnd] = xAxisRangesRef.current.get(xAxesState.axisDefaultId())?.original.asTuple() || [0, 0]
-            // const [yStart, yEnd] = yAxisRangesRef.current.get(yAxesState.axisDefaultId())?.original.asTuple() || [0, 0]
-            mainGElem
-                .selectAll(`#fn-equals-fn1-${chartId}-poincare`)
-                .data([[[xStart, yStart], [xEnd, yEnd]]])
-                .join(enter => enter
-                .select("path")
-                .style("stroke", "grey")
-                .style("fill", "none")
-                .style("stroke-width", "1px")
-                .attr("class", `fn-equals-fn1-poincare`)
-                .attr("id", `#fn-equals-fn1-${chartId}-poincare`)
-                .attr('transform', `translate(${margin.left}, ${margin.top})`)
-                .attr("d", lineGenerator), update => update.remove(), exit => exit.remove())
-                // clear out mouse-enter callbacks for the diagonal line
-                .on("mouseenter", () => {
-            })
-                .on("mouseleave", () => {
-            });
-            boundedSeries.forEach((data, name) => {
-                // grab the x and y axes assigned to the series, and if either or both
-                // axes aren't found, then give up and return
-                const [xAxisLinear, yAxisLinear] = axesFor(axisId => xAxesState.axisFor(axisId).getOrUndefined(), axisId => yAxesState.axisFor(axisId).getOrUndefined());
-                if (xAxisLinear === undefined || yAxisLinear === undefined)
-                    return;
-                // grab the style for the series
-                const seriesLineStyle = seriesStyles.get(name) || Object.assign(Object.assign({}, defaultLineStyle()), { highlightColor: defaultLineStyle().color });
-                // only show the data for which the filter matches
-                const plotData = (name.match(seriesFilter)) ? data : [];
-                const pathGenerator = d3.line()
-                    .x(d => xAxis.scale(d.n || 0))
-                    .y(d => yAxis.scale(d.n_1 || 0));
-                if (interpolation === undefined) {
-                    mainGElem
-                        .selectAll(`#${name}-${chartId}-poincare`)
-                        .remove();
-                }
-                else {
-                    // create the time-series paths
-                    mainGElem
-                        .selectAll(`#${name}-${chartId}-poincare`)
-                        .data([[], plotData], () => `${name}`)
-                        .join(enter => enter
-                        .append("path")
-                        .attr("class", 'iterate-series-lines')
-                        .attr("id", `${name}-${chartId}-poincare`)
-                        .attr("d", pathGenerator.curve(interpolation))
-                        .style("fill", "none")
-                        .style("stroke", seriesLineStyle.color)
-                        .style("stroke-width", seriesLineStyle.lineWidth)
-                        .attr('transform', `translate(${margin.left}, ${margin.top})`)
-                        .attr("clip-path", `url(#${clipPathId})`), update => update, exit => exit.remove());
-                }
-                // when specified, show a circle for the actual data point
-                if (showPoints) {
-                    mainGElem
-                        .selectAll(`.${name}-${chartId}-poincare-points`)
-                        .data(plotData, () => `${name}`)
-                        .join(enter => enter
-                        .append("circle")
-                        .attr("class", `${name}-${chartId}-poincare-points`)
-                        .attr("id", (_, index) => `${name}-${chartId}-poincare-point-${index}`)
-                        .attr("fill", seriesLineStyle.color)
-                        .attr("stroke", "none")
-                        .attr("cx", (d) => xAxisLinear.scale(d.n) || 0)
-                        .attr("cy", (d) => yAxisLinear.scale(d.n_1) || 0)
-                        .attr("r", 2)
-                        .attr('transform', `translate(${margin.left}, ${margin.top})`)
-                        .attr("clip-path", `url(#${clipPathId})`), update => update
-                        .attr("cx", (d) => xAxisLinear.scale(d.n) || 0)
-                        .attr("cy", (d) => yAxisLinear.scale(d.n_1) || 0), exit => exit.remove())
-                        .on("mouseenter", (event, datum) => {
-                        if (allowTooltip.current && tooltipVisible) {
-                            return handleMouseEnterPoint(chartId, name, container, event, datum, plotData, xAxisLinear, yAxisLinear, margin, seriesLineStyle, backgroundColor, allowTooltip.current, mouseOverHandlerFor(`tooltip-${chartId}`));
-                        }
-                        return _jsx(_Fragment, {});
-                    })
-                        .on("mouseleave", () => {
-                        handleMouseLeavePoint(chartId, name, seriesLineStyle.color, mouseLeaveHandlerFor(`tooltip-${chartId}`));
-                    });
-                }
-            });
-        }
-    }, [
-        container, onUpdateChartTime, panEnabled, zoomEnabled, chartId, plotDimensions, margin,
-        xAxesState, yAxesState,
-        onPan,
-        zoomMinScaleFactor, zoomMaxScaleFactor, zoomKeyModifiersRequired, onZoom,
-        seriesStyles, seriesFilter, showPoints,
-        interpolation, backgroundColor,
-        mouseOverHandlerFor, mouseLeaveHandlerFor,
-        tooltipVisible,
-    ]);
-    // need to keep the function references for use by the subscription, which forms a closure
-    // on them. without the references, the closures become stale, and resizing during streaming
-    // doesn't work properly
-    const updatePlotRef = useRef(updatePlot);
-    useEffect(() => {
-        updatePlotRef.current = updatePlot;
-    }, [updatePlot]);
+    const onZoom = useCallback((zoomFactor, x, y, plotDimensions, xRanges, yRanges) => axesZoomHandler(xAxesForSeries, yAxesForSeries, margin, setAxisIntervalFor, xAxesState, yAxesState, [zoomMinScaleFactor, zoomMaxScaleFactor])(zoomFactor, [x, y], plotDimensions, xRanges, yRanges), [xAxesForSeries, yAxesForSeries, margin, setAxisIntervalFor, xAxesState, yAxesState, zoomMinScaleFactor, zoomMaxScaleFactor]);
     const onUpdateAxesBoundsRef = useRef(updateAxisRanges);
     useEffect(() => {
         onUpdateAxesBoundsRef.current = updateAxisRanges;
     }, [updateAxisRanges]);
-    // memoized function for subscribing to the chart-data observable
-    const subscribe = useCallback(() => {
-        if (seriesObservable === undefined || mainG === null)
-            return undefined;
-        return subscriptionIteratesFor(seriesObservable, onSubscribe, windowingTime, xAxesState, yAxesState, onUpdateData, dropDataAfter, updateRangesAndPlot, 
-        // as new data flows into the subscription, the subscription
-        // updates this map directly (for performance)
-        seriesRef.current, end => currentTimeRef.current = end);
-    }, [
-        dropDataAfter, mainG,
-        onSubscribe, onUpdateData,
-        seriesObservable, updateRangesAndPlot, windowingTime,
-        xAxesState, yAxesState,
-    ]);
     // updates the plot when the interpolation and filter change, because the updatePlot
     // callback has changed.
     useEffect(() => {
-        if (container && mainG) {
-            updatePlot(mainG);
+        if (canvasContext) {
+            updatePlot(canvasContext);
         }
-    }, [axisRangeFor, container, mainG, updatePlot]);
-    // subscribe/unsubscribe to the observable chart data. when the `shouldSubscribe`
-    // is changed to `true` and we haven't subscribed yet, then subscribe. when the
-    // `shouldSubscribe` is `false` and we had subscribed, then unsubscribe. otherwise,
-    // do nothing.
+    }, [axisRangeFor, canvasContext, updatePlot]);
+    // wires up a single mousemove/mouseleave listener on the shared canvas to replace the old
+    // per-element SVG mouseenter/mouseleave handlers on the point circles. Hit-tests the mouse
+    // position against the last-drawn point geometry (see `geometryRef`, populated by the draw
+    // function above).
     useEffect(() => {
-        var _a;
-        if (shouldSubscribe && subscriptionRef.current === undefined) {
-            subscriptionRef.current = subscribe();
-            allowTooltip.current = false;
-        }
-        else if (!shouldSubscribe && subscriptionRef.current !== undefined) {
-            (_a = subscriptionRef.current) === null || _a === void 0 ? void 0 : _a.unsubscribe();
-            subscriptionRef.current = undefined;
+        if (!canvasContext)
+            return;
+        const canvas = canvasContext.canvas;
+        // highlights (or un-highlights) the shared x- and y-axes -- keyed on the series name
+        // alone (not the specific hovered point index), so moving the mouse between a
+        // series' own points doesn't flicker the highlight off and on
+        const highlightAxesFor = (seriesName, isHighlighted) => {
+            if (!highlightAxesOnMouseOver)
+                return;
+            const [xAxis, yAxis] = axesFor(axisId => xAxesState.axisFor(axisId).getOrUndefined(), axisId => yAxesState.axisFor(axisId).getOrUndefined());
+            const { highlightColor, highlightWidth } = seriesStyles.get(seriesName) || defaultLineStyle();
+            xAxis === null || xAxis === void 0 ? void 0 : xAxis.setHighlighted(isHighlighted, highlightColor, highlightWidth);
+            yAxis === null || yAxis === void 0 ? void 0 : yAxis.setHighlighted(isHighlighted, highlightColor, highlightWidth);
+        };
+        const handleMove = (event) => {
+            if (!allowTooltip.current || !tooltipVisible)
+                return;
+            const [x, y] = canvasLocalPoint(event, canvas);
+            const hit = seriesAt(x, y, geometryRef.current);
+            const hitSeriesName = hit === null || hit === void 0 ? void 0 : hit.name.replace(/::points$/, '');
+            const previous = hoveredPointRef.current;
+            if ((previous === null || previous === void 0 ? void 0 : previous.seriesName) !== hitSeriesName) {
+                if (previous !== undefined)
+                    highlightAxesFor(previous.seriesName, false);
+                if (hitSeriesName !== undefined)
+                    highlightAxesFor(hitSeriesName, true);
+            }
+            const sameAsBefore = previous !== undefined && hit !== undefined &&
+                previous.seriesName === hitSeriesName && previous.index === hit.index;
+            if (sameAsBefore)
+                return;
+            if (previous !== undefined) {
+                handleMouseLeavePoint(previous.seriesName, mouseLeaveHandlerFor(`tooltip-${chartId}`));
+            }
+            if (hit !== undefined && hitSeriesName !== undefined) {
+                const plotData = plotDataRef.current.get(hitSeriesName);
+                if (plotData !== undefined) {
+                    handleMouseEnterPoint(hitSeriesName, plotData[hit.index], plotData, [x, y], mouseOverHandlerFor(`tooltip-${chartId}`));
+                }
+            }
+            hoveredPointRef.current = hit !== undefined && hitSeriesName !== undefined ?
+                { seriesName: hitSeriesName, index: hit.index } :
+                undefined;
+            // hover state affects the highlight/label drawing, so request a redraw
+            canvasContext.requestRedraw();
+        };
+        const handleLeaveCanvas = () => {
+            const previous = hoveredPointRef.current;
+            if (previous !== undefined) {
+                handleMouseLeavePoint(previous.seriesName, mouseLeaveHandlerFor(`tooltip-${chartId}`));
+                highlightAxesFor(previous.seriesName, false);
+                hoveredPointRef.current = undefined;
+                canvasContext.requestRedraw();
+            }
+        };
+        canvas.addEventListener('mousemove', handleMove);
+        canvas.addEventListener('mouseleave', handleLeaveCanvas);
+        return () => {
+            canvas.removeEventListener('mousemove', handleMove);
+            canvas.removeEventListener('mouseleave', handleLeaveCanvas);
+        };
+    }, [
+        canvasContext, chartId, mouseOverHandlerFor, mouseLeaveHandlerFor, tooltipVisible,
+        highlightAxesOnMouseOver, xAxesState, yAxesState, seriesStyles
+    ]);
+    // the latest `updateRangesAndPlot`, for the view driver to call -- the driver is created once
+    // per run (see below), so it must not capture a stale one (e.g. bound to an older canvas)
+    const updateRangesAndPlotRef = useRef(updateRangesAndPlot);
+    useEffect(() => {
+        updateRangesAndPlotRef.current = updateRangesAndPlot;
+    }, [updateRangesAndPlot]);
+    // creates the view driver that keeps this plot's view in step with the data source, using the
+    // current settings -- see `useStreamingTimeAxes`'s identical effect event
+    const createViewDriver = useEffectEvent((source) => iteratesViewDriverFor(source, windowingTime, xAxesState, yAxesState, () => updateRangesAndPlotRef.current(), end => currentTimeRef.current = end));
+    // while the data source is running (and this plot has a canvas), drive the view from the
+    // data source's updates -- see `useStreamingTimeAxes`'s identical effect. The driver belongs to this plot
+    // instance alone and is always torn down with it.
+    useEffect(() => {
+        if (dataSource === undefined || !running || canvasContext === null)
+            return;
+        allowTooltip.current = false;
+        const driver = createViewDriver(dataSource);
+        return () => {
+            driver.unsubscribe();
             allowTooltip.current = true;
+        };
+    }, [dataSource, running, canvasContext]);
+    // this plot needs a data source (see the `Chart`'s `dataSource` prop)
+    useEffect(() => {
+        if (dataSource === undefined) {
+            console.error("PoincarePlot requires a data source; set the enclosing Chart's `dataSource` prop");
         }
-    }, [shouldSubscribe, subscribe]);
+    }, [dataSource]);
+    // unregister this plot's draw function on unmount
+    useEffect(() => {
+        return () => {
+            if (canvasContext) {
+                canvasContext.unregister(`poincare-plot-${chartId}`);
+            }
+        };
+    }, [canvasContext, chartId]);
     return null;
 }
 /**
- * Attempts to locate the x- and y-axes for the specified series. If no axis is found for the
- * series name, then uses the default returned by the useChart() hook
+ * @param dataSource The chart's data source
+ * @param seriesName The name of the series
+ * @return The number of points dropped from the series so far, when the data source counts them
+ * (an {@link IteratesDataSource} does); otherwise 0
+ */
+function droppedCountFor(dataSource, seriesName) {
+    return dataSource !== null && typeof dataSource === 'object' && 'droppedCountFor' in dataSource ?
+        dataSource.droppedCountFor(seriesName) :
+        0;
+}
+/**
+ * Locates the plot's x- and y-axes: always the default (first) ones, since every series of a
+ * Poincaré plot shares the same axes
  * @param xAxisFor The function that accepts an axis ID and returns the corresponding x-axis
  * @param yAxisFor The function that accepts an axis ID and returns the corresponding y-axis
+ * @return The x- and y-axes (either is actually `undefined` when it isn't found, despite the type)
+ * @throws Error when either axis isn't a continuous numeric axis
  */
 function axesFor(xAxisFor, yAxisFor) {
     const xAxis = xAxisFor("");
-    const xAxisLinear = xAxis;
     const yAxis = yAxisFor("");
+    checkAxisType("PoincarePlot", "x", xAxis, AxisType.ContinuousNumeric);
+    checkAxisType("PoincarePlot", "y", yAxis, AxisType.ContinuousNumeric);
+    const xAxisLinear = xAxis;
     const yAxisLinear = yAxis;
-    if (xAxis && !xAxisLinear) {
-        throw Error("Poincare plot requires that x-axis be of type LinearAxis");
-    }
-    if (yAxis && !yAxisLinear) {
-        throw Error("Poincare plot requires that y-axis be of type LinearAxis");
-    }
     return [xAxisLinear, yAxisLinear];
 }
 /**
- * @param chartId The ID of the chart
+ * Reports the tooltip for the hovered point. Replaces the old version, which also directly
+ * mutated the hovered SVG `<circle>`'s radius/fill (and its neighbors') as a side effect; that
+ * highlighting is now handled entirely by the draw function reading `hoveredPointRef` (see
+ * `updatePlot`'s `draw`) rather than by touching elements here.
  * @param seriesName The name of the series (i.e. the neuron ID)
- * @param container The SVG container holding the plot
- * @param event The mouse event that triggered this call
- * @param datum The datum over which the mouse has entered
+ * @param datum The hovered point, or `undefined` if the index doesn't resolve to a point
  * @param plotData The iterates series
- * @param xAxisLinear The x-axis (f[n](x))
- * @param yAxisLinear The y-axis (f[n+1](x))
- * @param margin The plot margin
- * @param seriesStyle The series style information (needed for (un)highlighting)
- * @param backgroundColor
- * @param allowTooltip When set to `false` won't show tooltip, even if it is visible (used by pan)
+ * @param mouseCoords The `[x, y]` position of the mouse, in canvas coordinates
  * @param mouseOverHandlerFor The handler for the mouse-over (registered by the <Tooltip/>)
  */
-function handleMouseEnterPoint(chartId, seriesName, container, event, datum, plotData, xAxisLinear, yAxisLinear, margin, seriesStyle, backgroundColor, allowTooltip, mouseOverHandlerFor) {
-    const { color, highlightColor, lineWidth } = seriesStyle;
-    const padding = 4;
-    const circleRadius = 5;
-    const circleStroke = lineWidth;
-    const circle = event.currentTarget;
-    d3.select(circle)
-        .attr("r", circleRadius)
-        .style("fill", highlightColor);
-    const index = plotData
-        .findIndex(point => point.n === datum.n && point.n_1 === datum.n_1);
-    /**
-     * Displays basic information about an iterate, generally its neighbors
-     * @param index The index of the iterate
-     */
-    function showInfo(index) {
-        d3.select(`#${seriesName}-${chartId}-poincare-point-${index}`)
-            .attr("r", circleRadius)
-            .style("fill", d3.rgb(highlightColor).brighter(0.7).toString())
-            .style("stroke-width", circleStroke)
-            .style("stroke", color);
-        // grab the (x, y)-coordinates for the plot
-        const iterateN = xAxisLinear.scale(plotData[index].n) + margin.left;
-        const iterateN_1 = yAxisLinear.scale(plotData[index].n_1) + margin.top;
-        const svg = d3.select(container);
-        // add a rectangle that serves as the background for the text (to make the
-        // text readable when the chart is busy)
-        const rect = svg
-            .append("rect")
-            .attr("class", `${seriesName}-${chartId}-poincare-point-text-background`);
-        // add the information about the iterate as a text element
-        const textElement = svg
-            .append("text")
-            .attr('class', `${seriesName}-${chartId}-poincare-point-text`)
-            .attr('fill', highlightColor)
-            .attr('font-family', 'sans-serif')
-            .attr('font-size', 11)
-            .attr('font-weight', 700)
-            .text(`n = ${index}; t = ${formatTime(plotData[index].time)} ms`);
-        // calculate the width and height of the text element
-        const { width, height } = textDimensions(textElement);
-        textElement
-            .attr("transform", `translate(${iterateN - 8}, ${iterateN_1 - circleRadius - circleStroke - padding})`);
-        rect
-            .attr("x", iterateN - padding / 2 - 8)
-            .attr("y", iterateN_1 - padding / 2 - circleRadius - circleStroke - height)
-            .attr("width", width + padding)
-            .attr("height", height + padding / 2)
-            .style("fill", backgroundColor);
-    }
-    if (index > 0) {
-        showInfo(index - 1);
-    }
-    if (index < plotData.length - 1) {
-        showInfo(index + 1);
-    }
-    const [x, y] = d3.pointer(event, container);
-    const currentDatum = (index >= 0) ? plotData[index] : { time: 0, n: 0, n_1: 0, index };
-    if (mouseOverHandlerFor && allowTooltip) {
-        mouseOverHandlerFor(seriesName, currentDatum.time, { series: plotData.map(ip => ({ iterateN: ip.n, iterateN_1: ip.n_1, time: ip.time })), metadata: {} }, [x, y]);
+function handleMouseEnterPoint(seriesName, datum, plotData, mouseCoords, mouseOverHandlerFor) {
+    if (datum === undefined)
+        return;
+    if (mouseOverHandlerFor) {
+        mouseOverHandlerFor(seriesName, datum.time, { series: plotData.map(ip => ({ iterateN: ip.n, iterateN_1: ip.n_1, time: ip.time })), metadata: {} }, mouseCoords);
     }
 }
-function handleMouseLeavePoint(chartId, seriesName, color, mouseLeaverHandlerFor) {
-    d3.selectAll(`.${seriesName}-${chartId}-poincare-points`)
-        .attr("r", 2)
-        .style("fill", color)
-        .style("stroke", "none");
-    d3.selectAll(`.${seriesName}-${chartId}-poincare-point-arrows`).remove();
-    d3.selectAll(`.${seriesName}-${chartId}-poincare-point-text`).remove();
-    d3.selectAll(`.${seriesName}-${chartId}-poincare-point-text-background`).remove();
+/**
+ * Calls the mouse-leave-series handler registered for this series (the highlight is cleared by
+ * the draw function, once the hovered point is cleared)
+ * @param seriesName The name of the series
+ * @param mouseLeaverHandlerFor Registered handler for the series when the mouse leaves
+ */
+function handleMouseLeavePoint(seriesName, mouseLeaverHandlerFor) {
     if (mouseLeaverHandlerFor) {
         mouseLeaverHandlerFor(seriesName);
     }