@kahwee/sf-map-svg 4.2.0 → 4.3.0

package/CHANGELOG.md

@@ -4,6 +4,15 @@ User-visible changes are recorded here. Unreleased entries describe changes on `
 
 ## Unreleased
 
+## 4.3.0 — 2026-10-02
+
+- Add `selectFeature` with typed marker, neighborhood source/ID and district year/ID references. Missing or mismatched identities preserve current geography and selection.
+- Accept the same source-aware map data in static and interactive rendering. Static maps can explicitly select a supplied neighborhood definition without manually rebuilding renderer rows; compact static inputs remain supported.
+- Include current mode, source, year and labels in configuration snapshots. Route controller mode/source/label setters through atomic configuration and support explicit camera preservation with `{ resetView: false }`.
+- Refine the Pages atlas opening with concise copy, a map ahead of statistics on phones, coordinate captions and three direct paths into designing, exploring and building. Improve shared theme-button touch targets and stack API reference records on phones while retaining table semantics.
+
+- Clarify the documentation paths, progressive enhancement and cleanup examples; consolidate browser validation and release instructions into one maintenance runbook. Check README and integration recipes against the packed package.
+
 ## 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.

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.
 
-[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)
+[Getting started](docs/developer-guide.md) · [API reference](docs/API.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
 
@@ -45,11 +45,16 @@ const map = createMap(fullMapData, {
   features: { motion: true },
   appearance: { theme: 'districts' },
 });
-document.querySelector('#map')?.append(map.element);
+const host = document.querySelector('#map');
+if (!host) throw new Error('Missing #map container');
+host.append(map.element);
 map.on('neighborhoodchange', ({ name }) => console.log(name));
 map.camera.zoom(1.5);
-// When the view is removed:
-map.destroy();
+// Call when your application removes this view.
+function disposeMap() {
+  map.destroy();
+  map.element.remove();
+}
 ```
 
 `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.
@@ -66,13 +71,4 @@ Call `destroy()` when removing an interactive map.
 
 Canonical geography is in [`data/`](data/README.md), with provenance in [`SOURCES.md`](SOURCES.md). The public `/data` entry exposes lookup, catalog, district maps, and source-specific neighborhood collections. These are deeply frozen; clone before editing.
 
-```sh
-pnpm install --frozen-lockfile
-pnpm check
-pnpm demo
-pnpm build-storybook
-pnpm test:stories:coverage
-pnpm test:package
-```
-
-The [contributing guide](CONTRIBUTING.md) explains the geographic and release checks. If you are upgrading from v2, follow the [v3 migration guide](docs/migration-v3.md).
+Install with `pnpm install --frozen-lockfile`. See the [contributing guide](CONTRIBUTING.md) for architecture and the [validation and release runbook](https://github.com/kahwee/sf-map-svg/blob/main/docs/maintenance.md) for checks, browser inspection, and publishing. If you are upgrading from v2, follow the [v3 migration guide](docs/migration-v3.md).

package/dist/src/configuration.d.ts

@@ -1,5 +1,7 @@
 import type { MapConfiguration, MapConfigurationSnapshot, MapOptions } from './controller-types.js';
 import type { NeighborhoodExplorerOptions } from './types.js';
 export declare function expandMapOptions(options: MapOptions): NeighborhoodExplorerOptions;
+type PresentationSnapshot = Pick<MapConfigurationSnapshot, 'features' | 'layers' | 'controls' | 'appearance'>;
 /** Prepare the entire configuration before any DOM mutation. */
-export declare function prepareConfiguration(current: MapConfigurationSnapshot, patch: MapConfiguration): MapConfigurationSnapshot;
+export declare function prepareConfiguration(current: PresentationSnapshot, patch: MapConfiguration): PresentationSnapshot;
+export {};

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

@@ -24,7 +24,12 @@ export interface MapOptions extends Omit<NeighborhoodExplorerOptions, keyof MapF
     features?: MapFeatures;
     appearance?: MapAppearance | undefined;
 }
+/** Current geographic choices and detached presentation overrides; excludes camera and selection. */
 export interface MapConfigurationSnapshot {
+    mode: NonNullable<MapOptions['mode']>;
+    source: NeighborhoodSource;
+    year: DistrictYear;
+    labels: boolean;
     features: MapFeatures;
     /** Explicit overrides; absent values continue to follow the current mode. */
     layers: InteractiveLayers;
@@ -58,6 +63,19 @@ export type MapSelectionChange = {
     current: DistrictSelection | null;
     previous: DistrictSelection | null;
 };
+/** Dataset identity is explicit; selection never switches geography implicitly. */
+export type MapFeatureReference = {
+    kind: 'marker';
+    id: string | null;
+} | {
+    kind: 'neighborhood';
+    source: NeighborhoodSource;
+    id: string | null;
+} | {
+    kind: 'district';
+    year: DistrictYear;
+    id: number | null;
+};
 export interface MapEvents {
     /** Common selection envelope; existing change events retain their payloads. */
     selectionchange: MapSelectionChange;
@@ -97,6 +115,10 @@ export interface MapEvents {
     };
     mapresize: undefined;
 }
+/** Convenience setters retain their historic reset default; false preserves the camera. */
+export interface MapViewUpdateOptions {
+    resetView?: boolean;
+}
 export interface MapCamera {
     /** Fixed 800 × 800 projected space, not longitude/latitude. */
     get(): MapViewport;
@@ -124,6 +146,10 @@ export interface MapController {
     /** Reconcile stable IDs; retained markers preserve nodes, focus, and entrance animations. */
     setMarkers(markers: readonly MapMarker[]): void;
     setOverlays(overlays: readonly MapOverlay[]): void;
+    /** False for missing IDs or a source/year other than the current geography. */
+    selectFeature(reference: MapFeatureReference, options?: CameraOptions & {
+        fit?: boolean;
+    }): boolean;
     selectMarker(id: string | null, options?: CameraOptions & {
         fit?: boolean;
     }): boolean;
@@ -138,8 +164,8 @@ export interface MapController {
     getSelectedDistrict(): DistrictSelection | null;
     setDistrictYear(year: DistrictYear, options?: CameraOptions): void;
     setDistrictStyle(style: ((district: DistrictSelection['district']) => DistrictStyle) | undefined): void;
-    setSource(source: NeighborhoodSource): void;
-    setMode(mode: NonNullable<MapOptions['mode']>): void;
+    setSource(source: NeighborhoodSource, options?: MapViewUpdateOptions): void;
+    setMode(mode: NonNullable<MapOptions['mode']>, options?: MapViewUpdateOptions): void;
     setLabels(visible: boolean): void;
     setTouchNavigation(enabled: boolean): void;
     projectToScreen(lng: number, lat: number): {

package/dist/src/explorer-core.js

@@ -1064,7 +1064,10 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
     function selectNeighborhood(name, options = {}) {
         if (destroyed)
             return false;
-        const feature = name === null ? undefined : getNeighborhood(name, source);
+        const feature = name === null
+            ? undefined
+            : (collections[source]?.features.find((entry) => entry.id === name) ??
+                getNeighborhood(name, source));
         if (name !== null && !feature)
             return false;
         validateCameraOptions(options);
@@ -1668,6 +1671,8 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
             throw new RangeError(`No ${nextYear} district dataset was supplied.`);
         if (nextMode === 'neighborhoods' && !sources.length)
             throw new RangeError('No neighborhood dataset was supplied.');
+        if (patch.source !== undefined && !Object.hasOwn(collections, patch.source))
+            throw new RangeError(`Unknown neighborhood source: ${patch.source}`);
         const commitSource = patch.source !== undefined && patch.source !== source
             ? prepareSource(patch.source, false)
             : undefined;

package/dist/src/map.js

@@ -39,6 +39,7 @@ export function createMap(data, options = {}) {
         ])),
     });
     const snapshot = () => ({
+        ...element.getMapState(),
         ...structuredClone({
             features: config.features,
             layers: config.layers,
@@ -129,7 +130,9 @@ export function createMap(data, options = {}) {
                 key,
                 next.features[key],
             ]));
+        let committed = false;
         element.applyPresentation({ ...patch, ...('appearance' in patch ? { appearance: next.appearance } : {}) }, () => {
+            committed = true;
             config = next;
             if (hasFeatures)
                 element.setFeatures(features);
@@ -138,6 +141,14 @@ export function createMap(data, options = {}) {
             if (hasControls)
                 element.setControls(controls);
         }, () => !destroyed && revision === configurationRevision);
+        return committed && !destroyed && revision === configurationRevision;
+    }
+    function updateView(patch, options = {}) {
+        assertOptions(options, 'view update', ['resetView']);
+        if (options.resetView !== undefined && typeof options.resetView !== 'boolean')
+            throw new TypeError('resetView must be a boolean.');
+        if (configure(patch) && options.resetView !== false)
+            element.resetView();
     }
     return Object.freeze({
         element,
@@ -146,7 +157,9 @@ export function createMap(data, options = {}) {
         get destroyed() {
             return destroyed;
         },
-        configure: use(configure),
+        configure: use((patch) => {
+            configure(patch);
+        }),
         getConfiguration: use(snapshot),
         getResolvedConfiguration: use(resolved),
         getCapabilities: use(capabilities),
@@ -180,6 +193,41 @@ export function createMap(data, options = {}) {
         }),
         setMarkers: use(element.setMarkers),
         setOverlays: use(element.setOverlays),
+        selectFeature: use((reference, options) => {
+            assertOptions(reference, 'feature reference');
+            if (!['marker', 'neighborhood', 'district'].includes(reference.kind))
+                throw new TypeError('Unknown feature kind.');
+            assertOptions(reference, 'feature reference', reference.kind === 'marker'
+                ? ['kind', 'id']
+                : reference.kind === 'neighborhood'
+                    ? ['kind', 'id', 'source']
+                    : ['kind', 'id', 'year']);
+            if (reference.kind === 'district') {
+                if (reference.id !== null &&
+                    (typeof reference.id !== 'number' || !Number.isFinite(reference.id)))
+                    throw new TypeError('District IDs must be finite numbers or null.');
+                if (![2002, 2012, 2022].includes(reference.year))
+                    throw new RangeError('Unknown district year.');
+                if (reference.year !== element.getMapState().year || !yearList.includes(reference.year))
+                    return false;
+                return element.selectDistrict(reference.id, options);
+            }
+            if (reference.id !== null && (typeof reference.id !== 'string' || !reference.id))
+                throw new TypeError('Feature IDs must be nonempty strings or null.');
+            if (reference.kind === 'marker')
+                return element.selectMarker(reference.id, options);
+            if (!['realtor', 'sf-find', 'analysis'].includes(reference.source))
+                throw new RangeError('Unknown neighborhood source.');
+            if (reference.source !== element.getMapState().source ||
+                !sourceList.includes(reference.source))
+                return false;
+            const feature = reference.id === null
+                ? null
+                : data.neighborhoods[reference.source]?.features.find((entry) => entry.id === reference.id);
+            if (reference.id !== null && !feature)
+                return false;
+            return element.selectNeighborhood(feature?.id ?? null, options);
+        }),
         selectMarker: use(element.selectMarker),
         getSelectedMarker: use(element.getSelectedMarker),
         selectNeighborhood: use(element.selectNeighborhood),
@@ -193,17 +241,10 @@ export function createMap(data, options = {}) {
         setDistrictStyle: use((style) => {
             configure({ appearance: { districtStyle: style } });
         }),
-        setSource: use((...args) => {
-            configurationRevision++;
-            element.setSource(...args);
-        }),
-        setMode: use((...args) => {
-            configurationRevision++;
-            element.setMode(...args);
-        }),
-        setLabels: use((...args) => {
-            configurationRevision++;
-            element.setLabels(...args);
+        setSource: use((source, options) => updateView({ source }, options)),
+        setMode: use((mode, options) => updateView({ mode }, options)),
+        setLabels: use((labels) => {
+            configure({ labels });
         }),
         setTouchNavigation: use(element.setTouchNavigation),
         projectToScreen: use(element.projectToScreen),

package/dist/src/static.d.ts

@@ -1,15 +1,18 @@
+import type { InteractiveSFMapData } from './explorer-data.js';
 import { type SFMapData } from './map-core.js';
 import type { SFMapOptions } from './types.js';
+/** Either compact static geography or the same source-aware geography used by createMap. */
+export type StaticMapInput = SFMapData | InteractiveSFMapData;
 export type { DistrictRowData, SFMapData as StaticMapData } from './map-core.js';
 export type { DistrictStyle, DistrictYear, SFMapOptions as StaticMapOptions, StaticMapAppearance, StaticMapLayers, } from './types.js';
 /** Server-safe SVG rendering with explicit data; returns SVG plus projection helpers. */
-export declare function renderMap(data: SFMapData, options?: SFMapOptions): {
+export declare function renderMap(data: StaticMapInput, options?: SFMapOptions): {
     svg: string;
     project: (coordinates: import("../data/types.js").Position) => [number, number];
     viewBox: [number, number, number, number];
 };
 /** Project canonical layer geometry without constructing an SVG string. */
-export declare function getLayerPaths(data: SFMapData, options?: SFMapOptions): {
+export declare function getLayerPaths(data: StaticMapInput, options?: SFMapOptions): {
     year: import("./types.js").DistrictYear;
     viewBox: [number, number, number, number];
     project: (coordinates: import("../data/types.js").Position) => [number, number];

package/dist/src/static.js

@@ -4,11 +4,37 @@ import { createSFMapWithData, getLayerPathsWithData } from './map-core.js';
 import { assertOptions } from './validation.js';
 /** Server-safe SVG rendering with explicit data; returns SVG plus projection helpers. */
 export function renderMap(data, options = {}) {
-    return createSFMapWithData(expandStaticOptions(options), data);
+    const prepared = expandStaticOptions(options);
+    return createSFMapWithData(prepared, staticInput(data, prepared));
 }
 /** Project canonical layer geometry without constructing an SVG string. */
 export function getLayerPaths(data, options = {}) {
-    return getLayerPathsWithData(expandStaticOptions(options), data);
+    const prepared = expandStaticOptions(options);
+    return getLayerPathsWithData(prepared, staticInput(data, prepared));
+}
+/** Borrow immutable geometry, deriving only the renderer's lightweight neighborhood rows. */
+function staticInput(data, options) {
+    if (options.source !== undefined && !['realtor', 'sf-find', 'analysis'].includes(options.source))
+        throw new RangeError('Unknown neighborhood source.');
+    if (!('map' in data)) {
+        if (options.source !== undefined)
+            throw new TypeError('source requires source-aware MapData; compact StaticMapData already chooses its geography.');
+        return data;
+    }
+    const source = options.source ??
+        ['realtor', 'sf-find', 'analysis'].find((candidate) => !!data.neighborhoods[candidate]);
+    if (source === undefined)
+        return data.map;
+    const collection = data.neighborhoods[source];
+    if (!collection)
+        throw new RangeError(`No ${source} neighborhood dataset was supplied.`);
+    return {
+        ...data.map,
+        neighborhoods: collection.features.map(({ geometry, properties }) => ({
+            name: properties.sourceName,
+            geometry,
+        })),
+    };
 }
 /** Grouped keys override flat compatibility keys; omitted keys preserve renderer defaults. */
 function expandStaticOptions(options) {

package/dist/src/types.d.ts

@@ -41,6 +41,8 @@ export interface SFMapOptions {
     height?: number;
     padding?: number;
     year?: DistrictYear;
+    /** Select a supplied neighborhood definition when rendering source-aware MapData. */
+    source?: NeighborhoodSource;
     districtLines?: boolean;
     neighborhoodLines?: boolean;
     districtFills?: boolean;
@@ -251,4 +253,4 @@ export interface NeighborhoodExplorerElement extends HTMLElement {
 export interface TransitAnimationElement extends HTMLElement {
     destroy(): void;
 }
-export type { MapAppearance, MapCamera, MapCapabilities, MapConfiguration, MapConfigurationSnapshot, MapController, MapControls, MapEvents, MapOptions, MapSelectionChange, ResolvedMapConfiguration, } from './controller-types.js';
+export type { MapAppearance, MapCamera, MapCapabilities, MapConfiguration, MapConfigurationSnapshot, MapController, MapControls, MapEvents, MapFeatureReference, MapOptions, MapSelectionChange, MapViewUpdateOptions, ResolvedMapConfiguration, } from './controller-types.js';

package/docs/API.md

@@ -6,6 +6,8 @@ and event types are exported by [src/api.ts](../src/api.ts) and defined in
 
 ## Static maps
 
+Static maps accept compact `StaticMapData` or the same source-aware `MapData` as interactive maps. With `MapData`, `source` selects a supplied neighborhood definition; SFAR realtor is preferred by default, followed by SF Find and analysis when available. A requested unavailable source throws before styling callbacks run. Compact `StaticMapData` already chooses its neighborhoods, so it rejects a `source` option. Both data shapes retain the static renderer defaults.
+
 Static maps accept the same grouped presentation vocabulary as interactive maps:
 
 ```ts
