@bitbaum/geo-kit 0.1.2 → 0.3.0

package/dist/map/controller.js

@@ -0,0 +1,375 @@
+import { WORLD_LIMITS, clampTilt, clampZoom, disc, projectionFor, wrapLon, cameraFor } from "./camera.js";
+import { coast, dragged, flight } from "./motion.js";
+import { groupFills, paintMap } from "./paint.js";
+import { pickAt, pickIndex } from "./pick.js";
+const IDLE_BEFORE_TURNING = 4000;
+const STOP_TURNING_AFTER = 120_000;
+const TURN_PER_MS = 0.004; // degrees: a full turn in about 90 seconds
+/** How long the disc takes to follow its view to a new place. */
+const FOLLOW_MS = 280;
+/** Past this a press is a drag, not a tap. */
+const TAP_SLOP = 6;
+const reducedMotion = () => typeof window !== "undefined" && window.matchMedia?.("(prefers-reduced-motion: reduce)").matches === true;
+const pixelRatio = () => Math.min(window.devicePixelRatio || 1, 2);
+const lerp = (a, b, t) => a + (b - a) * t;
+export function createMap(canvas, options) {
+    const limits = options.limits ?? WORLD_LIMITS;
+    const home = options.home ?? { center: [30, 18], k: 1 };
+    let shapes = options.shapes;
+    let index = pickIndex(shapes.features);
+    let fills = options.fills ?? new Map();
+    let paint = { palette: options.palette, groups: groupFills(shapes.features, fills, options.palette.land) };
+    let camera = home;
+    let size = { w: 0, h: 0 };
+    let shown = null;
+    let motion = {};
+    let touched = 0;
+    let hover = null;
+    let selected = null;
+    let grabbed = false;
+    let raf = 0;
+    let wake = 0;
+    let last = 0;
+    let destroyed = false;
+    const viewAt = (now) => {
+        if (!shown)
+            return null;
+        const t = Math.min((now - shown.start) / FOLLOW_MS, 1);
+        if (t >= 1)
+            return shown.to;
+        const e = 1 - (1 - t) ** 3;
+        const s = shown;
+        const at = (k) => lerp(s.from[k], s.to[k], e);
+        return { x0: at("x0"), y0: at("y0"), x1: at("x1"), y1: at("y1") };
+    };
+    const projection = (now = performance.now()) => {
+        const view = viewAt(now);
+        return view ? projectionFor(view, camera) : null;
+    };
+    const radius = () => {
+        const view = viewAt(performance.now());
+        return view ? disc(view).radius : 200;
+    };
+    const feature = (id) => {
+        const i = id === null ? undefined : shapes.index.get(id);
+        return i === undefined ? undefined : shapes.features[i];
+    };
+    /** Advance whatever is moving; true while another frame is needed. */
+    const advance = (now, dt) => {
+        if (motion.flight) {
+            const t = (now - motion.flight.start) / motion.flight.f.duration;
+            camera = motion.flight.f.at(t);
+            if (t < 1)
+                return true;
+            motion.flight = undefined;
+            return false;
+        }
+        if (motion.spin) {
+            const step = coast(camera, motion.spin, dt, radius(), limits);
+            camera = step.camera;
+            motion.spin = step.spin;
+            return !!step.spin;
+        }
+        if (!options.idleTurn || selected || camera.k > 1.3 || options.holdStill?.() || reducedMotion())
+            return false;
+        const idle = now - touched;
+        if (idle > IDLE_BEFORE_TURNING && idle < STOP_TURNING_AFTER) {
+            camera = { ...camera, center: [wrapLon(camera.center[0] + TURN_PER_MS * dt), camera.center[1]] };
+            return true;
+        }
+        if (idle <= IDLE_BEFORE_TURNING) {
+            // Nothing to draw until the turn may start: wake then, not every frame.
+            window.clearTimeout(wake);
+            wake = window.setTimeout(invalidate, IDLE_BEFORE_TURNING - idle + 20);
+        }
+        return false;
+    };
+    const tick = (now) => {
+        raf = 0;
+        if (destroyed)
+            return;
+        const dt = Math.min(now - (last || now), 64);
+        last = now;
+        const moving = advance(now, dt) || grabbed;
+        let again = moving;
+        if (shown && now - shown.start < FOLLOW_MS)
+            again = true;
+        if (options.animating?.(now))
+            again = true;
+        const ctx = canvas.getContext("2d");
+        const proj = projection(now);
+        if (ctx && proj && size.w > 0) {
+            const dpr = pixelRatio();
+            ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+            const flightAt = motion.flight ? (now - motion.flight.start) / motion.flight.f.duration : null;
+            paintMap(ctx, size, proj, moving ? shapes.coarse : shapes, paint, { hover: feature(hover), selected: feature(selected) }, options.over
+                ? (c, basis, p) => options.over(c, basis, p, { now, flight: flightAt, moving, sinceTouch: now - touched })
+                : undefined);
+        }
+        if (again)
+            raf = requestAnimationFrame(tick);
+        else
+            last = 0;
+    };
+    function invalidate() {
+        if (!raf && !destroyed)
+            raf = requestAnimationFrame(tick);
+    }
+    const flyTo = (to, duration) => {
+        const target = { center: [wrapLon(to.center[0]), clampTilt(to.center[1], limits)], k: clampZoom(to.k, limits) };
+        motion = {};
+        touched = performance.now();
+        if (reducedMotion())
+            camera = target;
+        else {
+            const f = flight(camera, target, limits);
+            motion.flight = { f: duration ? { ...f, duration } : f, start: performance.now() };
+        }
+        invalidate();
+    };
+    const grab = () => {
+        motion = {};
+        touched = performance.now();
+    };
+    const scale = (factor) => {
+        camera = { ...camera, k: clampZoom(camera.k * factor, limits) };
+        invalidate();
+    };
+    const zoomBy = (factor) => {
+        if (factor === "home")
+            flyTo(home);
+        else
+            flyTo({ ...camera, k: camera.k * factor }, 260);
+    };
+    const pick = (x, y) => {
+        const proj = projection();
+        return proj ? pickAt(index, proj, x, y) : null;
+    };
+    const choose = (id) => options.onSelect?.(id);
+    const takenFirst = (x, y, kind) => {
+        const proj = projection();
+        return !!proj && !!options.pickFirst?.(x, y, proj, kind);
+    };
+    const facing = () => {
+        const view = viewAt(performance.now());
+        if (!view)
+            return null;
+        const d = disc(view);
+        return pick(d.cx, d.cy)?.id ?? null;
+    };
+    /* ------------------------------------------------------------ input */
+    const pointers = new Map();
+    let gesture = { moved: false, vx: 0, vy: 0, t: 0, startX: 0, startY: 0 };
+    const local = (e) => {
+        const box = canvas.getBoundingClientRect();
+        return { x: e.clientX - box.left, y: e.clientY - box.top };
+    };
+    const on = {
+        keydown(e) {
+            const step = e.shiftKey ? 30 : 10;
+            const perStep = step / Math.max(camera.k, 1);
+            const turn = (dLon, dLat) => {
+                motion = {};
+                touched = performance.now();
+                camera = {
+                    center: [wrapLon(camera.center[0] + dLon * perStep), clampTilt(camera.center[1] + dLat * perStep, limits)],
+                    k: camera.k,
+                };
+                invalidate();
+                options.onFacing?.(facing());
+            };
+            const keys = {
+                ArrowLeft: () => turn(-1, 0),
+                ArrowRight: () => turn(1, 0),
+                ArrowUp: () => turn(0, 1),
+                ArrowDown: () => turn(0, -1),
+                "+": () => zoomBy(1.5),
+                "=": () => zoomBy(1.5),
+                "-": () => zoomBy(1 / 1.5),
+                "0": () => zoomBy("home"),
+                Home: () => zoomBy("home"),
+                Enter: () => choose(facing()),
+            };
+            const run = keys[e.key];
+            if (!run)
+                return;
+            e.preventDefault();
+            run();
+        },
+        pointerdown(e) {
+            if (e.pointerType === "mouse" && e.button !== 0)
+                return;
+            try {
+                canvas.setPointerCapture(e.pointerId);
+            }
+            catch {
+                // An untrusted or already-lifted pointer cannot be captured; the drag works without.
+            }
+            const at = local(e);
+            pointers.set(e.pointerId, at);
+            if (pointers.size === 1)
+                gesture = { moved: false, vx: 0, vy: 0, t: e.timeStamp, startX: at.x, startY: at.y };
+            else
+                gesture.moved = true; // a second finger is never a tap
+            grab();
+            grabbed = true;
+            if (hover !== null) {
+                hover = null;
+                options.onHover?.(null, at.x, at.y);
+            }
+        },
+        pointermove(e) {
+            const at = local(e);
+            const before = pointers.get(e.pointerId);
+            if (!before) {
+                if (e.pointerType === "mouse") {
+                    touched = performance.now();
+                    const taken = takenFirst(at.x, at.y, "hover");
+                    const id = taken ? null : (pick(at.x, at.y)?.id ?? null);
+                    canvas.style.cursor = taken || id ? "pointer" : "";
+                    if (id !== hover) {
+                        hover = id;
+                        invalidate();
+                    }
+                    // The caller's own layer answered this point; its hover is its own to show.
+                    if (!taken)
+                        options.onHover?.(id, at.x, at.y);
+                }
+                return;
+            }
+            const g = gesture;
+            if (pointers.size === 1) {
+                if (Math.hypot(at.x - g.startX, at.y - g.startY) > TAP_SLOP)
+                    g.moved = true;
+                if (g.moved) {
+                    const dx = at.x - before.x;
+                    const dy = at.y - before.y;
+                    camera = dragged(camera, dx, dy, radius(), limits);
+                    invalidate();
+                    const dt = Math.max(e.timeStamp - g.t, 1);
+                    // Smoothed velocity in px/ms, for the coast after release.
+                    g.vx = g.vx * 0.6 + (dx / dt) * 0.4;
+                    g.vy = g.vy * 0.6 + (dy / dt) * 0.4;
+                    g.t = e.timeStamp;
+                }
+            }
+            else if (pointers.size === 2) {
+                const other = [...pointers.entries()].find(([id]) => id !== e.pointerId)?.[1];
+                if (other) {
+                    const d0 = Math.hypot(before.x - other.x, before.y - other.y);
+                    const d1 = Math.hypot(at.x - other.x, at.y - other.y);
+                    if (d0 > 0)
+                        scale(d1 / d0);
+                }
+            }
+            pointers.set(e.pointerId, at);
+        },
+        pointerup(e) {
+            if (!pointers.delete(e.pointerId) || pointers.size > 0)
+                return;
+            grabbed = false;
+            invalidate();
+            const g = gesture;
+            if (!g.moved) {
+                const at = local(e);
+                if (!takenFirst(at.x, at.y, "tap"))
+                    choose(pick(at.x, at.y)?.id ?? null);
+                return;
+            }
+            const fresh = e.timeStamp - g.t < 80;
+            if (fresh && !reducedMotion() && Math.hypot(g.vx, g.vy) > 0.05) {
+                motion.spin = { vx: g.vx, vy: g.vy };
+                invalidate();
+            }
+        },
+        pointercancel(e) {
+            pointers.delete(e.pointerId);
+            if (pointers.size === 0) {
+                grabbed = false;
+                invalidate();
+            }
+        },
+        pointerleave(e) {
+            if (e.pointerType !== "mouse" || hover === null)
+                return;
+            hover = null;
+            canvas.style.cursor = "";
+            options.onHover?.(null, 0, 0);
+            invalidate();
+        },
+    };
+    const wheel = (e) => {
+        e.preventDefault();
+        const px = e.deltaMode === 1 ? e.deltaY * 16 : e.deltaY;
+        grab();
+        scale(Math.exp(-px * 0.0018));
+    };
+    const listeners = Object.entries(on).map(([type, fn]) => [type, fn]);
+    for (const [type, fn] of listeners)
+        canvas.addEventListener(type, fn);
+    canvas.addEventListener("wheel", wheel, { passive: false });
+    canvas.style.touchAction = "none";
+    if (!canvas.hasAttribute("tabindex"))
+        canvas.tabIndex = 0;
+    return {
+        resize(width, height, view) {
+            const dpr = pixelRatio();
+            const w = Math.round(width * dpr);
+            const h = Math.round(height * dpr);
+            if (canvas.width !== w || canvas.height !== h) {
+                canvas.width = w;
+                canvas.height = h;
+            }
+            size = { w: width, h: height };
+            const to = view ?? { x0: 0, y0: 0, x1: width, y1: height };
+            const now = performance.now();
+            const from = viewAt(now);
+            shown = from && !reducedMotion() ? { from, to, start: now } : { from: to, to, start: 0 };
+            invalidate();
+        },
+        setShapes(next) {
+            shapes = next;
+            index = pickIndex(shapes.features);
+            paint = { palette: paint.palette, groups: groupFills(shapes.features, fills, paint.palette.land) };
+            invalidate();
+        },
+        setFills(next) {
+            fills = next;
+            paint = { ...paint, groups: groupFills(shapes.features, fills, paint.palette.land) };
+            invalidate();
+        },
+        setPalette(palette) {
+            paint = { palette, groups: groupFills(shapes.features, fills, palette.land) };
+            invalidate();
+        },
+        setSelected(id, { fly = false } = {}) {
+            selected = id;
+            const f = feature(id);
+            const to = f && fly ? cameraFor(f.geometry, limits, options.focusZoom) : null;
+            if (to)
+                flyTo(to);
+            else
+                invalidate();
+        },
+        flyTo,
+        jumpTo(to) {
+            motion = {};
+            touched = performance.now();
+            camera = { center: [wrapLon(to.center[0]), clampTilt(to.center[1], limits)], k: clampZoom(to.k, limits) };
+            invalidate();
+        },
+        zoomBy,
+        camera: () => camera,
+        projection: () => projection(),
+        invalidate,
+        destroy() {
+            destroyed = true;
+            cancelAnimationFrame(raf);
+            raf = 0;
+            window.clearTimeout(wake);
+            for (const [type, fn] of listeners)
+                canvas.removeEventListener(type, fn);
+            canvas.removeEventListener("wheel", wheel);
+        },
+    };
+}

