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

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,15 +46,26 @@ 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. */
-    restyle(): void;
+    /**
+     * 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(styleLoaded?: boolean): 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,27 @@ export class PluginHost {
         this.#cancelStyleWait();
         this.#teardownAll();
     }
-    /** Tears down and sets up every plugin again (after a basemap change), once the style loads. */
-    restyle() {
+    /**
+     * 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(styleLoaded = false) {
         if (!this.#gl)
             return;
+        const loaded = styleLoaded || this.#live;
         this.#teardownAll();
-        this.#whenStyleLoaded();
+        if (loaded) {
+            this.#cancelStyleWait();
+            this.#setupAll();
+        }
+        else {
+            this.#whenStyleLoaded(true);
+        }
     }
     /** Tears down every plugin. The gl is not touched after this returns. */
     detach() {
@@ -157,11 +191,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 +220,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 +278,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 +303,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) {
@@ -338,12 +417,12 @@ export class PluginHost {
             interactive(layerIds, toHit) {
                 if (running.dead)
                     return;
-                running.unregisters.push(router.register(pluginId, layerIds, toHit, running.plugin.hoverPriority ?? 0));
+                running.unregisters.push(router.register(pluginId, layerIds, toHit, running.plugin.hoverPriority ?? 0, running.plugin.hoverable ?? true));
             },
             blocking(layerIds, toHover, onClick) {
                 if (running.dead)
                     return;
-                running.unregisters.push(router.registerBlocking(pluginId, layerIds, toHover, onClick, running.plugin.hoverPriority ?? 0));
+                running.unregisters.push(router.registerBlocking(pluginId, layerIds, toHover, onClick, running.plugin.hoverPriority ?? 0, running.plugin.hoverable ?? true));
             },
             on(type, layerId, listener) {
                 if (running.dead)

package/dist/core/plugin.d.ts

@@ -46,8 +46,33 @@ export interface FeatureListItem {
      * metadata's display hint). Without it the value is formatted as given.
      */
     precision?: number;
+    /**
+     * Cut a numeric `value` off at `precision` instead of rounding it, so the number never reads
+     * as the next level (e.g. fire power: 9.96 MW shows "9.9", not "10.0", beside "<10"). Default
+     * false.
+     */
+    truncate?: boolean;
     lngLat: [number, number];
+    /**
+     * The feature's shape. When given, the item is in view (the feature list, the view summary)
+     * when the shape overlaps the view, not only when `lngLat` is inside it, and focusing or
+     * hovering it while `lngLat` is off-screen pins its tooltip at a point of the shape in view
+     * (focus then leaves the camera where it is).
+     */
+    geometry?: Geometry;
+    /**
+     * `geometry`'s bounding box, `[west, south, east, north]` (`geometryBbox`). Optional; computed
+     * from `geometry` when missing. A plugin listing many shapes should measure it once per data
+     * load, since the list and summary test every item on every move.
+     */
+    bbox?: [number, number, 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;
@@ -65,7 +90,17 @@ export type LegendData = {
 };
 export interface ClickEvent {
     hits: FeatureHit[];
+    /** `modifier || touch`: today's "add to the selection" in multiple mode. */
     additive: boolean;
+    /** Shift, ⌘, or Ctrl was held. */
+    modifier: boolean;
+    /** A touch tap. */
+    touch: boolean;
+    /**
+     * A Shift-click that MapLibre's box zoom swallowed (it fires `boxzoomcancel` instead of
+     * `click`). Only `"modifier"` mode acts on it, so other maps behave as before.
+     */
+    boxZoom?: boolean;
     lngLat: [number, number];
 }
 /**
@@ -128,10 +163,17 @@ 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;
+    /**
+     * False: the plugin's features never take the hover (so no hover tooltip and no pointer
+     * cursor) and never hide a feature beneath from it, as if they weren't rendered. Clicks,
+     * `featuresAt`, and keyboard focus from the list are unchanged. Default true.
+     */
+    hoverable?: boolean;
     displayOptions?: Snippet;
     /** Richer tooltip content for one of this plugin's features, below its name. */
     tooltip?(item: FeatureListItem): Snippet | undefined;

package/dist/core/shape-view.d.ts

@@ -0,0 +1,27 @@
+import type { Geometry } from "geojson";
+import type { Bounds } from "./create-map.svelte.js";
+/**
+ * Shapes against the view: a geometry's bounding box, whether it overlaps the view, and a point of
+ * it inside the view. Coordinates are planar lng/lat (as `labelPoint`); no antimeridian handling.
+ */
+/** `[west, south, east, north]`. */
+export type Bbox = [west: number, south: number, east: number, north: number];
+/** The geometry's bounding box, or `null` when it has no coordinates. */
+export declare function geometryBbox(geometry: Geometry): Bbox | null;
+/** Inside an outer ring and outside its holes, for any polygon of the geometry. */
+export declare function containsPoint(geometry: Geometry, p: [number, number]): boolean;
+/**
+ * Whether the item is in view: a shape (`geometry`) when it intersects `bounds` (bbox pre-check,
+ * then the exact test; holes count), anything else when its `lngLat` is inside. Edges included.
+ */
+export declare function intersectsBounds(item: {
+    lngLat: [number, number];
+    geometry?: Geometry;
+    bbox?: Bbox;
+}, bounds: Bounds): boolean;
+/**
+ * A point of the shape inside `view`: `center` when the shape contains it; otherwise a point well
+ * inside the shape's visible part (polygons: the largest clipped one, never in a hole; lines: the
+ * middle of the longest visible piece); `null` when nothing of it is visible.
+ */
+export declare function shapeAnchor(geometry: Geometry, view: Bounds, center: [number, number]): [number, number] | null;