@kahwee/sf-map-svg 1.5.2 → 2.0.0

package/CHANGELOG.md

@@ -4,6 +4,46 @@ User-visible changes are recorded here. Unreleased entries describe changes on `
 
 ## Unreleased
 
+## 2.0.0 — 2026-09-27
+
+Version 2 makes geography an explicit dependency and separates the application API
+from its DOM element. This keeps small consumers small, gives configuration one
+consistent home, and makes animation and subscription ownership predictable.
+
+**Migration:** [Complete v1 → v2 guide, with before/after examples](https://github.com/kahwee/sf-map-svg/blob/v2.0.0/docs/migration-v2.md).
+**API:** [README](https://github.com/kahwee/sf-map-svg/blob/v2.0.0/README.md).
+**Consumer performance:** [Integration guide](https://github.com/kahwee/sf-map-svg/blob/v2.0.0/docs/consumer-integration.md).
+
+### Breaking changes
+
+- The root export now provides data-free `createMap(data, options)` and `renderMap(data, options)`. Move old `createSFMap`, `renderSFMap`, `neighborhoodNames`, `districtColors`, `districtYears`, and legacy static type imports to `/legacy` for an incremental migration. Existing named subpaths retain their compatibility APIs.
+- `createMap` returns a controller: mount `map.element`. Features belong in `features`, styling in `appearance`; flat spellings are rejected. Use `configure({ features, layers, controls })`, `camera.*`, and typed `on()` subscriptions. Appearance is construction-only.
+- The controller throws on operations after disposal; `destroy()` and unsubscribe remain idempotent. Configuration rejects unknown/malformed keys and invalid ranges. Marker/overlay IDs must be unique. Shared guide geography is immutable; clone before deriving custom data.
+
+### Added
+
+- Data-free `/map` and `/static` entrypoints, configuration-only `/presets`, detached configuration snapshots, and all-groups validation before configuration updates. Camera pan, zoom, reset, fit and set accept consistent animation options.
+- Palette, label font/weight/halo, selected/hover neighborhood styling, custom legend entries, compact expandable attribution, and independent visible/accessibility touch labels.
+- Opt-in eased camera motion and staggered marker entrances, respecting reduced motion, interruption, preference changes, and disposal.
+- Per-pin radii, selected rings, deterministic screen-space clustering and accessible marker choice, HTML overlay placement, screen projection, north arrow and approximate scale bar.
+- Server-safe overview `createGuideSVG` / `createGuideShell` and compact `mountGuideMap`, using matching simplified geography and reserved layout rows.
+- Coastline-only basemaps without neighborhood datasets. SFAR remains the default when supplied; alternative-only data selects the available source.
+- Full migration documentation, public examples, adversarial API contract matrix, production import-graph/size budgets, and automatic verification that GitHub release notes contain the complete changelog. The npm archive now includes CHANGELOG.md.
+
+### Fixed and hardened
+
+- Reentrant camera and selection callbacks cannot revive obsolete animation or overwrite a newer selection. Failed source, marker, overlay, feature, layer and control updates preserve existing state.
+- Runtime controls remain independent, feature toggles preserve camera/selection, and unrelated configuration updates no longer interrupt motion. Hiding touch controls returns gestures to the page.
+- Revoke obsolete cluster handlers immediately when markers, selection or clustering settings change; v2 overlay activation is wired to typed events for mouse and keyboard users.
+- Keyboard focus remains reachable through filtering and clustering; removed overlays lose listeners. Construction failures and repeated destruction clean up observers, listeners and asynchronous work.
+- Detached selection/event snapshots prevent accidental mutation of renderer state. Malformed/sparse viewports, coordinates, padding, overlay geometry and misspelled options are rejected. Corrected public `LineString` overlay typing.
+- Root static imports tree-shake away browser code and all geographic JSON. Renderer, camera, clustering, configuration and validation have separate internal boundaries; rendering remains offline with zero runtime dependencies.
+
+### Validation and bundle guidance
+
+- Covered by Node regression tests, Chromium Storybook interactions/coverage, declaration tests, clean packed-consumer installation, and desktop/390px browser inspection. Required checks include demo, Storybook and Pages builds.
+- Representative production gzip measurements: v2 root **22.8 KiB without geography**; static-only root import **4.5 KiB**; compatibility guide including overview geography **110.2 KiB**. Consumer output varies. Runtime switches do not remove imported code or data; use narrow entrypoints, explicit datasets and lazy detail loading.
+
 ## 1.5.2 — 2026-09-26
 
 - Run every Storybook story as a Chromium/Vitest browser check and publish an LCOV and JSON coverage artifact for the renderer, with baseline regression thresholds.

package/README.md

@@ -14,7 +14,7 @@ Self-contained SVG maps of San Francisco, with precise coastlines, soft district
 | --- | --- | --- |
 | Explore real election data | [California propositions by SF district](https://kahwee.github.io/sf-map-svg/propositions.html) or [local measures](https://kahwee.github.io/sf-map-svg/measures.html) | `custom-map` |
 | Make a small interactive city map | [Neighborhood guide](https://kahwee.github.io/sf-map-svg/#explore-more-title) | `/guide` |
-| Render a static or custom SVG | [Code recipes](docs/EXAMPLES.md) | Root or `/custom-map` |
+| Render a static or custom SVG | [Code recipes](docs/EXAMPLES.md) | `/static` or `/custom-map` |
 | Animate a route | [BART journey](https://kahwee.github.io/sf-map-svg/transit.html) | `/transit` or overlays |
 
 ## Install
@@ -27,7 +27,9 @@ Use Node 22.12+ for server-side rendering. Browser components need a DOM and a b
 
 | Start with | Entry point | What you get |
 | --- | --- | --- |
-| Static SVG | `@kahwee/sf-map-svg` | SVG markup, projection helpers, optional layers |
+| v2 controller | `@kahwee/sf-map-svg` or `/map` | Explicit data, grouped options, managed events and camera |
+| v2 static SVG | `@kahwee/sf-map-svg/static` | Server-safe rendering with explicit data |
+| Compatibility static SVG | `@kahwee/sf-map-svg/legacy` | Original renderer with bundled geography |
 | Data-injected SVG | `@kahwee/sf-map-svg/custom-map` | Tree-shakeable renderer core with only the geographic data you provide |
 | Neighborhood explorer | `@kahwee/sf-map-svg/explorer` | Search, source selection, map controls, GeoJSON downloads |
 | Interactive map | `@kahwee/sf-map-svg/interactive` | Embeddable map and controls without the explorer sidebar |
@@ -38,11 +40,44 @@ Use Node 22.12+ for server-side rendering. Browser components need a DOM and a b
 | Metadata search | `@kahwee/sf-map-svg/data/catalog` | Search names without polygon geometry |
 | SFAR lookup | `@kahwee/sf-map-svg/data/realtor` | Default neighborhoods without alternative sources |
 
+## Version 2: explicit data and a controller
+
+```js
+import { createMap } from '@kahwee/sf-map-svg';
+import { guideMapData } from '@kahwee/sf-map-svg/guide/data';
+import { guideOptions } from '@kahwee/sf-map-svg/presets';
+
+const map = createMap(guideMapData, {
+  ...guideOptions,
+  features: { motion: true, markerEntrance: true, clustering: true },
+  appearance: { colors: { water: '#e6f1f5' } },
+});
+document.querySelector('#map').append(map.element);
+map.configure({ features: { motion: false }, controls: { pan: false } });
+const unsubscribe = map.on('markerchange', ({ marker }) => console.log(marker?.id));
+map.camera.reset({ animate: false });
+// On component disposal: map.destroy();
+```
+
+The root and `/map` include no geography; `/static` includes no interactive runtime.
+`guide/data` supplies only overview geography; `/presets` supplies configuration only.
+Camera methods share `{ animate, duration }`. `configure()` accepts the same feature,
+layer and control groups as construction and validates the entire patch before applying
+it. Appearance is construction-only. The controller's `on()` returns an unsubscribe
+function and disposal removes all its subscriptions. Operations after disposal throw;
+`destroy()` itself is idempotent.
+
+`renderMap(data, options)` from `/static` returns `{ svg, project, ... }` and needs only
+`StaticMapData` (for example, `guideMapData.map`). Static options retain their SVG-unit
+semantics; camera/motion/control options belong exclusively to the browser controller.
+See [v2 migration and architecture](docs/migration-v2.md) for breaking changes,
+configuration resets, and bundle boundaries. Existing subpaths remain compatibility APIs.
+
 ## Render a static map
 
 ```js
 import { writeFile } from 'node:fs/promises';
