@kahwee/sf-map-svg 5.1.1 → 5.1.2

package/CHANGELOG.md

@@ -4,6 +4,10 @@ User-visible changes are recorded here. Unreleased entries describe changes on `
 
 ## Unreleased
 
+## 5.1.2 — 2026-11-05
+
+- Separate marker selection, activation and focus recovery into an internal controller; separate label candidate caching, screen-space collision layout and metrics invalidation into a label coordinator. Preserve the public API and shared animation frame scheduling.
+
 ## 5.1.1 — 2026-11-05
 
 - Reserve precinct report controls and status space during loading to prevent phone layout shifts when multiple reports are available.

package/dist/src/explorer-core.js

@@ -4,17 +4,17 @@ import { createClusterLayer } from './cluster-layer.js';
 import { clusterPoints } from './clusters.js';
 import { createDistrictController } from './district-controller.js';
 import { prepareDistrictStyles } from './district-style.js';
-import { element, setAttributeIfChanged, svgElement } from './dom.js';
+import { element, svgElement } from './dom.js';
 import { createExplorerControls } from './explorer-controls.js';
 import { fitBounds, projectedBounds } from './explorer-layout.js';
 import { controlKeys, layerKeys, normalizeFeatures, validateSwitchPatch } from './features.js';
 import { createFrameScheduler } from './frame-scheduler.js';
-import { labelCandidates, styleLabels, } from './label-candidates.js';
-import { createLabelRenderer } from './label-renderer.js';
+import { createLabelCoordinator } from './label-coordinator.js';
 import { createLayerTransitions } from './layer-transition.js';
 import { createSFMapWithData, districtColors, getLayerPathsWithData, resolveMapColors, } from './map-core.js';
 import { createMarkerCatalog } from './marker-catalog.js';
 import { createMarkerChooser } from './marker-chooser.js';
+import { createMarkerController } from './marker-controller.js';
 import { createMarkerLayer } from './marker-layer.js';
 import { createMarkerNavigation } from './marker-navigation.js';
 import { createNeighborhoodLayer, createNeighborhoodLookup, formatSourceLabel, } from './neighborhood-layer.js';
@@ -177,7 +177,6 @@ export function createNeighborhoodExplorerCore(options = {}, data, ui) {
         'aria-hidden': 'true',
         'font-family': labelStyle.fontFamily ?? styleOptions.font ?? 'system-ui,sans-serif',
     });
-    const labelRenderer = createLabelRenderer(labelLayer);
     geography.append(areas, stations, labelLayer, overlayLayer, markerLayer);
     let view = [0, 0, 800];
     const districts = createDistrictController({
@@ -313,7 +312,7 @@ export function createNeighborhoodExplorerCore(options = {}, data, ui) {
             if (!visual)
                 continue;
             const ring = features.selectedMarkerRing;
-            visual.ring.setAttribute('display', ring && marker.id === selectedMarker ? 'inline' : 'none');
+            visual.ring.setAttribute('display', ring && marker.id === markers.selected ? 'inline' : 'none');
             visual.ring.setAttribute('stroke', ring ? (ring.color ?? selectedMarkerColor) : selectedMarkerColor);
             visual.ring.setAttribute('stroke-width', String(ring ? ring.width : 2));
         }
@@ -348,7 +347,6 @@ export function createNeighborhoodExplorerCore(options = {}, data, ui) {
         kind: 'road',
     }));
     const secondaryRoads = svg.querySelectorAll('[data-key-road-level="secondary"]');
-    let secondaryRoadsVisible;
     const scaleUnitsPerMeter = Math.abs(map.project([-122.44, 37.76])[0] - map.project([-122.45, 37.76])[0]) / 879;
     const parkItems = (data.map.landmarks ?? []).map((feature) => ({
         point: map.project(feature.label),
@@ -356,18 +354,57 @@ export function createNeighborhoodExplorerCore(options = {}, data, ui) {
         kind: 'park',
     }));
     const markerCatalog = createMarkerCatalog(markerRenderer, markerSelect, map.project);
-    let selectedMarker = null;
     const markerNavigation = createMarkerNavigation(svg, controller.signal);
+    const markers = createMarkerController({
+        root,
+        canvas,
+        svg,
+        markerLayer,
+        markerSelect,
+        markerLabel,
+        markerCatalog,
+        markerNavigation,
+        strings,
+        fitPadding,
+        onMarkerActivate,
+        invalidateClusters,
+        drawClusters,
+        materializeMarker,
+        scheduleLabels,
+        syncFeatureControls,
+        moveView,
+        get markerChooser() {
+            return markerChooser;
+        },
+        get destroyed() {
+            return destroyed;
+        },
+        get view() {
+            return view;
+        },
+        get features() {
+            return features;
+        },
+        get markerColor() {
+            return markerColor;
+        },
+        get selectedMarkerColor() {
+            return selectedMarkerColor;
+        },
+        get controls() {
+            return controls;
+        },
+    });
+    const { getSelectedMarker, selectMarker, setMarkers, activateMarker } = markers;
     const markerChooser = createMarkerChooser(canvas, svg, (id) => {
         if (destroyed)
             return;
         selectMarker(id);
-        if (!destroyed && selectedMarker === id)
+        if (!destroyed && markers.selected === id)
             markerCatalog.items
                 .find((item) => item.marker.id === id)
                 ?.visual?.node.focus({ preventScroll: true });
     });
-    let markerRevision = 0;
     const clusterLayer = svgElement('g', { 'data-layer': 'marker-clusters' });
     geography.insertBefore(clusterLayer, markerLayer);
     function materializeMarker(item) {
@@ -377,7 +414,7 @@ export function createNeighborhoodExplorerCore(options = {}, data, ui) {
                 markerColor,
                 selectedMarkerColor,
                 reducedMotion: reducedMotion.matches,
-                selected: item.marker.id === selectedMarker,
+                selected: item.marker.id === markers.selected,
             }),
         });
     }
@@ -411,8 +448,8 @@ export function createNeighborhoodExplorerCore(options = {}, data, ui) {
             unit,
             view,
             items: markerCatalog.items,
-            revision: markerRevision,
-            selected: selectedMarker,
+            revision: markers.revision,
+            selected: markers.selected,
             features,
             markerColor,
             markerRadius,
@@ -501,141 +538,70 @@ export function createNeighborhoodExplorerCore(options = {}, data, ui) {
         moveView([0, 0, 800], options);
     }
     function scheduleLabels() {
-        if (destroyed)
-            return;
-        frames.invalidate();
-    }
-    let labelInputs = [];
-    let preparedLabels = [];
-    function prepareLabels(width, zoom) {
-        // Only screen-space positioning changes during pan or within these zoom/width bands.
-        const inputs = [
-            neighborhoods.items,
-            neighborhoods.selected,
-            districtItems,
-            markerRevision,
-            layers,
-            mode,
-            labelStyle,
-            colors,
-            minLabelSize,
-            maxLabelSize,
-            markerRadius,
-            zoom >= 1.8,
-            width >= 550,
-        ];
-        if (inputs.every((value, index) => value === labelInputs[index]))
-            return preparedLabels;
-        labelInputs = inputs;
-        const selectedItem = neighborhoods.items.find((item) => item.feature === neighborhoods.selected);
-        const candidates = [];
-        const marker = markerCatalog.items.find((item) => item.marker.id === selectedMarker);
-        if (marker)
-            candidates.push({
-                point: marker.point,
-                name: marker.marker.label ?? marker.marker.id,
-                kind: 'selected-marker',
-            });
-        if (selectedItem?.point && enabled('neighborhoodLabels'))
-            candidates.push({
-                point: selectedItem.point,
-                name: selectedItem.feature.properties.canonicalName,
-                kind: 'selected',
-            });
-        preparedLabels = styleLabels(labelCandidates({
-            selected: candidates,
-            districts: enabled('districtLabels') ? districtItems : [],
-            stations: enabled('bartStations') ? stationItems : [],
-            parks: enabled('landmarks') ? parkItems : [],
-            roads: enabled('roadLabels') ? roadItems : [],
-            neighborhoods: enabled('neighborhoodLabels')
-                ? neighborhoods.items
-                    .filter((item) => item.point !== undefined)
-                    .sort((a, b) => b.area - a.area || a.feature.id.localeCompare(b.feature.id))
-                    .flatMap((item) => item.feature !== neighborhoods.selected && item.point
-                    ? [
-                        {
-                            point: item.point,
-                            name: item.feature.properties.canonicalName,
-                            kind: 'neighborhood',
-                        },
-                    ]
-                    : [])
-                : [],
-        }, width, zoom), {
-            colors,
-            labelStyle,
-            labelSize: { min: minLabelSize, max: maxLabelSize },
-            markerRadius: marker?.marker.radius ?? markerRadius,
-        });
-        return preparedLabels;
+        labelCoordinator.schedule();
     }
+    const labelCoordinator = createLabelCoordinator({
+        root,
+        canvas,
+        scale,
+        overlayElement,
+        secondaryRoads,
+        stationItems,
+        roadItems,
+        parkItems,
+        scaleUnitsPerMeter,
+        neighborhoods,
+        markerCatalog,
+        markers,
+        enabled,
+        drawClusters,
+        labelLayer,
+        invalidateFrame: frames.invalidate,
+        get districtItems() {
+            return districtItems;
+        },
+        get layers() {
+            return layers;
+        },
+        get mode() {
+            return mode;
+        },
+        get labelStyle() {
+            return labelStyle;
+        },
+        get colors() {
+            return colors;
+        },
+        get minLabelSize() {
+            return minLabelSize;
+        },
+        get maxLabelSize() {
+            return maxLabelSize;
+        },
+        get markerRadius() {
+            return markerRadius;
+        },
+        get view() {
+            return view;
+        },
+        get destroyed() {
+            return destroyed;
+        },
+        get features() {
+            return features;
+        },
+        get labels() {
+            return labels;
+        },
+        get renderedMarkers() {
+            return renderedMarkers;
+        },
+        get renderedClusters() {
+            return renderedClusters;
+        },
+    });
     function drawLabels() {
-        if (destroyed)
-            return;
-        const canvasBox = canvas.getBoundingClientRect();
-        const width = canvasBox.width;
-        if (!width)
-            return;
-        const unit = view[2] / width, zoom = 800 / view[2];
-        if (features.scaleBar) {
-            const pixelsPerMeter = scaleUnitsPerMeter / unit;
-            const base = 10 ** Math.floor(Math.log10(100 / pixelsPerMeter));
-            const meters = [5, 2, 1].map((factor) => factor * base).find((value) => value * pixelsPerMeter <= 100) ??
-                base;
-            const scaleWidth = `${meters * pixelsPerMeter}px`;
-            const scaleText = meters >= 1000 ? `${meters / 1000} km` : `${meters} m`;
-            if (scale.style.width !== scaleWidth)
-                scale.style.width = scaleWidth;
-            if (scale.textContent !== scaleText)
-                scale.textContent = scaleText;
-        }
-        // Read overlay bounds before SVG writes; scale furniture above must have its current width.
-        const furnitureBounds = [...overlayElement.children]
-            .filter((node) => node.getClientRects().length > 0)
-            .map((node) => {
-            const box = node.getBoundingClientRect();
-            return [
-                box.left - canvasBox.left - 3,
-                box.top - canvasBox.top - 3,
-                box.right - canvasBox.left + 3,
-                box.bottom - canvasBox.top + 3,
-            ];
-        });
-        const showSecondaryRoads = zoom >= 1.8;
-        if (showSecondaryRoads !== secondaryRoadsVisible) {
-            for (const road of secondaryRoads)
-                road.style.display = showSecondaryRoads ? '' : 'none';
-            secondaryRoadsVisible = showSecondaryRoads;
-        }
-        for (const station of stationItems)
-            setAttributeIfChanged(station.node, 'r', 4.5 * unit);
-        drawClusters(unit);
-        if (!labels) {
-            labelRenderer.clear();
-            root.dataset.visibleLabels = '0';
-            return;
-        }
-        const labelCandidates = prepareLabels(width, zoom);
-        const stationBounds = (enabled('bartStations') ? stationItems : []).map(({ point }) => {
-            const x = (point[0] - view[0]) / unit;
-            const y = (point[1] - view[1]) / unit;
-            return [x - 6, y - 6, x + 6, y + 6];
-        });
-        const markerBounds = renderedMarkers.map(({ point, marker }) => {
-            const radius = marker.radius ?? markerRadius;
-            const x = (point[0] - view[0]) / unit, y = (point[1] - view[1]) / unit;
-            return [x - radius - 3, y - radius - 3, x + radius + 3, y + radius + 3];
-        });
-        root.dataset.visibleLabels = String(labelRenderer.draw(labelCandidates, view, width, [
-            ...stationBounds,
-            ...markerBounds,
-            ...furnitureBounds,
-            ...renderedClusters.map(({ point }) => {
-                const x = (point[0] - view[0]) / unit, y = (point[1] - view[1]) / unit;
-                return [x - 26, y - 26, x + 26, y + 26];
-            }),
-        ]));
+        labelCoordinator.draw();
     }
     const sidebar = ui.createSidebar?.(shell, data, chrome, strings.emptyResults, searchNeighborhoods);
     function updateDetail() {
@@ -741,91 +707,6 @@ export function createNeighborhoodExplorerCore(options = {}, data, ui) {
         attribution.textContent = description;
         scheduleLabels();
     }
-    function getSelectedMarker() {
-        const marker = markerCatalog.items.find((item) => item.marker.id === selectedMarker)?.marker;
-        return marker ? { ...marker, position: [...marker.position] } : null;
-    }
-    function selectMarker(id, options = {}) {
-        if (destroyed)
-            return false;
-        const item = markerCatalog.items.find((item) => item.marker.id === id);
-        if (id !== null && !item)
-            return false;
-        validateCameraOptions(options);
-        const width = canvas.getBoundingClientRect().width;
-        const target = item && options.fit !== false
-            ? width
-                ? fitViewport([...item.point, ...item.point], width, fitPadding)
-                : fitBounds([...item.point, ...item.point])
-            : null;
-        const revision = ++markerRevision;
-        const changed = selectedMarker !== id;
-        selectedMarker = id;
-        if (changed)
-            invalidateClusters();
-        markerSelect.value = id ?? '';
-        for (const entry of markerCatalog.items) {
-            const active = entry.marker.id === id;
-            const visual = active ? materializeMarker(entry).visual : entry.visual;
-            if (!visual)
-                continue;
-            const pressed = String(active);
-            const ring = active && features.selectedMarkerRing ? 'inline' : 'none';
-            const fill = active ? selectedMarkerColor : (entry.marker.color ?? markerColor);
-            if (visual.node.getAttribute('aria-pressed') !== pressed)
-                visual.node.setAttribute('aria-pressed', pressed);
-            if (visual.ring.getAttribute('display') !== ring)
-                visual.ring.setAttribute('display', ring);
-            if (visual.dot.getAttribute('fill') !== fill)
-                visual.dot.setAttribute('fill', fill);
-            if (active && markerLayer.lastChild !== visual.node)
-                markerLayer.append(visual.node);
-        }
-        scheduleLabels();
-        if (width || !features.clustering)
-            drawClusters(width ? view[2] / width : 1);
-        const marker = getSelectedMarker();
-        if (changed)
-            root.dispatchEvent(new CustomEvent('markerchange', { bubbles: true, detail: { id, marker } }));
-        if (!destroyed && changed && marker && markerRevision === revision && selectedMarker === id)
-            onMarkerActivate?.({ ...marker });
-        if (!destroyed && markerRevision === revision && target)
-            moveView(target, options);
-        return true;
-    }
-    function setMarkers(markers) {
-        if (destroyed)
-            return;
-        const prepared = markerCatalog.prepare(markers, selectedMarker);
-        if (!prepared)
-            return;
-        const { selection: nextSelection, focused: focusedMarker } = prepared;
-        invalidateClusters();
-        prepared.commit();
-        markerLabel.hidden = !markerCatalog.items.length || controls.markerPicker === false;
-        if (markerLabel.firstChild)
-            markerLabel.firstChild.textContent = `${strings.chooseMarker ?? 'Choose marker'} (${markerCatalog.items.length})`;
-        syncFeatureControls();
-        const revision = markerRevision + 1;
-        selectMarker(nextSelection, { fit: false });
-        if (!destroyed && markerRevision === revision && focusedMarker) {
-            markerNavigation.sync(markerCatalog.items.flatMap((item) => (item.visual ? [item.visual.node] : [])));
-            if (!markerNavigation.recover()) {
-                const recovery = markerCatalog.items.find((item) => item.marker.id === focusedMarker) ??
-                    markerCatalog.items[0];
-                if (recovery) {
-                    const { node } = materializeMarker(recovery).visual;
-                    markerLayer.append(node);
-                    node.focus({ preventScroll: true });
-                    const width = canvas.getBoundingClientRect().width;
-                    if (width)
-                        drawClusters(view[2] / width);
-                }
-                else
-                    svg.focus({ preventScroll: true });
-            }
-        }
-    }
     function setControls(patch) {
         if (destroyed)
             return;
@@ -924,21 +805,6 @@ export function createNeighborhoodExplorerCore(options = {}, data, ui) {
     });
     listen(markerLayer, 'focusout', scheduleLabels);
     listen(markerLayer, 'focusin', scheduleLabels);
-    function activateMarker(id, node) {
-        const item = markerCatalog.items.find((item) => item.marker.id === id);
-        if (!item)
-            return;
-        const coincident = markerCatalog.items.filter((other) => other.point[0] === item.point[0] && other.point[1] === item.point[1]);
-        if (coincident.length > 1)
-            markerChooser.open(coincident.map((other) => other.marker), node);
-        else {
-            selectMarker(id);
-            if (!destroyed && selectedMarker === id)
-                markerCatalog.items
-                    .find((other) => other.marker.id === id)
-                    ?.visual?.node.focus({ preventScroll: true });
-        }
-    }
     listen(markerLayer, 'click', (event) => {
         const node = event.target instanceof Element ? event.target.closest('[data-marker-id]') : null;
         if (node?.dataset.markerId)
@@ -1074,7 +940,7 @@ export function createNeighborhoodExplorerCore(options = {}, data, ui) {
             ])
                 root.style.setProperty(`--sf-map-${name}`, styleOptions[token] ?? fallback);
             labelLayer.setAttribute('font-family', labelStyle.fontFamily ?? styleOptions.font ?? 'system-ui,sans-serif');
-            labelRenderer.invalidateMetrics();
+            labelCoordinator.invalidateMetrics();
             for (const station of stationItems)
                 station.node.setAttribute('stroke', colors.bart ?? '#0073ae');
             for (const kind of ['bart', 'park', 'highway', 'road']) {
@@ -1094,7 +960,7 @@ export function createNeighborhoodExplorerCore(options = {}, data, ui) {
                 const visual = item.visual;
                 if (!visual)
                     continue;
-                visual.dot.setAttribute('fill', item.marker.id === selectedMarker
+                visual.dot.setAttribute('fill', item.marker.id === markers.selected
                     ? selectedMarkerColor
                     : (item.marker.color ?? markerColor));
                 visual.ring.setAttribute('stroke', features.selectedMarkerRing
@@ -1165,7 +1031,7 @@ export function createNeighborhoodExplorerCore(options = {}, data, ui) {
             canvas.style.touchAction = 'pan-y pinch-zoom';
             observer?.disconnect();
             frames.destroy();
-            labelRenderer.clear();
+            labelCoordinator.clear();
             sidebar?.destroy();
             neighborhoods.destroy();
         },
@@ -1174,7 +1040,7 @@ export function createNeighborhoodExplorerCore(options = {}, data, ui) {
         observer = new ResizeObserver(onResize);
         observer.observe(canvas);
         document.fonts?.addEventListener('loadingdone', () => {
-            labelRenderer.invalidateMetrics();
+            labelCoordinator.invalidateMetrics();
             scheduleLabels();
         }, { signal: controller.signal });
         reducedMotion.addEventListener('change', () => {

package/dist/src/label-coordinator.d.ts

@@ -0,0 +1,54 @@
+import type { View } from './explorer-layout.js';
+import type { normalizeFeatures } from './features.js';
+import { type LabelItem } from './label-candidates.js';
+import type { createMarkerCatalog } from './marker-catalog.js';
+import type { createMarkerController } from './marker-controller.js';
+import type { MarkerItem, MarkerVisual } from './marker-layer.js';
+import type { createNeighborhoodLayer } from './neighborhood-layer.js';
+import type { ExplorerMode, InteractiveLayers, NeighborhoodExplorerOptions } from './types.js';
+interface LabelHost {
+    root: HTMLElement;
+    canvas: HTMLElement;
+    scale: HTMLElement;
+    overlayElement: HTMLElement;
+    secondaryRoads: NodeListOf<SVGPathElement>;
+    stationItems: (LabelItem & {
+        node: SVGCircleElement;
+    })[];
+    roadItems: LabelItem[];
+    parkItems: LabelItem[];
+    scaleUnitsPerMeter: number;
+    neighborhoods: ReturnType<typeof createNeighborhoodLayer>;
+    markerCatalog: ReturnType<typeof createMarkerCatalog>;
+    markers: ReturnType<typeof createMarkerController>;
+    labelLayer: SVGGElement;
+    invalidateFrame(): void;
+    get districtItems(): LabelItem[];
+    get layers(): InteractiveLayers;
+    get mode(): ExplorerMode;
+    get labelStyle(): NonNullable<NeighborhoodExplorerOptions['labelStyle']>;
+    get colors(): NonNullable<NeighborhoodExplorerOptions['colors']>;
+    get minLabelSize(): number;
+    get maxLabelSize(): number;
+    get markerRadius(): number;
+    get view(): View;
+    get destroyed(): boolean;
+    get labels(): boolean;
+    get features(): ReturnType<typeof normalizeFeatures>;
+    get renderedMarkers(): (MarkerItem & {
+        visual: MarkerVisual;
+    })[];
+    get renderedClusters(): {
+        point: [number, number];
+    }[];
+    enabled(layer: keyof InteractiveLayers): boolean;
+    drawClusters(unit: number): void;
+}
+/** Own candidate caching, screen-space collision layout and label metrics invalidation. */
+export declare function createLabelCoordinator(host: LabelHost): {
+    draw: () => void;
+    schedule(): void;
+    invalidateMetrics(): void;
+    clear(): void;
+};
+export {};

package/dist/src/label-coordinator.js

@@ -0,0 +1,157 @@
+import { setAttributeIfChanged } from './dom.js';
+import { labelCandidates, styleLabels, } from './label-candidates.js';
+import { createLabelRenderer } from './label-renderer.js';
+/** Own candidate caching, screen-space collision layout and label metrics invalidation. */
+export function createLabelCoordinator(host) {
+    const { root, canvas, scale, overlayElement, secondaryRoads, stationItems, roadItems, parkItems, scaleUnitsPerMeter, neighborhoods, markerCatalog, markers, enabled, drawClusters, } = host;
+    const labelRenderer = createLabelRenderer(host.labelLayer);
+    let secondaryRoadsVisible;
+    let labelInputs = [];
+    let preparedLabels = [];
+    function prepareLabels(width, zoom) {
+        // Only screen-space positioning changes during pan or within these zoom/width bands.
+        const inputs = [
+            neighborhoods.items,
+            neighborhoods.selected,
+            host.districtItems,
+            markers.revision,
+            host.layers,
+            host.mode,
+            host.labelStyle,
+            host.colors,
+            host.minLabelSize,
+            host.maxLabelSize,
+            host.markerRadius,
+            zoom >= 1.8,
+            width >= 550,
+        ];
+        if (inputs.every((value, index) => value === labelInputs[index]))
+            return preparedLabels;
+        labelInputs = inputs;
+        const selectedItem = neighborhoods.items.find((item) => item.feature === neighborhoods.selected);
+        const candidates = [];
+        const marker = markerCatalog.items.find((item) => item.marker.id === markers.selected);
+        if (marker)
+            candidates.push({
+                point: marker.point,
+                name: marker.marker.label ?? marker.marker.id,
+                kind: 'selected-marker',
+            });
+        if (selectedItem?.point && enabled('neighborhoodLabels'))
+            candidates.push({
+                point: selectedItem.point,
+                name: selectedItem.feature.properties.canonicalName,
+                kind: 'selected',
+            });
+        preparedLabels = styleLabels(labelCandidates({
+            selected: candidates,
+            districts: enabled('districtLabels') ? host.districtItems : [],
+            stations: enabled('bartStations') ? stationItems : [],
+            parks: enabled('landmarks') ? parkItems : [],
+            roads: enabled('roadLabels') ? roadItems : [],
+            neighborhoods: enabled('neighborhoodLabels')
+                ? neighborhoods.items
+                    .filter((item) => item.point !== undefined)
+                    .sort((a, b) => b.area - a.area || a.feature.id.localeCompare(b.feature.id))
+                    .flatMap((item) => item.feature !== neighborhoods.selected && item.point
+                    ? [
+                        {
+                            point: item.point,
+                            name: item.feature.properties.canonicalName,
+                            kind: 'neighborhood',
+                        },
+                    ]
+                    : [])
+                : [],
+        }, width, zoom), {
+            colors: host.colors,
+            labelStyle: host.labelStyle,
+            labelSize: { min: host.minLabelSize, max: host.maxLabelSize },
+            markerRadius: marker?.marker.radius ?? host.markerRadius,
+        });
+        return preparedLabels;
+    }
+    function drawLabels() {
+        if (host.destroyed)
+            return;
+        const canvasBox = canvas.getBoundingClientRect();
+        const width = canvasBox.width;
+        if (!width)
+            return;
+        const unit = host.view[2] / width, zoom = 800 / host.view[2];
+        if (host.features.scaleBar) {
+            const pixelsPerMeter = scaleUnitsPerMeter / unit;
+            const base = 10 ** Math.floor(Math.log10(100 / pixelsPerMeter));
+            const meters = [5, 2, 1].map((factor) => factor * base).find((value) => value * pixelsPerMeter <= 100) ??
+                base;
+            const scaleWidth = `${meters * pixelsPerMeter}px`;
+            const scaleText = meters >= 1000 ? `${meters / 1000} km` : `${meters} m`;
+            if (scale.style.width !== scaleWidth)
+                scale.style.width = scaleWidth;
+            if (scale.textContent !== scaleText)
+                scale.textContent = scaleText;
+        }
+        // Read overlay bounds before SVG writes; scale furniture above must have its current width.
+        const furnitureBounds = [...overlayElement.children]
+            .filter((node) => node.getClientRects().length > 0)
+            .map((node) => {
+            const box = node.getBoundingClientRect();
+            return [
+                box.left - canvasBox.left - 3,
+                box.top - canvasBox.top - 3,
+                box.right - canvasBox.left + 3,
+                box.bottom - canvasBox.top + 3,
+            ];
+        });
+        const showSecondaryRoads = zoom >= 1.8;
+        if (showSecondaryRoads !== secondaryRoadsVisible) {
+            for (const road of secondaryRoads)
+                road.style.display = showSecondaryRoads ? '' : 'none';
+            secondaryRoadsVisible = showSecondaryRoads;
+        }
+        for (const station of stationItems)
+            setAttributeIfChanged(station.node, 'r', 4.5 * unit);
+        drawClusters(unit);
+        if (!host.labels) {
+            labelRenderer.clear();
+            root.dataset.visibleLabels = '0';
+            return;
+        }
+        const labelCandidates = prepareLabels(width, zoom);
+        const stationBounds = (enabled('bartStations') ? stationItems : []).map(({ point }) => {
+            const x = (point[0] - host.view[0]) / unit;
+            const y = (point[1] - host.view[1]) / unit;
+            return [x - 6, y - 6, x + 6, y + 6];
+        });
+        const markerBounds = host.renderedMarkers.map(({ point, marker }) => {
+            const radius = marker.radius ?? host.markerRadius;
+            const x = (point[0] - host.view[0]) / unit, y = (point[1] - host.view[1]) / unit;
+            return [x - radius - 3, y - radius - 3, x + radius + 3, y + radius + 3];
+        });
+        root.dataset.visibleLabels = String(labelRenderer.draw(labelCandidates, host.view, width, [
+            ...stationBounds,
+            ...markerBounds,
+            ...furnitureBounds,
+            ...host.renderedClusters.map(({ point }) => {
+                const x = (point[0] - host.view[0]) / unit, y = (point[1] - host.view[1]) / unit;
+                return [x - 26, y - 26, x + 26, y + 26];
+            }),
+        ]));
+    }
+    return {
+        draw: drawLabels,
+        schedule() {
+            if (!host.destroyed)
+                host.invalidateFrame();
+        },
+        invalidateMetrics() {
+            labelRenderer.invalidateMetrics();
+            labelInputs = [];
+        },
+        clear() {
+            labelRenderer.clear();
+            labelInputs = [];
+            preparedLabels = [];
+        },
+    };
+}

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

@@ -0,0 +1,55 @@
+import type { Position } from '../data/types.js';
+import { type View } from './explorer-layout.js';
+import type { normalizeFeatures } from './features.js';
+import type { createMarkerCatalog } from './marker-catalog.js';
+import type { createMarkerChooser } from './marker-chooser.js';
+import type { MarkerItem, MarkerVisual } from './marker-layer.js';
+import type { createMarkerNavigation } from './marker-navigation.js';
+import type { CameraOptions, MapMarker, NeighborhoodExplorerOptions } from './types.js';
+interface MarkerHost {
+    root: HTMLElement;
+    canvas: HTMLElement;
+    svg: SVGSVGElement;
+    markerLayer: SVGGElement;
+    markerSelect: HTMLSelectElement;
+    markerLabel: HTMLElement;
+    markerCatalog: ReturnType<typeof createMarkerCatalog>;
+    markerNavigation: ReturnType<typeof createMarkerNavigation>;
+    get markerChooser(): ReturnType<typeof createMarkerChooser>;
+    get destroyed(): boolean;
+    get view(): View;
+    get features(): ReturnType<typeof normalizeFeatures>;
+    get markerColor(): string;
+    get selectedMarkerColor(): string;
+    get controls(): NonNullable<NeighborhoodExplorerOptions['controls']>;
+    strings: NonNullable<NeighborhoodExplorerOptions['strings']>;
+    fitPadding: NonNullable<NeighborhoodExplorerOptions['fitPadding']>;
+    onMarkerActivate: NeighborhoodExplorerOptions['onMarkerActivate'];
+    invalidateClusters(): void;
+    drawClusters(unit: number): void;
+    materializeMarker(item: MarkerItem): MarkerItem & {
+        visual: MarkerVisual;
+    };
+    scheduleLabels(): void;
+    syncFeatureControls(): void;
+    moveView(view: View, options?: CameraOptions): void;
+}
+/** Own selection revisions, activation and focus recovery independently of marker rendering. */
+export declare function createMarkerController(host: MarkerHost): {
+    getSelectedMarker: () => {
+        id: string;
+        label?: string;
+        selected?: boolean;
+        color?: string;
+        radius?: number;
+        position: Position;
+    } | null;
+    selectMarker: (id: string | null, options?: {
+        fit?: boolean;
+    } & CameraOptions) => boolean;
+    setMarkers: (markers: readonly MapMarker[]) => void;
+    activateMarker: (id: string, node: SVGElement) => void;
+    readonly selected: string | null;
+    readonly revision: number;
+};
+export {};

package/dist/src/marker-controller.js

@@ -0,0 +1,125 @@
+import { validateCameraOptions } from './camera.js';
+import { fitBounds } from './explorer-layout.js';
+import { fitViewport } from './viewport.js';
+/** Own selection revisions, activation and focus recovery independently of marker rendering. */
+export function createMarkerController(host) {
+    const { root, canvas, svg, markerLayer, markerSelect, markerLabel, markerCatalog, markerNavigation, strings, fitPadding, onMarkerActivate, invalidateClusters, drawClusters, materializeMarker, scheduleLabels, syncFeatureControls, moveView, } = host;
+    let selectedMarker = null;
+    let markerRevision = 0;
+    function getSelectedMarker() {
+        const marker = markerCatalog.items.find((item) => item.marker.id === selectedMarker)?.marker;
+        return marker ? { ...marker, position: [...marker.position] } : null;
+    }
+    function selectMarker(id, options = {}) {
+        if (host.destroyed)
+            return false;
+        const item = markerCatalog.items.find((item) => item.marker.id === id);
+        if (id !== null && !item)
+            return false;
+        validateCameraOptions(options);
+        const width = canvas.getBoundingClientRect().width;
+        const target = item && options.fit !== false
+            ? width
+                ? fitViewport([...item.point, ...item.point], width, fitPadding)
+                : fitBounds([...item.point, ...item.point])
+            : null;
+        const revision = ++markerRevision;
+        const changed = selectedMarker !== id;
+        selectedMarker = id;
+        if (changed)
+            invalidateClusters();
+        markerSelect.value = id ?? '';
+        for (const entry of markerCatalog.items) {
+            const active = entry.marker.id === id;
+            const visual = active ? materializeMarker(entry).visual : entry.visual;
+            if (!visual)
+                continue;
+            const pressed = String(active);
+            const ring = active && host.features.selectedMarkerRing ? 'inline' : 'none';
+            const fill = active ? host.selectedMarkerColor : (entry.marker.color ?? host.markerColor);
+            if (visual.node.getAttribute('aria-pressed') !== pressed)
+                visual.node.setAttribute('aria-pressed', pressed);
+            if (visual.ring.getAttribute('display') !== ring)
+                visual.ring.setAttribute('display', ring);
+            if (visual.dot.getAttribute('fill') !== fill)
+                visual.dot.setAttribute('fill', fill);
+            if (active && markerLayer.lastChild !== visual.node)
+                markerLayer.append(visual.node);
+        }
+        scheduleLabels();
+        if (width || !host.features.clustering)
+            drawClusters(width ? host.view[2] / width : 1);
+        const marker = getSelectedMarker();
+        if (changed)
+            root.dispatchEvent(new CustomEvent('markerchange', { bubbles: true, detail: { id, marker } }));
+        if (!host.destroyed &&
+            changed &&
+            marker &&
+            markerRevision === revision &&
+            selectedMarker === id)
+            onMarkerActivate?.({ ...marker });
+        if (!host.destroyed && markerRevision === revision && target)
+            moveView(target, options);
+        return true;
+    }
+    function setMarkers(markers) {
+        if (host.destroyed)
+            return;
+        const prepared = markerCatalog.prepare(markers, selectedMarker);
+        if (!prepared)
+            return;
+        const { selection: nextSelection, focused: focusedMarker } = prepared;
+        invalidateClusters();
+        prepared.commit();
+        markerLabel.hidden = !markerCatalog.items.length || host.controls.markerPicker === false;
+        if (markerLabel.firstChild)
+            markerLabel.firstChild.textContent = `${strings.chooseMarker ?? 'Choose marker'} (${markerCatalog.items.length})`;
+        syncFeatureControls();
+        const revision = markerRevision + 1;
+        selectMarker(nextSelection, { fit: false });
+        if (!host.destroyed && markerRevision === revision && focusedMarker) {
+            markerNavigation.sync(markerCatalog.items.flatMap((item) => (item.visual ? [item.visual.node] : [])));
+            if (!markerNavigation.recover()) {
+                const recovery = markerCatalog.items.find((item) => item.marker.id === focusedMarker) ??
+                    markerCatalog.items[0];
+                if (recovery) {
+                    const { node } = materializeMarker(recovery).visual;
+                    markerLayer.append(node);
+                    node.focus({ preventScroll: true });
+                    const width = canvas.getBoundingClientRect().width;
+                    if (width)
+                        drawClusters(host.view[2] / width);
+                }
+                else
+                    svg.focus({ preventScroll: true });
+            }
+        }
+    }
+    function activateMarker(id, node) {
+        const item = markerCatalog.items.find((item) => item.marker.id === id);
+        if (!item)
+            return;
+        const coincident = markerCatalog.items.filter((other) => other.point[0] === item.point[0] && other.point[1] === item.point[1]);
+        if (coincident.length > 1)
+            host.markerChooser.open(coincident.map((other) => other.marker), node);
+        else {
+            selectMarker(id);
+            if (!host.destroyed && selectedMarker === id)
+                markerCatalog.items
+                    .find((other) => other.marker.id === id)
+                    ?.visual?.node.focus({ preventScroll: true });
+        }
+    }
+    return {
+        getSelectedMarker,
+        selectMarker,
+        setMarkers,
+        activateMarker,
+        get selected() {
+            return selectedMarker;
+        },
+        get revision() {
+            return markerRevision;
+        },
+    };
+}

package/llms-full.txt

@@ -2,13 +2,13 @@
 
 > Offline San Francisco SVG maps with explicit geographic imports, no runtime dependencies, static rendering, and a browser controller.
 
-@kahwee/sf-map-svg 5.1.1 · local working tree. Node >=24.0.0 for server rendering; browsers need a DOM and a JSON-capable bundler.
+@kahwee/sf-map-svg 5.1.2 · local working tree. Node >=24.0.0 for server rendering; browsers need a DOM and a JSON-capable bundler.
 
 These are working-tree docs. Unreleased changelog entries may describe APIs absent from npm; verify the installed version before copying them.
 
 Use renderMap(data, options) for SVG strings; createMap(data, options) returns a controller. Mount map.element and destroy it on unmount. Choose mode explicitly: createMap defaults to basemap. Geography is separate; staticMapData and fullMapData have different shapes.
 
-<!-- Generated from README.md; @kahwee/sf-map-svg 5.1.1 · local working tree. -->
+<!-- Generated from README.md; @kahwee/sf-map-svg 5.1.2 · local working tree. -->
 
 # SF Map SVG
 
@@ -267,7 +267,7 @@ for raw samples, output-equivalence checks, and reproducible commands.
 
 ---
 
-<!-- Generated from docs/developer-guide.md; @kahwee/sf-map-svg 5.1.1 · local working tree. -->
+<!-- Generated from docs/developer-guide.md; @kahwee/sf-map-svg 5.1.2 · local working tree. -->
 
 # Developer guide
 
@@ -433,7 +433,7 @@ See [API options](https://github.com/kahwee/sf-map-svg/blob/main/docs/API.md), [
 
 ---
 
-<!-- Generated from docs/API.md; @kahwee/sf-map-svg 5.1.1 · local working tree. -->
+<!-- Generated from docs/API.md; @kahwee/sf-map-svg 5.1.2 · local working tree. -->
 
 # Map options and lifecycle
 
@@ -619,7 +619,7 @@ Call `binding.setMarkers(next)` after `map.setMarkers(next)` when the catalog ch
 
 ---
 
-<!-- Generated from docs/EXAMPLES.md; @kahwee/sf-map-svg 5.1.1 · local working tree. -->
+<!-- Generated from docs/EXAMPLES.md; @kahwee/sf-map-svg 5.1.2 · local working tree. -->
 
 # Examples
 
@@ -760,7 +760,7 @@ See [query semantics and limitations](https://github.com/kahwee/sf-map-svg/blob/
 
 ---
 
-<!-- Generated from docs/consumer-integration.md; @kahwee/sf-map-svg 5.1.1 · local working tree. -->
+<!-- Generated from docs/consumer-integration.md; @kahwee/sf-map-svg 5.1.2 · local working tree. -->
 
 # Embedding and progressive enhancement
 
@@ -938,7 +938,7 @@ keyboard, focus, and dismissal behavior. See [coordinates and units](https://git
 
 ---
 
-<!-- Generated from docs/migration-v5.md; @kahwee/sf-map-svg 5.1.1 · local working tree. -->
+<!-- Generated from docs/migration-v5.md; @kahwee/sf-map-svg 5.1.2 · local working tree. -->
 
 # Migrating to v5
 
@@ -1043,7 +1043,7 @@ collections. Shared edges can match more than one feature. See the
 
 ---
 
-<!-- Generated from docs/migration-v3.md; @kahwee/sf-map-svg 5.1.1 · local working tree. -->
+<!-- Generated from docs/migration-v3.md; @kahwee/sf-map-svg 5.1.2 · local working tree. -->
 
 # Migrate to version 3
 
@@ -1084,7 +1084,7 @@ District styles are now prepared once per district on construction and style/yea
 
 ---
 
-<!-- Generated from SOURCES.md; @kahwee/sf-map-svg 5.1.1 · local working tree. -->
+<!-- Generated from SOURCES.md; @kahwee/sf-map-svg 5.1.2 · local working tree. -->
 
 # Geometry and provenance
 
@@ -1321,7 +1321,7 @@ Report-history points preserve only actual validated source counts and their dis
 
 ---
 
-<!-- Generated from CHANGELOG.md; @kahwee/sf-map-svg 5.1.1 · local working tree. -->
+<!-- Generated from CHANGELOG.md; @kahwee/sf-map-svg 5.1.2 · local working tree. -->
 
 # Changelog
 
@@ -1329,6 +1329,10 @@ User-visible changes are recorded here. Unreleased entries describe changes on `
 
 ## Unreleased
 
