@kahwee/sf-map-svg 1.5.1 → 2.0.0

package/dist/src/features.d.ts

@@ -0,0 +1,24 @@
+import type { MapFeatures } from './types.js';
+/** One normalization boundary shared by construction and atomic runtime patches. */
+export declare function normalizeFeatures(input?: MapFeatures): {
+    motion: false | {
+        duration: number;
+    };
+    markerEntrance: false | {
+        duration: number;
+        stagger: number;
+    };
+    clustering: false | {
+        radius: number;
+    };
+    selectedMarkerRing: false | {
+        color: string | undefined;
+        width: number;
+        gap: number;
+    };
+    northArrow: boolean;
+    scaleBar: boolean;
+};
+export declare const layerKeys: readonly ['districtFills', 'districtLines', 'districtLabels', 'neighborhoodLines', 'neighborhoodLabels', 'landmarks', 'bartStations', 'highways', 'keyRoads', 'roadLabels'];
+export declare const controlKeys: readonly ['zoom', 'pan', 'reset', 'labels', 'touch', 'legend', 'neighborhoodPicker', 'markerPicker', 'help', 'status'];
+export declare function validateSwitchPatch(patch: unknown, keys: readonly string[]): void;

package/dist/src/features.js

@@ -0,0 +1,99 @@
+import { assertOptions } from './validation.js';
+function objectOption(value, name) {
+    if (value === undefined || value === false)
+        return false;
+    if (value === true)
+        return {};
+    assertOptions(value, name, name === 'motion'
+        ? ['duration']
+        : name === 'markerEntrance'
+            ? ['duration', 'stagger']
+            : name === 'clustering'
+                ? ['radius']
+                : ['color', 'width', 'gap']);
+    return value;
+}
+function numberOption(value, fallback, name, positive = false) {
+    const result = value === undefined ? fallback : value;
+    if (typeof result !== 'number' ||
+        !Number.isFinite(result) ||
+        (positive ? result <= 0 : result < 0))
+        throw new RangeError(`${name} must be finite and ${positive ? 'positive' : 'nonnegative'}.`);
+    return result;
+}
+function flag(value, name) {
+    if (value !== undefined && typeof value !== 'boolean')
+        throw new TypeError(`${name} must be a boolean.`);
+    return value ?? false;
+}
+/** One normalization boundary shared by construction and atomic runtime patches. */
+export function normalizeFeatures(input = {}) {
+    assertOptions(input, 'features');
+    const keys = [
+        'motion',
+        'markerEntrance',
+        'clustering',
+        'selectedMarkerRing',
+        'northArrow',
+        'scaleBar',
+    ];
+    for (const key of Object.keys(input))
+        if (!keys.includes(key))
+            throw new TypeError(`Unknown feature: ${key}`);
+    const motion = objectOption(input.motion, 'motion');
+    const entrance = objectOption(input.markerEntrance, 'markerEntrance');
+    const clustering = objectOption(input.clustering, 'clustering');
+    const ring = objectOption(input.selectedMarkerRing, 'selectedMarkerRing');
+    if (ring && ring.color !== undefined && typeof ring.color !== 'string')
+        throw new TypeError('Ring color must be a string.');
+    return {
+        motion: motion && { duration: numberOption(motion.duration, 320, 'Motion duration') },
+        markerEntrance: entrance && {
+            duration: numberOption(entrance.duration, 420, 'Entrance duration'),
+            stagger: numberOption(entrance.stagger, 35, 'Entrance stagger'),
+        },
+        clustering: clustering && {
+            radius: numberOption(clustering.radius, 32, 'Cluster radius', true),
+        },
+        selectedMarkerRing: ring && {
+            color: ring.color,
+            width: numberOption(ring.width, 2, 'Ring width'),
+            gap: numberOption(ring.gap, 3, 'Ring gap'),
+        },
+        northArrow: flag(input.northArrow, 'northArrow'),
+        scaleBar: flag(input.scaleBar, 'scaleBar'),
+    };
+}
+export const layerKeys = [
+    'districtFills',
+    'districtLines',
+    'districtLabels',
+    'neighborhoodLines',
+    'neighborhoodLabels',
+    'landmarks',
+    'bartStations',
+    'highways',
+    'keyRoads',
+    'roadLabels',
+];
+export const controlKeys = [
+    'zoom',
+    'pan',
+    'reset',
+    'labels',
+    'touch',
+    'legend',
+    'neighborhoodPicker',
+    'markerPicker',
+    'help',
+    'status',
+];
+export function validateSwitchPatch(patch, keys) {
+    const record = assertOptions(patch, 'switches');
+    for (const [key, value] of Object.entries(record)) {
+        if (!keys.includes(key))
+            throw new TypeError(`Unknown switch: ${key}`);
+        if (value !== undefined && typeof value !== 'boolean')
+            throw new TypeError(`${key} must be boolean.`);
+    }
+}

