cursedbelt 5.92.3 → 5.94.0

package/dist/react/map-frame/MapFrame.js

@@ -0,0 +1,726 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * 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 { MAX_ZOOM, MIN_ZOOM, project, scaleBar, snapZoom, unproject, 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) => Math.min(MAX_ZOOM, Math.max(MIN_ZOOM, zoom));
+/** 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, zoom, theme) {
+    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, view) {
+    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, zoom, pan) {
+    const view = { 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) {
+    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 };
+}
+/*
+ * 🔴 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 = {
+    position: "relative",
+    width: "100%",
+    height: "100%",
+    overflow: "hidden",
+    background: "var(--muted)",
+};
+const LAYER_STYLE = { 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 = { position: "absolute", width: 1, height: 1, opacity: 0, pointerEvents: "none" };
+const IMAGE_STYLE = { userSelect: "none", WebkitUserDrag: "none" };
+export function MapFrame({ center, zoom, theme, children, onViewChange, label, className, style, imageSource = mapImageSource, ...rest }) {
+    /** 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(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(null);
+    const effective = live ?? { center, zoom };
+    const view = {
+        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(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(() => 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(null);
+    const drag = React.useRef(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());
+    /** 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(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(null);
+    const glide = React.useRef(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(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 = () => 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 = () => {
+        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 = () => {
+        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) => {
+        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) => {
+        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) => {
+            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 = {
+                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, velocity) => {
+        const base = readEffective();
+        const settle = (offset) => {
+            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) => {
+            // 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, pointerId) => {
+        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, pointerId) => {
+        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 (_jsxs("div", { ...rest, className: className, style: style ? { ...FRAME_STYLE, ...style } : FRAME_STYLE, "data-map-frame": "", "data-interactive": Boolean(onViewChange), children: [loading ? (_jsx("img", { 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)) }, source)) : null, _jsxs("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 = {
+                            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 = {
+                        center: from.center,
+                        zoom: from.zoom,
+                        width: VIEW_WIDTH,
+                        height: VIEW_HEIGHT,
+                    };
+                    commit({ center: zoomAnchoredAt(startView, point, next), zoom: next });
+                }, children: [_jsxs("g", { transform: pan ? `translate(${pan.dx} ${pan.dy})` : undefined, children: [placement ? (_jsx("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" })) : (_jsxs(_Fragment, { children: [_jsx("defs", { children: _jsx("pattern", { id: graticuleId, width: 40, height: 40, patternUnits: "userSpaceOnUse", children: _jsx("path", { d: "M40 0 L0 0 0 40", fill: "none", stroke: "color-mix(in oklab, var(--border) 60%, transparent)", strokeWidth: 1 }) }) }), _jsx("rect", { x: -VIEW_WIDTH, y: -VIEW_HEIGHT, width: VIEW_WIDTH * 3, height: VIEW_HEIGHT * 3, fill: "var(--muted)", "data-testid": "map-fallback" }), _jsx("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 })] }), _jsx(ScaleKey, { view: view })] })] }));
+}
+/**
+ * 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 }) {
+    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 (_jsxs("g", { "data-testid": "map-scale", children: [_jsx("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 }), _jsx("path", { d: `M${left} ${bottom - 5} v5 h${bar.widthUnits} v-5`, fill: "none", stroke: "var(--foreground)", strokeWidth: 1.5 }), _jsx("text", { x: left, y: bottom - 8, fontSize: 12, fill: "var(--foreground)", children: bar.label })] }));
+}
+//# sourceMappingURL=MapFrame.js.map