-import { renderSFMap } from '@kahwee/sf-map-svg';
+import { renderSFMap } from '@kahwee/sf-map-svg/legacy';
 
 const svg = renderSFMap({
   landmarks: true,
@@ -61,8 +96,8 @@ That entry point does not import the package's built-in JSON collections. Its `S
 requires the coast and accepts selected district vintages plus optional neighborhood,
 road, park, and station arrays. Use the canonical JSON subpaths documented in
 [`data/README.md`](data/README.md) as source; map each feature collection to the
-corresponding `SFMapData` records. The root entry remains convenient and includes the
-built-in datasets for backward compatibility.
+corresponding `SFMapData` records. The `/legacy` entry includes the built-in datasets for migration. The v2 root
+imports no geographic JSON.
 
 In tree-shaking bundlers, importing a single symbol from `/data` retains only the
 modules that symbol uses.
@@ -387,7 +422,7 @@ pnpm test:stories:coverage # Chromium checks plus renderer coverage report
 pnpm test:package     # install and check the packed package
 ```
 
-Use `pnpm format` to apply Biome formatting and safe lint fixes. Install Chromium once with `pnpm exec playwright install chromium` before local Storybook tests. Run `pnpm storybook` for interactive component examples at http://127.0.0.1:6006. The coverage command writes `coverage/storybook/coverage-summary.json` and `lcov.info` for `src/` TypeScript only. CI runs package checks on Node 22, 24, and 26 plus Chromium Storybook checks on Node 24, and uploads the coverage report. See [CONTRIBUTING.md](CONTRIBUTING.md) for source structure and release instructions.
+Use `pnpm format` to apply Biome formatting and safe lint fixes. Install Chromium once with `pnpm exec playwright install chromium` before local Storybook tests. Run `pnpm storybook` for interactive component examples at http://127.0.0.1:6006. The coverage command writes `coverage/storybook/coverage-summary.json` and `lcov.info` for `src/` TypeScript only. CI runs package and Chromium Storybook checks on Node 26 and uploads the coverage report. See [CONTRIBUTING.md](CONTRIBUTING.md) for source structure and release instructions.
 
 ### Browser verification
 
@@ -449,3 +484,107 @@ Embed the Pages demo with `<iframe src="https://kahwee.github.io/sf-map-svg/tran
 ## Ballot measures explorer
 
 [Explore local ballot measures](https://kahwee.github.io/sf-map-svg/measures.html): 44 measures from the November 2002, November 2012, November 2022, and June 2026 elections, across all three supported district map vintages. Pick an election, search its measures, inspect a district, compare two measures, and download an SVG, CSV, or the sourced JSON. The page includes touch pan/zoom, keyboard district selection, a sortable district table, and shareable year-specific views. Each election's results and district map load on demand. This is an archive of four elections, not every intervening election or a live results service. See [the election data schema](data/elections/README.md) and [SOURCES.md](SOURCES.md) for methods and source links.
+
+### Motion, styling, and progressive embeds
+
+The guide now exposes the same `colors` palette as the static renderer. Existing
+appearance and immediate camera movement remain the defaults. See
+[consumer integration recommendations](docs/consumer-integration.md) for the
+complete example, bundle choices, progressive shell, and testing contract.
+
+```js
+import { createGuideMap } from '@kahwee/sf-map-svg/guide/map';
+
+const map = createGuideMap({
+  colors: { water: '#202d38', land: '#34434a', park: '#42624d',
+    road: '#728080', neighborhood: '#64767e', label: '#f1f3ee' },
+  labelStyle: { fontFamily: 'DM Sans, system-ui, sans-serif', fontWeight: 550,
+    haloColor: '#34434a' },
+  motion: { duration: 400 },
+  markerEntrance: { duration: 450, stagger: 35 },
+  selectedMarkerRing: { color: '#f1f3ee', width: 2, gap: 3 },
+  clustering: { radius: 32 },
+  attribution: 'compact',
+  legend: { items: [{ label: 'Places', color: '#cf8757' }] },
+  northArrow: true,
+  scaleBar: true,
+  strings: { touchNavigation: 'Touch pan', touchNavigationLabel: 'Enable touch pan',
+    touchNavigationDone: 'Done', touchNavigationExitLabel: 'Restore page scrolling' },
+});
+document.querySelector('#map').append(map);
+```
+
+| Option | Contract |
+| --- | --- |
+| `colors` | Static palette keys: water, land, district, neighborhood, highway, road, park, landmark, BART (`bart`), label, marker, selected |
+| `labelStyle` | `fontFamily`, numeric `fontWeight`, `haloColor`; the application loads any custom font |
+| `areaStyle` | `selectedFill`, `selectedStroke`, `hoverFill`, `hoverStroke`; applies to selectable neighborhoods |
+| `motion` | `false` by default; `true` uses 320ms, or `{ duration }` in milliseconds |
+| `markerEntrance` | `false` by default; `true` uses 420ms and 35ms stagger, or `{ duration, stagger }`; only newly introduced IDs animate, delay capped at 1s |
+| `MapMarker.radius` | Per-marker visible radius; interactive units are CSS pixels, static units are SVG units |
+| `selectedMarkerRing` | Optional `{ color, width, gap }` in CSS pixels; preserves the hit target |
+| `clustering` | `false` by default; `true` or `{ radius }` groups nearby screen positions; selected pin remains independent |
+| `legend` | `{ builtins: false, items: [{ label, color }] }` replaces built-ins; omit `builtins` to append custom entries; `hidden` hides selected built-ins (`bart`, `park`, `highway`, `road`) |
+| `attribution` | `'full'` (default) or `'compact'`; compact keeps full provenance in a native disclosure |
+| `northArrow`, `scaleBar` | Optional canvas furniture; scale is approximate at central SF latitude, in metric units |
+
+`setViewport(view, { animate, duration })`, `fitGeometry(geometry, padding,
+{ animate, duration })`, `selectMarker(id, { fit, animate, duration })`, and
+`selectNeighborhood(name, { fit, animate, duration })` accept per-call motion
+controls. `animate: true` opts in even when global motion is disabled.
+`stopAnimation()` freezes the camera at its current viewport. A new camera
+operation replaces the previous transition; pointer gestures interrupt it.
+Reduced-motion preference overrides all animation requests. `destroy()` cancels
+camera frames, marker animations, listeners, and resize observation.
+
+`map.overlayElement` is a public HTML overlay slot. `map.projectToScreen(lng, lat)`
+returns `{ x, y, visible }` in CSS pixels relative to that slot. Call it after
+mounting; reposition your callout on `viewportchange` and `mapresize`.
+The slot ignores pointer events; interactive children can set `pointer-events:auto`.
+`clusteractivate` emits `{ markers }` and fits their geographic extent. Coincident
+pins cannot separate through zoom; retain the full native marker chooser or an
+accessible external list. `--sf-marker-index` on each marker is a stable entrance
+index hook, but the built-in animation avoids the need to style internal SVG.
+
+For server rendering, `createGuideSVG(options)` from `@kahwee/sf-map-svg/guide/static`
+uses the same simplified geography as the browser guide with one import.
+`createGuideShell(options)` also reserves compact toolbar, legend, and attribution
+rows; pass its `.sf-guide-shell` element to `mountGuideMap(shell, options)` from
+`@kahwee/sf-map-svg/guide/map`. By default, this compact layout hides the native
+pickers, pan buttons, label switch, help, and visible status; explicit control overrides are honored. Provide an accessible
+external place list. The toolbar and legend scroll horizontally if needed.
+
+### Reconfigure without rebuilding
+
+Construction options remain backward-compatible. Use these atomic patches for
+runtime switches; they preserve the map element, viewport, markers, and selection:
+
+```js
+map.setFeatures({ motion: false, clustering: true, selectedMarkerRing: true });
+map.setLayers({ landmarks: false, bartStations: true, roadLabels: false });
+map.setControls({ zoom: false, reset: true, touch: true });
+```
+
+`setFeatures` accepts the exported `MapFeatures` interface: `motion`,
+`markerEntrance`, `clustering`, `selectedMarkerRing`, `northArrow`, and `scaleBar`.
+Every feature accepts `false` to disable; the first four also accept `true` for
+built-in settings or an options object. Omitted patch keys retain their settings;
+`undefined` resets that key to the default. Options objects **replace** the previous
+object for that feature; they do not deep-merge. `getFeatures()` returns a detached,
+normalized snapshot. Changing motion cancels the current transition; changing
+entrance settings cancels active entrances and applies to future new marker IDs.
+
+`setLayers` accepts `InteractiveLayers`; `undefined` restores the mode default.
+Geometry, associated labels, built-in legend entries, and attribution update
+together. Roads and road labels remain independent switches. Toggling does not
+remove geography already imported into a client bundle.
+
+`setControls` accepts the same keys as `controls`. Hiding zoom no longer hides
+Reset, Labels, or Touch. Hiding the touch button disengages touch navigation so
+page scrolling stays recoverable. Unknown switch names and invalid values throw
+before modifying state. After `destroy()`, setters are no-ops and disposal can be
+repeated safely. Getters return the last state; screen projection still requires
+a mounted, visible canvas.
+
+For configuration precedence, malformed inputs, callback reentrancy, and lifecycle
+ownership, see the [maintainer API audit](docs/api-audit.md).

package/dist/data/README.md

@@ -4,6 +4,10 @@ The JSON files here are the geographic source of truth, not generated copies of
 
 The renderer, `neighborhoods` convenience export, and `getNeighborhood` default to the **92 SFAR realtor areas**. Import `neighborhoods-realtor.json` directly for that same geometry. The filename `neighborhoods.json` continues to identify the separate SF Find collection.
 
+Certified candidate vote snapshots are separate, optional JSON imports under
+[`candidates/`](candidates/README.md). They do not change the geographic
+renderer or its default bundle.
+
 ## Available files
 
 | File                          | Contents                                                            |
@@ -95,7 +99,7 @@ Lookup is exact after case/punctuation normalization, returns `undefined` for an
 ## Draw a neighborhood with the existing projection
 
 ```js
-import { createSFMap } from '@kahwee/sf-map-svg';
+import { createSFMap } from '@kahwee/sf-map-svg/legacy';
 import { getNeighborhood } from '@kahwee/sf-map-svg/data';
 import { geometryPath } from '@kahwee/sf-map-svg/geometry';
 

package/dist/data/types.d.ts

@@ -4,7 +4,10 @@ export type Geometry = {
     readonly type: 'Point';
     readonly coordinates: Position;
 } | {
-    readonly type: 'LineString' | 'MultiPoint';
+    readonly type: 'LineString';
+    readonly coordinates: readonly Position[];
+} | {
+    readonly type: 'MultiPoint';
     readonly coordinates: readonly Position[];
 } | {
     readonly type: 'Polygon';

package/dist/src/api.d.ts

@@ -0,0 +1,3 @@
+/** v2 root: runtime and types only. Geography is always an explicit import. */
+export * from './map.js';
+export * from './static.js';

package/dist/src/api.js

@@ -0,0 +1,3 @@
+/** v2 root: runtime and types only. Geography is always an explicit import. */
+export * from './map.js';
+export * from './static.js';

package/dist/src/camera.d.ts

@@ -0,0 +1,16 @@
+import type { CameraOptions, MapViewport } from './types.js';
+export declare function validateCameraOptions(options: CameraOptions): void;
+/** A cancellable camera independent of DOM rendering; generation guards cover reentrant events. */
+export declare function createCamera({ read, write, duration, reduced, request, cancel, now, }: {
+    read: () => MapViewport;
+    write: (view: MapViewport) => void;
+    duration: () => number;
+    reduced: () => boolean;
+    request: (callback: FrameRequestCallback) => number;
+    cancel: (id: number) => void;
+    now: () => number;
+}): {
+    stop: () => void;
+    destroy(): void;
+    move(next: MapViewport, options?: CameraOptions): void;
+};

package/dist/src/camera.js

@@ -0,0 +1,55 @@
+import { assertOptions } from './validation.js';
+import { validateViewport } from './viewport.js';
+export function validateCameraOptions(options) {
+    assertOptions(options, 'camera', ['animate', 'duration', 'fit']);
+    if ('fit' in options && options.fit !== undefined && typeof options.fit !== 'boolean')
+        throw new TypeError('fit must be boolean.');
+    if (options.animate !== undefined && typeof options.animate !== 'boolean')
+        throw new TypeError('animate must be a boolean.');
+    if (options.duration !== undefined &&
+        (!Number.isFinite(options.duration) || options.duration < 0))
+        throw new RangeError('Duration must be finite and nonnegative.');
+}
+/** A cancellable camera independent of DOM rendering; generation guards cover reentrant events. */
+export function createCamera({ read, write, duration, reduced, request, cancel, now, }) {
+    let frame = 0, generation = 0, destroyed = false;
+    function stop() {
+        generation++;
+        cancel(frame);
+        frame = 0;
+    }
+    return {
+        stop,
+        destroy() {
+            destroyed = true;
+            stop();
+        },
+        move(next, options = {}) {
+            if (destroyed)
+                return;
+            const target = validateViewport(next);
+            validateCameraOptions(options);
+            const ms = options.duration ?? (options.animate === true ? duration() || 320 : duration());
+            stop();
+            const token = generation;
+            if (options.animate === false || reduced() || !ms) {
+                write(target);
+                return;
+            }
+            const from = [...read()], start = now();
+            if (from.every((value, i) => value === target[i]))
+                return;
+            const tick = (time) => {
+                if (destroyed || token !== generation)
+                    return;
+                const t = Math.max(0, Math.min(1, (time - start) / ms));
+                const eased = 1 - (1 - t) ** 3;
+                write(target.map((value, i) => from[i] + (value - from[i]) * eased));
+                if (destroyed || token !== generation)
+                    return;
+                frame = t < 1 ? request(tick) : 0;
+            };
+            frame = request(tick);
+        },
+    };
+}

package/dist/src/clusters.d.ts

@@ -0,0 +1,7 @@
+/** Stable seed-distance groups with a spatial index, independent of input order and the DOM. */
+export declare function clusterPoints<T extends {
+    marker: {
+        id: string;
+    };
+    point: readonly [number, number];
+}>(items: readonly T[], unit: number, radius: number): T[][];

package/dist/src/clusters.js

@@ -0,0 +1,33 @@
+/** Stable seed-distance groups with a spatial index, independent of input order and the DOM. */
+export function clusterPoints(items, unit, radius) {
+    const cellSize = unit * radius;
+    if (!Number.isFinite(cellSize) || cellSize <= 0)
+        throw new RangeError('Cluster scale and radius must be positive and finite.');
+    const cells = new Map();
+    const groups = [];
+    for (const item of [...items].sort((a, b) => a.marker.id < b.marker.id ? -1 : a.marker.id > b.marker.id ? 1 : 0)) {
+        const [x, y] = item.point;
+        const cx = Math.floor(x / cellSize), cy = Math.floor(y / cellSize);
+        let nearest, distance = cellSize;
+        for (let dx = -1; dx <= 1; dx++)
+            for (let dy = -1; dy <= 1; dy++) {
+                for (const candidate of cells.get(`${cx + dx}:${cy + dy}`) ?? []) {
+                    const d = Math.hypot(x - candidate[0].point[0], y - candidate[0].point[1]);
+                    if (d < distance) {
+                        nearest = candidate;
+                        distance = d;
+                    }
+                }
+            }
+        if (nearest)
+            nearest.push(item);
+        else {
+            const group = [item], key = `${cx}:${cy}`;
+            groups.push(group);
+            const cell = cells.get(key) ?? [];
+            cell.push(group);
+            cells.set(key, cell);
+        }
+    }
+    return groups;
+}

package/dist/src/configuration.d.ts

@@ -0,0 +1,5 @@
+import type { MapConfiguration, MapConfigurationSnapshot, MapOptions } from './controller-types.js';
+import type { NeighborhoodExplorerOptions } from './types.js';
+export declare function expandMapOptions(options: MapOptions): NeighborhoodExplorerOptions;
+/** Prepare the entire configuration before any DOM mutation. */
+export declare function prepareConfiguration(current: MapConfigurationSnapshot, patch: MapConfiguration): MapConfigurationSnapshot;

package/dist/src/configuration.js

@@ -0,0 +1,73 @@
+import { controlKeys, layerKeys, normalizeFeatures, validateSwitchPatch } from './features.js';
+import { assertOptions, validateExplorerOptions } from './validation.js';
+const appearanceKeys = [
+    'theme',
+    'colors',
+    'labelStyle',
+    'areaStyle',
+    'labelSize',
+    'style',
+    'markerRadius',
+    'markerHitSize',
+    'markerColor',
+    'selectedMarkerColor',
+];
+const featureKeys = [
+    'motion',
+    'markerEntrance',
+    'selectedMarkerRing',
+    'clustering',
+    'northArrow',
+    'scaleBar',
+];
+export function expandMapOptions(options) {
+    const record = assertOptions(options, 'map');
+    for (const key of [
+        ...appearanceKeys,
+        ...featureKeys,
+        'interface',
+        'onMarkerActivate',
+        'onOverlayActivate',
+    ])
+        if (key in record)
+            throw new TypeError(`Use the v2 grouped options or map.on() instead of ${key}.`);
+    if (options.appearance !== undefined)
+        assertOptions(options.appearance, 'appearance', appearanceKeys);
+    if (options.features !== undefined)
+        normalizeFeatures(options.features);
+    const { features, appearance, ...rest } = options;
+    const expanded = { ...rest, ...appearance, ...features };
+    validateExplorerOptions(expanded);
+    return expanded;
+}
+/** Prepare the entire configuration before any DOM mutation. */
+export function prepareConfiguration(current, patch) {
+    assertOptions(patch, 'configuration', ['features', 'layers', 'controls']);
+    const features = 'features' in patch
+        ? normalizeFeatures(patch.features === undefined
+            ? {}
+            : { ...current.features, ...checkedFeatures(patch.features) })
+        : current.features;
+    const switches = (key, previous, keys) => {
+        if (!(key in patch))
+            return previous;
+        const value = patch[key];
+        if (value === undefined)
+            return {};
+        validateSwitchPatch(value, keys);
+        const next = { ...previous, ...value };
+        for (const property of Object.keys(next))
+            if (next[property] === undefined)
+                delete next[property];
+        return next;
+    };
+    return structuredClone({
+        features,
+        layers: switches('layers', current.layers, layerKeys),
+        controls: switches('controls', current.controls, controlKeys),
+    });
+}
+function checkedFeatures(value) {
+    normalizeFeatures(value);
+    return value;
+}

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

@@ -0,0 +1,84 @@
+import type { Geometry, NeighborhoodSource } from '../data/types.js';
+import type { CameraOptions, InteractiveLayers, MapFeatures, MapMarker, MapOverlay, MapPadding, MapViewport, NeighborhoodExplorerOptions, NeighborhoodSelection } from './types.js';
+export type MapAppearance = Pick<NeighborhoodExplorerOptions, 'theme' | 'colors' | 'labelStyle' | 'areaStyle' | 'labelSize' | 'style' | 'markerRadius' | 'markerHitSize' | 'markerColor' | 'selectedMarkerColor'>;
+export type MapControls = NonNullable<NeighborhoodExplorerOptions['controls']>;
+/** Omitted groups/keys retain their values; undefined groups reset all keys in that group. */
+export interface MapConfiguration {
+    features?: MapFeatures;
+    layers?: InteractiveLayers;
+    controls?: MapControls;
+}
+export interface MapOptions extends Omit<NeighborhoodExplorerOptions, keyof MapFeatures | keyof MapAppearance | 'interface' | 'onMarkerActivate' | 'onOverlayActivate'> {
+    features?: MapFeatures;
+    appearance?: MapAppearance;
+}
+export interface MapConfigurationSnapshot {
+    features: MapFeatures;
+    /** Explicit overrides; absent values continue to follow the current mode. */
+    layers: InteractiveLayers;
+    controls: MapControls;
+}
+export interface MapEvents {
+    markerchange: {
+        id: string | null;
+        marker: MapMarker | null;
+    };
+    neighborhoodchange: NeighborhoodSelection | {
+        id: null;
+        name: null;
+        source: NeighborhoodSource;
+        feature: null;
+    };
+    overlayactivate: {
+        overlay: MapOverlay;
+    };
+    clusteractivate: {
+        markers: MapMarker[];
+    };
+    viewportchange: {
+        viewport: MapViewport;
+    };
+    mapresize: undefined;
+}
+export interface MapCamera {
+    get(): MapViewport;
+    set(view: MapViewport, options?: CameraOptions): void;
+    fit(geometry: Geometry, options?: CameraOptions & {
+        padding?: number | MapPadding;
+    }): void;
+    pan(x: number, y: number, options?: CameraOptions): void;
+    zoom(factor: number, options?: CameraOptions): void;
+    reset(options?: CameraOptions): void;
+    stop(): void;
+}
+/** Owns the map lifecycle separately from its mountable DOM element. */
+export interface MapController {
+    readonly element: HTMLElement;
+    readonly overlayElement: HTMLDivElement;
+    readonly camera: MapCamera;
+    readonly destroyed: boolean;
+    configure(patch: MapConfiguration): void;
+    getConfiguration(): MapConfigurationSnapshot;
+    on<K extends keyof MapEvents>(type: K, listener: (detail: MapEvents[K]) => void): () => void;
+    setMarkers(markers: readonly MapMarker[]): void;
+    setOverlays(overlays: readonly MapOverlay[]): void;
+    selectMarker(id: string | null, options?: CameraOptions & {
+        fit?: boolean;
+    }): boolean;
+    getSelectedMarker(): MapMarker | null;
+    selectNeighborhood(name: string | null, options?: CameraOptions & {
+        fit?: boolean;
+    }): boolean;
+    getSelectedNeighborhood(): NeighborhoodSelection | null;
+    setSource(source: NeighborhoodSource): void;
+    setMode(mode: NonNullable<MapOptions['mode']>): void;
+    setLabels(visible: boolean): void;
+    setTouchNavigation(enabled: boolean): void;
+    projectToScreen(lng: number, lat: number): {
+        x: number;
+        y: number;
+        visible: boolean;
+    };
+    /** Idempotent; stops work and managed subscriptions. Does not remove host-owned DOM. */
+    destroy(): void;
+}

package/dist/src/controller-types.js

@@ -0,0 +1 @@
+export {};

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

@@ -2,4 +2,4 @@ import type { InteractiveSFMapData } from './explorer-data.js';
 import type { NeighborhoodExplorerElement, NeighborhoodExplorerOptions } from './types.js';
 export type { ExplorerMode, NeighborhoodExplorerElement, NeighborhoodExplorerOptions, } from './types.js';
 /** Create an offline, browser-only neighborhood explorer. Call destroy() before disposal. */
-export declare function createNeighborhoodExplorerCore({ source, mode, labels, neighborhood, year, theme, interface: chrome, layers, selectableNeighborhoods, labelSize, fitPadding, markers: initialMarkers, markerRadius, markerHitSize, markerColor, selectedMarkerColor, onMarkerActivate, overlays: initialOverlays, onOverlayActivate, style: styleOptions, strings, controls, }: NeighborhoodExplorerOptions | undefined, data: InteractiveSFMapData): NeighborhoodExplorerElement;
+export declare function createNeighborhoodExplorerCore(options: NeighborhoodExplorerOptions | undefined, data: InteractiveSFMapData): NeighborhoodExplorerElement;