@kahwee/sf-map-svg 3.0.1 → 4.0.0

package/CHANGELOG.md

@@ -4,6 +4,21 @@ User-visible changes are recorded here. Unreleased entries describe changes on `
 
 ## Unreleased
 
+## 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.
+- No map API, geographic data, rendering, or animation changes. Existing v3 integrations only need a supported Node runtime to upgrade.
+
+## 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.
@@ -226,7 +241,7 @@ consistent home, and makes animation and subscription ownership predictable.
 - Add overlay color options, TypeScript declarations, source records, and SVG checks.
 - Add Storybook 10.6 with eight interactive examples and API controls.
 - Add usage examples, contributor instructions, and AGENTS.md.
-- Update GitHub Actions and validate Storybook and package builds on Node 22 and 26.
+- Update GitHub Actions and validate Storybook and package builds across supported Node versions.
 - Configure weekly Dependabot updates for development dependencies and Actions.
 - Keep existing layer defaults unchanged, runtime dependencies at zero, and distribution private.
 

package/README.md

@@ -10,7 +10,9 @@ Offline, self-contained San Francisco SVG maps. The package has no runtime depen
 pnpm add @kahwee/sf-map-svg
 ```
 
-Node 22.12+ is required for server rendering. Browser maps need a DOM and a bundler that supports JSON imports.
+Node 24+ is required for server rendering. Browser maps need a DOM and a bundler that supports JSON imports.
+
+Upgrading from v3 to v4: update your Node runtime to 24 or newer. The map API, browser requirements, rendering, and animations are unchanged.
 
 ## Static SVG
 
@@ -52,12 +54,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/data/README.md