package/dist/map/cull.d.ts

@@ -0,0 +1,28 @@
+/**
+ * What is on the far side of the globe need not be drawn. Each country and
+ * each border line carries a cap — the smallest circle on the sphere, around
+ * its centre, that holds every vertex — and a frame streams only the ones
+ * whose cap reaches over the horizon. Half the world is skipped at rest, far
+ * more when zoomed in. Pure, so the horizon maths is tested.
+ */
+import { type GeoPermissibleObjects, type GeoProjection } from "d3-geo";
+export interface Cap {
+    center: [number, number];
+    /** Degrees from the centre to the farthest vertex. */
+    reach: number;
+}
+export declare function capOf(shape: GeoPermissibleObjects & {
+    coordinates: unknown;
+}): Cap;
+/**
+ * How far from the centre of view, in degrees, anything can still be seen on
+ * this canvas: the hemisphere when the whole disc fits, less when the globe
+ * is zoomed past the canvas edges.
+ */
+export declare function horizonOf(proj: GeoProjection, size: {
+    w: number;
+    h: number;
+}): number;
+/** The point of the Earth at the centre of an orthographic projection. */
+export declare function centreOf(proj: GeoProjection): [number, number];
+export declare function visible(cap: Cap, centre: [number, number], horizon: number): boolean;

