@kahwee/sf-map-svg 4.1.0 → 4.3.0

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.1.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.1.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.
 
-[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,14 +57,19 @@ 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 })` for runtime switches, `map.camera` for pan/zoom/fit/reset, and `map.on()` for typed events. Appearance is set at construction. SFAR realtor neighborhoods are the default when supplied; SF Find and analysis are explicit alternate sources. The `/data/full` preset includes all three collections and historical districts.
+`createMap(data, options)` returns a controller. Use `map.element` for mounting, `map.configure({ features, layers, controls, appearance, mode, source, year, labels })` for runtime switches, `map.camera` for pan/zoom/fit/reset, and `map.on()` for typed events. Appearance can change live while preserving camera, selection, and focus. `getResolvedConfiguration()` explains effective layers; `getCapabilities()` reports supplied geography. SFAR realtor neighborhoods are the default when supplied; SF Find and analysis are explicit alternate sources. The `/data/full` preset includes all three collections and historical districts.
 
 See [controller options, events, and lifecycle](https://github.com/kahwee/sf-map-svg/blob/main/docs/API.md#interactive-maps),
 [examples](https://github.com/kahwee/sf-map-svg/blob/main/docs/EXAMPLES.md), and [consumer integration](https://github.com/kahwee/sf-map-svg/blob/main/docs/consumer-integration.md).
@@ -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.1.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,13 +179,15 @@ SFAR realtor neighborhoods are the default when supplied. If only an alternative
 
 | Change | Call |
 | --- | --- |
-| Layers, controls, behaviors | `map.configure({ layers, controls, features })` |
+| 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)` |
 | Markers or route overlays | `map.setMarkers(items)`, `map.setOverlays(items)` |
 | Camera | `map.camera.set/pan/zoom/fit/reset(...)` |
-| Palette, typography, control styling | Construction-only `appearance`; recreate the map to change it |
+| 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.
 
@@ -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, selection, or construction appearance. 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
 