@@ -37,7 +37,7 @@ const mission = neighborhoods.features.find((f) => f.id === 'inner-mission');
 console.log(mission.properties.canonicalName, mission.geometry);
 ```
 
-Node 22.12+ supports this syntax. Bundlers may also support JSON imports without the import attribute. Files are included in the package archive; non-JavaScript consumers can parse the same JSON files directly. These are package entry points, not a hosted API. The public repository and GitHub Pages explorer also provide access to the source data. Consumers who need only one dataset can import its JSON subpath or a typed, frozen leaf module.
+Node 24+ supports this syntax. Bundlers may also support JSON imports without the import attribute. Files are included in the package archive; non-JavaScript consumers can parse the same JSON files directly. These are package entry points, not a hosted API. The public repository and GitHub Pages explorer also provide access to the source data. Consumers who need only one dataset can import its JSON subpath or a typed, frozen leaf module.
 
 ## Import only the data you need
 

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 });

package/dist/src/guide-map.d.ts

@@ -1,5 +1,10 @@
+import type { MapController, MapOptions } from './controller-types.js';
 import type { NeighborhoodExplorerElement as InteractiveSFMapElement, NeighborhoodExplorerOptions as InteractiveSFMapOptions } from './types.js';
-/** Guide map preset: SFAR neighborhoods, major parks, BART, and curated roads. */
+/** Preferred guide API: the same grouped options, events, camera and lifecycle as createMap. */
+export declare function createGuideController(options?: MapOptions): MapController;
+/** Enhance a static guide shell and return its owning controller. */
+export declare function mountGuideController(shell: HTMLElement, options?: MapOptions): MapController;
+/** Element-based compatibility API. Prefer createGuideController for new integrations. */
 export declare function createGuideMap(options?: InteractiveSFMapOptions): InteractiveSFMapElement;
 /** Enhance createGuideShell() in place with a fixed compact chrome layout.
  * Keep an accessible external place list when hiding the native pickers.

package/dist/src/guide-map.js

@@ -1,8 +1,64 @@
+import { expandMapOptions, prepareConfiguration } from './configuration.js';
 import { createNeighborhoodExplorerCore } from './explorer-core.js';
 import { guideMapData } from './guide-data.js';
+import { createMap } from './map.js';
 import { guideOptions } from './presets.js';
 import { validateExplorerOptions } from './validation.js';
-/** Guide map preset: SFAR neighborhoods, major parks, BART, and curated roads. */
+function controllerOptions(options) {
+    expandMapOptions(options);
+    const config = prepareConfiguration({ features: {}, layers: guideOptions.layers ?? {}, controls: {} }, {
+        features: options.features,
+        layers: options.layers === undefined ? {} : options.layers,
+        controls: options.controls,
+    });
+    return {
+        ...guideOptions,
+        ...options,
+        mode: options.mode === undefined ? guideOptions.mode : options.mode,
+        layers: config.layers,
+    };
+}
+/** Preferred guide API: the same grouped options, events, camera and lifecycle as createMap. */
+export function createGuideController(options = {}) {
+    return createMap(guideMapData, controllerOptions(options));
+}
+/** Enhance a static guide shell and return its owning controller. */
+export function mountGuideController(shell, options = {}) {
+    const prepared = controllerOptions(options);
+    const frame = shellFrame(shell, prepared.attribution);
+    const map = createMap(guideMapData, {
+        ...prepared,
+        attribution: 'compact',
+        controls: { ...shellControls, ...prepared.controls },
+    });
+    mountFrame(frame, map.element);
+    return map;
+}
+const shellControls = {
+    pan: false,
+    labels: false,
+    neighborhoodPicker: false,
+    markerPicker: false,
+    help: false,
+    status: false,
+    legend: true,
+};
+function shellFrame(shell, attribution) {
+    if (attribution === 'full')
+        throw new TypeError('The guide shell requires compact attribution; use createGuideController for full attribution.');
+    if (!shell.classList.contains('sf-guide-shell'))
+        throw new TypeError('Expected a createGuideShell container.');
+    const frame = shell.querySelector(':scope > .sf-guide-frame');
+    if (!frame || frame.classList.contains('sf-explorer'))
+        throw new Error('Shell is missing its static frame or already mounted.');
+    return frame;
+}
+function mountFrame(frame, map) {
+    map.classList.add('sf-guide-frame');
+    map.querySelector('.sf-explorer-map-column > details')?.classList.add('sf-guide-sources');
+    frame.replaceWith(map);
+}
+/** Element-based compatibility API. Prefer createGuideController for new integrations. */
 export function createGuideMap(options = {}) {
     validateExplorerOptions(options);
     return createNeighborhoodExplorerCore({
@@ -20,29 +76,15 @@ export function createGuideMap(options = {}) {
  */
 export function mountGuideMap(shell, options = {}) {
     validateExplorerOptions(options);
-    if (options.attribution === 'full')
-        throw new TypeError('The guide shell requires compact attribution; use createGuideMap for full attribution.');
-    if (!shell.classList.contains('sf-guide-shell'))
-        throw new TypeError('Expected a createGuideShell container.');
-    const frame = shell.querySelector(':scope > .sf-guide-frame');
-    if (!frame || frame.classList.contains('sf-explorer'))
-        throw new Error('Shell is missing its static frame or already mounted.');
+    const frame = shellFrame(shell, options.attribution);
     const map = createGuideMap({
         ...options,
         attribution: 'compact',
         controls: {
-            pan: false,
-            labels: false,
-            neighborhoodPicker: false,
-            markerPicker: false,
-            help: false,
-            status: false,
-            legend: true,
+            ...shellControls,
             ...options.controls,
         },
     });
-    map.classList.add('sf-guide-frame');
-    map.querySelector('.sf-explorer-map-column > details')?.classList.add('sf-guide-sources');
-    frame.replaceWith(map);
+    mountFrame(frame, map);
     return map;
 }

package/dist/src/guide.d.ts

@@ -1,5 +1,6 @@
+export type { MapController, MapOptions } from './controller-types.js';
 export type { InteractiveSFMapData } from './explorer-data.js';
 export { guideMapData } from './guide-data.js';
 export { loadGuideDetailedData } from './guide-detailed.js';
-export { createGuideMap, mountGuideMap } from './guide-map.js';
+export { createGuideController, createGuideMap, mountGuideController, mountGuideMap, } from './guide-map.js';
 export type { CameraOptions, MapFeatures, MapMarker, NeighborhoodExplorerElement as InteractiveSFMapElement, NeighborhoodExplorerOptions as InteractiveSFMapOptions, } from './types.js';

package/dist/src/guide.js

@@ -1,3 +1,3 @@
 export { guideMapData } from './guide-data.js';
 export { loadGuideDetailedData } from './guide-detailed.js';
-export { createGuideMap, mountGuideMap } from './guide-map.js';
+export { createGuideController, createGuideMap, mountGuideController, mountGuideMap, } from './guide-map.js';

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

@@ -0,0 +1,17 @@
+import type { Bounds } from '../data/types.js';
+export interface RenderLabel {
+    point: [number, number];
+    name: string;
+    kind: string;
+    fontSize: number;
+    fontWeight: number;
+    fill: string;
+    halo: string;
+    offset: number;
+}
+/** Reuse text nodes and screen-space metrics throughout a camera animation. */
+export declare function createLabelRenderer(layer: SVGGElement): {
+    invalidateMetrics(): void;
+    clear(): void;
+    draw(labels: RenderLabel[], view: readonly number[], width: number, obstacles: Bounds[]): number;
+};

package/dist/src/label-renderer.js

@@ -0,0 +1,81 @@
+import { layoutLabels } from './explorer-layout.js';
+/** Reuse text nodes and screen-space metrics throughout a camera animation. */
+export function createLabelRenderer(layer) {
+    const entries = new Map();
+    return {
+        invalidateMetrics() {
+            for (const entry of entries.values())
+                entry.width = undefined;
+        },
+        clear() {
+            entries.clear();
+            layer.replaceChildren();
+        },
+        draw(labels, view, width, obstacles) {
+            const unit = view[2] / width;
+            const keys = new Set();
+            const pending = labels.map((label) => {
+                const key = JSON.stringify([
+                    label.kind,
+                    label.name,
+                    label.point,
+                    label.fontSize,
+                    label.fontWeight,
+                ]);
+                keys.add(key);
+                let entry = entries.get(key);
+                if (!entry) {
+                    const node = document.createElementNS('http://www.w3.org/2000/svg', 'text');
+                    node.textContent = label.name;
+                    node.setAttribute('stroke-linejoin', 'round');
+                    node.setAttribute('paint-order', 'stroke');
+                    node.setAttribute('data-label-kind', label.kind);
+                    entry = { node };
+                    entries.set(key, entry);
+                }
+                const { node } = entry;
+                node.setAttribute('font-size', String(label.fontSize * unit));
+                node.setAttribute('font-weight', String(label.fontWeight));
+                node.setAttribute('fill', label.fill);
+                node.setAttribute('stroke', label.halo);
+                node.setAttribute('stroke-width', String(3 * unit));
+                // Batch writes before measuring new labels. Hidden candidates stay detached.
+                if (entry.width === undefined && !node.parentNode)
+                    layer.append(node);
+                return { label, entry };
+            });
+            for (const [key, entry] of entries) {
+                if (!keys.has(key)) {
+                    entry.node.remove();
+                    entries.delete(key);
+                }
+            }
+            const measured = pending.map(({ label, entry }) => {
+                entry.width ??= entry.node.getComputedTextLength() / unit;
+                return {
+                    ...label,
+                    node: entry.node,
+                    x: (label.point[0] - view[0]) / unit,
+                    y: (label.point[1] - view[1]) / unit,
+                    textWidth: entry.width,
+                    textHeight: label.fontSize * 1.25,
+                };
+            });
+            const placed = layoutLabels(measured, width, width, obstacles);
+            const visible = new Set(placed.map(({ node }) => node));
+            for (const { node } of measured)
+                if (!visible.has(node))
+                    node.remove();
+            let previous = null;
+            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));
+                const next = previous ? previous.nextSibling : layer.firstChild;
+                if (next !== item.node)
+                    layer.insertBefore(item.node, next);
+                previous = item.node;
+            }
+            return placed.length;
+        },
+    };
+}

package/dist/src/map-core.js

@@ -1,4 +1,5 @@
 import { validateMarkers, validateOverlays } from './validation.js';
+import { prepareDistrictStyles } from './district-style.js';
 import { geometryPath, positions, rawProject } from './geometry.js';
 import * as layers from './layers.js';
 import { escapeXml, stroke } from './svg.js';
@@ -48,12 +49,11 @@ export function getLayerPathsWithData(options, data, complete = true) {
         coast: path(data.coast),
         districts: (complete || options.districtFills !== false || options.districtLines !== false
             ? (data.districts?.[year] ?? [])
-            : []).map((district) => ({
-            id: district.id,
-            geometry: path(district.geometry),
-            extras: path(district.extras),
-            path: path(district.geometry) + path(district.extras),
-        })),
+            : []).map((district) => {
+            const geometry = path(district.geometry);
+            const extras = path(district.extras);
+            return { id: district.id, geometry, extras, path: geometry + extras };
+        }),
         neighborhoods: (complete ? (data.neighborhoods ?? []) : []).map((item) => ({
             name: item.name,
             path: path(item.geometry),
@@ -124,9 +124,10 @@ export function createSFMapWithData(options, data) {
     const roadData = data.keyRoads ?? [];
     const stationData = data.bartStations ?? [];
     const context = { project, path, colors, idPrefix, theme, labels };
+    const styles = prepareDistrictStyles(districtFills || districtLines ? districts : [], options.districtStyle);
     const districtPaths = districtFills || districtLines
         ? districts.map((d, index) => {
-            const style = validateDistrictStyle(options.districtStyle?.(d));
+            const style = styles.get(d.id) ?? {};
             return {
                 id: d.id,
                 path: geometry.districts[index]?.path ?? '',
@@ -171,19 +172,3 @@ export function createSFMapWithData(options, data) {
         viewBox: [0, 0, width, height],
     };
 }
-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}`);
-    for (const key of ['fill', 'stroke'])
-        if (style[key] !== undefined && typeof style[key] !== 'string')
-            throw new TypeError(`${key} must be a string.`);
-    if (style.opacity !== undefined &&
-        (!Number.isFinite(style.opacity) || style.opacity < 0 || style.opacity > 1))
-        throw new RangeError('District opacity must be between 0 and 1.');
-    return style;
-}

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