+## 5.1.2 — 2026-11-05
+
+- Separate marker selection, activation and focus recovery into an internal controller; separate label candidate caching, screen-space collision layout and metrics invalidation into a label coordinator. Preserve the public API and shared animation frame scheduling.
+
 ## 5.1.1 — 2026-11-05
 
 - Reserve precinct report controls and status space during loading to prevent phone layout shifts when multiple reports are available.
@@ -1717,7 +1721,7 @@ consistent home, and makes animation and subscription ownership predictable.
 
 # Published type contracts
 
-@kahwee/sf-map-svg 5.1.1 · local working tree. These declarations are generated by TypeScript. Use package export paths, not the internal filenames below. Imported relative contracts are included for context, not as additional public entry points.
+@kahwee/sf-map-svg 5.1.2 · local working tree. These declarations are generated by TypeScript. Use package export paths, not the internal filenames below. Imported relative contracts are included for context, not as additional public entry points.
 
 | Public import | Declaration |
 | --- | --- |

package/llms.txt

@@ -2,7 +2,7 @@
 
 > Offline San Francisco SVG maps with explicit geographic imports, no runtime dependencies, static rendering, and a browser controller.
 
-@kahwee/sf-map-svg 5.1.1 · local working tree. Node >=24.0.0 for server rendering; browsers need a DOM and a JSON-capable bundler.
+@kahwee/sf-map-svg 5.1.2 · local working tree. Node >=24.0.0 for server rendering; browsers need a DOM and a JSON-capable bundler.
 
 These are working-tree docs. Unreleased changelog entries may describe APIs absent from npm; verify the installed version before copying them.
 

package/package.json

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