@@ -233,7 +231,7 @@ See [API options](https://github.com/kahwee/sf-map-svg/blob/main/docs/API.md), [
 
 ---
 
-<!-- Generated from docs/API.md; @kahwee/sf-map-svg 4.1.0 · local working tree. -->
+<!-- Generated from docs/API.md; @kahwee/sf-map-svg 4.3.0 · local working tree. -->
 
 # Map options and lifecycle
 
@@ -243,7 +241,22 @@ and event types are exported by [src/api.ts](https://github.com/kahwee/sf-map-sv
 
 ## Static maps
 
-Static options include `theme`, `width`, `height`, `padding`, `year` (2002, 2012, 2022), `districtLines`, `districtFills`, `districtStyle`, `districtLabels`, `neighborhoodLines`, `labels`, `highways`, `keyRoads`, `roadLabels`, `landmarks`, `bartStations`, `markers`, `overlays`, `title`, `idPrefix`, `colors`, and `animation`. Each optional layer is independent. User-supplied text and attributes are escaped in SVG output.
+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
+const presentation = {
+  layers: { landmarks: true, bartStations: true },
+  appearance: { theme: 'districts' as const, colors: { water: '#e7f0f3' } },
+};
+const { svg } = renderMap(staticMapData, presentation);
+const map = createMap(fullMapData, presentation);
+```
+
+Static `layers` supports every interactive layer switch except `neighborhoodLabels`. Static `appearance` supports `theme`, `colors`, and `districtStyle`; browser typography, area interaction styles, and screen-space marker sizing remain interactive settings. Unknown grouped keys are rejected. Supplied grouped keys override flat compatibility keys; omitted or `undefined` grouped keys preserve the flat value or renderer default. The two renderers retain their existing defaults. Marker arrays accept readonly inputs.
+
+Flat compatibility options include `theme`, `width`, `height`, `padding`, `year` (2002, 2012, 2022), `districtLines`, `districtFills`, `districtStyle`, `districtLabels`, `neighborhoodLines`, `labels`, `highways`, `keyRoads`, `roadLabels`, `landmarks`, `bartStations`, `markers`, `overlays`, `title`, `idPrefix`, `colors`, and `animation`. Each optional layer is independent. User-supplied text and attributes are escaped in SVG output.
 
 Custom district IDs must be finite numbers. An empty `labelPoints` array uses the district's primary `label` position.
 
@@ -269,9 +282,60 @@ Two opt-in features animate the map's lines and layers. `features.layerTransitio
 
 District style callbacks are evaluated once per district at construction and on style or year updates. Hover, selection, and layer toggles reuse the prepared styles; call `setDistrictStyle()` again when external styling data changes. Invalid styles leave the current map unchanged. District fades respect reduced motion and are removed on interruption or destruction.
 
+## 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; 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.
+
+```ts
+map.configure({
+  appearance: { colors: { water: '#142d45' }, labelStyle: { fontFamily: 'Georgia,serif' } },
+  layers: { bartStations: false },
+});
+map.configure({ appearance: undefined }); // restore construction defaults, not initial overrides
+
+const overrides = map.getConfiguration();
+const effective = map.getResolvedConfiguration();
+const available = map.getCapabilities();
+```
+
+`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
+
+`selectionchange` adds a consistent envelope without changing existing event payloads:
+
+```ts
+map.on('selectionchange', (event) => {
+  // kind narrows current and previous to the corresponding selection type.
+  if (event.kind === 'marker') console.log(event.current?.id, event.previous?.id);
+});
+```
+
+`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.
+
+Explore presentation options in the [live map design playground](https://kahwee.github.io/sf-map-svg/playground.html). The page identifies its package version; released builds use compatible options for that installed version.
+
 ---
 
-<!-- Generated from docs/EXAMPLES.md; @kahwee/sf-map-svg 4.1.0 · local working tree. -->
+<!-- Generated from docs/EXAMPLES.md; @kahwee/sf-map-svg 4.3.0 · local working tree. -->
 
 # Examples
 
@@ -382,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.1.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 map = createGuideController({
+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:
+
+```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.1.0 · local working tree. -->
+<!-- Generated from docs/migration-v3.md; @kahwee/sf-map-svg 4.3.0 · local working tree. -->
 
 # Migrate to version 3
 
@@ -451,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.1.0 · local working tree. -->
+<!-- Generated from SOURCES.md; @kahwee/sf-map-svg 4.3.0 · local working tree. -->
 
 # Geometry and provenance
 
@@ -635,12 +723,35 @@ display geometry, and no precinct polygons or raw workbook data are shipped.
 
 ---
 
-<!-- Generated from CHANGELOG.md; @kahwee/sf-map-svg 4.1.0 · local working tree. -->
+<!-- Generated from CHANGELOG.md; @kahwee/sf-map-svg 4.3.0 · local working tree. -->
 
 # Changelog
 
 User-visible changes are recorded here. Unreleased entries describe changes on `main` that are not part of a tagged package release.
 
+## 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.
+- Strengthen the playground with strict TypeScript, checked JavaScript/TypeScript snippets, versioned design links, persistent explicit layer choices and independent static rendering. Keep mobile controls unobstructed and picker labels legible in dark mode.
+- Express explicit configuration resets for consumers using `exactOptionalPropertyTypes`, including nested appearance tokens. Make Pages API and guide references describe their actual package version without internal preview warnings.
+
+- Share grouped `layers` and supported `appearance` options between static and interactive maps, retaining flat static options and existing defaults; accept readonly static marker arrays.
+- Update interactive appearance, mode, source, district year and labels through `configure`, preserving camera and retained marker nodes. Merge appearance tokens by key and validate combined patches before commit.
+- Add `getResolvedConfiguration()` and `getCapabilities()` for effective layer switches and supplied geography, plus an additive `selectionchange` event with consistent current/previous snapshots.
+- Add a live Pages map design playground with six editable palettes, layers, typography, sample pins/routes, browser/static previews, undo/redo, shareable designs, copyable code and full-city SVG export. Keep released-package previews compatible with their installed API.
+- Refresh the Pages site: a new SF Map SVG mark traced from the real coastline, a reframed header with a release link, card-style reference tables that no longer collapse, a live filter for the API reference, an aligned playground with one-row-per-colour inks, and 12px minimum type for labels and badges.
+
 ## 4.1.0 — 2026-10-01
 
 - Validate canonical and generated GeoJSON during data checks, rejecting invalid WGS84 coordinates and malformed polygon rings before release.
@@ -932,7 +1043,7 @@ consistent home, and makes animation and subscription ownership predictable.
 
 # Published type contracts
 
-@kahwee/sf-map-svg 4.1.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 |
 | --- | --- |
@@ -987,25 +1098,85 @@ export declare function createMap(data: InteractiveSFMapData, options?: MapOptio
 ```ts
 import type { Geometry, NeighborhoodSource } from '../data/types.js';
 import type { CameraOptions, DistrictSelection, DistrictStyle, DistrictYear, InteractiveLayers, MapFeatures, MapMarker, MapOverlay, MapPadding, MapViewport, NeighborhoodExplorerOptions, NeighborhoodSelection } from './types.js';
-export type MapAppearance = Pick<NeighborhoodExplorerOptions, 'theme' | 'colors' | 'labelStyle' | 'areaStyle' | 'districtStyle' | 'labelSize' | 'style' | 'markerRadius' | 'markerHitSize' | 'markerColor' | 'selectedMarkerColor'>;
+/** Patch properties can explicitly remove overrides, including with exactOptionalPropertyTypes. */
+type Resettable<T> = {
+    [K in keyof T]?: T[K] | undefined;
+};
+type AppearanceOptions = Pick<NeighborhoodExplorerOptions, 'theme' | 'colors' | 'labelStyle' | 'areaStyle' | 'districtStyle' | 'labelSize' | 'style' | 'markerRadius' | 'markerHitSize' | 'markerColor' | 'selectedMarkerColor'>;
+export type MapAppearance = {
+    [K in keyof AppearanceOptions]?: K extends 'colors' | 'style' | 'labelStyle' | 'labelSize' | 'areaStyle' ? Resettable<NonNullable<AppearanceOptions[K]>> | undefined : AppearanceOptions[K] | undefined;
+};
 export type MapControls = NonNullable<NeighborhoodExplorerOptions['controls']>;
-/** Omitted groups/keys retain their values; undefined groups reset all keys in that group. */
+/** Omitted keys retain values. Undefined presentation groups reset; undefined mode/source/year/labels retain their current value. */
 export interface MapConfiguration {
-    features?: MapFeatures;
-    layers?: InteractiveLayers;
-    controls?: MapControls;
+    features?: Resettable<MapFeatures> | undefined;
+    layers?: Resettable<InteractiveLayers> | undefined;
+    controls?: Resettable<MapControls> | undefined;
+    appearance?: MapAppearance | undefined;
+    mode?: NonNullable<NeighborhoodExplorerOptions['mode']> | undefined;
+    source?: NeighborhoodSource | undefined;
+    year?: DistrictYear | undefined;
+    labels?: boolean | undefined;
 }
 export interface MapOptions extends Omit<NeighborhoodExplorerOptions, keyof MapFeatures | keyof MapAppearance | 'interface' | 'onMarkerActivate' | 'onOverlayActivate'> {
     features?: MapFeatures;
-    appearance?: MapAppearance;
+    appearance?: MapAppearance | undefined;
 }
+/** 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;
     controls: MapControls;
+    appearance: MapAppearance;
+}
+export interface MapCapabilities {
+    sources: readonly NeighborhoodSource[];
+    years: readonly DistrictYear[];
+    /** Data availability, independent of requested layer visibility. */
+    layers: Readonly<Record<keyof InteractiveLayers, boolean>>;
+}
+export interface ResolvedMapConfiguration extends MapConfigurationSnapshot {
+    mode: NonNullable<MapOptions['mode']>;
+    source: NeighborhoodSource;
+    year: DistrictYear;
+    labels: boolean;
+    /** Effective switches after mode defaults and data availability; label switches honor labels. */
+    layers: Record<keyof InteractiveLayers, boolean>;
 }
+export type MapSelectionChange = {
+    kind: 'marker';
+    current: MapMarker | null;
+    previous: MapMarker | null;
+} | {
+    kind: 'neighborhood';
+    current: NeighborhoodSelection | null;
+    previous: NeighborhoodSelection | null;
+} | {
+    kind: 'district';
+    current: DistrictSelection | null;
+    previous: DistrictSelection | null;
+};
+/** 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;
     districtchange: DistrictSelection | {
         id: null;
         year: DistrictYear;
@@ -1042,12 +1213,18 @@ 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;
     set(view: MapViewport, options?: CameraOptions): void;
     fit(geometry: Geometry, options?: CameraOptions & {
         padding?: number | MapPadding;
     }): void;
+    /** Delta in projected map units. */
     pan(x: number, y: number, options?: CameraOptions): void;
     zoom(factor: number, options?: CameraOptions): void;
     reset(options?: CameraOptions): void;
@@ -1061,10 +1238,16 @@ export interface MapController {
     readonly destroyed: boolean;
     configure(patch: MapConfiguration): void;
     getConfiguration(): MapConfigurationSnapshot;
+    getResolvedConfiguration(): ResolvedMapConfiguration;
+    getCapabilities(): MapCapabilities;
     on<K extends keyof MapEvents>(type: K, listener: (detail: MapEvents[K]) => void): () => void;
     /** Reconcile stable IDs; retained markers preserve nodes, focus, and entrance animations. */
     setMarkers(markers: readonly MapMarker[]): void;
     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;
@@ -1079,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): {
@@ -1091,6 +1274,7 @@ export interface MapController {
     /** Idempotent; stops work and managed subscriptions. Does not remove host-owned DOM. */
     destroy(): void;
 }
+export {};
 ```
 
 ### dist/data/types.d.ts
@@ -1264,11 +1448,16 @@ export interface MapOverlay {
     label?: string;
 }
 export interface SFMapOptions {
+    /** Grouped presentation; supplied keys take precedence over flat compatibility options. */
+    layers?: StaticMapLayers;
+    appearance?: StaticMapAppearance;
     theme?: 'districts' | 'transit';
     width?: number;
     height?: number;
     padding?: number;
     year?: DistrictYear;
+    /** Select a supplied neighborhood definition when rendering source-aware MapData. */
+    source?: NeighborhoodSource;
     districtLines?: boolean;
     neighborhoodLines?: boolean;
     districtFills?: boolean;
@@ -1282,7 +1471,7 @@ export interface SFMapOptions {
     roadLabels?: boolean;
     landmarks?: boolean;
     bartStations?: boolean;
-    markers?: MapMarker[];
+    markers?: readonly MapMarker[];
     overlays?: readonly MapOverlay[];
     title?: string;
     idPrefix?: string;
@@ -1298,6 +1487,9 @@ export interface SFMapOptions {
     };
     colors?: Partial<Record<'water' | 'land' | 'district' | 'neighborhood' | 'highway' | 'road' | 'park' | 'landmark' | 'bart' | 'label' | 'marker' | 'selected', string>>;
 }
+/** Presentation supported by both the static and interactive renderers. */
+export type StaticMapLayers = Omit<InteractiveLayers, 'neighborhoodLabels'>;
+export type StaticMapAppearance = Pick<SFMapOptions, 'theme' | 'colors' | 'districtStyle'>;
 /** Serializable viewport in the interactive map's fixed 800 × 800 projected space. */
 export type MapViewport = readonly [x: number, y: number, size: number];
 export type ExplorerMode = 'neighborhoods' | 'districts' | 'basemap';
@@ -1476,7 +1668,7 @@ export interface NeighborhoodExplorerElement extends HTMLElement {
 export interface TransitAnimationElement extends HTMLElement {
     destroy(): void;
 }
-export type { MapAppearance, MapCamera, MapConfiguration, MapController, MapEvents, MapOptions, } 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
@@ -1578,6 +1770,20 @@ export declare function getLayerPathsWithData(options: SFMapOptions, data: SFMap
         point: [number, number];
     }[];
 };
+export declare function resolveMapColors(theme: SFMapOptions['theme'], colors?: SFMapOptions['colors']): {
+    water: string;
+    land: string;
+    district: string;
+    neighborhood: string;
+    highway: string;
+    road: string;
+    park: string;
+    landmark: string;
+    bart: string;
+    label: string;
+    marker: string;
+    selected: string;
+};
 /** Make an offline SVG and the matching longitude/latitude projection. */
 export declare function createSFMapWithData(options: SFMapOptions, data: SFMapData): {
     svg: string;
@@ -1589,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 } from './types.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.1.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.1.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",
@@ -175,13 +175,14 @@
     "demo": "pnpm build && node examples/build.mjs",
     "format": "biome check --write .",
     "format:check": "biome format .",
-    "check": "pnpm peers check && pnpm lint && pnpm check:docs && pnpm data:check && pnpm typecheck && pnpm typecheck:stories && pnpm test && pnpm test:bundle",
+    "check": "pnpm peers check && pnpm lint && pnpm check:docs && pnpm data:check && pnpm typecheck && pnpm typecheck:stories && pnpm typecheck:website && pnpm test && pnpm test:bundle",
     "check:docs": "pnpm build && node scripts/check-docs.mjs && node scripts/build-llm-docs.mjs --check",
     "storybook": "pnpm build && storybook dev -p 6006 --host 127.0.0.1 --no-open",
     "build-storybook": "pnpm build && storybook build",
     "data:catalog": "node scripts/build-data-catalog.mjs",
     "data:check": "node scripts/build-data-catalog.mjs --check",
     "typecheck": "pnpm build && tsc -p tsconfig.json",
+    "typecheck:website": "pnpm build && tsc -p tsconfig.website.json",
     "typecheck:stories": "tsc -p tsconfig.stories.json",
     "data:normalize-realtor": "node scripts/normalize-realtor.mjs",
     "data:guide": "node scripts/build-guide-data.mjs",