@kahwee/sf-map-svg 4.4.0 → 5.0.0

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/neighborhood-layer.d.ts

@@ -0,0 +1,67 @@
+import type { Bounds, NeighborhoodFeature, NeighborhoodSource } from '../data/types.js';
+import type { InteractiveSFMapData } from './explorer-data.js';
+import { type Project } from './geometry.js';
+import type { CameraOptions, DistrictYear, ExplorerMode, MapPadding, MapViewport, NeighborhoodExplorerOptions, NeighborhoodSelection } from './types.js';
+export interface NeighborhoodItem {
+    feature: NeighborhoodFeature;
+    node: SVGPathElement;
+    bounds: Bounds;
+    point: [number, number] | undefined;
+    area: number;
+}
+export declare const sourceNames: Record<NeighborhoodSource, string>;
+export declare const formatSourceLabel: (source: NeighborhoodSource) => string;
+/** Source-scoped names and aliases; same-name polygons never cross source boundaries. */
+export declare function createNeighborhoodLookup(collections: InteractiveSFMapData['neighborhoods']): {
+    getNeighborhood: (name: string, selectedSource: NeighborhoodSource) => import("../data/types.js").Feature<import("../data/types.js").NeighborhoodProperties> | undefined;
+    searchNeighborhoods: (query: string, selectedSource: NeighborhoodSource) => {
+        id: string;
+        canonicalName: string;
+    }[];
+};
+interface NeighborhoodPresentation {
+    mode: ExplorerMode;
+    year: DistrictYear;
+    fitPadding: number | MapPadding;
+    areaStyle: NonNullable<NeighborhoodExplorerOptions['areaStyle']>;
+    colors: NonNullable<NeighborhoodExplorerOptions['colors']>;
+    selectableNeighborhoods: boolean;
+    lines: boolean;
+}
+interface NeighborhoodLayerOptions {
+    collections: InteractiveSFMapData['neighborhoods'];
+    initialSource: NeighborhoodSource;
+    project: Project;
+    root: HTMLElement;
+    areas: SVGGElement;
+    canvas: HTMLElement;
+    sourceSelect: HTMLSelectElement;
+    neighborhoodSelect: HTMLSelectElement;
+    status: HTMLElement;
+    readPresentation(): NeighborhoodPresentation;
+    isDestroyed(): boolean;
+    ensureVisible(): void;
+    refresh: {
+        selection(): void;
+        source(): void;
+    };
+    moveView(view: MapViewport, options: CameraOptions): void;
+    resetView(): void;
+    crossfade(layer: SVGGElement, commit: () => void): void;
+}
+/** Own neighborhood identity, prepared geometry, selection revisions and hover listeners.
+ * Preparation is detached: only the returned commit can replace the active source.
+ */
+export declare function createNeighborhoodLayer({ collections, initialSource, project, root, areas, canvas, sourceSelect, neighborhoodSelect, status, readPresentation, isDestroyed, ensureVisible, refresh, moveView, resetView, crossfade, }: NeighborhoodLayerOptions): {
+    readonly source: NeighborhoodSource;
+    readonly selected: NeighborhoodFeature | undefined;
+    readonly items: readonly NeighborhoodItem[];
+    getSelection: () => NeighborhoodSelection | null;
+    selectNeighborhood: (name: string | null, options?: {
+        fit?: boolean;
+    } & CameraOptions) => boolean;
+    prepareSource: (next: NeighborhoodSource, reset?: boolean) => () => void;
+    setSource: (next: NeighborhoodSource) => void;
+    destroy(): void;
+};
+export {};

package/dist/src/neighborhood-layer.js