package/dist/map/cull.js

@@ -0,0 +1,46 @@
+/**
+ * What is on the far side of the globe need not be drawn. Each country and
+ * each border line carries a cap — the smallest circle on the sphere, around
+ * its centre, that holds every vertex — and a frame streams only the ones
+ * whose cap reaches over the horizon. Half the world is skipped at rest, far
+ * more when zoomed in. Pure, so the horizon maths is tested.
+ */
+import { geoCentroid, geoDistance } from "d3-geo";
+const DEG = 180 / Math.PI;
+function eachPosition(coords, fn) {
+    if (!Array.isArray(coords))
+        return;
+    if (typeof coords[0] === "number")
+        return fn(coords);
+    for (const c of coords)
+        eachPosition(c, fn);
+}
+export function capOf(shape) {
+    const [lon, lat] = geoCentroid(shape);
+    const center = Number.isFinite(lon) ? [lon, lat] : [0, 0];
+    let reach = 0;
+    eachPosition(shape.coordinates, (p) => {
+        reach = Math.max(reach, geoDistance(center, [p[0] ?? 0, p[1] ?? 0]));
+    });
+    // A shape whose centroid is meaningless (a ring around a pole) is never culled.
+    return { center, reach: Number.isFinite(lon) ? reach * DEG : 180 };
+}
+/**
+ * How far from the centre of view, in degrees, anything can still be seen on
+ * this canvas: the hemisphere when the whole disc fits, less when the globe
+ * is zoomed past the canvas edges.
+ */
+export function horizonOf(proj, size) {
+    const [cx, cy] = proj.translate();
+    const r = proj.scale();
+    const far = Math.max(Math.hypot(cx, cy), Math.hypot(size.w - cx, cy), Math.hypot(cx, size.h - cy), Math.hypot(size.w - cx, size.h - cy));
+    return far >= r ? 90 : Math.asin(far / r) * DEG;
+}
+/** The point of the Earth at the centre of an orthographic projection. */
+export function centreOf(proj) {
+    const [l, p] = proj.rotate();
+    return [-l, -p];
+}
+export function visible(cap, centre, horizon) {
+    return geoDistance(centre, cap.center) * DEG - cap.reach < horizon + 1;
+}

