@sjvair/map-sdk 0.1.0-beta.6 → 0.1.0-beta.8

package/README.md

@@ -129,13 +129,25 @@ buttons, `"engine"` the MapTiler SDK's default zoom/compass and locate-me contro
 monitor-map uses today), and `"none"` none; the credits show in every case. Choose `controls` up
 front: changing it after mount recreates the map. `tooltip` is `"pinned"` (default: anchored to the
 feature) or `"pointer"` (shown at the pointer, as sjvair.com's map does, and hidden on zoom until
-the pointer moves again); a feature focused from the list is always pinned. Anything else goes in
+the pointer moves again); a feature focused from the list is always pinned. `card` (default
+`false`) pins the reading card on a click or tap: the card takes the pointer, has a Close button,
+and closes with Esc, Close, or a click elsewhere on the map; focusing a feature-list row shows the
+same card, and Tab from the row reaches it. Esc closes the card of the map that has focus; with
+focus nowhere, it closes the page's most recently pinned card. One card shows at a time, and no hover card shows while
+one is pinned. Selection and `featureclick` are unchanged: a click still selects as before and
+also pins. `map.pinned` is the pinned feature (reactive), and `map.unpin()` closes it. Anything else goes in
 the `overlays` snippet, where `getMapContext()` returns the map. `config.basemaps` replaces the
 default MapTiler Streets v4 variants (build on `defaultBasemaps()`, which `createMap` uses: today's
 sjvair.com setup is `{ ...defaultBasemaps(), excludedLayers: [] }`); `config.initialView` and
 `config.cooperativeGestures` set the camera and gesture handling. `config.projection` (`"mercator"`
 by default, or `"globe"`) and `config.space` (`false` by default, or `{ preset: "milkyway" }` for a
-space background behind the globe) are passed to MapTiler only when set.
+space background behind the globe) are passed to MapTiler only when set. `config.telemetry: false`
+turns off MapTiler's telemetry (a usage report of the SDK version, API key, and session id, sent
+about 2 s after each map is created) before the map is created. It is a page-wide setting in
+MapTiler's SDK: once one map turns it off, it stays off for every map on the page. MapTiler's
+session id (`mtsid`) stays on either way, since MapTiler bills SDK maps by session (without one,
+every tile request counts on its own) and its tile cache needs it. By default (`true`) MapTiler's
+own default applies.
 
 Without `createMonitorsStore`, build a `DataSource` yourself (below).
 