@@ -0,0 +1,22 @@
+import type { normalizeFeatures } from './features.js';
+import type { MapMarker } from './types.js';
+export interface MarkerItem {
+    marker: MapMarker;
+    point: [number, number];
+    node: SVGGElement;
+    dot: SVGCircleElement;
+    hit: SVGCircleElement;
+    ring: SVGCircleElement;
+}
+/** Own marker visuals and entrances; selection/events remain with the controller. */
+export declare function createMarkerLayer(layer: SVGGElement): {
+    cancelEntrances: () => void;
+    clear(): void;
+    add(marker: MapMarker, point: [number, number], index: number, { features, markerColor, selectedMarkerColor, reducedMotion, enter, }: {
+        features: ReturnType<typeof normalizeFeatures>;
+        markerColor: string;
+        selectedMarkerColor: string;
+        reducedMotion: boolean;
+        enter: boolean;
+    }): MarkerItem;
+};

package/dist/src/marker-layer.js

@@ -0,0 +1,64 @@
+import { svgElement } from './dom.js';
+/** Own marker visuals and entrances; selection/events remain with the controller. */
+export function createMarkerLayer(layer) {
+    const animations = new Set();
+    function cancelEntrances() {
+        for (const animation of animations)
+            animation.cancel();
+        animations.clear();
+    }
+    return {
+        cancelEntrances,
+        clear() {
+            cancelEntrances();
+            layer.replaceChildren();
+        },
+        add(marker, point, index, { features, markerColor, selectedMarkerColor, reducedMotion, enter, }) {
+            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',
+            });
+            node.style.setProperty('--sf-marker-index', String(index));
+            node.append(title, hit, ring, dot);
+            if (features.markerEntrance && enter && !reducedMotion && 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',
+                });
+                animations.add(animation);
+                animation.finished.then(() => animations.delete(animation), () => animations.delete(animation));
+            }
+            layer.append(node);
+            return { marker, point, node, dot, hit, ring };
+        },
+    };
+}

