@kahwee/sf-map-svg 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -4,6 +4,23 @@ User-visible changes are recorded here. Unreleased entries describe changes on `
 
 ## Unreleased
 
+## 3.1.0 — 2026-09-28
+
+- Add `createGuideController` and `mountGuideController` with the grouped options, camera, subscriptions, and lifecycle of `createMap`; preserve existing element-based guide factories.
+- Reject invalid marker coordinates before static rendering invokes district-style callbacks.
+- Prepare district styles once per update before changing the map, and reuse projected district paths.
+- Track both district crossfades so interrupted transitions, reduced motion, and teardown remove all outgoing layers.
+- Reuse label nodes and screen-space text measurements during camera movement, refreshing metrics when fonts load; separate label rendering and district appearance from the interactive engine.
+- Give marker visuals and entrance animations their own lifecycle, and prevent reentrant district callbacks from overwriting newer state or restarting work after destruction.
+- Document guide-controller integration and district-style refresh semantics; add browser regressions for callback atomicity, interrupted fades, camera motion, marker replacement, label reuse, and progressive shell mounting.
+
+## 3.0.1 — 2026-09-27
+
+- Narrow the complete-data presets to their direct geographic modules without changing rendered SVGs or public API behavior.
+- Correct stale contributing and example documentation links, add a local Markdown link check to `pnpm check`, and show the v3 controller API on the Pages homepage.
+- Skip the early push-triggered Pages build while a new package version is still processing on npm; the successful release workflow deploys that version from the registry.
+- Serve local visual snapshots with the same streaming Node HTTP approach as the Pages browser check, avoiding intermittent resets while loading large optional map data.
+
 ## 3.0.0 — 2026-09-27
 
 Version 3 removes the deprecated compatibility APIs. Applications must migrate before upgrading. The data-free root API introduced in version 2 remains the supported API.

package/README.md

@@ -16,16 +16,16 @@ Node 22.12+ is required for server rendering. Browser maps need a DOM and a bund
 
 ```ts
 import { renderMap } from '@kahwee/sf-map-svg';
-import { fullMapData } from '@kahwee/sf-map-svg/data/full';
+import { staticMapData } from '@kahwee/sf-map-svg/data/static';
 
