Backport improvements that were created during creation of gcds-map:

- Implement layer "registry" for child (Leaflet) layers in BaseLayerElement, HTMLFeatureElement, and HTMLTileElement to optimize layer management and cleanup.
- Update HTMLMapCaptionElement to ensure only the first caption manages the aria-label.
- Refactor rendering logic in renderStyles.js to improve handling of SVG and container elements.
- Adjust event handling in HTMLWebMapElement and HTMLLinkElement for better performance and reliability.
- Update test cases to ensure proper navigation and loading states.

Author: prushforth

src/layer.js

@@ -215,6 +215,9 @@ export class BaseLayerElement extends HTMLElement {
       lc.removeLayer(l);
     }
     // remove properties of layer involved in whenReady() logic
+    if (this._layerRegistry) {
+      this._layerRegistry.clear();
+    }
     delete this._layer;
     delete this._layerControl;
     delete this._layerControlHTML;
@@ -228,6 +231,18 @@ export class BaseLayerElement extends HTMLElement {
     /* jshint ignore:start */
     this.#hasConnected = true;
     /* jshint ignore:end */
+    // _layerRegistry tracks child MapFeatureLayer and MapTileLayer instances
+    // by their calculated DOM position (z-index). Adjacent <map-feature> or
+    // <map-tile> elements share a single Leaflet layer; the first in a sequence
+    // creates it and registers here with count=1. Subsequent siblings look up
+    // the entry and increment count. On disconnect, count is decremented;
+    // when it reaches 0 the entry is deleted and the Leaflet layer is removed.
+    // This replaces fragile DOM sibling traversal (getPrevious()) with O(1)
+    // lookup and proper reference counting for cleanup.
+    // map-link.js uses the same pattern for its templated child layers.
+    if (!this._layerRegistry) {
+      this._layerRegistry = new Map();
+    }
     this._createLayerControlHTML = createLayerControlHTML.bind(this);
     const doConnected = this._onAdd.bind(this);
     const doRemove = this._onRemove.bind(this);

src/map-caption.js

@@ -13,37 +13,47 @@ export class HTMLMapCaptionElement extends HTMLElement {
       this.parentElement.nodeName === 'MAPML-VIEWER' ||
       this.parentElement.nodeName === 'MAP'
     ) {
-      // calls MutationObserver; needed to observe changes to content between <map-caption> tags and update to aria-label
-      let mapcaption =
-        this.parentElement.querySelector('map-caption').textContent;
+      setTimeout(() => {
+        // Only the first map-caption child should manage the aria-label
+        const firstMapCaption = this.parentElement.querySelector('map-caption');
+        const isFirstCaption = firstMapCaption === this;
 
-      this.observer = new MutationObserver(() => {
-        let mapcaptionupdate =
+        if (!isFirstCaption) {
+          return;
+        }
+
+        // calls MutationObserver; needed to observe changes to content between <map-caption> tags and update to aria-label
+        let mapcaption =
           this.parentElement.querySelector('map-caption').textContent;
 
-        if (mapcaptionupdate !== mapcaption) {
-          this.parentElement.setAttribute(
-            'aria-label',
-            this.parentElement.querySelector('map-caption').textContent
-          );
-        }
-      });
+        this.observer = new MutationObserver(() => {
+          let mapcaptionupdate =
+            this.parentElement.querySelector('map-caption').textContent;
 
-      this.observer.observe(this, {
-        characterData: true,
-        subtree: true,
-        attributes: true,
-        childList: true
-      });
+          if (mapcaptionupdate !== mapcaption) {
+            this.parentElement.setAttribute(
+              'aria-label',
+              this.parentElement.querySelector('map-caption').textContent
+            );
+          }
+        });
 
-      // don't change aria-label if one already exists from user  (checks when element is first created)
-      if (!this.parentElement.hasAttribute('aria-label')) {
-        const ariaLabel = this.textContent;
-        this.parentElement.setAttribute('aria-label', ariaLabel);
-      }
+        this.observer.observe(this, {
+          characterData: true,
+          subtree: true,
+          attributes: true,
+          childList: true
+        });
+
+        // don't change aria-label if one already exists from user  (checks when element is first created)
+        if (!this.parentElement.hasAttribute('aria-label')) {
+          const ariaLabel = this.textContent;
+          this.parentElement.setAttribute('aria-label', ariaLabel);
+        }
+      }, 0);
     }
   }
   disconnectedCallback() {
-    this.observer.disconnect();
+    if (this.observer) this.observer.disconnect();
   }
 }