@@ -47,7 +49,7 @@ District style callbacks are evaluated once per district at construction and on
 
 ## Live configuration and inspection
 
-`map.configure({ appearance, mode, source, year, labels, layers, features, controls })` updates an existing map. Appearance updates preserve the camera, selections, retained marker nodes, and keyboard focus. Mode/source changes through `configure` preserve the camera; existing `setMode` and `setSource` convenience methods retain their reset behavior. Switching neighborhood source clears the neighborhood selection. Changing district year retains a selected district when it exists in the new year. Unsupported datasets, invalid appearance values, and invalid district-style callback results fail during preparation before commit. A reentrant styling callback can supersede the pending patch.
+`map.configure({ appearance, mode, source, year, labels, layers, features, controls })` updates an existing map. Appearance updates preserve the camera, selections, retained marker nodes, and keyboard focus. Mode/source changes through `configure` preserve the camera; the `setMode(mode, { resetView: false })` and `setSource(source, { resetView: false })` convenience methods use the same atomic update path and preserve the camera. Omit the second argument to retain their existing reset behavior. Invalid view-update options fail before changing configuration. Switching neighborhood source clears the neighborhood selection. Changing district year retains a selected district when it exists in the new year. Unsupported datasets, invalid appearance values, and invalid district-style callback results fail during preparation before commit. A reentrant styling callback can supersede the pending patch.
 
 Appearance token objects (`colors`, `style`, `labelStyle`, `labelSize`, `areaStyle`) merge supplied keys; other appearance properties replace. Omitted keys retain their value, an explicit `undefined` property removes that override, and `appearance: undefined` resets the whole appearance group. Feature objects retain their existing replacement semantics. Mode/source/year/labels ignore `undefined`; reset them with an explicit value. Patch types explicitly permit these resets with TypeScript’s `exactOptionalPropertyTypes` enabled.
 