@@ -0,0 +1,256 @@
+import { validateCameraOptions } from './camera.js';
+import { element, svgElement } from './dom.js';
+import { fitBounds, interiorAnchor, projectedBounds } from './explorer-layout.js';
+import { geometryPath } from './geometry.js';
+import { fitViewport } from './viewport.js';
+export const sourceNames = {
+    realtor: 'SFAR realtor · 92 areas',
+    'sf-find': 'SF Find · 117 areas',
+    analysis: 'City analysis · 41 areas',
+};
+const normalizeName = (value) => value
+    .normalize('NFKD')
+    .toLowerCase()
+    .replace(/[\u0300-\u036f'’]/g, '')
+    .replace(/[^a-z0-9]+/g, ' ')
+    .trim();
+export const formatSourceLabel = (source) => sourceNames[source] ?? `${source} neighborhoods`;
+/** Source-scoped names and aliases; same-name polygons never cross source boundaries. */
+export function createNeighborhoodLookup(collections) {
+    const getNeighborhood = (name, selectedSource) => {
+        const term = normalizeName(name);
+        if (!term)
+            return undefined;
+        return collections[selectedSource]?.features.find((feature) => [
+            feature.id,
+            feature.properties.canonicalName,
+            feature.properties.sourceName,
+            ...feature.properties.aliases,
+        ].some((value) => normalizeName(value) === term));
+    };
+    const searchNeighborhoods = (query, selectedSource) => {
+        const term = normalizeName(query);
+        return (collections[selectedSource]?.features ?? [])
+            .filter((feature) => [
+            feature.id,
+            feature.properties.canonicalName,
+            feature.properties.sourceName,
+            ...feature.properties.aliases,
+        ].some((value) => normalizeName(value).includes(term)))
+            .map((feature) => ({ id: feature.id, canonicalName: feature.properties.canonicalName }));
+    };
+    return { getNeighborhood, searchNeighborhoods };
+}
+/** Own neighborhood identity, prepared geometry, selection revisions and hover listeners.
+ * Preparation is detached: only the returned commit can replace the active source.
+ */
+export function createNeighborhoodLayer({ collections, initialSource, project, root, areas, canvas, sourceSelect, neighborhoodSelect, status, readPresentation, isDestroyed, ensureVisible, refresh, moveView, resetView, crossfade, }) {
+    let source = initialSource;
+    let selected;
+    let items = [];
+    let neighborhoodRevision = 0;
+    let sourceEvents = new AbortController();
+    const { getNeighborhood } = createNeighborhoodLookup(collections);
+    function getSelection() {
+        return selected
+            ? {
+                id: selected.id,
+                name: selected.properties.canonicalName,
+                source,
+                feature: structuredClone(selected),
+            }
+            : null;
+    }
+    function selectNeighborhood(name, options = {}) {
+        if (isDestroyed())
+            return false;
+        const feature = name === null
+            ? undefined
+            : (collections[source]?.features.find((entry) => entry.id === name) ??
+                getNeighborhood(name, source));
+        if (name !== null && !feature)
+            return false;
+        validateCameraOptions(options);
+        const { fitPadding } = readPresentation();
+        const selectedItem = items.find((item) => item.feature === feature);
+        const width = canvas.getBoundingClientRect().width;
+        const target = selectedItem && options.fit !== false
+            ? width
+                ? fitViewport(selectedItem.bounds, width, fitPadding)
+                : fitBounds(selectedItem.bounds)
+            : null;
+        if (feature)
+            ensureVisible();
+        const { areaStyle, colors, selectableNeighborhoods, lines } = readPresentation();
+        const revision = ++neighborhoodRevision;
+        const changed = selected !== feature;
+        selected = feature;
+        for (const item of items) {
+            const active = item.feature === selected;
+            item.node.setAttribute('fill', active ? (areaStyle.selectedFill ?? '#408dbe') : 'transparent');
+            item.node.setAttribute('fill-opacity', active ? '.16' : '1');
+            item.node.setAttribute('stroke', active ? (areaStyle.selectedStroke ?? '#176ba2') : (colors.neighborhood ?? '#9caebc'));
+            item.node.setAttribute('stroke-width', active ? '2.2' : lines ? '.55' : '0');
+            if (selectableNeighborhoods)
+                item.node.setAttribute('aria-pressed', String(active));
+            if (active)
+                areas.append(item.node);
+        }
+        if (feature)
+            root.dataset.selectedNeighborhood = feature.id;
+        else
+            delete root.dataset.selectedNeighborhood;
+        neighborhoodSelect.value = feature?.id ?? '';
+        refresh.selection();
+        status.textContent = feature
+            ? `${feature.properties.canonicalName} selected. ${formatSourceLabel(source)}.`
+            : 'Neighborhood selection cleared.';
+        if (changed)
+            root.dispatchEvent(new CustomEvent('neighborhoodchange', {
+                bubbles: true,
+                detail: {
+                    feature: feature ? structuredClone(feature) : null,
+                    source,
+                    id: feature?.id ?? null,
+                    name: feature?.properties.canonicalName ?? null,
+                },
+            }));
+        if (!isDestroyed() && neighborhoodRevision === revision && target)
+            moveView(target, options);
+        return true;
+    }
+    function prepareSource(next, reset = true) {
+        const { colors } = readPresentation();
+        const events = new AbortController();
+        if (!Object.hasOwn(collections, next))
+            throw new RangeError(`Unknown neighborhood source: ${next}`);
+        const collection = collections[next];
+        if (!collection ||
+            !Array.isArray(collection.features) ||
+            typeof collection.title !== 'string' ||
+            typeof collection.definition?.description !== 'string')
+            throw new TypeError('Neighborhood collections require features, title and definition description.');
+        const ids = new Set();
+        const nextOptions = [];
+        const nextItems = collection.features.map((feature) => {
+            if (!feature ||
+                typeof feature.id !== 'string' ||
+                !feature.id ||
+                ids.has(feature.id) ||
+                !feature.properties ||
+                typeof feature.properties.canonicalName !== 'string' ||
+                typeof feature.properties.sourceName !== 'string' ||
+                !Array.isArray(feature.properties.aliases) ||
+                Array.from(feature.properties.aliases).some((alias) => typeof alias !== 'string') ||
+                !['Polygon', 'MultiPolygon'].includes(feature.geometry?.type))
+                throw new TypeError('Neighborhood features require unique IDs, names, aliases and polygon geometry.');
+            ids.add(feature.id);
+            const bounds = projectedBounds(feature.geometry, project);
+            if (!bounds.every(Number.isFinite))
+                throw new RangeError('Neighborhood geometry must be nonempty and finite.');
+            const node = svgElement('path', {
+                d: geometryPath(feature.geometry, project),
+                'data-neighborhood-id': feature.id,
+                fill: 'transparent',
+                'fill-rule': 'evenodd',
+                stroke: colors.neighborhood ?? '#9caebc',
+                'stroke-width': '.55',
+                'vector-effect': 'non-scaling-stroke',
+                role: 'button',
+                tabindex: -1,
+                'aria-label': feature.properties.canonicalName,
+                'aria-pressed': 'false',
+            });
+            const option = element('option', feature.properties.canonicalName);
+            option.value = feature.id;
+            nextOptions.push(option);
+            const title = svgElement('title');
+            title.textContent = feature.properties.canonicalName;
+            node.append(title);
+            node.addEventListener('pointerenter', () => {
+                const { selectableNeighborhoods, areaStyle, colors } = readPresentation();
+                if (isDestroyed() ||
+                    !selectableNeighborhoods ||
+                    selected?.id === feature.id ||
+                    (!areaStyle.hoverFill && !areaStyle.hoverStroke))
+                    return;
+                node.setAttribute('fill', areaStyle.hoverFill ?? '#408dbe');
+                node.setAttribute('fill-opacity', '.12');
+                node.setAttribute('stroke', areaStyle.hoverStroke ?? colors.neighborhood ?? '#176ba2');
+            }, { signal: events.signal });
+            node.addEventListener('pointerleave', () => {
+                if (isDestroyed() || selected?.id === feature.id)
+                    return;
+                node.setAttribute('fill', 'transparent');
+                node.setAttribute('fill-opacity', '1');
+                node.setAttribute('stroke', readPresentation().colors.neighborhood ?? '#9caebc');
+            }, { signal: events.signal });
+            return {
+                feature,
+                node,
+                bounds,
+                point: interiorAnchor(feature.geometry, project),
+                area: (bounds[2] - bounds[0]) * (bounds[3] - bounds[1]),
+            };
+        });
+        return () => {
+            if (isDestroyed()) {
+                events.abort();
+                return;
+            }
+            sourceEvents.abort();
+            sourceEvents = events;
+            const { mode, year } = readPresentation();
+            const hadSelection = !!selected;
+            source = next;
+            sourceSelect.value = source;
+            selected = undefined;
+            const revision = ++neighborhoodRevision;
+            delete root.dataset.selectedNeighborhood;
+            root.dataset.source = source;
+            crossfade(areas, () => areas.replaceChildren(...nextItems.map((item) => item.node)));
+            neighborhoodSelect.replaceChildren(element('option', 'No neighborhood selected'));
+            neighborhoodSelect.options[0].value = '';
+            neighborhoodSelect.append(...nextOptions);
+            items = nextItems;
+            if (items[0])
+                items[0].node.setAttribute('tabindex', '0');
+            refresh.source();
+            status.textContent =
+                mode === 'basemap'
+                    ? 'San Francisco basemap.'
+                    : mode === 'districts'
+                        ? `${year} supervisorial districts. Numbers identify each district.`
+                        : `${formatSourceLabel(source)}. Select a neighborhood to begin.`;
+            if (hadSelection)
+                root.dispatchEvent(new CustomEvent('neighborhoodchange', {
+                    bubbles: true,
+                    detail: { feature: null, source, id: null, name: null },
+                }));
+            if (reset && !isDestroyed() && neighborhoodRevision === revision)
+                resetView();
+        };
+    }
+    function setSource(next) {
+        if (!isDestroyed())
+            prepareSource(next)();
+    }
+    return {
+        get source() {
+            return source;
+        },
+        get selected() {
+            return selected;
+        },
+        get items() {
+            return items;
+        },
+        getSelection,
+        selectNeighborhood,
+        prepareSource,
+        setSource,
+        destroy() {
+            sourceEvents.abort();
+        },
+    };
+}

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

@@ -0,0 +1,13 @@
+import { type Project } from './geometry.js';
+import type { MapOverlay } from './types.js';
+/** Prepare overlays before replacing live nodes; each replacement owns an abortable event scope. */
+export declare function createOverlayLayer({ layer: overlayLayer, root, project, onOverlayActivate, isDestroyed, }: {
+    layer: SVGGElement;
+    root: HTMLElement;
+    project: Project;
+    onOverlayActivate: ((overlay: MapOverlay) => void) | undefined;
+    isDestroyed(): boolean;
+}): {
+    set: (overlays: readonly MapOverlay[]) => void;
+    destroy(): void;
+};

package/dist/src/overlay-layer.js

@@ -0,0 +1,68 @@
+import { svgElement } from './dom.js';
+import { geometryPath } from './geometry.js';
+import { validateOverlays } from './validation.js';
+/** Prepare overlays before replacing live nodes; each replacement owns an abortable event scope. */
+export function createOverlayLayer({ layer: overlayLayer, root, project, onOverlayActivate, isDestroyed, }) {
+    let overlayEvents = new AbortController();
+    function setOverlays(overlays) {
+        if (isDestroyed())
+            return;
+        validateOverlays(overlays);
+        const events = new AbortController();
+        const next = overlays.map((input) => {
+            const overlay = structuredClone(input);
+            const node = svgElement('path', {
+                'data-overlay-id': overlay.id,
+                d: geometryPath(overlay.geometry, project),
+                fill: overlay.fill ?? 'none',
+                'fill-opacity': overlay.fillOpacity ?? 1,
+                stroke: overlay.stroke ?? '#bd8b73',
+                'stroke-width': overlay.strokeWidth ?? 2,
+                'vector-effect': 'non-scaling-stroke',
+                display: overlay.visible === false ? 'none' : 'inline',
+                'pointer-events': 'none',
+                ...(overlay.label ? { 'aria-label': overlay.label } : {}),
+            });
+            if (overlay.label) {
+                node.setAttribute('role', 'img');
+                const title = svgElement('title');
+                title.textContent = overlay.label;
+                node.append(title);
+            }
+            if (onOverlayActivate) {
+                node.setAttribute('role', 'button');
+                node.setAttribute('tabindex', overlay.visible === false ? '-1' : '0');
+                node.setAttribute('pointer-events', overlay.fill && overlay.fill !== 'none' ? 'visiblePainted' : 'stroke');
+                node.setAttribute('aria-label', overlay.label ?? overlay.id);
+                const activate = () => {
+                    if (isDestroyed() || events.signal.aborted)
+                        return;
+                    onOverlayActivate(structuredClone(overlay));
+                    if (isDestroyed() || events.signal.aborted)
+                        return;
+                    root.dispatchEvent(new CustomEvent('overlayactivate', {
+                        bubbles: true,
+                        detail: { overlay: structuredClone(overlay) },
+                    }));
+                };
+                node.addEventListener('click', activate, { signal: events.signal });
+                node.addEventListener('keydown', (event) => {
+                    if (event.key === 'Enter' || event.key === ' ') {
+                        event.preventDefault();
+                        activate();
+                    }
+                }, { signal: events.signal });
+            }
+            return node;
+        });
+        overlayEvents.abort();
+        overlayEvents = events;
+        overlayLayer.replaceChildren(...next);
+    }
+    return {
+        set: setOverlays,
+        destroy() {
+            overlayEvents.abort();
+        },
+    };
+}

package/dist/src/palettes.d.ts

@@ -0,0 +1,48 @@
+import type { SFMapOptions } from './types.js';
+/** Shared tokens for static SVGs, interactive maps, and consumer-owned place cards. */
+export interface MapPalette {
+    readonly colors: NonNullable<SFMapOptions['colors']>;
+    readonly haloColor: string;
+    readonly markerColor: string;
+    readonly selectedMarkerColor: string;
+    readonly selectedMarkerRingColor: string;
+}
+/** Opt-in editorial palettes inspired by YorkSF. Existing renderer themes stay unchanged. */
+export declare const mapPalettes: {
+    nightForest: {
+        colors: {
+            water: string;
+            land: string;
+            park: string;
+            neighborhood: string;
+            district: string;
+            road: string;
+            highway: string;
+            landmark: string;
+            bart: string;
+            label: string;
+        };
+        haloColor: string;
+        markerColor: string;
+        selectedMarkerColor: string;
+        selectedMarkerRingColor: string;
+    };
+    warmPaper: {
+        colors: {
+            water: string;
+            land: string;
+            park: string;
+            neighborhood: string;
+            district: string;
+            road: string;
+            highway: string;
+            landmark: string;
+            bart: string;
+            label: string;
+        };
+        haloColor: string;
+        markerColor: string;
+        selectedMarkerColor: string;
+        selectedMarkerRingColor: string;
+    };
+};

package/dist/src/palettes.js

@@ -0,0 +1,40 @@
+import { deepFreeze } from './immutable.js';
+/** Opt-in editorial palettes inspired by YorkSF. Existing renderer themes stay unchanged. */
+export const mapPalettes = /* @__PURE__ */ deepFreeze({
+    nightForest: {
+        colors: {
+            water: '#0a1412',
+            land: '#1b2c28',
+            park: '#1f3d33',
+            neighborhood: '#3b554e',
+            district: '#3b554e',
+            road: '#2f4943',
+            highway: '#5a4d40',
+            landmark: '#8fcbb4',
+            bart: '#8ea4ae',
+            label: '#d5e3e8',
+        },
+        haloColor: '#1b2c28',
+        markerColor: '#f2845f',
+        selectedMarkerColor: '#fff9e9',
+        selectedMarkerRingColor: '#ff957d',
+    },
+    warmPaper: {
+        colors: {
+            water: '#dce8ea',
+            land: '#f4efe4',
+            park: '#dcebe2',
+            neighborhood: '#88998e',
+            district: '#566b60',
+            road: '#c6bca9',
+            highway: '#987859',
+            landmark: '#315d48',
+            bart: '#365b68',
+            label: '#243d32',
+        },
+        haloColor: '#f4efe4',
+        markerColor: '#b23b10',
+        selectedMarkerColor: '#183a2f',
+        selectedMarkerRingColor: '#b23b10',
+    },
+});

package/dist/src/presets.d.ts

@@ -1,3 +1,4 @@
 import type { MapOptions } from './controller-types.js';
 /** Configuration only: pair with guide/data or a compatible caller-supplied dataset. */
 export declare const guideOptions: Readonly<MapOptions>;
+export { type MapPalette, mapPalettes } from './palettes.js';

package/dist/src/presets.js

@@ -15,3 +15,4 @@ export const guideOptions = deepFreeze({
         roadLabels: true,
     },
 });
+export { mapPalettes } from './palettes.js';

package/dist/src/static-labels.js

@@ -1,5 +1,6 @@
 import { interiorAnchor, layoutLabels, projectedBounds } from './explorer-layout.js';
 import { labelCandidates, styleLabels } from './label-candidates.js';
+import { spreadLabels } from './label-spread.js';
 import { escapeXml, number } from './svg.js';
 /** Conservative portable metrics; the browser refines these with its actual font. */
 export function estimateLabelWidth(text, fontSize) {
@@ -19,6 +20,14 @@ export function estimateLabelWidth(text, fontSize) {
 }
 /** Interactive overview rules, expressed entirely in screen pixels before serialization. */
 export function staticLabels(data, options, project) {
+    if (options.labelLayout?.compact) {
+        const { compact, ...layout } = options.labelLayout;
+        const wide = staticLabels(data, { ...options, labelLayout: layout }, project);
+        const narrow = staticLabels(data, { ...options, labelLayout: { ...layout, ...compact } }, project);
+        // Width-specific selectors prevent different breakpoints in inline maps interfering.
+        const key = compact.width;
+        return `<style>[data-label-layout="compact-${key}"]{display:none}@media(max-width:${key}px){[data-label-layout="wide-${key}"]{display:none}[data-label-layout="compact-${key}"]{display:inline}}</style><g data-label-layout="wide-${key}">${wide}</g><g data-label-layout="compact-${key}">${narrow}</g>`;
+    }
     const width = options.labelLayout?.width ?? options.width ?? 800;
     const unit = (options.width ?? 800) / width;
     const height = (options.height ?? 800) / unit;
@@ -48,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',
                 },
@@ -74,7 +83,11 @@ export function staticLabels(data, options, project) {
             }))
             : [],
         neighborhoods: neighborhoods.flatMap((item) => item.point ? [{ point: item.point, name: item.name, kind: 'neighborhood' }] : []),