src/map-feature.js

@@ -221,6 +221,14 @@ export class HTMLFeatureElement extends HTMLElement {
     )
       return;
     this._observer.disconnect();
+    // Decrement layer registry count
+    const entry = this._parentEl?._layerRegistry?.get(this.position);
+    if (entry) {
+      entry.count--;
+      if (entry.count === 0) {
+        this._parentEl._layerRegistry.delete(this.position);
+      }
+    }
     if (this._featureLayer) {
       this.removeFeature(this._featureLayer);
       // If this was the last feature in the layer, clean up the layer
@@ -290,16 +298,7 @@ export class HTMLFeatureElement extends HTMLElement {
     this._setUpEvents();
   }
   isFirst() {
-    // Get the previous element sibling
-    const prevSibling = this.previousElementSibling;
-
-    // If there's no previous sibling, return true
-    if (!prevSibling) {
-      return true;
-    }
-
-    // Compare the node names (tag names) - return true if they're different
-    return this.nodeName !== prevSibling.nodeName;
+    return !this._parentEl._layerRegistry.has(this.position);
   }
   getPrevious() {
     // Check if this is the first element of a sequence
@@ -370,13 +369,23 @@ export class HTMLFeatureElement extends HTMLElement {
             })
           });
 
+          // Register in parent's layer registry
+          parentElement._layerRegistry.set(this.position, {
+            layer: this._featureLayer,
+            count: 1
+          });
+
           this.addFeature(this._featureLayer);
 
           // add MapFeatureLayer to appropriate parent layer
           parentLayer.addLayer(this._featureLayer);
         } else {
-          // get the previous feature's layer
-          this._featureLayer = this.getPrevious()?._featureLayer;
+          // Look up the existing layer from the registry
+          const entry = this._parentEl._layerRegistry.get(this.position);
+          this._featureLayer = entry?.layer;
+          if (entry) {
+            entry.count++;
+          }
           if (this._featureLayer) {
             this.addFeature(this._featureLayer);
           }

src/map-link.js

@@ -271,6 +271,10 @@ export class HTMLLinkElement extends HTMLElement {
       (this.parentExtent && this.parentExtent.hasAttribute('data-moving'))
     )
       return;
+    // Layer registry for child map-feature/map-tile layers — see layer.js
+    if (!this._layerRegistry) {
+      this._layerRegistry = new Map();
+    }
     switch (this.rel.toLowerCase()) {
       // for some cases, require a dependency check
       case 'tile':
@@ -321,6 +325,9 @@ export class HTMLLinkElement extends HTMLElement {
     // what else?
   }
   disconnectedCallback() {
+    if (this._layerRegistry) {
+      this._layerRegistry.clear();
+    }
     switch (this.rel.toLowerCase()) {
       case 'stylesheet':
         if (this._stylesheetHost) {
@@ -453,12 +460,17 @@ export class HTMLLinkElement extends HTMLElement {
       this.link.setAttribute('href', new URL(this.href, this.getBase()).href);
       copyAttributes(this, this.link);
 
-      if (this._stylesheetHost._layer) {
+      // IMPORTANT: Only render if the correct container exists for THIS element's parent.
+      // Don't fall back to _extentLayer if this is a layer child - wait for _layer instead.
+      const isLayerChild = this._stylesheetHost.tagName === 'MAP-LAYER';
+      const isExtentChild = this._stylesheetHost.tagName === 'MAP-EXTENT';
+
+      if (isLayerChild && this._stylesheetHost._layer) {
         this._stylesheetHost._layer.renderStyles(this);
+      } else if (isExtentChild && this._stylesheetHost._extentLayer) {
+        this._stylesheetHost._extentLayer.renderStyles(this);
       } else if (this._stylesheetHost._templatedLayer) {
         this._stylesheetHost._templatedLayer.renderStyles(this);
-      } else if (this._stylesheetHost._extentLayer) {
-        this._stylesheetHost._extentLayer.renderStyles(this);
       }
     }
 

src/map-style.js

@@ -70,12 +70,17 @@ export class HTMLStyleElement extends HTMLElement {
     this.styleElement.mapStyle = this;
     this.styleElement.textContent = this.textContent;
     copyAttributes(this, this.styleElement);
-    if (this._stylesheetHost._layer) {
+    // IMPORTANT: Only render if the correct container exists for THIS element's parent.
+    // Don't fall back to _extentLayer if this is a layer child - wait for _layer instead.
+    const isLayerChild = this._stylesheetHost.tagName === 'MAP-LAYER';
+    const isExtentChild = this._stylesheetHost.tagName === 'MAP-EXTENT';
+
+    if (isLayerChild && this._stylesheetHost._layer) {
       this._stylesheetHost._layer.renderStyles(this);
+    } else if (isExtentChild && this._stylesheetHost._extentLayer) {
+      this._stylesheetHost._extentLayer.renderStyles(this);
     } else if (this._stylesheetHost._templatedLayer) {
       this._stylesheetHost._templatedLayer.renderStyles(this);
-    } else if (this._stylesheetHost._extentLayer) {
-      this._stylesheetHost._extentLayer.renderStyles(this);
     }
 
     function copyAttributes(source, target) {

src/map-tile.js

@@ -135,6 +135,14 @@ export class HTMLTileElement extends HTMLElement {
   }
 
   disconnectedCallback() {
+    // Decrement layer registry count
+    const entry = this._parentEl?._layerRegistry?.get(this.position);
+    if (entry) {
+      entry.count--;
+      if (entry.count === 0) {
+        this._parentEl._layerRegistry.delete(this.position);
+      }
+    }
     // If this is a map-tile connected to a tile layer, remove it from the layer
     if (this._tileLayer) {
       this._tileLayer.removeMapTile(this);
@@ -148,16 +156,7 @@ export class HTMLTileElement extends HTMLElement {
     }
   }
   isFirst() {
-    // Get the previous element sibling
-    const prevSibling = this.previousElementSibling;
-
-    // If there's no previous sibling, return true
-    if (!prevSibling) {
-      return true;
-    }
-
-    // Compare the node names (tag names) - return true if they're different
-    return this.nodeName !== prevSibling.nodeName;
+    return !this._parentEl._layerRegistry.has(this.position);
   }
   getPrevious() {
     // Check if this is the first element of a sequence
@@ -249,6 +248,12 @@ export class HTMLTileElement extends HTMLElement {
       });
       this._tileLayer.addMapTile(this);
 
+      // Register in parent's layer registry
+      parentElement._layerRegistry.set(this.position, {
+        layer: this._tileLayer,
+        count: 1
+      });
+
       // add MapTileLayer to TemplatedFeaturesOrTilesLayer of the MapLink
       if (parentElement._templatedLayer?.addLayer) {
         parentElement._templatedLayer.addLayer(this._tileLayer);
@@ -257,8 +262,12 @@ export class HTMLTileElement extends HTMLElement {
         parentElement._layer.addLayer(this._tileLayer);
       }
     } else {
-      // get the previous tile's layer
-      this._tileLayer = this.getPrevious()?._tileLayer;
+      // Look up the existing layer from the registry
+      const entry = parentElement._layerRegistry.get(this.position);
+      this._tileLayer = entry?.layer;
+      if (entry) {
+        entry.count++;
+      }
       if (this._tileLayer) {
         this._tileLayer.addMapTile(this);
       }

src/mapml-viewer.js

@@ -420,6 +420,16 @@ export class HTMLMapmlViewerElement extends HTMLElement {
             layersReady.push(reAttach.whenReady());
           }
           return Promise.allSettled(layersReady).then(() => {
+            // For single-layer case (e.g. link traversal), synchronously set
+            // zoom constraints so that layer.zoomTo() uses correct bounds
+            const layers = this.querySelectorAll('map-layer,layer-');
+            if (layers.length === 1) {
+              const layer = layers[0];
+              if (layer.extent) {
+                this._map.setMinZoom(layer.extent.zoom.minZoom);
+                this._map.setMaxZoom(layer.extent.zoom.maxZoom);
+              }
+            }
             // use the saved map location to ensure it is correct after
             // changing the map CRS.  Specifically affects projection
             // upgrades, e.g. https://maps4html.org/experiments/custom-projections/BNG/
@@ -660,13 +670,19 @@ export class HTMLMapmlViewerElement extends HTMLElement {
   _removeEvents() {
     if (this._map) {
       this._map.off();
-      this.removeEventListener('drop', this._dropHandler, false);
-      this.removeEventListener('dragover', this._dragoverHandler, false);
+      if (this._boundDropHandler) {
+        this.removeEventListener('drop', this._boundDropHandler, false);
+      }
+      if (this._boundDragoverHandler) {
+        this.removeEventListener('dragover', this._boundDragoverHandler, false);
+      }
     }
   }
   _setUpEvents() {
-    this.addEventListener('drop', this._dropHandler, false);
-    this.addEventListener('dragover', this._dragoverHandler, false);
+    this._boundDropHandler = this._dropHandler.bind(this);
+    this._boundDragoverHandler = this._dragoverHandler.bind(this);
+    this.addEventListener('drop', this._boundDropHandler, false);
+    this.addEventListener('dragover', this._boundDragoverHandler, false);
     this.addEventListener(
       'change',
       function (e) {

src/mapml.css

@@ -447,6 +447,11 @@ and: https://developer.mozilla.org/en-US/docs/Web/CSS/:fullscreen */
   text-shadow: 1px 1px 1px #000, 1px 1px 1px #000;
 }
 
+/* Ensure white background persists in fullscreen */
+:host(.mapml-fullscreen-on) {
+  background-color: white;
+}
+
 /*
  * User interaction.
  */

src/mapml/elementSupport/layers/renderStyles.js

@@ -10,15 +10,19 @@ export function renderStyles(mapStyleOrLink) {
 
     // If there are no rendered styles or links yet, insert before any content
     if (renderedSiblingStyles.length === 0) {
-      return this._container.lastChild &&
-        (this._container.lastChild.nodeName.toUpperCase() === 'SVG' ||
-          this._container.lastChild.classList.contains(
-            'mapml-vector-container'
-          ))
-        ? { position: 'beforebegin', node: this._container.lastChild }
-        : this._container.lastChild
-        ? { position: 'afterend', node: this._container.lastChild }
-        : { position: 'afterbegin', node: this._container };
+      const lastChild = this._container.lastChild;
+      if (!lastChild) {
+        return { position: 'afterbegin', node: this._container };
+      }
+
+      const isSVG = lastChild.nodeName === 'SVG';
+      const isContainer =
+        lastChild.classList?.contains('mapml-vector-container') ||
+        lastChild.classList?.contains('mapml-extentlayer-container');
+
+      return isSVG || isContainer
+        ? { position: 'beforebegin', node: lastChild }
+        : { position: 'afterend', node: lastChild };
     }
 
     // Peek into the light DOM context for comparison

src/mapml/layers/MapFeatureLayer.js

@@ -410,12 +410,18 @@ export var MapFeatureLayer = FeatureGroup.extend({
             !geometry._map
           ) {
             this.addRendering(geometry);
-            // update the layerbounds
-            let placeholder =
-              geometry.defaultOptions.group.parentNode.querySelector(
-                `span[id="${geometry._leaflet_id}"]`
-              );
-            placeholder.replaceWith(geometry.defaultOptions.group);
+            // Only try to find placeholder if the geometry group has a parentNode
+            // If parentNode is null, the geometry is being handled by reRender()
+            // which will attach it to the DOM after _validateRendering completes
+            if (geometry.defaultOptions.group.parentNode) {
+              let placeholder =
+                geometry.defaultOptions.group.parentNode.querySelector(
+                  `span[id="${geometry._leaflet_id}"]`
+                );
+              if (placeholder) {
+                placeholder.replaceWith(geometry.defaultOptions.group);
+              }
+            }
           }
         }
       }