@@ -207,7 +219,9 @@ the legend section's title: `layerLabel` (default) or the entry type's label fro
 provider (`monitorsPlugin` uses the latter, so its section reads "PM2.5"; `layerLabel` still names
 the layer in the list, selection bar and summary). `Legend` takes `order` (`"bottom-first"`,
 default, or `"top-first"`) and `framed` (`true`, default, draws its own card; `false` draws no
-border, background, padding or fixed width, so a host's own card frames it). Without a frame,
+border, background, padding or fixed width, so a host's own card frames it). The framed legend
+and the feature list panel are 21rem wide at most, and never wider than the map less 2rem (the
+window less 2rem outside a `MapView`), so they fit a small map on a wide screen. Without a frame,
 translucent swatches blend over the nearest ancestor with an opaque background (a see-through
 card is skipped), else `--background`; that color is read on mount, when `framed` changes, and on
 a theme change, but not when the card changes color through its own class or style.
@@ -254,7 +268,9 @@ source loads, fails, or is unavailable, the legend says so (a failure offers "Tr
 calls `status.retry()`). Values are shown with the metadata's display precision, except in the
 monitor, cluster, and collocation tooltips, which match monitor-map: the reading and a cluster's
 average are whole numbers, and a cluster's max and min are as reported. Fire values are cut off
-rather than rounded (see `truncateValues`). Times in the tooltips read like sjvair.com's map, in
+rather than rounded (see `truncateValues`). On a category scale, a value that is its level's code
+(smoke's `"light"`, the heat score's `2`) isn't shown: the list row, the tooltip, and the row's
+accessible name give only the level label. Times in the tooltips read like sjvair.com's map, in
 Pacific time: "4:00 pm Friday Nov 06, 2026", with " PT" after them on a device in another zone.
 The monitor cluster tooltip's count line gives the area the monitors are within, "3 monitors
 within a 22.619 mi² area": the area of their convex hull, left out when it would read 0.000 (two
@@ -548,6 +564,31 @@ local sjvair.com stack at `http://localhost:8000`.
 
 ## Changes
 
+### 0.1.0-beta.8
+
+- **The pinned reading card.** `MapView`'s new `card` prop: a click or tap on a feature pins its
+  card, which takes the pointer, has a Close button, and closes with Esc, Close, or a click
+  elsewhere on the map. Focusing a feature-list row shows the same card, and Tab reaches it; closing
+  it returns focus where it came from. With `card`, a tap always shows the reading: without
+  it, a tap's emulated `mouseout` (Chromium, WebKit) still hides the hover card right after the
+  tap, as before. Nothing changes without `card`, and with it, selection and `featureclick` behave
+  as before.
+- **New API:** `MapView`'s `card`, `MapContext.pinned` and `unpin()`. New message key for hosts
+  with their own catalog: `mapsdk_card_close` ("Close").
+
+### 0.1.0-beta.7
+
+- **Plugins come back at once after a basemap switch.** After picking another basemap, monitors,
+  fire, smoke and the other layers were missing until every tile of the new basemap had loaded
+  and drawn (4–10 s on a slow connection). They are now added as soon as the new style loads, as
+  sjvair.com's map does. A theme change while tiles are loading no longer waits either.
+- **`config.telemetry: false`** turns off MapTiler's telemetry (its usage report) for the page,
+  before the map is created. Sessions stay on, so billing by session and the tile cache are
+  unchanged. By default nothing changes.
+- **The feature list panel and the framed legend fit the map.** They were capped at the window's
+  width less 2rem; inside a `MapView` they are now capped at the map's width less 2rem, so a small
+  map on a wide screen doesn't overflow. MapView sets `--mapsdk-map-width` for this.
+
 ### 0.1.0-beta.6
 
 - **A category reading is shown once.** When a feature's value is its category level's code, the

package/dist/core/create-map.svelte.d.ts

@@ -32,6 +32,14 @@ export interface MapConfig {
     space?: false | {
         preset: string;
     };
+    /**
+     * Default `true`: MapTiler's own default. `false` turns off MapTiler's telemetry (a usage
+     * report of the SDK version, the API key, and the session id, sent about 2 s after each map is
+     * created) before the GL map is created. It is a page-wide setting in MapTiler's SDK, so once
+     * one map turns it off it stays off for every map on the page. MapTiler's session id (`mtsid`)
+     * stays on: MapTiler bills SDK maps by session, and its tile cache needs sessions.
+     */
+    telemetry?: boolean;
 }
 export interface CreateMapOptions {
     config: MapConfig;
@@ -162,6 +170,17 @@ export interface MapContext {
      * lists, with the bubble's `properties`, never a feature beneath it.
      */
     readonly hovered: Hovered | null;
+    /**
+     * Reactive. The feature whose reading card is pinned, and where, while `MapView`'s `card` is
+     * on; `null` otherwise. A click on a feature pins it (selection and `featureclick` are
+     * unchanged), focusing a feature-list row pins that row's feature, and a click on nothing (or
+     * on a cluster bubble or a feature without a hover card) unpins.
+     */
+    readonly pinned: Hovered | null;
+    /** Closes the pinned card. Does nothing when nothing is pinned. */
+    unpin(): void;
+    /** @internal For `MapView` only: turns pinning on or off. Off also unpins. */
+    setCardEnabled(on: boolean): void;
     /**
      * Marks the feature focused and pans to it (no animation under reduced motion): the item in
      * `pluginId`'s features when given, else the first plugin listing `refKey`. `null` clears the

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

@@ -58,6 +58,8 @@ class MapContextImpl {
     #focusedKey = $state(null);
     #focusedPluginId = $state(null);
     #focusedAnchor = $state.raw(null);
+    #pinned = $state.raw(null);
+    #cardEnabled = false;
     #selections = new SvelteMap();
     #featureClickHandlers = new Set();
     #router = new InteractionRouter();
@@ -98,6 +100,7 @@ class MapContextImpl {
             }
         });
         this.#router.onPick((e) => this.#pick(e));
+        this.#router.onMiss(() => this.unpin());
     }
     get camera() {
         return this.#camera;
@@ -137,6 +140,18 @@ class MapContextImpl {
     get hovered() {
         return this.#router.hovered;
     }
+    get pinned() {
+        return this.#pinned;
+    }
+    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));
@@ -171,6 +186,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)
@@ -249,9 +266,15 @@ class MapContextImpl {
         const found = untrack(() => this.#findItem(refKey, pluginId));
         if (!found)
             return;
-        const { item } = found;
+        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.
@@ -381,7 +404,9 @@ class MapContextImpl {
         this.#host.attach(gl);
         this.#router.attach(gl);
         gl.on("moveend", this.#onMoveEnd);
-        this.basemap.attach(gl, () => this.#host.restyle(), () => {
+        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();
@@ -393,6 +418,7 @@ class MapContextImpl {
             return;
         this.#gl.off("moveend", this.#onMoveEnd);
         this.#focusEasing = false;
+        this.unpin();
         this.#router.detach();
         this.basemap.detach();
         this.#host.detach();
@@ -435,9 +461,18 @@ class MapContextImpl {
     #pick(e) {
         if (this.#destroyed)
             return;
-        const [{ pluginId, ref }] = e.hits;
+        const [hit] = e.hits;
+        const { pluginId, ref } = hit;
         this.#emitClick(pluginId, ref, e.lngLat);
         this.#applyPick(pluginId, ref, e.additive);
+        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]) {

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

@@ -42,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

@@ -14,6 +14,7 @@ export class InteractionRouter {
     /* 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;
@@ -186,6 +187,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;
     };
@@ -201,11 +222,14 @@ 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 event = {

package/dist/core/plugin-host.svelte.d.ts

@@ -57,11 +57,15 @@ export declare class PluginHost {
      */
     suspend(): void;
     /**
-     * Tears down and sets up every plugin again (after a basemap change), once the style loads.
-     * On a loaded style the setup is synchronous, so only map events and theme watching call this,
-     * never code inside an effect: roots created there can stop (see the class comment).
+     * Tears down and sets up every plugin again (after a basemap or theme change), once the style
+     * loads. Pass `styleLoaded` from a `style.load` listener: `isStyleLoaded()` stays false there
+     * until every tile has loaded, and `style.load` has already fired, so waiting would last until
+     * `idle`. A live host's style is loaded too (`suspend` comes before every `setStyle`), so a theme
+     * change sets up at once as well. On a loaded style the setup is synchronous, so only map events
+     * and theme watching call this, never code inside an effect: roots created there can stop (see
+     * the class comment).
      */
-    restyle(): void;
+    restyle(styleLoaded?: boolean): void;
     /** Tears down every plugin. The gl is not touched after this returns. */
     detach(): void;
 }

package/dist/core/plugin-host.svelte.js

@@ -161,15 +161,26 @@ export class PluginHost {
         this.#teardownAll();
     }
     /**
-     * Tears down and sets up every plugin again (after a basemap change), once the style loads.
-     * On a loaded style the setup is synchronous, so only map events and theme watching call this,
-     * never code inside an effect: roots created there can stop (see the class comment).
+     * Tears down and sets up every plugin again (after a basemap or theme change), once the style
+     * loads. Pass `styleLoaded` from a `style.load` listener: `isStyleLoaded()` stays false there
+     * until every tile has loaded, and `style.load` has already fired, so waiting would last until
+     * `idle`. A live host's style is loaded too (`suspend` comes before every `setStyle`), so a theme
+     * change sets up at once as well. On a loaded style the setup is synchronous, so only map events
+     * and theme watching call this, never code inside an effect: roots created there can stop (see
+     * the class comment).
      */
-    restyle() {
+    restyle(styleLoaded = false) {
         if (!this.#gl)
             return;
+        const loaded = styleLoaded || this.#live;
         this.#teardownAll();
-        this.#whenStyleLoaded(true);
+        if (loaded) {
+            this.#cancelStyleWait();
+            this.#setupAll();
+        }
+        else {
+            this.#whenStyleLoaded(true);
+        }
     }
     /** Tears down every plugin. The gl is not touched after this returns. */
     detach() {

package/dist/data/messages/en.json

@@ -56,5 +56,6 @@
 	"mapsdk_collocation_reference": "Reference monitor",
 	"mapsdk_collocation_colocated": "Collocated monitor",
 	"mapsdk_collocation_interval_avg": "({interval} avg)",
-	"mapsdk_collocation_updated": "Last updated {when}"
+	"mapsdk_collocation_updated": "Last updated {when}",
+	"mapsdk_card_close": "Close"
 }

package/dist/ui/FeatureList.svelte

@@ -381,7 +381,8 @@
 		flex-direction: column;
 		position: relative;
 		width: 21rem;
-		max-width: calc(100vw - 2rem);
+		/* The map's width inside a MapView (set there), else the window's. */
+		max-width: calc(var(--mapsdk-map-width, 100vw) - 2rem);
 		max-height: 100%;
 		box-sizing: border-box;
 		border: 1px solid var(--card-border, var(--border));

package/dist/ui/Legend.svelte

@@ -143,7 +143,8 @@
 		flex-direction: column;
 		gap: 0.75rem;
 		width: 21rem;
-		max-width: calc(100vw - 2rem);
+		/* The map's width inside a MapView (set there), else the window's. */
+		max-width: calc(var(--mapsdk-map-width, 100vw) - 2rem);
 		box-sizing: border-box;
 		padding: 0.75rem 1rem;
 		border: 1px solid var(--card-border, var(--border));

package/dist/ui/MapTooltip.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
 	import { untrack } from "svelte";
+	import type { Attachment } from "svelte/attachments";
 	import type { MapContext } from "../core/create-map.svelte.js";
 	import type { GlMapLike } from "../core/gl.js";
 	import type { FeatureListItem, MapPlugin } from "../core/plugin.js";
@@ -24,9 +25,17 @@
 		mode?: "pinned" | "pointer";
 		/** The GL map, for `zoomstart` in `"pointer"` mode. */
 		gl?: Pick<GlMapLike, "on" | "off"> | null;
+		/**
+		 * The pinned reading card: `map.pinned` and a focused list item show as an interactive card
+		 * (pointer events, a Close button, Esc), and the hover doesn't show while one is pinned.
+		 */
+		card?: boolean;
 	}
 
-	let { map, project, width, height, mode = "pinned", gl = null }: Props = $props();
+	let { map, project, width, height, mode = "pinned", gl = null, card = false }: Props = $props();
+
+	// Ignored without the card, so a host's map never pins.
+	const pinned = $derived(card ? map.pinned : null);
 
 	// Pointer mode only: set by a zoom, cleared by the next pointer move over a hit.
 	let zoomHidden = $state(false);
@@ -45,11 +54,15 @@
 	let tipHeight = $state(0);
 	const GAP = 12;
 
-	// The keyboard-focused list item wins over the pointer.
-	const key = $derived(map.focusedKey ?? map.hovered?.hit.refKey ?? null);
+	// The keyboard-focused list item wins, then the pinned card, then the pointer (which shows
+	// nothing while a card is pinned).
+	const shownHit = $derived(map.focusedKey ? null : (pinned ?? map.hovered));
+	const key = $derived(map.focusedKey ?? shownHit?.hit.refKey ?? null);
 	// Primitives, so moving the pointer within one feature doesn't recompute the content.
-	const hitPluginId = $derived(map.focusedKey ? null : (map.hovered?.hit.pluginId ?? null));
-	const hitName = $derived(map.focusedKey ? null : (map.hovered?.hit.name ?? null));
+	const hitPluginId = $derived(shownHit?.hit.pluginId ?? null);
+	const hitName = $derived(shownHit?.hit.name ?? null);
+	// The card shows (interactive) for a focused item or a pinned feature.
+	const interactive = $derived(card && (map.focusedKey !== null || pinned !== null));
 
 	// Reads only the shown feature's plugin (or all plugins for a focused key), and only while
 	// something is shown, so an idle map doesn't subscribe to any plugin's data.
@@ -83,12 +96,20 @@
 		return untrack(() => (item?.geometry ? map.anchorFor(item) : null));
 	});
 	const anchor = $derived.by((): [number, number] | null => {
-		if (mode === "pointer" && !map.focusedKey) return map.hovered?.lngLat ?? null;
+		if (mode === "pointer" && !map.focusedKey && !pinned) return map.hovered?.lngLat ?? null;
 		// A focused feature that left the data has no item, so no tooltip.
 		if (map.focusedKey) return item ? (map.focusedAnchor ?? item.lngLat) : null;
-		return hoverAnchor ?? item?.lngLat ?? map.hovered?.lngLat ?? null;
+		return hoverAnchor ?? item?.lngLat ?? shownHit?.lngLat ?? null;
 	});
 	const projected = $derived(anchor ? project(anchor) : null);
+	// A card whose anchor is out of the map's box hides until it's back.
+	const offScreen = $derived(
+		interactive &&
+			projected !== null &&
+			width !== undefined &&
+			height !== undefined &&
+			(projected.x < 0 || projected.y < 0 || projected.x > width || projected.y > height)
+	);
 	// Centered above the point; flipped below it near the top edge; inside the container.
 	const position = $derived.by(() => {
 		if (!projected) return null;
@@ -105,7 +126,7 @@
 		// A hovered hit no plugin lists (e.g. a cluster bubble): its plugin's hover content.
 		if (key === null || hitPluginId === null) return undefined;
 		const plugin = map.plugins.find((p) => p.id === hitPluginId);
-		const hit = untrack(() => map.hovered?.hit);
+		const hit = untrack(() => shownHit?.hit);
 		return hit && plugin?.hoverTooltip?.(hit);
 	});
 
@@ -116,10 +137,128 @@
 		const plugin = found?.plugin ?? map.plugins.find((p) => p.id === hitPluginId);
 		return !plugin?.tooltipShowsName;
 	});
