stream-charts 1.2.0 → 2.0.0

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

@@ -1,146 +1,128 @@
-import { useCallback, useEffect, useMemo, useRef } from 'react';
+import { useCallback, useEffect, useRef } from 'react';
+import { useStreamingTimeAxes } from "./useStreamingTimeAxes";
+import { useHoveredSeries } from "../hooks/useHoveredSeries";
 import { useChart } from "../hooks/useChart";
+import { scatterTooltipPointList, scatterTooltipPoints } from "../tooltips/tooltipUtils";
 import * as d3 from "d3";
-import { setClipPathG } from "./plot";
-import { axesForSeriesGen, continuousAxisIntervals, continuousAxisRanges, continuousAxisZoomHandler, defaultLineStyle, panHandler } from "../axes/axes";
-import { noop } from "../utils";
-import { subscriptionTimeSeriesFor, subscriptionTimeSeriesWithCadenceFor, TimeWindowBehavior } from "../subscriptions/subscriptions";
-import { useDataObservable } from "../hooks/useDataObservable";
+import { clipToArea } from "./plot";
+import { AxisType, checkAxisType, defaultLineStyle } from "../axes/axes";
+import { seriesAt, canvasLocalPoint } from "./hitTesting";
+import { firstIndexAtOrAfter, noop } from "../utils";
+import { NoCurveFactory } from "./constants";
+import { timeSeriesAxisTimes, TimeWindowBehavior } from "../subscriptions/viewDrivers";
+import { useDataSource, useDataSourceRunning, useInitialData } from "../hooks/useDataSource";
+import { extentWith, visibleExtent } from "../axes/autoScale";
+import { growAutoScaledYAxes, useAutoScaleRestart } from "./autoScaleYAxes";
 import { usePlotDimensions } from "../hooks/usePlotDimensions";
