GeoSankey: persistent z-bump on hover/pin + flow-map screenshots

- Track a per-component \`bumpOrder\` of flow keys: every hover or pin
  appends (or moves-to-end) the active key. Render order sorts bumped
  flows last (most-recent on top), then falls back to the existing
  widest-first sort. Lincoln Bus no longer hides under Amtrak as soon
  as it's been engaged.
- README: add Flow Map section + table row in Visualizations.
- \`scrns.config.ts\`: add \`map-nj-ny\` / \`map-ny-nj\` shots
  (selector \`.geo-sankey\`, scrollTo same, \`headless: false\`
  because maplibre-gl needs WebGL).
- Generated initial \`map-nj-ny.png\` / \`map-ny-nj.png\`.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: ryan-williams

README.md

@@ -14,6 +14,14 @@ Reports are also mirrored in [Hudson County Complete Streets]' [Google Drive][gd
 
 Each GIF cycles through peak 1hr, peak period (3hr), and 24hr views. Click to open the interactive chart.
 
+## Flow Map
+
+| NJ→NY (entering) | NY→NJ (leaving) |
+|:-:|:-:|
+| [![NJ→NY map][map-nj-ny]][map-nj-ny-live] | [![NY→NJ map][map-ny-nj]][map-ny-nj-live] |
+
+Geographic Sankey of CBD crossings and ferry routes. Ribbon widths are proportional to passenger counts; flows merge/split at the ferry interchanges. Hovering or pinning a flow brings it to the top of the z-stack persistently.
+
 | | NJ→NY | NY→NJ |
 |---|:-:|:-:|
 | Peak 1hr | [![][nj-ny-1h]][nj-ny-1h-live] | [![][ny-nj-1h]][ny-nj-1h-live] |
@@ -39,17 +47,18 @@ See [`specs/extraction.md`] for full schema documentation and extraction notes.
 
 ## Visualizations
 
-The [web app][live] has 5 interactive charts built with [Plotly.js] and [pltly]:
+The [web app][live] has 6 interactive views — the Plotly charts use [Plotly.js] / [pltly]; the flow map uses [MapLibre GL] + [geo-sankey]:
 
 | Chart | Description | Controls |
 |-------|-------------|----------|
 | **Unified Chart** | NJ→NY crossings: bubble scatter, grouped bars, stacked %, recovery index | View, direction, time period, granularity, palette |
+| **Flow Map** | Geographic Sankey ribbons over a basemap of NJ↔Manhattan, width-proportional to passengers per crossing/mode (incl. multi-source ferry network) | Direction, time period, year, inline-legend, geo-scale, width-scale, hover-padding |
 | **Hourly Profile** | Stacked area of CBD entries/exits by hour | Mode vs sector, direction, year |
 | **Mode Share** | Stacked bar of daily persons by mode across years | Absolute vs %, direction |
 | **Sector Vehicles** | Motor vehicles by sector (stacked or grouped bars) | View, direction, time period |
 | **Peak Accumulation** | 50-year timeline of max persons in Manhattan Hub | (annotated, no toggles) |
 
-All charts support legend hover highlight and click-to-solo via [pltly].
+Plotly charts support legend hover highlight and click-to-solo via [pltly]; the flow map highlights on hover and pins on click, with the most recently engaged flow drawn on top.
 
 ## Extraction
 
@@ -79,6 +88,8 @@ Data sourced from publicly available [NYMTC Hub Bound Travel reports][NYMTC HBT]
 [live]: https://cbd.hudcostreets.org
 [Plotly.js]: https://plotly.com/javascript/
 [pltly]: https://github.com/runsascoded/pltly
+[MapLibre GL]: https://maplibre.org/
+[geo-sankey]: https://github.com/runsascoded/geo-sankey
 [`specs/extraction.md`]: specs/done/extraction.md
 [nj-ny-gif]: www/public/screenshots/nj-ny.gif
 [ny-nj-gif]: www/public/screenshots/ny-nj.gif
@@ -96,3 +107,7 @@ Data sourced from publicly available [NYMTC Hub Bound Travel reports][NYMTC HBT]
 [ny-nj-1h-live]: https://cbd.hudcostreets.org?d=nynj
 [ny-nj-3h-live]: https://cbd.hudcostreets.org?d=nynj&t=3h
 [ny-nj-1d-live]: https://cbd.hudcostreets.org?d=nynj&t=1d
+[map-nj-ny]: www/public/screenshots/map-nj-ny.png
+[map-ny-nj]: www/public/screenshots/map-ny-nj.png
+[map-nj-ny-live]: https://cbd.hudcostreets.org/#map
+[map-ny-nj-live]: https://cbd.hudcostreets.org/?d=nynj#map

www/public/screenshots/map-nj-ny.png

@@ -42,6 +42,28 @@ for (const dir of dirs) {
   }
 }
 
+// Flow map — geographic Sankey of crossings + ferries. The map needs more
+// settling time than Plotly: maplibre-gl loads vector tiles asynchronously,
+// then we render the ribbon polygons on top. The flow map sits below the
+// bubble chart, so scroll to it before capturing. Inline-legend is on by
+// default so the labels appear at the arrow tips. `headless: false` is
+// required because maplibre-gl uses WebGL, which needs a real GPU context —
+// in headless Chromium the canvas renders blank.
+function mapShot(params: string): ScreenshotConfig {
+  return {
+    query: params ? `?${params}` : '',
+    width: W,
+    height: 900,
+    selector: '.geo-sankey',
+    scrollTo: '.geo-sankey',
+    preScreenshotSleep: 3000,
+    headless: false,
+  }
+}
+for (const dir of dirs) {
+  screenshots[`map-${dir.key}`] = mapShot(dir.params)
+}
+
 // og:image — canonical bubble chart, clean mode (no toggles/SpeedDial, larger text)
 // Standard og:image is 1200x630
 screenshots['og'] = {

www/public/screenshots/map-ny-nj.png

@@ -463,6 +463,15 @@ function GeoSankeyInner({ data }: Props) {
   const [hoveredKey, setHoveredKey] = useState<string | null>(null)
   const [pinnedKey, setPinnedKey] = useState<string | null>(null)
   const activeKey = pinnedKey ?? hoveredKey
+  // Persistent z-bump: every hover (or pin) appends the flow's key to
+  // `bumpOrder`; later bumps move it to the end. Render order sorts by
+  // `bumpOrder` index after the default widest-first sort, so the most
+  // recently engaged flow always sits on top.
+  const [bumpOrder, setBumpOrder] = useState<string[]>([])
+  useEffect(() => {
+    if (!activeKey) return
+    setBumpOrder(prev => prev[prev.length - 1] === activeKey ? prev : [...prev.filter(k => k !== activeKey), activeKey])
+  }, [activeKey])
   // Edit mode is implicit: the ferry editor engages whenever the ferry flow
   // is pinned (click ferry ribbon on the map, or the "Ferries" legend row).
   // Click anywhere outside to exit.
@@ -589,10 +598,23 @@ function GeoSankeyInner({ data }: Props) {
       })
     }
 
-    // Sort widest first so narrower flows draw on top
-    features.sort((a, b) => (b.properties?.width ?? 0) - (a.properties?.width ?? 0))
+    // Sort: bumped flows last (in `bumpOrder` recency order) so the most
+    // recently hovered/pinned flow draws on top; remaining flows fall back to
+    // widest-first so smaller flows draw on top of larger neighbors.
+    features.sort((a, b) => {
+      const ka = a.properties?.key as string | undefined
+      const kb = b.properties?.key as string | undefined
+      const ai = ka ? bumpOrder.indexOf(ka) : -1
+      const bi = kb ? bumpOrder.indexOf(kb) : -1
+      if (ai !== bi) {
+        if (ai === -1) return -1
+        if (bi === -1) return 1
+        return ai - bi
+      }
+      return (b.properties?.width ?? 0) - (a.properties?.width ?? 0)
+    })
     return { type: 'FeatureCollection' as const, features }
-  }, [flows, direction, maxPassengers, mapView.zoom, geoScale, widthScale, ferryGS.graph])
+  }, [flows, direction, maxPassengers, mapView.zoom, geoScale, widthScale, ferryGS.graph, bumpOrder])