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

package/README.md

@@ -9,10 +9,10 @@ Supported browsers: Chrome/Edge 111+, Safari 16.4+, Firefox 128+. MIT licensed.
 
 ## Install
 
-Once published:
+map-sdk is in beta. Betas are published under the `next` tag:
 
 ```bash
-npm install @sjvair/map-sdk
+npm install @sjvair/map-sdk@next
 ```
 
 Peer dependencies: `svelte` (^5.57) and `@sjvair/sdk`, which is published to
@@ -129,13 +129,30 @@ 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.
+`card={{ actions }}` also puts your buttons in a row at the card's foot: `actions` is a snippet
+given a `CardContext` (`pluginId`, `ref`, `refKey`, the listed `item` or `null`, reactive
+`selectable` and `selected`, and `toggle()`, which is `map.togglePick` for that feature). Show
+Select/Remove only when `selectable` is true: a fire hotspot, a smoke plume, or a layer in mode
+`"none"` can't be selected, and `toggle()` then does nothing. 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).
 
@@ -156,22 +173,48 @@ create one per map (adding an object that is set up on another map throws). The
 ones they are built on. Presets don't fetch: the host supplies a `DataSource`. `monitorsPlugin` is
 selectable by default, like the shape presets.
 
+An added plugin is in `map.plugins` (and the legend and selection state) as soon as `addPlugin`
+returns. On a map that is already showing, its `setup` runs just after the current code finishes,
+so its layers aren't there yet on the next line. Code that must see them uses `await tick()`;
+`flushSync()` does not run setup.
+
 Selected points show a highlight ring and check mark by default. `selectedStyle: "enlarge"` on
 `pointsPlugin` or `monitorsPlugin` instead draws the selected icon at 1.3x with no ring (icon
 points only), as sjvair.com's map does today.
 
 `outline` on `shapesPlugin` is `"theme"` (default, a 1px `--foreground` edge), `"level"` (the edge
 in each level's color at the fill's opacity; choropleth only), or `"none"` (no outline layer).