-import { useInitialData } from "../hooks/useInitialData";
-import { Optional } from "result-fn";
-import { ContinuousAxisRange } from "../axes/ContinuousAxisRange";
+// how close (in pixels) the mouse must be to a data point to be over that point (rather than over a
+// line segment) -- at least this, or a little more than the markers' radius when they're larger
+const MIN_POINT_HOVER_RADIUS = 6;
+// the radii of the highlights on the points the tooltip shows: the hovered point, and the others
+const TOOLTIP_POINT_RADIUS = 5;
+const TOOLTIP_NEIGHBOR_RADIUS = 3.5;
 /**
- * Renders a streaming scatter 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}
- * hook, and therefore must be a child of the {@link Chart} in order to be plugged in to the
- * chart ecosystem (axes, tracker, tooltip).
+ * Renders a streaming scatter 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).
+ *
+ * The plot never subscribes to the data stream itself: the application owns the data source (and
+ * starts/stops it), and the data source keeps ingesting even while this plot is unmounted. While
+ * the data source is running, this plot listens to its updates through a view driver that only
+ * advances the plot's own view (auto-scroll, cadence) and redraws -- created when the plot mounts
+ * (or the data source starts) and always torn down when it unmounts (or the data source stops).
+ *
+ * Internally, this no longer creates/updates SVG `<path>`/`<circle>` elements. Instead, it
+ * registers a single draw function with the chart's {@link CanvasContext} that redraws every
+ * series from scratch each time the canvas repaints. Mouse hover (for the tooltip) is handled by
+ * hit-testing the mouse position against the last-drawn series geometry (see `hitTesting.ts`) on a
+ * `mousemove` listener attached directly to the canvas, since canvas has no per-shape events.
+ *
+ * When the data source is paused, hovering over a series shows the tooltip (when there's one),
+ * and highlights the points it shows; a y-axis with `autoScale` set grows to fit the data on screen.
  *
  * @param props The properties associated with the scatter plot
+ * @return `null` (the plot draws onto the chart's canvas)
  * @example
- <ScatterPlot
- interpolation={interpolation}
- axisAssignments={new Map([
- ['test2', assignAxes("x-axis-2", "y-axis-2")],
- ])}
- dropDataAfter={10000}
- panEnabled={true}
- zoomEnabled={true}
- zoomKeyModifiersRequired={true}
- />
+ *  <ScatterPlot
+ *      interpolation={interpolation}
+ *      axisAssignments={new Map([
+ *          ['test2', assignAxes("x-axis-2", "y-axis-2")],
+ *      ])}
+ *      panEnabled={true}
+ *      zoomEnabled={true}
+ *      zoomKeyModifiersRequired={true}
+ *  />
  */
 export function ScatterPlot(props) {
-    const { chartId, container, mainG, axes, color, seriesStyles, seriesFilter, mouse, hoveredSeriesRef, } = useChart();
+    var _a;
+    const { chartId, canvasContext, axes, color, seriesStyles, seriesFilter, mouse, backgroundColor, } = useChart();
+    const { hoveredSeriesName } = useHoveredSeries();
     const { initialData } = useInitialData();
-    const { xAxesState, yAxesState, setAxisIntervalFor, updateAxisRanges = noop, onUpdateAxesInterval, axesRanges, } = axes;
+    const { xAxesState, yAxesState, updateAxisRanges = noop, axisRangeFor, } = axes;
     const { mouseOverHandlerFor, mouseLeaveHandlerFor } = mouse;
     const { plotDimensions, margin } = usePlotDimensions();
-    const { seriesObservable, windowingTime = 100, shouldSubscribe, onSubscribe = noop, onUpdateData, } = useDataObservable();
-    const { axisAssignments = new Map(), interpolation = d3.curveLinear, dropDataAfter = Infinity, panEnabled = false, zoomEnabled = false, zoomKeyModifiersRequired = true, withCadenceOf, timeWindowBehavior = TimeWindowBehavior.SCROLL, } = props;
-    const initialTimes = useMemo(() => {
-        return new Map(Array.from(axesRanges().entries())
-            .map(([axisId, range]) => ([axisId, range.original.start])));
-    }, [axesRanges]);
+    // the application-owned source of the data, and whether it's running (streaming)
+    const dataSource = useDataSource();
+    const running = useDataSourceRunning(dataSource);
+    const { axisAssignments = new Map(), interpolation = d3.curveLinear, panEnabled = false, zoomEnabled = false, zoomKeyModifiersRequired = true, withCadenceOf, timeWindowBehavior = TimeWindowBehavior.SCROLL, markerRadius, hideMarkersWhileRunning = true, highlightAxesOnMouseOver = false, 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 "dataRef"
+    // array is what the draw function iterates over, 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
+    // time-series, e.i. an array of BaseSeries<Datum> 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<Datum>), 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 canvas draw function, and so as
+    // these are updated, the new data is picked up the next time the canvas redraws.
     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(new Map());
-    const subscriptionRef = useRef(undefined);
-    const isSubscriptionClosed = () => subscriptionRef.current === undefined || subscriptionRef.current.closed;
-    const allowTooltip = useRef(isSubscriptionClosed());
-    useEffect(() => {
-        currentTimeRef.current = new Map(Array.from(xAxesState.axes.keys()).map(id => [id, 0]));
-    }, [xAxesState]);
-    // calculates the distinct series IDs that cover all the series in the plot
-    const axesForSeries = useMemo(() => axesForSeriesGen(initialData, axisAssignments, xAxesState), [initialData, axisAssignments, xAxesState]);
-    // updates the timing using the onUpdateTime and updatePlot references. This and the references
-    // defined above allow the axes' times to be updated properly by avoid stale reference to these
-    // functions.
-    const updateTimingAndPlot = useCallback((ranges) => {
-        if (mainG !== null) {
-            onUpdateTimeRef.current(ranges);
-            updatePlotRef.current(ranges, mainG);
-            if (onUpdateAxesInterval) {
-                setTimeout(() => {
-                    const times = new Map();
-                    ranges.forEach((range, name) => times.set(name, range.current));
-                    onUpdateAxesInterval(times);
-                }, 0);
-            }
-        }
-    }, [mainG, onUpdateAxesInterval]);
-    // 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.
-    useEffect(() => {
-        dataRef.current = initialData.slice();
-        seriesRef.current = new Map(initialData.map(series => [series.name, series]));
-        currentTimeRef.current = new Map(Array.from(xAxesState.axes.keys()).map(id => [id, 0]));
-        updateTimingAndPlot(new Map(Array.from(continuousAxisRanges(xAxesState.axes).entries())
-            .map(([id, range]) => {
-            // grab the current range, then calculate the minimum time from the initial data, and
-            // set that as the start, and then add the range to it for the end time
-            const [start, end] = range.original.asTuple();
-            const minTime = initialData
-                .filter(srs => { var _a; return ((_a = axisAssignments.get(srs.name)) === null || _a === void 0 ? void 0 : _a.xAxis) === id; })
-                .reduce((tMin, series) => Math.min(tMin, !series.isEmpty() ? series.data[0].time : tMin), Infinity);
-            const startTime = minTime === Infinity ? 0 : minTime;
-            return [id, ContinuousAxisRange.from(startTime, startTime + end - start)];
-        })));
-    }, 
-    // ** not happy about this **
-    // only want this effect to run when the initial data is changed, which mean all the
-    // other dependencies are recalculated anyway.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [initialData]);
-    /**
-     * Adjusts the time-range and updates the plot when the plot is dragged to the left or right
-     * @param deltaX The amount that the plot is dragged
-     * @param plotDimensions The dimensions of the plot
-     * @param ranges A map holding the axis ID and its associated time range
-     */
-    const onPan = useCallback((x, plotDimensions, ranges) => panHandler(axesForSeries, margin, setAxisIntervalFor, xAxesState)(x, plotDimensions, ranges), [axesForSeries, margin, setAxisIntervalFor, xAxesState]);
-    /**
-     * 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.
-     * @param transform The d3 zoom transformation information
-     * @param x The x-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, plotDimensions, ranges) => continuousAxisZoomHandler(axesForSeries, margin, setAxisIntervalFor, xAxesState)(transform, x, plotDimensions, ranges), [axesForSeries, margin, setAxisIntervalFor, xAxesState]);
+    // the last-drawn geometry for each series, in canvas coordinates, used for hit-testing mouse
+    // hover on `mousemove` (see the effect below that wires up the listener)
+    const geometryRef = useRef(new Map());
+    // the name of the series the mouse was over on the previous `mousemove`, so we know when to
+    // fire a "leave" for the old series before firing an "over" for the new one
+    const lastHoveredRef = useRef(undefined);
+    // the points the tooltip is showing (for the hovered series), which the plot highlights -- set
+    // on mouse-over while a tooltip is shown, and cleared when the mouse leaves the series
+    const tooltipPointsRef = useRef(undefined);
+    // 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));
     const updatePlot = useCallback(
     /**
-     * Updates the plot data for the specified time-range, which may have changed due to zoom or pan
-     * @param timeRanges The current time range
-     * @param mainGElem The main <g> element selection for that holds the plot
+     * (Re-)registers this plot's draw function with the canvas context and requests a redraw.
+     * Replaces the old version, which directly mutated SVG `<path>`/`<circle>` elements bound
+     * via d3's enter/update/exit join. Canvas has no persistent elements to join against, so
+     * the draw function just redraws every series from its current data/scale state each time
+     * it's invoked -- there's no separate "update" case to handle.
+     *
+     * Pan/zoom behavior setup lives in a separate effect (see below), not here -- this
+     * function runs on every data tick (each `windowingTime` interval), and recreating/
+     * reattaching a `d3.drag()`/`d3.zoom()` behavior that often is pure overhead with no
+     * benefit, since panEnabled/zoomEnabled/plotDimensions/margin change far less often than
+     * the data does.
+     * @param cc The canvas context to register the draw function with
      */
-    (timeRanges, mainGElem) => {
-        if (container) {
-            // select the svg element bind the data to them
-            const svg = d3.select(container);
-            // create a map associating series-names to their time-series.
+    (cc) => {
+        const draw = (context) => {
+            var _a;
+            // const __drawStart = performance.now()
+            // let __totalRetained = 0
+            // let __totalProcessed = 0
+            const { context2D } = context;
+            // create a map associating series-names with 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 is uses a map(series_name -> series). The seriesRef is use to append
+            // performance-related confusion: wondering where the dataRef is updated? well, it isn't
+            // updated 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 use 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
@@ -148,44 +130,10 @@ export function ScatterPlot(props) {
                 series.name,
                 series.data
             ]));
-            // 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, plotDimensions, 
-                    // Array.from(boundedSeries.keys()),
-                    timeRanges);
-                    updatePlotRef.current(timeRanges, 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) {
-                const zoom = d3.zoom()
-                    .filter(event => !zoomKeyModifiersRequired || event.shiftKey || event.ctrlKey)
-                    .scaleExtent([0, 10])
-                    .translateExtent([[margin.left, margin.top], [plotDimensions.width, plotDimensions.height]])
-                    .on("zoom", event => {
-                    onZoom(event.transform, event.sourceEvent.offsetX - margin.left, plotDimensions, timeRanges);
-                    updatePlotRef.current(timeRanges, mainGElem);
-                });
-                svg.call(zoom);
-            }
-            // define the clip-path so that the series lines don't go beyond the plot area
-            const clipPathId = setClipPathG(chartId, mainGElem, plotDimensions);
+            context2D.save();
+            clipToArea(context, plotDimensions, { x: margin.left, y: margin.top });
+            context2D.translate(margin.left, margin.top);
+            const newGeometry = new Map();
             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
@@ -193,186 +141,295 @@ export function ScatterPlot(props) {
                 if (xAxisLinear === undefined || yAxisLinear === undefined)
                     return;
                 // grab the style for the series
-                const { color, lineWidth, highlightColor, highlightWidth } = seriesStyles.get(name) || defaultLineStyle();
+                const { color: seriesColor, lineWidth, highlightColor, highlightWidth } = seriesStyles.get(name) || defaultLineStyle();
                 // only show the data for which the filter matches
                 const plotData = (name.match(seriesFilter)) ? data : [];
-                // create the time-series paths
-                mainGElem
-                    .selectAll(`#${name}-${chartId}-scatter`)
-                    .data([[], plotData], () => `${name}`)
-                    .join(enter => enter
-                    .append("path")
-                    .attr("class", 'time-series-lines')
-                    .attr("id", `${name}-${chartId}-scatter`)
-                    .attr("data-series-name", name)
-                    .attr("d", d3.line()
-                    .x((d) => xAxisLinear.scale(d.time) || 0)
-                    .y((d) => yAxisLinear.scale(d.value) || 0)
-                    .curve(interpolation))
-                    .attr("fill", "none")
-                    .attr("stroke", hoveredSeriesRef.current === name ? highlightColor : color)
-                    .attr("stroke-width", hoveredSeriesRef.current === name ? highlightWidth : lineWidth)
-                    .attr('transform', `translate(${margin.left}, ${margin.top})`)
-                    .attr("clip-path", `url(#${clipPathId})`)
-                    .on("mouseover", (event, datumArray) => 
-                // recall that this handler is passed down via the "useChart" hook
-                handleMouseOverSeries(container, xAxisLinear, name, datumArray, event, margin, seriesStyles, allowTooltip.current, mouseOverHandlerFor(`tooltip-${chartId}`)))
-                    .on("mouseleave", event => handleMouseLeaveSeries(name, event.currentTarget, seriesStyles, mouseLeaveHandlerFor(`tooltip-${chartId}`))), update => update, exit => exit.remove());
+                const isHovered = hoveredSeriesName === name;
+                // skip the expensive per-point work below for retained-but-off-screen data:
+                // `plotData` can hold far more history than is ever visible (dropDataAfter is
+                // independent of, and often much larger than, the axis's current scrolling
+                // window), so iterating the *full* retained array every frame does a lot of
+                // work whose result is immediately thrown away as off-screen. Binary-search
+                // for where the visible domain begins, and only process from there on --
+                // backing up by one point so a line entering from off-screen still renders
+                // correctly across the boundary.
+                const [domainStart] = xAxisLinear.scale.domain();
+                const startIndex = Math.max(0, firstIndexAtOrAfter(plotData, domainStart, (d) => d.x) - 1);
+                const showMarkers = markerRadius != null && markerRadius >= 0 && (!running || !hideMarkersWhileRunning);
+                const markerRadiusResolved = isHovered ? markerRadius + 2 : markerRadius;
+                const segments = [];
+                let currentSegment = [];
+                const screenPoints = [];
+                context2D.fillStyle = isHovered ? highlightColor : seriesColor;
+                for (let i = startIndex; i < plotData.length; i++) {
+                    const d = plotData[i];
+                    const x = xAxisLinear.scale(d.x);
+                    const y = yAxisLinear.scale(d.y);
+                    // record geometry (outer/canvas coordinate space, margin baked in) for
+                    // mousemove hit-testing, regardless of on/off-screen -- a point just past
+                    // the edge should still be hoverable at the boundary
+                    screenPoints.push([x + margin.left, y + margin.top]);
+                    // the first point in this loop is the one deliberately backed up before
+                    // the visible domain (see startIndex above); include it in the segment so
+                    // the interpolated line entering from the left is smoothly clipped by the
+                    // canvas's clip region as the plot scrolls, rather than the line abruptly
+                    // popping into/out of existence right at the boundary
+                    const isLeftEdgeContinuationPoint = i === startIndex && x < 0;
+                    if (!isLeftEdgeContinuationPoint && (x < 0 || x > plotDimensions.width)) {
+                        if (currentSegment.length > 0) {
+                            segments.push(currentSegment);
+                            currentSegment = [];
+                        }
+                        continue;
+                    }
+                    currentSegment.push([x, y]);
+                    // point markers (one circle per datum) -- suppressed while streaming
+                    // because redrawing many circles every frame is more work than a single
+                    // line path
+                    if (showMarkers) {
+                        context2D.beginPath();
+                        context2D.arc(x, y, markerRadiusResolved, 0, 2 * Math.PI);
+                        context2D.fill();
+                    }
+                }
+                if (currentSegment.length > 0)
+                    segments.push(currentSegment);
+                // draw the series line (interpolation is applied via a Path2D built through a
+                // d3 line generator so that custom curve factories -- e.g. curveBasis,
+                // curveStep -- keep working exactly as they did with the SVG path)
+                context2D.strokeStyle = isHovered ? highlightColor : seriesColor;
+                context2D.lineWidth = isHovered ? highlightWidth : lineWidth;
+                segments.forEach(segment => {
+                    var _a;
+                    const path = new Path2D((_a = d3.line().curve(interpolation)(segment)) !== null && _a !== void 0 ? _a : "");
+                    context2D.stroke(path);
+                });
+                newGeometry.set(name, {
+                    points: screenPoints,
+                    asLine: true,
+                    hitRadius: Math.max(6, (isHovered ? highlightWidth : lineWidth) + 4)
+                });
+                if (showMarkers) {
+                    // markers get their own, generously-sized hit target keyed under a
+                    // derived name so a marker hover can be distinguished from a line hover
+                    // if the caller ever wants to (currently treated the same on mousemove)
+                    newGeometry.set(`${name}-markers`, {
+                        points: screenPoints,
+                        hitRadius: markerRadiusResolved + 3
+                    });
+                }
             });
-        }
+            // highlights the points the tooltip is showing (on top of the series): the
+            // hovered point is drawn larger than its neighbors (or than a segment's ends)
+            const tooltipPoints = tooltipPointsRef.current;
+            if (tooltipPoints !== undefined && !running && tooltipPoints.seriesName.match(seriesFilter)) {
+                const [xAxisLinear, yAxisLinear] = axesFor(tooltipPoints.seriesName, axisAssignments, axisId => xAxesState.axisFor(axisId).getOrUndefined(), axisId => yAxesState.axisFor(axisId).getOrUndefined());
+                if (xAxisLinear !== undefined && yAxisLinear !== undefined) {
+                    const { highlightColor = color } = (_a = seriesStyles.get(tooltipPoints.seriesName)) !== null && _a !== void 0 ? _a : {};
+                    const { points } = tooltipPoints;
+                    scatterTooltipPointList(points).forEach(datum => {
+                        const isHoveredPoint = points.kind === 'point' && datum === points.point;
+                        context2D.beginPath();
+                        context2D.arc(xAxisLinear.scale(datum.x), yAxisLinear.scale(datum.y), isHoveredPoint ? TOOLTIP_POINT_RADIUS : TOOLTIP_NEIGHBOR_RADIUS, 0, 2 * Math.PI);
+                        context2D.fillStyle = highlightColor;
+                        context2D.fill();
+                        // outlined in the background color, so it stands out from the line
+                        context2D.lineWidth = 1.5;
+                        context2D.strokeStyle = backgroundColor;
+                        context2D.stroke();
+                    });
+                }
+            }
+            geometryRef.current = newGeometry;
+            context2D.restore();
+        };
+        /**
+         * Grows the auto-scaling y-axes (see `ContinuousAxis`'s `autoScale` prop) to fit the
+         * data that's on screen: the data of the shown series (those matching the filter)
+         * within their x-axis' current window, including where their lines cross the window's
+         * edges (see `visibleExtent`). Since an axis only ever grows, the data that has
+         * scrolled off screen was already accounted for while it was on screen, so only the
+         * visible data needs checking each frame. Registered to run before the axes draw
+         * (they're at z-index 0), so the axes and the series are drawn with the grown domain
+         * in the same frame.
+         */
+        const autoScaleYAxes = () => {
+            const withLine = interpolation !== NoCurveFactory;
+            const extents = new Map();
+            dataRef.current.forEach(series => {
+                if (!series.name.match(seriesFilter))
+                    return;
+                const [xAxisLinear, yAxisLinear] = axesFor(series.name, axisAssignments, axisId => xAxesState.axisFor(axisId).getOrUndefined(), axisId => yAxesState.axisFor(axisId).getOrUndefined());
+                if (xAxisLinear === undefined || (yAxisLinear === null || yAxisLinear === void 0 ? void 0 : yAxisLinear.autoScale) === undefined)
+                    return;
+                const [start, end] = xAxisLinear.scale.domain();
+                const seriesExtent = visibleExtent(series.data, [start, end], yAxisLinear.scale, withLine);
+                if (seriesExtent === undefined)
+                    return;
+                const extent = extents.get(yAxisLinear.axisId);
+                extents.set(yAxisLinear.axisId, extent === undefined ? seriesExtent : extentWith(extentWith(extent, seriesExtent[0]), seriesExtent[1]));
+            });
+            growAutoScaledYAxes(extents, { yAxes: yAxesState.axes, axisRangeFor, updateAxisRanges });
+        };
+        cc.register(`scatter-plot-autoscale-${chartId}`, autoScaleYAxes, -10);
+        cc.register(`scatter-plot-${chartId}`, draw, 10);
+        cc.requestRedraw();
     }, [
-        container, panEnabled, zoomEnabled, chartId, plotDimensions, margin, onPan,
-        zoomKeyModifiersRequired, onZoom, axisAssignments,
-        xAxesState, yAxesState,
-        seriesStyles, seriesFilter, interpolation,
-        mouseOverHandlerFor, mouseLeaveHandlerFor,
-        hoveredSeriesRef
+        chartId, plotDimensions, axisAssignments, xAxesState, yAxesState, seriesStyles, seriesFilter,
+        interpolation, hoveredSeriesName, markerRadius, running, hideMarkersWhileRunning, axisRangeFor,
+        updateAxisRanges, color, backgroundColor, 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(noop);
-    useEffect(() => {
-        updatePlotRef.current = updatePlot;
-    }, [updatePlot]);
-    const onUpdateTimeRef = useRef(updateAxisRanges);
-    useEffect(() => {
-        onUpdateTimeRef.current = updateAxisRanges;
-    }, [updateAxisRanges]);
-    // memoized function for subscribing to the chart-data observable
-    const subscribe = useCallback(() => {
-        if (seriesObservable === undefined || mainG === null)
-            return undefined;
-        if (withCadenceOf !== undefined) {
-            return subscriptionTimeSeriesWithCadenceFor(seriesObservable, onSubscribe, windowingTime, axisAssignments, xAxesState, onUpdateData, dropDataAfter, updateTimingAndPlot, 
-            // as new data flows into the subscription, the subscription
-            // updates this map directly (for performance)
-            seriesRef.current, (axisId, end) => currentTimeRef.current.set(axisId, end), withCadenceOf);
-        }
-        return subscriptionTimeSeriesFor(seriesObservable, onSubscribe, windowingTime, axisAssignments, xAxesState, onUpdateData, dropDataAfter, updateTimingAndPlot, 
-        // as new data flows into the subscription, the subscription
-        // updates this map directly (for performance)
-        seriesRef.current, (axisId, end) => currentTimeRef.current.set(axisId, end), timeWindowBehavior, initialTimes);
-    }, [
-        axisAssignments, dropDataAfter, mainG,
-        onSubscribe, onUpdateData,
-        seriesObservable, updateTimingAndPlot, windowingTime, xAxesState,
+    // the time axes: their ranges, the view driver, panning and zooming, highlighting, and
+    // reporting the axes' intervals -- see `useStreamingTimeAxes`
+    useStreamingTimeAxes({
+        canvasContext,
+        dataSource,
+        running,
+        initialData,
+        timeOf: datum => datum.x,
+        axisTimesFor: timeSeriesAxisTimes(axisAssignments, xAxesState),
+        axisAssignments,
+        updatePlot,
+        onDataReset: () => {
+            dataRef.current = initialData.slice();
+            seriesRef.current = new Map(initialData.map(series => [series.name, series]));
+        },
+        allowTooltipRef: allowTooltip,
+        panEnabled,
+        zoomEnabled,
+        zoomKeyModifiersRequired,
+        onZoomReset,
         withCadenceOf,
-        initialTimes, timeWindowBehavior
-    ]);
-    const timeRangesRef = useRef(new Map());
+        timeWindowBehavior,
+        highlightAxesOnMouseOver,
+    });
+    // wires up a single mousemove/mouseleave listener on the shared canvas to replace the old
+    // per-element SVG mouseover/mouseleave handlers. Hit-tests the mouse position against the
+    // last-drawn geometry (see `geometryRef`, populated by the draw function above).
     useEffect(() => {
-        if (container && mainG) {
-            // so this gets a bit complicated. the time-ranges need to be updated whenever the time-ranges
-            // change. for example, as data is streamed in, the times change, and then we need to update the
-            // time-range. however, we want to keep the time-ranges to reflect their original scale so that
-            // we can zoom properly (so the updates can't fuck with the scale). At the same time, when the
-            // interpolation changes, then the update plot changes, and the time-ranges must maintain their
-            // original scale as well.
-            if (timeRangesRef.current.size === 0) {
-                // when no time-ranges have yet been created, then create them and hold on to a mutable
-                // reference to them
-                timeRangesRef.current = continuousAxisRanges(xAxesState.axes);
+        if (!canvasContext)
+            return;
+        const canvas = canvasContext.canvas;
+        const handleMove = (event) => {
+            if (!allowTooltip.current)
+                return;
+            const [x, y] = canvasLocalPoint(event, canvas);
+            const hit = seriesAt(x, y, geometryRef.current);
+            // markers are recorded under a "<name>-markers" key; normalize back to the
+            // underlying series name so callers only ever see the real series name.
+            // NOTE: `hit?.name.endsWith(...)` here would be unsafe -- `?.` only protects the
+            // `.name` access, not the chained `.endsWith(...)` call, so it would throw a
+            // TypeError on every mousemove where `hit` is undefined (i.e. most of them).
+            const hitName = hit !== undefined
+                ? (hit.name.endsWith('-markers') ? hit.name.slice(0, -'-markers'.length) : hit.name)
+                : undefined;
+            // only fire enter/leave transitions when the hovered series actually changes --
+            // but always recompute and re-report the tooltip content below for the *current*
+            // mouse position, even while still hovering the same series, so the tooltip keeps
+            // tracking the mouse as it moves across a series instead of freezing at wherever
+            // the hover was first detected.
+            if (hitName !== lastHoveredRef.current) {
+                if (lastHoveredRef.current !== undefined) {
+                    handleMouseLeaveSeries(lastHoveredRef.current, mouseLeaveHandlerFor(`tooltip-${chartId}`));
+                }
+                lastHoveredRef.current = hitName;
             }
-            else {
-                // when the time-ranges already exist, then we want to update the time-ranges for each
-                // existing time-range in a way that maintains the original scale.
-                const intervals = continuousAxisIntervals(xAxesState.axes);
-                timeRangesRef.current
-                    .forEach((range, id, rangesMap) => {
-                    const [start, end] = Optional.ofNullable(intervals.get(id))
-                        .map(interval => interval.asTuple())
-                        .getOrThrow(() => new Error(`Unable to retrieve interval for axis; axis_id: ${id}`));
-                    // .getOrElse([NaN, NaN])
-                    if (!isNaN(start) && !isNaN(end)) {
-                        // update the reference map with the new (start, end) portion of the range,
-                        // while keeping the original scale intact
-                        rangesMap.set(id, range.update(start, end));
-                    }
-                });
+            // the points the tooltip shows (and the plot highlights): the point under the mouse
+            // and its neighbors, or the two ends of the segment under the mouse
+            let tooltipPoints = undefined;
+            if (hitName !== undefined) {
+                const series = seriesRef.current.get(hitName);
+                const mouseOverHandler = mouseOverHandlerFor(`tooltip-${chartId}`);
+                const [xAxisLinear, yAxisLinear] = axesFor(hitName, axisAssignments, axisId => xAxesState.axisFor(axisId).getOrUndefined(), axisId => yAxesState.axisFor(axisId).getOrUndefined());
+                if (series !== undefined && xAxisLinear !== undefined && yAxisLinear !== undefined && mouseOverHandler !== undefined) {
+                    const points = scatterTooltipPoints(series.data, [x - margin.left, y - margin.top], xAxisLinear.scale, yAxisLinear.scale, Math.max(MIN_POINT_HOVER_RADIUS, (markerRadius !== null && markerRadius !== void 0 ? markerRadius : 0) + 3));
+                    tooltipPoints = { seriesName: hitName, points };
+                    const time = Math.round(xAxisLinear.scale.invert(x - margin.left));
+                    mouseOverHandler(hitName, time, { series: series.data, metadata: { points } }, [x, y]);
+                }
             }
-            updatePlot(timeRangesRef.current, mainG);
-        }
-    }, [chartId, color, container, mainG, plotDimensions, updatePlot, xAxesState]);
-    // 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.
+            updateTooltipPoints(tooltipPoints);
+        };
+        // remembers the points the tooltip shows, and redraws (to highlight them) when they change
+        const updateTooltipPoints = (tooltipPoints) => {
+            const previous = tooltipPointsRef.current;
+            if (previous === undefined && tooltipPoints === undefined)
+                return;
+            if (previous !== undefined && tooltipPoints !== undefined &&
+                previous.seriesName === tooltipPoints.seriesName &&
+                previous.points.kind === tooltipPoints.points.kind) {
+                const previousList = scatterTooltipPointList(previous.points);
+                const list = scatterTooltipPointList(tooltipPoints.points);
+                if (previousList.length === list.length && previousList.every((datum, index) => datum === list[index]))
+                    return;
+            }
+            tooltipPointsRef.current = tooltipPoints;
+            canvasContext.requestRedraw();
+        };
+        const handleLeaveCanvas = () => {
+            if (lastHoveredRef.current !== undefined) {
+                handleMouseLeaveSeries(lastHoveredRef.current, mouseLeaveHandlerFor(`tooltip-${chartId}`));
+                lastHoveredRef.current = undefined;
+            }
+            updateTooltipPoints(undefined);
+        };
+        canvas.addEventListener('mousemove', handleMove);
+        canvas.addEventListener('mouseleave', handleLeaveCanvas);
+        return () => {
+            canvas.removeEventListener('mousemove', handleMove);
+            canvas.removeEventListener('mouseleave', handleLeaveCanvas);
+        };
+    }, [canvasContext, chartId, margin, axisAssignments, xAxesState, yAxesState, mouseOverHandlerFor, mouseLeaveHandlerFor, markerRadius]);
+    // this plot needs a data source (see the `Chart`'s `dataSource` prop)
     useEffect(() => {
-        var _a;
-        if (shouldSubscribe && subscriptionRef.current === undefined) {
-            subscriptionRef.current = subscribe();
-            allowTooltip.current = false;
+        if (dataSource === undefined) {
+            console.error("ScatterPlot requires a data source; set the enclosing Chart's `dataSource` prop");
         }
-        else if (!shouldSubscribe && subscriptionRef.current !== undefined) {
-            (_a = subscriptionRef.current) === null || _a === void 0 ? void 0 : _a.unsubscribe();
-            subscriptionRef.current = undefined;
-            allowTooltip.current = true;
-        }
-    }, [shouldSubscribe, subscribe]);
+    }, [dataSource]);
+    // unregister this plot's draw function (and its auto-scaling step) on unmount
+    useEffect(() => {
+        return () => {
+            if (canvasContext) {
+                canvasContext.unregister(`scatter-plot-autoscale-${chartId}`);
+                canvasContext.unregister(`scatter-plot-${chartId}`);
+            }
+        };
+    }, [canvasContext, chartId]);
+    // new data, new scale: restarts the auto-scaling y-axes when the data source is replaced
+    useAutoScaleRestart(dataSource, { yAxes: yAxesState.axes, axisRangeFor, updateAxisRanges });
     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
