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

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
@@ -156,6 +156,11 @@ 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.
@@ -165,7 +170,8 @@ in each level's color at the fill's opacity; choropleth only), or `"none"` (no o
 `hmsSmokePlugin` uses `"level"`.
 
 `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:
@@ -180,7 +186,23 @@ 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). 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.
 
 `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
@@ -280,8 +302,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.
@@ -329,8 +353,10 @@ 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.
 
 ```ts
 import type { CustomLayerInterface, MapPlugin, PluginContext } from "@sjvair/map-sdk";
@@ -402,9 +428,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.

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

@@ -82,8 +82,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;
@@ -197,7 +198,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. */

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

@@ -50,6 +50,8 @@ 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);
@@ -77,7 +79,15 @@ 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));
     }
@@ -100,7 +110,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() {
@@ -269,6 +283,7 @@ class MapContextImpl {
         this.#router.attach(gl);
         this.basemap.attach(gl, () => this.#host.restyle(), () => {
             this.#ready = false;
+            this.#readyRequested = false;
             this.#host.suspend();
         });
         this.#attached = true;
@@ -283,6 +298,7 @@ class MapContextImpl {
         this.#glState = null;
         this.#attached = false;
         this.#ready = false;
+        this.#readyRequested = false;
     }
     themeChanged() {
         if (this.#gl)

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

@@ -10,7 +10,8 @@ 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.
  */
 export declare class InteractionRouter {
     #private;

package/dist/core/interactions.svelte.js

@@ -4,7 +4,8 @@
  * 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.
  */
 export class InteractionRouter {
     // Bookkeeping only; nothing reads these reactively.
@@ -120,9 +121,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 } }
@@ -194,7 +211,7 @@ export class InteractionRouter {
     };
     #onMove = (e) => {
         const found = this.#lookup([e.point.x, e.point.y]);
-        const hit = found.blocked ? found.blocker : found.hover;
+        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);
     };

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

@@ -7,12 +7,23 @@ export interface PluginHostOptions {
     router: InteractionRouter;
     /** Reactive: read inside a plugin's effects. */
     selectedKeys(pluginId: string): ReadonlySet<string>;
+    /**
+     * Called after each queued setup run finishes (also when it had nothing to do), never after a
+     * synchronous one.
+     */
+    onSettled?: () => void;
 }
 /**
  * Runs plugins against a GL map. Plugins are set up only when the map's style is loaded, and
  * everything they add through their `PluginContext` is removed on teardown, whatever their own
  * teardown does. The plugin list outlives any one GL map.
  *
+ * Setup never runs inside the caller's code. When `add` or `attach` would set plugins up, they
+ * are queued and set up in one microtask, where no effect is active: Svelte cuts loose the
+ * `$effect.root`s created inside an effect when that effect re-runs, and their effects can stop
+ * (see docs/superpowers/specs/2026-11-07-plugin-setup-outside-effects-design.md). Setup on a
+ * style load or `restyle` comes from map events, not host code, and stays synchronous.
+ *
  * Plugins draw in list order, later on top: each plugin's layers stay together, below the first
  * layer of the next plugin in the list that has any.
  */
@@ -21,9 +32,12 @@ export declare class PluginHost {
     constructor(opts: PluginHostOptions);
     /** In draw order, bottom first. Reactive. */
     get plugins(): readonly MapPlugin[];
+    /** True while a setup run is queued and has not started. Not reactive. */
+    get pending(): boolean;
     /**
-     * Adds `plugin` on top, or just below the plugin `before` names. Throws when the same plugin
-     * object is set up on another map at the moment (one plugin object per map).
+     * Adds `plugin` on top, or just below the plugin `before` names. It is in `plugins` at once;
+     * on a live map its setup runs in a microtask. Throws when the same plugin object is set up on
+     * another map at the moment (one plugin object per map).
      */
     add(plugin: MapPlugin, before?: string): void;
     /**
@@ -32,14 +46,21 @@ export declare class PluginHost {
      */
     move(id: string, before?: string): void;
     remove(id: string): void;
-    /** Uses `gl` from now on, setting up every plugin once its style is loaded. */
+    /**
+     * Uses `gl` from now on, setting up every plugin once its style is loaded (in a microtask when
+     * it already is).
+     */
     attach(gl: GlMapLike): void;
     /**
      * Tears every plugin down and stops waiting for a style, before the map's style is replaced:
      * nothing may touch a style on its way out. `restyle` sets them up again.
      */
     suspend(): void;
-    /** Tears down and sets up every plugin again (after a basemap change), once the style loads. */
+    /**
+     * 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).
+     */
     restyle(): void;
     /** Tears down every plugin. The gl is not touched after this returns. */
     detach(): void;

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

@@ -19,6 +19,12 @@ function ownershipError(plugin) {
  * everything they add through their `PluginContext` is removed on teardown, whatever their own
  * teardown does. The plugin list outlives any one GL map.
  *
+ * Setup never runs inside the caller's code. When `add` or `attach` would set plugins up, they
+ * are queued and set up in one microtask, where no effect is active: Svelte cuts loose the
+ * `$effect.root`s created inside an effect when that effect re-runs, and their effects can stop
+ * (see docs/superpowers/specs/2026-11-07-plugin-setup-outside-effects-design.md). Setup on a
+ * style load or `restyle` comes from map events, not host code, and stays synchronous.
+ *
  * Plugins draw in list order, later on top: each plugin's layers stay together, below the first
  * layer of the next plugin in the list that has any.
  */
@@ -36,6 +42,8 @@ export class PluginHost {
      * a style that already loaded while `isStyleLoaded()` is false because sources are loading.
      */
     #onStyleLoad = null;
+    /** True from scheduling a queued setup run until it starts. */
+    #setupQueued = false;
     constructor(opts) {
         this.#opts = opts;
     }
@@ -43,6 +51,10 @@ export class PluginHost {
     get plugins() {
         return this.#plugins;
     }
+    /** True while a setup run is queued and has not started. Not reactive. */
+    get pending() {
+        return this.#setupQueued;
+    }
     /**
      * The host's own reads are untracked, so calling `add`, `attach`, etc. from inside an effect
      * doesn't make that effect depend on the plugin list.
@@ -51,8 +63,9 @@ export class PluginHost {
         return untrack(() => this.#plugins);
     }
     /**
-     * Adds `plugin` on top, or just below the plugin `before` names. Throws when the same plugin
-     * object is set up on another map at the moment (one plugin object per map).
+     * Adds `plugin` on top, or just below the plugin `before` names. It is in `plugins` at once;
+     * on a live map its setup runs in a microtask. Throws when the same plugin object is set up on
+     * another map at the moment (one plugin object per map).
      */
     add(plugin, before) {
         if (this.#list.some((p) => p.id === plugin.id)) {
@@ -62,7 +75,7 @@ export class PluginHost {
             throw ownershipError(plugin);
         this.#plugins = this.#inserted(this.#list, plugin, before);
         if (this.#live)
-            this.#setup(plugin);
+            this.#queueSetup();
     }
     /**
      * Moves a plugin to the top, or just below the plugin `before` names, with its layers. Does
@@ -120,16 +133,22 @@ export class PluginHost {
         if (!this.#list.some((p) => p.id === id))
             return;
         this.#teardown(id);
+        const plugin = this.#list.find((p) => p.id === id);
+        if (plugin)
+            this.#release(plugin);
         this.#plugins = this.#list.filter((p) => p.id !== id);
     }
-    /** Uses `gl` from now on, setting up every plugin once its style is loaded. */
+    /**
+     * Uses `gl` from now on, setting up every plugin once its style is loaded (in a microtask when
+     * it already is).
+     */
     attach(gl) {
         if (this.#gl === gl)
             return;
         if (this.#gl)
             this.detach();
         this.#gl = gl;
-        this.#whenStyleLoaded();
+        this.#whenStyleLoaded(false);
     }
     /**
      * Tears every plugin down and stops waiting for a style, before the map's style is replaced:
@@ -141,12 +160,16 @@ export class PluginHost {
         this.#cancelStyleWait();
         this.#teardownAll();
     }
-    /** Tears down and sets up every plugin again (after a basemap change), once the style loads. */
+    /**
+     * 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).
+     */
     restyle() {
         if (!this.#gl)
             return;
         this.#teardownAll();
-        this.#whenStyleLoaded();
+        this.#whenStyleLoaded(true);
     }
     /** Tears down every plugin. The gl is not touched after this returns. */
     detach() {
@@ -157,11 +180,22 @@ export class PluginHost {
         this.#teardownAll();
         this.#gl = null;
     }
-    #whenStyleLoaded() {
+    /**
+     * Sets every plugin up once the style is loaded. On a style that already is, `now` sets them up
+     * synchronously (only for callers that never run inside an effect); otherwise they are queued.
+     */
+    #whenStyleLoaded(now) {
         const gl = this.#gl;
         this.#cancelStyleWait();
         if (gl.isStyleLoaded()) {
-            this.#setupAll();
+            if (now) {
+                this.#setupAll();
+            }
+            else {
+                // Live already, so an `add` before the microtask joins the queued run.
+                this.#live = true;
+                this.#queueSetup();
+            }
             return;
         }
         const onStyleLoad = () => {
@@ -175,6 +209,37 @@ export class PluginHost {
         for (const type of STYLE_READY_EVENTS)
             gl.on(type, onStyleLoad);
     }
+    /**
+     * Sets every plugin that isn't running up in a microtask, on whichever gl is live by then.
+     * Detach, suspend, and restyle clear `#live`, and only a loaded current gl sets it again, so
+     * the run never touches a gl that left. One run covers every request made before it starts.
+     */
+    #queueSetup() {
+        // Claim the queued plugins now, so another map can't take one before the run.
+        for (const plugin of this.#list)
+            this.#claim(plugin);
+        if (this.#setupQueued)
+            return;
+        this.#setupQueued = true;
+        queueMicrotask(() => {
+            this.#setupQueued = false;
+            if (this.#live)
+                this.#setupAll();
+            this.#opts.onSettled?.();
+        });
+    }
+    /** Marks `plugin` as this host's, unless another map holds it. */
+    #claim(plugin) {
+        if (!ownedElsewhere(plugin, this) && Object.isExtensible(plugin)) {
+            plugin[OWNER] = this;
+        }
+    }
+    /** Releases a plugin this host claimed but isn't running (queued, then removed or left). */
+    #release(plugin) {
+        const owned = plugin;
+        if (owned[OWNER] === this && !this.#running.has(plugin.id))
+            delete owned[OWNER];
+    }
     #cancelStyleWait() {
         const listener = this.#onStyleLoad;
         if (listener && this.#gl) {
@@ -202,8 +267,10 @@ export class PluginHost {
     }
     #teardownAll() {
         this.#live = false;
-        for (const plugin of this.#list)
+        for (const plugin of this.#list) {
             this.#teardown(plugin.id);
+            this.#release(plugin);
+        }
     }
     #setup(plugin) {
         const gl = this.#gl;
@@ -225,7 +292,8 @@ export class PluginHost {
         const ctx = this.#context(plugin.id, running);
         let teardown;
         try {
-            // Untracked: setup may be called from inside an effect (e.g. MapView's).
+            // Untracked, in case a plugin's setup reads state (setup runs from a microtask or a map
+            // event, never inside the caller's effect).
             teardown = untrack(() => plugin.setup(ctx));
         }
         catch (error) {

package/dist/core/plugin.d.ts

@@ -48,6 +48,12 @@ export interface FeatureListItem {
     precision?: number;
     lngLat: [number, number];
     selectable: boolean;
+    /**
+     * A short text about a feature with no level (e.g. "Level 2 charger"), shown where its level
+     * would be: in the feature list, its row's accessible name, and the generic tooltip. Ignored
+     * when the item has a level.
+     */
+    detail?: string;
 }
 export type LegendData = {
     pluginId: string;
@@ -128,8 +134,9 @@ export interface MapPlugin {
     selectable?: boolean;
     /**
      * Which plugin's feature the hover tooltip shows where several are under the pointer: the
-     * highest wins, the topmost on a tie. Default 0. A blocking layer on top still hides what is
-     * beneath it, and clicks ignore this (topmost first).
+     * highest wins, the topmost on a tie. Default 0. Over a blocking layer (a cluster bubble), a
+     * feature beneath shows only if its plugin's priority is higher than the blocking plugin's.
+     * Clicks ignore this (topmost first), and a blocking layer on top still blocks them.
      */
     hoverPriority?: number;
     displayOptions?: Snippet;

package/dist/data/messages/en.json

@@ -8,6 +8,7 @@
 	"mapsdk_list_row": "{name}, {value} {units}, {level}",
 	"mapsdk_list_row_no_units": "{name}, {value}, {level}",
 	"mapsdk_list_row_no_value": "{name}, no reading",
+	"mapsdk_list_row_detail": "{name}, {detail}",
 	"mapsdk_list_empty": "Nothing on the map in this view",
 	"mapsdk_selected_count_one": "{count} selected",
 	"mapsdk_selected_count_other": "{count} selected",

package/dist/plugins/points.svelte.d.ts

@@ -60,8 +60,9 @@ export interface PointsOptions<P extends MapFeatureProperties> {
     sortKey?(props: P): number;
     /**
      * Limits every layer the plugin draws (points, clusters, selection) to a zoom range: visible
-     * from `min` (inclusive) up to `max` (exclusive). Set on the layers, so it switches live while
-     * zooming. Default: all zooms.
+     * from `min` (inclusive) up to `max` (exclusive) of the camera zoom, switching live while
+     * zooming (layer visibility, not layer zoom ranges, so ranges that meet leave no gap on a
+     * globe). Default: all zooms.
      */
     zoomRange?: {
         min?: number;
@@ -75,6 +76,12 @@ export interface PointsOptions<P extends MapFeatureProperties> {
      * it loads.
      */
     legendTitle?: "layer" | "entry-type";
+    /**
+     * A short text for a feature with no level (e.g. "Level 2 charger"), shown in the feature list,
+     * its accessible name, and the generic tooltip where "No level" would be. Ignored for a
+     * feature with a level.
+     */
+    detail?(props: P): string | undefined;
     /** Whether `features()` lists this plugin's features. Default true. */
     listed?: boolean;
     /** Tooltip content for a feature, below its name; `props` are its source properties. */

package/dist/plugins/points.svelte.js

@@ -93,6 +93,7 @@ export function pointsPlugin(options) {
             if (!ref)
                 continue;
             const [lng, lat] = geometry.coordinates;
+            const detail = options.detail?.(props)?.trim();
             items.push({
                 refKey: props.refKey,
                 ref,
@@ -102,7 +103,8 @@ export function pointsPlugin(options) {
                 units: scale?.units ?? "",
                 precision,
                 lngLat: [lng, lat],
-                selectable: selectable && selectionId(ref) !== null
+                selectable: selectable && selectionId(ref) !== null,
+                ...(detail ? { detail } : {})
             });
         }
         return items;
@@ -209,15 +211,39 @@ export function pointsPlugin(options) {
             }
             return spec;
         }
-        /** The spec limited to the plugin's zoom range. */
+        // The zoom range shows and hides the layers by the camera zoom, not with layer
+        // minzoom/maxzoom: on a globe MapLibre uses the next zoom's tiles a little before the camera
+        // gets there and leaves a layer out of tiles at or above its maxzoom, so two plugins whose
+        // ranges meet (fire groups below 10, hotspots from 10) would leave a gap where neither drew.
+        const { min, max } = options.zoomRange ?? {};
+        const ranged = min !== undefined || max !== undefined;
+        const inRange = () => {
+            const zoom = gl.getZoom();
+            return (min === undefined || zoom >= min) && (max === undefined || zoom < max);
+        };
+        let shown = ranged ? inRange() : true;
+        /** The spec, hidden while the camera is outside the plugin's zoom range. */
         function zoomed(spec) {
-            const { min, max } = options.zoomRange ?? {};
+            if (!ranged)
+                return spec;
+            const layout = spec.layout;
             return {
                 ...spec,
-                ...(min !== undefined ? { minzoom: min } : {}),
-                ...(max !== undefined ? { maxzoom: max } : {})
+                layout: { ...layout, visibility: shown ? "visible" : "none" }
             };
         }
+        const onZoom = () => {
+            if (dead || inRange() === shown)
+                return;
+            shown = !shown;
+            for (const layerId of layers) {
+                if (gl.getLayer(layerId)) {
+                    gl.setLayoutProperty(layerId, "visibility", shown ? "visible" : "none");
+                }
+            }
+        };
+        if (ranged)
+            gl.on("zoom", onZoom);
         function removeLayers() {
             for (const layerId of layers.toReversed()) {
                 if (gl.getLayer(layerId))
@@ -447,6 +473,8 @@ export function pointsPlugin(options) {
         });
         return () => {
             dead = true;
+            if (ranged)
+                gl.off("zoom", onZoom);
             providers = null;
             live = null;
         };

package/dist/ui/FeatureList.svelte

@@ -9,6 +9,7 @@
 		inView,
 		optionIdPart,
 		rowLabel,
+		levelText,
 		shownLevel,
 		sortItems,
 		typeaheadIndex,
@@ -330,6 +331,7 @@
 			{#each windowRows as row, i (row.key)}
 				{@const index = range.start + i}
 				{@const level = shownLevel(row)}
+				{@const levelPlace = levelText(row, map.messages)}
 				{@const isOn = isSelected(row)}
 				<!-- Options aren't focused: the listbox holds focus and handles keys (aria-activedescendant). -->
 				<!-- svelte-ignore a11y_click_events_have_key_events, a11y_interactive_supports_focus -->
@@ -360,12 +362,14 @@
 						{formatValue(row)}{#if row.units && row.value !== null}&nbsp;{row.units}{/if}
 					</span>
 					<span class="mapsdk-list-level text-xs">
-						<span
-							class="mapsdk-list-swatch"
-							class:neutral={!level?.color}
-							style:background={level?.color || undefined}
-						></span>
-						{level ? level.label : map.messages("mapsdk_no_level")}
+						{#if levelPlace.kind !== "detail"}
+							<span
+								class="mapsdk-list-swatch"
+								class:neutral={!level?.color}
+								style:background={level?.color || undefined}
+							></span>
+						{/if}
+						{levelPlace.text}
 					</span>
 				</div>
 			{/each}

package/dist/ui/Legend.svelte

@@ -1,5 +1,5 @@
 <script lang="ts">
-	import { onMount } from "svelte";
+	import { onMount, untrack } from "svelte";
 	import "./controls.css";
 	import type { MapContext } from "../core/create-map.svelte.js";
 	import { watchTheme } from "../view/create-gl-map.js";
@@ -8,9 +8,19 @@
 
 	let {
 		map,
-		order = "bottom-first"
+		order = "bottom-first",
+		framed = true
 	}: {
 		map: MapContext;
+		/**
+		 * `true` (default) draws the legend's own card. `false` draws no frame (no border,
+		 * background, padding, or fixed width) so a host's card frames it. Translucent swatches
+		 * then blend over the nearest ancestor with an opaque background (a see-through card is
+		 * skipped), else the `--background` token. The color is read on mount, when `framed`
+		 * changes, and on a theme change; a card that changes color through its own class or
+		 * style isn't re-read.
+		 */
+		framed?: boolean;
 		/**
 		 * `"bottom-first"` (default) lists the bottom plugin's section first; `"top-first"`
 		 * last.
@@ -43,30 +53,50 @@
 		)
 	);
 
-	/** Computed colors can be oklch() or color(); a 1x1 canvas turns any of them into rgb. */
-	function resolveBackground(el: Element): string {
-		const css = getComputedStyle(el).backgroundColor;
+	/**
+	 * A computed color as rgb and whether it's opaque; computed colors can be oklch() or color(),
+	 * and a 1x1 canvas turns any of them into rgb.
+	 */
+	function toRgb(css: string): { rgb: string; opaque: boolean } {
 		const ctx = document.createElement("canvas").getContext("2d");
-		if (!ctx) return css;
+		if (!ctx) return { rgb: css, opaque: true };
 		ctx.clearRect(0, 0, 1, 1);
 		ctx.fillStyle = css;
 		ctx.fillRect(0, 0, 1, 1);
-		const [r, g, b] = ctx.getImageData(0, 0, 1, 1).data;
-		return `rgb(${r}, ${g}, ${b})`;
+		const [r, g, b, a] = ctx.getImageData(0, 0, 1, 1).data;
+		return { rgb: `rgb(${r}, ${g}, ${b})`, opaque: a === 255 };
 	}
 
-	onMount(() => {
-		const update = () => {
-			if (root) background = resolveBackground(root);
-		};
-		update();
-		return watchTheme(root!, update);
+	/**
+	 * What translucent swatches blend over: the legend's own card, or without a frame the nearest
+	 * ancestor with an opaque background (the host's card), else the `--background` token.
+	 */
+	function resolveBackground(el: HTMLElement, frameless: boolean): string {
+		if (!frameless) return toRgb(getComputedStyle(el).backgroundColor).rgb;
+		for (let at = el.parentElement; at; at = at.parentElement) {
+			const color = toRgb(getComputedStyle(at).backgroundColor);
+			if (color.opaque) return color.rgb;
+		}
+		// A computed custom property has its var() references already substituted.
+		return toRgb(getComputedStyle(el).getPropertyValue("--background").trim()).rgb;
+	}
+
+	function update() {
+		if (root) background = resolveBackground(root, !framed);
+	}
+
+	onMount(() => watchTheme(root!, update));
+
+	// On mount, and again when `framed` changes.
+	$effect(() => {
+		void framed;
+		untrack(update);
 	});
 </script>
 
 <section
 	bind:this={root}
-	class="mapsdk-legend"
+	class={["mapsdk-legend", !framed && "mapsdk-legend-frameless"]}
 	aria-label={map.messages("mapsdk_legend_label")}
 	hidden={entries.length === 0}
 >
@@ -124,6 +154,17 @@
 		pointer-events: auto;
 	}
 
+	/* framed={false}: the host's card is the frame. */
+	.mapsdk-legend-frameless {
+		width: auto;
+		max-width: none;
+		padding: 0;
+		border: 0;
+		border-radius: 0;
+		background: none;
+		box-shadow: none;
+	}
+
 	.mapsdk-legend[hidden] {
 		display: none;
 	}

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

@@ -2,6 +2,15 @@ import "./controls.css";
 import type { MapContext } from "../core/create-map.svelte.js";
 type $$ComponentProps = {
     map: MapContext;
+    /**
+     * `true` (default) draws the legend's own card. `false` draws no frame (no border,
+     * background, padding, or fixed width) so a host's card frames it. Translucent swatches
+     * then blend over the nearest ancestor with an opaque background (a see-through card is
+     * skipped), else the `--background` token. The color is read on mount, when `framed`
+     * changes, and on a theme change; a card that changes color through its own class or
+     * style isn't re-read.
+     */
+    framed?: boolean;
     /**
      * `"bottom-first"` (default) lists the bottom plugin's section first; `"top-first"`
      * last.

package/dist/ui/TooltipItem.svelte

@@ -3,6 +3,7 @@
 	import type { MessageProvider } from "../data/messages.js";
 	import type { FeatureListItem } from "../core/plugin.js";
 	import { NO_LEVEL } from "../data/scale.js";
+	import { levelText } from "./feature-list.js";
 	import { levelChip } from "./level-chip.js";
 	import { formatValue } from "./value-format.js";
 
@@ -19,7 +20,8 @@
 
 	// A level with an empty color shows its label on the neutral chip.
 	const level = $derived(item.level !== NO_LEVEL ? item.level : null);
-	const levelLabel = $derived(level ? level.label : messages("mapsdk_no_level"));
+	// The level's label, else the item's detail (plain text, no chip), else "No level".
+	const levelPlace = $derived(levelText(item, messages));
 	const chipColors = $derived.by(() => {
 		const chip = levelChip(level?.color);
 		return chip ? `background:${chip.background};color:${chip.text}` : "";
@@ -39,9 +41,13 @@
 			{valueText}{#if item.units} {item.units}{/if}
 		</div>
 	{/if}
-	<span class="mapsdk-tooltip-chip text-xs" class:neutral={!chipColors} style={chipColors}>
-		{levelLabel}
-	</span>
+	{#if levelPlace.kind === "detail"}
+		<span class="mapsdk-tooltip-detail text-xs">{levelPlace.text}</span>
+	{:else}
+		<span class="mapsdk-tooltip-chip text-xs" class:neutral={!chipColors} style={chipColors}>
+			{levelPlace.text}
+		</span>
+	{/if}
 </div>
 
 <style>

package/dist/ui/feature-list.d.ts

@@ -27,5 +27,12 @@ export declare function shownLevel(item: FeatureListItem): Level | null;
 export declare function sortItems(items: FeatureListItem[], by: SortBy): FeatureListItem[];
 /** The first index at or after `from` (wrapping) whose name starts with `query`, any case; -1 if none. */
 export declare function typeaheadIndex(items: FeatureListItem[], query: string, from: number): number;
-/** A row's accessible name: name, value, units, and level label. */
+/**
+ * What stands in an item's level place: its level's label, else its `detail`, else "No level".
+ */
+export declare function levelText(item: FeatureListItem, messages: MessageProvider): {
+    kind: "level" | "detail" | "none";
+    text: string;
+};
+/** A row's accessible name: name, value, units, and level label (or detail). */
 export declare function rowLabel(item: FeatureListItem, messages: MessageProvider, format: FormatProvider): string;

package/dist/ui/feature-list.js

@@ -65,16 +65,31 @@ export function typeaheadIndex(items, query, from) {
     }
     return -1;
 }
-/** A row's accessible name: name, value, units, and level label. */
-export function rowLabel(item, messages, format) {
-    if (item.value === null)
-        return messages("mapsdk_list_row_no_value", { name: item.name });
+/**
+ * What stands in an item's level place: its level's label, else its `detail`, else "No level".
+ */
+export function levelText(item, messages) {
     const level = shownLevel(item);
+    if (level)
+        return { kind: "level", text: level.label };
+    const detail = item.detail?.trim();
+    if (detail)
+        return { kind: "detail", text: detail };
+    return { kind: "none", text: messages("mapsdk_no_level") };
+}
+/** A row's accessible name: name, value, units, and level label (or detail). */
+export function rowLabel(item, messages, format) {
+    const level = levelText(item, messages);
+    if (item.value === null) {
+        return level.kind === "detail"
+            ? messages("mapsdk_list_row_detail", { name: item.name, detail: level.text })
+            : messages("mapsdk_list_row_no_value", { name: item.name });
+    }
     const params = {
         name: item.name,
         value: typeof item.value === "number" ? formatValue(item.value, item.precision, format) : item.value,
         units: item.units,
-        level: level ? level.label : messages("mapsdk_no_level")
+        level: level.text
     };
     return messages(item.units ? "mapsdk_list_row" : "mapsdk_list_row_no_units", params);
 }

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.1",
+	"version": "0.1.0-beta.3",
 	"license": "MIT",
 	"repository": {
 		"type": "git",