stream-charts 1.2.0 → 2.0.0

package/src/app/charts/plots/RasterPlot.tsx

@@ -1,35 +1,34 @@
-import {AxesAssignment, setClipPathG} from "./plot";
-import * as d3 from "d3";
-import {ZoomTransform} from "d3";
+import {type AxesAssignment, clipToArea, type Series} from "./plot";
+import {useStreamingTimeAxes} from "./useStreamingTimeAxes";
+import {useHoveredSeries} from "../hooks/useHoveredSeries";
 import {noop} from "../utils";
-import {NoTooltipMetadata, useChart} from "../hooks/useChart";
-import React, {useCallback, useEffect, useMemo, useRef} from "react";
-import {Datum, PixelDatum, TimeSeries} from "../series/timeSeries";
-import {GSelection} from "../d3types";
+import {useChart} from "../hooks/useChart";
+import type {RasterTooltipMetadata} from "../tooltips/tooltipUtils";
+import {useCallback, useEffect, useRef} from "react";
+import type {Datum, TimeSeries} from "../series/timeSeries";
 import {
-    axesForSeriesGen,
-    BaseAxis,
-    continuousAxisIntervals,
-    continuousAxisRanges,
-    continuousAxisZoomHandler,
-    ContinuousNumericAxis,
+    type BaseAxis,
+    AxisType,
+    checkAxisType,
+    type ContinuousNumericAxis,
     defaultLineStyle,
-    OrdinalStringAxis,
-    panHandler,
-    SeriesLineStyle
+    type OrdinalStringAxis,
+    type SeriesLineStyle
 } from "../axes/axes";
-import {Observable, Subscription} from "rxjs";
-import {Dimensions, Margin} from "../styling/margins";
-import {subscriptionTimeSeriesFor, subscriptionTimeSeriesWithCadenceFor} from "../subscriptions/subscriptions";
-import {useDataObservable} from "../hooks/useDataObservable";
-import {TimeSeriesChartData} from "../series/timeSeriesChartData";
+import type {CanvasContext} from "../d3types";
+import {seriesAt, canvasLocalPoint, type SeriesGeometry} from "./hitTesting";
+import type {Margin} from "../styling/margins";
+import {timeSeriesAxisTimes} from "../subscriptions/viewDrivers";
+import {useDataSource, useDataSourceRunning, useInitialData} from "../hooks/useDataSource";
+import type {TimeSeriesChartData} from "../series/timeSeriesChartData";
 import {usePlotDimensions} from "../hooks/usePlotDimensions";
-import {useInitialData} from "../hooks/useInitialData";
-import {TooltipData} from "../hooks/useTooltip";
-import {AxisInterval} from "../axes/AxisInterval";
-import {Optional} from "result-fn";
+import type {TooltipData} from "../hooks/useTooltip";
 import {ContinuousAxisRange} from "../axes/ContinuousAxisRange";
+import {FastShiftArray} from "fast-shift-array";
 