+ * Attempts to locate the x- and y-axes for the specified series. If the series has no axis
+ * assignment, then uses the default (first) x- and y-axes.
  * @param seriesName Name of the series for which to retrieve the axis
  * @param axisAssignments A map holding the series name and the associated x- and y-axes assigned
  * to that series. Note that the series in the axis-assignment map is merely a subset of the set
  * of series names.
  * @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(seriesName, axisAssignments, xAxisFor, yAxisFor) {
     const axes = axisAssignments.get(seriesName);
     const xAxis = xAxisFor((axes === null || axes === void 0 ? void 0 : axes.xAxis) || "");
-    const xAxisLinear = xAxis;
     const yAxis = yAxisFor((axes === null || axes === void 0 ? void 0 : axes.yAxis) || "");
+    checkAxisType("ScatterPlot", "x", xAxis, AxisType.ContinuousNumeric);
+    checkAxisType("ScatterPlot", "y", yAxis, AxisType.ContinuousNumeric);
+    const xAxisLinear = xAxis;
     const yAxisLinear = yAxis;
-    if (xAxis && !xAxisLinear) {
-        throw Error("Scatter plot requires that x-axis be of type LinearAxis");
-    }
-    if (yAxis && !yAxisLinear) {
-        throw Error("Scatter plot requires that y-axis be of type LinearAxis");
-    }
     return [xAxisLinear, yAxisLinear];
 }
 /**
- * Renders a tooltip showing the neuron, spike time, and the spike strength when the mouse hovers over a spike.
- * @param container The chart container
- * @param xAxis The x-axis
- * @param seriesName The name of the series (i.e. the neuron ID)
- * @param series The time series
- * @param event The mouse-over series event
- * @param margin The plot margin
- * @param seriesStyles The series style information (needed for (un)highlighting)
- * @param allowTooltip When set to `false` won't show tooltip, even if it is visible (used by pan)
- * @param mouseOverHandlerFor The handler for the mouse over (registered by the <Tooltip/>)
- */
-function handleMouseOverSeries(container, xAxis, seriesName, series, event, margin, seriesStyles, allowTooltip, mouseOverHandlerFor) {
-    // grab the time needed for the tooltip ID
-    const [x, y] = d3.pointer(event, container);
-    const time = Math.round(xAxis.scale.invert(x - margin.left));
-    const { highlightColor, highlightWidth } = seriesStyles.get(seriesName) || defaultLineStyle();
-    // Use d3 to select element, change color and size
-    d3.select(event.currentTarget)
-        .attr('stroke', highlightColor)
-        .attr('stroke-width', highlightWidth);
-    if (mouseOverHandlerFor && allowTooltip) {
-        mouseOverHandlerFor(seriesName, time, { series, metadata: {} }, [x, y]);
-    }
-}
-/**
- * Unselects the time series and calls the mouse-leave-series handler registered for this series.
+ * Calls the mouse-leave-series handler registered for this series. Replaces the old version, which
+ * also reset the hovered SVG element's stroke color/width directly; that reset is now implicit --
+ * once `hoveredSeriesName` is cleared, the next redraw simply paints the series in its normal
+ * (non-highlighted) style.
  * @param seriesName The name of the series (i.e. the neuron ID)
- * @param segment The SVG line element representing the spike, over which the mouse is hovering.
- * @param seriesStyles The styles for the series (for (un)highlighting)
  * @param mouseLeaverHandlerFor Registered handler for the series when the mouse leaves
  */
-function handleMouseLeaveSeries(seriesName, segment, seriesStyles, mouseLeaverHandlerFor) {
-    const { color, lineWidth } = seriesStyles.get(seriesName) || defaultLineStyle();
-    d3.select(segment)
-        .attr('stroke', color)
-        .attr('stroke-width', lineWidth);
+function handleMouseLeaveSeries(seriesName, mouseLeaverHandlerFor) {
     if (mouseLeaverHandlerFor) {
         mouseLeaverHandlerFor(seriesName);
     }