@kahwee/sf-map-svg 4.4.0 → 5.0.0

package/CHANGELOG.md

@@ -4,6 +4,31 @@ User-visible changes are recorded here. Unreleased entries describe changes on `
 
 ## Unreleased
 
+## 5.0.0 — 2026-10-19
+
+- Breaking: controller `setMode` and `setSource` preserve the camera; remove their `{ resetView }` argument. Call `camera.reset()` or `camera.fit()` explicitly.
+- Breaking: controller `configure` treats all omitted and undefined values as no-ops and merges nested feature records. Add `resetConfiguration(groups?)` to clear presentation overrides explicitly.
+- Breaking: controller `selectNeighborhood` selects exact IDs in the current source; resolve names through source-specific data lookup or use source/year-qualified `selectFeature`.
+- Include a [v5 migration guide](docs/migration-v5.md), migrated consumer examples, and regression checks. Retain Node 24+, offline rendering, zero runtime dependencies, geographic data, and default appearance.
+
+- Add offline `geometryBounds()` and `geometryContainsPoint()` helpers to `/geometry`, with readonly inputs, polygon holes and islands, nested collections, explicit boundary semantics, and coordinate validation. Export `Bounds`, `Geometry`, and `Position` from the same entry.
+- Breaking: markers now require `position: [longitude, latitude]`; remove the numeric `projectToScreen(lng, lat)` form in favor of one readonly GeoJSON position. Export shared `ScreenPoint` and `ProjectToScreen` types and cover camera changes, resizing, invalid coordinates, and controller disposal in browser regressions.
+- Document geographic queries, screen-coordinate integration, and API consistency follow-ups. Correct the developer guide: camera pan deltas are CSS pixels, not projected map units.
+
+## 4.5.0 — 2026-10-14
+
+- Add the optional `/cards` entry with `bindMapCards()`: hover/focus previews a pin without changing selection or camera, native buttons select places, map selection reveals matching cards without stealing focus, and explicit cleanup restores owned DOM attributes.
+- Spread budgeted static labels across the map while favoring nearby-pin context and retaining a selected-place label when it fits. Keep collision avoidance, all pins, unbudgeted labels, and default output unchanged.
+
+- Add opt-in `mapPalettes.nightForest` and `mapPalettes.warmPaper` tokens for consistent static/interactive map colors, label halos, markers, and selection rings, with contrast checks.
+
+- Port YorkSF’s editorial map-preview pattern into static rendering: opt-in compact SVG label layouts, spatial label budgets, and configurable halos for dark palettes. Add a build-time field-guide example and light/dark Storybook preview without runtime dependencies or changes to default output.
+
+- Separate interactive neighborhood state, controls, sidebar downloads and overlays into lifecycle-owned modules; revoke neighborhood hover listeners when replacing sources and keep optional explorer sidebar code out of normal map bundles.
+- Build the package once during `pnpm check`, while keeping standalone test and typecheck commands self-contained.
+
+- Include compatible development-tool updates to Vite 8.3.4 and Playwright 1.64.0. Keep Storybook/addons 10.6.1 and aligned Vitest/browser/coverage 5.0.3; their newer 10.6.2 and 5.0.4 releases remain inside pnpm's release-age window. Make the consumer examples' custom touch-button accessible names include their visible text. Remove the obsolete Storybook 10.6.0 peer overrides; retain Node 24+ and zero runtime dependencies. These tooling changes were previously prepared as 4.4.1 but not published separately.
+
 ## 4.4.0 — 2026-10-12
 
 - Add opt-in static `labelLayout: { width }` to `renderMap`, `createGuideSVG`, and `createGuideShell`. Static and interactive maps now share overview priorities, neighborhood anchors, font sizes, and collision rules; centered labels retain their anchors during enhancement.

package/README.md

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

package/dist/data/README.md

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

package/dist/src/cards.d.ts

@@ -0,0 +1,15 @@
+import type { MapController } from './controller-types.js';
+import type { MapMarker } from './types.js';
+export interface MapCardsOptions {
+    markers: readonly MapMarker[];
+    highlightColor?: string;
+    /** Reveal selected cards with native scrolling, without moving keyboard focus. Default true. */
+    scrollOnSelect?: boolean;
+}
+/** Connect consumer-owned [data-map-marker] cards and [data-map-select] buttons to a map. */
+export declare function bindMapCards(map: MapController, root: HTMLElement, options: MapCardsOptions): {
+    /** Call after map.setMarkers() when your place catalog changes. */
+    setMarkers(next: readonly MapMarker[]): void;
+    /** Remove owned listeners/decoration and restore card attributes. Call before map.destroy(). */
+    destroy(): void;
+};

package/dist/src/cards.js

@@ -0,0 +1,138 @@
+import { validateMarkers } from './validation.js';
+/** Connect consumer-owned [data-map-marker] cards and [data-map-select] buttons to a map. */
+export function bindMapCards(map, root, options) {
+    if (map.destroyed)
+        throw new Error('Cannot bind cards to a destroyed map.');
+    validateMarkers(options.markers);
+    let markers = new Map(options.markers.map((marker) => [marker.id, { ...marker }]));
+    let disposed = false;
+    let hovered = null;
+    let focused = null;
+    let selecting = false;
+    const document = root.ownerDocument;
+    const ring = document.createElement('span');
+    ring.dataset.mapCardHighlight = '';
+    ring.setAttribute('aria-hidden', 'true');
+    ring.style.cssText =
+        'position:absolute;width:26px;height:26px;box-sizing:border-box;border:3px solid;border-radius:50%;transform:translate(-50%,-50%);pointer-events:none';
+    ring.style.borderColor = options.highlightColor ?? '#e4531b';
+    ring.hidden = true;
+    map.overlayElement.append(ring);
+    const originals = new Map();
+    function attribute(node, key, value) {
+        let saved = originals.get(node);
+        if (!saved) {
+            saved = new Map();
+            originals.set(node, saved);
+        }
+        if (!saved.has(key))
+            saved.set(key, node.getAttribute(key));
+        if (value === null)
+            node.removeAttribute(key);
+        else
+            node.setAttribute(key, value);
+    }
+    const cardAt = (target) => {
+        const card = target instanceof Element ? target.closest('[data-map-marker]') : null;
+        return card && root.contains(card) ? card : null;
+    };
+    function highlight() {
+        ring.hidden = true;
+        if (disposed || map.destroyed || !map.overlayElement.getBoundingClientRect().width)
+            return;
+        const card = focused ?? hovered;
+        const marker = card && root.contains(card) ? markers.get(card.dataset.mapMarker ?? '') : undefined;
+        if (!marker)
+            return;
+        const point = map.projectToScreen(marker.position);
+        if (!point.visible)
+            return;
+        ring.style.left = `${point.x}px`;
+        ring.style.top = `${point.y}px`;
+        ring.hidden = false;
+    }
+    function selection(id, reveal) {
+        for (const card of root.querySelectorAll('[data-map-marker]')) {
+            const selected = id !== null && card.dataset.mapMarker === id;
+            attribute(card, 'data-map-selected', selected ? '' : null);
+            for (const button of card.querySelectorAll('button[data-map-select]'))
+                attribute(button, 'aria-pressed', String(selected));
+            if (selected && reveal && !selecting && options.scrollOnSelect !== false)
+                card.scrollIntoView({ block: 'nearest', inline: 'nearest', behavior: 'instant' });
+        }
+    }
+    const handlers = {
+        pointerover: (event) => {
+            if (event.pointerType !== 'touch') {
+                hovered = cardAt(event.target);
+                highlight();
+            }
+        },
+        pointerout: (event) => {
+            hovered = cardAt(event.relatedTarget);
+            highlight();
+        },
+        focusin: (event) => {
+            focused = cardAt(event.target);
+            highlight();
+        },
+        focusout: (event) => {
+            focused = cardAt(event.relatedTarget);
+            highlight();
+        },
+        click: (event) => {
+            if (disposed || map.destroyed)
+                return;
+            const target = event.target instanceof Element ? event.target.closest('button[data-map-select]') : null;
+            const card = cardAt(target);
+            const id = card?.dataset.mapMarker;
+            if (!target || !card || !id || !markers.has(id) || target.disabled)
+                return;
+            selecting = true;
+            try {
+                map.selectMarker(id, { fit: false });
+            }
+            finally {
+                selecting = false;
+            }
+        },
+    };
+    for (const [type, listener] of Object.entries(handlers))
+        root.addEventListener(type, listener);
+    const unsubscribers = [
+        map.on('markerchange', ({ id }) => selection(id, true)),
+        map.on('viewportchange', highlight),
+        map.on('mapresize', highlight),
+    ];
+    selection(map.getSelectedMarker()?.id ?? null, false);
+    return {
+        /** Call after map.setMarkers() when your place catalog changes. */
+        setMarkers(next) {
+            if (disposed)
+                return;
+            validateMarkers(next);
+            markers = new Map(next.map((marker) => [marker.id, { ...marker }]));
+            if (!map.destroyed)
+                selection(map.getSelectedMarker()?.id ?? null, false);
+            highlight();
+        },
+        /** Remove owned listeners/decoration and restore card attributes. Call before map.destroy(). */
+        destroy() {
+            if (disposed)
+                return;
+            disposed = true;
+            for (const [type, listener] of Object.entries(handlers))
+                root.removeEventListener(type, listener);
+            for (const unsubscribe of unsubscribers)
+                unsubscribe();
+            ring.remove();
+            for (const [node, saved] of originals)
+                for (const [key, value] of saved)
+                    if (value === null)
+                        node.removeAttribute(key);
+                    else
+                        node.setAttribute(key, value);
+            originals.clear();
+        },
+    };
+}

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

@@ -0,0 +1,2 @@
+/** Lifecycle-owned cluster rendering, including lazy markers and viewport mounting. */
+export { createClusterRenderer as createClusterLayer } from './cluster-renderer.js';

package/dist/src/cluster-layer.js

@@ -0,0 +1,2 @@
+/** Lifecycle-owned cluster rendering, including lazy markers and viewport mounting. */
+export { createClusterRenderer as createClusterLayer } from './cluster-renderer.js';

package/dist/src/configuration.d.ts

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

package/dist/src/configuration.js

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

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

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

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

@@ -0,0 +1,26 @@
+import type { createExplorerShell } from './explorer-shell.js';
+import type { MapViewport, NeighborhoodExplorerElement, NeighborhoodExplorerOptions } from './types.js';
+type Controls = NonNullable<NeighborhoodExplorerOptions['controls']>;
+type Shell = Pick<ReturnType<typeof createExplorerShell>, 'root' | 'toolbar' | 'canvas' | 'hint' | 'status' | 'modeSelect' | 'sourceSelect' | 'search' | 'results' | 'neighborhoodSelect' | 'markerSelect'>;
+type Commands = Pick<NeighborhoodExplorerElement, 'getViewport' | 'zoomBy' | 'resetView' | 'setLabels' | 'stopAnimation' | 'setMode' | 'setSource' | 'selectNeighborhood' | 'selectMarker'> & {
+    svg: SVGSVGElement;
+    signal: AbortSignal;
+    strings: NonNullable<NeighborhoodExplorerOptions['strings']>;
+    isDestroyed(): boolean;
+    getLabels(): boolean;
+    moveView(view: MapViewport): void;
+    setView(view: MapViewport): void;
+    updateResults(): void;
+    search(query: string): string | undefined;
+};
+/** Own toolbar and form events, touch navigation and control visibility.
+ * Commands read current map state; all listeners share the map's disposal signal.
+ */
+export declare function createExplorerControls({ root, toolbar, canvas, hint, status, modeSelect, sourceSelect, search, results, neighborhoodSelect, markerSelect, }: Shell, { svg, signal, strings, isDestroyed, getLabels, getViewport, moveView, zoomBy, resetView, setLabels, stopAnimation, setView, setMode, setSource, selectNeighborhood, selectMarker, updateResults, search: findNeighborhood, }: Commands): {
+    setTouchNavigation: (enabled: boolean) => void;
+    cancelNavigation: () => void;
+    update(controls: Controls): void;
+    updateLabels(labels: boolean): void;
+    updateZoom(zoom: number): void;
+};
+export {};

package/dist/src/explorer-controls.js

@@ -0,0 +1,120 @@
+import { element } from './dom.js';
+import { attachNavigation } from './navigation.js';
+/** Own toolbar and form events, touch navigation and control visibility.
+ * Commands read current map state; all listeners share the map's disposal signal.
+ */
+export function createExplorerControls({ root, toolbar, canvas, hint, status, modeSelect, sourceSelect, search, results, neighborhoodSelect, markerSelect, }, { svg, signal, strings, isDestroyed, getLabels, getViewport, moveView, zoomBy, resetView, setLabels, stopAnimation, setView, setMode, setSource, selectNeighborhood, selectMarker, updateResults, search: findNeighborhood, }) {
+    function listen(node, event, handler) {
+        node.addEventListener(event, (incoming) => handler(incoming), { signal });
+    }
+    const zoomControls = element('div', '', 'sf-explorer-control-group');
+    const panControls = element('div', '', 'sf-explorer-control-group sf-explorer-pan-controls');
+    toolbar.append(zoomControls, panControls);
+    function button(text, label, action, group = zoomControls) {
+        const node = element('button', text);
+        node.type = 'button';
+        node.setAttribute('aria-label', label);
+        node.addEventListener('click', () => action(), { signal });
+        group.append(node);
+        return node;
+    }
+    const zoomOut = button('−', 'Zoom out', () => zoomBy(1 / 1.5));
+    const zoomText = element('span', '100%', 'sf-explorer-zoom');
+    zoomControls.append(zoomText);
+    const zoomIn = button('+', 'Zoom in', () => zoomBy(1.5));
+    const resetButton = button(strings.reset ?? 'Reset', strings.reset ?? 'Reset map to city view', resetView);
+    const labelsButton = button('Labels', 'Show map labels', () => setLabels(!getLabels()));
+    for (const [symbol, label, dx, dy] of [
+        ['←', 'Pan west', -1, 0],
+        ['↑', 'Pan north', 0, -1],
+        ['↓', 'Pan south', 0, 1],
+        ['→', 'Pan east', 1, 0],
+    ])
+        button(symbol, label, () => {
+            const view = getViewport();
+            moveView([view[0] + (dx * view[2]) / 4, view[1] + (dy * view[2]) / 4, view[2]]);
+        }, panControls);
+    const touchLabel = strings.touchNavigation ?? 'Touch navigation';
+    const touchButton = button(touchLabel, strings.touchNavigationLabel ?? `Enable ${touchLabel.toLowerCase()}`, () => setTouchNavigation(!touchNavigation));
+    let touchNavigation = false;
+    const navigation = attachNavigation(svg, getViewport, (next) => {
+        stopAnimation();
+        setView(next);
+    }, signal, () => setTouchNavigation(false));
+    function setTouchNavigation(enabled) {
+        if (isDestroyed())
+            return;
+        if (typeof enabled !== 'boolean')
+            throw new TypeError('Touch navigation must be a boolean.');
+        touchNavigation = enabled;
+        navigation.setTouchNavigation(enabled);
+        canvas.style.touchAction = enabled ? 'none' : 'pan-y pinch-zoom';
+        touchButton.textContent = enabled
+            ? (strings.touchNavigationDone ?? 'Done: page scrolling')
+            : touchLabel;
+        touchButton.setAttribute('aria-label', enabled
+            ? (strings.touchNavigationExitLabel ?? `Exit ${touchLabel.toLowerCase()}`)
+            : (strings.touchNavigationLabel ?? `Enable ${touchLabel.toLowerCase()}`));
+        touchButton.setAttribute('aria-pressed', String(enabled));
+        root.dataset.touchNavigation = String(enabled);
+    }
+    listen(modeSelect, 'change', () => {
+        const next = modeSelect.value;
+        if (next === 'neighborhoods' || next === 'districts' || next === 'basemap')
+            setMode(next);
+    });
+    listen(search, 'input', updateResults);
+    listen(search, 'keydown', (event) => {
+        if (event.key === 'Enter') {
+            const match = findNeighborhood(search.value);
+            if (match) {
+                event.preventDefault();
+                selectNeighborhood(match);
+            }
+        }
+    });
+    listen(sourceSelect, 'change', () => {
+        const next = sourceSelect.value;
+        if (next === 'realtor' || next === 'sf-find' || next === 'analysis')
+            setSource(next);
+    });
+    listen(results, 'click', (event) => {
+        const node = event.target instanceof Element
+            ? event.target.closest('[data-neighborhood-result]')
+            : null;
+        if (node?.dataset.neighborhoodResult)
+            selectNeighborhood(node.dataset.neighborhoodResult);
+    });
+    listen(neighborhoodSelect, 'change', () => selectNeighborhood(neighborhoodSelect.value || null));
+    listen(markerSelect, 'change', () => selectMarker(markerSelect.value || null));
+    return {
+        setTouchNavigation,
+        cancelNavigation: navigation.cancel,
+        update(controls) {
+            for (const node of [zoomIn, zoomOut, zoomText])
+                node.hidden = controls.zoom === false;
+            panControls.hidden = controls.pan === false;
+            resetButton.hidden = controls.reset === false;
+            labelsButton.hidden = controls.labels === false;
+            touchButton.hidden = controls.touch === false;
+            if (touchButton.hidden && touchNavigation)
+                setTouchNavigation(false);
+            zoomControls.hidden = [...zoomControls.children].every((node) => node.hidden);
+            toolbar.hidden = zoomControls.hidden && panControls.hidden;
+            hint.hidden = controls.help === false;
+            if (hint.hidden)
+                svg.setAttribute('aria-describedby', hint.id);
+            else
+                svg.removeAttribute('aria-describedby');
+            status.classList.toggle('sf-explorer-visually-hidden', controls.status === false);
+        },
+        updateLabels(labels) {
+            labelsButton.setAttribute('aria-pressed', String(labels));
+        },
+        updateZoom(zoom) {
+            zoomText.textContent = `${Math.round(zoom * 100)}%`;
+            zoomIn.disabled = zoom >= 12;
+            zoomOut.disabled = zoom <= 1;
+        },
+    };
+}

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

@@ -1,6 +1,8 @@
 import type { NeighborhoodSource } from '../data/types.js';
 import type { MapConfiguration } from './controller-types.js';
 import type { InteractiveSFMapData } from './explorer-data.js';
+import type { createMapShell } from './explorer-shell.js';
+import type { createExplorerSidebar } from './explorer-sidebar.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. */
@@ -14,4 +16,7 @@ type MapEngineElement = NeighborhoodExplorerElement & {
     };
 };
 /** Create an offline, browser-only neighborhood explorer. Call destroy() before disposal. */
-export declare function createNeighborhoodExplorerCore(options: NeighborhoodExplorerOptions | undefined, data: InteractiveSFMapData): MapEngineElement;
+export declare function createNeighborhoodExplorerCore(options: NeighborhoodExplorerOptions | undefined, data: InteractiveSFMapData, ui: {
+    createShell: typeof createMapShell;
+    createSidebar?: typeof createExplorerSidebar;
+}): MapEngineElement;