@@ -63,7 +65,7 @@ const effective = map.getResolvedConfiguration();
 const available = map.getCapabilities();
 ```
 
-`getConfiguration()` returns detached feature, layer, control, and appearance overrides; district style callbacks retain their function identity. `getResolvedConfiguration()` adds the current mode, source, year and master labels and resolves **layer switches** through mode defaults, available data, and the master label switch. Appearance/control fields remain overrides. It does not claim that every label is visible: zoom and collision filtering still apply. `getCapabilities()` returns supplied `sources`, usable district `years`, and layer data availability for the current source/year, independent of visibility overrides. These reads throw after destruction.
+`getConfiguration()` returns the current mode, source, year and master labels, together with detached feature, layer, control, and appearance overrides; district style callbacks retain their function identity. `getResolvedConfiguration()` adds the current mode, source, year and master labels and resolves **layer switches** through mode defaults, available data, and the master label switch. Appearance/control fields remain overrides. It does not claim that every label is visible: zoom and collision filtering still apply. `getCapabilities()` returns supplied `sources`, usable district `years`, and layer data availability for the current source/year, independent of visibility overrides. These reads throw after destruction.
 
 ## Common selection event
 
@@ -78,6 +80,18 @@ map.on('selectionchange', (event) => {
 
 `kind` is `marker`, `neighborhood`, or `district`. `current` and `previous` are detached selection snapshots or `null`. The event follows committed selection changes, including clearing and a changed district vintage; it does not represent every activation. Existing `markerchange`, `neighborhoodchange`, and `districtchange` events remain supported.
 
+## Source-aware feature selection
+
+`selectFeature(reference, options)` accepts one typed identity for each selectable kind:
+
+```ts
+map.selectFeature({ kind: 'marker', id: 'ferry' }, { fit: false });
+map.selectFeature({ kind: 'neighborhood', source: 'realtor', id: 'inner-mission' });
+map.selectFeature({ kind: 'district', year: 2022, id: 3 });
+```
+
+Neighborhood IDs are exact source-scoped feature IDs, rather than display names or aliases. District identity includes the boundary year. This operation returns `false` for a missing feature or a source/year other than the map's current supplied geography; it never silently switches definitions or years. Choose geography through `configure` first. An `id` of `null` clears that kind in the referenced current geography. Malformed references throw. Existing `selectMarker`, `selectNeighborhood`, and `selectDistrict` shortcuts remain supported.
+
 ## Coordinates and units
 
 GeoJSON and static projection inputs use `[longitude, latitude]` in WGS84; markers use `{ lng, lat }`. Static `project` returns SVG units. `projectToScreen(lng, lat)` returns pixels relative to the mounted canvas. Camera viewports and pan deltas use the fixed 800 × 800 projected map space, independent of canvas size. Marker radius uses screen pixels in browser maps and SVG units in static output.

package/docs/api-audit.md

@@ -19,7 +19,8 @@ unbounded geographic data can never fail.
 | Clustering and selected/focused markers | Selected/focused pins remain individually reachable. Coincident alternatives remain available through the chooser. |
 | Marker entrance and reduced motion | Entrances are optional, independent of camera motion, and cancel on preference changes or disposal. Stable IDs avoid repeated entrances on filtering. |
 | Hiding touch control while gestures are enabled | Returns touch scrolling to the page. Other toolbar controls remain independent. |
-| Runtime patch omitted/false/undefined | Omitted retains; false disables; undefined resets to the default. Nested feature objects replace, rather than deep-merge. |
+| Convenience mode/source setters | Share the atomic configuration path. `{ resetView: false }` preserves the camera; omitted options retain the historic reset. Invalid options and unavailable geography leave state unchanged. |
+| Runtime patch omitted/false/undefined | Omitted retains; false disables boolean switches; undefined removes group/key overrides. Top-level mode/source/year/labels set to undefined retain their current values. Nested feature objects replace, rather than deep-merge. |
 | Compact shell and full attribution | Rejected before replacement. Use `createGuideController` for full attribution. Control overrides are honored and may deliberately alter layout. |
 | District style callbacks | Prepare and copy every style before committing. Hover/selection reuse the results; call `setDistrictStyle()` to refresh changed external data. Reentrant updates or destruction supersede pending work. |
 | Rapid district year changes | Both outgoing layers are tracked, inert, and removed on interruption, completion, reduced-motion changes, or destruction. Zero duration creates no transition copies. |
@@ -29,6 +30,8 @@ unbounded geographic data can never fail.
 | Guide controllers and compatibility factories | `createGuideController`/`mountGuideController` share grouped options and lifecycle with `createMap`. Existing element factories retain flat options and their return types. |
 | Layer hidden and bundle cost | Visibility never unloads imported geography. Use narrow entrypoints or data injection to save bytes. |
 
+Live appearance patches prepare values, district styles and source replacement before committing; token objects merge by key. Styling callbacks that issue a newer presentation update supersede the pending patch. Resolved layer reads distinguish visibility settings from data availability and from zoom/collision label filtering. The additive selection envelope preserves existing event contracts.
+
 ## Failure boundaries and regression evidence
 
 | Surface | Adversarial checks and behavior |
@@ -70,11 +73,6 @@ Exercise enable/disable round trips and callbacks that synchronously request a
 second update. Add published-type and bundle regressions when the import graph or
 public types change. Update this matrix when introducing a new interaction.
 
-## Verification for version 3
+## Verification
 
-- `pnpm check` covers Node regressions, types, lint, catalog topology, and bundle budgets.
-- `pnpm test:stories:coverage` runs Chromium stories and reports browser coverage.
-- `pnpm demo`, `pnpm build-storybook`, `pnpm test:package`, and `pnpm test:visual` cover examples, rendered stories, packed consumer imports, and reviewed map screenshots.
-- The packed consumer asserts removed compatibility entry points are absent.
-
-Live appearance patches prepare values, district styles and source replacement before committing; token objects merge by key. Styling callbacks that issue a newer presentation update supersede the pending patch. Resolved layer reads distinguish visibility settings from data availability and from zoom/collision label filtering. The additive selection envelope preserves existing event contracts.
+Follow the [validation and release runbook](https://github.com/kahwee/sf-map-svg/blob/main/docs/maintenance.md#validation-by-change). The packed consumer also asserts that removed compatibility entry points remain absent.

package/docs/consumer-integration.md

@@ -1,23 +1,47 @@
-# Consumer integration
+# Embedding and progressive enhancement
 
-Use the root controller and import geographic data explicitly. The [migration guide](migration-v3.md) maps removed v2 imports to supported calls.
+For basic mounting, events and cleanup, start with the [developer guide](developer-guide.md). The root controller takes explicit geography; the guide entry offers a smaller preset with the same grouped `configure()`, `camera`, `on()`, and `destroy()` contract. See the [migration guide](migration-v3.md) for removed v2 imports.
 
-For a compact browser guide:
+## Render a guide before JavaScript loads
+
+On the server or in a build step, render a compact frame:
 
 ```ts