+
+	let cardEl: HTMLDivElement | undefined = $state();
+	/** Where focus came from when it moved into the card, to return it on close. */
+	let origin: HTMLElement | null = null;
+
+	function onfocusin(e: FocusEvent) {
+		const from = e.relatedTarget;
+		focusInside = true;
+		region = cardEl?.closest<HTMLElement>("[data-mapsdk-map]") ?? region;
+		// Focus from outside sets the origin afresh, even from nowhere, so an earlier card's
+		// origin is never reused.
+		if (!(from instanceof Node && cardEl?.contains(from))) {
+			origin = from instanceof HTMLElement ? from : null;
+		}
+	}
+
+	/** Focus is inside the card (kept by focusin/focusout, since a removed card no longer says). */
+	let focusInside = false;
+	/** The map region the card is in, found while it's in the document. */
+	let region: HTMLElement | null = null;
+
+	function onfocusout(e: FocusEvent) {
+		const to = e.relatedTarget;
+		if (to instanceof Node && cardEl?.contains(to)) return;
+		// Later, not now: removing the focused card fires focusout too, and its teardown (which
+		// runs first) still has to see that focus was inside.
+		queueMicrotask(() => {
+			if (!cardEl?.contains(document.activeElement)) focusInside = false;
+		});
+	}
+
+	/** Focus inside the card goes back where it came from, else to the map region. */
+	function handBack() {
+		if (!focusInside) return;
+		focusInside = false;
+		const back = origin;
+		origin = null;
+		if (back?.isConnected) back.focus();
+		else if (region?.isConnected) {
+			if (!region.hasAttribute("tabindex")) region.setAttribute("tabindex", "-1");
+			region.focus();
+		}
+	}
+
+	// However the card goes (Close, a host's unpin, its plugin removed, its anchor off-screen),
+	// focus inside it isn't left on a removed node.
+	const handBackOnRemove: Attachment<HTMLElement> = () => () => handBack();
+
+	/** Unpins, handing focus back first. */
+	function close() {
+		handBack();
+		map.unpin();
+		// Focus back on a list row focuses (and so shows) that row again; the card stays closed
+		// until the next row move, as with Esc in the list.
+		if (map.focusedKey !== null) map.focusFeature(null);
+	}
+
+	function onkeydown(e: KeyboardEvent) {
+		if (e.key !== "Escape") return;
+		e.preventDefault();
+		e.stopPropagation();
+		close();
+	}
+
+	// A pinned hit with nothing to show (no name, listed item, or hover content) would be an
+	// invisible card that still hides the hover and takes Esc: unpin it.
+	$effect(() => {
+		if (pinned && !map.focusedKey && !(name || item || custom)) untrack(() => map.unpin());
+	});
+
+	// A pinned feature that left its plugin's data (a poll dropped it) closes its card. Only one
+	// its plugin listed while pinned: some hits are never listed (HMS fire hotspots), and keep it.
+	let listedKey: string | null = null;
+	$effect(() => {
+		if (!pinned || map.focusedKey) return;
+		const { pluginId, refKey } = pinned.hit;
+		const plugin = map.plugins.find((p) => p.id === pluginId);
+		if (!plugin?.features) return;
+		const id = `${pluginId}\n${refKey}`;
+		if (plugin.features().some((f) => f.refKey === refKey)) listedKey = id;
+		else if (listedKey === id) {
+			listedKey = null;
+			untrack(close);
+		}
+	});
 </script>
 
 <!-- Only with something to show: a hit with no name, item, or content gets no empty box. -->
