@sjvair/map-sdk 0.1.0-beta.1 → 0.1.0-beta.10

package/dist/core/create-map.svelte.js

@@ -3,10 +3,11 @@ import { SvelteMap } from "svelte/reactivity";
 import { createDefaultFormat } from "../data/format.js";
 import { defaultMessages } from "../data/messages.js";
 import { createDefaultMetadata } from "../data/metadata.js";
-import { applyPick, selectionKeys } from "../data/selection.js";
+import { applyPick, selectionKeys, toggleInSelection } from "../data/selection.js";
 import { BasemapState } from "./basemap.svelte.js";
 import { InteractionRouter } from "./interactions.svelte.js";
 import { PluginHost } from "./plugin-host.svelte.js";
+import { intersectsBounds, shapeAnchor } from "./shape-view.js";
 /** Monitor-map's start view. */
 const DEFAULT_VIEW = {
     center: [-119.7987626619462, 36.76272050981146],
@@ -19,6 +20,8 @@ class PluginSelection {
     mode = $state("none");
     selection = $state.raw(null);
     onselectionchange;
+    pickWith = $state("click");
+    canSelect;
 }
 function copyView(view) {
     return { ...view, center: [view.center[0], view.center[1]] };
@@ -36,6 +39,7 @@ function sameSelection(a, b) {
         return a === b;
     return (a.kind === b.kind && a.ids.length === b.ids.length && a.ids.every((id, i) => id === b.ids[i]));
 }
+const inRect = (p, b) => p[0] >= b.west && p[0] <= b.east && p[1] >= b.south && p[1] <= b.north;
 function prefersReducedMotion() {
     return globalThis.matchMedia?.("(prefers-reduced-motion: reduce)").matches ?? false;
 }
@@ -50,9 +54,16 @@ class MapContextImpl {
     #bounds = $state.raw(null);
     #attached = $state(false);
     #ready = $state(false);
+    /** `markReady` came while plugin setups were queued; the queued run sets `ready`. */
+    #readyRequested = false;
     #glState = $state.raw(null);
     #focusedKey = $state(null);
     #focusedPluginId = $state(null);
+    #focusedAnchor = $state.raw(null);
+    #pinned = $state.raw(null);
+    #notice = $state.raw(null);
+    #noticeCount = 0;
+    #cardEnabled = false;
     #selections = new SvelteMap();
     #featureClickHandlers = new Set();
     #router = new InteractionRouter();
@@ -61,6 +72,11 @@ class MapContextImpl {
     #destroyed = false;
     #listInset = 0;
     #listInsetSide = "left";
+    /** An animated ease that `focusFeature` started is still running (cleared on `moveend`). */
+    #focusEasing = false;
+    #onMoveEnd = () => {
+        this.#focusEasing = false;
+    };
     constructor(options) {
         const initialView = copyView(options.config.initialView ?? DEFAULT_VIEW);
         this.config = {
@@ -77,9 +93,18 @@ class MapContextImpl {
             mapUid: this.uid,
             providers: { metadata: this.metadata, messages: this.messages, format: this.format },
             router: this.#router,
-            selectedKeys: (pluginId) => selectionKeys(this.getSelection(pluginId))
+            selectedKeys: (pluginId) => selectionKeys(this.getSelection(pluginId)),
+            onSettled: () => {
+                // A setup that added a plugin queued another run; that run settles it.
+                if (this.#host.pending)
+                    return;
+                if (this.#readyRequested && this.#gl)
+                    this.#ready = true;
+                this.#readyRequested = false;
+            }
         });
         this.#router.onPick((e) => this.#pick(e));
+        this.#router.onMiss(() => this.unpin());
     }
     get camera() {
         return this.#camera;
@@ -100,7 +125,11 @@ class MapContextImpl {
         return this.#glState;
     }
     markReady() {
-        if (this.#gl)
+        if (!this.#gl)
+            return;
+        if (this.#host.pending)
+            this.#readyRequested = true;
+        else
             this.#ready = true;
     }
     get focusedKey() {
@@ -109,9 +138,39 @@ class MapContextImpl {
     get focusedPluginId() {
         return this.#focusedPluginId;
     }
+    get focusedAnchor() {
+        return this.#focusedAnchor;
+    }
     get hovered() {
         return this.#router.hovered;
     }
+    get pinned() {
+        return this.#pinned;
+    }
+    get notice() {
+        return this.#notice;
+    }
+    clearNotice() {
+        if (untrack(() => this.#notice) !== null)
+            this.#notice = null;
+    }
+    getPickWith(pluginId) {
+        return this.#selections.get(pluginId)?.pickWith ?? "click";
+    }
+    togglePick(pluginId, ref) {
+        if (this.#destroyed)
+            return;
+        this.#applyPick(pluginId, ref, { toggle: true });
+    }
+    unpin() {
+        if (untrack(() => this.#pinned) !== null)
+            this.#pinned = null;
+    }
+    setCardEnabled(on) {
+        this.#cardEnabled = on;
+        if (!on)
+            this.unpin();
+    }
     addPlugin(plugin, options = {}) {
         this.#assertAlive();
         const previous = untrack(() => this.#selections.get(plugin.id));
@@ -125,6 +184,10 @@ class MapContextImpl {
                     : (previous?.selection ?? null);
         });
         state.onselectionchange = options.onselectionchange ?? previous?.onselectionchange;
+        untrack(() => {
+            state.pickWith = options.pickWith ?? previous?.pickWith ?? "click";
+        });
+        state.canSelect = options.canSelect ?? previous?.canSelect;
         // Stored before the host adds it, so a setup that runs at once sees its selection.
         this.#selections.set(plugin.id, state);
         try {
@@ -146,6 +209,8 @@ class MapContextImpl {
     removePlugin(id) {
         this.#host.remove(id);
         this.#selections.delete(id);
+        if (untrack(() => this.#pinned)?.hit.pluginId === id)
+            this.unpin();
     }
     setSelection(pluginId, selection) {
         if (this.#destroyed)
@@ -164,9 +229,15 @@ class MapContextImpl {
         const found = untrack(() => this.#findItem(refKey, pluginId));
         if (!found)
             return;
-        this.#emitClick(pluginId, found.item.ref, found.item.lngLat);
-        if (found.item.selectable)
-            this.#applyPick(pluginId, found.item.ref, additive);
+        const { item } = found;
+        // Where the row's tooltip pins: the focused anchor for the focused row, else a point of a
+        // shape in view (a point's own position for points and on-screen label points).
+        const focused = untrack(() => this.#focusedKey) === refKey &&
+            (untrack(() => this.#focusedPluginId) ?? pluginId) === pluginId;
+        const anchor = (focused && untrack(() => this.#focusedAnchor)) || this.anchorFor(item);
+        this.#emitClick(pluginId, item.ref, anchor);
+        if (item.selectable)
+            this.#applyPick(pluginId, item.ref, { additive, modifier: additive });
     }
     clearSelection(pluginId) {
         if (this.#destroyed)
@@ -211,19 +282,107 @@ class MapContextImpl {
             return;
         this.#focusedKey = refKey;
         this.#focusedPluginId = refKey === null ? null : (pluginId ?? null);
+        this.#focusedAnchor = null;
         const gl = this.#gl;
         if (!gl || refKey === null)
             return;
         const found = untrack(() => this.#findItem(refKey, pluginId));
         if (!found)
             return;
+        const { plugin, item } = found;
+        const place = this.#placeFor(item, gl);
+        this.#focusedAnchor = place.anchor;
+        if (this.#cardEnabled) {
+            this.#pinned = {
+                hit: { pluginId: plugin.id, ref: item.ref, refKey: item.refKey, name: item.name },
+                lngLat: place.anchor
+            };
+        }
+        if (!place.pan) {
+            // Stays where it is now: an earlier focus's ease that is still running stops here.
+            // With nothing running, no move at all.
+            if (this.#focusEasing) {
+                const { lng, lat } = gl.getCenter();
+                gl.easeTo({ center: [lng, lat], duration: 0 });
+                this.#focusEasing = false;
+            }
+            return;
+        }
+        const reduce = prefersReducedMotion();
         gl.easeTo({
-            center: found.item.lngLat,
+            center: place.anchor,
             // The middle of the part the panel leaves clear. An offset, not padding: MapLibre keeps
             // padding for later moves (zooms, the reported center), an offset applies to this one.
             ...(this.#listInset > 0 && { offset: [this.#listOffsetX(), 0] }),
-            ...(prefersReducedMotion() && { duration: 0 })
+            ...(reduce && { duration: 0 })
         });
+        // Set after the call: stopping an earlier move fires its `moveend` inside `easeTo`.
+        this.#focusEasing = !reduce;
+    }
+    anchorFor(item) {
+        const gl = this.#gl;
+        if (!gl || !item.geometry)
+            return item.lngLat;
+        const { live, clear, liveCenter, clearCenter } = this.#views(gl);
+        if (inRect(item.lngLat, live) || !intersectsBounds(item, live))
+            return item.lngLat;
+        return (shapeAnchor(item.geometry, clear, clearCenter) ??
+            shapeAnchor(item.geometry, live, liveCenter) ??
+            item.lngLat);
+    }
+    /** The live view, and the part of it the list panel leaves clear, with their centers. */
+    #views(gl) {
+        const b = gl.getBounds();
+        const live = {
+            west: b.getWest(),
+            south: b.getSouth(),
+            east: b.getEast(),
+            north: b.getNorth()
+        };
+        const center = gl.getCenter();
+        const width = untrack(() => gl.getCanvas().clientWidth) || 0;
+        const share = width > 0 ? Math.min(Math.max(this.#listInset / width, 0), 0.99) : 0;
+        const cut = share * (live.east - live.west);
+        const clear = this.#listInsetSide === "left"
+            ? { ...live, west: live.west + cut }
+            : { ...live, east: live.east - cut };
+        return {
+            live,
+            clear,
+            liveCenter: [center.lng, center.lat],
+            clearCenter: [(clear.west + clear.east) / 2, center.lat]
+        };
+    }
+    /**
+     * Where focus puts `item`: `pan: false` keeps the camera (a shape in view whose `lngLat` is
+     * off-screen, with a point in the clear part); otherwise ease to center `anchor`.
+     */
+    #placeFor(item, gl) {
+        const { geometry, lngLat } = item;
+        if (!geometry)
+            return { anchor: lngLat, pan: true };
+        const { live, clear, liveCenter, clearCenter } = this.#views(gl);
+        if (inRect(lngLat, live))
+            return { anchor: lngLat, pan: true };
+        if (intersectsBounds(item, live)) {
+            const inClear = shapeAnchor(geometry, clear, clearCenter);
+            if (inClear)
+                return { anchor: inClear, pan: false };
+            const inLive = shapeAnchor(geometry, live, liveCenter);
+            if (inLive)
+                return { anchor: inLive, pan: true };
+        }
+        const settled = untrack(() => this.#bounds);
+        if (settled && intersectsBounds(item, settled)) {
+            const middle = [
+                (settled.west + settled.east) / 2,
+                (settled.south + settled.north) / 2
+            ];
+            const inSettled = shapeAnchor(geometry, settled, middle);
+            if (inSettled)
+                return { anchor: inSettled, pan: true };
+        }
+        return { anchor: lngLat, pan: true };
     }
     #cameraOptions(target, gl) {
         const zoom = target.zoom ??
@@ -267,8 +426,12 @@ class MapContextImpl {
         this.#glState = gl;
         this.#host.attach(gl);
         this.#router.attach(gl);
-        this.basemap.attach(gl, () => this.#host.restyle(), () => {
+        gl.on("moveend", this.#onMoveEnd);
+        this.basemap.attach(gl, 
+        // Called from style.load: the style is loaded, though its tiles may not be.
+        () => this.#host.restyle(true), () => {
             this.#ready = false;
+            this.#readyRequested = false;
             this.#host.suspend();
         });
         this.#attached = true;
@@ -276,6 +439,10 @@ class MapContextImpl {
     detach() {
         if (!this.#gl)
             return;
+        this.#gl.off("moveend", this.#onMoveEnd);
+        this.#focusEasing = false;
+        this.unpin();
+        this.clearNotice();
         this.#router.detach();
         this.basemap.detach();
         this.#host.detach();
@@ -283,6 +450,7 @@ class MapContextImpl {
         this.#glState = null;
         this.#attached = false;
         this.#ready = false;
+        this.#readyRequested = false;
     }
     themeChanged() {
         if (this.#gl)
@@ -310,15 +478,29 @@ class MapContextImpl {
         this.#featureClickHandlers.clear();
         this.#focusedKey = null;
         this.#focusedPluginId = null;
+        this.#focusedAnchor = null;
         this.#destroyed = true;
     }
     /** A click on a feature: report it, then apply it to the top hit's plugin's selection. */
     #pick(e) {
         if (this.#destroyed)
             return;
-        const [{ pluginId, ref }] = e.hits;
+        const [hit] = e.hits;
+        const { pluginId, ref } = hit;
+        // A box-zoom Shift-click only counts for a plugin that asked for modifier picks.
+        if (e.boxZoom && untrack(() => this.#selections.get(pluginId)?.pickWith) !== "modifier") {
+            return;
+        }
         this.#emitClick(pluginId, ref, e.lngLat);
-        this.#applyPick(pluginId, ref, e.additive);
+        this.#applyPick(pluginId, ref, { additive: e.additive, modifier: e.modifier });
+        if (!this.#cardEnabled || this.#destroyed)
+            return;
+        // A feature with no hover card (e.g. a smoke plume) gets no pinned card either.
+        const plugin = untrack(() => this.plugins).find((p) => p.id === pluginId);
+        if (!plugin || plugin.hoverable === false)
+            this.unpin();
+        else
+            this.#pinned = { hit, lngLat: e.lngLat };
     }
     #emitClick(pluginId, ref, lngLat) {
         for (const handler of [...this.#featureClickHandlers]) {
@@ -331,15 +513,48 @@ class MapContextImpl {
         }
     }
     /** The one place a user's pick (map click or list key) changes a plugin's selection. */
-    #applyPick(pluginId, ref, additive) {
+    /**
+     * The one place a user's pick (map click, list key, or the card's toggle) changes a plugin's
+     * selection: the plugin's `pickWith` rule, then its `canSelect`.
+     */
+    #applyPick(pluginId, ref, gesture) {
         // A featureclick handler may have removed the plugin.
         const state = untrack(() => this.#selections.get(pluginId));
         if (!state)
             return;
         const current = untrack(() => state.selection);
-        const next = applyPick(current, ref, untrack(() => state.mode), { additive });
-        if (sameSelection(current, next))
+        const mode = untrack(() => state.mode);
+        let next;
+        if (gesture.toggle)
+            next = toggleInSelection(current, ref, mode);
+        else if (untrack(() => state.pickWith) === "modifier") {
+            // A plain click or tap only pins the card.
+            next = gesture.modifier ? toggleInSelection(current, ref, mode) : current;
+        }
+        else
+            next = applyPick(current, ref, mode, { additive: gesture.additive ?? false });
+        if (sameSelection(current, next)) {
+            this.clearNotice();
             return;
+        }
+        if (state.canSelect) {
+            let verdict;
+            try {
+                verdict = state.canSelect(copySelection(next), ref);
+            }
+            catch (error) {
+                console.error("map-sdk: canSelect failed", error);
+                return;
+            }
+            if (verdict !== true) {
+                // An empty (or, from untyped JS, false) verdict refuses quietly.
+                if (typeof verdict === "string" && verdict !== "") {
+                    this.#notice = { message: verdict, id: ++this.#noticeCount };
+                }
+                return;
+            }
+        }
+        this.clearNotice();
         state.selection = next;
         state.onselectionchange?.(copySelection(next));
     }

package/dist/core/gl.d.ts

@@ -87,6 +87,11 @@ export interface GlMapLike {
         x: number;
         y: number;
     };
+    /** Position at a canvas pixel. */
+    unproject(point: [number, number]): {
+        lng: number;
+        lat: number;
+    };
     getCanvas(): HTMLCanvasElement;
     remove(): void;
 }

package/dist/core/interactions.svelte.d.ts

@@ -10,21 +10,24 @@ export interface Hovered {
  * Listens on the map itself (`click`, `mousemove`, `mouseout`) and queries only the registered
  * layers, so registrations can come and go without re-binding listeners. Layers nobody registered
  * are never hit. A blocking layer (e.g. a cluster bubble, which zooms instead) is never hit either,
- * but when it is topmost at a point nothing beneath it is hit or hovered.
+ * and when it is topmost at a point nothing beneath it is hit; only a feature whose plugin
+ * outranks it in `hoverPriority` is hovered through it. A non-hoverable plugin's features (e.g.
+ * smoke plumes) are left out of the hover and cursor as if they weren't rendered, but are still
+ * clicked and returned by lookups.
  */
 export declare class InteractionRouter {
     #private;
     /** The top hit under the pointer and where it is. Reactive, for the tooltip. */
     get hovered(): Hovered | null;
     /** Records the layers whose features `toHit` turns into hits. Returns an unregister function. */
-    register(pluginId: string, layerIds: string[], toHit: (props: Record<string, unknown>) => FeatureHit | null, priority?: number): () => void;
+    register(pluginId: string, layerIds: string[], toHit: (props: Record<string, unknown>) => FeatureHit | null, priority?: number, hoverable?: boolean): () => void;
     /**
      * Records layers that hide what is beneath them: when one is topmost at a point, clicks pick
      * nothing (calling `onClick` with that feature instead) and the hover is `toHover`'s hit for
      * it (or nothing). `toHover` must have no side effects: lookups call it too. Returns an
      * unregister function.
      */
-    registerBlocking(pluginId: string, layerIds: string[], toHover?: (props: Record<string, unknown>) => FeatureHit | null, onClick?: (feature: BlockingClick) => void, priority?: number): () => void;
+    registerBlocking(pluginId: string, layerIds: string[], toHover?: (props: Record<string, unknown>) => FeatureHit | null, onClick?: (feature: BlockingClick) => void, priority?: number, hoverable?: boolean): () => void;
     /** Listens to `gl` from now on. */
     attach(gl: GlMapLike): void;
     /** Stops listening and clears `hovered`. */
@@ -39,4 +42,9 @@ export declare class InteractionRouter {
      * click, or a touch tap; selection rules decide what it means for the plugin's mode.
      */
     onPick(handler: (e: ClickEvent) => void): () => void;
+    /**
+     * Called for a click that picks nothing: one with no hits, or one on a blocking layer (after
+     * that layer's own click handler). Returns an unsubscribe function.
+     */
+    onMiss(handler: () => void): () => void;
 }

package/dist/core/interactions.svelte.js

@@ -4,13 +4,17 @@
  * Listens on the map itself (`click`, `mousemove`, `mouseout`) and queries only the registered
  * layers, so registrations can come and go without re-binding listeners. Layers nobody registered
  * are never hit. A blocking layer (e.g. a cluster bubble, which zooms instead) is never hit either,
- * but when it is topmost at a point nothing beneath it is hit or hovered.
+ * and when it is topmost at a point nothing beneath it is hit; only a feature whose plugin
+ * outranks it in `hoverPriority` is hovered through it. A non-hoverable plugin's features (e.g.
+ * smoke plumes) are left out of the hover and cursor as if they weren't rendered, but are still
+ * clicked and returned by lookups.
  */
 export class InteractionRouter {
     // Bookkeeping only; nothing reads these reactively.
     /* eslint-disable svelte/prefer-svelte-reactivity */
     #registrations = new Set();
     #pickHandlers = new Set();
+    #missHandlers = new Set();
     /* eslint-enable svelte/prefer-svelte-reactivity */
     #gl = null;
     #canvas = null;
@@ -27,8 +31,15 @@ export class InteractionRouter {
         return this.#hovered;
     }
     /** Records the layers whose features `toHit` turns into hits. Returns an unregister function. */
-    register(pluginId, layerIds, toHit, priority = 0) {
-        return this.#add({ pluginId, layerIds: [...layerIds], toHit, blocking: false, priority });
+    register(pluginId, layerIds, toHit, priority = 0, hoverable = true) {
+        return this.#add({
+            pluginId,
+            layerIds: [...layerIds],
+            toHit,
+            blocking: false,
+            priority,
+            hoverable
+        });
     }
     /**
      * Records layers that hide what is beneath them: when one is topmost at a point, clicks pick
@@ -36,14 +47,15 @@ export class InteractionRouter {
      * it (or nothing). `toHover` must have no side effects: lookups call it too. Returns an
      * unregister function.
      */
-    registerBlocking(pluginId, layerIds, toHover, onClick, priority = 0) {
+    registerBlocking(pluginId, layerIds, toHover, onClick, priority = 0, hoverable = true) {
         return this.#add({
             pluginId,
             layerIds: [...layerIds],
             toHit: toHover ?? (() => null),
             blocking: true,
             onClick,
-            priority
+            priority,
+            hoverable
         });
     }
     #add(registration) {
@@ -67,6 +79,8 @@ export class InteractionRouter {
         gl.on("click", this.#onClick);
         gl.on("mousemove", this.#onMove);
         gl.on("mouseout", this.#onOut);
+        gl.on("boxzoomstart", this.#onBoxZoomStart);
+        gl.on("boxzoomcancel", this.#onBoxZoomCancel);
         this.#canvas = gl.getCanvas();
         this.#canvas.addEventListener("pointerdown", this.#onPointerDown);
     }
@@ -78,6 +92,9 @@ export class InteractionRouter {
         gl.off("click", this.#onClick);
         gl.off("mousemove", this.#onMove);
         gl.off("mouseout", this.#onOut);
+        gl.off("boxzoomstart", this.#onBoxZoomStart);
+        gl.off("boxzoomcancel", this.#onBoxZoomCancel);
+        this.#boxDrawn = false;
         this.#canvas?.removeEventListener("pointerdown", this.#onPointerDown);
         this.#setPointer(false);
         this.#canvas = null;
@@ -93,7 +110,8 @@ export class InteractionRouter {
         const found = this.#lookup(point);
         return found.blocked ? [] : found.hits;
     }
-    #lookup(point) {
+    /** What is under one point; with `forHover`, non-hoverable features are left out first. */
+    #lookup(point, forHover = false) {
         const none = { hits: [], hover: null, blocked: false, blocker: null, blockedBy: null };
         const gl = this.#gl;
         if (!gl)
@@ -102,6 +120,8 @@ export class InteractionRouter {
         /* eslint-disable svelte/prefer-svelte-reactivity */
         const byLayer = new Map();
         for (const registration of this.#registrations) {
+            if (forHover && !registration.hoverable)
+                continue;
             for (const id of registration.layerIds) {
                 // MapLibre errors on querying a missing layer (e.g. mid basemap change).
                 if (!byLayer.has(id) && gl.getLayer(id))
@@ -120,9 +140,25 @@ export class InteractionRouter {
         if (top?.blocking) {
             const properties = features[0].properties ?? {};
             const hit = top.toHit(properties);
+            // Clicks stay blocked, but the hover goes to the highest-priority feature beneath that
+            // outranks the blocking plugin.
+            let beneath = null;
+            let beneathPriority = top.priority;
+            for (const feature of features.slice(1)) {
+                const registration = byLayer.get(feature.layer.id);
+                if (!registration || registration.blocking)
+                    continue;
+                if (registration.priority <= beneathPriority)
+                    continue;
+                const below = registration.toHit(feature.properties ?? {});
+                if (!below)
+                    continue;
+                beneath = { ...below, pluginId: registration.pluginId };
+                beneathPriority = registration.priority;
+            }
             return {
                 hits: [],
-                hover: null,
+                hover: beneath,
                 blocked: true,
                 blocker: hit && { ...hit, pluginId: top.pluginId },
                 blockedBy: { registration: top, feature: { properties, geometry: features[0].geometry } }
@@ -156,6 +192,26 @@ export class InteractionRouter {
             this.#pickHandlers.delete(handler);
         };
     }
+    /**
+     * Called for a click that picks nothing: one with no hits, or one on a blocking layer (after
+     * that layer's own click handler). Returns an unsubscribe function.
+     */
+    onMiss(handler) {
+        this.#missHandlers.add(handler);
+        return () => {
+            this.#missHandlers.delete(handler);
+        };
+    }
+    #emitMiss() {
+        for (const handler of [...this.#missHandlers]) {
+            try {
+                handler();
+            }
+            catch (error) {
+                console.error("map-sdk: a miss handler failed", error);
+            }
+        }
+    }
     #onPointerDown = (e) => {
         this.#lastPointerType = e.pointerType || null;
     };
@@ -171,16 +227,23 @@ export class InteractionRouter {
             catch (error) {
                 console.error("map-sdk: a blocking layer's click handler failed", error);
             }
+            this.#emitMiss();
             return;
         }
         const { hits } = found;
-        if (hits.length === 0)
+        if (hits.length === 0) {
+            this.#emitMiss();
             return;
+        }
         const o = e.originalEvent;
         const pointerType = o?.pointerType || recorded;
+        const modifier = Boolean(o?.shiftKey || o?.metaKey || o?.ctrlKey);
+        const touch = pointerType === "touch";
         const event = {
             hits,
-            additive: Boolean(o?.shiftKey || o?.metaKey || o?.ctrlKey || pointerType === "touch"),
+            additive: modifier || touch,
+            modifier,
+            touch,
             lngLat: [e.lngLat.lng, e.lngLat.lat]
         };
         for (const handler of [...this.#pickHandlers]) {
@@ -192,9 +255,63 @@ export class InteractionRouter {
             }
         }
     };
+    /**
+     * MapLibre's box zoom starts on a Shift press and, released in place, suppresses the click and
+     * fires `boxzoomcancel`. A release with a pointer position is reported as a Shift-click
+     * (`boxZoom: true`) to the pick handlers only: no miss, no blocking layer's click.
+     */
+    /** A box was drawn since the Shift press: its cancel is a drag back to the start, not a click. */
+    #boxDrawn = false;
+    #onBoxZoomStart = () => {
+        this.#boxDrawn = true;
+    };
+    #onBoxZoomCancel = (e) => {
+        const drawn = this.#boxDrawn;
+        this.#boxDrawn = false;
+        if (drawn)
+            return;
+        const o = e.originalEvent;
+        const gl = this.#gl;
+        if (!gl || typeof o?.clientX !== "number" || typeof o.clientY !== "number")
+            return;
+        const point = this.#canvasPoint(o.clientX, o.clientY);
+        const found = this.#lookup(point);
+        if (found.blockedBy || found.hits.length === 0)
+            return;
+        const { lng, lat } = gl.unproject(point);
+        const event = {
+            hits: found.hits,
+            additive: true,
+            modifier: true,
+            touch: false,
+            boxZoom: true,
+            lngLat: [lng, lat]
+        };
+        for (const handler of [...this.#pickHandlers]) {
+            try {
+                handler(event);
+            }
+            catch (error) {
+                console.error("map-sdk: a pick handler failed", error);
+            }
+        }
+    };
+    /** A page position as a canvas pixel, as MapLibre's `DOM.mousePos` does (CSS scale included). */
+    #canvasPoint(clientX, clientY) {
+        const canvas = this.#canvas;
+        const rect = canvas?.getBoundingClientRect?.();
+        if (!canvas || !rect)
+            return [clientX, clientY];
+        const scaleX = canvas.offsetWidth ? rect.width / canvas.offsetWidth : 1;
+        const scaleY = canvas.offsetHeight ? rect.height / canvas.offsetHeight : 1;
+        return [
+            (clientX - rect.left) / scaleX - (canvas.clientLeft || 0),
+            (clientY - rect.top) / scaleY - (canvas.clientTop || 0)
+        ];
+    }
     #onMove = (e) => {
-        const found = this.#lookup([e.point.x, e.point.y]);
-        const hit = found.blocked ? found.blocker : found.hover;
+        const found = this.#lookup([e.point.x, e.point.y], true);
+        const hit = found.blocked ? (found.hover ?? found.blocker) : found.hover;
         this.#hovered = hit ? { hit, lngLat: [e.lngLat.lng, e.lngLat.lat] } : null;
         this.#setPointer(found.blocked || hit !== null);
     };