@sjvair/map-sdk 0.1.0-beta.2 → 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.
@@ -297,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.
@@ -421,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/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/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.2",
+	"version": "0.1.0-beta.3",
 	"license": "MIT",
 	"repository": {
 		"type": "git",