station-detail: prefetch on map hover + spinner overlay on chart

Two-part fix for the slow + jittery station-switch experience on
`/s/<slug>` when the user clicks between stations on the map.

**Prefetch on hover** (`StationMap.tsx`, `query/stations.ts`):
  - New `onMarkerHover?: (id) => void` prop on `StationMap`; fires
    80 ms after the cursor settles on a circle (debounced via
    `setTimeout` + `mouseout` cancel). Quick mouse-passes don't
    trigger requests.
  - `prefetchStationDetail(qc, slug, fromS, toS, binS)` in the query
    module chains the `/info` → `/totals` calls the next page will
    issue. Uses the SAME query keys (`station-info`/`station-avail`)
    as the live hooks, so the eventual `useStationAvailability` mount
    hits the warm cache instead of refetching.
  - `StationDetail.tsx` wires the hook by passing
    `onMarkerHover={(id) => prefetchStationDetail(qc, id, bufFromS,
    bufToS, binS)}` to its `StationMap`.

**Spinner overlay** (`StationDetail.tsx`):
  - Wraps `StationAvailabilityChart` in a relative container. While
    `rangeQuery.isFetching` is true, the chart dims to 40% opacity
    and an absolute-positioned `<CircularProgress />` floats over it.
    Pre-existing initial-load spinner (no data yet) is unchanged.

**Drops cross-station `keepPreviousData`** (`query/stations.ts`):
  - `useStationAvailability`'s `placeholderData` is now selective:
    keeps prev rows only when `gbfsId` is unchanged (same station,
    new range/bin). On cross-station nav, drops to undefined so the
    chart shows the spinner instead of the previous station's data
    with the new station's y-range — the "loaded but wrong" effect
    the user reported.

Verified live via synthetic `mouseover` on a hit-circle: 80 ms later
the `/info` + chained `/totals` requests fire with the hovered
station's id, before any click.

BE perf (uncached `/api/totals?kind=availability` at 2.0–2.8 s) is
a separate investigation — see task #64.

Author: ryan-williams

www/src/components/StationMap.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useMemo, useState } from 'react'
+import { useEffect, useMemo, useRef, useState } from 'react'
 import { Circle, MapContainer, Pane, Polyline, TileLayer, Tooltip, useMap } from 'react-leaflet'
 import 'leaflet/dist/leaflet.css'
 import { useTheme } from '../contexts/ThemeContext'
