@kahwee/sf-map-svg 4.1.0 → 4.2.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 User-visible changes are recorded here. Unreleased entries describe changes on `main` that are not part of a tagged package release.
 
+## Unreleased
+
+## 4.2.0 — 2026-10-01
+
+- Reuse one native dropdown treatment across Pages, with an inset chevron, a reserved end gutter, and preserved labels, keyboard behavior, and mobile pickers.
+- Strengthen the playground with strict TypeScript, checked JavaScript/TypeScript snippets, versioned design links, persistent explicit layer choices and independent static rendering. Keep mobile controls unobstructed and picker labels legible in dark mode.
+- Express explicit configuration resets for consumers using `exactOptionalPropertyTypes`, including nested appearance tokens. Make Pages API and guide references describe their actual package version without internal preview warnings.
+
+- Share grouped `layers` and supported `appearance` options between static and interactive maps, retaining flat static options and existing defaults; accept readonly static marker arrays.
+- Update interactive appearance, mode, source, district year and labels through `configure`, preserving camera and retained marker nodes. Merge appearance tokens by key and validate combined patches before commit.
+- Add `getResolvedConfiguration()` and `getCapabilities()` for effective layer switches and supplied geography, plus an additive `selectionchange` event with consistent current/previous snapshots.
+- Add a live Pages map design playground with six editable palettes, layers, typography, sample pins/routes, browser/static previews, undo/redo, shareable designs, copyable code and full-city SVG export. Keep released-package previews compatible with their installed API.
+- Refresh the Pages site: a new SF Map SVG mark traced from the real coastline, a reframed header with a release link, card-style reference tables that no longer collapse, a live filter for the API reference, an aligned playground with one-row-per-colour inks, and 12px minimum type for labels and badges.
+
 ## 4.1.0 — 2026-10-01
 
 - Validate canonical and generated GeoJSON during data checks, rejecting invalid WGS84 coordinates and malformed polygon rings before release.

package/README.md

@@ -2,7 +2,7 @@
 
 Offline, self-contained San Francisco SVG maps. The package has no runtime dependencies. Geography is always an explicit import; the root entry does not bundle data.
 