-import { createGuideController } from '@kahwee/sf-map-svg/guide';
+import { createGuideShell } from '@kahwee/sf-map-svg/guide/static';
+
+const markup = createGuideShell({ title: 'Explore San Francisco' });
+// Insert markup into your server-rendered HTML.
+```
+
+The shell uses an 800 × 800 projection with 28 units of padding, matching the interactive map. Use `createGuideSVG()` for custom dimensions. Rendering is offline, with zero runtime dependencies.
+
+## Enhance the existing frame
+
+In your browser entry, mount the controller into that shell:
 
-const map = createGuideController({
+```ts
+import { mountGuideController } from '@kahwee/sf-map-svg/guide';
+
+const shell = document.querySelector<HTMLElement>('.sf-guide-shell');
+if (!shell) throw new Error('Missing guide shell');
+const guide = mountGuideController(shell, {
+  attribution: 'compact',
   features: { motion: { duration: 400 }, markerEntrance: true },
   appearance: { theme: 'transit' },
 });
-document.querySelector('#map')?.append(map.element);
-// Dispose when the containing view unmounts.
-map.destroy();
+
+// Call before your application removes the containing view.
+function disposeGuide() {
+  guide.destroy();
+}
 ```
 
-The guide controller uses the same `configure()`, `camera`, `on()`, and `destroy()` contract as `createMap()`. Motion is opt-in and follows the user's reduced-motion preference. For explicit data composition, `createMap(guideMapData, guideOptions)` remains available using `/guide/data` and `/presets`.
+Compact attribution is required for an existing shell. Invalid configuration leaves its static frame intact. `destroy()` disposes listeners and animation work; your application owns removal of the containing view. Motion is opt-in and follows reduced-motion preferences.
+
+For a new browser-only guide, use `createGuideController()` and mount its `.element` as shown in the developer guide. Existing `createGuideMap()` and `mountGuideMap()` retain their augmented-element return types and flat options for compatibility.
+
+## Choose the data boundary
 
-To progressively enhance server-rendered `createGuideShell()` markup, use `mountGuideController(shell, options)` from `/guide`. It returns the controller and requires compact attribution. Invalid configuration leaves the static frame intact. Destroy the controller when unmounting. Existing `createGuideMap()` and `mountGuideMap()` return their original augmented elements and accept flat options for compatibility.
+`createMap(guideMapData, guideOptions)` remains available through `/guide/data` and `/presets`. For server rendering, pass `guideMapData.map` or `/data/static` to `renderMap()`. Use `/data/full` when interactive lookup collections are needed. The guide's detailed geography loads only on an explicit `loadGuideDetailedData()` call; enabling a layer does not download it.
 
-For server rendering, import `renderMap` from the root and pass `guideMapData.map`, `staticMapData` from `/data/static`, or another explicit `StaticMapData`. Import `/data/full` when interactive lookup collections are also required. All rendering stays offline and has zero runtime dependencies. The guide's detailed geography loads only when `loadGuideDetailedData()` is called.
+See the [exact API contract](API.md), [worked examples](EXAMPLES.md), and [bundle measurements](guide-bundle-report.md).

package/docs/developer-guide.md

@@ -80,7 +80,7 @@ function disposeMap() {
 | Visible labels | On | On, subject to zoom/collisions |
 | Motion features | Static animation off | Off; opt in via `features` |
 
-A layer switch does not download missing geography. `fullMapData` has `.map` for static rendering and separate lookup collections for interactive use. `staticMapData` is already a static data object. Use `renderMap(guideMapData.map, options)`, not `renderMap(guideMapData, options)`.
+A layer switch does not download missing geography. `fullMapData` has `.map` for static rendering and separate lookup collections for interactive use. `staticMapData` is already a static data object. Use `renderMap(guideMapData, options)` or `renderMap(fullMapData, { source: 'sf-find' })` to share source-aware geography with the browser controller. Passing `.map` remains supported as compact static geography; it already chooses its neighborhoods and does not accept a `source` option.
 
 SFAR realtor neighborhoods are the default when supplied. If only an alternative collection is supplied, the controller selects that available source. Choose `source` explicitly when comparing definitions. Sources retain separate identities; they are not interchangeable polygons.
 
@@ -88,7 +88,7 @@ SFAR realtor neighborhoods are the default when supplied. If only an alternative
 
 | Change | Call |
 | --- | --- |
-| Layers, controls, behaviors | `map.configure({ layers, controls, features, appearance, mode, source, year, labels })` |
+| Presentation, layers, controls, behaviors | `map.configure({ layers, controls, features, appearance, mode, source, year, labels })` |
 | Map mode or neighborhood source | `map.setMode(mode)`, `map.setSource(source)` |
 | District boundaries or choropleth | `map.setDistrictYear(year)`, `map.setDistrictStyle(callback)` |
 | Master text visibility | `map.setLabels(visible)` |
@@ -96,6 +96,8 @@ SFAR realtor neighborhoods are the default when supplied. If only an alternative
 | Camera | `map.camera.set/pan/zoom/fit/reset(...)` |
 | Palette, typography, control styling | `map.configure({ appearance })`; retains camera, selection and focus |
 
+Appearance token objects merge by key; `undefined` removes an override and `appearance: undefined` resets the group. Static maps accept grouped `layers` and the shared `appearance` keys (`theme`, `colors`, `districtStyle`) too. See [the API contract](API.md#live-configuration-and-inspection) and [the design playground](https://kahwee.github.io/sf-map-svg/playground.html).
+
 `configure` merges supplied keys; omitted keys keep their existing values. Set a layer or control key to `undefined` to remove its override. Set a whole group to `undefined` to reset that group. Set a feature to `false` to disable it. Explicit layer overrides keep winning after mode changes.
 
 ```ts