package/dist/src/guide-data.js

@@ -4,13 +4,14 @@ import highways from '../data/guide/highways.json' with { type: 'json' };
 import roads from '../data/guide/key-roads.json' with { type: 'json' };
 import landmarks from '../data/guide/landmarks.json' with { type: 'json' };
 import neighborhoods from '../data/guide/neighborhoods-realtor.json' with { type: 'json' };
+import { deepFreeze } from './immutable.js';
 const neighborhoodData = neighborhoods;
 const highwayData = highways;
 const parkData = landmarks;
 const roadData = roads;
 const stationData = bart;
 /** Compact, source-aware geography with no district or alternate-neighborhood files. */
-export const guideMapData = {
+export const guideMapData = deepFreeze({
     map: {
         coast: coast.features[0].geometry,
         neighborhoods: neighborhoodData.features.map((feature) => ({
@@ -38,4 +39,4 @@ export const guideMapData = {
             : []),
     },
     neighborhoods: { realtor: neighborhoodData },
-};
+});

package/dist/src/guide-detailed.js

@@ -1,3 +1,4 @@
+import { deepFreeze } from './immutable.js';
 /** Load detailed selected geography only after the caller requests it. */
 export async function loadGuideDetailedData() {
     const [coastData, neighborhoodData, parkData, highwayData, roadData, bartData] = await Promise.all([
@@ -13,7 +14,7 @@ export async function loadGuideDetailedData() {
     const detailedHighways = highwayData.default;
     const detailedParks = parkData.default;
     const detailedStations = bartData.default;
-    return {
+    return deepFreeze({
         map: {
             coast: coastData.default.features[0].geometry,
             neighborhoods: detailedNeighborhoods.features.map((feature) => ({
@@ -41,5 +42,5 @@ export async function loadGuideDetailedData() {
                 : []),
         },
         neighborhoods: { realtor: detailedNeighborhoods },
-    };
+    });
 }

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

@@ -1,3 +1,7 @@
 import type { InteractiveSFMapElement, InteractiveSFMapOptions } from './interactive-data.js';
 /** Guide map preset: SFAR neighborhoods, major parks, BART, and curated roads. */
 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.
+ */
+export declare function mountGuideMap(shell: HTMLElement, options?: InteractiveSFMapOptions): InteractiveSFMapElement;

package/dist/src/guide-map.js

@@ -1,22 +1,47 @@
 import { guideMapData } from './guide-data.js';
 import { createInteractiveSFMapWithData } from './interactive-data.js';
+import { guideOptions } from './presets.js';
+import { validateExplorerOptions } from './validation.js';
 /** Guide map preset: SFAR neighborhoods, major parks, BART, and curated roads. */
 export function createGuideMap(options = {}) {
+    validateExplorerOptions(options);
     return createInteractiveSFMapWithData(guideMapData, {
         mode: 'neighborhoods',
         ...options,
         layers: {
-            districtFills: false,
-            districtLines: false,
-            districtLabels: false,
-            neighborhoodLines: true,
-            neighborhoodLabels: true,
-            landmarks: true,
-            bartStations: true,
-            highways: true,
-            keyRoads: true,
-            roadLabels: true,
+            ...guideOptions.layers,
             ...options.layers,
         },
     });
 }
+/** Enhance createGuideShell() in place with a fixed compact chrome layout.
+ * Keep an accessible external place list when hiding the native pickers.
+ */
+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 map = createGuideMap({
+        ...options,
+        attribution: 'compact',
+        controls: {
+            pan: false,
+            labels: false,
+            neighborhoodPicker: false,
+            markerPicker: false,
+            help: false,
+            status: false,
+            legend: true,
+            ...options.controls,
+        },
+    });
+    map.classList.add('sf-guide-frame');
+    map.querySelector('.sf-explorer-map-column > details')?.classList.add('sf-guide-sources');
+    frame.replaceWith(map);
+    return map;
+}

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

@@ -0,0 +1,2 @@
+/** Shared compact-embed geometry; keep server and mounted frames identical. */
+export declare const guideShellCSS = "\n.sf-guide-shell{max-width:1120px;margin:auto}\n.sf-guide-shell .sf-guide-frame{display:grid;grid-template-columns:minmax(0,1fr);grid-template-rows:64px auto auto 44px minmax(40px,auto);border:1px solid #cedae3;border-radius:14px;overflow:hidden;margin:0;max-width:none;font:14px/1.5 system-ui,sans-serif}\n.sf-guide-shell .sf-guide-frame[data-interface] .sf-explorer-body,.sf-guide-shell .sf-guide-frame .sf-explorer-map-column{display:contents}\n.sf-guide-shell .sf-explorer-toolbar{grid-row:1;flex-wrap:nowrap;overflow-x:auto;padding:8px;margin:0}\n.sf-guide-shell .sf-explorer-control-group{flex-wrap:nowrap;max-width:none;flex-shrink:0}\n.sf-guide-shell .sf-explorer-toolbar button{white-space:nowrap}\n.sf-guide-shell .sf-explorer-feature-controls{grid-row:2}\n.sf-guide-shell .sf-guide-placeholder:nth-child(3){grid-row:4}\n.sf-guide-shell .sf-explorer-canvas{grid-row:3;aspect-ratio:1;min-width:0}\n.sf-guide-shell .sf-explorer-canvas>svg{display:block;width:100%;height:100%}\n.sf-guide-shell .sf-explorer-legend{grid-row:4;flex-wrap:nowrap;overflow-x:auto;padding:10px 14px;align-items:center;margin:0}\n.sf-guide-shell .sf-guide-sources{grid-row:5;box-sizing:border-box;min-height:40px;padding:8px 14px;margin:0;font:12px/24px system-ui,sans-serif;background:#fff;color:#496578}\n.sf-guide-shell .sf-guide-placeholder{box-sizing:border-box;padding:12px 14px;background:#fff;color:#496578}\n";

package/dist/src/guide-shell.js

@@ -0,0 +1,16 @@
+/** Shared compact-embed geometry; keep server and mounted frames identical. */
+export const guideShellCSS = `
+.sf-guide-shell{max-width:1120px;margin:auto}
+.sf-guide-shell .sf-guide-frame{display:grid;grid-template-columns:minmax(0,1fr);grid-template-rows:64px auto auto 44px minmax(40px,auto);border:1px solid #cedae3;border-radius:14px;overflow:hidden;margin:0;max-width:none;font:14px/1.5 system-ui,sans-serif}
+.sf-guide-shell .sf-guide-frame[data-interface] .sf-explorer-body,.sf-guide-shell .sf-guide-frame .sf-explorer-map-column{display:contents}
+.sf-guide-shell .sf-explorer-toolbar{grid-row:1;flex-wrap:nowrap;overflow-x:auto;padding:8px;margin:0}
+.sf-guide-shell .sf-explorer-control-group{flex-wrap:nowrap;max-width:none;flex-shrink:0}
+.sf-guide-shell .sf-explorer-toolbar button{white-space:nowrap}
+.sf-guide-shell .sf-explorer-feature-controls{grid-row:2}
+.sf-guide-shell .sf-guide-placeholder:nth-child(3){grid-row:4}
+.sf-guide-shell .sf-explorer-canvas{grid-row:3;aspect-ratio:1;min-width:0}
+.sf-guide-shell .sf-explorer-canvas>svg{display:block;width:100%;height:100%}
+.sf-guide-shell .sf-explorer-legend{grid-row:4;flex-wrap:nowrap;overflow-x:auto;padding:10px 14px;align-items:center;margin:0}
+.sf-guide-shell .sf-guide-sources{grid-row:5;box-sizing:border-box;min-height:40px;padding:8px 14px;margin:0;font:12px/24px system-ui,sans-serif;background:#fff;color:#496578}
+.sf-guide-shell .sf-guide-placeholder{box-sizing:border-box;padding:12px 14px;background:#fff;color:#496578}
+`;

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

@@ -0,0 +1,9 @@
+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];
+    viewBox: [number, number, number, number];
+};
+/** Stable compact frame, progressively enhanced with mountGuideMap(). No browser globals. */
+export declare function createGuideShell(options?: SFMapOptions): string;

package/dist/src/guide-static.js

@@ -0,0 +1,26 @@
+import { guideMapData } from './guide-data.js';
+import { guideShellCSS } from './guide-shell.js';
+import { createSFMapWithData } from './map-core.js';
+/** Server-safe overview using exactly the guide browser geography. */
+export function createGuideSVG(options = {}) {
+    return createSFMapWithData({
+        theme: 'transit',
+        districtFills: false,
+        districtLines: false,
+        districtLabels: false,
+        neighborhoodLines: true,
+        landmarks: true,
+        highways: true,
+        keyRoads: true,
+        bartStations: true,
+        ...options,
+    }, guideMapData.map);
+}
+/** Stable compact frame, progressively enhanced with mountGuideMap(). No browser globals. */
+export function createGuideShell(options = {}) {
+    if ((options.width !== undefined && options.width !== 800) ||
+        (options.height !== undefined && options.height !== 800) ||
+        (options.padding !== undefined && options.padding !== 28))
+        throw new RangeError('Guide shells use the interactive 800 by 800 projection with 28 units of padding. Use createGuideSVG for custom dimensions.');
+    return `<div class="sf-guide-shell"><style>${guideShellCSS}</style><div class="sf-guide-frame"><div class="sf-guide-placeholder" aria-hidden="true">Map controls</div><div class="sf-explorer-canvas">${createGuideSVG(options).svg}</div><div class="sf-guide-placeholder" aria-hidden="true">Map legend</div><div class="sf-guide-sources">Map data · DataSF / BART</div></div></div>`;
+}

package/dist/src/guide.d.ts

@@ -1,5 +1,6 @@
 export type { InteractiveSFMapData } from './explorer-data.js';
 export { guideMapData } from './guide-data.js';
 export { loadGuideDetailedData } from './guide-detailed.js';
-export { createGuideMap } from './guide-map.js';
+export { createGuideMap, mountGuideMap } from './guide-map.js';
 export type { InteractiveSFMapElement, InteractiveSFMapOptions } from './interactive-data.js';
+export type { CameraOptions, MapFeatures, MapMarker } 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 } from './guide-map.js';
+export { createGuideMap, mountGuideMap } from './guide-map.js';

package/dist/src/interactive-data.d.ts

@@ -1,6 +1,6 @@
 import type { InteractiveSFMapData } from './explorer-data.js';
 import type { NeighborhoodExplorerOptions } from './types.js';
 export type { InteractiveSFMapData } from './explorer-data.js';
-export type { InteractiveLayers, MapPadding, MapViewport, NeighborhoodExplorerElement as InteractiveSFMapElement, NeighborhoodExplorerOptions as InteractiveSFMapOptions, NeighborhoodSelection, } from './types.js';
+export type { CameraOptions, InteractiveLayers, MapFeatures, MapMarker, MapPadding, MapViewport, NeighborhoodExplorerElement as InteractiveSFMapElement, NeighborhoodExplorerOptions as InteractiveSFMapOptions, NeighborhoodSelection, } from './types.js';
 /** Browser map shell that bundles only the geography supplied by the caller. */
 export declare function createInteractiveSFMapWithData(data: InteractiveSFMapData, options?: NeighborhoodExplorerOptions): import("./types.js").NeighborhoodExplorerElement;

package/dist/src/interactive-data.js

@@ -1,5 +1,7 @@
 import { createNeighborhoodExplorerCore } from './explorer-core.js';
+import { validateExplorerOptions } from './validation.js';
 /** Browser map shell that bundles only the geography supplied by the caller. */
 export function createInteractiveSFMapWithData(data, options = {}) {
+    validateExplorerOptions(options);
     return createNeighborhoodExplorerCore({ mode: 'basemap', ...options, interface: 'map' }, data);
 }

package/dist/src/interactive.d.ts

@@ -1,4 +1,4 @@
 import type { NeighborhoodExplorerOptions } from './types.js';
-export type { InteractiveLayers, MapOverlay, MapPadding, MapViewport, NeighborhoodExplorerElement as InteractiveSFMapElement, NeighborhoodExplorerOptions as InteractiveSFMapOptions, NeighborhoodSelection, } from './types.js';
+export type { CameraOptions, InteractiveLayers, MapFeatures, MapMarker, MapOverlay, MapPadding, MapViewport, NeighborhoodExplorerElement as InteractiveSFMapElement, NeighborhoodExplorerOptions as InteractiveSFMapOptions, NeighborhoodSelection, } from './types.js';
 /** Reusable browser map; plain basemap by default, no editorial UI or URL changes. */
 export declare function createInteractiveSFMap(options?: NeighborhoodExplorerOptions): import("./types.js").NeighborhoodExplorerElement;

package/dist/src/interactive.js

@@ -1,5 +1,7 @@
 import { createNeighborhoodExplorer } from './explorer.js';
+import { validateExplorerOptions } from './validation.js';
 /** Reusable browser map; plain basemap by default, no editorial UI or URL changes. */
 export function createInteractiveSFMap(options = {}) {
+    validateExplorerOptions(options);
     return createNeighborhoodExplorer({ mode: 'basemap', ...options, interface: 'map' });
 }

package/dist/src/layers.js

@@ -46,8 +46,10 @@ export function bartStations(items, { project, colors, labels }) {
 export function markers(items, { project, colors }) {
     return `<g data-layer="markers">${items
         .map((marker) => {
+        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);
-        return `<circle data-marker-id="${escapeXml(marker.id)}" cx="${x}" cy="${y}" r="${marker.selected ? 8 : 5}" fill="${escapeXml(marker.color ?? (marker.selected ? colors.selected : colors.marker))}" stroke="#fff9e9" stroke-width="2" vector-effect="non-scaling-stroke"><title>${escapeXml(marker.label ?? marker.id)}</title></circle>`;
+        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"><title>${escapeXml(marker.label ?? marker.id)}</title></circle>`;
     })
         .join('')}</g>`;
 }

package/dist/src/map-core.js

@@ -1,3 +1,4 @@
+import { validateMarkers, validateOverlays } from './validation.js';
 import { geometryPath, positions, rawProject } from './geometry.js';
 import * as layers from './layers.js';
 import { escapeXml, stroke } from './svg.js';
@@ -46,6 +47,8 @@ let sequence = 0;
 /** Make an offline SVG and the matching longitude/latitude projection. */
 export function createSFMapWithData(options, data) {
     const { theme = 'districts', width = 800, height = 800, padding = 28, year = 2022, districtLines = true, neighborhoodLines = false, districtFills = true, districtLabels = true, labels = true, highways = false, keyRoads = false, landmarks = false, bartStations = false, markers = [], title = 'San Francisco map', idPrefix = `sf-map-${++sequence}`, } = options;
+    validateMarkers(markers);
+    validateOverlays(options.overlays ?? []);
     const roadLabels = options.roadLabels ?? keyRoads;
     if (![width, height, padding].every(Number.isFinite) ||
         width <= 0 ||
@@ -113,14 +116,6 @@ export function createSFMapWithData(options, data) {
     if (bartStations)
         parts.push(layers.bartStations(stationData, context));
     for (const overlay of options.overlays ?? []) {
-        if (!overlay.id || !/^[A-Za-z0-9_-]+$/.test(overlay.id))
-            throw new TypeError('Overlay IDs must contain only letters, numbers, underscores, or hyphens.');
-        if (overlay.strokeWidth !== undefined &&
-            (!Number.isFinite(overlay.strokeWidth) || overlay.strokeWidth < 0))
-            throw new RangeError('Overlay strokeWidth must be a finite nonnegative number.');
-        if (overlay.fillOpacity !== undefined &&
-            (!Number.isFinite(overlay.fillOpacity) || overlay.fillOpacity < 0 || overlay.fillOpacity > 1))
-            throw new RangeError('Overlay fillOpacity must be a finite number from 0 to 1.');
         parts.push(`<path data-overlay-id="${escapeXml(overlay.id)}"${overlay.label ? ` aria-label="${escapeXml(overlay.label)}"` : ''} d="${path(overlay.geometry)}" fill="${escapeXml(overlay.fill ?? 'none')}" fill-opacity="${overlay.fillOpacity ?? 1}" stroke="${escapeXml(overlay.stroke ?? colors.road)}" stroke-width="${overlay.strokeWidth ?? 2}" vector-effect="non-scaling-stroke"${overlay.visible === false ? ' display="none"' : ''}/>`);
     }
     parts.push(layers.markers(markers, context), '</g></svg>');

package/dist/src/map.d.ts

@@ -0,0 +1,7 @@
+import type { MapController, MapOptions } from './controller-types.js';
+import { type InteractiveSFMapData } from './interactive-data.js';
+export type * from './controller-types.js';
+export type { InteractiveSFMapData as MapData } from './explorer-data.js';
+export type { CameraOptions, InteractiveLayers, MapFeatures, MapMarker, MapOverlay, MapPadding, MapViewport, NeighborhoodSelection, } 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

@@ -0,0 +1,106 @@
+import { validateCameraOptions } from './camera.js';
+import { expandMapOptions, prepareConfiguration } from './configuration.js';
+import { controlKeys, layerKeys } from './features.js';
+import { createInteractiveSFMapWithData } from './interactive-data.js';
+import { assertOptions } from './validation.js';
+/** No geography is imported. Supply a preset or your own immutable data. */
+export function createMap(data, options = {}) {
+    const expanded = expandMapOptions(options);
+    let config = prepareConfiguration({ features: {}, layers: {}, controls: {} }, {
+        features: options.features,
+        layers: options.layers,
+        controls: options.controls,
+    });
+    const element = createInteractiveSFMapWithData(data, {
+        ...expanded,
+        onOverlayActivate: () => { },
+    });
+    const subscriptions = new Set();
+    let destroyed = false;
+    function active() {
+        if (destroyed)
+            throw new Error('Map controller has been destroyed.');
+    }
+    const use = (fn) => (...args) => {
+        active();
+        return fn(...args);
+    };
+    const camera = Object.freeze({
+        get: use(element.getViewport),
+        set: use(element.setViewport),
+        stop: use(element.stopAnimation),
+        pan: use(element.panBy),
+        zoom: use(element.zoomBy),
+        reset: use(element.resetView),
+        fit: use((geometry, fitOptions = {}) => {
+            assertOptions(fitOptions, 'fit', ['padding', 'animate', 'duration']);
+            const { padding, ...motion } = fitOptions;
+            validateCameraOptions(motion);
+            element.fitGeometry(geometry, padding, motion);
+        }),
+    });
+    return Object.freeze({
+        element,
+        overlayElement: element.overlayElement,
+        camera,
+        get destroyed() {
+            return destroyed;
+        },
+        configure: use((patch) => {
+            const next = prepareConfiguration(config, patch);
+            // Full switch patches are needed so removed overrides reset engine defaults.
+            const layers = Object.fromEntries(layerKeys.map((key) => [key, next.layers[key]]));
+            const controls = Object.fromEntries(controlKeys.map((key) => [key, next.controls[key]]));
+            if ('features' in patch)
+                element.setFeatures(patch.features ?? next.features);
+            if ('layers' in patch)
+                element.setLayers(layers);
+            if ('controls' in patch)
+                element.setControls(controls);
+            config = next;
+        }),
+        getConfiguration: use(() => structuredClone(config)),
+        on: use((type, listener) => {
+            if (![
+                'markerchange',
+                'neighborhoodchange',
+                'overlayactivate',
+                'clusteractivate',
+                'viewportchange',
+                'mapresize',
+            ].includes(type) ||
+                typeof listener !== 'function')
+                throw new TypeError('Expected a supported map event and listener.');
+            const handle = (event) => {
+                if (event.target === element)
+                    listener(structuredClone(event.detail ?? undefined));
+            };
+            element.addEventListener(type, handle);
+            const unsubscribe = () => {
+                element.removeEventListener(type, handle);
+                subscriptions.delete(unsubscribe);
+            };
+            subscriptions.add(unsubscribe);
+            return unsubscribe;
+        }),
+        setMarkers: use(element.setMarkers),
+        setOverlays: use(element.setOverlays),
+        selectMarker: use(element.selectMarker),
+        getSelectedMarker: use(element.getSelectedMarker),
+        selectNeighborhood: use(element.selectNeighborhood),
+        getSelectedNeighborhood: use(element.getSelection),
+        setSource: use(element.setSource),
+        setMode: use(element.setMode),
+        setLabels: use(element.setLabels),
+        setTouchNavigation: use(element.setTouchNavigation),
+        projectToScreen: use(element.projectToScreen),
+        destroy() {
+            if (destroyed)
+                return;
+            destroyed = true;
+            for (const unsubscribe of subscriptions)
+                unsubscribe();
+            element.destroy();
+        },
+    });
+}

package/dist/src/presets.d.ts

@@ -0,0 +1,3 @@
+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>;

package/dist/src/presets.js

@@ -0,0 +1,17 @@
+import { deepFreeze } from './immutable.js';
+/** Configuration only: pair with guide/data or a compatible caller-supplied dataset. */
+export const guideOptions = deepFreeze({
+    mode: 'neighborhoods',
+    layers: {
+        districtFills: false,
+        districtLines: false,
+        districtLabels: false,
+        neighborhoodLines: true,
+        neighborhoodLabels: true,
+        landmarks: true,
+        bartStations: true,
+        highways: true,
+        keyRoads: true,
+        roadLabels: true,
+    },
+});

package/dist/src/static.d.ts

@@ -0,0 +1,10 @@
+import { type SFMapData } from './map-core.js';
+import type { SFMapOptions } from './types.js';
+export type { SFMapData as StaticMapData } from './map-core.js';
+export type { SFMapOptions as StaticMapOptions } from './types.js';
+/** Server-safe SVG rendering with explicit data; returns SVG plus projection helpers. */
+export declare function renderMap(data: SFMapData, options?: SFMapOptions): {
+    svg: string;
+    project: (coordinates: import("../data/types.js").Position) => [number, number];
+    viewBox: [number, number, number, number];
+};

package/dist/src/static.js

@@ -0,0 +1,5 @@
+import { createSFMapWithData } from './map-core.js';
+/** Server-safe SVG rendering with explicit data; returns SVG plus projection helpers. */
+export function renderMap(data, options = {}) {
+    return createSFMapWithData(options, data);
+}