-[Live examples](https://kahwee.github.io/sf-map-svg/examples.html) · [Storybook source](stories/) · [Geographic sources](SOURCES.md) · [v3 migration](docs/migration-v3.md)
+[Design playground](https://kahwee.github.io/sf-map-svg/playground.html) · [Live examples](https://kahwee.github.io/sf-map-svg/examples.html) · [Storybook source](stories/) · [Geographic sources](SOURCES.md) · [v3 migration](docs/migration-v3.md)
 
 ## Install
 
@@ -52,7 +52,7 @@ map.camera.zoom(1.5);
 map.destroy();
 ```
 
-`createMap(data, options)` returns a controller. Use `map.element` for mounting, `map.configure({ features, layers, controls })` for runtime switches, `map.camera` for pan/zoom/fit/reset, and `map.on()` for typed events. Appearance is set at construction. SFAR realtor neighborhoods are the default when supplied; SF Find and analysis are explicit alternate sources. The `/data/full` preset includes all three collections and historical districts.
+`createMap(data, options)` returns a controller. Use `map.element` for mounting, `map.configure({ features, layers, controls, appearance, mode, source, year, labels })` for runtime switches, `map.camera` for pan/zoom/fit/reset, and `map.on()` for typed events. Appearance can change live while preserving camera, selection, and focus. `getResolvedConfiguration()` explains effective layers; `getCapabilities()` reports supplied geography. SFAR realtor neighborhoods are the default when supplied; SF Find and analysis are explicit alternate sources. The `/data/full` preset includes all three collections and historical districts.
 
 See [controller options, events, and lifecycle](docs/API.md#interactive-maps),
 [examples](docs/EXAMPLES.md), and [consumer integration](docs/consumer-integration.md).

package/dist/src/appearance.d.ts

@@ -0,0 +1,5 @@
+import type { MapAppearance } from './controller-types.js';
+export declare const appearanceKeys: readonly ['theme', 'colors', 'labelStyle', 'areaStyle', 'districtStyle', 'labelSize', 'style', 'markerRadius', 'markerHitSize', 'markerColor', 'selectedMarkerColor'];
+/** Copy configuration records without cloning or invoking styling callbacks. */
+export declare function copyAppearance(value?: MapAppearance): MapAppearance;
+export declare function prepareAppearance(current: MapAppearance, patch: MapAppearance | undefined): MapAppearance;

package/dist/src/appearance.js

@@ -0,0 +1,54 @@
+import { assertOptions, validateExplorerOptions } from './validation.js';
+export const appearanceKeys = [
+    'theme',
+    'colors',
+    'labelStyle',
+    'areaStyle',
+    'districtStyle',
+    'labelSize',
+    'style',
+    'markerRadius',
+    'markerHitSize',
+    'markerColor',
+    'selectedMarkerColor',
+];
+/** Copy configuration records without cloning or invoking styling callbacks. */
+export function copyAppearance(value = {}) {
+    const { districtStyle, ...rest } = value;
+    return { ...structuredClone(rest), ...(districtStyle ? { districtStyle } : {}) };
+}
+export function prepareAppearance(current, patch) {
+    if (patch === undefined)
+        return {};
+    assertOptions(patch, 'appearance', appearanceKeys);
+    const next = { ...current, ...patch };
+    for (const key of ['colors', 'labelStyle', 'areaStyle', 'labelSize', 'style']) {
+        if (Object.hasOwn(patch, key) && patch[key] !== undefined) {
+            assertOptions(patch[key], key);
+            const tokens = { ...current[key], ...patch[key] };
+            for (const name of Object.keys(tokens))
+                if (tokens[name] === undefined)
+                    delete tokens[name];
+            Object.assign(next, { [key]: tokens });
+        }
+    }
+    for (const key of appearanceKeys)
+        if (next[key] === undefined)
+            delete next[key];
+    validateExplorerOptions(next);
+    if (next.theme !== undefined && !['districts', 'transit'].includes(next.theme))
+        throw new TypeError('Theme must be districts or transit.');
+    const min = next.labelSize?.min ?? 11, max = next.labelSize?.max ?? 12;
+    const radius = next.markerRadius ?? 6, hit = next.markerHitSize ?? 44;
+    if (![min, max, radius, hit].every(Number.isFinite) ||
+        min < 8 ||
+        max < min ||
+        max > 32 ||
+        radius <= 0 ||
+        hit < radius * 2)
+        throw new RangeError('Use label sizes from 8–32px and a positive marker radius inside its hit target.');
+    const weight = next.labelStyle?.fontWeight;
+    if (weight !== undefined && (!Number.isFinite(weight) || weight < 1 || weight > 1000))
+        throw new RangeError('Label font weight must be finite and between 1 and 1000.');
+    return copyAppearance(next);
+}

package/dist/src/configuration.js

@@ -1,18 +1,6 @@
+import { appearanceKeys, copyAppearance, prepareAppearance } from './appearance.js';
 import { controlKeys, layerKeys, normalizeFeatures, validateSwitchPatch } from './features.js';
 import { assertOptions, validateExplorerOptions } from './validation.js';
-const appearanceKeys = [
-    'theme',
-    'colors',
-    'labelStyle',
-    'areaStyle',
-    'districtStyle',
-    'labelSize',
-    'style',
-    'markerRadius',
-    'markerHitSize',
-    'markerColor',
-    'selectedMarkerColor',
-];
 const featureKeys = [
     'motion',
     'markerEntrance',
@@ -48,18 +36,34 @@ export function expandMapOptions(options) {
                     ? `Use ${replacement} instead of the flat ${key} option.`
                     : 'interface is internal and is not a supported createMap option.');
         }
-    if (options.appearance !== undefined)
-        assertOptions(options.appearance, 'appearance', appearanceKeys);
+    const preparedAppearance = options.appearance === undefined ? undefined : prepareAppearance({}, options.appearance);
     if (options.features !== undefined)
         normalizeFeatures(options.features);
-    const { features, appearance, ...rest } = options;
-    const expanded = { ...rest, ...appearance, ...features };
+    const { features, appearance: _appearance, ...rest } = options;
+    const expanded = { ...rest, ...preparedAppearance, ...features };
     validateExplorerOptions(expanded);
     return expanded;
 }
 /** Prepare the entire configuration before any DOM mutation. */
 export function prepareConfiguration(current, patch) {
-    assertOptions(patch, 'configuration', ['features', 'layers', 'controls']);
+    assertOptions(patch, 'configuration', [
+        'features',
+        'layers',
+        'controls',
+        'appearance',
+        'mode',
+        'source',
+        'year',
+        'labels',
+    ]);
+    if (patch.mode !== undefined && !['basemap', 'neighborhoods', 'districts'].includes(patch.mode))
+        throw new RangeError('Unknown map mode.');
+    if (patch.source !== undefined && !['realtor', 'sf-find', 'analysis'].includes(patch.source))
+        throw new RangeError('Unknown neighborhood source.');
+    if (patch.year !== undefined && ![2002, 2012, 2022].includes(patch.year))
+        throw new RangeError('District year must be 2002, 2012, or 2022.');
+    if (patch.labels !== undefined && typeof patch.labels !== 'boolean')
+        throw new TypeError('Labels must be a boolean.');
     const features = 'features' in patch
         ? normalizeFeatures(patch.features === undefined
             ? {}
@@ -78,11 +82,16 @@ export function prepareConfiguration(current, patch) {
                 delete next[property];
         return next;
     };
-    return structuredClone({
-        features,
-        layers: switches('layers', current.layers, layerKeys),
-        controls: switches('controls', current.controls, controlKeys),
-    });
+    return {
+        ...structuredClone({
+            features,
+            layers: switches('layers', current.layers, layerKeys),
+            controls: switches('controls', current.controls, controlKeys),
+        }),
+        appearance: 'appearance' in patch
+            ? prepareAppearance(current.appearance ?? {}, patch.appearance)
+            : copyAppearance(current.appearance),
+    };
 }
 function checkedFeatures(value) {
     normalizeFeatures(value);

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

@@ -1,24 +1,66 @@
 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';
-export type MapAppearance = Pick<NeighborhoodExplorerOptions, 'theme' | 'colors' | 'labelStyle' | 'areaStyle' | 'districtStyle' | 'labelSize' | 'style' | 'markerRadius' | 'markerHitSize' | 'markerColor' | 'selectedMarkerColor'>;
+/** Patch properties can explicitly remove overrides, including with exactOptionalPropertyTypes. */
+type Resettable<T> = {
+    [K in keyof T]?: T[K] | undefined;
+};
+type AppearanceOptions = Pick<NeighborhoodExplorerOptions, 'theme' | 'colors' | 'labelStyle' | 'areaStyle' | 'districtStyle' | 'labelSize' | 'style' | 'markerRadius' | 'markerHitSize' | 'markerColor' | 'selectedMarkerColor'>;
+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 groups/keys retain their values; undefined groups reset all keys in that group. */
+/** Omitted keys retain values. Undefined presentation groups reset; undefined mode/source/year/labels retain their current value. */
 export interface MapConfiguration {
-    features?: MapFeatures;
-    layers?: InteractiveLayers;
-    controls?: MapControls;
+    features?: Resettable<MapFeatures> | undefined;
+    layers?: Resettable<InteractiveLayers> | undefined;
+    controls?: Resettable<MapControls> | undefined;
+    appearance?: MapAppearance | undefined;
+    mode?: NonNullable<NeighborhoodExplorerOptions['mode']> | undefined;
+    source?: NeighborhoodSource | undefined;
+    year?: DistrictYear | undefined;
+    labels?: boolean | undefined;
 }
 export interface MapOptions extends Omit<NeighborhoodExplorerOptions, keyof MapFeatures | keyof MapAppearance | 'interface' | 'onMarkerActivate' | 'onOverlayActivate'> {
     features?: MapFeatures;
-    appearance?: MapAppearance;
+    appearance?: MapAppearance | undefined;
 }
 export interface MapConfigurationSnapshot {
     features: MapFeatures;
     /** Explicit overrides; absent values continue to follow the current mode. */
     layers: InteractiveLayers;
     controls: MapControls;
+    appearance: MapAppearance;
+}
+export interface MapCapabilities {
+    sources: readonly NeighborhoodSource[];
+    years: readonly DistrictYear[];
+    /** Data availability, independent of requested layer visibility. */
+    layers: Readonly<Record<keyof InteractiveLayers, boolean>>;
+}
+export interface ResolvedMapConfiguration extends MapConfigurationSnapshot {
+    mode: NonNullable<MapOptions['mode']>;
+    source: NeighborhoodSource;
+    year: DistrictYear;
+    labels: boolean;
+    /** Effective switches after mode defaults and data availability; label switches honor labels. */
+    layers: Record<keyof InteractiveLayers, boolean>;
 }
+export type MapSelectionChange = {
+    kind: 'marker';
+    current: MapMarker | null;
+    previous: MapMarker | null;
+} | {
+    kind: 'neighborhood';
+    current: NeighborhoodSelection | null;
+    previous: NeighborhoodSelection | null;
+} | {
+    kind: 'district';
+    current: DistrictSelection | null;
+    previous: DistrictSelection | null;
+};
 export interface MapEvents {
+    /** Common selection envelope; existing change events retain their payloads. */
+    selectionchange: MapSelectionChange;
     districtchange: DistrictSelection | {
         id: null;
         year: DistrictYear;
@@ -56,11 +98,13 @@ export interface MapEvents {
     mapresize: undefined;
 }
 export interface MapCamera {
+    /** Fixed 800 × 800 projected space, not longitude/latitude. */
     get(): MapViewport;
     set(view: MapViewport, options?: CameraOptions): void;
     fit(geometry: Geometry, options?: CameraOptions & {
         padding?: number | MapPadding;
     }): void;
+    /** Delta in projected map units. */
     pan(x: number, y: number, options?: CameraOptions): void;
     zoom(factor: number, options?: CameraOptions): void;
     reset(options?: CameraOptions): void;
@@ -74,6 +118,8 @@ export interface MapController {
     readonly destroyed: boolean;
     configure(patch: MapConfiguration): void;
     getConfiguration(): MapConfigurationSnapshot;
+    getResolvedConfiguration(): ResolvedMapConfiguration;
+    getCapabilities(): MapCapabilities;
     on<K extends keyof MapEvents>(type: K, listener: (detail: MapEvents[K]) => void): () => void;
     /** Reconcile stable IDs; retained markers preserve nodes, focus, and entrance animations. */
     setMarkers(markers: readonly MapMarker[]): void;
@@ -104,3 +150,4 @@ export interface MapController {
     /** Idempotent; stops work and managed subscriptions. Does not remove host-owned DOM. */
     destroy(): void;
 }
+export {};

package/dist/src/explorer-core.d.ts

@@ -1,5 +1,17 @@
+import type { NeighborhoodSource } from '../data/types.js';
+import type { MapConfiguration } from './controller-types.js';
 import type { InteractiveSFMapData } from './explorer-data.js';
-import type { NeighborhoodExplorerElement, NeighborhoodExplorerOptions } from './types.js';
+import type { DistrictYear, ExplorerMode, NeighborhoodExplorerElement, NeighborhoodExplorerOptions } from './types.js';
 export type { ExplorerMode, NeighborhoodExplorerElement, NeighborhoodExplorerOptions, } from './types.js';
+/** Private bridge between the renderer and its public lifecycle controller. */
+type MapEngineElement = NeighborhoodExplorerElement & {
+    applyPresentation(patch: MapConfiguration, onCommit?: () => void, isCurrent?: () => boolean): boolean;
+    getMapState(): {
+        mode: ExplorerMode;
+        source: NeighborhoodSource;
+        year: DistrictYear;
+        labels: boolean;
+    };
+};
 /** Create an offline, browser-only neighborhood explorer. Call destroy() before disposal. */
-export declare function createNeighborhoodExplorerCore(options: NeighborhoodExplorerOptions | undefined, data: InteractiveSFMapData): NeighborhoodExplorerElement;
+export declare function createNeighborhoodExplorerCore(options: NeighborhoodExplorerOptions | undefined, data: InteractiveSFMapData): MapEngineElement;

package/dist/src/explorer-core.js

@@ -1,3 +1,4 @@
+import { copyAppearance } from './appearance.js';
 import { createCamera, validateCameraOptions } from './camera.js';
 import { clusterPoints } from './clusters.js';
 import { renderDistrictAppearance } from './district-layer.js';
@@ -11,7 +12,7 @@ import { createFrameScheduler } from './frame-scheduler.js';
 import { geometryPath } from './geometry.js';
 import { createLabelRenderer } from './label-renderer.js';
 import { createLayerTransitions } from './layer-transition.js';
-import { createSFMapWithData, districtColors, getLayerPathsWithData } from './map-core.js';
+import { createSFMapWithData, districtColors, getLayerPathsWithData, resolveMapColors, } from './map-core.js';
 import { createMarkerLayer } from './marker-layer.js';
 import { attachNavigation } from './navigation.js';
 import { validateExplorerOptions, validateMarkers, validateOverlays } from './validation.js';
@@ -37,7 +38,7 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
         throw new RangeError(`Unknown map mode: ${mode}`);
     if (chrome !== 'explorer' && chrome !== 'map')
         throw new RangeError('Unknown interface.');
-    const minLabelSize = labelSize.min ?? 11, maxLabelSize = labelSize.max ?? 12;
+    let minLabelSize = labelSize.min ?? 11, maxLabelSize = labelSize.max ?? 12;
     if (![minLabelSize, maxLabelSize, markerRadius, markerHitSize].every(Number.isFinite) ||
         minLabelSize < 8 ||
         maxLabelSize < minLabelSize ||
@@ -464,7 +465,7 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
             districtTransition.fade(fills, fade);
         updateDistrictAppearance();
     }
-    function setDistrictYear(next, options = {}) {
+    function setDistrictYear(next, options = {}, preparedStyles) {
         if (destroyed)
             return;
         validateCameraOptions(options);
@@ -475,7 +476,7 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
         if (next === year)
             return;
         const revision = districtRevision;
-        const prepared = prepareDistrictStyles(data.map.districts[next], districtStyle);
+        const prepared = preparedStyles ?? prepareDistrictStyles(data.map.districts[next], districtStyle);
         if (destroyed || revision !== districtRevision)
             return;
         const committedRevision = ++districtRevision;
@@ -1118,9 +1119,7 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
             moveView(target, options);
         return true;
     }
-    function setSource(next) {
-        if (destroyed)
-            return;
+    function prepareSource(next, reset = true) {
         if (!Object.hasOwn(collections, next))
             throw new RangeError(`Unknown neighborhood source: ${next}`);
         const collection = collections[next];
@@ -1191,36 +1190,42 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
                 area: (bounds[2] - bounds[0]) * (bounds[3] - bounds[1]),
             };
         });
-        const hadSelection = !!selected;
-        source = next;
-        sourceSelect.value = source;
-        selected = undefined;
-        const revision = ++neighborhoodRevision;
-        delete root.dataset.selectedNeighborhood;
-        root.dataset.source = source;
-        layerFades.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');
-        updateResults();
-        updateDetail();
-        updateComposition();
-        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 (!destroyed && neighborhoodRevision === revision)
-            resetView();
+        return () => {
+            const hadSelection = !!selected;
+            source = next;
+            sourceSelect.value = source;
+            selected = undefined;
+            const revision = ++neighborhoodRevision;
+            delete root.dataset.selectedNeighborhood;
+            root.dataset.source = source;
+            layerFades.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');
+            updateResults();
+            updateDetail();
+            updateComposition();
+            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 && !destroyed && neighborhoodRevision === revision)
+                resetView();
+        };
+    }
+    function setSource(next) {
+        if (!destroyed)
+            prepareSource(next)();
     }
     function syncFeatureControls() {
         featureControls.hidden = neighborhoodLabel.hidden && markerLabel.hidden;
@@ -1653,7 +1658,133 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
         scheduleLabels();
         root.dispatchEvent(new CustomEvent('mapresize', { bubbles: true }));
     };
+    let presentationRevision = 0;
+    function applyPresentation(patch, onCommit, isCurrent = () => true) {
+        const revision = ++presentationRevision;
+        const nextYear = patch.year ?? year;
+        const nextMode = patch.mode ?? mode;
+        if ((patch.year !== undefined || nextMode === 'districts') &&
+            (!data.map.districts?.[nextYear] || !data.districts?.[nextYear]))
+            throw new RangeError(`No ${nextYear} district dataset was supplied.`);
+        if (nextMode === 'neighborhoods' && !sources.length)
+            throw new RangeError('No neighborhood dataset was supplied.');
+        const commitSource = patch.source !== undefined && patch.source !== source
+            ? prepareSource(patch.source, false)
+            : undefined;
+        const appearance = patch.appearance;
+        const nextStyle = appearance ? appearance.districtStyle : districtStyle;
+        const districtVersion = districtRevision;
+        const prepared = appearance || nextYear !== year
+            ? prepareDistrictStyles(data.map.districts?.[nextYear] ?? [], nextStyle)
+            : districtStyles;
+        if (destroyed ||
+            !isCurrent() ||
+            revision !== presentationRevision ||
+            districtVersion !== districtRevision)
+            return false;
+        if (nextYear !== year) {
+            // Validate target paths and label coordinates before any presentation group commits.
+            getLayerPathsWithData({ year: nextYear }, data.map, false);
+            for (const feature of data.districts?.[nextYear]?.features ?? [])
+                for (const point of feature.properties.labelPoints)
+                    map.project(point);
+        }
+        onCommit?.();
+        if (appearance) {
+            districtRevision++;
+            const next = copyAppearance(appearance);
+            theme = next.theme ?? 'transit';
+            colors = next.colors ?? {};
+            labelStyle = next.labelStyle ?? {};
+            areaStyle = next.areaStyle ?? {};
+            styleOptions = next.style ?? {};
+            minLabelSize = next.labelSize?.min ?? 11;
+            maxLabelSize = next.labelSize?.max ?? 12;
+            markerRadius = next.markerRadius ?? 6;
+            markerHitSize = next.markerHitSize ?? 44;
+            markerColor = next.markerColor ?? colors.marker ?? '#245b61';
+            selectedMarkerColor = next.selectedMarkerColor ?? colors.selected ?? '#f04f32';
+            districtTransition.cancel();
+            const fills = districtLayers.find((layer) => layer.dataset.layer === 'district-fills');
+            const fade = layerFades.duration();
+            const stylesChanged = nextStyle !== districtStyle ||
+                [...prepared].some(([id, value]) => ['fill', 'stroke', 'opacity'].some((key) => value[key] !== districtStyles.get(id)?.[key]));
+            if (fills && fade && enabled('districtFills') && nextYear === year && stylesChanged)
+                districtTransition.fade(fills, fade);
+            districtStyle = nextStyle;
+            districtStyles = prepared;
+            const palette = resolveMapColors(theme, colors);
+            svg.querySelector('rect')?.setAttribute('fill', palette.water);
+            svg.querySelector('[data-layer="coast"]')?.setAttribute('fill', palette.land);
+            svg.querySelector('[data-layer="coastline"]')?.setAttribute('stroke', palette.district);
+            for (const [layer, color] of [
+                ['landmarks', palette.park],
+                ['highways', palette.highway],
+                ['key-roads', palette.road],
+            ])
+                for (const node of svg.querySelectorAll(`[data-layer="${layer}"] path`)) {
+                    node.setAttribute(layer === 'landmarks' ? 'fill' : 'stroke', color);
+                    if (layer === 'highways')
+                        node.setAttribute('stroke-width', theme === 'transit' ? '2' : '1.4');
+                }
+            for (const [token, fallback, name] of [
+                ['ink', '#18364f', 'ink'],
+                ['surface', '#fff', 'surface'],
+                ['accent', '#163d61', 'accent'],
+                ['border', '#cedae3', 'border'],
+                ['focus', '#1676b8', 'focus'],
+                ['controlGap', '6px', 'control-gap'],
+                ['font', 'system-ui,sans-serif', 'font'],
+            ])
+                root.style.setProperty(`--sf-map-${name}`, styleOptions[token] ?? fallback);
+            labelLayer.setAttribute('font-family', labelStyle.fontFamily ?? styleOptions.font ?? 'system-ui,sans-serif');
+            labelRenderer.invalidateMetrics();
+            for (const station of stationItems)
+                station.node.setAttribute('stroke', colors.bart ?? '#0073ae');
+            for (const kind of ['bart', 'park', 'highway', 'road']) {
+                const symbol = legend.querySelector(`.sf-explorer-legend-${kind}`);
+                if (symbol) {
+                    symbol.style.removeProperty(kind === 'bart' ? 'border-color' : 'background-color');
+                    if (colors[kind])
+                        symbol.style.setProperty(kind === 'bart' ? 'border-color' : 'background-color', colors[kind]);
+                }
+            }
+            for (const item of items) {
+                const active = item.feature === selected;
+                item.node.setAttribute('fill', active ? (areaStyle.selectedFill ?? '#408dbe') : 'transparent');
+                item.node.setAttribute('stroke', active ? (areaStyle.selectedStroke ?? '#176ba2') : (colors.neighborhood ?? '#9caebc'));
+            }
+            for (const item of markerItems) {
+                item.dot.setAttribute('fill', item.marker.id === selectedMarker
+                    ? selectedMarkerColor
+                    : (item.marker.color ?? markerColor));
+                item.ring.setAttribute('stroke', features.selectedMarkerRing
+                    ? (features.selectedMarkerRing.color ?? selectedMarkerColor)
+                    : selectedMarkerColor);
+            }
+            invalidateClusters();
+            updateDistrictAppearance();
+        }
+        if (nextYear !== year)
+            setDistrictYear(nextYear, {}, prepared);
+        if (destroyed || revision !== presentationRevision || !isCurrent())
+            return false;
+        commitSource?.();
+        if (destroyed || revision !== presentationRevision || !isCurrent())
+            return false;
+        if (commitSource && appearance)
+            for (const item of items)
+                item.node.setAttribute('stroke', colors.neighborhood ?? '#9caebc');
+        if (patch.mode !== undefined)
+            setMode(patch.mode, false);
+        if (patch.labels !== undefined)
+            setLabels(patch.labels);
+        scheduleLabels();
+        return true;
+    }
     const explorer = Object.assign(root, {
+        applyPresentation,
+        getMapState: () => ({ mode, source, year, labels }),
         selectNeighborhood,
         getSelection,
         selectDistrict,

package/dist/src/guide-map.js

@@ -6,7 +6,7 @@ import { guideOptions } from './presets.js';
 import { validateExplorerOptions } from './validation.js';
 function controllerOptions(options) {
     expandMapOptions(options);
-    const config = prepareConfiguration({ features: {}, layers: guideOptions.layers ?? {}, controls: {} }, {
+    const config = prepareConfiguration({ features: {}, layers: guideOptions.layers ?? {}, controls: {}, appearance: {} }, {
         features: options.features,
         layers: options.layers === undefined ? {} : options.layers,
         controls: options.controls,

package/dist/src/guide-static.js

@@ -1,9 +1,9 @@
 import { guideMapData } from './guide-data.js';
 import { guideShellCSS } from './guide-shell.js';
-import { createSFMapWithData } from './map-core.js';
+import { renderMap } from './static.js';
 /** Server-safe overview using exactly the guide browser geography. */
 export function createGuideSVG(options = {}) {
-    return createSFMapWithData({
+    return renderMap(guideMapData.map, {
         theme: 'transit',
         districtFills: false,
         districtLines: false,
@@ -14,7 +14,7 @@ export function createGuideSVG(options = {}) {
         keyRoads: true,
         bartStations: true,
         ...options,
-    }, guideMapData.map);
+    });
 }
 /** Stable compact frame, progressively enhanced with mountGuideMap(). No browser globals. */
 export function createGuideShell(options = {}) {

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

@@ -80,6 +80,20 @@ export declare function getLayerPathsWithData(options: SFMapOptions, data: SFMap
         point: [number, number];
     }[];
 };
+export declare function resolveMapColors(theme: SFMapOptions['theme'], colors?: SFMapOptions['colors']): {
+    water: string;
+    land: string;
+    district: string;
+    neighborhood: string;
+    highway: string;
+    road: string;
+    park: string;
+    landmark: string;
+    bart: string;
+    label: string;
+    marker: string;
+    selected: string;
+};
 /** Make an offline SVG and the matching longitude/latitude projection. */
 export declare function createSFMapWithData(options: SFMapOptions, data: SFMapData): {
     svg: string;

package/dist/src/map-core.js

@@ -104,6 +104,9 @@ const transitColors = {
     marker: '#0073ae',
     selected: '#0073ae',
 };
+export function resolveMapColors(theme, colors = {}) {
+    return { ...defaults, ...(theme === 'transit' ? transitColors : {}), ...colors };
+}
 let sequence = 0;
 /** Make an offline SVG and the matching longitude/latitude projection. */
 export function createSFMapWithData(options, data) {
@@ -115,7 +118,7 @@ export function createSFMapWithData(options, data) {
         throw new TypeError('idPrefix must start with a letter and contain only letters, numbers, underscores, or hyphens.');
     if (theme !== 'districts' && theme !== 'transit')
         throw new TypeError('Theme must be districts or transit.');
-    const colors = { ...defaults, ...(theme === 'transit' ? transitColors : {}), ...options.colors };
+    const colors = resolveMapColors(theme, options.colors);
     const animation = normalizeStaticAnimation(options.animation);
     const animated = animation !== null;
     const geometry = getLayerPathsWithData(options, data, false);