@@ -105,7 +107,7 @@ map.configure({ features: { motion: false } });
 map.configure({ layers: undefined }); // clear all explicit layer overrides
 ```
 
-`getConfiguration()` returns a detached snapshot of these groups, including explicit layer overrides. It is not a full serialization of mode, source, year, camera, or selection. Appearance overrides are included. Use `getResolvedConfiguration()` for current mode/source/year/labels and effective layer switches, and `getCapabilities()` for supplied geography. Invalid configuration patches leave the current map unchanged.
+`getConfiguration()` returns current mode/source/year/labels and a detached snapshot of the presentation groups, including explicit layer and appearance overrides. Camera and selection remain separate runtime state. Use `getResolvedConfiguration()` for current mode/source/year/labels and effective layer switches, and `getCapabilities()` for supplied geography. Invalid configuration patches leave the current map unchanged. Convenience methods use the same atomic update path: pass `map.setMode(mode, { resetView: false })` or `map.setSource(source, { resetView: false })` to keep the camera. Their default still resets the view.
 
 ## Markers, routes and camera coordinates
 
@@ -135,5 +137,3 @@ The package declarations are the exact type contract for your installed version.
 The generated `llms.txt` index links to Markdown documentation; `llms-full.txt` combines the guides and type contracts into one file. Both are built from the same package selected for the site. Local previews are labeled as working-tree docs. Released builds use the installed npm package's docs and declarations.
 
 See [API options](API.md), [worked examples](EXAMPLES.md), [consumer integration](consumer-integration.md), and [v3 migration](migration-v3.md).
-
-Appearance token objects merge by key; `undefined` removes an override and `appearance: undefined` resets the group. Static maps accept grouped `layers` and the shared `appearance` keys (`theme`, `colors`, `districtStyle`) too. See [the API contract](API.md#live-configuration-and-inspection) and [the design playground](https://kahwee.github.io/sf-map-svg/playground.html).

package/llms-full.txt

@@ -2,19 +2,19 @@
 
 > Offline San Francisco SVG maps with explicit geographic imports, no runtime dependencies, static rendering, and a browser controller.
 
-@kahwee/sf-map-svg 4.2.0 · local working tree. Node >=24.0.0 for server rendering; browsers need a DOM and a JSON-capable bundler.
+@kahwee/sf-map-svg 4.3.0 · local working tree. Node >=24.0.0 for server rendering; browsers need a DOM and a JSON-capable bundler.
 
 These are working-tree docs. Unreleased changelog entries may describe APIs absent from npm; verify the installed version before copying them.
 
 Use renderMap(data, options) for SVG strings; createMap(data, options) returns a controller. Mount map.element and destroy it on unmount. Choose mode explicitly: createMap defaults to basemap. Geography is separate; staticMapData and fullMapData have different shapes.
 
-<!-- Generated from README.md; @kahwee/sf-map-svg 4.2.0 · local working tree. -->
+<!-- Generated from README.md; @kahwee/sf-map-svg 4.3.0 · local working tree. -->
 
 # SF Map SVG
 
 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.
 
-[Design playground](https://kahwee.github.io/sf-map-svg/playground.html) · [Live examples](https://kahwee.github.io/sf-map-svg/examples.html) · [Storybook source](https://github.com/kahwee/sf-map-svg/blob/main/stories/) · [Geographic sources](https://github.com/kahwee/sf-map-svg/blob/main/SOURCES.md) · [v3 migration](https://github.com/kahwee/sf-map-svg/blob/main/docs/migration-v3.md)
+[Getting started](https://github.com/kahwee/sf-map-svg/blob/main/docs/developer-guide.md) · [API reference](https://github.com/kahwee/sf-map-svg/blob/main/docs/API.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](https://github.com/kahwee/sf-map-svg/blob/main/stories/) · [Geographic sources](https://github.com/kahwee/sf-map-svg/blob/main/SOURCES.md) · [v3 migration](https://github.com/kahwee/sf-map-svg/blob/main/docs/migration-v3.md)
 
 ## Install
 
@@ -57,11 +57,16 @@ const map = createMap(fullMapData, {
   features: { motion: true },
   appearance: { theme: 'districts' },
 });
-document.querySelector('#map')?.append(map.element);
+const host = document.querySelector('#map');
+if (!host) throw new Error('Missing #map container');
+host.append(map.element);
 map.on('neighborhoodchange', ({ name }) => console.log(name));
 map.camera.zoom(1.5);
-// When the view is removed:
-map.destroy();
+// Call when your application removes this view.
+function disposeMap() {
+  map.destroy();
+  map.element.remove();
+}
 ```
 
 `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.
@@ -78,20 +83,11 @@ Call `destroy()` when removing an interactive map.
 
 Canonical geography is in [`data/`](https://github.com/kahwee/sf-map-svg/blob/main/data/README.md), with provenance in [`SOURCES.md`](https://github.com/kahwee/sf-map-svg/blob/main/SOURCES.md). The public `/data` entry exposes lookup, catalog, district maps, and source-specific neighborhood collections. These are deeply frozen; clone before editing.
 
-```sh
-pnpm install --frozen-lockfile
-pnpm check
-pnpm demo
-pnpm build-storybook
-pnpm test:stories:coverage
-pnpm test:package
-```
-
-The [contributing guide](https://github.com/kahwee/sf-map-svg/blob/main/CONTRIBUTING.md) explains the geographic and release checks. If you are upgrading from v2, follow the [v3 migration guide](https://github.com/kahwee/sf-map-svg/blob/main/docs/migration-v3.md).
+Install with `pnpm install --frozen-lockfile`. See the [contributing guide](https://github.com/kahwee/sf-map-svg/blob/main/CONTRIBUTING.md) for architecture and the [validation and release runbook](https://github.com/kahwee/sf-map-svg/blob/main/docs/maintenance.md) for checks, browser inspection, and publishing. If you are upgrading from v2, follow the [v3 migration guide](https://github.com/kahwee/sf-map-svg/blob/main/docs/migration-v3.md).
 
 ---
 
-<!-- Generated from docs/developer-guide.md; @kahwee/sf-map-svg 4.2.0 · local working tree. -->
+<!-- Generated from docs/developer-guide.md; @kahwee/sf-map-svg 4.3.0 · local working tree. -->
 
 # Developer guide
 
@@ -175,7 +171,7 @@ function disposeMap() {
 | Visible labels | On | On, subject to zoom/collisions |
 | Motion features | Static animation off | Off; opt in via `features` |
 
-A layer switch does not download missing geography. `fullMapData` has `.map` for static rendering and separate lookup collections for interactive use. `staticMapData` is already a static data object. Use `renderMap(guideMapData.map, options)`, not `renderMap(guideMapData, options)`.
+A layer switch does not download missing geography. `fullMapData` has `.map` for static rendering and separate lookup collections for interactive use. `staticMapData` is already a static data object. Use `renderMap(guideMapData, options)` or `renderMap(fullMapData, { source: 'sf-find' })` to share source-aware geography with the browser controller. Passing `.map` remains supported as compact static geography; it already chooses its neighborhoods and does not accept a `source` option.
 
 SFAR realtor neighborhoods are the default when supplied. If only an alternative collection is supplied, the controller selects that available source. Choose `source` explicitly when comparing definitions. Sources retain separate identities; they are not interchangeable polygons.
 
@@ -183,7 +179,7 @@ SFAR realtor neighborhoods are the default when supplied. If only an alternative
 
 | Change | Call |
 | --- | --- |
-| Layers, controls, behaviors | `map.configure({ layers, controls, features, appearance, mode, source, year, labels })` |
+| Presentation, layers, controls, behaviors | `map.configure({ layers, controls, features, appearance, mode, source, year, labels })` |
 | Map mode or neighborhood source | `map.setMode(mode)`, `map.setSource(source)` |
 | District boundaries or choropleth | `map.setDistrictYear(year)`, `map.setDistrictStyle(callback)` |
 | Master text visibility | `map.setLabels(visible)` |
@@ -191,6 +187,8 @@ SFAR realtor neighborhoods are the default when supplied. If only an alternative
 | Camera | `map.camera.set/pan/zoom/fit/reset(...)` |
 | Palette, typography, control styling | `map.configure({ appearance })`; retains camera, selection and focus |
 
+Appearance token objects merge by key; `undefined` removes an override and `appearance: undefined` resets the group. Static maps accept grouped `layers` and the shared `appearance` keys (`theme`, `colors`, `districtStyle`) too. See [the API contract](https://github.com/kahwee/sf-map-svg/blob/main/docs/API.md#live-configuration-and-inspection) and [the design playground](https://kahwee.github.io/sf-map-svg/playground.html).
+
 `configure` merges supplied keys; omitted keys keep their existing values. Set a layer or control key to `undefined` to remove its override. Set a whole group to `undefined` to reset that group. Set a feature to `false` to disable it. Explicit layer overrides keep winning after mode changes.
 
 ```ts
