From b9fa0eedcc2367a018f501688a9bd6d4e86bb956 Mon Sep 17 00:00:00 2001
From: Sameh Khamis <sameh@halfpixel.ai>
Date: Wed, 14 Oct 2026 19:23:46 -0700
Subject: [PATCH] fix(maps): stop all delivery once the controller is destroyed

A listener could destroy the controller and re-subscribe one still pending in
the snapshot, which then ran. Delivery now stops at destruction and a destroyed
controller takes no listeners. Adds ordering tests for adds, duplicates and
re-adds during delivery, and moves the current-state note after the section
intro.
---
 docs/CURRENT-STATE.md                        |  6 ++--
 src/maps/controller.js                       |  4 ++-
 src/maps/map-subscription-ownership.test.mjs | 34 ++++++++++++++++++++
 3 files changed, 41 insertions(+), 3 deletions(-)

diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index 8ecd0eae8..8474257b6 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -5209,8 +5209,6 @@ the project's MIT license; see `DATA_SOURCES.md`.
 
 ## Map source factories and coordination
 
-A subscriber removed, or a controller destroyed, during a settled-state delivery receives no further callbacks from that delivery.
-
 Map selection is composed from separate imagery, terrain and 3D factories.
 The default registry retains Google 3D, Bing Aerial/Labels, Esri Satellite and
 OSM, including their setup guidance and existing preset/share IDs. Esri still
@@ -5218,6 +5216,10 @@ falls back to OSM on construction failure or two active tile failures, and
 credits follow the source actually displayed. Terrain remains lazy while the
 photoreal globe is hidden.
 
+Map-stack subscribers hear each settled activation once. A subscriber removed
+during a delivery, or every subscriber once the controller is destroyed, gets
+no further callback from it, and a destroyed controller accepts no new ones.
+
 Map credentials are passed to each source constructor rather than changing SDK-wide Google or ion defaults.
 
 Bing Aerial and Bing Labels resolve their ion imagery endpoint with the supplied
diff --git a/src/maps/controller.js b/src/maps/controller.js
index 6dd2720f7..2b2ea462f 100644
--- a/src/maps/controller.js
+++ b/src/maps/controller.js
@@ -131,7 +131,8 @@ export class MapSourceController {
    * @returns {() => void} Unsubscribe.
    */
   subscribe(listener) {
-    if (typeof listener !== 'function') return () => {};
+    // A destroyed controller never settles again, so it takes no listeners.
+    if (typeof listener !== 'function' || this._destroyed) return () => {};
     this._subscribers.add(listener);
     return () => {
       this._subscribers.delete(listener);
@@ -142,6 +143,7 @@ export class MapSourceController {
     if (this._destroyed || !this._subscribers.size) return;
     const state = this.getState();
     for (const listener of [...this._subscribers]) {
+      if (this._destroyed) return;
       if (!this._subscribers.has(listener)) continue;
       try {
         listener(state);
diff --git a/src/maps/map-subscription-ownership.test.mjs b/src/maps/map-subscription-ownership.test.mjs
index 638de65a2..cf0708c09 100644
--- a/src/maps/map-subscription-ownership.test.mjs
+++ b/src/maps/map-subscription-ownership.test.mjs
@@ -53,3 +53,37 @@ test('destroying the controller during delivery stops remaining listeners', asyn
   await controller.setStack('fixture');
   assert.deepEqual(calls, ['destroy']);
 });
+
+test('a listener re-added after destroy during delivery is not called', async () => {
+  const controller = fixture();
+  const calls = [];
+  const later = () => calls.push('later');
+  controller.subscribe(() => {
+    calls.push('destroy');
+    controller.destroy();
+    controller.subscribe(later);
+  });
+  controller.subscribe(later);
+  await controller.setStack('fixture');
+  assert.deepEqual(calls, ['destroy']);
+});
+
+test('delivery order: added during delivery waits, duplicates run once, re-added runs', async () => {
+  const controller = fixture();
+  const calls = [];
+  const twice = () => calls.push('twice');
+  const readded = () => calls.push('readded');
+  let offReadded;
+  controller.subscribe(() => {
+    calls.push('first');
+    controller.subscribe(() => calls.push('added-late'));
+    offReadded();
+    controller.subscribe(readded);
+  });
+  controller.subscribe(twice);
+  controller.subscribe(twice);
+  offReadded = controller.subscribe(readded);
+  await controller.setStack('fixture');
+  assert.deepEqual(calls, ['first', 'twice', 'readded']);
+  controller.destroy();
+});