@@ -72,6 +72,7 @@ function StationMarkers({
   setSelectedId,
   pinnedId,
   onPin,
+  onMarkerHover,
   pairCounts,
   colors,
   stationColors,
@@ -82,6 +83,7 @@ function StationMarkers({
   setSelectedId?: (id: string | undefined) => void
   pinnedId?: string
   onPin?: (id: string | undefined) => void
+  onMarkerHover?: (id: string) => void
   pairCounts?: StationPairCounts | null
   colors: TileColors
   stationColors?: Record<string, string> | null
@@ -93,6 +95,25 @@ function StationMarkers({
   const selectedStation = selectedId ? stations[selectedId] : undefined
   const mPerPx = useMemo(() => getMetersPerPixel(map), [map, zoom])
 
+  // Hover-prefetch: fire `onMarkerHover(id)` 80 ms after the cursor settles on
+  // a circle, cancelling if the cursor leaves first. Quick mouse-passes don't
+  // trigger requests; deliberate hovers warm the cache for an imminent click.
+  const hoverTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  useEffect(() => () => {
+    if (hoverTimerRef.current) clearTimeout(hoverTimerRef.current)
+  }, [])
+  const scheduleHoverPrefetch = (id: string) => {
+    if (!onMarkerHover) return
+    if (hoverTimerRef.current) clearTimeout(hoverTimerRef.current)
+    hoverTimerRef.current = setTimeout(() => onMarkerHover(id), 80)
+  }
+  const cancelHoverPrefetch = () => {
+    if (hoverTimerRef.current) {
+      clearTimeout(hoverTimerRef.current)
+      hoverTimerRef.current = null
+    }
+  }
+
   // Suppress the permanent selected-station tooltip while the cursor is over a
   // destination line — otherwise both tooltips pile up at the source station,
   // overlapping awkwardly. (Only used in unpinned/hover mode; when pinned we
@@ -212,6 +233,17 @@ function StationMarkers({
           // Hit-test circle: invisible (fillOpacity 0, weight 0), but with
           // a clickable radius of at least HIT_RADIUS_PX. Carries the
           // eventHandlers + tooltip.
+          const eventHandlers: Record<string, () => void> = {}
+          if (onPin || setSelectedId) {
+            eventHandlers.click = () => (onPin ?? setSelectedId)?.(id)
+          }
+          if (onMarkerHover || (hoverToSelect && setSelectedId)) {
+            eventHandlers.mouseover = () => {
+              if (hoverToSelect && setSelectedId && id !== selectedId) setSelectedId(id)
+              scheduleHoverPrefetch(id)
+            }
+            eventHandlers.mouseout = cancelHoverPrefetch
+          }
           const hit = (
             <Circle
               key={`${id}-hit`}
@@ -220,10 +252,7 @@ function StationMarkers({
               fillOpacity={0}
               weight={0}
               bubblingMouseEvents={false}
-              eventHandlers={(onPin || setSelectedId) ? {
-                click: () => (onPin ?? setSelectedId)?.(id),
-                ...(hoverToSelect && setSelectedId ? { mouseover: () => { if (id !== selectedId) setSelectedId(id) } } : {}),
-              } : undefined}
+              eventHandlers={Object.keys(eventHandlers).length ? eventHandlers : undefined}
             >
               {/* Suppress base-circle tooltips for other stations while a
                   station is pinned — the pinned TT stays put, nothing else
@@ -240,7 +269,7 @@ function StationMarkers({
         })}
       </Pane>
     )
-  }, [stations, selectedId, setSelectedId, onPin, colors, stationColors, hoverToSelect, isPinned, hitRadius])
+  }, [stations, selectedId, setSelectedId, onPin, onMarkerHover, colors, stationColors, hoverToSelect, isPinned, hitRadius])
 
   // Permanent tooltip on the destination station while hovering an edge that
   // ends there. Anchored at the dst's lat/lng with a tiny invisible Circle
@@ -320,6 +349,10 @@ export interface StationMapProps {
    *  expected to toggle / update `pinnedId`. If omitted, clicks
    *  fall back to `setSelectedId`. */
   onPin?: (id: string | undefined) => void
+  /** Fired ~80ms after the cursor settles on a circle. Use to warm
+   *  caches for an imminent click (e.g. prefetch the station-detail
+   *  data the click will navigate to). */
+  onMarkerHover?: (id: string) => void
   pairCounts?: StationPairCounts | null
   stationColors?: Record<string, string> | null
 
@@ -352,6 +385,7 @@ export default function StationMap({
   setSelectedId,
   pinnedId,
   onPin,
+  onMarkerHover,
   pairCounts,
   stationColors,
   center,
@@ -399,6 +433,7 @@ export default function StationMap({
         setSelectedId={setSelectedId}
         pinnedId={pinnedId}
         onPin={onPin}
+        onMarkerHover={onMarkerHover}
         pairCounts={pairCounts}
         colors={colors}
         stationColors={stationColors}

www/src/pages/StationDetail.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useMemo, useRef, useState } from 'react'
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { useNavigate, useParams } from 'react-router-dom'
 import { Box, CircularProgress, Typography } from '@mui/material'
 import css from '../index.module.css'
@@ -16,8 +16,9 @@ import { Checkbox } from '../components/Checkbox'
 import { Checklist } from '../components/Checklist'
 import { Radios } from '../components/Radios'
 import { useStationTrips } from '../hooks/useStationTrips'
+import { useQueryClient } from '@tanstack/react-query'
 import {
-  pickAvailBinAuto,
+  pickAvailBinAuto, prefetchStationDetail,
   useStationInfo, useStationAvailability,
 } from '../query/stations'
 import { useRollupQuery, type Side } from '../query/rollups'
@@ -197,6 +198,18 @@ export default function StationDetail() {
   const data = rangeQuery.data ?? null
   const error = rangeQuery.error ? String(rangeQuery.error) : null
 
+  // Prefetch handler for hovered map circles. Reuses the current page's
+  // (bufFromS, bufToS, binS) so the prefetched cache entries match the next
+  // page's query keys exactly — the click navigates and `useStationAvailability`
+  // there hits the warmed cache for an instant render.
+  const queryClient = useQueryClient()
+  const onMarkerHover = useCallback((id: string) => {
+    const binS = binMs > 0
+      ? Math.floor(binMs / 1000)
+      : pickAvailBinAuto(bufToS - bufFromS, availViewportPx)
+    void prefetchStationDetail(queryClient, id, bufFromS, bufToS, binS)
+  }, [queryClient, bufFromS, bufToS, binMs, availViewportPx])
+
   // Load monthly trip history from the public DVX cache
   const { rows: tripsRows } = useStationTrips(info?.short_name)
 
@@ -478,23 +491,36 @@ export default function StationDetail() {
         )}
 
         {data && data.rows.length > 0 && (
-          <StationAvailabilityChart
-            rows={data.rows}
-            capacity={info?.capacity ?? null}
-            visibleFromS={fromS}
-            visibleToS={toS}
-            binS={data.binS}
-            onPan={(minS, maxS) => {
-              const duration = roundDuration((maxS - minS) * 1000)
-              const nowS = Date.now() / 1000
-              // Snap to Latest when drag ends within 10 min of now (matches awair UX).
-              const snapToLatest = maxS >= nowS - 10 * 60
-              setRange({
-                timestamp: snapToLatest ? null : new Date(maxS * 1000),
-                duration,
-              })
-            }}
-          />
+          <Box sx={{ position: 'relative' }}>
+            <Box sx={{ opacity: rangeQuery.isFetching ? 0.4 : 1, transition: 'opacity 120ms' }}>
+              <StationAvailabilityChart
+                rows={data.rows}
+                capacity={info?.capacity ?? null}
+                visibleFromS={fromS}
+                visibleToS={toS}
+                binS={data.binS}
+                onPan={(minS, maxS) => {
+                  const duration = roundDuration((maxS - minS) * 1000)
+                  const nowS = Date.now() / 1000
+                  // Snap to Latest when drag ends within 10 min of now (matches awair UX).
+                  const snapToLatest = maxS >= nowS - 10 * 60
+                  setRange({
+                    timestamp: snapToLatest ? null : new Date(maxS * 1000),
+                    duration,
+                  })
+                }}
+              />
+            </Box>
+            {rangeQuery.isFetching && (
+              <Box sx={{
+                position: 'absolute', inset: 0,
+                display: 'flex', alignItems: 'center', justifyContent: 'center',
+                pointerEvents: 'none',
+              }}>
+                <CircularProgress />
+              </Box>
+            )}
+          </Box>
         )}
 
         {data && data.rows.length === 0 && (
@@ -522,6 +548,7 @@ export default function StationDetail() {
               stations={mapStations}
               selectedId={mapShortName}
               setSelectedId={(sid) => { if (sid && sid !== mapShortName) navigate(`/s/${sid}`) }}
+              onMarkerHover={onMarkerHover}
               pairCounts={pairCounts}
               center={mapCenter}
               zoom={15}

www/src/query/stations.ts

@@ -6,7 +6,7 @@
  *   binned per `binOverrideS` or `pickAvailBinAuto`. Single shape regardless
  *   of window size (the worker handles tier selection: mo1/d1/h1/raw).
  */
-import { keepPreviousData, useQuery } from '@tanstack/react-query'
+import { keepPreviousData, type QueryClient, useQuery } from '@tanstack/react-query'
 
 // Override at build/dev time with `VITE_API_BASE=http://localhost:51896 pnpm dev`.
 const API_BASE = import.meta.env.VITE_API_BASE ?? 'https://ctbk-gbfs-api.ryan-0dc.workers.dev'
@@ -54,15 +54,18 @@ export interface StationRangeResponse {
   last_polled_at: number | null
 }
 
+const stationInfoKey = (id: string) => ['station-info', id] as const
+const stationInfoFn = async (id: string): Promise<StationInfo | null> => {
+  const res = await fetch(`${API_BASE}/api/stations/${encodeURIComponent(id)}/info`)
+  if (!res.ok) return null
+  return res.json()
+}
+
 export function useStationInfo(id: string | undefined) {
   return useQuery<StationInfo | null>({
-    queryKey: ['station-info', id],
+    queryKey: stationInfoKey(id ?? ''),
     enabled: !!id,
-    queryFn: async () => {
-      const res = await fetch(`${API_BASE}/api/stations/${encodeURIComponent(id!)}/info`)
-      if (!res.ok) return null
-      return res.json()
-    },
+    queryFn: () => stationInfoFn(id!),
   })
 }
 
@@ -178,6 +181,35 @@ function totalsRowsToAvailabilityRows(
  *  newly-arrived polls should appear without a manual reload). Worker
  *  stitches today's WAL into in-progress bins, so a refetch returns rows
  *  through `now`. */
+const stationAvailKey = (gbfsId: string, fromS: number, toS: number, binS: number) =>
+  ['station-avail', gbfsId, fromS, toS, `bin${binS}`] as const
+
+const stationAvailFn = async (
+  gbfsId: string, fromS: number, toS: number, binS: number, capacityHint: number | null,
+): Promise<StationRangeResponse & { binS: number }> => {
+  const url = new URL(`${API_BASE}/api/totals`)
+  url.searchParams.set('kind', 'availability')
+  url.searchParams.set('metric', 'all')
+  url.searchParams.set('scope', 'stations')
+  url.searchParams.set('from', String(fromS))
+  url.searchParams.set('to', String(toS))
+  url.searchParams.set('filter.station_id', gbfsId)
+  url.searchParams.set('agg', 'mean')
+  url.searchParams.set('bin', String(binS))
+  const res = await fetch(url.toString())
+  if (!res.ok) throw new Error(`HTTP ${res.status}`)
+  const data = await res.json() as { rows: AvailabilityOverviewRow[] }
+  return {
+    station_id: gbfsId,
+    from: fromS,
+    to: toS,
+    capacity: capacityHint,
+    last_polled_at: null,
+    rows: totalsRowsToAvailabilityRows(data.rows),
+    binS,
+  }
+}
+
 export function useStationAvailability(
   gbfsId: string | null | undefined,  // canonical UUID — required for /totals
   fromS: number,
@@ -191,36 +223,45 @@ export function useStationAvailability(
 ) {
   const binS = binOverrideS ?? pickAvailBinAuto(toS - fromS, viewportPx)
   return useQuery<StationRangeResponse & { binS: number }>({
-    queryKey: ['station-avail', gbfsId, fromS, toS, `bin${binS}`],
+    queryKey: stationAvailKey(gbfsId ?? '', fromS, toS, binS),
     enabled: !!gbfsId,
-    queryFn: async () => {
-      const url = new URL(`${API_BASE}/api/totals`)
-      url.searchParams.set('kind', 'availability')
-      url.searchParams.set('metric', 'all')
-      url.searchParams.set('scope', 'stations')
-      url.searchParams.set('from', String(fromS))
-      url.searchParams.set('to', String(toS))
-      url.searchParams.set('filter.station_id', gbfsId!)
-      url.searchParams.set('agg', 'mean')
-      url.searchParams.set('bin', String(binS))
-      const res = await fetch(url.toString())
-      if (!res.ok) throw new Error(`HTTP ${res.status}`)
-      const data = await res.json() as { rows: AvailabilityOverviewRow[] }
-      return {
-        station_id: gbfsId!,
-        from: fromS,
-        to: toS,
-        capacity: capacityHint,
-        last_polled_at: null,
-        rows: totalsRowsToAvailabilityRows(data.rows),
-        binS,
-      }
+    queryFn: () => stationAvailFn(gbfsId!, fromS, toS, binS, capacityHint),
+    // Keep stale data ONLY when the station_id hasn't changed (i.e. the user
+    // toggled range/bin on the same station). On cross-station nav, drop to
+    // `undefined` so the chart shows a spinner instead of the previous
+    // station's data — which is misleading when the new station has different
+    // capacity / activity profile.
+    placeholderData: (prev, prevQuery) => {
+      if (!prev || !prevQuery) return undefined
+      const prevGbfsId = (prevQuery.queryKey as readonly unknown[])[1]
+      return prevGbfsId === gbfsId ? prev : undefined
     },
-    placeholderData: keepPreviousData,
     refetchInterval: liveRefresh ? 60_000 : false,
   })
 }
 
+/** Warm the cache for a station-detail navigation. Called from map hover
+ *  handlers. Idempotent — repeat calls within the cache window are no-ops.
+ *  Chains `info` → `avail` so the avail-query keys match the eventual page
+ *  request (`gbfs_station_id` is only known after `/info`). */
+export async function prefetchStationDetail(
+  qc: QueryClient,
+  slugOrShortName: string,
+  fromS: number,
+  toS: number,
+  binS: number,
+): Promise<void> {
+  const info = await qc.fetchQuery({
+    queryKey: stationInfoKey(slugOrShortName),
+    queryFn: () => stationInfoFn(slugOrShortName),
+  })
+  if (!info?.gbfs_station_id) return
+  await qc.prefetchQuery({
+    queryKey: stationAvailKey(info.gbfs_station_id, fromS, toS, binS),
+    queryFn: () => stationAvailFn(info.gbfs_station_id!, fromS, toS, binS, info.capacity ?? null),
+  })
+}
+
 /** Fetch binned availability aggregation for one station. `gbfsId` is the
  *  GBFS UUID (not slug or short_name). Returns `mean` per `binS`-sized bucket
  *  by default; pass `agg='p50'` etc. for percentile reducers. */