@kahwee/sf-map-svg 3.0.0 → 3.1.0

package/dist/src/full-data.js

@@ -1,4 +1,5 @@
-import { districtMaps, neighborhoodCollections } from '../data/index.js';
+import { districtMaps } from '../data/districts.js';
+import { neighborhoodCollections } from '../data/lookup.js';
 import { deepFreeze } from './immutable.js';
 import { staticMapData } from './static-data.js';
 /** Complete, explicit geographic preset. Import this only when all datasets are needed. */

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/static-data.js

@@ -1,4 +1,6 @@
-import { bartStations, keyRoads, landmarks } from '../data/index.js';
+import { landmarks } from '../data/landmarks.js';
+import { keyRoads } from '../data/roads.js';
+import { bartStations } from '../data/stations.js';
 import data from './data.js';
 import { deepFreeze } from './immutable.js';
 /** Complete data for static rendering, without interactive lookup collections. */

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

@@ -17,9 +17,9 @@ Choose by task. All snippets use the public package API; browser examples need a
 ```ts
 import { writeFile } from 'node:fs/promises';
 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 = renderMap(fullMapData.map, {
+const svg = renderMap(staticMapData, {
   year: 2022,
   landmarks: true,
   bartStations: true,
@@ -28,25 +28,25 @@ const svg = renderMap(fullMapData.map, {
 await writeFile('districts.svg', svg);
 ```
 
-The full preset imports all packaged geography. For smaller bundles, pass selected data to the root or `/static` renderer. See the [static recipe](../README.md#static-svg).
+The static preset includes the packaged map layers without interactive lookup collections. For smaller bundles, pass selected data to the root or `/static` renderer. See the [static recipe](../README.md#static-svg).
 
 For an election choropleth, use `renderMap(data, { year, districtStyle })` or
 `createMap({ map: data, districts: districtMaps, neighborhoods: {} }, options)`.
 The controller exposes `setDistrictYear`, `setDistrictStyle`, `selectDistrict`, and typed
 district events; `getLayerPaths(data, { year })` returns fitted paths without SVG markup.
-See the [complete election recipe](../README.md#election-district-api) and the Storybook
-“Election choropleth” example.
+See the [Storybook election choropleth](../stories/ElectionMap.stories.ts) for a working example.
 
 ## 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 [guide recipe](../README.md#render-a-static-map).
+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).
 
 ## Selected geography
 
@@ -71,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();
 ```
 
-For server rendering, import `renderMap` from the root and pass `guideMapData.map` or another explicit `StaticMapData`. Import `/data/full` only if the complete packaged geography is required. All rendering stays offline and has zero runtime dependencies. The guide's detailed geography loads only when `loadGuideDetailedData()` is called.
+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

@@ -4,14 +4,14 @@ Version 3 removes the deprecated compatibility entry points and their bundled-da
 
 | Version 2 import or call | Version 3 replacement |
 | --- | --- |
-| `/legacy` `renderSFMap(options)` | `renderMap(fullMapData.map, options).svg` |
-| `/legacy` `createSFMap(options)` | `renderMap(fullMapData.map, options)` |
+| `/legacy` `renderSFMap(options)` | `renderMap(staticMapData, options).svg` |
+| `/legacy` `createSFMap(options)` | `renderMap(staticMapData, options)` |
 | `/custom-map` `createSFMapWithData(options, data)` | `renderMap(data, options)` |
 | `/explorer` `createNeighborhoodExplorer(options)` | `createMap(fullMapData, options)`; mount `.element` |
 | `/interactive` `createInteractiveSFMap(options)` | `createMap(fullMapData, { mode: 'basemap', ...options })`; mount `.element` |
 | `/interactive-data` `createInteractiveSFMapWithData(data, options)` | `createMap(data, options)`; mount `.element` |
 
-`fullMapData` comes from `@kahwee/sf-map-svg/data/full`. It is an explicit import of all packaged geography. For smaller bundles, use `staticMapData` from `/data/static` for SVGs, construct data from individual `/data/*` modules, or use `guideMapData` from `/guide/data`. There is no implicit geographic data in the root import.
+`staticMapData` comes from `@kahwee/sf-map-svg/data/static` and includes the complete static map. `fullMapData` comes from `/data/full` and adds the interactive lookup collections. For smaller bundles, construct data from individual `/data/*` modules or use `guideMapData` from `/guide/data`. There is no implicit geographic data in the root import.
 
 ```ts
 import { createMap, renderMap } from '@kahwee/sf-map-svg';
@@ -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.0",
+  "version": "3.1.0",
   "description": "Offline SVG maps of San Francisco with district boundaries, parks, landmarks, and BART stations.",
   "type": "module",
   "main": "./dist/src/api.js",
@@ -171,7 +171,8 @@
     "demo": "pnpm build && node examples/build.mjs",
     "format": "biome check --write .",
     "format:check": "biome format .",
-    "check": "pnpm peers check && pnpm lint && pnpm data:check && pnpm typecheck && pnpm typecheck:stories && pnpm test && pnpm test:bundle",
+    "check": "pnpm peers check && pnpm lint && pnpm check:docs && pnpm data:check && pnpm typecheck && pnpm typecheck:stories && pnpm test && pnpm test:bundle",
+    "check:docs": "node scripts/check-docs.mjs",
     "storybook": "pnpm build && storybook dev -p 6006 --host 127.0.0.1 --no-open",
     "build-storybook": "pnpm build && storybook build",
     "data:catalog": "node scripts/build-data-catalog.mjs",