+/**
+ * The properties of the {@link RasterPlot}
+ */
 export interface Props {
     /**
      * Holds the mapping between a series and the axis it uses (is assigned). The
@@ -37,11 +36,6 @@ export interface Props {
      * object holding the ID of the assigned x-axis and y-axis.
      */
     axisAssignments?: Map<string, AxesAssignment>
-    /**
-     * The number of milliseconds of data to hold in memory before dropping it. Defaults to
-     * infinity (i.e. no data is dropped)
-     */
-    dropDataAfter?: number
     /**
      * Enables panning (default is false)
      */
@@ -66,18 +60,41 @@ export interface Props {
     withCadenceOf?: number
     /**
      * The (optional, default = 2 pixels) top and bottom margin (in pixels) for the spike lines in the plot.
-     * Margins on individual series can also be set through the {@link Chart.seriesStyles} property.
+     * Margins on individual series can also be set through the {@link ChartProps.seriesStyles} property.
      */
     spikeMargin?: number
+    /**
+     * When true, hovering over a series also highlights the x- and y-axes it is plotted
+     * against (in the series' own highlight color/width). Defaults to `false`.
+     */
+    highlightAxesOnMouseOver?: boolean
+    /**
+     * Called whenever this plot (re)creates its zoom behavior, handing
+     * the caller a `resetZoom` function that programmatically clears d3-zoom's own accumulated
+     * scale/pan state back to identity. See {@link ScatterPlot}'s identical prop for the full
+     * explanation of why this is needed. Only meaningful (called) while `zoomEnabled` is true.
+     */
+    onZoomReset?: (resetZoom: () => void) => void
 }
 
 /**
- * Renders a streaming neuron raster 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 neuron raster 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 -- see {@link ScatterPlot} for how the
+ * application-owned data source and this plot's mount-scoped view driver divide the work.
+ *
+ * Internally, this no longer creates/updates SVG `<line>` elements. Instead, it registers a single
+ * draw function with the chart's {@link CanvasContext} that redraws every series' spikes from
+ * scratch each time the canvas repaints. Mouse hover (for the tooltip) is handled by hit-testing
+ * the mouse position against the last-drawn spike geometry -- as *disjoint* segments, since unlike
+ * a scatter series, consecutive spikes are not connected by a line (see `hitTesting.ts`). When
+ * the data source is paused, hovering over a spike shows the tooltip (when there's one).
+ *
  * @param props The properties associated with the raster plot
+ * @return `null` (the plot draws onto the chart's canvas)
  * @example
  <RasterPlot
      axisAssignments={new Map([
@@ -85,7 +102,6 @@ export interface Props {
         ['neuron2', assignAxes("x-axis-2", "y-axis-2")],
      ])}
      spikeMargin={1}
-     dropDataAfter={5000}
      panEnabled={true}
      zoomEnabled={true}
      zoomKeyModifiersRequired={true}
@@ -94,151 +110,75 @@ export interface Props {
 export function RasterPlot(props: Props): null {
     const {
         chartId,
-        container,
-        mainG,
+        canvasContext,
         axes,
-        color,
         seriesStyles,
         seriesFilter,
         mouse,
-        hoveredSeriesRef,
-    } = useChart<Datum, SeriesLineStyle, NoTooltipMetadata, ContinuousAxisRange, ContinuousNumericAxis>()
+    } = useChart<Datum, SeriesLineStyle, RasterTooltipMetadata, ContinuousAxisRange, ContinuousNumericAxis>()
+    const {hoveredSeriesName} = useHoveredSeries()
 
     const {
         xAxesState,
         yAxesState,
         setAxisAssignments,
-        setAxisIntervalFor,
-        updateAxisRanges = noop,
-        onUpdateAxesInterval,
     } = axes
 
     const {mouseOverHandlerFor, mouseLeaveHandlerFor} = mouse
 
     const {plotDimensions, margin} = usePlotDimensions()
 
-    const {
-        seriesObservable,
-        windowingTime = 100,
-        shouldSubscribe,
-
-        onSubscribe = noop,
-        onUpdateData,
-    } = useDataObservable()
+    // the application-owned source of the data, and whether it's running (streaming)
+    const dataSource = useDataSource<TimeSeriesChartData, Datum, TimeSeries>()
+    const running = useDataSourceRunning(dataSource)
 
-    const {initialData} = useInitialData<TimeSeriesChartData, Datum>()
+    const {initialData} = useInitialData<Datum>()
 
     const {
         axisAssignments = new Map<string, AxesAssignment>(),
-        dropDataAfter = Infinity,
         panEnabled = false,
         zoomEnabled = false,
         zoomKeyModifiersRequired = true,
         withCadenceOf,
         spikeMargin = 2,
+        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 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
+    // 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).
-    const dataRef = useRef<Array<TimeSeries>>(initialData.slice() as Array<TimeSeries>)
-    const seriesRef = useRef<Map<string, TimeSeries>>(new Map(initialData.map(series => [series.name, series as TimeSeries])))
-    // map(axis_id -> current_time) -- maps the axis ID to the current time for that axis
-    const currentTimeRef = useRef<Map<string, number>>(new Map())
-
-    const subscriptionRef = useRef<Subscription>(undefined)
-
-    const isSubscriptionClosed = () => subscriptionRef.current === undefined || subscriptionRef.current.closed
-
-    const allowTooltipRef = useRef<boolean>(isSubscriptionClosed())
-
-    useEffect(
-        () => {
-            currentTimeRef.current = new Map(Array.from<string>(xAxesState.axes.keys()).map(id => [id, 0]))
-        },
-        [xAxesState]
-    )
-
-    // set the axis assignments needed if a tooltip is being used
-    useEffect(
-        () => {
-            setAxisAssignments(axisAssignments)
-        },
-        [axisAssignments, setAxisAssignments]
+    // 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<Array<TimeSeries>>(initialData.slice())
+    const seriesRef = useRef<Map<string, TimeSeries>>(
+        new Map(initialData.map(
+            series => [series.name, series]
+            )
+        )
     )
 
-    // calculates the distinct series IDs that cover all the series in the plot
-    const axesForSeries = useMemo(
-        () => axesForSeriesGen<Datum, ContinuousNumericAxis>(initialData, axisAssignments, xAxesState),
-        [initialData, axisAssignments, xAxesState]
-    )
+    // the last-drawn geometry for each series' spikes, in canvas coordinates, used for
+    // hit-testing mouse hover on `mousemove` (see the effect below that wires up the listener)
+    const geometryRef = useRef<Map<string, SeriesGeometry>>(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<string | undefined>(undefined)
 
-    // updates the timing using the onUpdateTime and updatePlot references. This and the references
-    // defined above allow the axes' times to be update properly by avoid stale reference to these
-    // functions.
-    const updateTimingAndPlot = useCallback((ranges: Map<string, ContinuousAxisRange>): void => {
-            if (mainG !== null) {
-                onUpdateTimeRef.current(ranges)
-                updatePlotRef.current(ranges, mainG)
-                if (onUpdateAxesInterval) {
-                    setTimeout(() => {
-                        const times = new Map<string, AxisInterval>()
-                        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() as Array<TimeSeries>
-            seriesRef.current = new Map(initialData.map(series => [series.name, series as TimeSeries]))
-            currentTimeRef.current = new Map(Array.from<string>(xAxesState.axes.keys()).map(id => [id, 0]))
-            updateTimingAndPlot(new Map(Array.from(continuousAxisRanges(xAxesState.axes as Map<string, ContinuousNumericAxis>).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 as Array<TimeSeries>)
-                            .filter(srs => axisAssignments.get(srs.name)?.xAxis === id)
-                            .reduce(
-                                (tMin: number, series: TimeSeries) => 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]
-    )
+    // tooltips are only shown while the data source is paused (and not while panning)
+    const allowTooltipRef = useRef<boolean>(!(dataSource?.running ?? false))
 
     /**
      * Calculates the upper and lower y-coordinate for the spike line
@@ -261,88 +201,27 @@ export function RasterPlot(props: Props): null {
     }
 
     /**
-     * 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 series An array of series names
-     * @param ranges A map holding the axis ID and its associated time range
-     */
-    const onPan = useCallback(
-        (x: number,
-         plotDimensions: Dimensions,
-         ranges: Map<string, ContinuousAxisRange>
-        ) => 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: ZoomTransform,
-            x: number,
-            plotDimensions: Dimensions,
-            ranges: Map<string, ContinuousAxisRange>,
-        ) => continuousAxisZoomHandler(axesForSeries, margin, setAxisIntervalFor, xAxesState)(transform, x, plotDimensions, ranges),
-        [axesForSeries, margin, setAxisIntervalFor, xAxesState]
-    )
-
-    /**
-     * @param timeRanges
-     * @param mainGElem
+     * (Re-)registers this plot's draw function with the canvas context and requests a redraw.
+     * Replaces the old version, which directly mutated SVG `<line>` elements bound via d3's
+     * enter/update/exit join. Canvas has no persistent elements to join against, so the draw
+     * function just redraws every spike from current data/scale state each time it's invoked.
+     *
+     * 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 unrelated to drawing the new
+     * data.
+     * @param cc The canvas context to register the draw function with
      */
     const updatePlot = useCallback(
-        (timeRanges: Map<string, ContinuousAxisRange>, mainGElem: GSelection) => {
-            if (container) {
-                // select the svg element bind the data to them
-                const svg = d3.select<SVGSVGElement, any>(container)
-
-                // set up panning
-                if (panEnabled) {
-                    const drag = d3.drag<SVGSVGElement, Datum>()
-                        .on("start", () => {
-                            d3.select(container).style("cursor", "move")
-                            allowTooltipRef.current = false
-                        })
-                        .on("drag", (event: any) => {
-                            onPan(event.dx, plotDimensions, timeRanges)
-                            // need to update the plot with the new time-ranges
-                            updatePlotRef.current(timeRanges, mainGElem)
-                        })
-                        .on("end", () => {
-                            d3.select(container).style("cursor", "auto")
-                            allowTooltipRef.current = isSubscriptionClosed()
-                        })
-
-                    svg.call(drag)
-                }
+        (cc: CanvasContext) => {
+            const draw = (context: CanvasContext) => {
+                const {context2D} = context
 
-                // set up for zooming
-                if (zoomEnabled) {
-                    const zoom = d3.zoom<SVGSVGElement, Datum>()
-                        .filter((event: any) => !zoomKeyModifiersRequired || event.shiftKey || event.ctrlKey)
-                        .scaleExtent([0, 10])
-                        .translateExtent([[margin.left, margin.top], [plotDimensions.width, plotDimensions.height]])
-                        .on("zoom", (event: any) => {
-                                onZoom(
-                                    event.transform,
-                                    event.sourceEvent.offsetX - margin.left,
-                                    plotDimensions,
-                                    timeRanges,
-                                )
-                                updatePlotRef.current(timeRanges, mainGElem)
-                            }
-                        )
+                context2D.save()
+                clipToArea(context, plotDimensions, {x: margin.left, y: margin.top})
+                context2D.translate(margin.left, margin.top)
 
-                    svg.call(zoom)
-                }
+                const newGeometry = new Map<string, SeriesGeometry>()
 
                 // enter, update, delete the raster data
                 dataRef.current.forEach(series => {
@@ -352,10 +231,11 @@ export function RasterPlot(props: Props): null {
                         axisId => xAxesState.axisFor(axisId).getOrUndefined(),
                         axisId => yAxesState.axisFor(axisId).getOrUndefined()
                     )
+                    if (xAxis === undefined || yAxis === undefined) return
 
                     // grab the series styles, or the defaults if none exist
                     const {
-                        color,
+                        color: seriesColor,
                         lineWidth,
                         highlightColor,
                         highlightWidth,
@@ -365,234 +245,178 @@ export function RasterPlot(props: Props): null {
                         highlightColor: defaultLineStyle().color
                     }
 
-                    const isHovered = hoveredSeriesRef.current === series.name
-                    const strokeColor = isHovered ? highlightColor : color
+                    const isHovered = hoveredSeriesName === series.name
+                    const strokeColor = isHovered ? highlightColor : seriesColor
                     const strokeWidth = isHovered ? (highlightWidth || lineWidth) : lineWidth
 
                     // only show the data for which the regex filter matches
-                    const plotData = (series.name.match(seriesFilter)) ? series.data : []
-
-                    const seriesContainer = svg
-                        .select<SVGGElement>(`#${series.name}-${chartId}-raster`)
-                        .selectAll<SVGLineElement, PixelDatum>('line')
-                        .data(plotData as PixelDatum[])
+                    const plotData: FastShiftArray<Datum> = (series.name.match(seriesFilter)) ? series.data : FastShiftArray.empty<Datum>()
 
-                    //
-                    // enter new elements
+                    // grab the functions that are used to determine the lower and upper coordinates of
+                    // the raster line (y1, y2) and then calculate the values (y1, y2) using those functions
                     const {yUpper, yLower} = yCoordsFn(yAxis.scale.bandwidth(), lineWidth, spikeLineMargin)
-
-                    // grab the value (index) associated with the series name (this is a category axis)
                     const y = yAxis.scale(series.name) || 0
-                    // enter
-                    seriesContainer
-                        .enter()
-                        .append<SVGLineElement>('line')
-                        .attr('x1', datum => datum.x)
-                        .attr('x2', datum => datum.x)
-                        .attr('y1', _ => yUpper(y))
-                        .attr('y2', _ => yLower(y))
-                        .attr('stroke', strokeColor)
-                        .attr('stroke-width', strokeWidth)
-                        .attr('data-series-name', series.name)
-                        .attr('class', 'spikes-lines')
-                        .on(
-                            "mouseover",
-                            (event, datumArray) =>
-                                handleMouseOverSeries(
-                                    container,
-                                    xAxis,
-                                    series.name,
-                                    datumArray,
-                                    event,
-                                    margin,
-                                    seriesStyles,
-                                    allowTooltipRef.current,
-                                    mouseOverHandlerFor(`tooltip-${chartId}`)
-                                )
-                        )
-                        .on(
-                            "mouseleave",
-                            event => handleMouseLeaveSeries(
-                                series.name,
-                                event.currentTarget,
-                                seriesStyles,
-                                mouseLeaveHandlerFor(`tooltip-${chartId}`)
-                            )
-                        )
-                        .each(datum => datum.x = xAxis.scale(datum.time))
-
-                    // update
-                    seriesContainer
-                        .each(datum => datum.x = xAxis.scale(datum.time))
-                        .attr('x1', datum => datum.x)
-                        .attr('x2', datum => datum.x)
-                        .attr('y1', _ => yUpper(y))
-                        .attr('y2', _ => yLower(y))
-                        .attr('stroke', strokeColor)
-                        .attr('stroke-width', strokeWidth)
-
-                    // exit old elements
-                    seriesContainer.exit().remove()
+                    const y1 = yUpper(y)
+                    const y2 = yLower(y)
+
+                    context2D.strokeStyle = strokeColor
+                    context2D.lineWidth = strokeWidth
+
+                    const segments: Array<[[number, number], [number, number]]> = []
+                    for (let i = 0; i < plotData.length; i++) {
+                        const x = xAxis.scale(plotData[i].x)
+                        context2D.beginPath()
+                        context2D.moveTo(x, y1)
+                        context2D.lineTo(x, y2)
+                        context2D.stroke()
+                        segments.push([[x + margin.left, y1 + margin.top], [x + margin.left, y2 + margin.top]])
+                    }
+
+                    newGeometry.set(series.name, {
+                        points: [],
+                        segments,
+                        hitRadius: Math.max(4, strokeWidth)
+                    })
                 })
+
+                geometryRef.current = newGeometry
+
+                context2D.restore()
             }
+
+            cc.register(`raster-plot-${chartId}`, draw, 10)
+            cc.requestRedraw()
         },
         [
-            axisAssignments, chartId, container, margin,
-            mouseLeaveHandlerFor, mouseOverHandlerFor, onPan, onZoom,
-            panEnabled,
-            plotDimensions,
-            seriesFilter, seriesStyles,
-            xAxesState, yAxesState,
-            zoomEnabled, zoomKeyModifiersRequired,
-            spikeMargin,
-            hoveredSeriesRef
+            axisAssignments, chartId, plotDimensions, seriesFilter, seriesStyles, xAxesState, yAxesState,
+            spikeMargin, hoveredSeriesName, 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<(r: Map<string, ContinuousAxisRange>, g: GSelection) => void>(noop)
-    useEffect(
-        () => {
-            if (mainG !== null && container !== null) {
-                // when the update plot function doesn't yet exist, then create the container holding the plot
-                const clipPathId = setClipPathG(chartId, mainG, plotDimensions)
-                if (updatePlotRef.current === noop) {
-                    mainG
-                        .selectAll<SVGGElement, TimeSeries>('g')
-                        .attr("clip-path", `url(#${clipPathId})`)
-                        .data<TimeSeries>(dataRef.current)
-                        .enter()
-                        .append('g')
-                        .attr('class', 'spikes-series')
-                        .attr('id', series => `${series.name}-${chartId}-raster`)
-                        .attr('transform', `translate(${margin.left}, ${margin.top})`)
-
-                } else {
-                    mainG
-                        .selectAll<SVGGElement, TimeSeries>('g')
-                        .attr("clip-path", `url(#${clipPathId})`)
-                }
-                updatePlotRef.current = updatePlot
-            }
+    // the time axes: their ranges, the view driver, panning and zooming, highlighting, and
+    // reporting the axes' intervals -- see `useStreamingTimeAxes`
+    useStreamingTimeAxes<TimeSeriesChartData, Datum>({
+        canvasContext,
+        dataSource,
+        running,
+        initialData,
+        timeOf: datum => datum.x,
+        axisTimesFor: timeSeriesAxisTimes(axisAssignments, xAxesState),
+        axisAssignments,
+        updatePlot,
+        onDataReset: () => {
+            dataRef.current = initialData.slice() as Array<TimeSeries>
+            seriesRef.current = new Map(initialData.map(series => [series.name, series as TimeSeries]))
         },
-        [chartId, container, mainG, margin, plotDimensions, updatePlot]
-    )
+        allowTooltipRef,
+        panEnabled,
+        zoomEnabled,
+        zoomKeyModifiersRequired,
+        onZoomReset,
+        withCadenceOf,
+        highlightAxesOnMouseOver,
+    })
 
-    // grab a reference to the function used to update the time ranges and update that reference
-    // if the function changes (solve for stale closures)
-    const onUpdateTimeRef = useRef(updateAxisRanges)
+    // the series' axis assignments, for the chart (e.g. the tooltip looks up a spike's row's axis)
     useEffect(
         () => {
-            onUpdateTimeRef.current = updateAxisRanges
+            setAxisAssignments(axisAssignments)
         },
-        [updateAxisRanges]
+        [axisAssignments, setAxisAssignments]
     )
 
-    // memoized function for subscribing to the chart-data observable
-    const subscribe = useCallback(
+    // 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 spike geometry (see `geometryRef`, populated by the draw function above).
+    useEffect(
         () => {
-            if (seriesObservable === undefined || mainG === null) return undefined
-            if (withCadenceOf !== undefined) {
-                return subscriptionTimeSeriesWithCadenceFor(
-                    seriesObservable as Observable<TimeSeriesChartData>,
-                    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
-                )
+            if (!canvasContext) return
+
+            const canvas = canvasContext.canvas
+
+            const handleMove = (event: MouseEvent) => {
+                if (!allowTooltipRef.current) return
+
+                const [x, y] = canvasLocalPoint(event, canvas)
+                const hit = seriesAt(x, y, geometryRef.current)
+
+                if (hit?.name === lastHoveredRef.current && hit !== undefined) {
+                    // still hovering the same series -- no enter/leave to fire, but the specific
+                    // spike may have changed, so fall through and re-report below
+                } else if (lastHoveredRef.current !== undefined) {
+                    handleMouseLeaveSeries(lastHoveredRef.current, mouseLeaveHandlerFor(`tooltip-${chartId}`))
+                }
+
+                if (hit !== undefined) {
+                    const series = seriesRef.current.get(hit.name)
+                    const selectedDatum = series?.data[hit.index]
+                    const xAxis = axesFor(
+                        hit.name,
+                        axisAssignments,
+                        axisId => xAxesState.axisFor(axisId).getOrUndefined(),
+                        axisId => yAxesState.axisFor(axisId).getOrUndefined()
+                    )[0]
+                    if (series !== undefined && selectedDatum !== undefined && xAxis !== undefined) {
+                        handleMouseOverSeries(
+                            xAxis,
+                            hit.name,
+                            selectedDatum,
+                            series.data,
+                            [x, y],
+                            margin,
+                            mouseOverHandlerFor(`tooltip-${chartId}`)
+                        )
+                    }
+                }
+
+                lastHoveredRef.current = hit?.name
+            }
+
+            const handleLeaveCanvas = () => {
+                if (lastHoveredRef.current !== undefined) {
+                    handleMouseLeaveSeries(lastHoveredRef.current, mouseLeaveHandlerFor(`tooltip-${chartId}`))
+                    lastHoveredRef.current = undefined
+                }
+            }
+
+            canvas.addEventListener('mousemove', handleMove)
+            canvas.addEventListener('mouseleave', handleLeaveCanvas)
+            return () => {
+                canvas.removeEventListener('mousemove', handleMove)
+                canvas.removeEventListener('mouseleave', handleLeaveCanvas)
             }
-            return subscriptionTimeSeriesFor(
-                seriesObservable as Observable<TimeSeriesChartData>,
-                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)
-            )
         },
-        [
-            axisAssignments, dropDataAfter, mainG,
-            onSubscribe, onUpdateData,
-            seriesObservable, updateTimingAndPlot, windowingTime, xAxesState,
-            withCadenceOf
-        ]
+        [canvasContext, chartId, margin, axisAssignments, xAxesState, yAxesState, mouseOverHandlerFor, mouseLeaveHandlerFor]
     )
 
-    const timeRangesRef = useRef<Map<string, ContinuousAxisRange>>(new Map())
+    // this plot needs a data source (see the `Chart`'s `dataSource` prop)
     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 as Map<string, ContinuousNumericAxis>)
-                } 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))
-                            }
-                        })
-                }
-                updatePlot(timeRangesRef.current, mainG)
+            if (dataSource === undefined) {
+                console.error("RasterPlot requires a data source; set the enclosing Chart's `dataSource` prop")
             }
         },
