cursedbelt 5.93.0 → 5.95.0

package/dist/react/map-frame/MapFrame.d.ts

@@ -0,0 +1,219 @@
+/**
+ * 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, type Viewport } 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 declare const VIEW_WIDTH = 640;
+export declare const VIEW_HEIGHT = 400;
+/** 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 declare const WHEEL_SETTLE_MS = 220;
+/** The URL of one rendered viewport. Pure, and exported so a test can name the
+ *  picture it expects without restating the query string. */
+export declare function mapImageSource(center: LatLng, zoom: number, theme: "light" | "dark"): string;
+/**
+ * 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 declare function imagePlacement(settled: {
+    center: LatLng;
+    zoom: number;
+}, view: Viewport): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/**
+ * 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 declare function pannedCenter(center: LatLng, zoom: number, pan: {
+    dx: number;
+    dy: number;
+}): LatLng;
+/**
+ * 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 declare function visibleArea(box: {
+    width: number;
+    height: number;
+}): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/** 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;
+}
+export declare function MapFrame({ center, zoom, theme, children, onViewChange, label, className, style, imageSource, ...rest }: MapFrameProps): React.JSX.Element;
+//# sourceMappingURL=MapFrame.d.ts.map

package/dist/react/map-frame/MapFrame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MapFrame.d.ts","sourceRoot":"","sources":["../../../src/react/map-frame/MapFrame.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuHG;AACH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EACN,KAAK,MAAM,EAOX,KAAK,QAAQ,EAEb,MAAM,UAAU,CAAC;AAElB;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,MAAM,CAAC;AAC9B,eAAO,MAAM,WAAW,MAAM,CAAC;AA2B/B;;;;;;;+DAO+D;AAC/D,eAAO,MAAM,eAAe,MAAM,CAAC;AAyBnC;6DAC6D;AAC7D,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAK5F;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC7B,OAAO,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EACzC,IAAI,EAAE,QAAQ,GACZ;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAMzD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC3B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC7B,MAAM,CAIR;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAM3H;AAED,qGAAqG;AACrG,MAAM,WAAW,aAAc,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,UAAU,CAAC;IAC5F,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC;IACxB;oCACgC;IAChC,QAAQ,EAAE,CAAC,OAAO,EAAE;QACnB,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QACrD,IAAI,EAAE,QAAQ,CAAC;KACf,KAAK,KAAK,CAAC,SAAS,CAAC;IACtB;;;;yDAIqD;IACrD,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAChE,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd;6FACyF;IACzF,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,KAAK,MAAM,CAAC;CAChF;AAoBD,wBAAgB,QAAQ,CAAC,EACxB,MAAM,EACN,IAAI,EACJ,KAAK,EACL,QAAQ,EACR,YAAY,EACZ,KAAK,EACL,SAAS,EACT,KAAK,EACL,WAA4B,EAC5B,GAAG,IAAI,EACP,EAAE,aAAa,qBA2jBf"}