@kahwee/sf-map-svg 5.1.2 → 5.1.4

package/CHANGELOG.md

@@ -4,6 +4,14 @@ User-visible changes are recorded here. Unreleased entries describe changes on `
 
 ## Unreleased
 
+## 5.1.4 — 2026-11-05
+
+- Group internal browser controllers, renderers and shells under `src/interactive`, and SVG generation under `src/rendering`. Rename the general map engine, controls and marker renderer to match their responsibilities; clarify selection-detail, neighborhood-results and layer-composition operations. Keep public package entry points unchanged.
+
+## 5.1.3 — 2026-11-05
+
+- Give configuration snapshots and revisions a dedicated internal owner. Split presentation preparation from a guarded, single-use commit, rejecting stale or disposed updates before mutating presentation. Preserve public configuration and reset behavior.
+
 ## 5.1.2 — 2026-11-05
 
 - Separate marker selection, activation and focus recovery into an internal controller; separate label candidate caching, screen-space collision layout and metrics invalidation into a label coordinator. Preserve the public API and shared animation frame scheduling.

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

@@ -1,5 +1,5 @@
 import type { normalizeFeatures } from './features.js';
-import type { MarkerItem, MarkerVisual } from './marker-layer.js';
+import type { MarkerItem, MarkerVisual } from './interactive/marker-renderer.js';
 import type { createMarkerNavigation } from './marker-navigation.js';
 import type { MapViewport } from './types.js';
 interface ClusterState {

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

@@ -1,4 +1,4 @@
-import type { DistrictRowData } from './map-core.js';
+import type { DistrictRowData } from './rendering/svg-map-renderer.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, }: {

package/dist/src/district-layer.js

@@ -1,4 +1,4 @@
-import { districtColors } from './map-core.js';
+import { districtColors } from './rendering/svg-map-renderer.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) {

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

@@ -1,4 +1,4 @@
-import type { DistrictRowData } from './map-core.js';
+import type { DistrictRowData } from './rendering/svg-map-renderer.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/explorer-data.d.ts

@@ -1,5 +1,5 @@
 import type { DistrictProperties, FeatureCollection, NeighborhoodProperties, NeighborhoodSource } from '../data/types.js';
-import type { SFMapData } from './map-core.js';
+import type { SFMapData } from './rendering/svg-map-renderer.js';
 import type { DistrictYear } from './types.js';
 /** Geographic inputs for the data-injected interactive map entry point. */
 export interface InteractiveSFMapData {

package/dist/src/guide-map.js

@@ -1,7 +1,7 @@
 import { expandMapOptions, prepareConfiguration } from './configuration.js';
-import { createNeighborhoodExplorerCore } from './explorer-core.js';
-import { createMapShell } from './explorer-shell.js';
 import { guideMapData } from './guide-data.js';
+import { createMapEngine } from './interactive/map-engine.js';
+import { createMapShell } from './interactive/map-shell.js';
 import { createMap } from './map.js';
 import { guideOptions } from './presets.js';
 import { validateExplorerOptions } from './validation.js';
@@ -62,7 +62,7 @@ function mountFrame(frame, map) {
 /** Element-based compatibility API. Prefer createGuideController for new integrations. */
 export function createGuideMap(options = {}) {
     validateExplorerOptions(options);
-    return createNeighborhoodExplorerCore({
+    return createMapEngine({
         mode: 'neighborhoods',
         ...options,
         layers: {

package/dist/src/interactive/configuration-controller.d.ts

@@ -0,0 +1,21 @@
+import { prepareConfiguration } from '../configuration.js';
+import type { MapConfiguration } from '../controller-types.js';
+import type { NeighborhoodExplorerElement } from '../types.js';
+/** A prepared engine update may commit once, only while all revisions remain current. */
+export interface PreparedPresentation {
+    commit(onCommit: () => void, isCurrent: () => boolean): boolean;
+}
+export interface ConfigurationTarget extends Pick<NeighborhoodExplorerElement, 'setFeatures' | 'setLayers' | 'setControls'> {
+    preparePresentation(patch: MapConfiguration): PreparedPresentation | undefined;
+}
+/** Own the public configuration snapshot and invalidate stale updates before DOM mutation. */
+export declare function createConfigurationController(initial: ReturnType<typeof prepareConfiguration>, element: ConfigurationTarget, isDestroyed: () => boolean): {
+    configure: (patch: MapConfiguration) => boolean;
+    readonly current: {
+        features: import("../types.js").MapFeatures;
+        layers: import("../types.js").InteractiveLayers;
+        controls: import("../controller-types.js").MapControls;
+        appearance: import("../controller-types.js").MapAppearance;
+    };
+    invalidate(): void;
+};

package/dist/src/interactive/configuration-controller.js

@@ -0,0 +1,43 @@
+import { prepareConfiguration } from '../configuration.js';
+import { controlKeys, layerKeys } from '../features.js';
+/** Own the public configuration snapshot and invalidate stale updates before DOM mutation. */
+export function createConfigurationController(initial, element, isDestroyed) {
+    let config = initial;
+    let configurationRevision = 0;
+    function configure(patch) {
+        const revision = ++configurationRevision;
+        const next = prepareConfiguration(config, patch);
+        const hasFeatures = 'features' in patch, hasLayers = 'layers' in patch, hasControls = 'controls' in patch;
+        const layers = Object.fromEntries(layerKeys.map((key) => [key, next.layers[key]]));
+        const controls = Object.fromEntries(controlKeys.map((key) => [key, next.controls[key]]));
+        const features = patch.features === undefined
+            ? next.features
+            : Object.fromEntries(Object.keys(patch.features).map((key) => [
+                key,
+                next.features[key],
+            ]));
+        const presentation = element.preparePresentation({
+            ...patch,
+            ...('appearance' in patch ? { appearance: next.appearance } : {}),
+        });
+        const committed = presentation?.commit(() => {
+            config = next;
+            if (hasFeatures)
+                element.setFeatures(features);
+            if (hasLayers)
+                element.setLayers(layers);
+            if (hasControls)
+                element.setControls(controls);
+        }, () => !isDestroyed() && revision === configurationRevision);
+        return committed === true && !isDestroyed() && revision === configurationRevision;
+    }
+    return {
+        configure,
+        get current() {
+            return config;
+        },
+        invalidate() {
+            configurationRevision++;
+        },
+    };
+}

package/dist/src/{district-controller.d.ts → interactive/district-controller.d.ts}

@@ -1,9 +1,9 @@
-import type { Geometry, Position } from '../data/types.js';
-import { prepareDistrictStyles } from './district-style.js';
-import type { InteractiveSFMapData } from './explorer-data.js';
-import type { normalizeFeatures } from './features.js';
-import type { LabelItem } from './label-candidates.js';
-import type { CameraOptions, DistrictSelection, DistrictYear, NeighborhoodExplorerOptions } from './types.js';
+import type { Geometry, Position } from '../../data/types.js';
+import { prepareDistrictStyles } from '../district-style.js';
+import type { InteractiveSFMapData } from '../explorer-data.js';
+import type { normalizeFeatures } from '../features.js';
+import type { LabelItem } from '../label-candidates.js';
+import type { CameraOptions, DistrictSelection, DistrictYear, NeighborhoodExplorerOptions } from '../types.js';
 type Host = {
     root: HTMLElement;
     svg: SVGSVGElement;
@@ -23,12 +23,12 @@ type Host = {
     fitGeometry(geometry: Geometry, padding: undefined, options: CameraOptions): void;
     project(point: Position): [number, number];
     setLabels(items: LabelItem[]): void;
-    updateComposition(): void;
+    syncLayerComposition(): void;
     scheduleLabels(): void;
 };
 /** Owns district selection, styles, revisions and cancellable motion. */
 export declare function createDistrictController(host: Host, initialDistrictStyle: NeighborhoodExplorerOptions['districtStyle']): {
-    districtRow: (id: number) => import("./map-core.js").DistrictRowData | undefined;
+    districtRow: (id: number) => import("../rendering/svg-map-renderer.js").DistrictRowData | undefined;
     districtSelection: (id: number | null) => DistrictSelection | {
         id: null;
         year: DistrictYear;
@@ -40,7 +40,7 @@ export declare function createDistrictController(host: Host, initialDistrictStyl
         fit?: boolean;
     } & CameraOptions) => boolean;
     activateDistrict: (id: number) => boolean;
-    setDistrictStyle: (style: ((district: import('./map-core.js').DistrictRowData) => import("./types.js").DistrictStyle) | undefined) => void;
+    setDistrictStyle: (style: ((district: import("../rendering/svg-map-renderer.js").DistrictRowData) => import("../types.js").DistrictStyle) | undefined) => void;
     setDistrictYear: (next: DistrictYear, options?: CameraOptions, preparedStyles?: ReturnType<typeof prepareDistrictStyles>) => void;
     transition: {
         cancel(): void;
@@ -56,9 +56,9 @@ export declare function createDistrictController(host: Host, initialDistrictStyl
     };
     readonly revision: number;
     invalidate(): void;
-    readonly style: ((district: import('./map-core.js').DistrictRowData) => import("./types.js").DistrictStyle) | undefined;
-    readonly styles: ReadonlyMap<number, import("./types.js").DistrictStyle>;
-    commitStyles(style: ((district: import('./map-core.js').DistrictRowData) => import("./types.js").DistrictStyle) | undefined, styles: ReadonlyMap<number, import("./types.js").DistrictStyle>): void;
+    readonly style: ((district: import("../rendering/svg-map-renderer.js").DistrictRowData) => import("../types.js").DistrictStyle) | undefined;
+    readonly styles: ReadonlyMap<number, import("../types.js").DistrictStyle>;
+    commitStyles(style: ((district: import("../rendering/svg-map-renderer.js").DistrictRowData) => import("../types.js").DistrictStyle) | undefined, styles: ReadonlyMap<number, import("../types.js").DistrictStyle>): void;
     hovered: number | null;
 };
 export {};

package/dist/src/{district-controller.js → interactive/district-controller.js}

@@ -1,13 +1,13 @@
-import { validateCameraOptions } from './camera.js';
-import { renderDistrictAppearance } from './district-layer.js';
-import { createDistrictMorph } from './district-morph.js';
-import { prepareDistrictStyles } from './district-style.js';
-import { createDistrictTransition } from './district-transition.js';
-import { svgElement } from './dom.js';
-import { getLayerPathsWithData } from './map-core.js';
+import { validateCameraOptions } from '../camera.js';
+import { renderDistrictAppearance } from '../district-layer.js';
+import { createDistrictMorph } from '../district-morph.js';
+import { prepareDistrictStyles } from '../district-style.js';
+import { createDistrictTransition } from '../district-transition.js';
+import { svgElement } from '../dom.js';
+import { getLayerPathsWithData } from '../rendering/svg-map-renderer.js';
 /** Owns district selection, styles, revisions and cancellable motion. */
 export function createDistrictController(host, initialDistrictStyle) {
-    const { root, svg, status, data, districtLayers, reducedMotion, enabled, fitGeometry, updateComposition, scheduleLabels, } = host;
+    const { root, svg, status, data, districtLayers, reducedMotion, enabled, fitGeometry, syncLayerComposition, scheduleLabels, } = host;
     const districtMorph = createDistrictMorph();
     let selectedDistrict = null;
     let hoveredDistrict = null;
@@ -160,7 +160,7 @@ export function createDistrictController(host, initialDistrictStyle) {
         if (selectedDistrict === null)
             delete root.dataset.selectedDistrict;
         updateDistrictAppearance();
-        updateComposition();
+        syncLayerComposition();
         if (morph && lineLayer && previousOutlines)
             districtMorph.start(lineLayer, previousOutlines, {
                 duration: morph.duration,

package/dist/src/{explorer-sidebar.d.ts → interactive/explorer-sidebar.d.ts}

@@ -1,7 +1,7 @@
-import type { NeighborhoodFeature, NeighborhoodSource } from '../data/types.js';
-import type { InteractiveSFMapData } from './explorer-data.js';
-import type { createExplorerShell } from './explorer-shell.js';
-import type { DistrictYear, ExplorerMode } from './types.js';
+import type { NeighborhoodFeature, NeighborhoodSource } from '../../data/types.js';
+import type { InteractiveSFMapData } from '../explorer-data.js';
+import type { DistrictYear, ExplorerMode } from '../types.js';
+import type { createExplorerShell } from './map-shell.js';
 interface SidebarState {
     mode: ExplorerMode;
     year: DistrictYear;
@@ -13,8 +13,8 @@ export declare function createExplorerSidebar({ detail, results, search, count,
     id: string;
     canonicalName: string;
 }[]): {
-    updateDetail: ({ mode, year, source, selected }: SidebarState) => void;
-    updateResults: ({ source, selected }: SidebarState) => void;
+    updateSelectionDetail: ({ mode, year, source, selected }: SidebarState) => void;
+    updateNeighborhoodResults: ({ source, selected }: SidebarState) => void;
     destroy: () => void;
 };
 export {};

package/dist/src/{explorer-sidebar.js → interactive/explorer-sidebar.js}

@@ -1,4 +1,4 @@
-import { element } from './dom.js';
+import { element } from '../dom.js';
 /** Render sidebar snapshots and own every download URL until replacement or disposal. */
 export function createExplorerSidebar({ detail, results, search, count, }, data, chrome, emptyResults, searchNeighborhoods) {
     const downloads = new Set();
@@ -15,7 +15,7 @@ export function createExplorerSidebar({ detail, results, search, count, }, data,
         link.download = filename;
         return link;
     }
-    function updateDetail({ mode, year, source, selected }) {
+    function updateSelectionDetail({ mode, year, source, selected }) {
         releaseDownloads();
         if (chrome === 'map')
             return;
@@ -53,7 +53,7 @@ export function createExplorerSidebar({ detail, results, search, count, }, data,
         provenance.append(element('summary', 'About these boundaries'), element('p', collection.definition.description));
         detail.append(provenance);
     }
-    function updateResults({ source, selected }) {
+    function updateNeighborhoodResults({ source, selected }) {
         if (chrome === 'map')
             return;
         const activeElement = document.activeElement;
@@ -75,5 +75,5 @@ export function createExplorerSidebar({ detail, results, search, count, }, data,
         if (!matches.length)
             results.append(element('p', emptyResults ?? 'No matches. Try another name or definition source.', 'sf-explorer-note'));
     }
-    return { updateDetail, updateResults, destroy: releaseDownloads };
+    return { updateSelectionDetail, updateNeighborhoodResults, destroy: releaseDownloads };
 }

package/dist/src/{label-coordinator.d.ts → interactive/label-coordinator.d.ts}

@@ -1,11 +1,11 @@
-import type { View } from './explorer-layout.js';
-import type { normalizeFeatures } from './features.js';
-import { type LabelItem } from './label-candidates.js';
-import type { createMarkerCatalog } from './marker-catalog.js';
+import type { View } from '../explorer-layout.js';
+import type { normalizeFeatures } from '../features.js';
+import { type LabelItem } from '../label-candidates.js';
+import type { createMarkerCatalog } from '../marker-catalog.js';
+import type { createNeighborhoodLayer } from '../neighborhood-layer.js';
+import type { ExplorerMode, InteractiveLayers, NeighborhoodExplorerOptions } from '../types.js';
 import type { createMarkerController } from './marker-controller.js';
-import type { MarkerItem, MarkerVisual } from './marker-layer.js';
-import type { createNeighborhoodLayer } from './neighborhood-layer.js';
-import type { ExplorerMode, InteractiveLayers, NeighborhoodExplorerOptions } from './types.js';
+import type { MarkerItem, MarkerVisual } from './marker-renderer.js';
 interface LabelHost {
     root: HTMLElement;
     canvas: HTMLElement;

package/dist/src/{label-coordinator.js → interactive/label-coordinator.js}

@@ -1,5 +1,5 @@
-import { setAttributeIfChanged } from './dom.js';
-import { labelCandidates, styleLabels, } from './label-candidates.js';
+import { setAttributeIfChanged } from '../dom.js';
+import { labelCandidates, styleLabels, } from '../label-candidates.js';
 import { createLabelRenderer } from './label-renderer.js';
 /** Own candidate caching, screen-space collision layout and label metrics invalidation. */
 export function createLabelCoordinator(host) {

package/dist/src/{label-renderer.d.ts → interactive/label-renderer.d.ts}

@@ -1,5 +1,5 @@
-import type { Bounds } from '../data/types.js';
-import type { RenderLabel } from './label-candidates.js';
+import type { Bounds } from '../../data/types.js';
+import type { RenderLabel } from '../label-candidates.js';
 /** Reuse text nodes and screen-space metrics throughout a camera animation. */
 export declare function createLabelRenderer(layer: SVGGElement): {
     invalidateMetrics(): void;

package/dist/src/{label-renderer.js → interactive/label-renderer.js}

@@ -1,5 +1,5 @@
-import { setAttributeIfChanged } from './dom.js';
-import { layoutLabels } from './explorer-layout.js';
+import { setAttributeIfChanged } from '../dom.js';
+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();

package/dist/src/{explorer-controls.d.ts → interactive/map-controls.d.ts}

@@ -1,5 +1,5 @@
-import type { createExplorerShell } from './explorer-shell.js';
-import type { MapViewport, NeighborhoodExplorerElement, NeighborhoodExplorerOptions } from './types.js';
+import type { MapViewport, NeighborhoodExplorerElement, NeighborhoodExplorerOptions } from '../types.js';
+import type { createExplorerShell } from './map-shell.js';
 type Controls = NonNullable<NeighborhoodExplorerOptions['controls']>;
 type Shell = Pick<ReturnType<typeof createExplorerShell>, 'root' | 'toolbar' | 'canvas' | 'hint' | 'status' | 'modeSelect' | 'sourceSelect' | 'search' | 'results' | 'neighborhoodSelect' | 'markerSelect'>;
 type Commands = Pick<NeighborhoodExplorerElement, 'getViewport' | 'zoomBy' | 'resetView' | 'setLabels' | 'stopAnimation' | 'setMode' | 'setSource' | 'selectNeighborhood' | 'selectMarker'> & {
@@ -10,13 +10,13 @@ type Commands = Pick<NeighborhoodExplorerElement, 'getViewport' | 'zoomBy' | 're
     getLabels(): boolean;
     moveView(view: MapViewport): void;
     setView(view: MapViewport): void;
-    updateResults(): void;
+    updateNeighborhoodResults(): void;
     search(query: string): string | undefined;
 };
 /** Own toolbar and form events, touch navigation and control visibility.
  * Commands read current map state; all listeners share the map's disposal signal.
  */
-export declare function createExplorerControls({ root, toolbar, canvas, hint, status, modeSelect, sourceSelect, search, results, neighborhoodSelect, markerSelect, }: Shell, { svg, signal, strings, isDestroyed, getLabels, getViewport, moveView, zoomBy, resetView, setLabels, stopAnimation, setView, setMode, setSource, selectNeighborhood, selectMarker, updateResults, search: findNeighborhood, }: Commands): {
+export declare function createMapControls({ root, toolbar, canvas, hint, status, modeSelect, sourceSelect, search, results, neighborhoodSelect, markerSelect, }: Shell, { svg, signal, strings, isDestroyed, getLabels, getViewport, moveView, zoomBy, resetView, setLabels, stopAnimation, setView, setMode, setSource, selectNeighborhood, selectMarker, updateNeighborhoodResults, search: findNeighborhood, }: Commands): {
     setTouchNavigation: (enabled: boolean) => void;
     cancelNavigation: () => void;
     update(controls: Controls): void;

package/dist/src/{explorer-controls.js → interactive/map-controls.js}

@@ -1,9 +1,9 @@
-import { element } from './dom.js';
-import { attachNavigation } from './navigation.js';
+import { element } from '../dom.js';
+import { attachNavigation } from '../navigation.js';
 /** Own toolbar and form events, touch navigation and control visibility.
  * Commands read current map state; all listeners share the map's disposal signal.
  */
-export function createExplorerControls({ root, toolbar, canvas, hint, status, modeSelect, sourceSelect, search, results, neighborhoodSelect, markerSelect, }, { svg, signal, strings, isDestroyed, getLabels, getViewport, moveView, zoomBy, resetView, setLabels, stopAnimation, setView, setMode, setSource, selectNeighborhood, selectMarker, updateResults, search: findNeighborhood, }) {
+export function createMapControls({ root, toolbar, canvas, hint, status, modeSelect, sourceSelect, search, results, neighborhoodSelect, markerSelect, }, { svg, signal, strings, isDestroyed, getLabels, getViewport, moveView, zoomBy, resetView, setLabels, stopAnimation, setView, setMode, setSource, selectNeighborhood, selectMarker, updateNeighborhoodResults, search: findNeighborhood, }) {
     function listen(node, event, handler) {
         node.addEventListener(event, (incoming) => handler(incoming), { signal });
     }
@@ -63,7 +63,7 @@ export function createExplorerControls({ root, toolbar, canvas, hint, status, mo
         if (next === 'neighborhoods' || next === 'districts' || next === 'basemap')
             setMode(next);
     });
-    listen(search, 'input', updateResults);
+    listen(search, 'input', updateNeighborhoodResults);
     listen(search, 'keydown', (event) => {
         if (event.key === 'Enter') {
             const match = findNeighborhood(search.value);

package/dist/src/{explorer-core.d.ts → interactive/map-engine.d.ts}

@@ -1,13 +1,14 @@
-import type { NeighborhoodSource } from '../data/types.js';
-import type { MapConfiguration } from './controller-types.js';
-import type { InteractiveSFMapData } from './explorer-data.js';
-import type { createMapShell } from './explorer-shell.js';
+import type { NeighborhoodSource } from '../../data/types.js';
+import type { MapConfiguration } from '../controller-types.js';
+import type { InteractiveSFMapData } from '../explorer-data.js';
+import type { DistrictYear, ExplorerMode, NeighborhoodExplorerElement, NeighborhoodExplorerOptions } from '../types.js';
+import type { PreparedPresentation } from './configuration-controller.js';
 import type { createExplorerSidebar } from './explorer-sidebar.js';
-import type { DistrictYear, ExplorerMode, NeighborhoodExplorerElement, NeighborhoodExplorerOptions } from './types.js';
-export type { ExplorerMode, NeighborhoodExplorerElement, NeighborhoodExplorerOptions, } from './types.js';
+import type { createMapShell } from './map-shell.js';
+export type { ExplorerMode, NeighborhoodExplorerElement, NeighborhoodExplorerOptions, } from '../types.js';
 /** Private bridge between the renderer and its public lifecycle controller. */
 type MapEngineElement = NeighborhoodExplorerElement & {
-    applyPresentation(patch: MapConfiguration, onCommit?: () => void, isCurrent?: () => boolean): boolean;
+    preparePresentation(patch: MapConfiguration): PreparedPresentation | undefined;
     getMapState(): {
         mode: ExplorerMode;
         source: NeighborhoodSource;
@@ -16,7 +17,7 @@ type MapEngineElement = NeighborhoodExplorerElement & {
     };
 };
 /** Create an offline, browser-only neighborhood explorer. Call destroy() before disposal. */
-export declare function createNeighborhoodExplorerCore(options: NeighborhoodExplorerOptions | undefined, data: InteractiveSFMapData, ui: {
+export declare function createMapEngine(options: NeighborhoodExplorerOptions | undefined, data: InteractiveSFMapData, ui: {
     createShell: typeof createMapShell;
     createSidebar?: typeof createExplorerSidebar;
 }): MapEngineElement;