@cfasim-ui/docs 0.7.3 → 0.7.5

package/charts/ChoroplethMap/ChoroplethMap.vue

@@ -25,7 +25,18 @@ import type { Topology, GeometryCollection } from "topojson-specification";
 import { formatNumber, type NumberFormat } from "@cfasim-ui/shared";
 import ChartMenu from "../ChartMenu/ChartMenu.vue";
 import type { ChartMenuItem } from "../ChartMenu/ChartMenu.vue";
-import { saveSvg, savePng } from "../ChartMenu/download.js";
+import { saveSvg, savePng, saveCanvasPng } from "../ChartMenu/download.js";
+import {
+  buildScene,
+  buildPicking,
+  drawScene,
+  drawHoverHighlight,
+  pickIndexAt,
+  type CanvasScene,
+  type CanvasDrawState,
+  type CanvasOverlayItem,
+  type CanvasHighlightItem,
+} from "./canvasLayer.js";
 import {
   useChartFullscreen,
   isTouchDevice,
@@ -255,6 +266,16 @@ const props = withDefaults(
      * built-in reset button is unaffected.
      */
     focusZoom?: boolean;
+    /**
+     * Rendering backend, fixed at mount. `"svg"` (default) keeps one DOM
+     * path per feature — full assistive-tech fallback (per-feature
+     * `<title>`) and SVG export. `"canvas"` paints every feature into a
+     * single canvas: much faster for dense maps (counties, HSAs) and on
+     * mobile WebKit, with identical interactions. In canvas mode the menu
+     * offers PNG export only, and there is no per-feature fallback for
+     * assistive tech — configure an interactive tooltip.
+     */
+    renderer?: "svg" | "canvas";
     /**
      * Where to teleport the map while expanded (the Expand menu item). A
      * CSS selector or element; defaults to `body`. Moving it to the
@@ -273,6 +294,7 @@ const props = withDefaults(
     menu: true,
     legend: true,
     zoom: false,
+    renderer: "svg",
     zoomMode: "activate",
     touchExpand: true,
     zoomHint: true,
@@ -398,6 +420,32 @@ const overlayPathEls = new Map<
   string,
   { el: SVGPathElement; strokeWidth?: number }
 >();
+
+// ─── Canvas renderer state (renderer="canvas") ───────────────────────────
+// The svg stays as the transparent interaction/zoom surface; the canvas
+// underneath paints the scene. Plain module state, mutated imperatively —
+// same rationale as the path maps above.
+const isCanvas = computed(() => props.renderer === "canvas");
+const canvasRef = ref<HTMLCanvasElement | null>(null);
+let scene: CanvasScene | null = null;
+let pickingCanvas: HTMLCanvasElement | null = null;
+let pickingCtx: CanvasRenderingContext2D | null = null;
+let canvasHoveredId: string | null = null;
+const canvasFocused = new Map<string, CanvasHighlightItem>();
+let canvasOverlays: CanvasOverlayItem[] = [];
+let redrawFrame = 0;
+// xMidYMid-meet letterbox offsets (CSS px) inside the svg/canvas box,
+// tracked by the resize observer alongside viewScale.
+let meetOffsetX = 0;
+let meetOffsetY = 0;
+
+interface CanvasViewState {
+  dpr: number;
+  meetScale: number;
+  offsetX: number;
+  offsetY: number;
+  zoom: { k: number; x: number; y: number };
+}
 let isZooming = false;
 let tooltipObserver: ResizeObserver | null = null;
 const lastTooltipSize = { width: 0, height: 0 };
@@ -474,6 +522,8 @@ function setupInteraction() {
   // `touchend` is non-passive so a confirmed tap can preventDefault and
   // suppress the compatibility click/hover the browser would otherwise
   // synthesize (the double-fire and iOS first-tap-hover sources).
+  // Must run before setupZoom(): d3-zoom stopImmediatePropagation()s
+  // touch events once its filter passes, which would starve these.
   svg.addEventListener("touchstart", onTouchStart, { passive: true });
   svg.addEventListener("touchend", onTouchEnd);
   svg.addEventListener("touchcancel", onTouchCancel, { passive: true });
@@ -481,6 +531,14 @@ function setupInteraction() {
   // degrades zoom/pan); taps provide the one-shot hover + tooltip instead
   // (see touchHover).
   if (isTouchDevice()) return;
+  if (isCanvas.value) {
+    // No per-feature elements to delegate to — clicks resolve through the
+    // picking canvas and hover through per-mousemove picking on the svg.
+    svg.addEventListener("click", onDelegatedEvent);
+    svg.addEventListener("mousemove", onCanvasMouseMove);
+    svg.addEventListener("mouseleave", onCanvasMouseLeave);
+    return;
+  }
   g.addEventListener("click", onDelegatedEvent);
   g.addEventListener("mouseover", onDelegatedEvent);
   g.addEventListener("mousemove", onDelegatedMouseMove);
@@ -494,6 +552,9 @@ function teardownInteraction() {
     svg.removeEventListener("touchstart", onTouchStart);
     svg.removeEventListener("touchend", onTouchEnd);
     svg.removeEventListener("touchcancel", onTouchCancel);
+    svg.removeEventListener("click", onDelegatedEvent);
+    svg.removeEventListener("mousemove", onCanvasMouseMove);
+    svg.removeEventListener("mouseleave", onCanvasMouseLeave);
   }
   if (!g) return;
   g.removeEventListener("click", onDelegatedEvent);
@@ -515,20 +576,55 @@ function dismissOnViewportChange() {
 let svgResizeObserver: ResizeObserver | null = null;
 
 onMounted(() => {
-  setupZoom();
+  // Order is load-bearing: once its filter passes (zoom activated /
+  // expanded), d3-zoom calls stopImmediatePropagation() on touchstart and
+  // touchend. Same-element listeners run in registration order, so our
+  // tap listeners must be registered BEFORE d3-zoom's or taps (selection,
+  // tooltips) go dead the moment the map owns touch gestures.
   setupInteraction();
+  setupZoom();
   rebuildPaths();
   applyFocus();
   attachTooltipObserver();
   if (svgRef.value && typeof ResizeObserver !== "undefined") {
     svgResizeObserver = new ResizeObserver((entries) => {
-      const w = entries[0]?.contentRect.width;
-      if (!w) return;
-      viewScale.value = w / CANONICAL_WIDTH;
-      applyStrokeScale();
+      const rect = entries[0]?.contentRect;
+      if (!rect?.width) return;
+      // Replicate preserveAspectRatio="xMidYMid meet": a uniform scale to
+      // fit, centered — the letterbox offsets matter in fullscreen, where
+      // the svg box no longer matches the viewBox aspect ratio.
+      const s = rect.height
+        ? Math.min(rect.width / width.value, rect.height / height.value)
+        : rect.width / width.value;
+      viewScale.value = s;
+      meetOffsetX = (rect.width - s * width.value) / 2;
+      meetOffsetY = rect.height ? (rect.height - s * height.value) / 2 : 0;
+      if (isCanvas.value) {
+        const canvas = canvasRef.value;
+        const svgEl = svgRef.value;
+        if (canvas && svgEl) {
+          // Pin the canvas over the svg box (the wrapper also contains the
+          // in-flow header above the map). SVG elements have no offsetTop,
+          // so derive the offset from the two bounding rects.
+          const wrapRect = containerRef.value?.getBoundingClientRect();
+          const svgRect = svgEl.getBoundingClientRect();
+          canvas.style.top = `${svgRect.top - (wrapRect?.top ?? 0)}px`;
+          canvas.style.left = `${svgRect.left - (wrapRect?.left ?? 0)}px`;
+          canvas.style.width = `${rect.width}px`;
+          canvas.style.height = `${rect.height}px`;
+          const dpr =
+            (typeof window !== "undefined" && window.devicePixelRatio) || 1;
+          canvas.width = Math.max(1, Math.round(rect.width * dpr));
+          canvas.height = Math.max(1, Math.round(rect.height * dpr));
+        }
+        requestRedraw();
+      } else {
+        applyStrokeScale();
+      }
     });
     svgResizeObserver.observe(svgRef.value);
   }
+  if (isCanvas.value) armDprListener();
   window.addEventListener("scroll", dismissOnViewportChange, {
     passive: true,
     capture: true,
@@ -539,7 +635,9 @@ onMounted(() => {
 onUnmounted(() => {
   tooltipObserver?.disconnect();
   svgResizeObserver?.disconnect();
+  dprQuery?.removeEventListener("change", onDprChange);
   if (pendingMoveFrame) cancelAnimationFrame(pendingMoveFrame);
+  if (redrawFrame) cancelAnimationFrame(redrawFrame);
   window.clearTimeout(pendingSelectTimer);
   teardownZoom();
   teardownInteraction();
@@ -569,7 +667,10 @@ function setupZoom() {
       // click press felt broken. The tooltip only needs to go once the
       // map actually moves under the cursor.
       clearHover();
-      if (mapGroupRef.value) {
+      if (isCanvas.value) {
+        // Frames blit + progressively sharpen via the render pipeline.
+        requestRedraw();
+      } else if (mapGroupRef.value) {
         mapGroupRef.value.setAttribute("transform", event.transform);
       }
       const t = event.transform;
@@ -580,6 +681,8 @@ function setupZoom() {
     })
     .on("end", () => {
       isZooming = false;
+      // Sharpen after gestures: an idle-view frame starts a base refresh.
+      if (isCanvas.value) requestRedraw();
     });
 
   // Dynamic filter deciding which pointer gestures d3-zoom may handle —
@@ -693,33 +796,55 @@ function applyFocus() {
   const baseResolved = resolved.filter((r) => r.geoType === props.geoType);
   const overlayResolved = resolved.filter((r) => r.geoType !== props.geoType);
 
-  // Diff base-geoType highlights, keyed by path element so we can
-  // restyle on style change without churning unrelated paths.
-  const nextBaseStyles = new Map<SVGPathElement, FocusItem>();
-  for (const r of baseResolved) {
-    const p = pathsByFeatureId.get(String(r.feature.id));
-    if (p) nextBaseStyles.set(p, r.item);
-  }
-  for (const [p] of focusedPathStyles) {
-    if (nextBaseStyles.has(p) || p === hoveredEl) continue;
-    restoreDefaultStroke(p);
-  }
-  for (const [p, item] of nextBaseStyles) {
-    const prev = focusedPathStyles.get(p);
-    const unchanged =
-      prev != null &&
-      prev.style === item.style &&
-      prev.stroke === item.stroke &&
-      prev.strokeWidth === item.strokeWidth;
-    if (unchanged && p !== hoveredEl) continue; // already styled
-    if (p !== hoveredEl) applyHighlightStroke(p, item);
-  }
-  focusedPathStyles.clear();
-  for (const [p, item] of nextBaseStyles) focusedPathStyles.set(p, item);
+  if (isCanvas.value) {
+    // Canvas backend: highlights and overlays are just draw state.
+    canvasFocused.clear();
+    for (const r of baseResolved) {
+      canvasFocused.set(String(r.feature.id), r.item);
+    }
+    const generator = pathGenerator.value;
+    canvasOverlays = overlayResolved.flatMap((r) => {
+      const d = generator(r.feature);
+      if (!d) return [];
+      return [
+        {
+          path: new Path2D(d),
+          stroke: r.item.stroke ?? "#fff",
+          strokeWidth: r.item.strokeWidth,
+          style: r.item.style,
+        },
+      ];
+    });
+    requestRedraw();
+  } else {
+    // Diff base-geoType highlights, keyed by path element so we can
+    // restyle on style change without churning unrelated paths.
+    const nextBaseStyles = new Map<SVGPathElement, FocusItem>();
+    for (const r of baseResolved) {
+      const p = pathsByFeatureId.get(String(r.feature.id));
+      if (p) nextBaseStyles.set(p, r.item);
+    }
+    for (const [p] of focusedPathStyles) {
+      if (nextBaseStyles.has(p) || p === hoveredEl) continue;
+      restoreDefaultStroke(p);
+    }
+    for (const [p, item] of nextBaseStyles) {
+      const prev = focusedPathStyles.get(p);
+      const unchanged =
+        prev != null &&
+        prev.style === item.style &&
+        prev.stroke === item.stroke &&
+        prev.strokeWidth === item.strokeWidth;
+      if (unchanged && p !== hoveredEl) continue; // already styled
+      if (p !== hoveredEl) applyHighlightStroke(p, item);
+    }
+    focusedPathStyles.clear();
+    for (const [p, item] of nextBaseStyles) focusedPathStyles.set(p, item);
 
-  // Cross-geoType outlines render as non-interactive paths on top of
-  // the base layer.
-  syncOverlayPaths(overlayResolved);
+    // Cross-geoType outlines render as non-interactive paths on top of
+    // the base layer.
+    syncOverlayPaths(overlayResolved);
+  }
 
   // Clearing focus doesn't touch the zoom transform — the user keeps
   // whatever pan/zoom they had. Only the reset button snaps back to
@@ -766,10 +891,15 @@ function applyFocus() {
   const showFocusTooltip = () => {
     if (!hasInteractiveTooltip.value || !tooltipTarget) return;
     const firstId = String(tooltipTarget.id);
+    // Read positions *after* the transform commits so the tooltip lands
+    // at the focused feature's on-screen position.
+    if (isCanvas.value) {
+      const anchor = featureClientAnchor(firstId);
+      if (anchor) showTooltip(firstId, anchor.x, anchor.y);
+      return;
+    }
     const pathEl = pathsByFeatureId.get(firstId);
     if (!pathEl) return;
-    // Read the rect *after* the transform commits so the tooltip lands at
-    // the focused feature's on-screen position.
     const rect = pathEl.getBoundingClientRect();
     showTooltip(
       firstId,
@@ -933,8 +1063,12 @@ const svgStyle = computed(() => {
   if (
     hasZoomed.value ||
     fullscreen.isFullscreen.value ||
-    (props.zoom && isScrollMode.value)
+    (props.zoom && (isScrollMode.value || isTouchDevice()))
   ) {
+    // Touch maps get the layer up front, not just once zoomed: a tap
+    // restyles a feature path, and without the layer WebKit repaints the
+    // surrounding page layer (~200ms per mutation on the HSA map — taps
+    // felt sluggish inline while fullscreen, already layered, was fast).
     style["will-change"] = "transform";
   }
   return Object.keys(style).length ? style : undefined;
@@ -952,13 +1086,16 @@ function zoomBy(factor: number) {
 // Zoom level a tap zooms to (expanding or in place).
 const TAP_ZOOM_SCALE = 2;
 
-// Target transform for a tap: TAP_ZOOM_SCALE× centered on the tapped
-// point. Falls back to the map center when the CTM is unavailable (jsdom).
-function tapZoomTransform(clientX: number, clientY: number): ZoomTransform {
-  const svgEl = svgRef.value!;
-  const k = TAP_ZOOM_SCALE;
-  let mx = width.value / 2;
-  let my = height.value / 2;
+// client → canonical viewBox coordinates via the svg's CTM (which covers
+// viewBox scaling, letterboxing, and pinch-zoom quirks). Falls back to a
+// rect-proportional mapping when the CTM is unavailable (non-rendering
+// test DOMs).
+function clientToViewBox(
+  clientX: number,
+  clientY: number,
+): [number, number] | null {
+  const svgEl = svgRef.value;
+  if (!svgEl) return null;
   let ctm: DOMMatrix | null = null;
   try {
     ctm = svgEl.getScreenCTM();
@@ -966,13 +1103,27 @@ function tapZoomTransform(clientX: number, clientY: number): ZoomTransform {
     ctm = null;
   }
   if (ctm) {
-    // client → viewBox coords (the svg CTM covers viewBox scaling and
-    // letterboxing), then unwind the current zoom transform.
     const inv = ctm.inverse();
-    const px = inv.a * clientX + inv.c * clientY + inv.e;
-    const py = inv.b * clientX + inv.d * clientY + inv.f;
-    [mx, my] = zoomTransform(svgEl).invert([px, py]);
+    return [
+      inv.a * clientX + inv.c * clientY + inv.e,
+      inv.b * clientX + inv.d * clientY + inv.f,
+    ];
   }
+  const rect = svgEl.getBoundingClientRect();
+  const sx = rect.width ? width.value / rect.width : 1;
+  const sy = rect.height ? height.value / rect.height : 1;
+  return [(clientX - rect.left) * sx, (clientY - rect.top) * sy];
+}
+
+// Target transform for a tap: TAP_ZOOM_SCALE× centered on the tapped
+// point. Falls back to the map center when the point can't be resolved.
+function tapZoomTransform(clientX: number, clientY: number): ZoomTransform {
+  const svgEl = svgRef.value!;
+  const k = TAP_ZOOM_SCALE;
+  let mx = width.value / 2;
+  let my = height.value / 2;
+  const p = clientToViewBox(clientX, clientY);
+  if (p) [mx, my] = zoomTransform(svgEl).invert(p);
   return zoomIdentity
     .translate(width.value / 2 - k * mx, height.value / 2 - k * my)
     .scale(k);
@@ -1520,23 +1671,53 @@ function applyTooltipPosition(clientX: number, clientY: number) {
     chartRect,
   );
   el.style.transform = `translate3d(${left}px, ${top}px, 0) translateY(-50%)`;
+  // Safari reports client coordinates (events AND element rects) in
+  // visual-viewport space, while position: fixed resolves against the
+  // layout viewport — under page pinch-zoom the tooltip lands offset from
+  // its target (typically "too high" by the pan offset). Rather than
+  // sniffing engines, self-calibrate: re-measure where the tooltip
+  // actually landed — the rect comes back in the same client space as the
+  // target coords — and shift by the residual. Chrome measures ~0.
+  const vv = typeof window !== "undefined" ? window.visualViewport : null;
+  if (!vv || (vv.scale <= 1.01 && vv.offsetTop < 1 && vv.offsetLeft < 1)) {
+    return;
+  }
+  const actual = el.getBoundingClientRect();
+  const dx = actual.left - left;
+  const dy = actual.top + actual.height / 2 - top;
+  if (Math.abs(dx) > 1 || Math.abs(dy) > 1) {
+    el.style.transform = `translate3d(${left - dx}px, ${top - dy}px, 0) translateY(-50%)`;
+  }
 }
 
+// The expanded touch view swaps the pointer-anchored tooltip for a bottom
+// sheet: floating fixed positioning is unreliable there (Safari reports
+// touch/rect coordinates in visual-viewport space once the page is
+// pinch-zoomed), while a sheet pinned to the wrapper is always right.
+const tooltipMode = computed<"float" | "sheet">(() =>
+  fullscreen.isFullscreen.value && isTouchDevice() ? "sheet" : "float",
+);
+
 function showTooltip(featId: string, clientX: number, clientY: number) {
   const data = tooltipDataById.get(featId);
   if (!data) return;
   const child = tooltipChildRef.value;
-  const el = child?.getEl();
-  if (!child || !el) return;
+  if (!child) return;
   child.setData(data);
-  lastPointer = { x: clientX, y: clientY };
   tooltipVisible = true;
+  if (tooltipMode.value === "sheet") {
+    child.setOpen(true);
+    return;
+  }
+  const el = child.getEl();
+  if (!el) return;
+  lastPointer = { x: clientX, y: clientY };
   applyTooltipPosition(clientX, clientY);
   el.style.visibility = "visible";
 }
 
 function moveTooltip(clientX: number, clientY: number) {
-  if (!tooltipVisible) return;
+  if (!tooltipVisible || tooltipMode.value === "sheet") return;
   pendingMoveX = clientX;
   pendingMoveY = clientY;
   if (pendingMoveFrame) return;
@@ -1554,6 +1735,7 @@ function hideTooltip() {
   if (!tooltipVisible) return;
   tooltipVisible = false;
   lastPointer = null;
+  tooltipChildRef.value?.setOpen(false);
   const el = tooltipChildRef.value?.getEl();
   if (el) el.style.visibility = "hidden";
 }
@@ -1605,7 +1787,224 @@ function highlightWidthFor(item?: FocusItem): number {
   return item?.strokeWidth ?? effectiveStrokeWidth.value + 1;
 }
 
+// ─── Canvas renderer: redraw, picking, tooltip anchors ───────────────────
+
+function canvasHighlightColor(): string {
+  // light-dark() isn't paintable on a canvas context; resolve it through
+  // the shared probe. (Cached by input — a mid-session theme flip keeps
+  // the first resolution until remount, same tradeoff as resolveColorToRgb
+  // elsewhere.)
+  const rgb = resolveColorToRgb(HIGHLIGHT_STROKE);
+  return rgb ? `rgb(${rgb[0]},${rgb[1]},${rgb[2]})` : "#000";
+}
+
+function currentCanvasView(): CanvasViewState {
+  const t = zoomTransform(svgRef.value!);
+  return {
+    dpr: (typeof window !== "undefined" && window.devicePixelRatio) || 1,
+    meetScale: viewScale.value,
+    offsetX: meetOffsetX,
+    offsetY: meetOffsetY,
+    zoom: { k: t.k, x: t.x, y: t.y },
+  };
+}
+
+function canvasDrawState(): CanvasDrawState {
+  return {
+    strokeColor: props.strokeColor,
+    strokeWidth: effectiveStrokeWidth.value,
+    highlightStroke: canvasHighlightColor(),
+    hoveredId: canvasHoveredId,
+    focused: canvasFocused,
+    overlays: canvasOverlays,
+  };
+}
+
+// Direct rendering with an adaptive buffered fallback. With the canvas on
+// its own compositor layer and feature outlines stroked as one path, a
+// full county-scale pass rasters in single-digit milliseconds, so every
+// frame renders the whole scene crisply. If a device proves slower (two
+// consecutive full draws over SLOW_FRAME_MS), gesture frames fall back to
+// blitting the last crisp render, refreshed at least every
+// GESTURE_REFRESH_MS, and always sharpened at rest.
+const SLOW_FRAME_MS = 24;
+const GESTURE_REFRESH_MS = 350;
+let slowDrawStreak = 0;
+let fastDrawStreak = 0;
+let rendererIsSlow = false;
+// Canvas backing stores are sized in device pixels, and ResizeObserver
+// doesn't fire when the window moves to a display with a different
+// devicePixelRatio. Watch a resolution media query instead — it matches
+// only the current DPR, so each change re-arms a fresh query (the
+// standard trick), resizes the backing store, and redraws.
+let dprQuery: MediaQueryList | null = null;
+
+function armDprListener() {
+  if (
+    typeof window === "undefined" ||
+    typeof window.matchMedia !== "function"
+  ) {
+    return;
+  }
+  dprQuery?.removeEventListener("change", onDprChange);
+  dprQuery = window.matchMedia(
+    `(resolution: ${window.devicePixelRatio || 1}dppx)`,
+  );
+  dprQuery.addEventListener("change", onDprChange);
+}
+
+function onDprChange() {
+  armDprListener();
+  const canvas = canvasRef.value;
+  const svgEl = svgRef.value;
+  if (!isCanvas.value || !canvas || !svgEl) return;
+  const rect = svgEl.getBoundingClientRect();
+  if (rect.width) {
+    const dpr = window.devicePixelRatio || 1;
+    canvas.width = Math.max(1, Math.round(rect.width * dpr));
+    canvas.height = Math.max(1, Math.round(rect.height * dpr));
+  }
+  requestRedraw();
+}
+
+let snapshotCanvas: HTMLCanvasElement | null = null;
+let snapshotView: CanvasViewState | null = null;
+let lastFullDrawAt = 0;
+
+function blitSnapshot(
+  ctx: CanvasRenderingContext2D,
+  view: CanvasViewState,
+  img: HTMLCanvasElement,
+  imgView: CanvasViewState,
+) {
+  const off = (v: CanvasViewState, axis: "x" | "y") =>
+    v.dpr *
+    ((axis === "x" ? v.offsetX : v.offsetY) +
+      v.meetScale * (axis === "x" ? v.zoom.x : v.zoom.y));
+  const r =
+    (view.dpr * view.meetScale * view.zoom.k) /
+    (imgView.dpr * imgView.meetScale * imgView.zoom.k);
+  ctx.setTransform(
+    r,
+    0,
+    0,
+    r,
+    off(view, "x") - r * off(imgView, "x"),
+    off(view, "y") - r * off(imgView, "y"),
+  );
+  ctx.drawImage(img, 0, 0);
+  ctx.setTransform(1, 0, 0, 1, 0, 0);
+}
+
+function drawNow() {
+  const display = canvasRef.value;
+  if (!display) return;
+  const ctx = display.getContext("2d");
+  if (!ctx) return;
+  const now = () =>
+    typeof performance !== "undefined" ? performance.now() : 0;
+  ctx.setTransform(1, 0, 0, 1, 0, 0);
+  ctx.clearRect(0, 0, display.width, display.height);
+  if (!scene) return;
+  const view = currentCanvasView();
+
+  // Slow-device fallback: blit between throttled crisp refreshes while a
+  // gesture is live.
+  if (
+    rendererIsSlow &&
+    isZooming &&
+    snapshotCanvas &&
+    snapshotView &&
+    typeof ctx.drawImage === "function" &&
+    now() - lastFullDrawAt < GESTURE_REFRESH_MS
+  ) {
+    blitSnapshot(ctx, view, snapshotCanvas, snapshotView);
+    if (canvasHoveredId) {
+      drawHoverHighlight(ctx, scene, view, canvasDrawState(), canvasHoveredId);
+    }
+    return;
+  }
+
+  const t0 = now();
+  drawScene(ctx, scene, view, canvasDrawState());
+  const dt = now() - t0;
+  lastFullDrawAt = t0 + dt;
+  // Symmetric hysteresis: two consecutive slow full draws engage the
+  // fallback, two consecutive fast ones release it — so a cold-start
+  // hiccup (JIT warmup, first-paint contention) can't lock a fast device
+  // into blurry gesture blits forever.
+  if (dt > SLOW_FRAME_MS) {
+    fastDrawStreak = 0;
+    if (++slowDrawStreak >= 2) rendererIsSlow = true;
+  } else {
+    slowDrawStreak = 0;
+    if (++fastDrawStreak >= 2) rendererIsSlow = false;
+  }
+  if (!rendererIsSlow || typeof document === "undefined") return;
+  // Keep a snapshot current for the fallback's gesture blits.
+  if (!snapshotCanvas) snapshotCanvas = document.createElement("canvas");
+  if (snapshotCanvas.width !== display.width) {
+    snapshotCanvas.width = display.width;
+  }
+  if (snapshotCanvas.height !== display.height) {
+    snapshotCanvas.height = display.height;
+  }
+  const sctx = snapshotCanvas.getContext("2d");
+  if (sctx && typeof sctx.drawImage === "function") {
+    sctx.setTransform(1, 0, 0, 1, 0, 0);
+    sctx.clearRect(0, 0, snapshotCanvas.width, snapshotCanvas.height);
+    sctx.drawImage(display, 0, 0);
+    snapshotView = view;
+  } else {
+    snapshotView = null;
+  }
+}
+
+// rAF-coalesced: gesture zooms can emit several events per frame.
+function requestRedraw() {
+  if (!isCanvas.value || redrawFrame) return;
+  redrawFrame = requestAnimationFrame(() => {
+    redrawFrame = 0;
+    drawNow();
+  });
+}
+
+// Feature under a client point via the picking canvas — O(1) per query
+// regardless of feature count. The zoom transform is unwound here; the
+// picking bitmap itself is only rebuilt on geometry changes.
+function pickFeatureAt(clientX: number, clientY: number): string | null {
+  const svgEl = svgRef.value;
+  if (!svgEl || !scene || !pickingCtx) return null;
+  const p = clientToViewBox(clientX, clientY);
+  if (!p) return null;
+  const [mx, my] = zoomTransform(svgEl).invert(p);
+  const idx = pickIndexAt(pickingCtx, scene, mx, my);
+  return idx == null ? null : scene.items[idx].id;
+}
+
+// Client-coordinate center of a feature — the canvas-mode stand-in for a
+// path element's getBoundingClientRect (tooltip anchoring).
+function featureClientAnchor(featId: string): { x: number; y: number } | null {
+  const svgEl = svgRef.value;
+  const f = featuresById.value.get(featId);
+  if (!svgEl || !f) return null;
+  const [[x0, y0], [x1, y1]] = pathGenerator.value.bounds(f);
+  const [vx, vy] = zoomTransform(svgEl).apply([(x0 + x1) / 2, (y0 + y1) / 2]);
+  let ctm: DOMMatrix | null = null;
+  try {
+    ctm = svgEl.getScreenCTM();
+  } catch {
+    ctm = null;
+  }
+  if (!ctm) return null;
+  return {
+    x: ctm.a * vx + ctm.c * vy + ctm.e,
+    y: ctm.b * vx + ctm.d * vy + ctm.f,
+  };
+}
+
 function applyStrokeScale() {
+  if (isCanvas.value) return; // stroke widths are computed at draw time
   const d = strokeDivisor();
   const eff = effectiveStrokeWidth.value;
   baseGroupRef.value?.setAttribute("stroke-width", String(eff / d));
@@ -1662,7 +2061,31 @@ function setHover(pathEl: SVGPathElement) {
   applyHighlightStroke(pathEl, focusedPathStyles.get(pathEl));
 }
 
+// Renderer-agnostic hover entry point: canvas mode tracks an id and
+// repaints; svg mode restyles the path element.
+function setHoverId(featId: string) {
+  if (isCanvas.value) {
+    if (canvasHoveredId === featId) return;
+    canvasHoveredId = featId;
+    requestRedraw();
+    return;
+  }
+  const p = pathsByFeatureId.get(featId);
+  if (p) setHover(p);
+}
+
 function clearHover() {
+  if (isCanvas.value) {
+    if (canvasHoveredId != null) {
+      canvasHoveredId = null;
+      // The hover highlight lives on the display layer, so dropping it
+      // is just another cheap composite frame.
+      requestRedraw();
+      emit("stateHover", null);
+    }
+    hideTooltip();
+    return;
+  }
   if (hoveredEl) {
     const focusItem = focusedPathStyles.get(hoveredEl);
     if (focusItem == null) {
@@ -1704,7 +2127,7 @@ function onDelegatedEvent(event: Event) {
   // already swallows genuine post-drag clicks via clickDistance.
   if (event.type === "mouseover" && isZooming) return;
   const me = event as MouseEvent;
-  const featId = eventToFeatureId(me.target);
+  const featId = featureIdFromEvent(me.target, me.clientX, me.clientY);
   if (!featId) return;
   const data = tooltipDataById.get(featId);
   if (!data) return;
@@ -1725,7 +2148,7 @@ function onDelegatedEvent(event: Event) {
       emitSelection(data);
     }
   } else if (event.type === "mouseover") {
-    setHover(pathsByFeatureId.get(featId)!);
+    setHoverId(featId);
     if (hasInteractiveTooltip.value)
       showTooltip(featId, me.clientX, me.clientY);
     emit("stateHover", payload);
@@ -1743,6 +2166,44 @@ function onDelegatedMouseOut(event: MouseEvent) {
   clearHover();
 }
 
+// Canvas mode has no per-feature elements to delegate mouseover to —
+// hover is resolved by picking on every mousemove instead (a 1px read
+// from a CPU canvas; cheap even at mousemove rates).
+function onCanvasMouseMove(event: MouseEvent) {
+  if (isZooming) return;
+  const featId = pickFeatureAt(event.clientX, event.clientY);
+  if (featId === canvasHoveredId) {
+    if (featId) moveTooltip(event.clientX, event.clientY);
+    return;
+  }
+  if (!featId) {
+    clearHover();
+    return;
+  }
+  const data = tooltipDataById.get(featId);
+  if (!data) return;
+  setHoverId(featId);
+  emit("stateHover", { id: data.id, name: data.name, value: data.value });
+  if (hasInteractiveTooltip.value) {
+    showTooltip(featId, event.clientX, event.clientY);
+  }
+}
+
+function onCanvasMouseLeave() {
+  clearHover();
+}
+
+// Renderer-agnostic feature resolution for pointer events.
+function featureIdFromEvent(
+  target: EventTarget | null,
+  clientX: number,
+  clientY: number,
+): string | null {
+  return isCanvas.value
+    ? pickFeatureAt(clientX, clientY)
+    : eventToFeatureId(target);
+}
+
 function onTouchStart(event: TouchEvent) {
   // Single-finger only — a second touch is a pinch-zoom, not a selection.
   if (event.touches.length !== 1) {
@@ -1754,7 +2215,7 @@ function onTouchStart(event: TouchEvent) {
     x: t.clientX,
     y: t.clientY,
     time: event.timeStamp,
-    featId: eventToFeatureId(event.target),
+    featId: featureIdFromEvent(event.target, t.clientX, t.clientY),
   };
 }
 
@@ -1833,14 +2294,35 @@ function onTouchEnd(event: TouchEvent) {
 }
 
 // A tap doubles as the touch replacement for hover: apply the hover-style
-// highlight, announce it, and show the tooltip at the tapped point.
-// (Continuous hover *tracking* stays off on touch — see setupInteraction —
-// this is the one-shot equivalent.)
+// highlight, announce it, and show the tooltip. (Continuous hover
+// *tracking* stays off on touch — see setupInteraction — this is the
+// one-shot equivalent.)
 function touchHover(data: TooltipPayload, clientX: number, clientY: number) {
-  const pathEl = pathsByFeatureId.get(data.id);
-  if (pathEl) setHover(pathEl);
+  setHoverId(data.id);
   emit("stateHover", { id: data.id, name: data.name, value: data.value });
-  if (hasInteractiveTooltip.value) showTooltip(data.id, clientX, clientY);
+  if (!hasInteractiveTooltip.value) return;
+  // Anchor to the feature, not the finger: element rects and fixed
+  // positioning share the layout-viewport coordinate space, so this
+  // stays put when the page itself is pinch-zoomed — Safari reports
+  // touch client coords in *visual*-viewport space, which would skew a
+  // finger-anchored tooltip. Also keeps it out from under the finger.
+  if (isCanvas.value) {
+    const anchor = featureClientAnchor(data.id);
+    if (anchor) showTooltip(data.id, anchor.x, anchor.y);
+    else showTooltip(data.id, clientX, clientY);
+    return;
+  }
+  const pathEl = pathsByFeatureId.get(data.id);
+  if (pathEl) {
+    const rect = pathEl.getBoundingClientRect();
+    showTooltip(
+      data.id,
+      rect.left + rect.width / 2,
+      rect.top + rect.height / 2,
+    );
+  } else {
+    showTooltip(data.id, clientX, clientY);
+  }
 }
 
 function onTouchCancel() {
@@ -1877,6 +2359,9 @@ function rebuildPaths() {
   // applyFocus can re-resolve against the new path tree.
   focusedPathStyles.clear();
   overlayPathEls.clear();
+  canvasHoveredId = null;
+  canvasFocused.clear();
+  canvasOverlays = [];
 
   const path = pathGenerator.value;
   const features = featuresGeo.value.features;
@@ -1884,7 +2369,43 @@ function rebuildPaths() {
   // means the projection was fitted to an empty collection and yields NaN
   // coordinates — skip drawing entirely, including the state-borders mesh,
   // until real features arrive and re-trigger a rebuild.
-  if (features.length === 0) return;
+  if (features.length === 0) {
+    scene = null;
+    pickingCtx = null;
+    snapshotView = null;
+    requestRedraw();
+    return;
+  }
+
+  if (isCanvas.value) {
+    // Canvas backend: no DOM per feature — build the scene + picking
+    // bitmap, and keep the tooltip payload cache exactly as svg mode does.
+    for (const feat of features) {
+      const id = String(feat.id);
+      tooltipDataById.set(id, {
+        id,
+        name: featureName(feat),
+        value: valueFor(id),
+        feature: feat as ChoroplethFeature,
+      });
+    }
+    const borders = stateBordersPath.value;
+    scene = buildScene(
+      features as Array<{ id?: string | number | null }>,
+      path as (feature: never) => string | null,
+      colorFor,
+      borders ? path(borders) : null,
+    );
+    if (!pickingCanvas && typeof document !== "undefined") {
+      pickingCanvas = document.createElement("canvas");
+    }
+    pickingCtx = pickingCanvas
+      ? buildPicking(scene, width.value, height.value, pickingCanvas)
+      : null;
+    requestRedraw();
+    return;
+  }
+
   const stroke = props.strokeColor;
   const wantsTitleFallback = !hasInteractiveTooltip.value;
 
@@ -1932,6 +2453,14 @@ function rebuildPaths() {
 }
 
 function updateFills() {
+  if (isCanvas.value) {
+    if (scene) {
+      for (const item of scene.items) item.fill = colorFor(item.id);
+    }
+    for (const [id, entry] of tooltipDataById) entry.value = valueFor(id);
+    requestRedraw();
+    return;
+  }
   const refreshTitle = !hasInteractiveTooltip.value;
   for (const [id, p] of pathsByFeatureId) {
     const value = valueFor(id);
@@ -1950,6 +2479,11 @@ function updateFills() {
 }
 
 function updateStrokes() {
+  if (isCanvas.value) {
+    // Stroke params are read at render time — refresh both buffers.
+    requestRedraw();
+    return;
+  }
   for (const p of pathsByFeatureId.values()) {
     // Highlighted paths (hover / focus) keep their #555 + thicker stroke.
     if (p === hoveredEl || focusedPathStyles.has(p)) continue;
@@ -2045,6 +2579,19 @@ const fullscreen = useChartFullscreen({
 
 const menuItems = computed<ChartMenuItem[]>(() => {
   const fname = menuFilename();
+  if (isCanvas.value) {
+    // No SVG DOM to serialize in canvas mode; PNG exports straight off
+    // the rendering canvas (already devicePixelRatio-sized).
+    return [
+      fullscreen.menuItem.value,
+      {
+        label: "Save as PNG",
+        action: () => {
+          if (canvasRef.value) saveCanvasPng(canvasRef.value, fname);
+        },
+      },
+    ];
+  }
   return [
     fullscreen.menuItem.value,
     {
@@ -2111,10 +2658,12 @@ watch(
 
 // Exiting the expanded touch view (✕, Escape) returns to the static inline
 // map at full extent — the inline map has no pan gestures, so a preserved
-// transform would strand the user off-center.
+// transform would strand the user off-center. Any toggle also drops the
+// tooltip: the presentation mode (float vs sheet) may change with it.
 watch(
   () => fullscreen.isFullscreen.value,
   (expanded) => {
+    hideTooltip();
     if (expanded || !isTouchDevice()) return;
     if (!svgRef.value || !zoomBehavior) return;
     const svg = select(svgRef.value);
@@ -2204,6 +2753,17 @@ watch(
       <div v-if="showZoomHint" class="choropleth-zoom-hint">
         {{ zoomHintText }}
       </div>
+      <!-- Canvas backend paints here; the (empty) svg after it stays the
+      interaction/zoom surface. pointer-events: none lets every event fall
+      through to the svg even though the positioned canvas paints above
+      the transparent svg. Position/size are pinned to the svg box by the
+      resize observer. -->
+      <canvas
+        v-if="isCanvas"
+        ref="canvasRef"
+        class="choropleth-canvas"
+        aria-hidden="true"
+      />
       <svg
         ref="svgRef"
         :viewBox="`0 0 ${width} ${height}`"
@@ -2234,7 +2794,11 @@ watch(
         @zoom-out="zoomBy(1 / ZOOM_STEP)"
         @reset="resetZoom"
       />
-      <ChoroplethTooltip v-if="hasInteractiveTooltip" ref="tooltipChildRef">
+      <ChoroplethTooltip
+        v-if="hasInteractiveTooltip"
+        ref="tooltipChildRef"
+        :mode="tooltipMode"
+      >
         <template #default="raw">
           <slot name="tooltip" v-bind="narrowSlotProps(raw)">
             <span v-if="tooltipFormat" v-html="tooltipFormat(raw)" />
@@ -2295,6 +2859,18 @@ watch(
   cursor: pointer;
 }
 
+.choropleth-canvas {
+  position: absolute;
+  top: 0;
+  left: 0;
+  pointer-events: none;
+  /* Own compositor layer: without it WebKit repaints the surrounding
+     page layer on every canvas frame (the same >100ms/frame pathology
+     the svg renderer hit). Canvas mode implies interactivity, so the
+     layer is always warranted. */
+  will-change: transform;
+}
+
 /* Overlays the top of the map: absolutely positioned with no `top`, the
    box keeps its static position — the top edge of the svg that follows it
    in the markup — without taking up flow space. The text carries a