-        [chartId, color, container, mainG, plotDimensions, updatePlot, xAxesState]
+        [dataSource]
     )
 
-    // 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.
+    // unregister this plot's draw function on unmount
     useEffect(
         () => {
-            if (shouldSubscribe && subscriptionRef.current === undefined) {
-                subscriptionRef.current = subscribe()
-                allowTooltipRef.current = false
-            } else if (!shouldSubscribe && subscriptionRef.current !== undefined) {
-                subscriptionRef.current?.unsubscribe()
-                subscriptionRef.current = undefined
-                allowTooltipRef.current = true
+            return () => {
+                if (canvasContext) {
+                    canvasContext.unregister(`raster-plot-${chartId}`)
+                }
             }
         },
-        [shouldSubscribe, subscribe]
+        [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.
+ * 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
@@ -600,7 +424,8 @@ export function RasterPlot(props: Props): null {
  * @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 A 2d tuple holding the linear x-axis as its first element and the category y-axis as
- * the second element.
+ * the second element (either is actually `undefined` when it isn't found, despite the type).
+ * @throws Error when the x-axis isn't a continuous numeric axis, or the y-axis isn't a category axis
  */
 function axesFor(
     seriesName: string,
@@ -610,79 +435,62 @@ function axesFor(
 ): [xAxis: ContinuousNumericAxis, yAxis: OrdinalStringAxis] {
     const axes = axisAssignments.get(seriesName)
     const xAxis = xAxisFor(axes?.xAxis || "")
+    checkAxisType("RasterPlot", "x", xAxis, AxisType.ContinuousNumeric)
     const xAxisLinear = xAxis as ContinuousNumericAxis
-    if (xAxis && !xAxisLinear) {
-        throw Error("Raster plot requires that x-axis be of type LinearAxis")
-    }
     const yAxis = yAxisFor(axes?.yAxis || "")
+    checkAxisType("RasterPlot", "y", yAxis, AxisType.OrdinalString)
     const yAxisCategory = yAxis as OrdinalStringAxis
-    if (yAxis && !yAxisCategory) {
-        throw Error("Raster plot requires that y-axis be of type CategoryAxis")
-    }
     return [xAxisLinear, yAxisCategory]
 }
 
 /**
- * Renders a tooltip showing the neuron, spike time, and the spike strength when the mouse hovers over a spike.
- * @param container The chart container
+ * Reports a tooltip showing the neuron, spike time, and the spike's value when the mouse hovers over a spike.
+ * Replaces the old version, which mutated the hovered SVG `<line>`'s stroke directly; highlighting is now
+ * handled by the draw function reading `hoveredSeriesName` from chart state rather than by touching an
+ * element here.
  * @param xAxis The x-axis
  * @param seriesName The name of the series (i.e. the neuron ID)
  * @param selectedDatum The selected datum
- * @param event The mouse-over series event
+ * @param spikes All the series' spikes that the chart holds (for the tooltip's statistics)
+ * @param mouseCoords The `[x, y]` position of the mouse, in canvas coordinates
  * @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: SVGSVGElement,
     xAxis: ContinuousNumericAxis,
     seriesName: string,
     selectedDatum: Datum,
-    event: React.MouseEvent<SVGPathElement>,
+    spikes: Series<Datum>,
+    mouseCoords: [x: number, y: number],
     margin: Margin,
-    seriesStyles: Map<string, SeriesLineStyle>,
-    allowTooltip: boolean,
-    mouseOverHandlerFor: ((seriesName: string, time: number, tooltipData: TooltipData<Datum, NoTooltipMetadata>, mouseCoords: [x: number, y: number]) => void) | undefined,
+    mouseOverHandlerFor: ((seriesName: string, time: number, tooltipData: TooltipData<Datum, RasterTooltipMetadata>, mouseCoords: [x: number, y: number]) => void) | undefined,
 ): void {
     // grab the time needed for the tooltip ID
-    const [x, y] = d3.pointer(event, container)
+    const [x] = mouseCoords
     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<SVGPathElement, Datum>(event.currentTarget)
-        .attr('stroke', highlightColor)
-        .attr('stroke-width', highlightWidth)
-
-    if (mouseOverHandlerFor && allowTooltip) {
+    if (mouseOverHandlerFor) {
         // the contract for the mouse over handler is for a time-series, but here we only
         // need one point, the selected datum, and so we convert it into an array of point
         // (i.e. a time-series). The category tooltip is (and custom ones, must) be
-        // written to expect only the selected point
-        mouseOverHandlerFor(seriesName, time, {series: [selectedDatum], metadata: {}}, [x, y])
+        // written to expect only the selected point. All the series' spikes (that the chart
+        // holds) come along in the metadata, for the tooltip's statistics
+        mouseOverHandlerFor(seriesName, time, {series: [selectedDatum], metadata: {spikes}}, mouseCoords)
     }
 }
 
 /**
- * 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 spikes in their 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: string,
-    segment: SVGPathElement,
-    seriesStyles: Map<string, SeriesLineStyle>,
     mouseLeaverHandlerFor: ((seriesName: string) => void) | undefined,
 ): void {
-    const {color, lineWidth} = seriesStyles.get(seriesName) || defaultLineStyle()
-    d3.select<SVGPathElement, Datum>(segment)
-        .attr('stroke', color)
-        .attr('stroke-width', lineWidth)
-
     if (mouseLeaverHandlerFor) {
         mouseLeaverHandlerFor(seriesName)
     }