@@ -200,7 +198,7 @@ map.configure({ features: { motion: false } });
 map.configure({ layers: undefined }); // clear all explicit layer overrides
 ```
 
-`getConfiguration()` returns a detached snapshot of these groups, including explicit layer overrides. It is not a full serialization of mode, source, year, camera, or selection. Appearance overrides are included. Use `getResolvedConfiguration()` for current mode/source/year/labels and effective layer switches, and `getCapabilities()` for supplied geography. Invalid configuration patches leave the current map unchanged.
+`getConfiguration()` returns current mode/source/year/labels and a detached snapshot of the presentation groups, including explicit layer and appearance overrides. Camera and selection remain separate runtime state. Use `getResolvedConfiguration()` for current mode/source/year/labels and effective layer switches, and `getCapabilities()` for supplied geography. Invalid configuration patches leave the current map unchanged. Convenience methods use the same atomic update path: pass `map.setMode(mode, { resetView: false })` or `map.setSource(source, { resetView: false })` to keep the camera. Their default still resets the view.
 
 ## Markers, routes and camera coordinates
 
@@ -231,11 +229,9 @@ The generated `llms.txt` index links to Markdown documentation; `llms-full.txt`
 
 See [API options](https://github.com/kahwee/sf-map-svg/blob/main/docs/API.md), [worked examples](https://github.com/kahwee/sf-map-svg/blob/main/docs/EXAMPLES.md), [consumer integration](https://github.com/kahwee/sf-map-svg/blob/main/docs/consumer-integration.md), and [v3 migration](https://github.com/kahwee/sf-map-svg/blob/main/docs/migration-v3.md).
 
-Appearance token objects merge by key; `undefined` removes an override and `appearance: undefined` resets the group. Static maps accept grouped `layers` and the shared `appearance` keys (`theme`, `colors`, `districtStyle`) too. See [the API contract](https://github.com/kahwee/sf-map-svg/blob/main/docs/API.md#live-configuration-and-inspection) and [the design playground](https://kahwee.github.io/sf-map-svg/playground.html).
-
 ---
 
-<!-- Generated from docs/API.md; @kahwee/sf-map-svg 4.2.0 · local working tree. -->
+<!-- Generated from docs/API.md; @kahwee/sf-map-svg 4.3.0 · local working tree. -->
 
 # Map options and lifecycle
 
@@ -245,6 +241,8 @@ and event types are exported by [src/api.ts](https://github.com/kahwee/sf-map-sv
 
 ## Static maps
 
+Static maps accept compact `StaticMapData` or the same source-aware `MapData` as interactive maps. With `MapData`, `source` selects a supplied neighborhood definition; SFAR realtor is preferred by default, followed by SF Find and analysis when available. A requested unavailable source throws before styling callbacks run. Compact `StaticMapData` already chooses its neighborhoods, so it rejects a `source` option. Both data shapes retain the static renderer defaults.
+
 Static maps accept the same grouped presentation vocabulary as interactive maps:
 
 ```ts
@@ -286,7 +284,7 @@ District style callbacks are evaluated once per district at construction and on
 
 ## Live configuration and inspection
 
-`map.configure({ appearance, mode, source, year, labels, layers, features, controls })` updates an existing map. Appearance updates preserve the camera, selections, retained marker nodes, and keyboard focus. Mode/source changes through `configure` preserve the camera; existing `setMode` and `setSource` convenience methods retain their reset behavior. Switching neighborhood source clears the neighborhood selection. Changing district year retains a selected district when it exists in the new year. Unsupported datasets, invalid appearance values, and invalid district-style callback results fail during preparation before commit. A reentrant styling callback can supersede the pending patch.
+`map.configure({ appearance, mode, source, year, labels, layers, features, controls })` updates an existing map. Appearance updates preserve the camera, selections, retained marker nodes, and keyboard focus. Mode/source changes through `configure` preserve the camera; the `setMode(mode, { resetView: false })` and `setSource(source, { resetView: false })` convenience methods use the same atomic update path and preserve the camera. Omit the second argument to retain their existing reset behavior. Invalid view-update options fail before changing configuration. Switching neighborhood source clears the neighborhood selection. Changing district year retains a selected district when it exists in the new year. Unsupported datasets, invalid appearance values, and invalid district-style callback results fail during preparation before commit. A reentrant styling callback can supersede the pending patch.
 
 Appearance token objects (`colors`, `style`, `labelStyle`, `labelSize`, `areaStyle`) merge supplied keys; other appearance properties replace. Omitted keys retain their value, an explicit `undefined` property removes that override, and `appearance: undefined` resets the whole appearance group. Feature objects retain their existing replacement semantics. Mode/source/year/labels ignore `undefined`; reset them with an explicit value. Patch types explicitly permit these resets with TypeScript’s `exactOptionalPropertyTypes` enabled.
 
