@kahwee/sf-map-svg 4.0.0 → 4.1.0

package/dist/data/stations.d.ts

@@ -1,4 +1,4 @@
-import type { FeatureCollection } from './types.js';
-export declare const bartStations: FeatureCollection<{
+import type { PointFeatureCollection } from './types.js';
+export declare const bartStations: PointFeatureCollection<{
     readonly name: string;
 }>;

package/dist/data/types.d.ts

@@ -60,6 +60,13 @@ export interface FeatureCollection<P = Readonly<Record<string, unknown>>> {
     };
     readonly features: readonly Feature<P>[];
 }
+export type PointFeatureCollection<P = Readonly<Record<string, unknown>>> = Omit<FeatureCollection<P>, 'features'> & {
+    readonly features: readonly (Feature<P> & {
+        readonly geometry: Extract<Geometry, {
+            readonly type: 'Point';
+        }>;
+    })[];
+};
 export type NeighborhoodSource = 'sf-find' | 'analysis' | 'realtor';
 export interface NeighborhoodProperties {
     readonly name: string;
@@ -69,7 +76,7 @@ export interface NeighborhoodProperties {
     readonly definitionSource: NeighborhoodSource;
     readonly nameSources: readonly string[];
     readonly note?: string;
-    readonly sourceCode?: string;
+    readonly sourceCode?: string | null;
     readonly realtorDistrict?: string;
 }
 export interface NeighborhoodEntry extends NeighborhoodProperties {

package/dist/src/api.d.ts

@@ -1,3 +1,3 @@
-/** v2 root: runtime and types only. Geography is always an explicit import. */
+/** Runtime and types only. Geography is always an explicit import. */
 export * from './map.js';
 export * from './static.js';

package/dist/src/api.js

@@ -1,3 +1,3 @@
-/** v2 root: runtime and types only. Geography is always an explicit import. */
+/** Runtime and types only. Geography is always an explicit import. */
 export * from './map.js';
 export * from './static.js';

package/dist/src/configuration.js

@@ -20,6 +20,8 @@ const featureKeys = [
     'clustering',
     'northArrow',
     'scaleBar',
+    'layerTransitions',
+    'districtMorph',
 ];
 export function expandMapOptions(options) {
     const record = assertOptions(options, 'map');
@@ -30,8 +32,22 @@ export function expandMapOptions(options) {
         'onMarkerActivate',
         'onOverlayActivate',
     ])
-        if (key in record)
-            throw new TypeError(`Use the v2 grouped options or map.on() instead of ${key}.`);
+        if (key in record) {
+            const replacement = appearanceKeys.includes(key)
+                ? `appearance.${key}`
+                : featureKeys.includes(key)
+                    ? `features.${key}`
+                    : key === 'onMarkerActivate'
+                        ? "map.on('markerchange', listener)"
+                        : key === 'onOverlayActivate'
+                            ? "map.on('overlayactivate', listener)"
+                            : null;
+            throw new TypeError(key === 'onMarkerActivate'
+                ? `Marker activation callbacks are not supported; use ${replacement} for selection changes.`
+                : replacement
+                    ? `Use ${replacement} instead of the flat ${key} option.`
+                    : 'interface is internal and is not a supported createMap option.');
+        }
     if (options.appearance !== undefined)
         assertOptions(options.appearance, 'appearance', appearanceKeys);
     if (options.features !== undefined)

package/dist/src/controller-types.d.ts

@@ -75,6 +75,7 @@ export interface MapController {
     configure(patch: MapConfiguration): void;
     getConfiguration(): MapConfigurationSnapshot;
     on<K extends keyof MapEvents>(type: K, listener: (detail: MapEvents[K]) => void): () => void;
+    /** Reconcile stable IDs; retained markers preserve nodes, focus, and entrance animations. */
     setMarkers(markers: readonly MapMarker[]): void;
     setOverlays(overlays: readonly MapOverlay[]): void;
     selectMarker(id: string | null, options?: CameraOptions & {

package/dist/src/district-morph.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Morph district outlines between two map years. Matching rings are resampled and aligned;
+ * a ring without a partner grows from, or shrinks into, its partner's center. The real
+ * district layers stay the exact year snapshots; this only draws a decorative overlay.
+ */
+export declare function createDistrictMorph(): {
+    stop: () => void;
+    /**
+     * `previous` maps district id to its old outline path; the new outlines are read from
+     * `layer`, which stays hidden until the morph settles into it.
+     */
+    start(layer: SVGGElement, previous: ReadonlyMap<string, string>, { duration, stroke }: {
+        duration: number;
+        stroke: string;
+    }): void;
+    readonly active: boolean;
+};

package/dist/src/district-morph.js

@@ -0,0 +1,148 @@
+const svgNamespace = 'http://www.w3.org/2000/svg';
+function rings(d) {
+    return (d.match(/M[^M]*/g) ?? [])
+        .map((piece) => {
+        const node = document.createElementNS(svgNamespace, 'path');
+        node.setAttribute('d', piece);
+        const length = node.getTotalLength();
+        const middle = node.getPointAtLength(length / 2);
+        return { length, center: [middle.x, middle.y], node };
+    })
+        .filter((ring) => ring.length > 0)
+        .sort((a, b) => b.length - a.length);
+}
+function sample(ring, count) {
+    return Array.from({ length: count }, (_, index) => {
+        const point = ring.node.getPointAtLength((ring.length * index) / count);
+        return [point.x, point.y];
+    });
+}
+/** Rotate and orient `to` so each point travels the shortest total distance. */
+function align(from, to) {
+    const count = from.length;
+    let best = Number.POSITIVE_INFINITY;
+    let bestOffset = 0;
+    let bestDirection = 1;
+    for (const direction of [1, -1]) {
+        for (let offset = 0; offset < count; offset++) {
+            let score = 0;
+            for (let index = 0; index < count; index += 4) {
+                const a = from[index];
+                const b = to[(offset + direction * index + count * 2) % count];
+                score += (a[0] - b[0]) ** 2 + (a[1] - b[1]) ** 2;
+            }
+            if (score < best) {
+                best = score;
+                bestOffset = offset;
+                bestDirection = direction;
+            }
+        }
+    }
+    return from.map((_, index) => to[(bestOffset + bestDirection * index + count * 2) % count]);
+}
+const ease = (t) => (t < 0.5 ? 4 * t ** 3 : 1 - (-2 * t + 2) ** 3 / 2);
+/**
+ * Morph district outlines between two map years. Matching rings are resampled and aligned;
+ * a ring without a partner grows from, or shrinks into, its partner's center. The real
+ * district layers stay the exact year snapshots; this only draws a decorative overlay.
+ */
+export function createDistrictMorph() {
+    let frame = 0;
+    let overlay;
+    let lines;
+    function stop() {
+        cancelAnimationFrame(frame);
+        frame = 0;
+        overlay?.remove();
+        overlay = undefined;
+        lines?.style.removeProperty('opacity');
+        lines = undefined;
+    }
+    return {
+        stop,
+        /**
+         * `previous` maps district id to its old outline path; the new outlines are read from
+         * `layer`, which stays hidden until the morph settles into it.
+         */
+        start(layer, previous, { duration, stroke }) {
+            stop();
+            const next = new Map([...layer.querySelectorAll('path[data-district]')].map((path) => [
+                path.dataset.district ?? '',
+                path.getAttribute('d') ?? '',
+            ]));
+            const group = document.createElementNS(svgNamespace, 'g');
+            group.dataset.layer = 'district-morph';
+            group.setAttribute('aria-hidden', 'true');
+            group.style.pointerEvents = 'none';
+            const clip = layer.getAttribute('clip-path');
+            if (clip)
+                group.setAttribute('clip-path', clip);
+            const tracks = [];
+            for (const id of new Set([...previous.keys(), ...next.keys()])) {
+                const before = rings(previous.get(id) ?? '');
+                const after = rings(next.get(id) ?? '');
+                for (let index = 0; index < Math.max(before.length, after.length); index++) {
+                    const start = before[index];
+                    const end = after[index];
+                    if (!start && !end)
+                        continue;
+                    const count = Math.min(360, Math.max(48, Math.ceil(Math.max(start?.length ?? 0, end?.length ?? 0) / 3)));
+                    const from = start
+                        ? sample(start, count)
+                        : Array.from({ length: count }, () => end.center);
+                    const target = end
+                        ? sample(end, count)
+                        : Array.from({ length: count }, () => start.center);
+                    const node = document.createElementNS(svgNamespace, 'path');
+                    for (const [name, value] of Object.entries({
+                        fill: 'none',
+                        stroke,
+                        'stroke-width': '1.6',
+                        'stroke-linejoin': 'round',
+                        'vector-effect': 'non-scaling-stroke',
+                    }))
+                        node.setAttribute(name, value);
+                    group.append(node);
+                    tracks.push({ node, from, to: start && end ? align(from, target) : target });
+                }
+            }
+            if (!tracks.length)
+                return;
+            overlay = group;
+            lines = layer;
+            layer.after(group);
+            layer.style.opacity = '0';
+            let begin;
+            const draw = (progress) => {
+                const t = ease(progress);
+                for (const track of tracks) {
+                    let d = '';
+                    for (let index = 0; index < track.from.length; index++) {
+                        const [ax, ay] = track.from[index];
+                        const [bx, by] = track.to[index];
+                        d += `${index ? 'L' : 'M'}${(ax + (bx - ax) * t).toFixed(2)},${(ay + (by - ay) * t).toFixed(2)}`;
+                    }
+                    track.node.setAttribute('d', `${d}Z`);
+                }
+                // The morph hands over to the exact outlines in its final quarter.
+                const settle = Math.max(0, (progress - 0.75) / 0.25);
+                group.style.opacity = String(1 - settle);
+                layer.style.opacity = String(settle);
+            };
+            draw(0);
+            const tick = (time) => {
+                begin ??= time;
+                const progress = Math.min(1, (time - begin) / duration);
+                draw(progress);
+                if (progress < 1)
+                    frame = requestAnimationFrame(tick);
+                else
+                    stop();
+            };
+            frame = requestAnimationFrame(tick);
+        },
+        get active() {
+            return overlay !== undefined;
+        },
+    };
+}

package/dist/src/explorer-core.js

@@ -1,13 +1,16 @@
 import { createCamera, validateCameraOptions } from './camera.js';
 import { clusterPoints } from './clusters.js';
 import { renderDistrictAppearance } from './district-layer.js';
+import { createDistrictMorph } from './district-morph.js';
 import { prepareDistrictStyles } from './district-style.js';
 import { createDistrictTransition } from './district-transition.js';
 import { element, svgElement } from './dom.js';
 import { fitBounds, interiorAnchor, projectedBounds } from './explorer-layout.js';
 import { controlKeys, layerKeys, normalizeFeatures, validateSwitchPatch } from './features.js';
+import { createFrameScheduler } from './frame-scheduler.js';
 import { geometryPath } from './geometry.js';
 import { createLabelRenderer } from './label-renderer.js';
+import { createLayerTransitions } from './layer-transition.js';
 import { createSFMapWithData, districtColors, getLayerPathsWithData } from './map-core.js';
 import { createMarkerLayer } from './marker-layer.js';
 import { attachNavigation } from './navigation.js';
@@ -29,7 +32,7 @@ let explorerCount = 0;
 /** Create an offline, browser-only neighborhood explorer. Call destroy() before disposal. */
 export function createNeighborhoodExplorerCore(options = {}, data) {
     validateExplorerOptions(options);
-    let { source = 'realtor', mode = 'neighborhoods', labels = true, neighborhood, year = 2022, theme = 'transit', colors = {}, labelStyle = {}, areaStyle = {}, districtStyle: initialDistrictStyle, motion = false, markerEntrance = false, selectedMarkerRing, clustering = false, legend: legendOptions = {}, attribution: attributionMode = 'full', northArrow = false, scaleBar = false, interface: chrome = 'explorer', layers = {}, selectableNeighborhoods = true, labelSize = {}, fitPadding = 24, markers: initialMarkers = [], markerRadius = 6, markerHitSize = 44, markerColor = colors.marker ?? '#245b61', selectedMarkerColor = colors.selected ?? '#f04f32', onMarkerActivate, overlays: initialOverlays = [], onOverlayActivate, style: styleOptions = {}, strings = {}, controls = {}, } = options;
+    let { source = 'realtor', mode = 'neighborhoods', labels = true, neighborhood, year = 2022, theme = 'transit', colors = {}, labelStyle = {}, areaStyle = {}, districtStyle: initialDistrictStyle, motion = false, markerEntrance = false, selectedMarkerRing, clustering = false, legend: legendOptions = {}, attribution: attributionMode = 'full', northArrow = false, scaleBar = false, layerTransitions = false, districtMorph: districtMorphOption = false, interface: chrome = 'explorer', layers = {}, selectableNeighborhoods = true, labelSize = {}, fitPadding = 24, markers: initialMarkers = [], markerRadius = 6, markerHitSize = 44, markerColor = colors.marker ?? '#245b61', selectedMarkerColor = colors.selected ?? '#f04f32', onMarkerActivate, overlays: initialOverlays = [], onOverlayActivate, style: styleOptions = {}, strings = {}, controls = {}, } = options;
     if (!['neighborhoods', 'districts', 'basemap'].includes(mode))
         throw new RangeError(`Unknown map mode: ${mode}`);
     if (chrome !== 'explorer' && chrome !== 'map')
@@ -49,6 +52,8 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
         selectedMarkerRing,
         northArrow,
         scaleBar,
+        layerTransitions,
+        districtMorph: districtMorphOption,
     });
     if (labelStyle.fontWeight !== undefined &&
         (!Number.isFinite(labelStyle.fontWeight) ||
@@ -434,6 +439,13 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
             root.dispatchEvent(new CustomEvent('districtchange', { bubbles: true, detail: districtSelection(id) }));
         return true;
     }
+    function activateDistrict(id) {
+        const revision = districtRevision + 1;
+        if (!selectDistrict(id) || destroyed || revision !== districtRevision)
+            return false;
+        root.dispatchEvent(new CustomEvent('districtactivate', { bubbles: true, detail: districtSelection(id) }));
+        return !destroyed && revision === districtRevision;
+    }
     function setDistrictStyle(style) {
         if (destroyed)
             return;
@@ -444,6 +456,12 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
         districtRevision++;
         districtStyle = style;
         districtStyles = prepared;
+        const fills = districtLayers.find((layer) => layer.dataset.layer === 'district-fills');
+        const fade = layerFades.duration();
+        // A new style settles any fill crossfade still running from an earlier change.
+        districtTransition.cancel();
+        if (fills && fade && enabled('districtFills'))
+            districtTransition.fade(fills, fade);
         updateDistrictAppearance();
     }
     function setDistrictYear(next, options = {}) {
@@ -464,8 +482,28 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
         const geometry = getLayerPathsWithData({ year: next }, data.map, false);
         const previousYear = year;
         districtTransition.cancel();
+        districtMorph.stop();
+        const lineLayer = districtLayers.find((layer) => layer.dataset.layer === 'district-lines');
+        const morph = features.districtMorph &&
+            options.animate !== false &&
+            initialized &&
+            !reducedMotion.matches &&
+            (enabled('districtLines') || enabled('districtFills'))
+            ? features.districtMorph
+            : false;
+        const previousOutlines = morph && lineLayer
+            ? new Map([...lineLayer.querySelectorAll('path[data-district]')].map((path) => [
+                path.dataset.district ?? '',
+                path.getAttribute('d') ?? '',
+            ]))
+            : undefined;
         for (const layer of districtLayers) {
-            if (options.animate && !reducedMotion.matches)
+            if (morph) {
+                // The morph replaces the line crossfade; fills fade across the whole morph.
+                if (layer !== lineLayer)
+                    districtTransition.fade(layer, morph.duration);
+            }
+            else if (options.animate && !reducedMotion.matches)
                 districtTransition.fade(layer, options.duration ?? 280);
             layer.replaceChildren(...geometry.districts.map((district) => svgElement('path', {
                 'data-district': district.id,
@@ -491,6 +529,11 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
             delete root.dataset.selectedDistrict;
         updateDistrictAppearance();
         updateComposition();
+        if (morph && lineLayer && previousOutlines)
+            districtMorph.start(lineLayer, previousOutlines, {
+                duration: morph.duration,
+                stroke: colors.district ?? '#71838a',
+            });
         scheduleLabels();
         status.textContent = `${year} supervisorial districts.`;
         root.dispatchEvent(new CustomEvent('districtyearchange', { bubbles: true, detail: { year, previousYear } }));
@@ -504,7 +547,15 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
     let items = [];
     let destroyed = false;
     let initialized = false;
-    let frame = 0;
+    const layerFades = createLayerTransitions(() => initialized && features.layerTransitions && !reducedMotion.matches
+        ? features.layerTransitions.duration
+        : 0);
+    const districtMorph = createDistrictMorph();
+    const frames = createFrameScheduler({
+        request: (callback) => requestAnimationFrame(callback),
+        cancel: (id) => cancelAnimationFrame(id),
+        render: drawLabels,
+    });
     const markerRenderer = createMarkerLayer(markerLayer);
     const cancelEntrances = markerRenderer.cancelEntrances;
     const camera = createCamera({
@@ -512,8 +563,8 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
         write: setView,
         duration: () => (initialized && features.motion ? features.motion.duration : 0),
         reduced: () => reducedMotion.matches,
-        request: (callback) => requestAnimationFrame(callback),
-        cancel: (id) => cancelAnimationFrame(id),
+        request: frames.request,
+        cancel: frames.cancel,
         now: () => performance.now(),
     });
     const stopAnimation = camera.stop;
@@ -532,6 +583,12 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
             stopAnimation();
         if (Object.hasOwn(patch, 'markerEntrance'))
             cancelEntrances();
+        if (Object.hasOwn(patch, 'layerTransitions')) {
+            layerFades.cancel();
+            districtTransition.cancel();
+        }
+        if (Object.hasOwn(patch, 'districtMorph'))
+            districtMorph.stop();
         if (Object.hasOwn(patch, 'clustering'))
             invalidateClusters();
         syncFurniture();
@@ -798,8 +855,7 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
     function scheduleLabels() {
         if (destroyed)
             return;
-        cancelAnimationFrame(frame);
-        frame = requestAnimationFrame(drawLabels);
+        frames.invalidate();
     }
     function drawLabels() {
         if (destroyed)
@@ -1142,7 +1198,7 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
         const revision = ++neighborhoodRevision;
         delete root.dataset.selectedNeighborhood;
         root.dataset.source = source;
-        areas.replaceChildren(...nextItems.map((item) => item.node));
+        layerFades.crossfade(areas, () => areas.replaceChildren(...nextItems.map((item) => item.node)));
         neighborhoodSelect.replaceChildren(element('option', 'No neighborhood selected'));
         neighborhoodSelect.options[0].value = '';
         neighborhoodSelect.append(...nextOptions);
@@ -1185,9 +1241,9 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
         ]) {
             const layer = svg.querySelector(`[data-layer="${name}"]`);
             if (layer)
-                layer.style.display = enabled(key) ? '' : 'none';
+                layerFades.set(layer, enabled(key));
         }
-        stations.style.display = enabled('bartStations') ? '' : 'none';
+        layerFades.set(stations, enabled('bartStations'));
         for (const [kind, key] of [
             ['bart', 'bartStations'],
             ['park', 'landmarks'],
@@ -1202,7 +1258,7 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
             controls.legend === false ||
                 ![...legend.children].some((node) => !node.hidden);
         const neighborhoodsVisible = enabled('neighborhoodLines') || (labels && enabled('neighborhoodLabels'));
-        areas.style.display = neighborhoodsVisible ? '' : 'none';
+        layerFades.set(areas, neighborhoodsVisible);
         areas.style.pointerEvents = selectableNeighborhoods ? '' : 'none';
         neighborhoodLabel.hidden =
             !neighborhoodsVisible ||
@@ -1219,7 +1275,7 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
         }
         for (const layer of districtLayers) {
             const key = layer.dataset.layer === 'district-fills' ? 'districtFills' : 'districtLines';
-            layer.style.display = enabled(key) ? '' : 'none';
+            layerFades.set(layer, enabled(key));
         }
         updateDistrictAppearance();
         const districtsVisible = enabled('districtFills') || enabled('districtLines') || (labels && enabled('districtLabels'));
@@ -1274,10 +1330,16 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
         markerSelect.value = id ?? '';
         for (const entry of markerItems) {
             const active = entry.marker.id === id;
-            entry.node.setAttribute('aria-pressed', String(active));
-            entry.ring.setAttribute('display', active && features.selectedMarkerRing ? 'inline' : 'none');
-            entry.dot.setAttribute('fill', active ? selectedMarkerColor : (entry.marker.color ?? markerColor));
-            if (active)
+            const pressed = String(active);
+            const ring = active && features.selectedMarkerRing ? 'inline' : 'none';
+            const fill = active ? selectedMarkerColor : (entry.marker.color ?? markerColor);
+            if (entry.node.getAttribute('aria-pressed') !== pressed)
+                entry.node.setAttribute('aria-pressed', pressed);
+            if (entry.ring.getAttribute('display') !== ring)
+                entry.ring.setAttribute('display', ring);
+            if (entry.dot.getAttribute('fill') !== fill)
+                entry.dot.setAttribute('fill', fill);
+            if (active && markerLayer.lastChild !== entry.node)
                 markerLayer.append(entry.node);
         }
         scheduleLabels();
@@ -1294,41 +1356,78 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
         if (destroyed)
             return;
         validateMarkers(markers);
+        const existing = new Map(markerItems.map((item) => [item.marker.id, item]));
         const ids = new Set();
         const next = markers.map((marker) => {
             ids.add(marker.id);
-            return { marker: { ...marker }, point: map.project([marker.lng, marker.lat]) };
+            const previous = existing.get(marker.id);
+            const point = previous?.marker.lng === marker.lng && previous.marker.lat === marker.lat
+                ? previous.point
+                : map.project([marker.lng, marker.lat]);
+            return { marker: { ...marker }, point };
         });
+        const nextSelection = selectedMarker && ids.has(selectedMarker)
+            ? selectedMarker
+            : (markers.find((marker) => marker.selected)?.id ?? null);
+        const keys = ['id', 'lng', 'lat', 'label', 'selected', 'color', 'radius'];
+        if (markerSelect.options.length > 0 &&
+            nextSelection === selectedMarker &&
+            next.length === markerItems.length &&
+            next.every(({ marker }, index) => keys.every((key) => marker[key] === markerItems[index].marker[key])))
+            return;
         const focusedMarker = markerItems.find((item) => item.node === document.activeElement)?.marker
             .id;
         invalidateClusters();
-        const previousIds = new Set(markerItems.map((item) => item.marker.id));
-        markerRenderer.clear();
-        const previous = selectedMarker;
-        markerSelect.replaceChildren(element('option', 'No marker selected'));
-        markerSelect.options[0].value = '';
+        const options = new Map([...markerSelect.options].map((option) => [option.value, option]));
+        for (const item of markerItems) {
+            if (!ids.has(item.marker.id)) {
+                markerRenderer.remove(item);
+                options.get(item.marker.id)?.remove();
+            }
+        }
+        if (!options.has('')) {
+            const empty = element('option', 'No marker selected');
+            empty.value = '';
+            markerSelect.prepend(empty);
+        }
         markerItems = next.map(({ marker, point }, index) => {
-            const item = markerRenderer.add(marker, point, index, {
-                features,
-                markerColor,
-                selectedMarkerColor,
-                reducedMotion: reducedMotion.matches,
-                enter: !previousIds.has(marker.id),
-            });
-            const option = element('option', marker.label ?? marker.id);
-            option.value = marker.id;
-            markerSelect.append(option);
+            const previous = existing.get(marker.id);
+            const item = previous ??
+                markerRenderer.add(marker, point, index, {
+                    features,
+                    markerColor,
+                    selectedMarkerColor,
+                    reducedMotion: reducedMotion.matches,
+                    enter: true,
+                });
+            if (previous)
+                markerRenderer.update(item, marker, point, index);
+            const option = options.get(marker.id) ?? element('option');
+            const label = marker.label ?? marker.id;
+            if (option.textContent !== label)
+                option.textContent = label;
+            if (option.value !== marker.id)
+                option.value = marker.id;
+            if (markerSelect.children[index + 1] !== option)
+                markerSelect.insertBefore(option, markerSelect.children[index + 1] ?? null);
             return item;
         });
+        // Match input order without detaching unchanged nodes; selected markers remain on top.
+        const ordered = markerItems.filter((item) => item.marker.id !== nextSelection);
+        const selectedItem = markerItems.find((item) => item.marker.id === nextSelection);
+        if (selectedItem)
+            ordered.push(selectedItem);
+        ordered.forEach((item, index) => {
+            if (markerLayer.children[index] !== item.node)
+                markerLayer.insertBefore(item.node, markerLayer.children[index] ?? null);
+        });
         markerLabel.hidden = !markerItems.length || controls.markerPicker === false;
         if (markerLabel.firstChild)
             markerLabel.firstChild.textContent = `${strings.chooseMarker ?? 'Choose marker'} (${markerItems.length})`;
         syncFeatureControls();
-        const nextSelection = previous && ids.has(previous)
-            ? previous
-            : (markers.find((marker) => marker.selected)?.id ?? null);
+        const revision = markerRevision + 1;
         selectMarker(nextSelection, { fit: false });
-        if (focusedMarker)
+        if (!destroyed && markerRevision === revision && focusedMarker)
             (markerItems.find((item) => item.marker.id === focusedMarker)?.node ?? svg).focus({
                 preventScroll: true,
             });
@@ -1465,12 +1564,8 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
             districtRow(districtId)) {
             if (event.key === 'Enter' || event.key === ' ') {
                 event.preventDefault();
-                selectDistrict(districtId);
-                root.dispatchEvent(new CustomEvent('districtactivate', {
-                    bubbles: true,
-                    detail: districtSelection(districtId),
-                }));
-                target.focus();
+                if (activateDistrict(districtId))
+                    target.focus();
             }
             else if (event.key === '[' || event.key === ']') {
                 event.preventDefault();
@@ -1521,9 +1616,7 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
             ? event.target.closest('[data-layer="district-fills"] [data-district], [data-layer="district-lines"] [data-district]')
             : null;
         if (district?.dataset.district) {
-            const id = Number(district.dataset.district);
-            selectDistrict(id);
-            root.dispatchEvent(new CustomEvent('districtactivate', { bubbles: true, detail: districtSelection(id) }));
+            activateDistrict(Number(district.dataset.district));
             return;
         }
         const node = event.target instanceof Element
@@ -1592,13 +1685,15 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
             destroyed = true;
             camera.destroy();
             districtTransition.cancel();
+            layerFades.cancel();
+            districtMorph.stop();
             cancelEntrances();
             controller.abort();
             overlayEvents.abort();
             clusterEvents.abort();
             canvas.style.touchAction = 'pan-y pinch-zoom';
             observer?.disconnect();
-            cancelAnimationFrame(frame);
+            frames.destroy();
             labelRenderer.clear();
             releaseDownloads();
         },
@@ -1614,6 +1709,8 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
             if (reducedMotion.matches) {
                 stopAnimation();
                 districtTransition.cancel();
+                layerFades.cancel();
+                districtMorph.stop();
                 cancelEntrances();
             }
         }, { signal: controller.signal });

package/dist/src/features.d.ts

@@ -18,6 +18,12 @@ export declare function normalizeFeatures(input?: MapFeatures): {
     };
     northArrow: boolean;
     scaleBar: boolean;
+    layerTransitions: false | {
+        duration: number;
+    };
+    districtMorph: false | {
+        duration: number;
+    };
 };
 export declare const layerKeys: readonly ['districtFills', 'districtLines', 'districtLabels', 'neighborhoodLines', 'neighborhoodLabels', 'landmarks', 'bartStations', 'highways', 'keyRoads', 'roadLabels'];
 export declare const controlKeys: readonly ['zoom', 'pan', 'reset', 'labels', 'touch', 'legend', 'neighborhoodPicker', 'markerPicker', 'help', 'status'];