@kahwee/sf-map-svg 4.5.0 → 5.0.0

package/CHANGELOG.md

@@ -4,6 +4,17 @@ User-visible changes are recorded here. Unreleased entries describe changes on `
 
 ## Unreleased
 
+## 5.0.0 — 2026-10-19
+
+- Breaking: controller `setMode` and `setSource` preserve the camera; remove their `{ resetView }` argument. Call `camera.reset()` or `camera.fit()` explicitly.
+- Breaking: controller `configure` treats all omitted and undefined values as no-ops and merges nested feature records. Add `resetConfiguration(groups?)` to clear presentation overrides explicitly.
+- Breaking: controller `selectNeighborhood` selects exact IDs in the current source; resolve names through source-specific data lookup or use source/year-qualified `selectFeature`.
+- Include a [v5 migration guide](docs/migration-v5.md), migrated consumer examples, and regression checks. Retain Node 24+, offline rendering, zero runtime dependencies, geographic data, and default appearance.
+
+- Add offline `geometryBounds()` and `geometryContainsPoint()` helpers to `/geometry`, with readonly inputs, polygon holes and islands, nested collections, explicit boundary semantics, and coordinate validation. Export `Bounds`, `Geometry`, and `Position` from the same entry.
+- Breaking: markers now require `position: [longitude, latitude]`; remove the numeric `projectToScreen(lng, lat)` form in favor of one readonly GeoJSON position. Export shared `ScreenPoint` and `ProjectToScreen` types and cover camera changes, resizing, invalid coordinates, and controller disposal in browser regressions.
+- Document geographic queries, screen-coordinate integration, and API consistency follow-ups. Correct the developer guide: camera pan deltas are CSS pixels, not projected map units.
+
 ## 4.5.0 — 2026-10-14
 
 - Add the optional `/cards` entry with `bindMapCards()`: hover/focus previews a pin without changing selection or camera, native buttons select places, map selection reveals matching cards without stealing focus, and explicit cleanup restores owned DOM attributes.

package/README.md

@@ -6,6 +6,11 @@ Offline, self-contained San Francisco SVG maps. The package has no runtime depen
 
 [Map preview](https://github.com/kahwee/sf-map-svg/blob/main/docs/map-preview.png) · 2,000-marker screencasts: [desktop](https://github.com/kahwee/sf-map-svg/blob/main/docs/media/markers-2000-desktop.webm), [390 px phone](https://github.com/kahwee/sf-map-svg/blob/main/docs/media/markers-2000-phone.webm). [Screenshots and capture instructions](https://github.com/kahwee/sf-map-svg/blob/main/docs/media/README.md) show zoom, viewport culling, clustering, label updates, and selection from the complete catalog. These recordings illustrate behavior; frame timings are reported below.
 
+## Upgrading to v5
+
+Version 5.0.0 standardizes coordinate tuples and controller reset behavior.
+Read the [migration guide](docs/migration-v5.md) before upgrading from v4.
+
 ## Install
 
 ```sh