-const { svg, project, viewBox } = renderMap(fullMapData.map, {
+const { svg, project, viewBox } = renderMap(staticMapData, {
   year: 2022,
   landmarks: true,
   bartStations: true,
 });
 ```
 
-`renderMap(data, options)` returns SVG markup and matching projection helpers. Import `/data/full` only when all packaged geography is needed. For static rendering without interactive lookup collections, import `staticMapData` from `/data/static`. Small maps can compose selected JSON exports from `/data/*` and pass them as `StaticMapData`. `getLayerPaths(data, options)` returns fitted geographic paths without SVG markup.
+`renderMap(data, options)` returns SVG markup and matching projection helpers. `/data/static` includes the complete static map without interactive lookup collections. Small maps can compose selected JSON exports from `/data/*` and pass them as `StaticMapData`. `getLayerPaths(data, options)` returns fitted geographic paths without SVG markup.
 
 Static options include `theme`, `width`, `height`, `padding`, `year` (2002, 2012, 2022), `districtLines`, `districtFills`, `districtStyle`, `districtLabels`, `neighborhoodLines`, `labels`, `highways`, `keyRoads`, `roadLabels`, `landmarks`, `bartStations`, `markers`, `overlays`, `title`, `idPrefix`, and `colors`. Each optional layer is independent. User-supplied text and attributes are escaped in SVG output.
 
@@ -52,12 +52,16 @@ map.destroy();
 
 `createMap(data, options)` returns a controller. Use `map.element` for mounting, `map.configure({ features, layers, controls })` for runtime switches, `map.camera` for pan/zoom/fit/reset, and `map.on()` for typed events. Appearance is set at construction. SFAR realtor neighborhoods are the default when supplied; SF Find and analysis are explicit alternate sources. The `/data/full` preset includes all three collections and historical districts.
 
-Construction options include `mode` (`basemap`, `neighborhoods`, or `districts`), `source`, `neighborhood`, `year`, `labels`, `layers`, `controls`, `features`, `appearance`, `markers`, `overlays`, `legend`, `strings`, `attribution`, `fitPadding`, and touch navigation settings. `features` holds motion, marker entrances, selected marker rings, clustering, north arrow, and scale bar. `appearance` holds theme, color tokens, label and area styles, marker colors and sizes, and district styling. `layers` controls district fill/line/labels, neighborhood lines/labels, landmarks, BART, highways, key roads, and road labels. See the exported `MapOptions` type for exact values and the [Storybook examples](stories/) for live controls.
+Construction options include `mode` (`basemap`, `neighborhoods`, or `districts`), `source`, `neighborhood`, `year`, `labels`, `layers`, `controls`, `features`, `appearance`, `markers`, `overlays`, `legend`, `strings`, `attribution`, and `fitPadding`. Enable map touch gestures with the touch control or `map.setTouchNavigation(true)`. `features` holds motion, marker entrances, selected marker rings, clustering, north arrow, and scale bar. `appearance` holds theme, color tokens, label and area styles, marker colors and sizes, and district styling. `layers` controls district fill/line/labels, neighborhood lines/labels, landmarks, BART, highways, key roads, and road labels. See the exported `MapOptions` type for exact values and the [Storybook examples](stories/) for live controls.
 
 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.
 
 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.
+
+District style callbacks are evaluated once per district at construction and on style or year updates. Hover, selection, and layer toggles reuse the prepared styles; call `setDistrictStyle()` again when external styling data changes. Invalid styles leave the current map unchanged. District fades respect reduced motion and are removed on interruption or destruction.
+
 ## Data and development
 
 Canonical geography is in [`data/`](data/README.md), with provenance in [`SOURCES.md`](SOURCES.md). The public `/data` entry exposes lookup, catalog, district maps, and source-specific neighborhood collections. These are deeply frozen; clone before editing.

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

@@ -0,0 +1,15 @@
+import type { DistrictRowData } from './map-core.js';
+import type { DistrictStyle, DistrictYear, SFMapOptions } from './types.js';
+/** Apply prepared styles and interaction state without invoking consumer callbacks. */
+export declare function renderDistrictAppearance({ svg, rows, styles, selectedDistrict, hoveredDistrict, year, theme, colors, fills, lines, }: {
+    svg: SVGSVGElement;
+    rows: readonly DistrictRowData[];
+    styles: ReadonlyMap<number, DistrictStyle>;
+    selectedDistrict: number | null;
+    hoveredDistrict: number | null;
+    year: DistrictYear;
+    theme: SFMapOptions['theme'];
+    colors: NonNullable<SFMapOptions['colors']>;
+    fills: boolean;
+    lines: boolean;
+}): void;

package/dist/src/district-layer.js

@@ -0,0 +1,51 @@
+import { districtColors } from './map-core.js';
+/** Apply prepared styles and interaction state without invoking consumer callbacks. */
+export function renderDistrictAppearance({ svg, rows, styles, selectedDistrict, hoveredDistrict, year, theme, colors, fills, lines, }) {
+    for (const row of rows) {
+        const styled = styles.get(row.id);
+        const active = selectedDistrict === row.id;
+        const hovered = hoveredDistrict === row.id;
+        const fill = svg.querySelector(`[data-layer="district-fills"] [data-district="${row.id}"]`);
+        const line = svg.querySelector(`[data-layer="district-lines"] [data-district="${row.id}"]`);
+        if (fill) {
+            fill.setAttribute('fill', styled?.fill ??
+                (theme === 'transit' ? (colors.land ?? '#fcfcf8') : districtColors[row.id - 1]));
+            if (styled?.opacity === undefined)
+                fill.removeAttribute('fill-opacity');
+            else
+                fill.setAttribute('fill-opacity', String(styled.opacity));
+            fill.setAttribute('role', 'button');
+            fill.setAttribute('aria-label', `District ${row.id}, ${year}`);
+            fill.setAttribute('aria-pressed', String(active));
+            fill.setAttribute('tabindex', row.id === 1 ? '0' : '-1');
+            fill.style.cursor = 'pointer';
+        }
+        if (line) {
+            line.setAttribute('stroke', active
+                ? (colors.selected ?? '#f04f32')
+                : hovered
+                    ? '#163e56'
+                    : (styled?.stroke ?? colors.district ?? '#a7b8c0'));
+            line.setAttribute('stroke-width', active ? '3' : hovered ? '2.2' : '1.1');
+            const lineInteractive = !fills && lines;
+            line.style.pointerEvents = lineInteractive ? 'stroke' : 'none';
+            if (lineInteractive) {
+                line.setAttribute('role', 'button');
+                line.setAttribute('aria-label', `District ${row.id}, ${year}`);
+                line.setAttribute('aria-pressed', String(active));
+                line.setAttribute('tabindex', row.id === 1 ? '0' : '-1');
+                line.style.cursor = 'pointer';
+            }
+            else {
+                line.removeAttribute('role');
+                line.removeAttribute('aria-label');
+                line.removeAttribute('aria-pressed');
+                line.removeAttribute('tabindex');
+            }
+            if (styled?.opacity === undefined)
+                line.removeAttribute('stroke-opacity');
+            else
+                line.setAttribute('stroke-opacity', String(styled.opacity));
+        }
+    }
+}

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

@@ -0,0 +1,4 @@
+import type { DistrictRowData } from './map-core.js';
+import type { DistrictStyle, SFMapOptions } from './types.js';
+/** Evaluate user code once and copy its result before changing the map. */
+export declare function prepareDistrictStyles(rows: readonly DistrictRowData[], callback: SFMapOptions['districtStyle']): ReadonlyMap<number, DistrictStyle>;

package/dist/src/district-style.js

@@ -0,0 +1,23 @@
+/** Evaluate user code once and copy its result before changing the map. */
+export function prepareDistrictStyles(rows, callback) {
+    if (callback !== undefined && typeof callback !== 'function')
+        throw new TypeError('districtStyle must be a function.');
+    return new Map(rows.map((row) => [row.id, validateDistrictStyle(callback?.(row))]));
+}
+function validateDistrictStyle(style) {
+    if (style === undefined)
+        return {};
+    if (!style || typeof style !== 'object' || Array.isArray(style))
+        throw new TypeError('districtStyle must return a style object.');
+    for (const key of Object.keys(style))
+        if (!['fill', 'stroke', 'opacity'].includes(key))
+            throw new TypeError(`Unknown district style: ${key}`);
+    const copy = { ...style };
+    for (const key of ['fill', 'stroke'])
+        if (copy[key] !== undefined && typeof copy[key] !== 'string')
+            throw new TypeError(`${key} must be a string.`);
+    if (copy.opacity !== undefined &&
+        (!Number.isFinite(copy.opacity) || copy.opacity < 0 || copy.opacity > 1))
+        throw new RangeError('District opacity must be between 0 and 1.');
+    return copy;
+}

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

@@ -0,0 +1,5 @@
+/** Own both district-layer fades and remove their inert copies synchronously on cancellation. */
+export declare function createDistrictTransition(): {
+    cancel(): void;
+    fade(layer: SVGGElement, duration: number): void;
+};

package/dist/src/district-transition.js

@@ -0,0 +1,38 @@
+/** Own both district-layer fades and remove their inert copies synchronously on cancellation. */
+export function createDistrictTransition() {
+    const active = new Map();
+    const remove = (animation, node) => {
+        active.delete(animation);
+        node.remove();
+    };
+    return {
+        cancel() {
+            for (const [animation, node] of active) {
+                animation.cancel();
+                node.remove();
+            }
+            active.clear();
+        },
+        fade(layer, duration) {
+            if (!duration)
+                return;
+            const old = layer.cloneNode(true);
+            old.dataset.districtTransition = '';
+            old.setAttribute('aria-hidden', 'true');
+            old.style.pointerEvents = 'none';
+            for (const path of old.querySelectorAll('[data-district]')) {
+                path.removeAttribute('tabindex');
+                path.removeAttribute('role');
+                path.removeAttribute('aria-label');
+                path.removeAttribute('aria-pressed');
+            }
+            layer.after(old);
+            const animation = old.animate([{ opacity: 1 }, { opacity: 0 }], {
+                duration,
+                easing: 'ease-out',
+            });
+            active.set(animation, old);
+            animation.finished.then(() => remove(animation, old), () => remove(animation, old));
+        },
+    };
+}

package/dist/src/dom.d.ts

@@ -0,0 +1,2 @@
+export declare function element<K extends keyof HTMLElementTagNameMap>(tag: K, text?: string, className?: string): HTMLElementTagNameMap[K];
+export declare function svgElement<K extends keyof SVGElementTagNameMap>(tag: K, attributes?: Record<string, string | number>): SVGElementTagNameMap[K];

package/dist/src/dom.js

@@ -0,0 +1,14 @@
+export function element(tag, text, className) {
+    const node = document.createElement(tag);
+    if (text)
+        node.textContent = text;
+    if (className)
+        node.className = className;
+    return node;
+}
+export function svgElement(tag, attributes = {}) {
+    const node = document.createElementNS('http://www.w3.org/2000/svg', tag);
+    for (const [key, value] of Object.entries(attributes))
+        node.setAttribute(key, String(value));
+    return node;
+}

package/dist/src/explorer-core.js

@@ -1,13 +1,18 @@
 import { createCamera, validateCameraOptions } from './camera.js';
 import { clusterPoints } from './clusters.js';
-import { fitBounds, interiorAnchor, layoutLabels, projectedBounds } from './explorer-layout.js';
+import { renderDistrictAppearance } from './district-layer.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 { geometryPath } from './geometry.js';
+import { createLabelRenderer } from './label-renderer.js';
 import { createSFMapWithData, districtColors, getLayerPathsWithData } from './map-core.js';
+import { createMarkerLayer } from './marker-layer.js';
 import { attachNavigation } from './navigation.js';
 import { validateExplorerOptions, validateMarkers, validateOverlays } from './validation.js';
 import { fitViewport, validateViewport } from './viewport.js';
-const svgNS = 'http://www.w3.org/2000/svg';
 const sourceNames = {
     realtor: 'SFAR realtor · 92 areas',
     'sf-find': 'SF Find · 117 areas',
@@ -20,20 +25,6 @@ const normalizeName = (value) => value
     .replace(/[^a-z0-9]+/g, ' ')
     .trim();
 const formatSourceLabel = (source) => sourceNames[source] ?? `${source} neighborhoods`;
-function element(tag, text, className) {
-    const node = document.createElement(tag);
-    if (text)
-        node.textContent = text;
-    if (className)
-        node.className = className;
-    return node;
-}
-function svgElement(tag, attributes = {}) {
-    const node = document.createElementNS(svgNS, tag);
-    for (const [key, value] of Object.entries(attributes))
-        node.setAttribute(key, String(value));
-    return node;
-}
 let explorerCount = 0;
 /** Create an offline, browser-only neighborhood explorer. Call destroy() before disposal. */
 export function createNeighborhoodExplorerCore(options = {}, data) {
@@ -314,7 +305,6 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
         districtLabels: false,
         districtLines: true,
         districtFills: true,
-        districtStyle: initialDistrictStyle,
         highways: true,
         keyRoads: true,
         roadLabels: false,
@@ -380,13 +370,16 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
         '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];
     let selected;
     let selectedDistrict = null;
     let hoveredDistrict = null;
     let districtStyle = initialDistrictStyle;
-    let districtTransition;
+    let districtStyles = prepareDistrictStyles(data.map.districts?.[year] ?? [], districtStyle);
+    const districtTransition = createDistrictTransition();
+    let districtRevision = 0;
     root.dataset.year = String(year);
     function districtRow(id) {
         return data.map.districts?.[year]?.find((district) => district.id === id);
@@ -403,54 +396,18 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
             : districtSelection(selectedDistrict);
     }
     function updateDistrictAppearance() {
-        const rows = data.map.districts?.[year] ?? [];
-        for (const row of rows) {
-            const styled = districtStyle?.(row);
-            const active = selectedDistrict === row.id;
-            const hovered = hoveredDistrict === row.id;
-            const fill = svg.querySelector(`[data-layer="district-fills"] [data-district="${row.id}"]`);
-            const line = svg.querySelector(`[data-layer="district-lines"] [data-district="${row.id}"]`);
-            if (fill) {
-                fill.setAttribute('fill', styled?.fill ??
-                    (theme === 'transit' ? (colors.land ?? '#fcfcf8') : districtColors[row.id - 1]));
-                if (styled?.opacity === undefined)
-                    fill.removeAttribute('fill-opacity');
-                else
-                    fill.setAttribute('fill-opacity', String(styled.opacity));
-                fill.setAttribute('role', 'button');
-                fill.setAttribute('aria-label', `District ${row.id}, ${year}`);
-                fill.setAttribute('aria-pressed', String(active));
-                fill.setAttribute('tabindex', row.id === 1 ? '0' : '-1');
-                fill.style.cursor = 'pointer';
-            }
-            if (line) {
-                line.setAttribute('stroke', active
-                    ? (colors.selected ?? '#f04f32')
-                    : hovered
-                        ? '#163e56'
-                        : (styled?.stroke ?? colors.district ?? '#a7b8c0'));
-                line.setAttribute('stroke-width', active ? '3' : hovered ? '2.2' : '1.1');
-                const lineInteractive = !enabled('districtFills') && enabled('districtLines');
-                line.style.pointerEvents = lineInteractive ? 'stroke' : 'none';
-                if (lineInteractive) {
-                    line.setAttribute('role', 'button');
-                    line.setAttribute('aria-label', `District ${row.id}, ${year}`);
-                    line.setAttribute('aria-pressed', String(active));
-                    line.setAttribute('tabindex', row.id === 1 ? '0' : '-1');
-                    line.style.cursor = 'pointer';
-                }
-                else {
-                    line.removeAttribute('role');
-                    line.removeAttribute('aria-label');
-                    line.removeAttribute('aria-pressed');
-                    line.removeAttribute('tabindex');
-                }
-                if (styled?.opacity === undefined)
-                    line.removeAttribute('stroke-opacity');
-                else
-                    line.setAttribute('stroke-opacity', String(styled.opacity));
-            }
-        }
+        renderDistrictAppearance({
+            svg,
+            rows: data.map.districts?.[year] ?? [],
+            styles: districtStyles,
+            selectedDistrict,
+            hoveredDistrict,
+            year,
+            theme,
+            colors,
+            fills: enabled('districtFills'),
+            lines: enabled('districtLines'),
+        });
     }
     function selectDistrict(id, options = {}) {
         if (destroyed)
@@ -459,6 +416,7 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
         if (id !== null && (!Number.isInteger(id) || !districtRow(id)))
             return false;
         const changed = selectedDistrict !== id;
+        const revision = ++districtRevision;
         selectedDistrict = id;
         if (id === null)
             delete root.dataset.selectedDistrict;
@@ -468,6 +426,8 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
         const selectedRow = id === null ? undefined : districtRow(id);
         if (selectedRow && options.fit)
             fitGeometry(selectedRow.geometry, undefined, options);
+        if (destroyed || revision !== districtRevision)
+            return true;
         status.textContent =
             id === null ? 'District selection cleared.' : `District ${id} selected, ${year} boundaries.`;
         if (changed)
@@ -477,10 +437,13 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
     function setDistrictStyle(style) {
         if (destroyed)
             return;
-        if (style !== undefined && typeof style !== 'function')
-            throw new TypeError('districtStyle must be a function.');
-        createSFMapWithData({ year, districtStyle: style, districtLabels: false }, data.map);
+        const revision = districtRevision;
+        const prepared = prepareDistrictStyles(data.map.districts?.[year] ?? [], style);
+        if (destroyed || revision !== districtRevision)
+            return;
+        districtRevision++;
         districtStyle = style;
+        districtStyles = prepared;
         updateDistrictAppearance();
     }
     function setDistrictYear(next, options = {}) {
@@ -493,28 +456,17 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
             throw new RangeError(`No ${next} district dataset was supplied.`);
         if (next === year)
             return;
-        const geometry = getLayerPathsWithData({ year: next }, data.map);
-        createSFMapWithData({ year: next, districtStyle, districtLabels: false }, data.map);
+        const revision = districtRevision;
+        const prepared = prepareDistrictStyles(data.map.districts[next], districtStyle);
+        if (destroyed || revision !== districtRevision)
+            return;
+        const committedRevision = ++districtRevision;
+        const geometry = getLayerPathsWithData({ year: next }, data.map, false);
         const previousYear = year;
-        districtTransition?.cancel();
+        districtTransition.cancel();
         for (const layer of districtLayers) {
-            const old = options.animate && !reducedMotion.matches ? layer.cloneNode(true) : null;
-            if (old) {
-                old.setAttribute('aria-hidden', 'true');
-                old.style.pointerEvents = 'none';
-                for (const path of old.querySelectorAll('[data-district]')) {
-                    path.removeAttribute('tabindex');
-                    path.removeAttribute('role');
-                    path.removeAttribute('aria-label');
-                    path.removeAttribute('aria-pressed');
-                }
-                layer.after(old);
-                districtTransition = old.animate([{ opacity: 1 }, { opacity: 0 }], {
-                    duration: options.duration ?? 280,
-                    easing: 'ease-out',
-                });
-                districtTransition.finished.then(() => old.remove()).catch(() => old.remove());
-            }
+            if (options.animate && !reducedMotion.matches)
+                districtTransition.fade(layer, options.duration ?? 280);
             layer.replaceChildren(...geometry.districts.map((district) => svgElement('path', {
                 'data-district': district.id,
                 d: district.path,
@@ -524,6 +476,7 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
             })));
         }
         year = next;
+        districtStyles = prepared;
         hoveredDistrict = null;
         root.dataset.year = String(year);
         svg.dataset.year = String(year);
@@ -541,7 +494,7 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
         scheduleLabels();
         status.textContent = `${year} supervisorial districts.`;
         root.dispatchEvent(new CustomEvent('districtyearchange', { bubbles: true, detail: { year, previousYear } }));
-        if (selectedDistrict !== null)
+        if (!destroyed && committedRevision === districtRevision && selectedDistrict !== null)
             root.dispatchEvent(new CustomEvent('districtchange', {
                 bubbles: true,
                 detail: districtSelection(selectedDistrict),
@@ -552,12 +505,8 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
     let destroyed = false;
     let initialized = false;
     let frame = 0;
-    const entranceAnimations = new Set();
-    function cancelEntrances() {
-        for (const animation of entranceAnimations)
-            animation.cancel();
-        entranceAnimations.clear();
-    }
+    const markerRenderer = createMarkerLayer(markerLayer);
+    const cancelEntrances = markerRenderer.cancelEntrances;
     const camera = createCamera({
         read: getViewport,
         write: setView,
@@ -858,7 +807,6 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
         const width = canvas.getBoundingClientRect().width;
         if (!width)
             return;
-        labelLayer.replaceChildren();
         const unit = view[2] / width, zoom = 800 / view[2];
         for (const road of svg.querySelectorAll('[data-key-road-level="secondary"]'))
             road.style.display = zoom >= 1.8 ? '' : 'none';
@@ -884,6 +832,7 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
             scale.textContent = meters >= 1000 ? `${meters / 1000} km` : `${meters} m`;
         }
         if (!labels) {
+            labelRenderer.clear();
             root.dataset.visibleLabels = '0';
             return;
         }
@@ -919,13 +868,14 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
                 name: item.feature.properties.canonicalName,
                 kind: 'neighborhood',
             })));
-        const measured = candidates.map((item) => {
+        const labelCandidates = candidates.map((item) => {
             const fontSize = item.kind === 'road'
                 ? Math.max(minLabelSize, Math.min(11, maxLabelSize))
                 : Math.max(minLabelSize, Math.min(maxLabelSize, 12));
-            const node = svgElement('text', {
-                'font-size': fontSize * unit,
-                'font-weight': labelStyle.fontWeight ??
+            return {
+                ...item,
+                fontSize,
+                fontWeight: labelStyle.fontWeight ??
                     (item.kind.startsWith('selected') || item.kind === 'district' ? 700 : 550),
                 fill: colors.label ??
                     (item.kind === 'park'
@@ -933,22 +883,7 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
                         : item.kind === 'road'
                             ? '#77736b'
                             : '#163d61'),
-                stroke: labelStyle.haloColor ?? '#ffffff',
-                'stroke-width': 3 * unit,
-                'stroke-linejoin': 'round',
-                'paint-order': 'stroke',
-                'data-label-kind': item.kind,
-            });
-            node.textContent = item.name;
-            labelLayer.append(node);
-            return {
-                ...item,
-                node,
-                x: (item.point[0] - view[0]) / unit,
-                y: (item.point[1] - view[1]) / unit,
-                textWidth: node.getComputedTextLength() / unit,
-                fontSize,
-                textHeight: fontSize * 1.25,
+                halo: labelStyle.haloColor ?? '#ffffff',
                 offset: item.kind === 'selected-marker'
                     ? (marker?.marker.radius ?? markerRadius) + 9
                     : item.kind === 'bart'
@@ -980,19 +915,11 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
                 box.bottom - canvasBox.top + 3,
             ];
         });
-        const placed = layoutLabels(measured, width, width, [
+        root.dataset.visibleLabels = String(labelRenderer.draw(labelCandidates, view, width, [
             ...stationBounds,
             ...markerBounds,
             ...furnitureBounds,
-        ]);
-        for (const item of measured)
-            item.node.remove();
-        for (const item of placed) {
-            item.node.setAttribute('x', String(view[0] + item.left * unit));
-            item.node.setAttribute('y', String(view[1] + (item.top + item.fontSize) * unit));
-            labelLayer.append(item.node);
-        }
-        root.dataset.visibleLabels = String(placed.length);
+        ]));
     }
     function releaseDownloads() {
         for (const url of downloads)
@@ -1376,65 +1303,22 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
             .id;
         invalidateClusters();
         const previousIds = new Set(markerItems.map((item) => item.marker.id));
-        for (const animation of entranceAnimations)
-            animation.cancel();
-        entranceAnimations.clear();
+        markerRenderer.clear();
         const previous = selectedMarker;
-        markerLayer.replaceChildren();
         markerSelect.replaceChildren(element('option', 'No marker selected'));
         markerSelect.options[0].value = '';
         markerItems = next.map(({ marker, point }, index) => {
-            const node = svgElement('g', {
-                transform: `translate(${point[0]},${point[1]})`,
-                'data-marker-id': marker.id,
-                role: 'button',
-                tabindex: 0,
-                'aria-label': marker.label ?? marker.id,
-                'aria-pressed': 'false',
-            });
-            const hit = svgElement('circle', { fill: 'transparent', 'pointer-events': 'all' });
-            const dot = svgElement('circle', {
-                fill: marker.color ?? markerColor,
-                stroke: '#fff9e9',
-                'stroke-width': 2,
-                'vector-effect': 'non-scaling-stroke',
-                'pointer-events': 'none',
-            });
-            const title = svgElement('title');
-            title.textContent = marker.label ?? marker.id;
-            const ring = svgElement('circle', {
-                fill: 'none',
-                stroke: features.selectedMarkerRing
-                    ? (features.selectedMarkerRing.color ?? selectedMarkerColor)
-                    : selectedMarkerColor,
-                'stroke-width': features.selectedMarkerRing ? features.selectedMarkerRing.width : 2,
-                'vector-effect': 'non-scaling-stroke',
-                'pointer-events': 'none',
-                display: 'none',
+            const item = markerRenderer.add(marker, point, index, {
+                features,
+                markerColor,
+                selectedMarkerColor,
+                reducedMotion: reducedMotion.matches,
+                enter: !previousIds.has(marker.id),
             });
-            node.style.setProperty('--sf-marker-index', String(index));
-            node.append(title, hit, ring, dot);
-            if (features.markerEntrance &&
-                !previousIds.has(marker.id) &&
-                !reducedMotion.matches &&
-                typeof dot.animate === 'function') {
-                const animation = dot.animate([
-                    { opacity: 0, transform: 'translateY(-12px)' },
-                    { opacity: 1, transform: 'translateY(0)' },
-                ], {
-                    duration: features.markerEntrance.duration,
-                    delay: Math.min(index * features.markerEntrance.stagger, 1000),
-                    easing: 'cubic-bezier(.2,.8,.2,1)',
-                    fill: 'backwards',
-                });
-                entranceAnimations.add(animation);
-                animation.onfinish = () => entranceAnimations.delete(animation);
-            }
-            markerLayer.append(node);
             const option = element('option', marker.label ?? marker.id);
             option.value = marker.id;
             markerSelect.append(option);
-            return { marker, point, node, dot, hit, ring };
+            return item;
         });
         markerLabel.hidden = !markerItems.length || controls.markerPicker === false;
         if (markerLabel.firstChild)
@@ -1707,6 +1591,7 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
         destroy() {
             destroyed = true;
             camera.destroy();
+            districtTransition.cancel();
             cancelEntrances();
             controller.abort();
             overlayEvents.abort();
@@ -1714,16 +1599,21 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
             canvas.style.touchAction = 'pan-y pinch-zoom';
             observer?.disconnect();
             cancelAnimationFrame(frame);
+            labelRenderer.clear();
             releaseDownloads();
         },
     });
     try {
         observer = new ResizeObserver(onResize);
         observer.observe(canvas);
-        document.fonts?.addEventListener('loadingdone', scheduleLabels, { signal: controller.signal });
+        document.fonts?.addEventListener('loadingdone', () => {
+            labelRenderer.invalidateMetrics();
+            scheduleLabels();
+        }, { signal: controller.signal });
         reducedMotion.addEventListener('change', () => {
             if (reducedMotion.matches) {
                 stopAnimation();
+                districtTransition.cancel();
                 cancelEntrances();
             }
         }, { signal: controller.signal });