package/dist/map/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `@bitbaum/geo-kit/map`: the renderer for the geography the main entry
+ * delivers. An orthographic globe on Canvas 2D (d3-geo), which zoomed in is a
+ * flat map of the place in front of the reader, so the world and a commune are
+ * one projection. Framework-free: `createMap` takes a canvas; the pure parts
+ * (camera, motion, culling, picking, the fast projection) are exported for
+ * tests and overlays. Needs the optional peers `d3-geo` and, for TopoJSON,
+ * `topojson-client`.
+ */
+export { WORLD_LIMITS, cameraFor, cameraForBounds, clampTilt, clampZoom, disc, focusOf, mainland, projectionFor, rotationOf, wrapLon, zoomFor, type Camera, type Focus, type Limits, type View, } from "./camera.ts";
+export { createMap, type FrameInfo, type MapController, type MapOptions } from "./controller.ts";
+export { capOf, centreOf, horizonOf, visible, type Cap } from "./cull.ts";
+export { coast, dragged, flight, type Flight, type Spin } from "./motion.ts";
+export { fade, groupFills, paintMap, type DrawOver, type Fill, type Marks, type Paint, type Palette } from "./paint.ts";
+export { pickAt, pickIndex, type Pickable } from "./pick.ts";
+export { coarsened, polygonsOf, rewound, shapesFromFeatures, shapesFromTopology, shapesOf, type MapFeature, type MapShapes, type Shapes, type TopologyOptions, } from "./shapes.ts";
+export { basisOf, pack, project, traceLine, traceRing, type Basis, type Packed } from "./trace.ts";