@@ -82,6 +87,33 @@ See [controller options, events, and lifecycle](docs/API.md#interactive-maps),
 [examples](docs/EXAMPLES.md), and [consumer integration](docs/consumer-integration.md).
 Call `destroy()` when removing an interactive map.
 
+## Geographic queries and screen coordinates
+
+New in v5. See the [v5 migration guide](docs/migration-v5.md) for breaking changes.
+
+Use the data-free `/geometry` entry to calculate geographic bounds or test which
+polygons contain a location, without constructing a map or requiring a browser:
+
+```ts
+import { geometryBounds, geometryContainsPoint } from '@kahwee/sf-map-svg/geometry';
+import { neighborhoods } from '@kahwee/sf-map-svg/data/realtor';
+
+const location = [-122.42, 37.76] as const;
+const matches = neighborhoods.features.filter(({ geometry }) =>
+  geometryContainsPoint(geometry, location),
+);
+const bounds = matches[0] ? geometryBounds(matches[0].geometry) : null;
+```
+
+Polygon holes are respected; shared boundaries can match multiple areas.
+Bounds are `[west, south, east, north]` in degrees, not camera coordinates.
+The [query contract](docs/API.md#geographic-queries) covers empty geometry,
+validation, and geographic limitations.
+
+For mounted browser maps, `map.projectToScreen(location)` returns canvas-relative
+CSS pixels and viewport visibility. All coordinate inputs now use GeoJSON tuples. See the [overlay recipe](docs/consumer-integration.md#position-html-overlays)
+and [coordinate units](docs/API.md#coordinates-and-units).
+
 ## Documentation for coding assistants
 
 [Developer guide](docs/developer-guide.md) · [llms.txt index](llms.txt) · [Complete text documentation](llms-full.txt). Generated from project docs and TypeScript declarations; run `pnpm docs:llms` after changing those inputs.

package/dist/data/README.md

@@ -110,6 +110,13 @@ const pathData = geometryPath(mission.geometry, map.project);
 // Use pathData as an SVG <path d="..."> over map.svg.
 ```
 
+The v5 `/geometry` helpers `geometryBounds(geometry)` and
+`geometryContainsPoint(geometry, position)` also work with these readonly dataset
+features. They import no geography themselves. Containment respects holes and
+includes shared boundaries, so keep all matches when querying a source. See the
+[area-lookup example](../docs/EXAMPLES.md#find-areas-containing-a-location) and
+[query contract](../docs/API.md#geographic-queries). These additions are available in v5.
+
 `geometryPath` handles Polygon, MultiPolygon, LineString, MultiLineString, and GeometryCollection; points use `map.project` and a marker element. Storybook's **Data / Neighborhood explorer** demonstrates the complete overlay and offers JSON downloads.
 
 ## District display metadata

package/dist/src/cards.js

@@ -44,7 +44,7 @@ export function bindMapCards(map, root, options) {
         const marker = card && root.contains(card) ? markers.get(card.dataset.mapMarker ?? '') : undefined;
         if (!marker)
             return;
-        const point = map.projectToScreen(marker.lng, marker.lat);
+        const point = map.projectToScreen(marker.position);
         if (!point.visible)
             return;
         ring.style.left = `${point.x}px`;

package/dist/src/configuration.d.ts

@@ -2,6 +2,8 @@ import type { MapConfiguration, MapConfigurationSnapshot, MapOptions } from './c
 import type { NeighborhoodExplorerOptions } from './types.js';
 export declare function expandMapOptions(options: MapOptions): NeighborhoodExplorerOptions;
 type PresentationSnapshot = Pick<MapConfigurationSnapshot, 'features' | 'layers' | 'controls' | 'appearance'>;
+/** Public v5 patches consistently ignore undefined at every record depth. */
+export declare function configurationPatch(patch: MapConfiguration, current?: Partial<MapConfiguration>): MapConfiguration;
 /** Prepare the entire configuration before any DOM mutation. */
 export declare function prepareConfiguration(current: PresentationSnapshot, patch: MapConfiguration): PresentationSnapshot;
 export {};

package/dist/src/configuration.js

@@ -44,6 +44,36 @@ export function expandMapOptions(options) {
     validateExplorerOptions(expanded);
     return expanded;
 }
+/** Public v5 patches consistently ignore undefined at every record depth. */
+export function configurationPatch(patch, current = {}) {
+    assertOptions(patch, 'configuration', [
+        'features',
+        'layers',
+        'controls',
+        'appearance',
+        'mode',
+        'source',
+        'year',
+        'labels',
+    ]);
+    const clean = (value, previous, depth) => {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return value;
+        const prior = previous && typeof previous === 'object' && !Array.isArray(previous)
+            ? previous
+            : {};
+        return {
+            ...(depth >= 2 ? prior : {}),
+            ...Object.fromEntries(Object.entries(value)
+                .filter(([, entry]) => entry !== undefined || depth > 0)
+                .map(([key, entry]) => [
+                key,
+                clean(entry === undefined ? prior[key] : entry, prior[key], depth + 1),
+            ])),
+        };
+    };
+    return clean(patch, current, 0);
+}
 /** Prepare the entire configuration before any DOM mutation. */
 export function prepareConfiguration(current, patch) {
     assertOptions(patch, 'configuration', [

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

@@ -1,6 +1,6 @@
 import type { Geometry, NeighborhoodSource } from '../data/types.js';
-import type { CameraOptions, DistrictSelection, DistrictStyle, DistrictYear, InteractiveLayers, MapFeatures, MapMarker, MapOverlay, MapPadding, MapViewport, NeighborhoodExplorerOptions, NeighborhoodSelection } from './types.js';
-/** Patch properties can explicitly remove overrides, including with exactOptionalPropertyTypes. */
+import type { CameraOptions, DistrictSelection, DistrictStyle, DistrictYear, InteractiveLayers, MapFeatures, MapMarker, MapOverlay, MapPadding, MapViewport, NeighborhoodExplorerOptions, NeighborhoodSelection, ProjectToScreen } from './types.js';
+/** Explicit undefined is accepted as a no-op, including with exactOptionalPropertyTypes. */
 type Resettable<T> = {
     [K in keyof T]?: T[K] | undefined;
 };
@@ -9,7 +9,7 @@ export type MapAppearance = {
     [K in keyof AppearanceOptions]?: K extends 'colors' | 'style' | 'labelStyle' | 'labelSize' | 'areaStyle' ? Resettable<NonNullable<AppearanceOptions[K]>> | undefined : AppearanceOptions[K] | undefined;
 };
 export type MapControls = NonNullable<NeighborhoodExplorerOptions['controls']>;
-/** Omitted keys retain values. Undefined presentation groups reset; undefined mode/source/year/labels retain their current value. */
+/** Omitted and undefined values retain current values. Use resetConfiguration to clear overrides. */
 export interface MapConfiguration {
     features?: Resettable<MapFeatures> | undefined;
     layers?: Resettable<InteractiveLayers> | undefined;
@@ -115,10 +115,7 @@ export interface MapEvents {
     };
     mapresize: undefined;
 }
-/** Convenience setters retain their historic reset default; false preserves the camera. */
-export interface MapViewUpdateOptions {
-    resetView?: boolean;
-}
+export type MapConfigurationGroup = 'features' | 'layers' | 'controls' | 'appearance';
 export interface MapCamera {
     /** Fixed 800 × 800 projected space, not longitude/latitude. */
     get(): MapViewport;
@@ -139,6 +136,8 @@ export interface MapController {
     readonly camera: MapCamera;
     readonly destroyed: boolean;
     configure(patch: MapConfiguration): void;
+    /** Clear presentation overrides to built-in defaults, preserving camera and geographic choices. */
+    resetConfiguration(groups?: readonly MapConfigurationGroup[]): void;
     getConfiguration(): MapConfigurationSnapshot;
     getResolvedConfiguration(): ResolvedMapConfiguration;
     getCapabilities(): MapCapabilities;
@@ -154,7 +153,7 @@ export interface MapController {
         fit?: boolean;
     }): boolean;
     getSelectedMarker(): MapMarker | null;
-    selectNeighborhood(name: string | null, options?: CameraOptions & {
+    selectNeighborhood(id: string | null, options?: CameraOptions & {
         fit?: boolean;
     }): boolean;
     getSelectedNeighborhood(): NeighborhoodSelection | null;
@@ -164,15 +163,12 @@ export interface MapController {
     getSelectedDistrict(): DistrictSelection | null;
     setDistrictYear(year: DistrictYear, options?: CameraOptions): void;
     setDistrictStyle(style: ((district: DistrictSelection['district']) => DistrictStyle) | undefined): void;
-    setSource(source: NeighborhoodSource, options?: MapViewUpdateOptions): void;
-    setMode(mode: NonNullable<MapOptions['mode']>, options?: MapViewUpdateOptions): void;
+    setSource(source: NeighborhoodSource): void;
+    setMode(mode: NonNullable<MapOptions['mode']>): void;
     setLabels(visible: boolean): void;
     setTouchNavigation(enabled: boolean): void;
-    projectToScreen(lng: number, lat: number): {
-        x: number;
-        y: number;
-        visible: boolean;
-    };
+    /** Accepts a GeoJSON position; returns canvas-relative CSS pixels. */
+    projectToScreen: ProjectToScreen;
     /** Idempotent; stops work and managed subscriptions. Does not remove host-owned DOM. */
     destroy(): void;
 }

package/dist/src/explorer-core.js

@@ -140,8 +140,10 @@ export function createNeighborhoodExplorerCore(options = {}, data, ui) {
         arrow.hidden = !features.northArrow;
     }
     syncFurniture();
-    function projectToScreen(lng, lat) {
-        const [x, y] = map.project([lng, lat]);
+    function projectToScreen(position) {
+        if (!Array.isArray(position) || position.length < 2)
+            throw new RangeError('Expected a [longitude, latitude] position.');
+        const [x, y] = map.project(position);
         const width = canvas.getBoundingClientRect().width;
         if (!width)
             throw new Error('Mount the map before projecting to screen.');
@@ -510,7 +512,10 @@ export function createNeighborhoodExplorerCore(options = {}, data, ui) {
     const clusters = createClusterLayer(svg, markerLayer, clusterLayer, markerNavigation, materializeMarker, (group, node, signal) => {
         if (destroyed || signal.aborted)
             return;
-        const markers = group.map((item) => ({ ...item.marker }));
+        const markers = group.map((item) => ({
+            ...item.marker,
+            position: [...item.marker.position],
+        }));
         const minimumUnit = 800 / 12 / Math.max(1, canvas.getBoundingClientRect().width);
         if (clusterPoints(group, minimumUnit, features.clustering ? features.clustering.radius : 36)
             .length === 1)
@@ -518,7 +523,7 @@ export function createNeighborhoodExplorerCore(options = {}, data, ui) {
         else
             fitGeometry({
                 type: 'MultiPoint',
-                coordinates: markers.map((marker) => [marker.lng, marker.lat]),
+                coordinates: markers.map((marker) => marker.position),
             });
         if (!destroyed && !signal.aborted)
             root.dispatchEvent(new CustomEvent('clusteractivate', { bubbles: true, detail: { markers } }));
@@ -866,7 +871,7 @@ export function createNeighborhoodExplorerCore(options = {}, data, ui) {
     }
     function getSelectedMarker() {
         const marker = markerCatalog.items.find((item) => item.marker.id === selectedMarker)?.marker;
-        return marker ? { ...marker } : null;
+        return marker ? { ...marker, position: [...marker.position] } : null;
     }
     function selectMarker(id, options = {}) {
         if (destroyed)

package/dist/src/geometry.d.ts

@@ -1,5 +1,10 @@
-import type { Geometry, Position } from '../data/types.js';
+import type { Bounds, Geometry, Position } from '../data/types.js';
+export type { Bounds, Geometry, Position } from '../data/types.js';
 export type Project = (position: Position) => [number, number];
 export declare function rawProject([longitude, latitude]: Position): [number, number];
 export declare function positions(geometry: Geometry | null | undefined): Position[];
 export declare function geometryPath(geometry: Geometry | null | undefined, project: Project): string;
+/** Geographic [west, south, east, north], or null for empty geometry. */
+export declare function geometryBounds(geometry: Geometry | null | undefined): Bounds | null;
+/** Polygon hit testing in longitude/latitude; boundaries (including hole edges) count as hits. */
+export declare function geometryContainsPoint(geometry: Geometry | null | undefined, point: Position): boolean;

package/dist/src/geometry.js

@@ -51,3 +51,83 @@ export function geometryPath(geometry, project) {
             return '';
     }
 }
+function validatePosition(point) {
+    if (!Number.isFinite(point[0]) ||
+        !Number.isFinite(point[1]) ||
+        Math.abs(point[0]) > 180 ||
+        Math.abs(point[1]) > 90)
+        throw new RangeError('Expected finite longitude/latitude within [-180, 180] and [-90, 90].');
+}
+/** Geographic [west, south, east, north], or null for empty geometry. */
+export function geometryBounds(geometry) {
+    let west = Infinity;
+    let south = Infinity;
+    let east = -Infinity;
+    let north = -Infinity;
+    for (const point of positions(geometry)) {
+        validatePosition(point);
+        west = Math.min(west, point[0]);
+        south = Math.min(south, point[1]);
+        east = Math.max(east, point[0]);
+        north = Math.max(north, point[1]);
+    }
+    return west === Infinity ? null : [west, south, east, north];
+}
+// 0 outside, 1 inside, 2 on an edge. Rings may be explicitly or implicitly closed.
+function ringLocation(point, ring) {
+    if (ring.length < 3)
+        return 0;
+    let inside = false;
+    const [x, y] = point;
+    for (let i = 0, j = ring.length - 1; i < ring.length; j = i++) {
+        const [ax, ay] = ring[j];
+        const [bx, by] = ring[i];
+        const cross = (x - ax) * (by - ay) - (y - ay) * (bx - ax);
+        if (cross === 0 &&
+            x >= Math.min(ax, bx) &&
+            x <= Math.max(ax, bx) &&
+            y >= Math.min(ay, by) &&
+            y <= Math.max(ay, by))
+            return 2;
+        if (ay > y !== by > y && x < ((bx - ax) * (y - ay)) / (by - ay) + ax)
+            inside = !inside;
+    }
+    return inside ? 1 : 0;
+}
+/** Polygon hit testing in longitude/latitude; boundaries (including hole edges) count as hits. */
+export function geometryContainsPoint(geometry, point) {
+    validatePosition(point);
+    // Validate the entire input, including parts not reached by the hit test.
+    geometryBounds(geometry);
+    const polygonContains = (rings) => {
+        if (!rings.length)
+            return false;
+        const outer = ringLocation(point, rings[0]);
+        if (outer === 0)
+            return false;
+        if (outer === 2)
+            return true;
+        let inHole = false;
+        for (const ring of rings.slice(1)) {
+            const location = ringLocation(point, ring);
+            if (location === 2)
+                return true;
+            if (location === 1)
+                inHole = true;
+        }
+        return !inHole;
+    };
+    const contains = (part) => {
+        switch (part.type) {
+            case 'Polygon':
+                return polygonContains(part.coordinates);
+            case 'MultiPolygon':
+                return part.coordinates.some(polygonContains);
+            case 'GeometryCollection':
+                return part.geometries.some(contains);
+            default:
+                return false;
+        }
+    };
+    return geometry ? contains(geometry) : false;
+}

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

@@ -2,7 +2,7 @@ import type { SFMapOptions } from './types.js';
 /** Server-safe overview using exactly the guide browser geography. */
 export declare function createGuideSVG(options?: SFMapOptions): {
     svg: string;
-    project: (coordinates: import("../data/types.js").Position) => [number, number];
+    project: (coordinates: import("./geometry.js").Position) => [number, number];
     viewBox: [number, number, number, number];
 };
 /** Stable compact frame, progressively enhanced with mountGuideMap(). No browser globals. */

package/dist/src/layers.js

@@ -58,7 +58,7 @@ export function markers(items, { project, colors, animated }) {
         .map((marker, index) => {
         if (marker.radius !== undefined && (!Number.isFinite(marker.radius) || marker.radius <= 0))
             throw new RangeError('Marker radius must be positive and finite.');
-        const [x, y] = project([marker.lng, marker.lat]).map(number);
+        const [x, y] = project(marker.position).map(number);
         return `<circle data-marker-id="${escapeXml(marker.id)}" cx="${x}" cy="${y}" r="${marker.radius ?? (marker.selected ? 8 : 5)}" fill="${escapeXml(marker.color ?? (marker.selected ? colors.selected : colors.marker))}" stroke="#fff9e9" stroke-width="2" vector-effect="non-scaling-stroke"${order(animated, index)}><title>${escapeXml(marker.label ?? marker.id)}</title></circle>`;
     })
         .join('')}</g>`;

package/dist/src/map.d.ts

@@ -2,6 +2,6 @@ import type { MapController, MapOptions } from './controller-types.js';
 import type { InteractiveSFMapData } from './explorer-data.js';
 export type * from './controller-types.js';
 export type { InteractiveSFMapData as MapData } from './explorer-data.js';
-export type { CameraOptions, DistrictSelection, DistrictStyle, DistrictYear, InteractiveLayers, MapFeatures, MapMarker, MapOverlay, MapPadding, MapViewport, NeighborhoodSelection, } from './types.js';
+export type { CameraOptions, DistrictSelection, DistrictStyle, DistrictYear, InteractiveLayers, MapFeatures, MapMarker, MapOverlay, MapPadding, MapViewport, NeighborhoodSelection, ProjectToScreen, ScreenPoint, } from './types.js';
 /** No geography is imported. Supply a preset or your own immutable data. */
 export declare function createMap(data: InteractiveSFMapData, options?: MapOptions): MapController;

package/dist/src/map.js

@@ -1,6 +1,6 @@
 import { copyAppearance } from './appearance.js';
 import { validateCameraOptions } from './camera.js';
-import { expandMapOptions, prepareConfiguration } from './configuration.js';
+import { configurationPatch, expandMapOptions, prepareConfiguration } from './configuration.js';
 import { createNeighborhoodExplorerCore } from './explorer-core.js';
 import { createMapShell } from './explorer-shell.js';
 import { controlKeys, layerKeys } from './features.js';
@@ -144,13 +144,6 @@ export function createMap(data, options = {}) {
         }, () => !destroyed && revision === configurationRevision);
         return committed && !destroyed && revision === configurationRevision;
     }
-    function updateView(patch, options = {}) {
-        assertOptions(options, 'view update', ['resetView']);
-        if (options.resetView !== undefined && typeof options.resetView !== 'boolean')
-            throw new TypeError('resetView must be a boolean.');
-        if (configure(patch) && options.resetView !== false)
-            element.resetView();
-    }
     return Object.freeze({
         element,
         overlayElement: element.overlayElement,
@@ -159,7 +152,13 @@ export function createMap(data, options = {}) {
             return destroyed;
         },
         configure: use((patch) => {
-            configure(patch);
+            configure(configurationPatch(patch, config));
+        }),
+        resetConfiguration: use((groups = ['features', 'layers', 'controls', 'appearance']) => {
+            if (!Array.isArray(groups) ||
+                groups.some((key) => !['features', 'layers', 'controls', 'appearance'].includes(key)))
+                throw new TypeError('Unknown configuration reset group.');
+            configure(Object.fromEntries(groups.map((key) => [key, undefined])));
         }),
         getConfiguration: use(snapshot),
         getResolvedConfiguration: use(resolved),
@@ -231,7 +230,14 @@ export function createMap(data, options = {}) {
         }),
         selectMarker: use(element.selectMarker),
         getSelectedMarker: use(element.getSelectedMarker),
-        selectNeighborhood: use(element.selectNeighborhood),
+        selectNeighborhood: use((id, options) => {
+            const source = element.getMapState().source;
+            if (id !== null && (typeof id !== 'string' || !id))
+                throw new TypeError('Neighborhood IDs must be nonempty strings or null.');
+            if (id !== null && !data.neighborhoods[source]?.features.some((feature) => feature.id === id))
+                return false;
+            return element.selectNeighborhood(id, options);
+        }),
         getSelectedNeighborhood: use(element.getSelection),
         selectDistrict: use(element.selectDistrict),
         getSelectedDistrict: use(element.getSelectedDistrict),
@@ -242,8 +248,12 @@ export function createMap(data, options = {}) {
         setDistrictStyle: use((style) => {
             configure({ appearance: { districtStyle: style } });
         }),
-        setSource: use((source, options) => updateView({ source }, options)),
-        setMode: use((mode, options) => updateView({ mode }, options)),
+        setSource: use((source) => {
+            configure({ source });
+        }),
+        setMode: use((mode) => {
+            configure({ mode });
+        }),
         setLabels: use((labels) => {
             configure({ labels });
         }),

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

@@ -1,7 +1,7 @@
 import type { createMarkerLayer, MarkerItem } from './marker-layer.js';
 import type { MapMarker } from './types.js';
 /** Own ordered records and picker reconciliation; prepare before committing DOM changes. */
-export declare function createMarkerCatalog(renderer: ReturnType<typeof createMarkerLayer>, picker: HTMLSelectElement, project: (point: [number, number]) => [number, number]): {
+export declare function createMarkerCatalog(renderer: ReturnType<typeof createMarkerLayer>, picker: HTMLSelectElement, project: (point: import('../data/types.js').Position) => [number, number]): {
     readonly items: MarkerItem[];
     prepare(markers: readonly MapMarker[], selected: string | null): {
         selection: string | null;

package/dist/src/marker-catalog.js

@@ -14,19 +14,25 @@ export function createMarkerCatalog(renderer, picker, project) {
             const next = markers.map((marker) => {
                 ids.add(marker.id);
                 const previous = existing.get(marker.id);
-                const point = previous?.marker.lng === marker.lng && previous.marker.lat === marker.lat
+                const point = previous?.marker.position[0] === marker.position[0] &&
+                    previous.marker.position[1] === marker.position[1]
                     ? previous.point
-                    : project([marker.lng, marker.lat]);
-                return { marker: { ...marker }, point };
+                    : project(marker.position);
+                return {
+                    marker: { ...marker, position: [...marker.position] },
+                    point,
+                };
             });
             const selection = selected && ids.has(selected)
                 ? selected
                 : (markers.find((marker) => marker.selected)?.id ?? null);
-            const keys = ['id', 'lng', 'lat', 'label', 'selected', 'color', 'radius'];
+            const keys = ['id', 'label', 'selected', 'color', 'radius'];
             if (picker.options.length > 0 &&
                 selection === selected &&
                 next.length === items.length &&
-                next.every(({ marker }, index) => keys.every((key) => marker[key] === items[index].marker[key])))
+                next.every(({ marker }, index) => marker.position.length === items[index].marker.position.length &&
+                    marker.position.every((value, offset) => value === items[index].marker.position[offset]) &&
+                    keys.every((key) => marker[key] === items[index].marker[key])))
                 return undefined;
             const focused = items.find((item) => item.visual?.node === document.activeElement)?.marker.id;
             return {

package/dist/src/static-labels.js

@@ -57,7 +57,7 @@ export function staticLabels(data, options, project) {
         selected: marker
             ? [
                 {
-                    point: point([marker.lng, marker.lat]),
+                    point: point(marker.position),
                     name: marker.label ?? marker.id,
                     kind: 'selected-marker',
                 },
@@ -96,7 +96,7 @@ export function staticLabels(data, options, project) {
             })
             : []),
         ...markers.map((item) => {
-            const [x, y] = point([item.lng, item.lat]);
+            const [x, y] = point(item.position);
             // Also cover the legacy SVG marker when it is larger than its interactive counterpart.
             const radius = Math.max(item.radius ?? 6, (item.radius ?? (item.selected ? 8 : 5)) / unit) + 3;
             return [x - radius, y - radius, x + radius, y + radius];
@@ -109,7 +109,7 @@ export function staticLabels(data, options, project) {
         textWidth: estimateLabelWidth(item.name, item.fontSize),
         textHeight: item.fontSize * 1.25,
     })), width, height, obstacles);
-    return `<g data-layer="overview-labels" font-family="system-ui,sans-serif">${spreadLabels(placed, options.labelLayout?.maxLabels, markers.map((marker) => point([marker.lng, marker.lat])), width, height)
+    return `<g data-layer="overview-labels" font-family="system-ui,sans-serif">${spreadLabels(placed, options.labelLayout?.maxLabels, markers.map((marker) => point(marker.position)), width, height)
         .map((item) => `<text data-label-kind="${escapeXml(item.kind)}" text-anchor="middle" x="${number((item.left + item.textWidth / 2) * unit)}" y="${number((item.top + item.fontSize) * unit)}" font-size="${number(item.fontSize * unit)}" font-weight="${item.fontWeight}" fill="${escapeXml(item.fill)}" stroke="${escapeXml(item.halo)}" stroke-width="${number(3 * unit)}" stroke-linejoin="round" paint-order="stroke">${escapeXml(item.name)}</text>`)
         .join('')}</g>`;
 }

package/dist/src/static.d.ts

@@ -8,14 +8,14 @@ export type { DistrictStyle, DistrictYear, SFMapOptions as StaticMapOptions, Sta
 /** Server-safe SVG rendering with explicit data; returns SVG plus projection helpers. */
 export declare function renderMap(data: StaticMapInput, options?: SFMapOptions): {
     svg: string;
-    project: (coordinates: import("../data/types.js").Position) => [number, number];
+    project: (coordinates: import("./geometry.js").Position) => [number, number];
     viewBox: [number, number, number, number];
 };
 /** Project canonical layer geometry without constructing an SVG string. */
 export declare function getLayerPaths(data: StaticMapInput, options?: SFMapOptions): {
     year: import("./types.js").DistrictYear;
     viewBox: [number, number, number, number];
-    project: (coordinates: import("../data/types.js").Position) => [number, number];
+    project: (coordinates: import("./geometry.js").Position) => [number, number];
     coast: string;
     districts: {
         id: number;

package/dist/src/types.d.ts

@@ -1,4 +1,12 @@
-import type { Geometry, NeighborhoodFeature, NeighborhoodSource } from '../data/types.js';
+import type { Geometry, NeighborhoodFeature, NeighborhoodSource, Position } from '../data/types.js';
+/** Canvas-relative CSS pixels; visibility means inside the current square map viewport. */
+export interface ScreenPoint {
+    x: number;
+    y: number;
+    visible: boolean;
+}
+/** WGS84 longitude/latitude; altitude, if supplied in a position, is ignored. */
+export type ProjectToScreen = (position: Position) => ScreenPoint;
 export type DistrictYear = 2002 | 2012 | 2022;
 export interface DistrictSelection {
     id: number;
@@ -12,8 +20,7 @@ export interface DistrictStyle {
 }
 export interface MapMarker {
     id: string;
-    lng: number;
-    lat: number;
+    position: Position;
     label?: string;
     selected?: boolean;
     color?: string;
@@ -220,11 +227,7 @@ export interface CameraOptions {
 export interface NeighborhoodExplorerElement extends HTMLElement {
     /** Append positioned HTML children here; coordinates are relative to this layer. */
     readonly overlayElement: HTMLDivElement;
-    projectToScreen(lng: number, lat: number): {
-        x: number;
-        y: number;
-        visible: boolean;
-    };
+    projectToScreen: ProjectToScreen;
     stopAnimation(): void;
     /** Atomic patch; false disables, undefined resets a feature to its default. */
     setFeatures(patch: MapFeatures): void;
@@ -268,4 +271,4 @@ export interface NeighborhoodExplorerElement extends HTMLElement {
 export interface TransitAnimationElement extends HTMLElement {
     destroy(): void;
 }
-export type { MapAppearance, MapCamera, MapCapabilities, MapConfiguration, MapConfigurationSnapshot, MapController, MapControls, MapEvents, MapFeatureReference, MapOptions, MapSelectionChange, MapViewUpdateOptions, ResolvedMapConfiguration, } from './controller-types.js';
+export type { MapAppearance, MapCamera, MapCapabilities, MapConfiguration, MapConfigurationGroup, MapConfigurationSnapshot, MapController, MapControls, MapEvents, MapFeatureReference, MapOptions, MapSelectionChange, ResolvedMapConfiguration, } from './controller-types.js';

package/dist/src/validation.js

@@ -155,14 +155,16 @@ export function validateMarkers(markers) {
         throw new TypeError('Markers must be an array.');
     const ids = new Set();
     for (const marker of markers) {
-        assertOptions(marker, 'marker');
+        assertOptions(marker, 'marker', ['id', 'position', 'label', 'selected', 'color', 'radius']);
         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)
+        if (!Array.isArray(marker.position) ||
+            marker.position.length < 2 ||
+            !Number.isFinite(marker.position[0]) ||
+            Math.abs(marker.position[0]) > 180 ||
+            !Number.isFinite(marker.position[1]) ||
+            Math.abs(marker.position[1]) >= 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.');