@@ -302,7 +300,7 @@ const effective = map.getResolvedConfiguration();
 const available = map.getCapabilities();
 ```
 
-`getConfiguration()` returns detached feature, layer, control, and appearance overrides; district style callbacks retain their function identity. `getResolvedConfiguration()` adds the current mode, source, year and master labels and resolves **layer switches** through mode defaults, available data, and the master label switch. Appearance/control fields remain overrides. It does not claim that every label is visible: zoom and collision filtering still apply. `getCapabilities()` returns supplied `sources`, usable district `years`, and layer data availability for the current source/year, independent of visibility overrides. These reads throw after destruction.
+`getConfiguration()` returns the current mode, source, year and master labels, together with detached feature, layer, control, and appearance overrides; district style callbacks retain their function identity. `getResolvedConfiguration()` adds the current mode, source, year and master labels and resolves **layer switches** through mode defaults, available data, and the master label switch. Appearance/control fields remain overrides. It does not claim that every label is visible: zoom and collision filtering still apply. `getCapabilities()` returns supplied `sources`, usable district `years`, and layer data availability for the current source/year, independent of visibility overrides. These reads throw after destruction.
 
 ## Common selection event
 
@@ -317,6 +315,18 @@ map.on('selectionchange', (event) => {
 
 `kind` is `marker`, `neighborhood`, or `district`. `current` and `previous` are detached selection snapshots or `null`. The event follows committed selection changes, including clearing and a changed district vintage; it does not represent every activation. Existing `markerchange`, `neighborhoodchange`, and `districtchange` events remain supported.
 
+## Source-aware feature selection
+
+`selectFeature(reference, options)` accepts one typed identity for each selectable kind:
+
+```ts
+map.selectFeature({ kind: 'marker', id: 'ferry' }, { fit: false });
+map.selectFeature({ kind: 'neighborhood', source: 'realtor', id: 'inner-mission' });
+map.selectFeature({ kind: 'district', year: 2022, id: 3 });
+```
+
+Neighborhood IDs are exact source-scoped feature IDs, rather than display names or aliases. District identity includes the boundary year. This operation returns `false` for a missing feature or a source/year other than the map's current supplied geography; it never silently switches definitions or years. Choose geography through `configure` first. An `id` of `null` clears that kind in the referenced current geography. Malformed references throw. Existing `selectMarker`, `selectNeighborhood`, and `selectDistrict` shortcuts remain supported.
+
 ## Coordinates and units
 
 GeoJSON and static projection inputs use `[longitude, latitude]` in WGS84; markers use `{ lng, lat }`. Static `project` returns SVG units. `projectToScreen(lng, lat)` returns pixels relative to the mounted canvas. Camera viewports and pan deltas use the fixed 800 × 800 projected map space, independent of canvas size. Marker radius uses screen pixels in browser maps and SVG units in static output.
@@ -325,7 +335,7 @@ Explore presentation options in the [live map design playground](https://kahwee.
 
 ---
 
-<!-- Generated from docs/EXAMPLES.md; @kahwee/sf-map-svg 4.2.0 · local working tree. -->
+<!-- Generated from docs/EXAMPLES.md; @kahwee/sf-map-svg 4.3.0 · local working tree. -->
 
 # Examples
 
@@ -436,35 +446,59 @@ For the controller and explicit data imports, see [the v3 migration guide](https
 
 ---
 
-<!-- Generated from docs/consumer-integration.md; @kahwee/sf-map-svg 4.2.0 · local working tree. -->
+<!-- Generated from docs/consumer-integration.md; @kahwee/sf-map-svg 4.3.0 · local working tree. -->
+
+# Embedding and progressive enhancement
 
-# Consumer integration
+For basic mounting, events and cleanup, start with the [developer guide](https://github.com/kahwee/sf-map-svg/blob/main/docs/developer-guide.md). The root controller takes explicit geography; the guide entry offers a smaller preset with the same grouped `configure()`, `camera`, `on()`, and `destroy()` contract. See the [migration guide](https://github.com/kahwee/sf-map-svg/blob/main/docs/migration-v3.md) for removed v2 imports.
 
-Use the root controller and import geographic data explicitly. The [migration guide](https://github.com/kahwee/sf-map-svg/blob/main/docs/migration-v3.md) maps removed v2 imports to supported calls.
+## Render a guide before JavaScript loads
 
-For a compact browser guide:
+On the server or in a build step, render a compact frame:
 
 ```ts
-import { createGuideController } from '@kahwee/sf-map-svg/guide';
+import { createGuideShell } from '@kahwee/sf-map-svg/guide/static';
+
+const markup = createGuideShell({ title: 'Explore San Francisco' });
+// Insert markup into your server-rendered HTML.
+```
+
+The shell uses an 800 × 800 projection with 28 units of padding, matching the interactive map. Use `createGuideSVG()` for custom dimensions. Rendering is offline, with zero runtime dependencies.
 
-const map = createGuideController({
+## Enhance the existing frame
+
+In your browser entry, mount the controller into that shell:
+
+```ts
+import { mountGuideController } from '@kahwee/sf-map-svg/guide';
+
+const shell = document.querySelector<HTMLElement>('.sf-guide-shell');
+if (!shell) throw new Error('Missing guide shell');
+const guide = mountGuideController(shell, {
+  attribution: 'compact',
   features: { motion: { duration: 400 }, markerEntrance: true },
   appearance: { theme: 'transit' },
 });
-document.querySelector('#map')?.append(map.element);
-// Dispose when the containing view unmounts.
-map.destroy();
+
+// Call before your application removes the containing view.
+function disposeGuide() {
+  guide.destroy();
+}
 ```
 
-The guide controller uses the same `configure()`, `camera`, `on()`, and `destroy()` contract as `createMap()`. Motion is opt-in and follows the user's reduced-motion preference. For explicit data composition, `createMap(guideMapData, guideOptions)` remains available using `/guide/data` and `/presets`.
+Compact attribution is required for an existing shell. Invalid configuration leaves its static frame intact. `destroy()` disposes listeners and animation work; your application owns removal of the containing view. Motion is opt-in and follows reduced-motion preferences.
+
+For a new browser-only guide, use `createGuideController()` and mount its `.element` as shown in the developer guide. Existing `createGuideMap()` and `mountGuideMap()` retain their augmented-element return types and flat options for compatibility.
+
+## Choose the data boundary
 
-To progressively enhance server-rendered `createGuideShell()` markup, use `mountGuideController(shell, options)` from `/guide`. It returns the controller and requires compact attribution. Invalid configuration leaves the static frame intact. Destroy the controller when unmounting. Existing `createGuideMap()` and `mountGuideMap()` return their original augmented elements and accept flat options for compatibility.
+`createMap(guideMapData, guideOptions)` remains available through `/guide/data` and `/presets`. For server rendering, pass `guideMapData.map` or `/data/static` to `renderMap()`. Use `/data/full` when interactive lookup collections are needed. The guide's detailed geography loads only on an explicit `loadGuideDetailedData()` call; enabling a layer does not download it.
 
-For server rendering, import `renderMap` from the root and pass `guideMapData.map`, `staticMapData` from `/data/static`, or another explicit `StaticMapData`. Import `/data/full` when interactive lookup collections are also required. All rendering stays offline and has zero runtime dependencies. The guide's detailed geography loads only when `loadGuideDetailedData()` is called.
+See the [exact API contract](https://github.com/kahwee/sf-map-svg/blob/main/docs/API.md), [worked examples](https://github.com/kahwee/sf-map-svg/blob/main/docs/EXAMPLES.md), and [bundle measurements](https://github.com/kahwee/sf-map-svg/blob/main/docs/guide-bundle-report.md).
 
 ---
 
-<!-- Generated from docs/migration-v3.md; @kahwee/sf-map-svg 4.2.0 · local working tree. -->
+<!-- Generated from docs/migration-v3.md; @kahwee/sf-map-svg 4.3.0 · local working tree. -->
 
 # Migrate to version 3
 
@@ -505,7 +539,7 @@ District styles are now prepared once per district on construction and style/yea
 
 ---
 
-<!-- Generated from SOURCES.md; @kahwee/sf-map-svg 4.2.0 · local working tree. -->
+<!-- Generated from SOURCES.md; @kahwee/sf-map-svg 4.3.0 · local working tree. -->
 
 # Geometry and provenance
 
@@ -689,7 +723,7 @@ display geometry, and no precinct polygons or raw workbook data are shipped.
 
 ---
 
-<!-- Generated from CHANGELOG.md; @kahwee/sf-map-svg 4.2.0 · local working tree. -->
+<!-- Generated from CHANGELOG.md; @kahwee/sf-map-svg 4.3.0 · local working tree. -->
 
 # Changelog
 
@@ -697,6 +731,15 @@ User-visible changes are recorded here. Unreleased entries describe changes on `
 
 ## Unreleased
 