package/dist/map/index.js

@@ -0,0 +1,17 @@
+/**
+ * `@bitbaum/geo-kit/map`: the renderer for the geography the main entry
+ * delivers. An orthographic globe on Canvas 2D (d3-geo), which zoomed in is a
+ * flat map of the place in front of the reader, so the world and a commune are
+ * one projection. Framework-free: `createMap` takes a canvas; the pure parts
+ * (camera, motion, culling, picking, the fast projection) are exported for
+ * tests and overlays. Needs the optional peers `d3-geo` and, for TopoJSON,
+ * `topojson-client`.
+ */
+export { WORLD_LIMITS, cameraFor, cameraForBounds, clampTilt, clampZoom, disc, focusOf, mainland, projectionFor, rotationOf, wrapLon, zoomFor, } from "./camera.js";
+export { createMap } from "./controller.js";
+export { capOf, centreOf, horizonOf, visible } from "./cull.js";
+export { coast, dragged, flight } from "./motion.js";
+export { fade, groupFills, paintMap } from "./paint.js";
+export { pickAt, pickIndex } from "./pick.js";
+export { coarsened, polygonsOf, rewound, shapesFromFeatures, shapesFromTopology, shapesOf, } from "./shapes.js";
+export { basisOf, pack, project, traceLine, traceRing } from "./trace.js";