package/dist/src/types.d.ts

@@ -41,7 +41,7 @@ export interface SFMapOptions {
     districtLines?: boolean;
     neighborhoodLines?: boolean;
     districtFills?: boolean;
-    /** Style each supervisorial district without taking over SVG rendering. */
+    /** Evaluated once per district at construction/style/year updates; call setDistrictStyle again when external data changes. */
     districtStyle?: (district: import('./map-core.js').DistrictRowData) => DistrictStyle;
     districtLabels?: boolean;
     /** Hide all visible text labels while retaining geographic symbols and accessible titles. */

package/dist/src/validation.js

@@ -157,6 +157,11 @@ export function validateMarkers(markers) {
         if (typeof marker.id !== 'string' || !marker.id || ids.has(marker.id))
             throw new RangeError('Markers require unique nonempty IDs.');
         ids.add(marker.id);
+        if (!Number.isFinite(marker.lng) ||
+            Math.abs(marker.lng) > 180 ||
+            !Number.isFinite(marker.lat) ||
+            Math.abs(marker.lat) >= 90)
+            throw new RangeError('Marker coordinates require finite longitude from -180 to 180 and latitude strictly between -90 and 90.');
         if (marker.radius !== undefined && (!Number.isFinite(marker.radius) || marker.radius <= 0))
             throw new RangeError('Marker radius must be positive and finite.');
         if (marker.selected !== undefined && typeof marker.selected !== 'boolean')

package/docs/EXAMPLES.md

@@ -39,10 +39,11 @@ See the [Storybook election choropleth](../stories/ElectionMap.stories.ts) for a
 ## Lightweight interactive guide
 
 ```ts
-import { createGuideMap } from '@kahwee/sf-map-svg/guide';
+import { createGuideController } from '@kahwee/sf-map-svg/guide';
 
-const map = createGuideMap({ layers: { roadLabels: false } });
-document.querySelector('#map')?.append(map);
+const map = createGuideController({ layers: { roadLabels: false } });
+document.querySelector('#map')?.append(map.element);
+// On unmount: map.destroy();
 ```
 
 The guide includes selected coast, SFAR neighborhoods, parks, roads, and stations. Detailed geography loads only when explicitly requested; see the [consumer guide recipe](consumer-integration.md).
@@ -70,10 +71,10 @@ This imports one neighborhood definition source. To omit its geometry too, impor
 ## Route overlay
 
 ```ts
-import { createGuideMap } from '@kahwee/sf-map-svg/guide';
+import { createGuideController } from '@kahwee/sf-map-svg/guide';
 
-const map = createGuideMap();
-document.querySelector('#map')?.append(map);
+const map = createGuideController();
+document.querySelector('#map')?.append(map.element);
 map.setOverlays([{
   id: 'trip',
   label: 'Example route',

package/docs/api-audit.md

@@ -20,7 +20,11 @@ unbounded geographic data can never fail.
 | Marker entrance and reduced motion | Entrances are optional, independent of camera motion, and cancel on preference changes or disposal. Stable IDs avoid repeated entrances on filtering. |
 | Hiding touch control while gestures are enabled | Returns touch scrolling to the page. Other toolbar controls remain independent. |
 | Runtime patch omitted/false/undefined | Omitted retains; false disables; undefined resets to the default. Nested feature objects replace, rather than deep-merge. |
-| Compact shell and full attribution | Rejected before replacement. Use `createGuideMap` for full explorer chrome. Control overrides are honored and may deliberately alter layout. |
+| Compact shell and full attribution | Rejected before replacement. Use `createGuideController` for full attribution. Control overrides are honored and may deliberately alter layout. |
+| 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. |
+| 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. |
 
 ## Failure boundaries and regression evidence
@@ -40,9 +44,10 @@ unbounded geographic data can never fail.
 
 Regression sources: `test/api-contract.test.js`, `test/camera.test.js`,
 `test/viewport.test.js`, `stories/Robustness.stories.ts`,
-`stories/Enhancements.stories.ts`, and `scripts/smoke-package.mjs`.
+`stories/Enhancements.stories.ts`, `stories/Motion.stories.ts`,
+`stories/Controller.stories.ts`, and `scripts/smoke-package.mjs`.
 
-Callbacks run after their corresponding state is committed. Consumer callback
+Event listeners and activation callbacks run after their corresponding state is committed. District-style callbacks instead run during preparation, before commit. Consumer event callback
 exceptions are not transactional validation errors and do not roll back an already
 committed change. Direct mutation of the returned DOM can invalidate invariants;
 use the public methods and `overlayElement` extension point.

package/docs/consumer-integration.md

@@ -5,14 +5,19 @@ Use the version 3 root controller and explicit geographic data. The [migration g
 For a compact browser guide:
 
 ```ts
-import { createMap } from '@kahwee/sf-map-svg';
-import { guideMapData } from '@kahwee/sf-map-svg/guide/data';
-import { guideOptions } from '@kahwee/sf-map-svg/presets';
+import { createGuideController } from '@kahwee/sf-map-svg/guide';
 
-const map = createMap(guideMapData, { ...guideOptions });
+const map = createGuideController({
+  features: { motion: { duration: 400 }, markerEntrance: true },
+  appearance: { theme: 'transit' },
+});
 document.querySelector('#map')?.append(map.element);
 // Dispose when the containing view unmounts.
 map.destroy();
 ```
 
+The guide controller uses the same `configure()`, `camera`, `on()`, and `destroy()` contract as `createMap()`. Motion is opt-in and follows the user's reduced-motion preference. For explicit data composition, `createMap(guideMapData, guideOptions)` remains available using `/guide/data` and `/presets`.
+
+To progressively enhance server-rendered `createGuideShell()` markup, use `mountGuideController(shell, options)` from `/guide`. It returns the controller and requires compact attribution. Invalid configuration leaves the static frame intact. Destroy the controller when unmounting. Existing `createGuideMap()` and `mountGuideMap()` return their original augmented elements and accept flat options for compatibility.
+
 For server rendering, import `renderMap` from the root and pass `guideMapData.map`, `staticMapData` from `/data/static`, or another explicit `StaticMapData`. Import `/data/full` when interactive lookup collections are also required. All rendering stays offline and has zero runtime dependencies. The guide's detailed geography loads only when `loadGuideDetailedData()` is called.

package/docs/guide-bundle-report.md

@@ -1,12 +1,12 @@
 # Guide bundle size report
 
-Generated 2026-09-27 by `pnpm report:guide` with Vite production minification and gzip compression. Each emitted JS chunk is compressed independently. The report measures the explicit-data v3 root and the optional `@kahwee/sf-map-svg/guide` preset.
+Generated 2026-09-28 by `pnpm report:guide` with Vite production minification and gzip compression. Each emitted JS chunk is compressed independently. The report measures the explicit-data v3 root and the optional `@kahwee/sf-map-svg/guide` preset.
 
 | Entry | Initial JS, raw | Initial JS, gzip | Explicit detail JS, gzip |
 | --- | ---: | ---: | ---: |
-| v3 root (explicit data) | 84.5 KB | 24.6 KB | — |
-| v3 static renderer | 14.8 KB | 4.9 KB | — |
-| Guide preset | 469.8 KB | 112.0 KB | 473.7 KB |
+| v3 root (explicit data) | 87.4 KB | 25.5 KB | — |
+| v3 static renderer | 15.3 KB | 5.0 KB | — |
+| Guide preset | 477.1 KB | 114.1 KB | 473.7 KB |
 
 **500 KB target:** met.
 

package/docs/migration-v3.md

@@ -28,3 +28,9 @@ map.destroy();
 The controller owns subscriptions and cleanup. Replace old element calls with controller methods (`camera.get/set/pan/zoom/reset/fit/stop`, `selectNeighborhood`, `setSource`, `setMode`, `setLabels`, `setMarkers`, and `setOverlays`). Group feature flags under `features` and styling under `appearance`; `configure` updates runtime features, layers, and controls. For code that needs the guide shell, `/guide`, `/guide/data`, `/guide/static`, and `/guide/map` remain supported. `/transit` also remains supported.
 
 Review tree-shaking after migrating: `/data/full` intentionally includes every packaged layer, while the root and `/static` stay data free. Test server rendering, browser mounting, and map disposal in your application before upgrading production.
+
+## Updating from 3.0 to 3.1
+
+Existing guide factories remain compatible. New integrations can use `createGuideController(options)` and `mountGuideController(shell, options)` from `/guide` or `/guide/map`. Move flat styling options into `appearance`, animation options into `features`, append `.element`, and use `.camera` and `.on()` as with `createMap`.
+
+District styles are now prepared once per district on construction and style/year updates. Hover and selection reuse that snapshot. If a callback reads mutable external data, call `map.setDistrictStyle(callback)` after changing the data; do not rely on hovering to refresh colors. Callback errors leave the previous style intact, and callback-triggered updates or destruction take precedence over the pending update.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kahwee/sf-map-svg",
-  "version": "3.0.1",
+  "version": "4.0.0",
   "description": "Offline SVG maps of San Francisco with district boundaries, parks, landmarks, and BART stations.",
   "type": "module",
   "main": "./dist/src/api.js",
@@ -128,7 +128,7 @@
   },
   "license": "MIT",
   "engines": {
-    "node": ">=22.12.0"
+    "node": ">=24.0.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.14",