+## 4.3.0 — 2026-10-02
+
+- Add `selectFeature` with typed marker, neighborhood source/ID and district year/ID references. Missing or mismatched identities preserve current geography and selection.
+- Accept the same source-aware map data in static and interactive rendering. Static maps can explicitly select a supplied neighborhood definition without manually rebuilding renderer rows; compact static inputs remain supported.
+- Include current mode, source, year and labels in configuration snapshots. Route controller mode/source/label setters through atomic configuration and support explicit camera preservation with `{ resetView: false }`.
+- Refine the Pages atlas opening with concise copy, a map ahead of statistics on phones, coordinate captions and three direct paths into designing, exploring and building. Improve shared theme-button touch targets and stack API reference records on phones while retaining table semantics.
+
+- Clarify the documentation paths, progressive enhancement and cleanup examples; consolidate browser validation and release instructions into one maintenance runbook. Check README and integration recipes against the packed package.
+
 ## 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.
@@ -1000,7 +1043,7 @@ consistent home, and makes animation and subscription ownership predictable.
 
 # Published type contracts
 
-@kahwee/sf-map-svg 4.2.0 · local working tree. These declarations are generated by TypeScript. Use package export paths, not the internal filenames below. Imported relative contracts are included for context, not as additional public entry points.
+@kahwee/sf-map-svg 4.3.0 · local working tree. These declarations are generated by TypeScript. Use package export paths, not the internal filenames below. Imported relative contracts are included for context, not as additional public entry points.
 
 | Public import | Declaration |
 | --- | --- |
@@ -1079,7 +1122,12 @@ export interface MapOptions extends Omit<NeighborhoodExplorerOptions, keyof MapF
     features?: MapFeatures;
     appearance?: MapAppearance | undefined;
 }
+/** Current geographic choices and detached presentation overrides; excludes camera and selection. */
 export interface MapConfigurationSnapshot {
+    mode: NonNullable<MapOptions['mode']>;
+    source: NeighborhoodSource;
+    year: DistrictYear;
+    labels: boolean;
     features: MapFeatures;
     /** Explicit overrides; absent values continue to follow the current mode. */
     layers: InteractiveLayers;
@@ -1113,6 +1161,19 @@ export type MapSelectionChange = {
     current: DistrictSelection | null;
     previous: DistrictSelection | null;
 };
+/** Dataset identity is explicit; selection never switches geography implicitly. */
+export type MapFeatureReference = {
+    kind: 'marker';
+    id: string | null;
+} | {
+    kind: 'neighborhood';
+    source: NeighborhoodSource;
+    id: string | null;
+} | {
+    kind: 'district';
+    year: DistrictYear;
+    id: number | null;
+};
 export interface MapEvents {
     /** Common selection envelope; existing change events retain their payloads. */
     selectionchange: MapSelectionChange;
@@ -1152,6 +1213,10 @@ export interface MapEvents {
     };
     mapresize: undefined;
 }
+/** Convenience setters retain their historic reset default; false preserves the camera. */
+export interface MapViewUpdateOptions {
+    resetView?: boolean;
+}
 export interface MapCamera {
     /** Fixed 800 × 800 projected space, not longitude/latitude. */
     get(): MapViewport;
@@ -1179,6 +1244,10 @@ export interface MapController {
     /** Reconcile stable IDs; retained markers preserve nodes, focus, and entrance animations. */
     setMarkers(markers: readonly MapMarker[]): void;
     setOverlays(overlays: readonly MapOverlay[]): void;
+    /** False for missing IDs or a source/year other than the current geography. */
+    selectFeature(reference: MapFeatureReference, options?: CameraOptions & {
+        fit?: boolean;
+    }): boolean;
     selectMarker(id: string | null, options?: CameraOptions & {
         fit?: boolean;
     }): boolean;
@@ -1193,8 +1262,8 @@ export interface MapController {
     getSelectedDistrict(): DistrictSelection | null;
     setDistrictYear(year: DistrictYear, options?: CameraOptions): void;
     setDistrictStyle(style: ((district: DistrictSelection['district']) => DistrictStyle) | undefined): void;
-    setSource(source: NeighborhoodSource): void;
-    setMode(mode: NonNullable<MapOptions['mode']>): void;
+    setSource(source: NeighborhoodSource, options?: MapViewUpdateOptions): void;
+    setMode(mode: NonNullable<MapOptions['mode']>, options?: MapViewUpdateOptions): void;
     setLabels(visible: boolean): void;
     setTouchNavigation(enabled: boolean): void;
     projectToScreen(lng: number, lat: number): {
@@ -1387,6 +1456,8 @@ export interface SFMapOptions {
     height?: number;
     padding?: number;
     year?: DistrictYear;
+    /** Select a supplied neighborhood definition when rendering source-aware MapData. */
+    source?: NeighborhoodSource;
     districtLines?: boolean;
     neighborhoodLines?: boolean;
     districtFills?: boolean;
@@ -1597,7 +1668,7 @@ export interface NeighborhoodExplorerElement extends HTMLElement {
 export interface TransitAnimationElement extends HTMLElement {
     destroy(): void;
 }
-export type { MapAppearance, MapCamera, MapCapabilities, MapConfiguration, MapConfigurationSnapshot, MapController, MapControls, MapEvents, MapOptions, MapSelectionChange, ResolvedMapConfiguration, } from './controller-types.js';
+export type { MapAppearance, MapCamera, MapCapabilities, MapConfiguration, MapConfigurationSnapshot, MapController, MapControls, MapEvents, MapFeatureReference, MapOptions, MapSelectionChange, MapViewUpdateOptions, ResolvedMapConfiguration, } from './controller-types.js';
 ```
 
 ### dist/src/explorer-data.d.ts
@@ -1724,18 +1795,21 @@ export declare function createSFMapWithData(options: SFMapOptions, data: SFMapDa
 ### dist/src/static.d.ts
 
 ```ts
+import type { InteractiveSFMapData } from './explorer-data.js';
 import { type SFMapData } from './map-core.js';
 import type { SFMapOptions } from './types.js';
+/** Either compact static geography or the same source-aware geography used by createMap. */
+export type StaticMapInput = SFMapData | InteractiveSFMapData;
 export type { DistrictRowData, SFMapData as StaticMapData } from './map-core.js';
 export type { DistrictStyle, DistrictYear, SFMapOptions as StaticMapOptions, StaticMapAppearance, StaticMapLayers, } from './types.js';
 /** Server-safe SVG rendering with explicit data; returns SVG plus projection helpers. */
-export declare function renderMap(data: SFMapData, options?: SFMapOptions): {
+export declare function renderMap(data: StaticMapInput, options?: SFMapOptions): {
     svg: string;
     project: (coordinates: import("../data/types.js").Position) => [number, number];
     viewBox: [number, number, number, number];
 };
 /** Project canonical layer geometry without constructing an SVG string. */
-export declare function getLayerPaths(data: SFMapData, options?: SFMapOptions): {
+export declare function getLayerPaths(data: StaticMapInput, options?: SFMapOptions): {
     year: import("./types.js").DistrictYear;
     viewBox: [number, number, number, number];
     project: (coordinates: import("../data/types.js").Position) => [number, number];

package/llms.txt

@@ -2,7 +2,7 @@
 
 > Offline San Francisco SVG maps with explicit geographic imports, no runtime dependencies, static rendering, and a browser controller.
 
-@kahwee/sf-map-svg 4.2.0 · local working tree. Node >=24.0.0 for server rendering; browsers need a DOM and a JSON-capable bundler.
+@kahwee/sf-map-svg 4.3.0 · local working tree. Node >=24.0.0 for server rendering; browsers need a DOM and a JSON-capable bundler.
 
 These are working-tree docs. Unreleased changelog entries may describe APIs absent from npm; verify the installed version before copying them.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kahwee/sf-map-svg",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "description": "Offline SVG maps of San Francisco with district boundaries, parks, landmarks, and BART stations.",
   "type": "module",
   "main": "./dist/src/api.js",