@cfasim-ui/docs 0.7.4 → 0.7.6

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,
@@ -131,6 +142,16 @@ const props = withDefaults(
     state?: string;
     width?: number;
     height?: number;
+    /**
+     * Tighten the national (multi-state) fit by cropping the Alaska/Hawaii
+     * overhang so the contiguous US fills more of the frame. `false`/`0`
+     * (default) fits every region into view; `true`/`1` fits the lower-48 to
+     * the frame and lets Alaska's western tail (and Hawaii) clip into the
+     * lower-left corner. A number in between (e.g. `0.5`) crops partway. No
+     * effect in single-state mode or on a national HSA map (HSA ids aren't
+     * FIPS, so AK/HI can't be split out).
+     */
+    tightFit?: boolean | number;
     colorScale?: ChoroplethColorScale | ThresholdStop[] | CategoricalStop[];
     /**
      * Map title. `\n` in the string creates additional lines, each
@@ -255,6 +276,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,12 +304,14 @@ const props = withDefaults(
     menu: true,
     legend: true,
     zoom: false,
+    renderer: "svg",
     zoomMode: "activate",
     touchExpand: true,
     zoomHint: true,
     tooltipClamp: "chart",
     focusZoomLevel: 4,
     focusZoom: true,
+    tightFit: false,
   },
 );
 
@@ -398,6 +431,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 };
@@ -483,6 +542,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);
@@ -496,6 +563,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);
@@ -529,13 +599,43 @@ onMounted(() => {
   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,
@@ -546,7 +646,9 @@ onMounted(() => {
 onUnmounted(() => {
   tooltipObserver?.disconnect();
   svgResizeObserver?.disconnect();
+  dprQuery?.removeEventListener("change", onDprChange);
   if (pendingMoveFrame) cancelAnimationFrame(pendingMoveFrame);
+  if (redrawFrame) cancelAnimationFrame(redrawFrame);
   window.clearTimeout(pendingSelectTimer);
   teardownZoom();
   teardownInteraction();
@@ -576,7 +678,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;
@@ -587,6 +692,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 —
@@ -700,33 +807,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
@@ -773,10 +902,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,
@@ -963,13 +1097,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();
@@ -977,13 +1114,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);
@@ -1217,6 +1368,31 @@ const stateBordersPath = computed(() => {
 // flush against the SVG edge. Only applied in single-state mode.
 const STATE_FIT_INSET = 12;
 
+// Resolved `tightFit` amount in [0,1]: false/0 → 0 (full fit), true → 1.
+const tightFitAmount = computed(() => {
+  const v = props.tightFit;
+  if (v === true) return 1;
+  if (!v) return 0;
+  return Math.max(0, Math.min(1, Number(v)));
+});
+
+// The national fit target with Alaska (FIPS 02) and Hawaii (15) removed, so
+// the projection can be re-fit to just the contiguous US. Null when the crop
+// is off, in single-state mode, on an HSA map (ids aren't FIPS), or when
+// nothing was removed — the projection then uses the plain full fit.
+const conusFeaturesGeo = computed(() => {
+  if (tightFitAmount.value <= 0 || stateFips.value) return null;
+  if (props.geoType === "hsas") return null;
+  const fc = featuresGeo.value;
+  const pad = props.geoType === "counties" ? 5 : 2;
+  const kept = fc.features.filter((f) => {
+    const st = String(f.id).padStart(pad, "0").slice(0, 2);
+    return st !== "02" && st !== "15";
+  });
+  if (kept.length === fc.features.length) return null;
+  return { type: "FeatureCollection" as const, features: kept };
+});
+
 const projection = computed(() => {
   const outline = stateOutlineFeature.value;
   if (stateFips.value && outline) {
@@ -1236,13 +1412,27 @@ const projection = computed(() => {
     if (Number.isFinite(c[0]) && Number.isFinite(c[1])) return albers;
     return geoMercator().fitExtent(extent, outline);
   }
-  return geoAlbersUsa().fitExtent(
-    [
-      [0, 0],
-      [width.value, height.value],
-    ],
-    featuresGeo.value,
-  );
+  const extent: [[number, number], [number, number]] = [
+    [0, 0],
+    [width.value, height.value],
+  ];
+  const full = geoAlbersUsa().fitExtent(extent, featuresGeo.value);
+  const conus = conusFeaturesGeo.value;
+  if (!conus) return full;
+  // Tighten the fit by interpolating the projection's scale + translate from
+  // the full fit toward the contiguous-US fit. At amount 1 CONUS fills the
+  // frame and Alaska's western tail (and Hawaii) clip into the lower-left
+  // corner, cropped by the SVG/canvas viewport. Everything downstream (paths,
+  // picking, tooltip anchors, focus zoom) derives from this projection, so
+  // both renderers stay consistent.
+  const tight = geoAlbersUsa().fitExtent(extent, conus);
+  const t = tightFitAmount.value;
+  const lerp = (a: number, b: number) => a + (b - a) * t;
+  const [fx, fy] = full.translate();
+  const [tx, ty] = tight.translate();
+  return geoAlbersUsa()
+    .scale(lerp(full.scale(), tight.scale()))
+    .translate([lerp(fx, tx), lerp(fy, ty)]);
 });
 
 const pathGenerator = computed(() => geoPath(projection.value));
@@ -1483,7 +1673,8 @@ function titleText(name: string, value: number | string | undefined): string {
 //      using lastTooltipSize (possibly stale by one frame) → visibility:visible
 //   2. tooltipObserver fires when the slot DOM has actually committed → we
 //      refresh lastTooltipSize and re-apply the position if still visible.
-//   3. mousemove  → rAF-throttled direct DOM write of transform; no reactivity.
+//   3. mousemove  → rAF-throttled; re-runs the same flip/clamp placement as
+//      the initial hover (direct DOM write of transform, no reactivity).
 //   4. mouseout (leaving the map) → visibility:hidden.
 //
 // There is no `await` and no token: out-of-order completion is impossible
@@ -1583,11 +1774,14 @@ function moveTooltip(clientX: number, clientY: number) {
   if (pendingMoveFrame) return;
   pendingMoveFrame = requestAnimationFrame(() => {
     pendingMoveFrame = 0;
-    const el = tooltipChildRef.value?.getEl();
-    if (!el || !tooltipVisible) return;
+    if (!tooltipVisible) return;
     lastPointer = { x: pendingMoveX, y: pendingMoveY };
-    // Mid-hover: don't re-run flip/clamp on every pixel; just translate.
-    el.style.transform = `translate3d(${pendingMoveX + 16}px, ${pendingMoveY}px, 0) translateY(-50%)`;
+    // Re-run the same flip/clamp as the initial hover. This is already
+    // rAF-coalesced (at most once per frame), so the flip/clamp cost is
+    // negligible. Hardcoding the right side here instead made the tooltip
+    // ignore the boundary while moving and fight showTooltip's per-feature
+    // flip on dense maps (the tooltip appeared to switch sides).
+    applyTooltipPosition(pendingMoveX, pendingMoveY);
   });
 }
 
@@ -1647,7 +1841,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));
@@ -1704,7 +2115,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) {
@@ -1746,7 +2181,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;
@@ -1767,7 +2202,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);
@@ -1785,6 +2220,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) {
@@ -1796,7 +2269,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),
   };
 }
 
@@ -1825,8 +2298,10 @@ function onTouchEnd(event: TouchEvent) {
     !fullscreen.isFullscreen.value
   ) {
     // Suppress the synthetic click/hover the browser would replay from
-    // this tap (and iOS's hover-first tap).
-    event.preventDefault();
+    // this tap (and iOS's hover-first tap). Guard on cancelable: a
+    // touchend fired while the page is mid-scroll is non-cancelable, and
+    // preventDefault there is a no-op that only logs a console intervention.
+    if (event.cancelable) event.preventDefault();
     const prev = lastTap;
     lastTap = { x: t.clientX, y: t.clientY, time: event.timeStamp };
     const isDoubleTap =
@@ -1868,8 +2343,10 @@ function onTouchEnd(event: TouchEvent) {
   const data = tooltipDataById.get(start.featId);
   if (!data) return;
   // Suppress the synthetic click/hover the browser would replay from this
-  // tap, so selection fires exactly once and never via iOS's hover-first tap.
-  event.preventDefault();
+  // tap, so selection fires exactly once and never via iOS's hover-first
+  // tap. Guard on cancelable — a touchend fired mid page-scroll is
+  // non-cancelable, and preventDefault there only logs an intervention.
+  if (event.cancelable) event.preventDefault();
   touchHover(data, t.clientX, t.clientY);
   emitSelection(data);
 }
@@ -1879,16 +2356,22 @@ function onTouchEnd(event: TouchEvent) {
 // *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) 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) {
-    // 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.
     const rect = pathEl.getBoundingClientRect();
     showTooltip(
       data.id,
@@ -1934,6 +2417,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;
@@ -1941,7 +2427,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;
 
@@ -1989,6 +2511,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);
@@ -2007,6 +2537,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;
@@ -2102,6 +2637,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,
     {
@@ -2263,6 +2811,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}`"
@@ -2358,6 +2917,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