-`hmsSmokePlugin` uses `"level"`.
+`hmsSmokePlugin` uses `"level"`. `hoverable: false` on `shapesPlugin` sets the plugin's
+`hoverable` (see [Writing a plugin](#writing-a-plugin)): hovering a shape shows no tooltip and
+doesn't hide what is beneath it, while focusing it from the feature list still pins its tooltip.
+`hmsSmokePlugin` uses it, so a plume, which can cover much of the map, never pops up a tooltip.
+
+```ts
+map.addPlugin(
+	shapesPlugin({
+		id: "plumes",
+		source: staticSource(plumes, { dataset: "hms-smoke", entryType: "smoke-density" }),
+		layerLabel: "Plumes",
+		mode: "choropleth",
+		hoverable: false
+	})
+);
+```
 
 `zoomRange: { min?, max? }` on `pointsPlugin` limits every layer it draws (points, clusters,
-selection) to zooms from `min` (inclusive) up to `max` (exclusive), switching live while zooming.
+selection) to camera zooms from `min` (inclusive) up to `max` (exclusive), switching live while
+zooming. Two plugins whose ranges meet hand over with no gap, on the globe too.
 
 `hmsFirePlugin({ id?, source, hotspots?, layerLabel })` draws fires as flame icons sized and
 colored by FRP. With `hotspots`, it switches by itself while zooming, as sjvair.com's map does:
 `source` (the fire store's `groups`) below zoom 10 and `hotspots` from zoom 10. It stays one
 layer: one legend section, one feature list (the groups, so keyboard users reach every fire;
-hotspots aren't listed), and tooltips for both.
+hotspots aren't listed), and tooltips for both. The tooltip is the monitors' reading box: "Fire
+(MW)", the power in its level's color, beside the name ("3 fire detections", "1 fire detection"
+for a group, "Fire detection" for one detection) and the level ("50–149 MW"); a group of two or
+more says "Average". A feature with a `count` (`FireFeatureProperties`, which the fire store's
+groups carry) is a group. Fire values are cut off at the display precision, not rounded, in the
+tooltip, the list and its accessible names, so 9.96 MW reads "9.9" beside "<10".
 
 `legendDisplay: "gradient" | "blocks"` on `pointsPlugin` sets how the legend draws a range scale
 (default a gradient; `hmsFirePlugin` uses `"blocks"`, labeled with the levels' own labels). A blocks
@@ -180,7 +223,29 @@ each level's label under its segment; long labels wrap. `legendTitle: "layer" |
 the legend section's title: `layerLabel` (default) or the entry type's label from the metadata
 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"`).
+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). 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.
+
+```svelte
+<div class="w-84 rounded-md bg-white shadow">
+	<h3>Legend</h3>
+	<Legend {map} framed={false} />
+</div>
+```
+
+`detail?(props)` on `pointsPlugin` gives a feature with no level a short text (such as "Level 2
+charger") shown where "No level" would be: in the feature list (plain text, no swatch), the row's
+accessible name ("Fresno Station, Level 2 charger"), and the tooltip. A feature with a level
+always shows its level. A plugin of your own sets the same `detail` on its `FeatureListItem`s.
+
+`truncateValues: true` on `pointsPlugin` cuts values off at the display precision instead of
+rounding them (`truncate` on each `FeatureListItem`), in the list, its accessible names, and the
+generic tooltip, so a value never reads as the next level up. `hmsFirePlugin` uses it.
 
 `collocationSitesPlugin({ id?, source, layerLabel })` draws collocation sites as sjvair.com does:
 each at its reference monitor, in that monitor's shape and level color (inactive gray, inside
@@ -207,7 +272,14 @@ and reads "No level"; a level with an empty color draws neutral with its own lab
 source loads, fails, or is unavailable, the legend says so (a failure offers "Try again", which
 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.
+average are whole numbers, and a cluster's max and min are as reported. Fire values are cut off
+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
+monitors, or all on one line or one spot).
 
 `createMonitorsStore()` (from `@sjvair/map-sdk/stores`) loads the monitors list and latest readings
 for an entry type, polls every two minutes, and exposes `dataSource`. `init()`, `update()`,
@@ -280,8 +352,10 @@ not selectable). `encodeRef`/`decodeRef` convert between refs and keys.
 
 A plugin is an object with an `id` and a `setup(ctx)` that adds sources, layers, and images
 through its `PluginContext` and returns a teardown. The host runs `setup` once the map's style is
-ready and again after a basemap or theme change; everything added through `ctx` is removed on
-teardown, and ids are namespaced per map. `features()` feeds the feature list, tooltip, and
+ready and again after a basemap or theme change. For a plugin added to a ready map, `setup` runs
+just after the current code finishes (a microtask), never inside the caller's code, so adding and
+removing plugins from an `$effect` is safe. Everything added through `ctx` is removed on teardown,
+and ids are namespaced per map. `features()` feeds the feature list, tooltip, and
 summary; `legend()` the legend. A plugin's `tooltip` content sits under the feature's name; set
 `tooltipShowsName` when the content shows the name itself (the monitor and collocation tooltips
 do), and the name header is left out.
@@ -321,6 +395,19 @@ function sitesPlugin(sites: Sites): MapPlugin {
 }
 ```
 
+An item for a shape (a polygon or line) can carry its `geometry` and, optionally, its `bbox`
+(`[west, south, east, north]`, from `geometryBbox(geometry)`). The list and the summary then count
+it as in view when the shape overlaps the view, not only when its `lngLat` is inside it: a smoke
+plume that fills the screen is listed even though its center is off-screen. Measure `bbox` once per
+data load (both are tested on every move); without it the box is computed each time. Focusing such
+a shape from the list while its `lngLat` is off-screen leaves the camera where it is, and its
+tooltip pins at a point of the shape in view: the view's center (beside the list panel) when the
+shape covers it, else a point inside its visible part. `map.focusedAnchor` is where the focused
+tooltip pins, and `map.anchorFor(item)` gives that point for any item without moving the camera
+(the hover tooltip uses it). `intersectsBounds(item, bounds)` is the in-view test. `shapesPlugin`
+and the presets built on it set `geometry` and `bbox` already. Bounds across the antimeridian are
+not handled.
+
 A plugin can also add a MapLibre custom layer, such as a wind layer from a library you add
 yourself, with `ctx.addCustomLayer(local, create)`. The host calls `create` with the namespaced id
 (the layer must use it) and adds the object it returns as is, in the plugin's draw-order slot. It is
@@ -329,8 +416,13 @@ time), and `movePlugin` moves it with the plugin's other layers.
 
 The cursor is a pointer over any interactive feature or cluster bubble. Where several plugins'
 features are under the pointer, the hover tooltip shows the one whose plugin has the highest
-`hoverPriority` (default 0), the topmost on a tie; a cluster bubble on top still hides what is
-beneath it, and clicks always go to the topmost.
+`hoverPriority` (default 0), the topmost on a tie. Over a cluster bubble, the bubble's tooltip
+shows unless a feature beneath belongs to a plugin with a higher `hoverPriority` than the
+bubble's (collocation sites under monitor clusters). Clicks always go to the topmost, so a click
+on a bubble still zooms into it. A plugin with `hoverable: false` never takes the hover: its
+features show no hover tooltip or pointer cursor and are passed over as if they weren't drawn, so
+whatever is beneath gets the hover. They are still clicked, returned by `featuresAt`, and pin
+their tooltip when focused from the feature list.
 
 ```ts
 import type { CustomLayerInterface, MapPlugin, PluginContext } from "@sjvair/map-sdk";
@@ -380,9 +472,35 @@ map.addPlugin(plugin, {
 in the selection bar, and a feature that appears later shows as selected. `map.getSelection(id)`
 and `getSelectionMode(id)` are reactive.
 
+`pickWith: "modifier"` (an `addPlugin` option; default `"click"`) is for maps where a click should
+only show the reading: a plain click or tap pins the card (use it with `MapView`'s `card`), and
+Shift/Cmd/Ctrl-click, or the list's Space or Shift+Enter, toggles the feature in the selection (in
+`single` mode it selects, or clears it when it's already selected). A tap never selects; the card's
+own buttons do (below). Shift-click goes through MapLibre's box zoom, which takes every Shift press:
+map-sdk turns a Shift release in place into the pick for `"modifier"` plugins only, and Shift-drag
+still zooms to a box. With `pickWith: "click"`, a Shift-click still does nothing on the map.
+
+`canSelect(next, ref)` (also an `addPlugin` option) refuses a user's pick before it shows: it gets
+the selection the pick would produce and returns `true` to let it through or a message to refuse
+it. A refused pick changes nothing and calls no `onselectionchange`; the map shows the message for
+4 s and announces it to screen readers (`map.notice` holds it). It isn't asked for `setSelection`
+or the selection bar's Clear.
+
+```ts
+map.addPlugin(plugin, {
+	selectionMode: "multiple",
+	pickWith: "modifier",
+	canSelect: (next) => (next?.ids.length ?? 0) <= 3 || "Up to 3 monitors"
+});
+```
+
+`map.togglePick(pluginId, ref)` is a user's toggle for your own controls (the card's Select or
+Remove): the same rule, `canSelect`, and `onselectionchange` as a modifier-click.
+
 `map.on("featureclick", ({ pluginId, ref, lngLat }) => …)` fires for every click on a feature,
 whatever the mode, and also for a pick in the feature list, so keyboard users get the same event;
-`lngLat` is the click point (the item's position for a list pick). It returns an unsubscribe
+`lngLat` is the click point. For a list pick it's where the item's tooltip pins: the item's
+position, or for a shape whose label point is off-screen, a point of the shape in view. It returns an unsubscribe
 function. For your own context menu, `map.featuresAt({ x, y })` returns the hits under
 a canvas point, topmost first, and `map.featureForElement(element)` returns the hit for a row of
 the feature list (an element with `data-mapsdk-ref`). Both return nothing while the map is
@@ -402,9 +520,10 @@ map.easeTo({ center: monitor.lngLat, minZoom: 12 });
 
 ## Ready, and reaching the GL map
 
-`map.ready` is reactive: true once the attached map's style has loaded and the map has gone idle
-for the first time, false again on detach and while a basemap switch reloads the style. Show a load
-screen until it is true. `map.gl` is the attached GL map (or `null`), reactive.
+`map.ready` is reactive: true once the attached map's style has loaded, the map has gone idle
+for the first time, and any queued plugin setups have run; false again on detach and while a
+basemap switch reloads the style. Adding a plugin to a ready map leaves it true. Show a load screen
+until it is true. `map.gl` is the attached GL map (or `null`), reactive.
 
 `maptilerMap(map)` returns it as a MapTiler `Map` (or `null` while detached). It is an escape hatch
 for markers and popups only: never add sources or layers through it, because plugins own those.
@@ -473,6 +592,113 @@ local sjvair.com stack at `http://localhost:8000`.
    podman exec sjvaircom_web_1 python manage.py loaddata default-calibrations.yaml
    ```
 
+## Changes
+
+### 0.1.0-beta.10
+
+- **Buttons on the pinned card.** `card={{ actions }}`: a snippet of the host's own buttons, given
+  the card's feature, whether it's selected, and `toggle()` (the dashboard's Select and Remove).
+- **Pick with a modifier.** `pickWith: "modifier"`: a plain click or tap only pins the card, and
+  Shift/Cmd/Ctrl-click (or the list's Space or Shift+Enter) toggles the selection. Shift-click now
+  reaches the map through MapLibre's box zoom for these plugins; Shift-drag still zooms to a box.
+- **Refuse a pick before it shows.** `canSelect(next, ref)` returns `true` or a message: a refused
+  pick changes nothing and calls no `onselectionchange`, and the map shows and announces the
+  message for 4 s (`map.notice`). An empty message refuses quietly.
+- **The feature list's Shift+Enter now picks additively**, as Shift-click on a row does (Enter
+  alone replaces, Space adds or removes, as before). This applies with any `pickWith`.
+- **New API:** `pickWith`, `canSelect`, `MapContext.togglePick`, `getPickWith`, `notice`,
+  `CardOptions`, `CardContext`, and `GlMapLike.unproject` (for hosts that wrap the GL map).
+- **Every `MapView` now has a `role="status"` element** (empty unless a pick is refused), so a host
+  test that finds "the" status by role inside a map may need to narrow it.
+
+### 0.1.0-beta.9
+
+- **A map with `tooltip="pointer"` comes back after releasing WebGL.** Setting `MapView`'s
+  `active` to `false` threw "Cannot read properties of null (reading 'off')" from the tooltip's
+  zoom listener, and the map never drew again until a reload. It now releases and rebuilds cleanly.
+  In 0.1.0-beta.7 and 0.1.0-beta.8; maps with the default `tooltip="pinned"` weren't affected.
+
+### 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
+  list row, the tooltip, and the row's accessible name show only the level label. Smoke rows read
+  "Smoke, Light" (was "light Light"), burn status "Burning Discouraged", and heat score
+  "Moderate" (the 0–4 number is no longer shown). Number scales such as PM2.5 and fire power are
+  unchanged, and a category value that matches no level is still shown.
+- **New message key for hosts with their own catalog:** `mapsdk_list_row_level`
+  (`"{name}, {level}"`).
+
+### 0.1.0-beta.5
+
+- **Shapes that cover the view are in view.** The feature list and the view summary count a shape
+  when it overlaps the view, not only when its center (label point) is inside it. A smoke plume or
+  a big region that fills the screen, with its center off-screen, now has a list row and is
+  counted. Points are unchanged.
+- **Focusing such a shape doesn't move the map.** Before, focusing a row panned to center the
+  shape's label point (a plume's could be off Baja). Now the camera stays, and the tooltip pins at
+  a point of the shape in view, with no move event. A shape whose label point is on screen still
+  pans to it.
+- **Hover tooltips** in `"pinned"` mode follow the same rule: a hovered shape whose label point is
+  off-screen pins its tooltip inside the view instead of at the map's edge. If the map moves while
+  the pointer rests on the shape, the pin is found again when the map settles.
+- **`featureclick` from the list** (Enter on a row) reports that same in-view point for such a
+  shape, instead of its off-screen label point. A handler that pans to `lngLat` no longer sends
+  the map off to the shape's far-away center. Points and on-screen label points report their
+  position, as before.
+- **New API (all optional):** `FeatureListItem.geometry` and `.bbox`, `MapContext.focusedAnchor`
+  and `.anchorFor(item)`, `geometryBbox`, `intersectsBounds`, and the `Bbox` type.
+
+### 0.1.0-beta.4
+
+Defaults from monitor-map 5.0's parity review against sjvair.com's map (4.3.0). Every map gets
+them; none is an option.
+
+- **Tooltip times** read like sjvair.com's map, in Pacific time: "4:00 pm Friday Nov 06, 2026"
+  (was "Nov 6, 2026, 4:00 PM"). A device in another zone still gets " PT" after the time.
+- **The cluster area line is back.** The monitor cluster tooltip's count line reads "3 monitors
+  within a 22.619 mi² area". This reverses the 2026-11-04 parity decision of "no area line". The
+  wording is new (sjvair.com said "covering"), and the area is the convex hull of the cluster's
+  monitors, so clusters of four or more can differ from sjvair.com's number, which followed the
+  monitors' order and could cross itself. No line when the area would read 0.000.
+- **Fire tooltips are the reading box**: "Fire (MW)", the power in its level's color, beside the
+  name and level; "Average" for a group of two or more. Fire values are cut off, not rounded, in
+  the tooltip, the list and its accessible names. Every group names its count, a group of 1
+  included ("1 fire detection").
+- **Smoke plumes show no hover tooltip** and never take the hover from what is beneath them;
+  focusing a plume from the feature list still pins its tooltip. This reverses part of milestone
+  2's accessibility additions ("tooltips on smoke and fire"): fire keeps a tooltip.
+- **Breaking for hosts with their own message catalog:** `mapsdk_hms_fire_detections` is now
+  `mapsdk_hms_fire_detections_one` / `_other`. New keys: `mapsdk_hms_fire_box_header`,
+  `mapsdk_hms_fire_box_header_no_units`, `mapsdk_hms_fire_average`, `mapsdk_level_with_units`,
+  and `mapsdk_monitor_cluster_count_area_one` / `_other`.
+- **New API:** `MapPlugin.hoverable`, `shapesPlugin`'s `hoverable`, `pointsPlugin`'s
+  `truncateValues`, `FeatureListItem.truncate`, and `FireFeatureProperties`.
+
 ## Development
 
 ```bash

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

@@ -5,7 +5,7 @@ import type { FeatureRef, SelectionMode, SpatialSelection } from "../data/types.
 import { BasemapState, type BasemapConfig } from "./basemap.svelte.js";
 import type { GlMapLike } from "./gl.js";
 import { type Hovered } from "./interactions.svelte.js";
-import type { FeatureHit, MapPlugin } from "./plugin.js";
+import type { FeatureHit, FeatureListItem, MapPlugin } from "./plugin.js";
 export interface CameraState {
     center: [number, number];
     zoom: number;
@@ -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;
@@ -48,11 +56,28 @@ export interface PluginOptions {
     selectionMode?: SelectionMode;
     selection?: SpatialSelection | null;
     onselectionchange?(sel: SpatialSelection | null): void;
+    /**
+     * `"click"` (default): today's rules (a click selects; Shift/⌘/Ctrl or a tap adds in
+     * `"multiple"` mode). `"modifier"`: a plain click or tap only pins the card (use it with
+     * `MapView`'s `card`), and Shift/⌘/Ctrl-click, or the list's Space or Shift+Enter, toggles the
+     * feature in the selection.
+     */
+    pickWith?: "click" | "modifier";
+    /**
+     * Called before a user's pick (a click, a list pick, or the card's `toggle`) changes the
+     * selection, with the selection it would produce. `true` lets it through; a string refuses it
+     * and is the message the map shows (`MapContext.notice`). Not called for `setSelection` or the
+     * selection bar's Clear.
+     */
+    canSelect?(next: SpatialSelection | null, ref: FeatureRef): true | string;
 }
 export type FeatureClickHandler = (e: {
     pluginId: string;
     ref: FeatureRef;
-    /** The click point; for a pick in the feature list, the item's position. */
+    /**
+     * The click point. For a pick in the feature list, where the item's tooltip pins: its position,
+     * or for a shape whose label point is off-screen, a point of the shape in view.
+     */
     lngLat: [number, number];
 }) => void;
 /** Where a camera move ends up. `zoom` wins over `minZoom`. */
@@ -82,8 +107,9 @@ export interface MapContext {
     /** Reactive. */
     readonly attached: boolean;
     /**
-     * Reactive. True once the attached map's style has loaded and the map has gone idle for the
-     * first time; false again on `detach()` and while a basemap switch reloads the style. A load
+     * Reactive. True once the attached map's style has loaded, the map has gone idle for the
+     * first time, and any queued plugin setups have run; false again on `detach()` and while a
+     * basemap switch reloads the style. Adding a plugin to a ready map leaves it true. A load
      * screen can wait for it.
      */
     readonly ready: boolean;
@@ -158,6 +184,34 @@ 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;
+    /** Reactive. The plugin's `pickWith`: `"click"` for an unknown plugin. */
+    getPickWith(pluginId: string): "click" | "modifier";
+    /**
+     * A user's toggle of `ref` (the card's Select/Remove): the modifier-click rule, with the
+     * plugin's `canSelect` and `onselectionchange`, in either `pickWith` mode.
+     */
+    togglePick(pluginId: string, ref: FeatureRef): void;
+    /**
+     * Reactive. The latest refused pick's message; `id` grows with each refusal, so the same
+     * message twice is announced again. Cleared by the next pick, `clearNotice()`, and detach.
+     */
+    readonly notice: {
+        message: string;
+        id: number;
+    } | null;
+    /** @internal For `PickNotice`: clears the notice. */
+    clearNotice(): void;
+    /** 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
@@ -184,6 +238,18 @@ export interface MapContext {
     readonly focusedKey: string | null;
     /** Reactive. The plugin `focusFeature` was given with `focusedKey`, or `null`. */
     readonly focusedPluginId: string | null;
+    /**
+     * Reactive. Where the focused feature's tooltip pins, set by `focusFeature` (`null` without
+     * focus): its `lngLat`, or for a shape that overlaps the view with its `lngLat` off-screen, a
+     * point of the shape in the part of the view the list panel leaves clear. Fixed at focus
+     * time, so it stays on the feature if the map then moves.
+     */
+    readonly focusedAnchor: [number, number] | null;
+    /**
+     * Where `item`'s tooltip pins in the current view, without moving the camera: its `lngLat`,
+     * or for a shape (`geometry`) with its `lngLat` off-screen, a point of the shape in view.
+     */
+    anchorFor(item: FeatureListItem): [number, number];
     /** For MapView only: uses `gl` from now on. */
     attach(gl: GlMapLike): void;
     /** For MapView only: stops using the current GL map. */
@@ -197,7 +263,8 @@ export interface MapContext {
     updateView(camera: CameraState, bounds: Bounds): void;
     /**
      * For MapView only: the host's theme changed, so plugins set up again and re-read the theme
-     * colors they bake into paint and images. Does nothing while detached.
+     * colors they bake into paint and images. Does nothing while detached. Sets plugins up
+     * synchronously, so never call it from inside an effect (see `PluginHost`).
      */
     themeChanged(): void;
     /** Detaches, removes every plugin, and drops handlers. The context can't be used after. */