-    }, width, 1), { colors: options.colors, markerRadius: marker?.radius ?? 6 });
+    }, width, 1), {
+        colors: options.colors,
+        markerRadius: marker?.radius ?? 6,
+        labelStyle: { haloColor: options.labelLayout?.haloColor },
+    });
     const obstacles = [
         ...(options.bartStations
             ? (data.bartStations ?? []).map((item) => {
@@ -83,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];
@@ -96,5 +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">${placed.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>`;
+    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/static.js

@@ -84,9 +84,28 @@ function expandStaticOptions(options) {
         if (options[key] !== undefined && typeof options[key] !== 'string')
             throw new TypeError(`${key} must be a string.`);
     if (options.labelLayout !== undefined) {
-        assertOptions(options.labelLayout, 'label layout', ['width']);
+        assertOptions(options.labelLayout, 'label layout', [
+            'width',
+            'maxLabels',
+            'haloColor',
+            'compact',
+        ]);
         if (!Number.isFinite(options.labelLayout.width) || options.labelLayout.width <= 0)
-            throw new RangeError('Label layout width must be positive and finite.');
+            throw new RangeError('Invalid label layout width.');
+        const { maxLabels, haloColor, compact } = options.labelLayout;
+        if (maxLabels !== undefined && (!Number.isSafeInteger(maxLabels) || maxLabels < 0))
+            throw new RangeError('Invalid maxLabels.');
+        if (haloColor !== undefined && typeof haloColor !== 'string')
+            throw new TypeError('haloColor must be a string.');
+        if (compact !== undefined) {
+            assertOptions(compact, 'compact label layout', ['width', 'maxLabels']);
+            if (!Number.isFinite(compact.width) ||
+                compact.width <= 0 ||
+                compact.width >= options.labelLayout.width)
+                throw new RangeError('Invalid compact width.');
+            if (!Number.isSafeInteger(compact.maxLabels) || compact.maxLabels < 0)
+                throw new RangeError('Invalid maxLabels.');
+        }
     }
     if (options.markers !== undefined)
         validateMarkers(options.markers);