@kahwee/sf-map-svg 4.0.0 → 4.0.1

package/CHANGELOG.md

@@ -4,6 +4,11 @@ User-visible changes are recorded here. Unreleased entries describe changes on `
 
 ## Unreleased
 
+## 4.0.1 — 2026-09-28
+
+- Reconcile marker updates by ID, preserving retained SVG nodes, picker options, keyboard focus, and entrance animations. Identical ordered updates no longer mutate the DOM; only new IDs animate in and removed markers cancel their entrances.
+- Advance animated cameras and dependent label, marker, and cluster layout in one shared browser frame, with regression coverage for coalescing, cancellation, reentrant updates, and destruction.
+
 ## 4.0.0 — 2026-09-28
 
 - Breaking: require Node 24 or newer for server rendering and development. Validate the minimum supported major alongside Node 26 in CI; browser runtime requirements are unchanged.

package/README.md

@@ -58,6 +58,8 @@ Construction options include `mode` (`basemap`, `neighborhoods`, or `districts`)
 
 The controller also supports marker, neighborhood, and district selection; district year and style changes; source and mode changes; labels and touch navigation; screen projection; and typed `markerchange`, `neighborhoodchange`, `districtchange`, `districthover`, `districtactivate`, `districtyearchange`, `overlayactivate`, `clusteractivate`, `viewportchange`, and `mapresize` events. `destroy()` releases browser resources; operations after destruction throw.
 
+`setMarkers()` reconciles by stable marker `id`: retained markers keep their DOM nodes, focus, and in-progress entrance animations; only new IDs animate in. Identical ordered marker updates are a visual no-op. Camera state and `viewportchange` events remain synchronous, while animated camera steps and their dependent label/marker layout commit in the same browser frame.
+
 For a small guide, import `guideMapData` from `/guide/data` and pass it to `createMap`. The optional `/guide` entry also provides `createGuideMap`, `mountGuideMap`, and detailed-data loading for existing guide layouts. `/transit` provides the standalone schematic transit animation. See [examples](docs/EXAMPLES.md) and [consumer integration](docs/consumer-integration.md).
 
 For the guide preset with the same controller API, use `createGuideController(options)` from `/guide` (or `/guide/map`). It accepts grouped `MapOptions` and returns `MapController`; `mountGuideController(shell, options)` enhances a `createGuideShell()` container. Both use the lightweight guide geography. Existing `createGuideMap` and `mountGuideMap` calls retain their element-based API.

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/explorer-core.js

@@ -6,6 +6,7 @@ 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 { createSFMapWithData, districtColors, getLayerPathsWithData } from './map-core.js';
@@ -504,7 +505,11 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
     let items = [];
     let destroyed = false;
     let initialized = false;
-    let frame = 0;
+    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 +517,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;
@@ -798,8 +803,7 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
     function scheduleLabels() {
         if (destroyed)
             return;
-        cancelAnimationFrame(frame);
-        frame = requestAnimationFrame(drawLabels);
+        frames.invalidate();
     }
     function drawLabels() {
         if (destroyed)
@@ -1274,10 +1278,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 +1304,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,
             });
@@ -1598,7 +1645,7 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
             clusterEvents.abort();
             canvas.style.touchAction = 'pan-y pinch-zoom';
             observer?.disconnect();
-            cancelAnimationFrame(frame);
+            frames.destroy();
             labelRenderer.clear();
             releaseDownloads();
         },

package/dist/src/frame-scheduler.d.ts

@@ -0,0 +1,11 @@
+/** One browser frame for camera advancement and the dependent screen-space rendering. */
+export declare function createFrameScheduler({ request, cancel, render, }: {
+    request: (callback: FrameRequestCallback) => number;
+    cancel: (id: number) => void;
+    render: () => void;
+}): {
+    request(callback: FrameRequestCallback): number;
+    cancel(id: number): void;
+    invalidate(): void;
+    destroy(): void;
+};

package/dist/src/frame-scheduler.js

@@ -0,0 +1,64 @@
+/** One browser frame for camera advancement and the dependent screen-space rendering. */
+export function createFrameScheduler({ request, cancel, render, }) {
+    let frame;
+    let pending;
+    let sequence = 0;
+    let dirty = false;
+    let flushing = false;
+    let destroyed = false;
+    function schedule() {
+        if (!destroyed && !flushing && frame === undefined && (pending || dirty))
+            frame = request(flush);
+    }
+    function flush(time) {
+        frame = undefined;
+        if (destroyed)
+            return;
+        flushing = true;
+        const next = pending;
+        pending = undefined;
+        try {
+            next?.callback(time);
+            if (!destroyed && dirty) {
+                dirty = false;
+                render();
+            }
+        }
+        finally {
+            flushing = false;
+            schedule();
+        }
+    }
+    return {
+        request(callback) {
+            const id = ++sequence;
+            if (!destroyed) {
+                pending = { id, callback };
+                schedule();
+            }
+            return id;
+        },
+        cancel(id) {
+            if (pending?.id === id)
+                pending = undefined;
+            if (!pending && !dirty && frame !== undefined) {
+                cancel(frame);
+                frame = undefined;
+            }
+        },
+        invalidate() {
+            if (destroyed)
+                return;
+            dirty = true;
+            schedule();
+        },
+        destroy() {
+            destroyed = true;
+            if (frame !== undefined)
+                cancel(frame);
+            frame = undefined;
+            pending = undefined;
+            dirty = false;
+        },
+    };
+}

package/dist/src/marker-layer.d.ts

@@ -7,11 +7,14 @@ export interface MarkerItem {
     dot: SVGCircleElement;
     hit: SVGCircleElement;
     ring: SVGCircleElement;
+    title: SVGTitleElement;
 }
 /** Own marker visuals and entrances; selection/events remain with the controller. */
 export declare function createMarkerLayer(layer: SVGGElement): {
     cancelEntrances: () => void;
     clear(): void;
+    remove(item: MarkerItem): void;
+    update(item: MarkerItem, marker: MapMarker, point: [number, number], index: number): void;
     add(marker: MapMarker, point: [number, number], index: number, { features, markerColor, selectedMarkerColor, reducedMotion, enter, }: {
         features: ReturnType<typeof normalizeFeatures>;
         markerColor: string;

package/dist/src/marker-layer.js

@@ -1,9 +1,9 @@
 import { svgElement } from './dom.js';
 /** Own marker visuals and entrances; selection/events remain with the controller. */
 export function createMarkerLayer(layer) {
-    const animations = new Set();
+    const animations = new Map();
     function cancelEntrances() {
-        for (const animation of animations)
+        for (const animation of animations.values())
             animation.cancel();
         animations.clear();
     }
@@ -13,6 +13,24 @@ export function createMarkerLayer(layer) {
             cancelEntrances();
             layer.replaceChildren();
         },
+        remove(item) {
+            animations.get(item.node)?.cancel();
+            animations.delete(item.node);
+            item.node.remove();
+        },
+        update(item, marker, point, index) {
+            if (item.point[0] !== point[0] || item.point[1] !== point[1])
+                item.node.setAttribute('transform', `translate(${point[0]},${point[1]})`);
+            const label = marker.label ?? marker.id;
+            if (item.title.textContent !== label) {
+                item.title.textContent = label;
+                item.node.setAttribute('aria-label', label);
+            }
+            if (item.node.style.getPropertyValue('--sf-marker-index') !== String(index))
+                item.node.style.setProperty('--sf-marker-index', String(index));
+            item.marker = marker;
+            item.point = point;
+        },
         add(marker, point, index, { features, markerColor, selectedMarkerColor, reducedMotion, enter, }) {
             const node = svgElement('g', {
                 transform: `translate(${point[0]},${point[1]})`,
@@ -54,11 +72,15 @@ export function createMarkerLayer(layer) {
                     easing: 'cubic-bezier(.2,.8,.2,1)',
                     fill: 'backwards',
                 });
-                animations.add(animation);
-                animation.finished.then(() => animations.delete(animation), () => animations.delete(animation));
+                animations.set(node, animation);
+                const release = () => {
+                    if (animations.get(node) === animation)
+                        animations.delete(node);
+                };
+                animation.finished.then(release, release);
             }
             layer.append(node);
-            return { marker, point, node, dot, hit, ring };
+            return { marker, point, node, dot, hit, ring, title };
         },
     };
 }

package/dist/src/types.d.ts

@@ -207,6 +207,7 @@ export interface NeighborhoodExplorerElement extends HTMLElement {
     fitGeometry(geometry: Geometry, padding?: number | MapPadding, options?: CameraOptions): void;
     /** Explicitly engage map touch gestures; false restores page gestures. */
     setTouchNavigation(enabled: boolean): 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?: {

package/docs/api-audit.md

@@ -24,6 +24,8 @@ unbounded geographic data can never fail.
 | District style callbacks | Prepare and copy every style before committing. Hover/selection reuse the results; call `setDistrictStyle()` to refresh changed external data. Reentrant updates or destruction supersede pending work. |
 | Rapid district year changes | Both outgoing layers are tracked, inert, and removed on interruption, completion, reduced-motion changes, or destruction. Zero duration creates no transition copies. |
 | Label metrics and camera movement | Reuse screen-space text measurements and nodes across frames. Font loading invalidates measurements; hidden or removed candidates do not remain in the visible layer. |
+| Marker replacement | Reconcile stable IDs, preserve retained nodes/picker options and entrance animations, cancel removed entrances, and restore focus after reordering. Identical ordered values do not mutate the DOM or restart work. |
+| Camera and label scheduling | A shared frame advances the camera before rendering dependent labels, marker sizes, and clusters. State/events remain synchronous; cancellation preserves pending layout, and destruction cancels both kinds of work. |
 | Guide controllers and compatibility factories | `createGuideController`/`mountGuideController` share grouped options and lifecycle with `createMap`. Existing element factories retain flat options and their return types. |
 | Layer hidden and bundle cost | Visibility never unloads imported geography. Use narrow entrypoints or data injection to save bytes. |
 

package/docs/guide-bundle-report.md

@@ -4,9 +4,9 @@ Generated 2026-09-28 by `pnpm report:guide` with Vite production minification an
 
 | Entry | Initial JS, raw | Initial JS, gzip | Explicit detail JS, gzip |
 | --- | ---: | ---: | ---: |
-| v3 root (explicit data) | 87.4 KB | 25.5 KB | — |
+| v3 root (explicit data) | 89.7 KB | 26.3 KB | — |
 | v3 static renderer | 15.3 KB | 5.0 KB | — |
-| Guide preset | 477.1 KB | 114.1 KB | 473.7 KB |
+| Guide preset | 479.5 KB | 114.9 KB | 473.7 KB |
 
 **500 KB target:** met.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kahwee/sf-map-svg",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "description": "Offline SVG maps of San Francisco with district boundaries, parks, landmarks, and BART stations.",
   "type": "module",
   "main": "./dist/src/api.js",