cursedbelt 5.92.3 → 5.94.0

package/src/react/map-frame/MapFrame.tsx

@@ -0,0 +1,954 @@
+/**
+ * A map: Google's imagery underneath, our own interactive layer on top.
+ *
+ * cursedbelt/react/map-frame — lifted from apps/family (forge task 3700) so every app draws
+ * maps through ONE frame. The imagery comes from the app's own `/api/map` proxy
+ * (`imageSource` overrides the URL); `cursedbelt-server/maps-static` is that proxy's shared
+ * half. The owner's reports quoted below were made on family's atlas.
+ *
+ * ── Why not a map library ───────────────────────────────────────────────────
+ * Three reasons, and the first is not negotiable:
+ *
+ *  1. **The key can never reach the browser.** `GOOGLE_MAPS_API_KEY` is
+ *     restricted by API and NOT by HTTP referrer, so a Maps JavaScript API embed
+ *     — which requires the key in a script URL — would publish a credential
+ *     anybody could spend. The imagery is therefore proxied by this app's own
+ *     `/api/map`.
+ *  2. **It is cheaper.** A static render bills at roughly a third of a JS map
+ *     load, and identical viewports are shared between every viewer by the
+ *     server's cache.
+ *  3. **The overlay is the product.** What makes this a family atlas rather than
+ *     a map is that a dot is a person you can open, an arc is a journey somebody
+ *     made, and both are clickable, focusable and announced to a screen reader.
+ *     Those are our SVG elements either way; a tile engine underneath would only
+ *     add weight.
+ *
+ * ── 🔴 The alignment contract ───────────────────────────────────────────────
+ * The overlay is only correct if it uses the SAME projection as the imagery. It
+ * does — `shared/geo.ts` implements Google's own Web Mercator formula — and the
+ * two are locked together by:
+ *
+ *  · one FIXED logical viewport (`VIEW_WIDTH` × `VIEW_HEIGHT`) for both,
+ *  · `preserveAspectRatio="xMidYMid slice"` on the SVG, which now carries BOTH
+ *    layers (see "one coordinate system" below),
+ *  · the same `center` and integer `zoom` behind both.
+ *
+ * Break any one and every pin drifts from its coastline — more the further from
+ * the equator, which is exactly where this family's records are.
+ *
+ * ── 🔴 Why the imagery is an SVG `<image>` and not a sibling `<img>` ─────────
+ * It used to be a CSS-positioned `<img>` under the SVG, kept in step only by
+ * `object-fit: cover` matching `slice`. That is two coordinate systems agreeing
+ * by construction, which is fine while nothing MOVES — and stops being fine the
+ * moment a drag has to translate both by the same amount, because a viewport unit
+ * is not a CSS pixel and the conversion depends on the element's measured box.
+ * Putting the imagery inside the SVG makes the translation one number in one
+ * coordinate system, which is what makes the pan below correct rather than
+ * approximately correct.
+ *
+ * ── 🔴 The drag defect this file was rewritten for ──────────────────────────
+ * The owner's report, verbatim: *"Dragging on a map moves the nodes and paths
+ * while the map stays still and catches up after dropping."* Both halves of that
+ * were one cause. The old `onPointerMove` called `onViewChange` on EVERY move, so:
+ *
+ *  · the SVG overlay re-projected instantly — pins and arcs moved with the finger;
+ *  · the imagery is a NETWORK FETCH (`/api/map?lat=…&lng=…`), so it could only
+ *    appear once a round trip completed, one round trip per mouse move, arriving
+ *    long after the gesture. The map therefore lagged and "caught up" at the end.
+ *
+ * It was also **spending money on every mouse move**: each distinct center is a
+ * separate billable Google Static Maps render, so one drag across the atlas minted
+ * dozens of renders against the app's ceiling — for pictures nobody ever
+ * saw, because the next move superseded them.
+ *
+ * The fix is the one every map makes: a drag translates the WHOLE SCENE locally
+ * (`pan`, in viewport units, applied to imagery and overlay by a single
+ * `translate`), and the viewport is committed exactly ONCE, on release. So a drag
+ * is now one render rather than fifty, and the two layers cannot separate because
+ * neither one re-projects while the finger is down.
+ *
+ * ── …and why the released frame does not flash ──────────────────────────────
+ * Committing swaps `center`, which changes the image URL, which is a fetch. Naively
+ * that blanks the map for as long as the network takes — replacing a lag at the end
+ * of the drag with a hole at the end of the drag. So the frame keeps the imagery it
+ * has (`settled`) and DRAWS IT WHERE IT BELONGS in the new viewport: same math as
+ * a pin, applied to a picture. The old imagery slides out of frame, its blank edge
+ * follows the drag, and the new render replaces it when it lands. That is exactly
+ * what a tiled map does, without tiles.
+ *
+ * ── 🔴 Continuous gestures on top of an INTEGER-zoom imagery source ─────────
+ * The owner's second report: *"I wish zooming in and out was possible with mouse
+ * gestures… mobile should allow touch movements and zoom too."* The obvious fix —
+ * fetch a render per wheel tick — is the drag defect above wearing a different
+ * hat, and it bills for every frame.
+ *
+ * So a gesture runs entirely LOCALLY against a fractional zoom, and only the
+ * settled value is snapped and committed:
+ *
+ *  · `live` holds the viewport the reader is currently manipulating. Its zoom may
+ *    be 6.37; `project` and `imagePlacement` are both continuous, so the overlay
+ *    and the imagery scale together through the whole gesture with no fetch.
+ *  · the image URL is built from the PROPS — the last COMMITTED integer viewport —
+ *    so no amount of wheeling or pinching can mint a render.
+ *  · a wheel commits 220 ms after it stops; a pinch commits on release; a drag
+ *    commits when it comes to rest. One billable render per gesture, same as before.
+ *
+ * The zoom is anchored under the cursor (`zoomAnchoredAt`), not about the frame's
+ * center, which is the difference between closing in on a town and watching it
+ * slide off the edge as you approach it.
+ *
+ * ── 🔴 …and the fraction SURVIVES the commit (2026-09-11) ───────────────────
+ * The imagery takes an integer zoom, so a commit rounds — and a notch is only
+ * ~0.26 of a level. Every notch that fell outside the settle window therefore
+ * rounded itself away: measured against the counter in
+ * `@satellites/maps-platform`, six notches 260 ms apart committed six times and
+ * left the map at **exactly the zoom it started on**, and no number of trackpad
+ * flicks (whose deltas are a tenth of a notch) could zoom it at all.
+ *
+ * 🔴 That bug was also the only reason the slow path looked cheap — six commits
+ * rounding to one integer are six identical URLs, so five were cache hits. So the
+ * two belong together: `wheelLeftover` carries the discarded fraction into the
+ * next notch's TARGET (never into the viewport it is anchored against), and
+ * family's `FORGE/apps/family/src/components/wheelBilling.test.tsx` pins the gesture's cost and the fact that it moved in
+ * the same assertions. Repair one without the other and the atlas starts billing
+ * a render per notch, which is the defect this whole section exists to prevent.
+ *
+ * ── Degrading with no key ───────────────────────────────────────────────────
+ * With no imagery the frame draws a graticule and keeps every pin, arc and
+ * interaction working. A family atlas with no coastlines is still a diagram of
+ * who went where; refusing to draw would be worse.
+ */
+import React from "react";
+import {
+	type LatLng,
+	MAX_ZOOM,
+	MIN_ZOOM,
+	project,
+	scaleBar,
+	snapZoom,
+	unproject,
+	type Viewport,
+	zoomAnchoredAt,
+} from "./geo.js";
+
+/**
+ * The one logical viewport, for both layers.
+ *
+ * 640×400 because Google caps a single static render at 640px before `scale`, and
+ * a fixed size is what keeps the cache key space tiny — see `/api/map`. The frame
+ * is then CSS-scaled to whatever the layout gives it.
+ */
+export const VIEW_WIDTH = 640;
+export const VIEW_HEIGHT = 400;
+
+/**
+ * 🔴 How far the pointer must travel before this becomes a pan.
+ *
+ * The first version captured the pointer on `pointerdown`, which redirected a
+ * press on a PIN to the map — so the primary interaction of the whole screen
+ * (touch a dot to open the place) silently did nothing, while panning worked
+ * perfectly. Found by driving the live page in a browser; no unit test would
+ * have caught it, because both halves are individually correct.
+ *
+ * Six viewport units is above the tremor of a deliberate click and well below
+ * any intended drag.
+ */
+const PAN_THRESHOLD = 6;
+
+/**
+ * Wheel travel → zoom levels.
+ *
+ * A notched mouse wheel reports ~100 `deltaY` per click and a trackpad reports a
+ * stream of small ones, so a single constant has to serve both. 1/380 puts a
+ * mouse click at just over a quarter of a zoom level — four clicks to double the
+ * scale, which is deliberate: a wheel that jumped a whole level per notch is what
+ * makes people overshoot and then hunt.
+ */
+const ZOOM_PER_WHEEL_PIXEL = 1 / 380;
+
+/** How long after the last wheel event the viewport is committed — i.e. how long
+ *  after the reader stops before the sharp render is asked for. Long enough that
+ *  a multi-notch scroll is ONE render, short enough not to feel sticky.
+ *
+ *  🔴 Exported so a smoke (family's `__smoke/atlas.spec.ts`) can DERIVE its billing ceiling from it
+ *  rather than hard-coding a number that has to be loosened every time the Mac
+ *  gets busy. See that file — a gate whose constant drifts upward under load is
+ *  a gate that stops guarding the thing it was written for. */
+export const WHEEL_SETTLE_MS = 220;
+
+/**
+ * Momentum: how fast a flick decays, as the time constant of an exponential.
+ *
+ * 120 ms gives a glide of roughly a third of a second — enough that a flick
+ * crosses the Atlantic in one gesture, short enough that the map never feels like
+ * it is running away from the reader.
+ */
+const GLIDE_DECAY_MS = 120;
+
+/** Below this (viewport units per ms) a release was a stop, not a flick. */
+const GLIDE_MIN_VELOCITY = 0.02;
+
+const clampZoom = (zoom: number): number => Math.min(MAX_ZOOM, Math.max(MIN_ZOOM, zoom));
+
+/** The viewport whose imagery is currently on screen. Tracked separately from the
+ *  prop viewport because the two differ for exactly as long as a render is in
+ *  flight, and that gap is what the frame draws through instead of blanking. */
+interface SettledImage {
+	src: string;
+	center: LatLng;
+	zoom: number;
+}
+
+/** The URL of one rendered viewport. Pure, and exported so a test can name the
+ *  picture it expects without restating the query string. */
+export function mapImageSource(center: LatLng, zoom: number, theme: "light" | "dark"): string {
+	return (
+		`/api/map?lat=${center.lat.toFixed(4)}&lng=${center.lng.toFixed(4)}` +
+		`&z=${zoom}&w=${VIEW_WIDTH}&h=${VIEW_HEIGHT}&theme=${theme}`
+	);
+}
+
+/**
+ * Where a already-rendered viewport sits inside the one being drawn now.
+ *
+ * Pure, and the whole reason a committed pan does not flash: it is the same
+ * projection a pin gets, applied to a 640×400 picture. `scale` is the zoom
+ * difference (a double-click leaves a half-size image covering the middle of the
+ * frame until the closer render lands), and the position is the settled center
+ * projected into the current view, minus half the scaled picture.
+ */
+export function imagePlacement(
+	settled: { center: LatLng; zoom: number },
+	view: Viewport,
+): { x: number; y: number; width: number; height: number } {
+	const scale = 2 ** (view.zoom - settled.zoom);
+	const at = project(settled.center, view);
+	const width = VIEW_WIDTH * scale;
+	const height = VIEW_HEIGHT * scale;
+	return { x: at.x - width / 2, y: at.y - height / 2, width, height };
+}
+
+/**
+ * The viewport a completed drag lands on.
+ *
+ * Pure, because it is the one piece of the gesture worth pinning in a test: the
+ * center moves OPPOSITE the finger, through the projection, so a drag covers the
+ * same ground at every zoom.
+ */
+export function pannedCenter(
+	center: LatLng,
+	zoom: number,
+	pan: { dx: number; dy: number },
+): LatLng {
+	const view: Viewport = { center, zoom, width: VIEW_WIDTH, height: VIEW_HEIGHT };
+	const anchor = project(center, view);
+	return unproject({ x: anchor.x - pan.dx, y: anchor.y - pan.dy }, view);
+}
+
+/**
+ * Pure: the part of the logical viewport a `box` of that size actually shows. The SVG is
+ * `xMidYMid slice`, so a box narrower than 16:10 crops the sides and a wider one crops top and
+ * bottom — a consumer that fits pins to the whole 640×400 would put some of them out of sight on a
+ * phone. Fit to this instead (its `width`/`height` are `zoomToFit`'s size), and keep a label inside
+ * `x … x + width`. An unmeasured box (0×0) shows the whole viewport.
+ */
+export function visibleArea(box: { width: number; height: number }): { x: number; y: number; width: number; height: number } {
+	if (!(box.width > 0 && box.height > 0)) return { x: 0, y: 0, width: VIEW_WIDTH, height: VIEW_HEIGHT };
+	const scale = Math.max(box.width / VIEW_WIDTH, box.height / VIEW_HEIGHT);
+	const width = Math.min(VIEW_WIDTH, box.width / scale);
+	const height = Math.min(VIEW_HEIGHT, box.height / scale);
+	return { x: (VIEW_WIDTH - width) / 2, y: (VIEW_HEIGHT - height) / 2, width, height };
+}
+
+/** Any other attribute (`data-*`, `aria-describedby`, an `id`) lands on the frame's root `<div>`. */
+export interface MapFrameProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "children"> {
+	center: LatLng;
+	zoom: number;
+	theme: "light" | "dark";
+	/** Drawn inside the SVG, in viewport coordinates. Given `project` so children
+	 *  never re-derive the math. */
+	children: (helpers: {
+		project: (point: LatLng) => { x: number; y: number };
+		view: Viewport;
+	}) => React.ReactNode;
+	/** A completed drag or a double-click asks for a new viewport. Absent means the
+	 *  map is fixed — which is right for a thumbnail and wrong for the atlas.
+	 *
+	 *  🔴 Called ONCE per gesture, on release — never per pointer move. See the
+	 *  file header: a call here is a billable render. */
+	onViewChange?: (next: { center: LatLng; zoom: number }) => void;
+	/** Announced to assistive technology. The map is decorative without one. */
+	label: string;
+	/** The URL of one rendered viewport. Defaults to {@link mapImageSource} — the app's own
+	 *  `/api/map` proxy, which `cursedbelt-server/maps-static` serves the shared half of. */
+	imageSource?: (center: LatLng, zoom: number, theme: "light" | "dark") => string;
+}
+
+/*
+ * 🔴 Every style is INLINE, so an app mounts the frame with no stylesheet to import and no
+ * class to keep in step (family's `.ft-map*` rules were the frame's whole CSS). A consumer
+ * sizes the frame by sizing its container — the frame is 100% of it.
+ */
+const FRAME_STYLE: React.CSSProperties = {
+	position: "relative",
+	width: "100%",
+	height: "100%",
+	overflow: "hidden",
+	background: "var(--muted)",
+};
+const LAYER_STYLE: React.CSSProperties = { position: "absolute", inset: 0, width: "100%", height: "100%" };
+/** The render being fetched: it occupies no space and paints nothing. `display: none` would
+ *  stop some browsers fetching at all. */
+const PRELOAD_STYLE: React.CSSProperties = { position: "absolute", width: 1, height: 1, opacity: 0, pointerEvents: "none" };
+const IMAGE_STYLE = { userSelect: "none", WebkitUserDrag: "none" } as React.CSSProperties;
+
+export function MapFrame({
+	center,
+	zoom,
+	theme,
+	children,
+	onViewChange,
+	label,
+	className,
+	style,
+	imageSource = mapImageSource,
+	...rest
+}: MapFrameProps) {
+	/** Per instance: two frames on one page must not share one `<pattern>` id. */
+	const graticuleId = `cb-map-graticule-${React.useId().replace(/:/g, "")}`;
+	const svgRef = React.useRef<SVGSVGElement | null>(null);
+
+	/**
+	 * The viewport the reader is manipulating right now, fractional zoom and all.
+	 *
+	 * Null when nothing is in flight, and then the props ARE the viewport. Non-null
+	 * only between the first wheel notch (or the second finger) and the commit —
+	 * see the file header for why this cannot be allowed to reach the image URL.
+	 */
+	const [live, setLive] = React.useState<{ center: LatLng; zoom: number } | null>(null);
+	const effective = live ?? { center, zoom };
+	const view: Viewport = {
+		center: effective.center,
+		zoom: effective.zoom,
+		width: VIEW_WIDTH,
+		height: VIEW_HEIGHT,
+	};
+
+	/** 🔴 Built from the PROPS, never from `effective`. The committed viewport is
+	 *  the only one that is allowed to cost money. */
+	const source = imageSource(center, zoom, theme);
+
+	/** The imagery on screen, which is the last one that LOADED — not the one the
+	 *  props ask for. They differ only while a render is in flight. */
+	const [settled, setSettled] = React.useState<SettledImage | null>(null);
+	/** Sources that answered with an error. Keyed by URL rather than a boolean, so
+	 *  one 404 (a ceiling hit, a blip) cannot permanently blank every map in the
+	 *  session the way a sticky flag did — a different viewport is a different
+	 *  picture and deserves its own attempt. */
+	const [failed, setFailed] = React.useState<ReadonlySet<string>>(() => new Set());
+
+	/**
+	 * The live drag, in viewport units.
+	 *
+	 * State rather than a ref because the scene has to re-render as it moves; a ref
+	 * would translate nothing. The gesture's origin lives in `drag` (a ref, because
+	 * changing it must not re-render).
+	 */
+	const [pan, setPan] = React.useState<{ dx: number; dy: number } | null>(null);
+	const drag = React.useRef<{
+		pointerId: number;
+		startX: number;
+		startY: number;
+		/** Set once the pointer has moved far enough to BE a drag. Until then the
+		 *  gesture is still a click, and the pointer is deliberately not captured. */
+		panning: boolean;
+		/** The last few positions, for the flick velocity. Trimmed to the recent past
+		 *  so a slow drag that PAUSES before release glides nowhere, which is what
+		 *  "put it down here" should mean. */
+		samples: { x: number; y: number; at: number }[];
+	} | null>(null);
+
+	/** Every pointer currently on the frame. Two of them is a pinch; one is a drag.
+	 *  A ref because tracking a finger must not re-render. */
+	const pointers = React.useRef(new Map<number, { x: number; y: number }>());
+	/** The pinch in flight: the viewport it started from, so every frame is computed
+	 *  from the ORIGIN rather than accumulated from the last one (which drifts). */
+	const pinch = React.useRef<{
+		startDistance: number;
+		startMidpoint: { x: number; y: number };
+		startView: Viewport;
+	} | null>(null);
+
+	/** Mirrors `live` for the callbacks that fire outside a render — the wheel's
+	 *  settle timer and the glide's animation frames. */
+	const liveRef = React.useRef(live);
+	liveRef.current = live;
+	const committedRef = React.useRef({ center, zoom, onViewChange });
+	committedRef.current = { center, zoom, onViewChange };
+
+	const wheelTimer = React.useRef<ReturnType<typeof setTimeout> | null>(null);
+	const glide = React.useRef<number | null>(null);
+
+	/**
+	 * 🔴 The fraction the last commit ROUNDED AWAY, and what it rounded to.
+	 *
+	 * The imagery source takes an integer zoom (`/api/map` rounds it), so `commit`
+	 * snaps — and a notch is only ~0.26 of a level. A gesture whose notches land
+	 * inside one settle window accumulates in `live` and is fine; one whose notches
+	 * are further apart than `WHEEL_SETTLE_MS` commits each notch on its own, and
+	 * every one of those commits used to start again from the SNAPPED integer.
+	 *
+	 * Measured 2026-09-11, six notches driven through this component with the spend
+	 * counted at `@satellites/maps-platform`: at 260 ms apart the map committed six
+	 * times and ended at **exactly the zoom it started at**. A slow wheel could not
+	 * zoom, and a trackpad — whose deltas are a tenth of a notch and whose momentum
+	 * tail outlasts any fixed debounce — could not zoom at all.
+	 *
+	 * 🔴 That bug was also the only reason the slow path looked CHEAP: six commits
+	 * that all round to the same integer are six identical URLs, so five of them
+	 * were cache hits. Fix the zoom without this and the atlas silently starts
+	 * billing a render per notch — the exact defect the debounce exists to prevent.
+	 * So the fraction is carried, and family's `FORGE/apps/family/src/components/wheelBilling.test.tsx` pins both halves
+	 * together: the gesture must zoom AND it must cost one render.
+	 *
+	 * Only the WHEEL reads it. A drag, a pinch and a double-click all start from a
+	 * viewport the reader can see, and a double-click resuming from a hidden 0.4 of
+	 * a level would jump two levels from the one that is drawn.
+	 */
+	const carried = React.useRef<{ center: LatLng; fractional: number; snapped: number } | null>(
+		null,
+	);
+
+	/** The viewport a gesture is standing on right now, wherever it is being read
+	 *  from. Always prefers the live one — a wheel then a drag is one continuous
+	 *  interaction to the reader and must be one to the arithmetic. */
+	const readEffective = (): { center: LatLng; zoom: number } =>
+		liveRef.current ?? { center: committedRef.current.center, zoom: committedRef.current.zoom };
+
+	/**
+	 * How much of a zoom level the last commit rounded away — added to the TARGET
+	 * of the next notch, never to the viewport it is anchored against.
+	 *
+	 * 🔴 That split is the whole subtlety. The anchor (`zoomAnchoredAt`) has to be
+	 * computed against the viewport actually on screen, or the ground under the
+	 * cursor is unprojected at a scale nothing is drawn at and the point slides out
+	 * from under the pointer — worse at the edges, which is where somebody zooming
+	 * toward a town is aiming. So the fraction goes into where the notch is HEADED,
+	 * and the picture it starts from stays the one the reader can see.
+	 *
+	 * Zero while a gesture is live: `live` already holds the fraction then.
+	 *
+	 * It counts only when the props are still EXACTLY what we handed up, which is
+	 * what makes it safe — a parent that moved the map itself (a deep link, a
+	 * cluster click, a fly-to) fails the comparison and the props win, so a stale
+	 * fraction can never shadow somebody else's viewport.
+	 */
+	const wheelLeftover = (): number => {
+		if (liveRef.current) return 0;
+		const held = carried.current;
+		if (!held) return 0;
+		const committed = committedRef.current;
+		const ours =
+			held.snapped === committed.zoom &&
+			held.center.lat === committed.center.lat &&
+			held.center.lng === committed.center.lng;
+		return ours ? held.fractional - held.snapped : 0;
+	};
+
+	const stopGlide = (): void => {
+		if (glide.current !== null) cancelAnimationFrame(glide.current);
+		glide.current = null;
+	};
+
+	/**
+	 * Hand a settled viewport up, and drop every local override in the same tick.
+	 *
+	 * Both halves matter. Committing without clearing `live` leaves the gesture's
+	 * fractional zoom permanently shadowing the props; clearing without committing
+	 * springs the map back to where the gesture started.
+	 */
+	const commit = (next: { center: LatLng; zoom: number }): void => {
+		setLive(null);
+		liveRef.current = null;
+		setPan(null);
+		const snapped = snapZoom(next.zoom);
+		// Keep the fraction `snapped` just discarded, so the next wheel notch resumes
+		// where this gesture actually ended rather than at the rounded integer — see
+		// `carried` above for the measurement that made this necessary.
+		carried.current = { center: next.center, fractional: next.zoom, snapped };
+		committedRef.current.onViewChange?.({ center: next.center, zoom: snapped });
+	};
+
+	// Takes the base mouse shape rather than `React.PointerEvent`, because a
+	// double-click and a native wheel event arrive as MouseEvents and need the same
+	// arithmetic.
+	const toViewportUnits = (event: {
+		clientX: number;
+		clientY: number;
+	}): { x: number; y: number } | null => {
+		const svg = svgRef.current;
+		if (!svg) return null;
+		const box = svg.getBoundingClientRect();
+		if (box.width === 0 || box.height === 0) return null;
+		// `slice` scales by the LARGER ratio and centers the overflow, so undoing it
+		// needs the same scale in both axes plus the centering offset.
+		const scale = Math.max(box.width / VIEW_WIDTH, box.height / VIEW_HEIGHT);
+		return {
+			x: (event.clientX - box.left - (box.width - VIEW_WIDTH * scale) / 2) / scale,
+			y: (event.clientY - box.top - (box.height - VIEW_HEIGHT * scale) / 2) / scale,
+		};
+	};
+
+	/**
+	 * 🔴 The wheel is bound by hand, non-passive, and it has to be.
+	 *
+	 * React registers `onWheel` at the root as a PASSIVE listener, so
+	 * `event.preventDefault()` inside a JSX `onWheel` prop is silently ignored and
+	 * the page scrolls behind the map while the map also zooms. A native listener
+	 * with `{ passive: false }` is the only way to own the gesture. Bound once and
+	 * kept — every value it reads comes from a ref, so it can never go stale.
+	 */
+	// biome-ignore lint/correctness/useExhaustiveDependencies: bound exactly once, on purpose. Everything the handler reads lives in a ref (`committedRef`, `liveRef`) or is a stable setter, so re-binding per render would only churn listeners — and re-binding mid-gesture would drop the wheel the reader is in the middle of.
+	React.useEffect(() => {
+		const svg = svgRef.current;
+		if (!svg) return;
+		const onWheel = (event: WheelEvent): void => {
+			if (!committedRef.current.onViewChange) return;
+			event.preventDefault();
+			stopGlide();
+			const point = toViewportUnits(event);
+			if (!point) return;
+			// `deltaMode` 1 is lines and 2 is pages — Firefox reports lines for a
+			// notched wheel, so a raw deltaY would zoom ~15× too slowly there.
+			const lines = event.deltaMode === 1 ? 16 : event.deltaMode === 2 ? VIEW_HEIGHT : 1;
+			// Anchored against what is DRAWN…
+			const from = readEffective();
+			const startView: Viewport = {
+				center: from.center,
+				zoom: from.zoom,
+				width: VIEW_WIDTH,
+				height: VIEW_HEIGHT,
+			};
+			// …and aimed from where the last gesture actually ended, so notches spaced
+			// further apart than the settle still accumulate instead of each rounding
+			// back to the integer they started on. See `wheelLeftover`.
+			const base = from.zoom + wheelLeftover();
+			const next = clampZoom(base - event.deltaY * lines * ZOOM_PER_WHEEL_PIXEL);
+			if (next === base) return;
+			const moved = { center: zoomAnchoredAt(startView, point, next), zoom: next };
+			liveRef.current = moved;
+			setLive(moved);
+
+			if (wheelTimer.current) clearTimeout(wheelTimer.current);
+			wheelTimer.current = setTimeout(() => {
+				wheelTimer.current = null;
+				const settledView = liveRef.current;
+				if (settledView) commit(settledView);
+			}, WHEEL_SETTLE_MS);
+		};
+		svg.addEventListener("wheel", onWheel, { passive: false });
+		return () => svg.removeEventListener("wheel", onWheel);
+	}, []);
+
+	// Nothing should outlive the component: a pending settle would commit a
+	// viewport into an unmounted parent, and a running glide would leak a frame
+	// loop for as long as the tab is open.
+	React.useEffect(
+		() => () => {
+			if (wheelTimer.current) clearTimeout(wheelTimer.current);
+			if (glide.current !== null) cancelAnimationFrame(glide.current);
+		},
+		[],
+	);
+
+	/**
+	 * The flick.
+	 *
+	 * A released drag keeps moving and decays exponentially, then commits ONCE when
+	 * it comes to rest — so momentum costs the same single render a plain drag does.
+	 * Readers who have asked for less motion get the plain drag.
+	 */
+	const startGlide = (from: { dx: number; dy: number }, velocity: { vx: number; vy: number }) => {
+		const base = readEffective();
+		const settle = (offset: { dx: number; dy: number }): void => {
+			commit({ center: pannedCenter(base.center, base.zoom, offset), zoom: base.zoom });
+		};
+		const speed = Math.hypot(velocity.vx, velocity.vy);
+		const reduced =
+			typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
+		if (speed < GLIDE_MIN_VELOCITY || reduced) {
+			settle(from);
+			return;
+		}
+
+		let offset = from;
+		let vx = velocity.vx;
+		let vy = velocity.vy;
+		let last = performance.now();
+		const step = (now: number): void => {
+			// Clamped: a backgrounded tab hands back one enormous delta, which would
+			// teleport the map on return.
+			const elapsed = Math.min(48, now - last);
+			last = now;
+			offset = { dx: offset.dx + vx * elapsed, dy: offset.dy + vy * elapsed };
+			const decay = Math.exp(-elapsed / GLIDE_DECAY_MS);
+			vx *= decay;
+			vy *= decay;
+			setPan(offset);
+			if (Math.hypot(vx, vy) > GLIDE_MIN_VELOCITY / 4) {
+				glide.current = requestAnimationFrame(step);
+				return;
+			}
+			glide.current = null;
+			settle(offset);
+		};
+		glide.current = requestAnimationFrame(step);
+	};
+
+	/**
+	 * Release the drag and let it come to rest on a viewport.
+	 *
+	 * Committing here (or at the end of the glide this may hand off to) and nowhere
+	 * else is the whole fix — see the header. A gesture that never crossed
+	 * `PAN_THRESHOLD` was a click and commits nothing.
+	 */
+	const endDrag = (element: Element | null, pointerId: number): void => {
+		const state = drag.current;
+		drag.current = null;
+		const offset = pan;
+		if (element?.hasPointerCapture?.(pointerId)) element.releasePointerCapture(pointerId);
+		if (!state?.panning || !offset || !committedRef.current.onViewChange) {
+			setPan(null);
+			return;
+		}
+		if (offset.dx === 0 && offset.dy === 0) {
+			setPan(null);
+			return;
+		}
+		// Velocity from the recent samples only. A drag that stalled before release
+		// has none, and gliding it anyway is the "it kept going after I stopped"
+		// complaint every over-eager momentum implementation earns.
+		const recent = state.samples.filter((sample) => performance.now() - sample.at < 90);
+		const first = recent[0];
+		const last = recent[recent.length - 1];
+		const span = first && last ? last.at - first.at : 0;
+		const velocity =
+			first && last && span > 8
+				? { vx: (last.x - first.x) / span, vy: (last.y - first.y) / span }
+				: { vx: 0, vy: 0 };
+		startGlide(offset, velocity);
+	};
+
+	/** A pointer has gone away — from a release, a cancel, or leaving the window. */
+	const dropPointer = (element: Element | null, pointerId: number): void => {
+		pointers.current.delete(pointerId);
+		if (pinch.current) {
+			// The pinch ends the moment it stops being two fingers, and where it ends
+			// is where it stays — a one-finger remainder must not silently become a
+			// drag from a position nobody put their finger on.
+			if (pointers.current.size < 2) {
+				pinch.current = null;
+				drag.current = null;
+				const settledView = liveRef.current;
+				if (settledView) commit(settledView);
+			}
+			if (element?.hasPointerCapture?.(pointerId)) element.releasePointerCapture(pointerId);
+			return;
+		}
+		endDrag(element, pointerId);
+	};
+
+	const placement = settled ? imagePlacement(settled, view) : null;
+	const loading = source !== settled?.src && !failed.has(source);
+
+	return (
+		<div {...rest} className={className} style={style ? { ...FRAME_STYLE, ...style } : FRAME_STYLE} data-map-frame="" data-interactive={Boolean(onViewChange)}>
+			{/*
+			 * The render currently being fetched, off-screen.
+			 *
+			 * A real element rather than `new Image()` so the browser's own decoding,
+			 * priority and cache behavior apply, and so a test can drive `load` and
+			 * `error` without stubbing a global. It never paints; the SVG `<image>`
+			 * below is what the reader sees, and it only ever points at bytes that
+			 * have already arrived.
+			 */}
+			{loading ? (
+				<img
+					key={source}
+					src={source}
+					alt=""
+					aria-hidden="true"
+					style={PRELOAD_STYLE}
+					draggable={false}
+					data-testid="map-preload"
+					onLoad={() => setSettled({ src: source, center, zoom })}
+					onError={() => setFailed((current) => new Set(current).add(source))}
+				/>
+			) : null}
+
+			<svg
+				ref={svgRef}
+				style={{
+					...LAYER_STYLE,
+					...(onViewChange ? { cursor: pan ? "grabbing" : "grab", touchAction: "none" } : {}),
+				}}
+				viewBox={`0 0 ${VIEW_WIDTH} ${VIEW_HEIGHT}`}
+				preserveAspectRatio="xMidYMid slice"
+				role="img"
+				aria-label={label}
+				data-panning={pan ? "true" : "false"}
+				onPointerDown={(event) => {
+					if (!onViewChange) return;
+					// A wheel-and-then-grab is one interaction: land the wheel's viewport
+					// before the hand takes over, or the drag starts from a stale origin.
+					stopGlide();
+					const point = toViewportUnits(event);
+					if (!point) return;
+					// Touch and pen have no buttons worth filtering; a mouse has three and
+					// only the primary one pans.
+					if (event.pointerType === "mouse" && event.button !== 0) return;
+					pointers.current.set(event.pointerId, point);
+
+					if (pointers.current.size === 2) {
+						// A second finger converts whatever was happening into a pinch. Any
+						// drag offset already on screen is folded into the live center first,
+						// so the map does not jump back the instant the finger lands.
+						const from = readEffective();
+						const base = pan
+							? { center: pannedCenter(from.center, from.zoom, pan), zoom: from.zoom }
+							: from;
+						setPan(null);
+						drag.current = null;
+						const [a, b] = [...pointers.current.values()];
+						if (!a || !b) return;
+						const startView: Viewport = {
+							center: base.center,
+							zoom: base.zoom,
+							width: VIEW_WIDTH,
+							height: VIEW_HEIGHT,
+						};
+						pinch.current = {
+							startDistance: Math.max(1, Math.hypot(b.x - a.x, b.y - a.y)),
+							startMidpoint: { x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 },
+							startView,
+						};
+						liveRef.current = base;
+						setLive(base);
+						event.currentTarget.setPointerCapture(event.pointerId);
+						return;
+					}
+					if (pointers.current.size > 2) return;
+
+					// Recorded, but NOT captured — see PAN_THRESHOLD. Capturing here is
+					// what stole every click on a pin.
+					drag.current = {
+						pointerId: event.pointerId,
+						startX: point.x,
+						startY: point.y,
+						panning: false,
+						samples: [{ x: point.x, y: point.y, at: performance.now() }],
+					};
+				}}
+				onPointerMove={(event) => {
+					if (!onViewChange) return;
+					const point = toViewportUnits(event);
+					if (!point) return;
+					if (pointers.current.has(event.pointerId)) pointers.current.set(event.pointerId, point);
+
+					const pinching = pinch.current;
+					if (pinching) {
+						if (pointers.current.size < 2) return;
+						const [a, b] = [...pointers.current.values()];
+						if (!a || !b) return;
+						const distance = Math.max(1, Math.hypot(b.x - a.x, b.y - a.y));
+						const midpoint = { x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 };
+						// Computed from the pinch's ORIGIN every frame rather than from the
+						// previous frame: accumulating ratios drifts, and a drifting pinch
+						// ends somewhere the fingers never asked for.
+						const next = clampZoom(
+							pinching.startView.zoom + Math.log2(distance / pinching.startDistance),
+						);
+						const moved = {
+							center: zoomAnchoredAt(pinching.startView, pinching.startMidpoint, next, midpoint),
+							zoom: next,
+						};
+						liveRef.current = moved;
+						setLive(moved);
+						return;
+					}
+
+					const state = drag.current;
+					if (!state || state.pointerId !== event.pointerId) return;
+					const dx = point.x - state.startX;
+					const dy = point.y - state.startY;
+					state.samples.push({ x: dx, y: dy, at: performance.now() });
+					if (state.samples.length > 8) state.samples.shift();
+					if (!state.panning) {
+						if (Math.hypot(dx, dy) < PAN_THRESHOLD) return;
+						// NOW it is a drag: take the pointer so it survives leaving the
+						// frame, which is exactly when you are trying to pan.
+						state.panning = true;
+						event.currentTarget.setPointerCapture(event.pointerId);
+					}
+					// 🔴 LOCAL only. The viewport is committed on release; see the header.
+					setPan({ dx, dy });
+				}}
+				onPointerUp={(event) => dropPointer(event.currentTarget, event.pointerId)}
+				onPointerCancel={(event) => {
+					// A canceled gesture is not a pan — drop the offset without
+					// committing, so the scene springs back rather than half-moving.
+					pointers.current.delete(event.pointerId);
+					pinch.current = null;
+					drag.current = null;
+					setPan(null);
+					if (event.currentTarget.hasPointerCapture?.(event.pointerId)) {
+						event.currentTarget.releasePointerCapture(event.pointerId);
+					}
+				}}
+				onDoubleClick={(event) => {
+					if (!onViewChange) return;
+					stopGlide();
+					const point = toViewportUnits(event);
+					if (!point) return;
+					// Zoom toward the point under the cursor — held exactly still, rather
+					// than the old halfway-to-the-center approximation, which drifted the
+					// target away by more the further from the middle you aimed. Shift
+					// reverses it, which is the convention every map shares.
+					const from = readEffective();
+					const next = snapZoom(from.zoom + (event.shiftKey ? -1 : 1));
+					if (next === from.zoom) return;
+					const startView: Viewport = {
+						center: from.center,
+						zoom: from.zoom,
+						width: VIEW_WIDTH,
+						height: VIEW_HEIGHT,
+					};
+					commit({ center: zoomAnchoredAt(startView, point, next), zoom: next });
+				}}
+			>
+				{/*
+				 * ONE translate for the whole scene. Imagery and overlay are siblings
+				 * inside it, so they physically cannot separate during a drag — which is
+				 * the property the owner's report was about.
+				 */}
+				<g transform={pan ? `translate(${pan.dx} ${pan.dy})` : undefined}>
+					{placement ? (
+						<image
+							href={settled?.src}
+							x={placement.x}
+							y={placement.y}
+							width={placement.width}
+							height={placement.height}
+							preserveAspectRatio="none"
+							style={IMAGE_STYLE}
+							data-testid="map-image"
+						/>
+					) : (
+						// No imagery yet (or the render failed): the graticule, so the frame
+						// reads as a map rather than as a broken picture. Drawn oversized so
+						// a drag does not expose an edge before the render lands.
+						<>
+							<defs>
+								<pattern id={graticuleId} width={40} height={40} patternUnits="userSpaceOnUse">
+									<path
+										d="M40 0 L0 0 0 40"
+										fill="none"
+										stroke="color-mix(in oklab, var(--border) 60%, transparent)"
+										strokeWidth={1}
+									/>
+								</pattern>
+							</defs>
+							<rect
+								x={-VIEW_WIDTH}
+								y={-VIEW_HEIGHT}
+								width={VIEW_WIDTH * 3}
+								height={VIEW_HEIGHT * 3}
+								fill="var(--muted)"
+								data-testid="map-fallback"
+							/>
+							{/* The grid itself. No `aria-hidden`: the whole SVG is one
+							    `role="img"` with a label, so nothing inside it is announced
+							    separately and marking a child hidden only confuses the tree. */}
+							<rect
+								x={-VIEW_WIDTH}
+								y={-VIEW_HEIGHT}
+								width={VIEW_WIDTH * 3}
+								height={VIEW_HEIGHT * 3}
+								fill={`url(#${graticuleId})`}
+							/>
+						</>
+					)}
+					{children({ project: (point) => project(point, view), view })}
+				</g>
+				<ScaleKey view={view} />
+			</svg>
+		</div>
+	);
+}
+
+/**
+ * The distance key — "5 mi · 8 km" under a bar of exactly that length.
+ *
+ * ── 🔴 OUTSIDE the panning `<g>`, on purpose ────────────────────────────────
+ * A drag translates the whole scene, and a scale bar that slid off the corner
+ * with it would be the one mark on this map that is not about a place. The zoom
+ * does not change during a pan, so the bar is correct throughout without moving.
+ *
+ * ── 🔴 Every color is an INLINE style, and that is a budget decision ────────
+ * `apps/family`'s entry stylesheet had 89 bytes of headroom when the tree wires
+ * landed, and `.ft-map*` lived in its global sheet because the dossier's
+ * birthplace thumbnail draws it — so a handful of new rules here would land on
+ * the first-paint route with no lazier route to push them into. Presentation
+ * attributes reading the theme's own tokens cost the stylesheet nothing.
+ *
+ * It is `aria-hidden`: the whole SVG is one `role="img"` with a label, so a
+ * child announced separately only clutters the tree — the rule the graticule
+ * comment already states.
+ */
+/** About how wide one character of the 12-unit label runs, so the plate holds a label longer than its bar. */
+const LABEL_EM = 6.6;
+
+function ScaleKey({ view }: { view: Viewport }) {
+	const bar = scaleBar(view);
+	// A frame too small (or a zoom too far out) for even the smallest step of the
+	// 1/2/5 series draws nothing rather than a bar labeled with a fraction.
+	if (bar.widthUnits <= 0) return null;
+	const left = 12;
+	const bottom = VIEW_HEIGHT - 12;
+	return (
+		/*
+		 * 🔴 No `aria-hidden`, and the graticule's comment beside it says why: the
+		 * whole SVG is ONE `role="img"` with a label, so nothing inside it is
+		 * announced separately and marking a child hidden only adds a node to the
+		 * tree that says so. Biome's `noAriaHiddenOnFocusable` flags it as well,
+		 * which is the same finding from the other direction.
+		 */
+		<g data-testid="map-scale">
+			{/* A dark plate under the mark, because the imagery underneath is a
+			    photograph and a hairline over a bright field is unreadable. */}
+			<rect
+				x={left - 5}
+				y={bottom - 22}
+				width={Math.max(bar.widthUnits, bar.label.length * LABEL_EM) + 10}
+				height={28}
+				rx={4}
+				fill="var(--card)"
+				opacity={0.78}
+			/>
+			<path
+				d={`M${left} ${bottom - 5} v5 h${bar.widthUnits} v-5`}
+				fill="none"
+				stroke="var(--foreground)"
+				strokeWidth={1.5}
+			/>
+			<text
+				x={left}
+				y={bottom - 8}
+				fontSize={12}
+				fill="var(--foreground)"
+			>
+				{bar.label}
+			</text>
+		</g>
+	);
+}