package/dist/map/motion.d.ts

@@ -0,0 +1,29 @@
+import { type Camera, type Limits } from "./camera.ts";
+/**
+ * Turning the globe by a drag of (dx, dy) pixels: the land under the finger
+ * follows it at the centre of the disc, whatever the zoom. North stays up.
+ */
+export declare function dragged(camera: Camera, dx: number, dy: number, radius: number, limits?: Limits): Camera;
+export interface Flight {
+    at: (t: number) => Camera;
+    /** Milliseconds: longer the farther it turns, never a slog. */
+    duration: number;
+}
+/**
+ * From one view to another along the great circle (the short way round, so
+ * Fiji to Samoa crosses the date line instead of circling the globe), pulling
+ * back mid-way on a long turn so the reader sees where they are going. The
+ * zoom moves on a log scale, so a flight from the world to a commune does not
+ * spend its first half barely zooming.
+ */
+export declare function flight(from: Camera, to: Camera, limits?: Limits): Flight;
+/** A flick: px/ms along each axis, carried on after the finger lifts. */
+export interface Spin {
+    vx: number;
+    vy: number;
+}
+/** One frame of coasting: turn by the velocity, then let it decay. */
+export declare function coast(camera: Camera, spin: Spin, dt: number, radius: number, limits?: Limits): {
+    camera: Camera;
+    spin?: Spin;
+};

package/dist/map/motion.js

@@ -0,0 +1,58 @@
+/**
+ * How the map moves, pure so it can be tested: a drag turns it, a flight
+ * carries it from one view to another the short way round, and a flick keeps
+ * it turning for a moment after release.
+ */
+import { geoDistance, geoInterpolate } from "d3-geo";
+import { WORLD_LIMITS, clampTilt, wrapLon } from "./camera.js";
+/**
+ * Turning the globe by a drag of (dx, dy) pixels: the land under the finger
+ * follows it at the centre of the disc, whatever the zoom. North stays up.
+ */
+export function dragged(camera, dx, dy, radius, limits = WORLD_LIMITS) {
+    const perPixel = 180 / (Math.PI * radius * camera.k);
+    // Near the poles a pixel is more longitude; ease it so a drag there does not whip.
+    const lonScale = 1 / Math.max(Math.cos((camera.center[1] * Math.PI) / 180), 0.35);
+    return {
+        center: [
+            wrapLon(camera.center[0] - dx * perPixel * Math.min(lonScale, 2)),
+            clampTilt(camera.center[1] + dy * perPixel, limits),
+        ],
+        k: camera.k,
+    };
+}
+const ease = (t) => (t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2);
+/**
+ * From one view to another along the great circle (the short way round, so
+ * Fiji to Samoa crosses the date line instead of circling the globe), pulling
+ * back mid-way on a long turn so the reader sees where they are going. The
+ * zoom moves on a log scale, so a flight from the world to a commune does not
+ * spend its first half barely zooming.
+ */
+export function flight(from, to, limits = WORLD_LIMITS) {
+    const arc = (geoDistance(from.center, to.center) * 180) / Math.PI;
+    const along = geoInterpolate(from.center, to.center);
+    const pull = Math.min(Math.max((arc - 30) / 150, 0), 0.45);
+    const lk0 = Math.log(from.k);
+    const lk1 = Math.log(to.k);
+    return {
+        duration: Math.round(450 + Math.min(arc, 180) * 4 + Math.min(Math.abs(lk1 - lk0), 6) * 60),
+        at(t) {
+            const e = ease(Math.min(Math.max(t, 0), 1));
+            const [lon = 0, lat = 0] = along(e);
+            const k = Math.exp(lk0 + (lk1 - lk0) * e);
+            const dip = 1 - pull * Math.sin(Math.PI * e);
+            return {
+                center: [wrapLon(lon), clampTilt(lat, limits)],
+                k: Math.max(k * dip, limits.minZoom),
+            };
+        },
+    };
+}
+/** One frame of coasting: turn by the velocity, then let it decay. */
+export function coast(camera, spin, dt, radius, limits = WORLD_LIMITS) {
+    const next = dragged(camera, spin.vx * dt, spin.vy * dt, radius, limits);
+    const decay = Math.exp(-dt / 325);
+    const left = { vx: spin.vx * decay, vy: spin.vy * decay };
+    return { camera: next, spin: Math.hypot(left.vx, left.vy) < 0.01 ? undefined : left };
+}