-{#if (name || item || custom) && position && !(zoomHidden && !map.focusedKey)}
+{#if interactive && (name || item || custom) && position && !offScreen}
+	<!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+	<div
+		bind:this={cardEl}
+		{@attach handBackOnRemove}
+		class="mapsdk-tooltip mapsdk-card text-sm"
+		role="group"
+		aria-label={name ?? undefined}
+		bind:offsetWidth={tipWidth}
+		bind:offsetHeight={tipHeight}
+		style:left="{position.left}px"
+		style:top="{position.top}px"
+		{onfocusin}
+		{onfocusout}
+		{onkeydown}
+	>
+		{#if showName}
+			<div class="mapsdk-tooltip-name">{name}</div>
+		{/if}
+		{#if custom}
+			{@render custom()}
+		{:else if item}
+			<TooltipItem {item} messages={map.messages} format={map.format} />
+		{/if}
+		<button
+			type="button"
+			class="mapsdk-card-close mapsdk-focus"
+			aria-label={map.messages("mapsdk_card_close")}
+			onclick={close}
+		>
+			<span aria-hidden="true">×</span>
+		</button>
+	</div>
+{:else if !interactive && (name || item || custom) && position && !(zoomHidden && !map.focusedKey)}
 	<div
 		class="mapsdk-tooltip text-sm"
 		role="tooltip"
@@ -168,4 +307,36 @@
 	.mapsdk-tooltip-name {
 		font-weight: 600;
 	}
+
+	/* The pinned card: takes the pointer, and sits above the feature list panel. Room on the
+	   right for the Close button. */
+	.mapsdk-card {
+		z-index: 3;
+		padding-right: 2rem;
+		pointer-events: auto;
+	}
+
+	.mapsdk-card-close {
+		position: absolute;
+		top: 0.25rem;
+		right: 0.25rem;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		width: 1.5rem;
+		height: 1.5rem;
+		padding: 0;
+		border: 0;
+		border-radius: var(--radius-control, var(--radius));
+		background: transparent;
+		color: inherit;
+		font: inherit;
+		font-size: 1.125rem;
+		line-height: 1;
+		cursor: pointer;
+	}
+
+	.mapsdk-card-close:hover {
+		background: var(--accent, var(--muted));
+	}
 </style>

package/dist/ui/MapTooltip.svelte.d.ts

@@ -22,6 +22,11 @@ interface Props {
     mode?: "pinned" | "pointer";
     /** The GL map, for `zoomstart` in `"pointer"` mode. */
     gl?: Pick<GlMapLike, "on" | "off"> | null;
+    /**
+     * The pinned reading card: `map.pinned` and a focused list item show as an interactive card
+     * (pointer events, a Close button, Esc), and the hover doesn't show while one is pinned.
+     */
+    card?: boolean;
 }
 declare const MapTooltip: import("svelte").Component<Props, {}, "">;
 type MapTooltip = ReturnType<typeof MapTooltip>;

package/dist/view/MapView.svelte

@@ -56,6 +56,12 @@
 		 * Keyboard focus from the feature list always shows it pinned.
 		 */
 		tooltip?: "pinned" | "pointer";
+		/**
+		 * `true`: a click or tap on a feature pins its reading card, which takes the pointer and
+		 * closes with Esc, its Close button, or a click elsewhere on the map; focusing a
+		 * feature-list row shows the same card. Selection and `featureclick` are unchanged.
+		 */
+		card?: boolean;
 	}
 
 	let {
@@ -67,9 +73,46 @@
 		featureList = true,
 		selectionBar = true,
 		controls = "mapsdk",
-		tooltip = "pinned"
+		tooltip = "pinned",
+		card = false
 	}: Props = $props();
 
+	// Pinning only, no plugin setup, so it's safe in an effect.
+	$effect(() => {
+		map.setCardEnabled(card);
+		return () => map.setCardEnabled(false);
+	});
+
+	/**
+	 * Esc outside the card closes it when focus is in this map or nowhere (the body), so a key
+	 * pressed in another map, or elsewhere on the page, leaves this card alone.
+	 */
+	function onWindowKeydown(e: KeyboardEvent) {
+		if (e.key !== "Escape" || e.defaultPrevented || !map.pinned) return;
+		const active = document.activeElement;
+		if (active && active !== document.body && !root.contains(active)) return;
+		// Focus nowhere: only the most recently pinned card on the page closes.
+		if (!active || active === document.body) {
+			let latest: HTMLElement | null = null;
+			for (const el of document.querySelectorAll<HTMLElement>("[data-mapsdk-pinned-at]")) {
+				if (!latest || Number(el.dataset.mapsdkPinnedAt) > Number(latest.dataset.mapsdkPinnedAt)) {
+					latest = el;
+				}
+			}
+			if (latest && latest !== root) return;
+		}
+		e.preventDefault();
+		map.unpin();
+	}
+
+	// When this map's card was pinned, so Esc with focus nowhere closes the latest card only.
+	$effect(() => {
+		const pinned = map.pinned;
+		if (!root) return;
+		if (pinned) root.dataset.mapsdkPinnedAt = String(performance.now());
+		else delete root.dataset.mapsdkPinnedAt;
+	});
+
 	const list = $derived(resolveFeatureList(featureList));
 	const sides = $derived(list ? cornerSides(list.position) : null);
 
@@ -148,6 +191,12 @@
 	function onListKeydown(e: KeyboardEvent) {
 		if (e.key !== "Escape") return;
 		e.preventDefault();
+		// The card closes first (and the focused row's card with it); the next Esc closes the panel.
+		if (card && (map.pinned || map.focusedKey)) {
+			map.unpin();
+			map.focusFeature(null);
+			return;
+		}
 		listOpen = false;
 		listButton?.focus();
 	}
@@ -242,6 +291,8 @@
 	});
 </script>
 
+<svelte:window onkeydown={onWindowKeydown} />
+
 <div
 	bind:this={root}
 	bind:clientWidth={width}
@@ -250,9 +301,9 @@
 	role="region"
 	aria-label={label ?? map.messages("mapsdk_map_label")}
 	data-mapsdk-map={map.uid}
+	style:--mapsdk-map-width={width > 0 ? `${width}px` : undefined}
 >
 	<div class="mapsdk-gl" bind:this={glContainer}></div>
-	<MapTooltip {map} {project} {width} {height} mode={tooltip} gl={projector} />
 	{#if list && sides}
 		<div
 			class="mapsdk-list-panel"
@@ -282,6 +333,8 @@
 			{/if}
 		</div>
 	{/if}
+	<!-- After the list, so Tab from a list row reaches the pinned card's Close button. -->
+	<MapTooltip {map} {project} {width} {height} mode={tooltip} gl={projector} {card} />
 	<!-- After the list, so Tab reaches the List button first. -->
 	{#if selectionBar}
 		<SelectionBar {map} clearRight={list?.position === "top-right" && controls === "none"} />

package/dist/view/MapView.svelte.d.ts

@@ -37,6 +37,12 @@ interface Props {
      * Keyboard focus from the feature list always shows it pinned.
      */
     tooltip?: "pinned" | "pointer";
+    /**
+     * `true`: a click or tap on a feature pins its reading card, which takes the pointer and
+     * closes with Esc, its Close button, or a click elsewhere on the map; focusing a
+     * feature-list row shows the same card. Selection and `featureclick` are unchanged.
+     */
+    card?: boolean;
 }
 declare const MapView: import("svelte").Component<Props, {}, "">;
 type MapView = ReturnType<typeof MapView>;

package/dist/view/create-gl-map.js

@@ -128,6 +128,10 @@ function recordView(gl, ctx) {
  */
 export function createGlMap(container, ctx, engineControls = false) {
     const { camera, style } = untrack(() => ({ camera: ctx.camera, style: styleOf(ctx) }));
+    // Before the map exists, so its telemetry timer finds it off. Sessions stay on: MapTiler
+    // bills SDK maps by session, and without one every tile request counts on its own.
+    if (ctx.config.telemetry === false)
+        maptilerConfig.telemetry = false;
     const gl = new GlMap({
         container,
         style,

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@sjvair/map-sdk",
 	"description": "Svelte 5 map components for SJVAir air-quality data",
-	"version": "0.1.0-beta.6",
+	"version": "0.1.0-beta.8",
 	"license": "MIT",
 	"repository": {
 		"type": "git",