package/dist/map/paint.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Painting the map on a canvas: the fills grouped so each colour is one path,
+ * and one frame drawn: atmosphere and lit sphere, graticule, land, borders,
+ * limb shade, the hover and selection outlines, then whatever the caller
+ * draws over it (sites, routes, figures). Every layer but the land and its
+ * borders is optional, so the same painter draws a lit globe of the world and
+ * a plain map of communes where the data is the picture.
+ */
+import { type GeoProjection } from "d3-geo";
+import type { MapFeature, Shapes } from "./shapes.ts";
+import { type Basis } from "./trace.ts";
+export type Fill = string | CanvasPattern;
+export interface Palette {
+    /** The sea, or the page under a map with no base. */
+    sphere: string;
+    /** The sphere's lit side; absent paints it flat. */
+    sphereLight?: string;
+    /** Absent draws no graticule. */
+    graticule?: string;
+    /** A feature with no fill of its own. */
+    land: string;
+    border: string;
+    hover: string;
+    selected: string;
+    /** A glow past the limb, [inner, outer]; absent draws none. */
+    glow?: [string, string];
+    /** Shade toward the limb, [inner, outer]; absent draws none. */
+    limb?: [string, string];
+    /** Border width in CSS pixels (default 0.6). */
+    borderWidth?: number;
+}
+/**
+ * Any CSS colour at an alpha, for gradients that fade without greying. The
+ * canvas normalises the colour first: a build may minify `#000000` to `#000`,
+ * and a token could as well be `rgb()`.
+ */
+export declare function fade(colour: string, a: number): string;
+/**
+ * The fills as one entry per colour, in the order the caller's map first
+ * names each colour, then the features with no fill: a path per colour, not
+ * per feature. As indexes, so the full and the coarse shapes share it.
+ */
+export declare function groupFills(features: readonly MapFeature<unknown>[], fills: ReadonlyMap<string, Fill>, land: Fill): [Fill, number[]][];
+interface Backdrop {
+    key: string;
+    under: HTMLCanvasElement;
+    over: HTMLCanvasElement;
+}
+/** What a frame needs that outlives it: the palette, the fill groups, the cached backdrop. */
+export interface Paint {
+    palette: Palette;
+    groups: [Fill, number[]][];
+    backdrop?: Backdrop;
+}
+export interface Marks<P = Record<string, unknown>> {
+    hover?: MapFeature<P>;
+    selected?: MapFeature<P>;
+}
+/** What the caller draws over the map, in CSS pixels, with the frame's basis. */
+export type DrawOver = (ctx: CanvasRenderingContext2D, basis: Basis, projection: GeoProjection) => void;
+/** One frame, in CSS pixels (the caller has set the device-pixel transform). */
+export declare function paintMap<P>(ctx: CanvasRenderingContext2D, size: {
+    w: number;
+    h: number;
+}, proj: GeoProjection, shapes: Shapes<P>, paint: Paint, marks?: Marks<P>, over?: DrawOver): void;
+export {};